docs(06-07): complete top-level integration plan

2026-09-22 08:10:16 +08:00 · 2026-09-14 21:11:44 +08:00 · 2026-09-14 21:11:44 +08:00 · d815ec7736
commit d815ec7736
parent 9f9dd11223
3 changed files with 190 additions and 14 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -210,7 +210,7 @@ Plans:
  3. 测试在本地可运行且全部通过
   4. 测试由 AI 编写并运行，通过验证后可提交

-**Plans**: 8/9 plans executed replanned (D-28；旧 06-01/06-02 执行结果标记 superseded，按同号重跑；数据端切片，非数据 render/legacy 覆盖延后)
+**Plans**: 9/9 plans executed replanned (D-28；旧 06-01/06-02 执行结果标记 superseded，按同号重跑；数据端切片，非数据 render/legacy 覆盖延后)

 Plans:

@ -220,7 +220,7 @@ Plans:
 - [x] 06-04-PLAN.md — Replay focus ReplayArray ops + encode/decode + system/sandbox/decorators (data-common/src/replay；无 save/load，完整播放→06-07)
 - [x] 06-05-PLAN.md — Hero ALL files incl. rendering + async mover (data-base/src/hero；无 save/load)
 - [x] 06-06-PLAN.md — Map ALL interfaces, emphasis static/dynamic tiles + static arrays (data-base/src/map；无 save/load)
- [ ] 06-07-PLAN.md — Top-level integration: damage combos + map+replay play + second-play re-record equality; error 2001–2008 (BLOCKED: pre-execution user confirmation)
+- [x] 06-07-PLAN.md — Top-level integration: damage combos + map+replay play + second-play re-record equality; error 2001–2008 (user confirmed replay recording wired)
 - [x] 06-08-PLAN.md — Flag full surface + common (utils/indexer/faceManager+face/mover) (无 save/load)
 - [x] 06-09-PLAN.md — Save/load independent system: every saveState/loadState class + CoreState top-level (BLOCKED: pre-execution user confirmation)

@ -236,8 +236,8 @@ Plans:

 **Wave 2** *(blocked on Wave 1 + user confirmation)*

- [ ] 06-07-PLAN.md — depends on 06-02/06-04/06-06; requires user to wire replay recording
- [ ] 06-09-PLAN.md — depends on 06-03/06-05/06-06/06-08; requires user to adjust CoreState saveables + add public save/load entry
+- [x] 06-07-PLAN.md — depends on 06-02/06-04/06-06; replay recording wired by user (17d7c8f), SUMMARY complete
+- [x] 06-09-PLAN.md — depends on 06-03/06-05/06-06/06-08; requires user to adjust CoreState saveables + add public save/load entry

 ## Progress

@ -251,4 +251,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 | 3. 数据端完成 | 19/19 | Complete    | 2026-09-12 |
 | 4. 渲染适配与双布局 | 0/TBD | Not started | - |
 | 5. Legacy 移植 | 0/TBD | Not started | - |
-| 6. 单元测试 | 8/9 | In Progress|  |
+| 6. 单元测试 | 9/9 | In Progress|  |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -4,16 +4,16 @@ milestone: v1.0
 current_phase: 06
 current_phase_name: unit-tests
 status: executing
-stopped_at: Completed 06-09-PLAN.md
-last_updated: "2026-09-14T10:59:52.055Z"
+stopped_at: Completed 06-07-PLAN.md
+last_updated: "2026-09-14T13:09:31.918Z"
 last_activity: 2026-09-14
 last_activity_desc: Phase 06 execution started
-state_head: 502d87ba260989fe2018a5139c5f9729d82a2275
+state_head: 9f9dd112234e814ea97b31fab87f395fa1308d9a
 progress:
  total_phases: 6
  completed_phases: 0
  total_plans: 46
-  completed_plans: 45
+  completed_plans: 46
 milestone_name: milestone
 ---

@ -29,9 +29,9 @@ See: .planning/PROJECT.md (updated 2026-09-10)
 ## Current Position

 Phase: 06 (unit-tests) — EXECUTING
-Plan: 9 of 9 (06-09 complete; 06-07 outstanding — no SUMMARY)
-Status: 06-09 save/load tests complete; D-44(c) blocked by pre-existing test:ci regression
-Last activity: 2026-09-14 — Completed 06-09-PLAN.md
+Plan: 9 of 9 (06-07 complete; all Phase 06 plans have SUMMARY)
+Status: Phase 06 data-end unit tests complete; #06-09 test:ci regression resolved by later commits, D-44(c) green
+Last activity: 2026-09-14 — Completed 06-07-PLAN.md

 Progress: [█████░░░░░] 50%

