You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
153 lines
6.3 KiB
153 lines
6.3 KiB
3 weeks ago
|
# 遗留代码向开发规范收敛方案
|
||
|
|
|
||
|
|
> 日期：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)
|