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

> 日期：2026-08-17  
> 状态：Phase 0 完成；Phase 1 草案已产出；**Phase 2 启动链试点进行中**  
> 关联：[开发规范.md](./开发规范.md)、[项目说明.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. 为什么不建议「现在全库优化」

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

---

## 4. 分阶段收敛路线

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

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

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

产出 [`需求-模块保留.md`](./需求-模块保留.md)（**待用户确认**）：

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

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

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

详见 [`计划-试点启动链.md`](./计划-试点启动链.md)。

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

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

1. **启动链**：`GameLaunch` → `BootPipeline` → `GameController.init`（边界清晰、易测）
2. **资源门面**：`AssetService`、`BundleLifecycle`、`RuntimeLoadingGate`（与 §10、§11 直接相关）
3. **战斗门面**：`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. 下一步

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

---

## 8. 相关文档

- [开发规范.md](./开发规范.md)
- [需求-模块保留.md](./需求-模块保留.md)
- [计划-试点启动链.md](./计划-试点启动链.md)
- [项目分析报告.md](./项目分析报告.md) — 基线架构
- [项目说明.md](./项目说明.md)