@ -86,6 +86,7 @@ Progress: [█████░░░░░] 50%
 | Phase 06 P06 | 24min | 3 tasks | 8 files |
 | Phase 06 P08 | 21min | 3 tasks | 6 files |
 | Phase 06 P09 | 42min | 3 tasks | 9 files |
+| Phase 06 P07 | 40min | 4 tasks | 4 files |

 ## Accumulated Context

@ -173,6 +174,9 @@ Recent decisions affecting current work:
 - [Phase 06]: 06-08：疑似缺陷 #06-08-1（ObjectMover.backward(count>1) 因 Special 步翻转 moveDirection 而方向摆动、净位移为零），按 D-05 以正确预期 it.skip 登记，不修改核心代码
 - [Phase 06]: 06-09：存读档独立系统按 D-43 三阶段执行，6 个测试文件 41 通过 / 6 跳过；11 个可达码 55/58/59/112/113/119/120/122/124/177/178 全部触发；CoreState 顶层经公开 saveState/loadState 对 5 saveable × 3 压缩档整体往返
 - [Phase 06]: 06-09：按 D-05 登记 5 处疑似缺陷 #06-09-1..5（EquipmentState 数值表读档错误 / HeroEquipment 存档未深拷贝 / DynamicTile 不恢复 num / ReplayArray 不恢复 length / 码 178 语义与文案相反），并以正确预期 it.skip 记录；另记录既有 test:ci 回归阻断项（commit cee8439）
+- [Phase 06]: 06-07：顶层集成按 D-43 三阶段执行，2 个测试文件 24 通过 / 1 跳过；伤害/光环组合用真实 Enemy/EnemyContext/CommonAura/GuardAura/final effect 驱动，hero 属性用内联合成对象
+- [Phase 06]: 06-07：录像播放期间用 replaySystem.disable()/revert() 抑制录制，二次录制经 ReplaySystem.saveState()/loadState()（IReplaySystemSave）最小重置；ReplayArray 不可存档已由用例断言
+- [Phase 06]: 06-07：真实 code 覆盖 176 + 2001–2008；发现 #06-07-1（CoreState 未向寻路 finder 注入 maps/layer/predicate，顶层录像瞬移恒返回 2005），按 D-05 以 it.skip 正确预期用例登记

 ### Pending Todos

@ -202,6 +206,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-09-14T10:59:39.690Z
-Stopped at: Completed 06-09-PLAN.md
+Last session: 2026-09-14T13:09:31.695Z
+Stopped at: Completed 06-07-PLAN.md
 Resume file: None
