6.3 KiB

Raw Permalink Blame History

遗留代码向开发规范收敛方案

日期：2026-08-17
状态：Phase 0 完成；Phase 1 草案已产出；Phase 2 启动链试点进行中
关联：开发规范.md、项目说明.md

1. 结论：能否优化？

可以，但不能一次性全库重写。

维度	说明
可行性	规范与现有代码无根本冲突；MX 分层、门面、资源管线本身已较成熟
规模	`assets` 下约 684 个 `.ts` 文件；业务脚本 507 个
风险	全库同步改注释/结构/Set 替换，极易引入回归，且大量模块可能被新产品直接删除
推荐策略	渐进收敛：新代码 100% 遵规范；触达遗留代码时局部收敛；按模块与需求排期批量清理

原则：先明确新产品 保留哪些模块，再对保留模块做规范收敛；未保留模块不投入重构成本。

2. 基线扫描（静态统计，2026-08-17）

以下为与《开发规范》明显偏离的 粗略数量（用于排期，非精确审计）：

偏离项	约略规模	说明
`new Set` / `new Map`	~70 个文件	含 MX 内核与战斗热路径；替换需逐文件验证小游戏真机
`export function` 全局函数	~120 个文件	多为 battle 工具函数、popAnim、配置解析
`??` 空值合并	~200+ 个文件	部分合理，部分属静默兜底，需人工区分
JSDoc 不完整	绝大多数遗留文件	全补注释工作量大，宜按模块推进
函数内嵌套函数 / 闭包	广泛存在	UI、动画、SDK 回调常见
对象池	`BattleOwnedWeaponPool`、`BagWeaponPool` 等	需专项审计 reset 完整性

说明：项目已有 MembershipSet（assets/mx/tools/MembershipSet.ts）作为 Set 的小游戏替代，MX 层替换 Set 应优先复用该能力，而非再发明一套。

3. 为什么不建议「现在全库优化」

新产品范围未定：老项目含引流小游戏、多渠道马甲、95 章塔防等，可能整体裁掉。
测试覆盖不足：test/ 目录尚空，大规模重构缺少自动化回归。
规范中的「禁止兜底」：全库删除 ?? 会改变大量边界行为，需策划/用例确认。
Set/Map 替换：战斗 ECS、寻路、预载调度等核心路径改动影响面大，须分模块 + 真机验证。
开发规范 已约定：遗留代码 新写与触达部分 收敛，非一次性全量。

4. 分阶段收敛路线

Phase 0 — 治理与门禁（低成本，建议立即）✅

项	动作
文档	本方案 + `开发规范.md` 已就位
Cursor 规则	`dev-standards.mdc` 已 `alwaysApply`
新代码	强制 100% 遵规范
触达遗留	PR/提交时对照 §13 自检清单
需求绑定	每个 `docs/需求-*` 注明「规范收敛范围」
审计脚本	`tools/规范审计.py`

Phase 1 — 模块保留清单（依赖产品需求）📝 草案

产出 需求-模块保留.md（待用户确认）：

保留：MX 框架、Boot、资源管线、（战斗？UI 壳？SDK？）
删除/冻结：引流小游戏、多余马甲配置、不用的 UI Tab
改造：新玩法接入点

未列入保留的目录不做规范重构。

Phase 2 — 试点模块（保留且高频）🔄 进行中

详见 计划-试点启动链.md。

项	状态
`GameLaunch.ts` 规范收敛	✅ 代码已改
`BootPipeline.ts` JSDoc	✅
`test/启动链冒烟清单.md`	✅
编辑器/真机冒烟	⏳ 待人工执行

建议优先顺序（在保留前提下）：

启动链：GameLaunch → BootPipeline → GameController.init（边界清晰、易测）
资源门面：AssetService、BundleLifecycle、RuntimeLoadingGate（与 §10、§11 直接相关）
战斗门面：BattleFacade、BattleRuntime（若新产品仍用塔防战斗）

试点内容（每模块）：

补 JSDoc（公开 API）
审计对象池 reset / 释放
将新增逻辑中的 Set 改为 MembershipSet 或数组
去掉 明确错误 的静默兜底，改为 warn + 中止

Phase 3 — 战斗 / UI 批量（工作量大）

区域	文件量级	注意
`assets/script/battle/`	~203 ts	全局函数多、Set 多、技能表现复杂
`assets/script/ui/`	~194 ts	Auto_* 生成文件慎改结构
`assets/mx/module/battle/`	核心内核	改动需跨项目影响评估

须配套：test/ 用例 + 真机清单。

Phase 4 — 全局函数 → 类方法（长期）

将 export function 逐步收入类/命名空间对象，按文件依赖从叶子节点向根收敛，避免一次改 MechanismServices 等 30+ 函数文件。

5. 触达遗留代码时的最低要求

即使不做全量重构，本次修改涉及的文件 至少做到：

新增/修改的逻辑符合 OOP，无新增全局业务函数
新增符号带 JSDoc
不新增 Set/Map（新代码）
不新增静默兜底
动画/资源/池化：生命周期完整
若改动对象池：验证 reset 与归还路径

6. 可选工程化（后续）

工具	用途	放置
自定义 ESLint 规则	禁止新 `Set`/`Map`、禁止 `export function`（warn）	`tools/`
规范审计脚本	统计 Set/??/无 JSDoc 文件列表	`tools/`
单元测试	启动、资源、战斗门面	`test/`

待 Phase 1 模块清单确认后扩展 ESLint；当前可用 python tools/规范审计.py --list。

7. 下一步

确认 需求-模块保留.md 中的保留/删除项
执行 test/启动链冒烟清单.md 验证试点
Phase 2 后续：AssetService、BundleLifecycle 同标准审计
首版 MVP 需求文档（docs/需求-*.md）

6.3 KiB Raw Permalink Blame History