diff --git a/.planning/phases/07-data-fixes/07-02-SUMMARY.md b/.planning/phases/07-data-fixes/07-02-SUMMARY.md new file mode 100644 index 0000000..c398b71 --- /dev/null +++ b/.planning/phases/07-data-fixes/07-02-SUMMARY.md @@ -0,0 +1,177 @@ +--- +phase: 07-data-fixes +plan: 02 +subsystem: enemy +tags: [enemy, reuse-mapping, prefab, createEnemy, vitest, data-base] + +# Dependency graph +requires: + - phase: 06-unit-tests + provides: 正确预期 it.skip 用例(enemy 2 条)与 06-TEST-FINDINGS.md #06-03-1 权威登记 + - phase: 07-data-fixes + plan: 01 + provides: 波次 1 的串行执行基线(D-09 逐步确认与 D-12c 全量门禁的串行约束) +provides: + - createEnemy/createEnemyById 与 getPrefab/deletePrefab/modifyPrefabAttribute 共用 internalGetPrefab 复用解析(#06-03-1) + - 源码内不变式注释:所有按 code/id 取模板的公开入口必须经 internalGetPrefab(D-11) +affects: [07-verify-work, enemy] + +actuals: + tokens: 1360 + tasks: 3 + commits: 2 + plan_head_before: 657d9720aff06da6cdc5c14c5645d1b7c52d2c14 + +tech-stack: + added: [] + patterns: + - "单一解析入口:公开创建入口与既有读写入口统一经 internalGetPrefab 解析复用映射,避免新增入口再次绕过" + +key-files: + created: [] + modified: + - packages-user/data-base/src/enemy/manager.ts + - packages-user/data-base/src/enemy/manager.test.ts + - .planning/WINDOWS.md + +key-decisions: + - "Task 0(D-09 预执行汇报)经用户确认为 approve(含注释):确认 createEnemy/createEnemyById 改用 this.internalGetPrefab,并执行可选步骤 ④ 加入中文不变式注释(D-08 / D-11)" + +patterns-established: + - "不改 internalGetPrefab/getPrefab 既有实现与返回类型:创建入口只是接入同一解析入口,未引入 as 断言、未调整方法顺序" + +requirements-completed: [FIX-01] + +coverage: + - id: D1 + description: "#06-03-1 创建入口接入复用映射:createEnemy/createEnemyById 均经 internalGetPrefab 解析" + requirement: FIX-01 + verification: + - kind: unit + ref: "packages-user/data-base/src/enemy/manager.test.ts#creates enemies for reused codes and ids through the reuse mapping" + status: pass + - kind: unit + ref: "packages-user/data-base/src/enemy/manager.test.ts#creates four independent enemies from one prefab reused by four facing codes" + status: pass + human_judgment: false + - id: D2 + description: "未注册复用映射的 code/id 行为不变(既有绿用例全绿,无回归)" + requirement: FIX-01 + verification: + - kind: unit + ref: "packages-user/data-base/src/enemy/manager.test.ts(19 passed / 0 skipped)" + status: pass + - kind: unit + ref: "pnpm test:ci(66 files passed / 656 passed / 21 skipped)" + status: pass + human_judgment: false + - id: D3 + description: "D-44 文件级门禁通过;WINDOWS.md id 24 结清" + requirement: FIX-01 + verification: + - kind: other + ref: "pnpm exec eslint --fix + pnpm exec eslint packages-user/data-base/src/enemy/{manager.ts,manager.test.ts}(0 错误)" + status: pass + - kind: other + ref: "pnpm exec vue-tsc --noEmit 按 enemy/manager 过滤(0 命中)" + status: pass + human_judgment: false + +duration: 3min +completed: 2026-09-15 +status: complete +--- + +# Phase 7 Plan 02: enemy 系统缺陷修复 Summary + +**`#06-03-1` 创建入口接入复用映射:`createEnemy`/`createEnemyById` 统一经 `internalGetPrefab` 解析,两条正确预期用例取消 skip 全绿,全量套件 656 passed / 21 skipped** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-09-15T17:14:46Z +- **Completed:** 2026-09-15T17:18Z +- **Tasks:** 3 (Task 0 为已获用户确认的 checkpoint:decision,Task 1/2 为 auto) +- **Files modified:** 3 (1 生产源码 + 1 测试 + WINDOWS.md) + +## Accomplishments + +- **#06-03-1**:`manager.ts:119-131` 的 `createEnemy(code)` 与 `createEnemyById(id)` 由直接查 `prefabByCode`/`prefabById` 改为调用既有私有 `internalGetPrefab`,与同文件的 `getPrefab`/`deletePrefab`/`modifyPrefabAttribute` 使用同一复用解析入口。`if (!prefab) return null;` 与 `return prefab.clone();` 两行保持原样;未新增 `as` 断言、未改返回类型、未调整方法顺序。 +- **不变式注释(D-11,用户确认的可选步骤 ④)**:在 `createEnemyById` 上方加入两行中文注释,说明「所有按 code/id 取模板的公开入口都必须经 `internalGetPrefab` 解析复用映射,复用映射把同一模板的多个朝向 code 别名到来源模板,绕过解析会让这些 code 取不到模板」——说明**为什么**必须走该入口,而非复述下一行调用。 +- **用例处置(D-10)**:`manager.test.ts` 仅取消 `creates enemies for reused codes and ids through the reuse mapping`(`:272`)与 `creates four independent enemies from one prefab reused by four facing codes`(`:282`)两处 `it.skip`,**断言一字未改**;同步两处 it 前的中文单行注释为修复后行为描述。未新增任何用例、未新增任何 `it.skip`。 +- **账本**:WINDOWS.md id 24(G-06-03-A)→ `fixed`(`open_count` 15→14,`fixed_count` 12→13),未新建条目、未 waive。 + +## Task Commits + +Each task was committed atomically: + +1. **Task 0: D-09 预执行汇报** - checkpoint:decision,由 orchestrator 呈现并由用户回复 **approve(含注释)**后解除;本执行者未停步(无提交,仅记录) +2. **Task 1: #06-03-1 resolve the reuse mapping in enemy creation** - `b70ccbd` (fix) +3. **Task 2: close windows ledger entry 24** - `ad0d704` (chore) + +**Plan metadata:** `docs(07-02): complete enemy data-fixes plan` (SUMMARY.md commit, see completion report) + +## Files Created/Modified + +- `packages-user/data-base/src/enemy/manager.ts` - `createEnemy`/`createEnemyById` 接入 `internalGetPrefab`;新增不变式中文注释 +- `packages-user/data-base/src/enemy/manager.test.ts` - 2 条 skip 取消(断言不变)+ 2 处中文注释同步 +- `.planning/WINDOWS.md` - id 24 → fixed(`open_count` 15→14,`fixed_count` 12→13) + +## Decisions Made + +- **Task 0(D-09 预执行汇报)**:用户回复 `approve(含注释)` —— 确认 D-08 的修法(`createEnemy`/`createEnemyById` 改用 `this.internalGetPrefab`),并选择执行可选步骤 ④(加入中文不变式注释,D-11)。本计划未在 Task 0 停步,直接进入 Task 1。 +- **注释写法**:按 dev.md「注释必须包含价值、不得解释下一行」与「禁止非 jsDoc 多行注释、多行用多个单行注释代替」的要求,写成两行单行注释,说明不变式的**理由**(复用映射承载多朝向 code)而非复述调用。 +- **提交粒度(D-13)**:源码+测试为一个 `fix` 原子提交;账本结清单独 `chore` 提交(与 07-01 的既有节奏一致)。 + +## Deviations from Plan + +**None - plan executed exactly as written.** + +- 计划称「不需要 `as`」:实测 `internalGetPrefab` 返回 `IEnemy | null`,可直接 `.clone()`,未引入任何断言。 +- 计划称调用方行为不变:`manager.test.ts` 中 `createEnemy(1)` 在 `deletePrefab(1)` 后仍返回 `null`(`:219`)、`createEnemy(99)`/`createEnemyById('missing')` 仍返回 `null`(`:205-206`)、`addPrefab` 后 `saveLoad.test.ts` 的 `createEnemy(9) === null` 均已由既有绿用例覆盖并通过。 +- **未触发 D-09「方案失败即退出并修订计划」条件**:聚焦用例、D-44 三步门禁与全量套件一次通过。 + +## Verification Results + +- **Task 1 聚焦:** `pnpm exec vitest run packages-user/data-base/src/enemy/manager.test.ts` → **1 file passed / 19 passed / 0 skipped**(修复前该文件为 19 tests 含 2 skipped) +- **D-44 文件级门禁(Task 2,对两个改动文件串行执行):** + - `pnpm exec eslint --fix <2 files>` 后 `pnpm exec eslint <2 files>` → **0 错误**(`--fix` 未产生额外改动) + - `pnpm exec vue-tsc --noEmit` 输出按 `enemy/manager` 过滤 → **0 命中**(0 类型错误);整仓退出码非零但全部为 `packages-user/client-modules/src/**` 的既有渲染端诊断(D-12 明确排除) + - `pnpm test:ci` → **66 files passed / 656 passed / 21 skipped**(07-01 结束时基线 66 files / 654 passed / 23 skipped;+2 passed、−2 skipped,与 2 条取消 skip 用例精确对应) +- **`it.skip` 审计:** `manager.test.ts` 中已无任何 `it.skip`/`it.only`;本计划未新增任何跳过(D-10)。 + +## WINDOWS.md 对照 + +| id | 缺陷 | 结果 | +|----|------|------| +| 24 | G-06-03-A:复用映射未接入 `createEnemy`/`createEnemyById`(#06-03-1) | fixed | + +`windows status` 结清后:`open_count 14` / `fixed_count 13` / `total_count 27`。本计划**未新建任何账本条目**、未执行任何 `waive`。 + +## Threat Flags + +None — 未引入新的信任边界或外部接口。`threat_model` 中 `T-7-07`(Tampering:创建入口绕过复用映射)已由 Task 1 的「统一经 `internalGetPrefab` 解析」缓解;`T-7-SC`(依赖安装)本计划无安装动作(`package.json`/`pnpm-lock.yaml` 未变更)。 + +## Known Stubs + +None — 本计划未新增 stub、未新增 `TODO`/`FIXME`、未留下占位实现。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- enemy 系统 `#06-03-1` 已修复并原子入库,2 条正确预期用例转绿;WINDOWS.md id 24 结清。 +- 剩余 Phase 7 计划(replay / hero / map / flag+common / save / path)尚未执行;本计划源码层与其他计划无耦合,但按 D-09/D-12c 仍须**串行**执行。 +- **STATE.md / ROADMAP.md 未由本执行者修改**(按 orchestrator 指示,由 orchestrator 在 wave 完成后统一写入)。 + +--- +*Phase: 07-data-fixes* +*Completed: 2026-09-15* + +## Self-Check: PASSED + +- SUMMARY.md present at `.planning/phases/07-data-fixes/07-02-SUMMARY.md` +- Commits present: b70ccbd, ad0d704 +- Modified files present: `packages-user/data-base/src/enemy/manager.ts`, `packages-user/data-base/src/enemy/manager.test.ts`, `.planning/WINDOWS.md`