--- a/.planning/phases/06-unit-tests/06-07-SUMMARY.md
+++ b/.planning/phases/06-unit-tests/06-07-SUMMARY.md
@ -0,0 +1,172 @@
+---
+phase: 06-unit-tests
+plan: "07"
+subsystem: testing
+tags: [vitest, replay, damage-calculation, aura, integration, top-level]
+
+# Dependency graph
+requires:
+  - phase: 03-data-completion
+    provides: replay command contract (ReplayCommandCode 0-7, error 2001-2008) and first-divergence diagnostics
+  - phase: 06-unit-tests
+    provides: 06-02 enemy top-level basics, 06-04 replay array/system/sandbox, 06-05 hero subsystems, 06-06 map interfaces, 06-09 CoreState save/load
+provides:
+  - top-level damage combination coverage (multi-special + system-layer aura/effect pipelines)
+  - real small-map replay playback with second-recording exact comparison
+  - warn 176 + replay error 2001-2008 code coverage
+affects: [06-verify, milestone-v1.0]
+
+actuals:
+  tokens: 11300
+  tasks: 4
+  commits: 3
+
+tech-stack:
+  added: []
+  patterns:
+    - "real-API top-level integration tests via createCoreState (no production code changes)"
+    - "inline synthetic fixtures with real Enemy/EnemyContext/MainDamageCalculator/ReplaySystem"
+    - "replay recording suppression woven with replaySystem.disable()/revert() (nesting counter)"
+    - "bounded async waiting (waitForEnded iteration cap) with real timers only"
+
+key-files:
+  created:
+    - packages-user/data-state/test/enemyCombination.test.ts
+    - packages-user/data-state/test/replayPlayback.test.ts
+  modified:
+    - .planning/phases/06-unit-tests/06-COVERAGE-MAP.md
+    - .planning/phases/06-unit-tests/06-TEST-FINDINGS.md
+
+key-decisions:
+  - "阶段 1/2 的伤害与光环组合用真实 Enemy/EnemyContext/CommonAura/GuardAura/final effect 驱动，仅 hero 属性使用内联合成对象"
+  - "录像播放期间用 replaySystem.disable()/revert() 抑制录制，避免英雄操作回写 route 使读流过期"
+  - "二次录制用 ReplaySystem.saveState()/loadState()（IReplaySystemSave）做最小录像重置，ReplayArray 明确不再可存档"
+  - "瞬移播放需在测试内注入 finder 的 maps/layer/predicate；CoreState 缺该注入，登记为疑似缺陷 #06-07-1"
+
+patterns-established:
+  - "录像逐条比对：快照为 {code, params:[{type,value}]}，步数 + code + 各 param type/value 全等"
+  - "被跳过 / 未执行的验证都必须有 #06-07-N 锚点并登记 06-TEST-FINDINGS.md"
+
+requirements-completed: [TEST-01]
+
+coverage:
+  - id: D1
+    description: "顶层伤害组合：多特殊属性 + 系统层光环/效果组合、阶段顺序与属性→伤害联动"
+    requirement: "TEST-01"
+    verification:
+      - kind: integration
+        ref: "packages-user/data-state/test/enemyCombination.test.ts"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "真实小地图录像播放 + 重置后二次录制逐条完全相等 + 二次播放完成"
+    requirement: "TEST-01"
+    verification:
+      - kind: integration
+        ref: "packages-user/data-state/test/replayPlayback.test.ts"
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "录像记录新码 176 与执行错误 2001-2008 全覆盖触发断言"
+    requirement: "TEST-01"
+    verification:
+      - kind: unit
+        ref: "packages-user/data-state/test/replayPlayback.test.ts"
+        status: pass
+    human_judgment: false
+
+duration: 40min
+completed: 2026-09-14
+status: complete
+---
+
+# Phase [06]: [unit-tests] Plan [07] Summary
+
+**真实 API 顶层集成：顶层多特殊属性伤害组合与系统层光环/效果流水线，加上真实小地图录像完整播放、二次录制逐条完全相等，以及 176 与 error 2001–2008 全覆盖**
+
+## Performance
+
+- **Duration:** 40 min
+- **Started:** 2026-09-14T12:30:00Z
+- **Completed:** 2026-09-14T13:10:00Z
+- **Tasks:** 4 (1 前置确认门禁 + 3 阶段任务)
+- **Files modified:** 4 (2 新增测试文件 + 2 规划产物)
+
+## Accomplishments
+- `enemyCombination.test.ts`：阶段 1 真实 API 单特殊属性/单光环基线；阶段 2 顶层多特殊属性伤害组合、真实支援递归、光环基础 ↔ 常规查询、光环特殊 ↔ 特殊查询、final-effect 阶段顺序、同/跨优先级顺序、属性流水线 → 缓存伤害系统联动（`markDirty`/`deleteEnemy`/`with`）。
+- `replayPlayback.test.ts`：真实小地图场景下经真实勇士移动器录制、完整播放、重置录像（`ReplaySystem.saveState()`/`loadState()`）后二次录制并按「步数 + 每步 code + 各 param 的 type/value」逐条断言完全相等，随后二次播放完成。
+- code 覆盖：warn **176** 与 error **2001/2002/2003/2004/2005/2006/2007/2008** 各至少一条触发断言（`logger.warn`/`logger.error` spy）。
+- 澄清 D-32/录像属主：`ReplaySystem` 为可存档属主（`IReplaySystemSave`），`ReplayArray` 无 `saveState`/`loadState`（用例显式断言）。
+- 登记疑似缺陷 `#06-07-1`（顶层寻路 finder 未接线）为 `it.skip` 正确预期用例。
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: 执行前门禁 — 用户已确认录像记录接通（checkpoint, pre-cleared）** - 无代码提交（用户此前已完成 `17d7c8f` 录像记录改造）
+2. **Task 2: 阶段 1（构件级）真实 API 单分支基线** - `bdeafd5` (test)
+3. **Task 3: 阶段 2（组合/流水线）多 special + 光环/效果组合** - `edd4de3` (test)
+4. **Task 4: 阶段 3（完整/集成）小地图播放 + 二次录制比对 + 176 + 2001–2008** - `9f9dd11` (test)
+
+**Plan metadata:** 见最终 docs 提交（本 SUMMARY + STATE.md + ROADMAP.md）
+
+## Files Created/Modified
+- `packages-user/data-state/test/enemyCombination.test.ts` — 真实 Enemy/EnemyContext/计算器驱动的伤害组合与光环/效果流水线（12 通过）
+- `packages-user/data-state/test/replayPlayback.test.ts` — 录制/播放/二次录制逐条比对，176 与 2001–2008（12 通过 / 1 跳过）
+- `.planning/phases/06-unit-tests/06-COVERAGE-MAP.md` — 追加 06-07 小节与 176、2001–2008 行
+- `.planning/phases/06-unit-tests/06-TEST-FINDINGS.md` — 追加 `#06-07` 小节与 `#06-07-1`
+
+## Decisions Made
+- 阶段 1/2 伤害与光环组合沿用真实顶层实现（`Enemy`、`EnemyContext`、`CommonAura`/`GuardAura`、`MainEnemyFinalEffect`、`MainDamageCalculator`），hero 属性用内联合成对象以保证数值确定；fixture 全部内联（D-02/D-03）。
+- 录像播放期间以 `replaySystem.disable()`/`revert()` 抑制录制：真实英雄操作内部会经 `replay.route.add(...)` 回写，若不抑制会使读流过期、播放提前停止。
+- 二次录制前用 `ReplaySystem.saveState()`/`loadState()`（`IReplaySystemSave`）做最小录像重置；明确不测存读档本身（D-32），并断言 `ReplayArray` 不可存档。
+- 瞬移（2005）播放需在测试内以公开的 `finder.useMapState/useMapLayer/usePassPredicate` 注入；生产 `CoreState` 未接线，按 D-05 登记 `#06-07-1` 并加 `it.skip` 正确预期用例。
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] 测试断言误用 `toEqual` 造成 vitest 序列化 OOM**
+- **Found during:** Task 3（阶段 2 属性→伤害联动）
+- **Issue:** `DamageSystem.getDamageInfo*` 返回 `{ handler, ...info }`，其中 `handler.context`/`handler.state` 指向巨大且循环的对象图；用 `toEqual` 整对象断言失败时 vitest 打印 diff 会序列化该图，导致 heap OOM。
+- **Fix:** 改为对标量断言（`info?.damage`/`info?.turn`），避免整对象 diff。
+- **Files modified:** `packages-user/data-state/test/enemyCombination.test.ts`
+- **Verification:** 聚焦运行由 OOM 变为 12 通过。
+- **Committed in:** `edd4de3`
+
+**2. [Rule 1 - Bug] 顶层录像瞬移在真实 `CoreState` 恒返回 2005**
+- **Found during:** Task 4（阶段 3 小地图播放）
+- **Issue:** `CoreState` 构造 `PathfindingSystem` 后只 `useMover`，未向 `finder` 注入 maps/layer/predicate，`teleportTo` 告警 173 并返回 `null`，播放中的瞬移步失败使沙箱不结束。
+- **Fix:** 不改生产代码；在测试场景内以公开 `finder.useMapState/useMapLayer/usePassPredicate` 完成注入，使「真实瞬移播放」路径可测；缺口登记为 `#06-07-1`（`it.skip` 正确预期用例）。
+- **Files modified:** `packages-user/data-state/test/replayPlayback.test.ts`、`06-TEST-FINDINGS.md`
+- **Verification:** 播放用例由「沙箱不结束」变为正常结束；`#06-07-1` 用例 skip 待修复。
+- **Committed in:** `9f9dd11`
+
+---
+
+**Total deviations:** 2 auto-fixed（均为测试侧 Rule 1）
+**Impact on plan:** 未修改任何生产/核心源码；测试仅新增 2 个 `*.test.ts`。`#06-07-1` 为记录型缺口，不阻塞本计划完成。
+
+## Issues Encountered
+- `pnpm test:ci` 的既有回归（`#06-09` 阻断项，commit `cee8439`）已由后续 `2ff422a`/`c08f3f8` 修复；本次 D-44(c) 全绿（66 文件 / 629 通过 / 20 跳过）。
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- 顶层集成测试落地，Phase 6 数据端切片补齐；`#06-07-1` 待用户确认是否由 CoreState 或客户端层接线寻路 finder。
+- 16 个计划可达 code 覆盖已在 `06-COVERAGE-MAP.md` 06-07 小节登记。
+
+---
+*Phase: 06-unit-tests*
+*Completed: 2026-09-14*
+
+## Self-Check: PASSED
+
+- FOUND: packages-user/data-state/test/enemyCombination.test.ts
+- FOUND: packages-user/data-state/test/replayPlayback.test.ts
+- FOUND: .planning/phases/06-unit-tests/06-07-SUMMARY.md
+- COMMIT FOUND: bdeafd5 (stage 1)
+- COMMIT FOUND: edd4de3 (stage 2)
+- COMMIT FOUND: 9f9dd11 (stage 3 + docs)