docs(06-02): complete enemy top-level implementation unit test plan

2026-09-23 16:50:19 +08:00 · 2026-09-14 09:10:05 +08:00 · 2026-09-14 09:10:05 +08:00 · bcac8a97e4
commit bcac8a97e4
parent 7b956705d3
5 changed files with 205 additions and 13 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -210,12 +210,12 @@ Plans:
  3. 测试在本地可运行且全部通过
   4. 测试由 AI 编写并运行，通过验证后可提交

-**Plans**: 1/9 plans executed (data-layer slice; non-data render/legacy coverage deferred)
+**Plans**: 2/9 plans executed (data-layer slice; non-data render/legacy coverage deferred)

 Plans:

 - [x] 06-01-PLAN.md — Combat L2 (data-system/src/combat) behavior tests + phase tracer
- [ ] 06-02-PLAN.md — Combat L3 (data-state/src/enemy) calculator/aura/special/mapDamage tests
+- [x] 06-02-PLAN.md — Combat L3 (data-state/src/enemy) calculator/aura/special/mapDamage tests
 - [ ] 06-03-PLAN.md — Enemy data model (data-base/src/enemy) tests
 - [ ] 06-04-PLAN.md — Replay (data-common/src/replay) tests + replay integration
 - [ ] 06-05-PLAN.md — Hero core (attribute/modifier/location/state) tests
@ -226,7 +226,7 @@ Plans:

 **Wave 1** *(all plans; independent new test files, no shared production edits)*

- [ ] 06-01-PLAN.md
+- [x] 06-01-PLAN.md
 - [ ] 06-02-PLAN.md
 - [ ] 06-03-PLAN.md
 - [ ] 06-04-PLAN.md
@ -248,4 +248,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. 单元测试 | 1/9 | In Progress|  |
+| 6. 单元测试 | 2/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-01-PLAN.md
-last_updated: "2026-09-14T00:53:17.655Z"
+stopped_at: Completed 06-02-PLAN.md
+last_updated: "2026-09-14T01:09:15.227Z"
 last_activity: 2026-09-14
 last_activity_desc: Phase 06 execution started
-state_head: 6c8f85a2be68d9696844ee863a8bb6787b6fde45
+state_head: 7b956705d3ecf72553561c3f124039a9100ad3be
 progress:
  total_phases: 6
  completed_phases: 0
  total_plans: 46
-  completed_plans: 38
+  completed_plans: 39
 milestone_name: milestone
 ---

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

 Phase: 06 (unit-tests) — EXECUTING
-Plan: 2 of 9
+Plan: 3 of 9
 Status: Ready to execute
 Last activity: 2026-09-14 — Phase 06 execution started

@ -77,6 +77,7 @@ Progress: [█████░░░░░] 50%
 | Phase 03 P18 | 14min | 3 tasks | 8 files |
 | Phase 03 P19 | 8min | 2 tasks | 6 files |
 | Phase 06 P01 | 9min | 3 tasks | 6 files |
+| Phase 06 P02 | 9min | 3 tasks | 6 files |

 ## Accumulated Context

@ -140,6 +141,8 @@ Recent decisions affecting current work:
 - [quick 260913-qtq]: 事件注册收口为单一 createEventRegistrations()，不做分类包装；共享工具放 event/utils.ts 且不经 index 导出。
 - [Phase 06]: 06-01：combat Layer-2 以行为单测覆盖（DamageContext/DamageSystem/MapDamage/EnemyContext/CombatFlow），三处疑似 bug 只记录不修复，按 D-05 写成 it.skip 正确预期用例并登记 06-TEST-FINDINGS.md #06-01-1..3
 - [Phase 06]: 06-01：Node 测试须同时 polyfill Map.getOrInsert 与 getOrInsertComputed（EnemyContext 使用前者）
+- [Phase 06]: 06-02：enemy 顶层实现以 6 个同目录行为单测覆盖（calculator/final/comparer/aura/special/mapDamage），fixture 全部 inline，未修改任何生产代码
+- [Phase 06]: 06-02：未发现疑似 bug，06-TEST-FINDINGS.md 无新增 #06-02-N；BetweenDamageView 方向去重语义与 plan 措辞不符但实现正确，仅记录澄清

 ### Pending Todos

@ -168,6 +171,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-09-14T00:53:17.425Z
-Stopped at: Completed 06-01-PLAN.md
+Last session: 2026-09-14T01:09:14.983Z
+Stopped at: Completed 06-02-PLAN.md
 Resume file: None
--- a/.planning/phases/06-unit-tests/06-02-SUMMARY.md
+++ b/.planning/phases/06-unit-tests/06-02-SUMMARY.md
@ -0,0 +1,179 @@
+---
+phase: 06-unit-tests
+plan: 02
+subsystem: testing
+tags: [vitest, unit-test, data-state, enemy, damage-calculator, aura, special-registry, map-damage, node]
+
+requires:
+  - phase: 06-unit-tests
+    provides: "Node Vitest harness pattern (vi.hoisted global stub + dynamic module bag + inline fakes + logger.catch) and the shared 06-TEST-FINDINGS.md sink"
+provides:
+  - "Top-level combat implementation coverage: MainDamageCalculator (all special branches), MainEnemyFinalEffect, MainEnemyComparer, CommonAura/GuardAura, registerSpecials, and the map-damage views/converter/reducer"
+  - "Reusable inline fixture shapes for data-state enemy tests (fake enemy/hero/state/context/view)"
+affects: [06-unit-tests, 06-03, 06-08]
+
+actuals:
+  tokens: 16356
+  tasks: 3
+  commits: 4
+  plan_head_before: 50d868760aab1f00544424d01b1982978d0aa344
+
+tech-stack:
+  added: []
+  patterns:
+    - "Inline per-file fake IEnemy/IReadonlyEnemy/IReadonlyHeroAttribute/IStateBase/IEnemyContext; data-layer interfaces never mocked"
+    - "vi.stubGlobal('core', { flags }) with a mutable handle returned from vi.hoisted for the BetweenDamageView core read (restored per assertion)"
+    - "Focused vitest run per task, then pnpm test:ci as the phase gate"
+
+key-files:
+  created:
+    - packages-user/data-state/src/enemy/calculator.test.ts
+    - packages-user/data-state/src/enemy/final.test.ts
+    - packages-user/data-state/src/enemy/comparer.test.ts
+    - packages-user/data-state/src/enemy/aura.test.ts
+    - packages-user/data-state/src/enemy/special.test.ts
+    - packages-user/data-state/src/enemy/mapDamage.test.ts
+  modified: []
+
+key-decisions:
+  - "06-02：enemy 顶层实现以行为单测覆盖，6 个同目录 *.test.ts 全部保持 inline fixture（D-02/D-03），未修改任何生产代码"
+  - "06-02：MainDamageCalculator 逐个特殊分支断言精确 { damage, turn }，支援路径额外验证 inGuard 不泄漏（两次顶层计算相等 + 支援怪自身 guard 不被递归）"
+  - "06-02：registerSpecials 断言代码 0-27 各注册一次且守卫默认值为空集合；仅对 6/25/1 调用 getSpecialName/getDescription，避免触发 core.values.* 全局读取"
+  - "06-02：plan 对 BetweenDamageView 的描述『两个 delta 都为正』与实现不符（实现是排除向左/向上以去重），按实现实际语义断言（右/下命中），属描述措辞而非代码缺陷，未登记 findings"
+  - "06-02：未发现疑似 bug，06-TEST-FINDINGS.md 无新增 #06-02-N 条目，无 it.skip/it.todo"
+
+requirements-completed: [TEST-01]
+
+coverage:
+  - id: D1
+    description: "MainDamageCalculator 行为覆盖：基础伤害/回合、无法破防与无敌、魔攻、连击 4/5、多段、支援递归与告警 137、先攻、破甲、反击、净化、吸血（含 add）、负伤 flag 夹取、固伤、仇恨、取整、攻击/其他属性临界上界"
+    requirement: TEST-01
+    verification:
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/calculator.test.ts#MainDamageCalculator base and defeat branches"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "MainEnemyFinalEffect 与 MainEnemyComparer 行为覆盖：坚固下限提升、模仿复制、无属性不变、优先级 0；基础属性与特殊属性数量/代码/数值深比较"
+    requirement: TEST-01
+    verification:
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/final.test.ts#MainEnemyFinalEffect"
+        status: pass
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/comparer.test.ts#MainEnemyComparer"
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "光环与特殊属性注册覆盖：CommonAura 范围选择与加成结算、GuardAura 3x3 范围与守卫定位符添加/自身跳过/缺来源跳过；registerSpecials 代码 0-27 各一次、守卫默认值、名称与描述生成"
+    requirement: TEST-01
+    verification:
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/aura.test.ts#CommonAura apply"
+        status: pass
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/special.test.ts#registerSpecials"
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "地图伤害覆盖：领域/阻击/激光/夹击/捕捉五种视图的范围参数与伤害信息、转换器按特殊属性顺序组装视图与激光朝向查找、合并器求和/最大伤害类型/额外信息并集"
+    requirement: TEST-01
+    verification:
+      - kind: unit
+        ref: "packages-user/data-state/src/enemy/mapDamage.test.ts#MainMapDamageReducer"
+        status: pass
+    human_judgment: false
+  - id: D5
+    description: "FLAGGED ASSUMPTION：TEST-01 是否由 `pnpm test:ci` 门禁下的行为单测满足，需用户确认（ROADMAP 侧无边界 verifier 解析该规格）"
+    requirement: TEST-01
+    verification: []
+    human_judgment: true
+    rationale: "计划 frontmatter 明确将该假设标为 unverified；只有用户能确认该验收口径，自动化测试无法自证需求定义。"
+
+duration: 9min
+completed: 2026-09-14
+status: complete
+---
+
+# Phase 06 Plan 02: Enemy Top-Level Implementation Unit Tests Summary
+
+**Behavior unit tests for `data-state/src/enemy` — MainDamageCalculator every special branch, final effect, comparer, aura converters, special registry 0-27, and the five map-damage views plus converter/reducer, all green under the fixed `pnpm test:ci` gate**
+
+## Performance
+
+- **Duration:** 9 min
+- **Started:** 2026-09-14T08:58:34Z
+- **Completed:** 2026-09-14T09:07:44Z
+- **Tasks:** 3
+- **Files modified:** 6 created (all `*.test.ts`), 0 production files touched
+
+## Accomplishments
+
+- `calculator.test.ts` (22 tests) proves exact `{ damage, turn }` for the baseline, the two defeat paths (no break-through / 无敌 without cross), and every special branch: 魔攻, 2/3连击, 多段, 支援 guard recursion + warn 137 + `inGuard` non-leakage, 先攻, 破甲, 反击, 净化, 吸血 (with/without `add`), 负伤 flag clamping, 固伤, 仇恨, flooring, and both `getCriticalLimit` paths (坚固 → Infinity).
+- `aura.test.ts` (13 tests) covers `CommonAuraConverter`/`GuardAuraConverter` selection, `FullRange`/`RectRange`/`ManhattanRange` choice and params, buff math, the 3×3 guard range, guard-locator registration, own-locator skip and missing-source no-op.
+- `special.test.ts` (6 tests) calls `registerSpecials` on an inline fake manager and asserts codes 0-27 registered exactly once, the `guard` empty-set default, and name/description generation for a serializable special (code 6), the halo (code 25) and a none-property special (code 1).
+- `mapDamage.test.ts` (19 tests) drives all five views (`Zone`, `Repulse`, `Laser`, `Between`, `Ambush`), the converter's per-special view order + laser face lookup, and the reducer's sum / max-damage type / catch+repulse union, including the `core.flags.betweenAttackMax` branch.
+- `final.test.ts` (5) and `comparer.test.ts` (5) cover the final-effect and comparison contracts.
+- Full suite: `pnpm test:ci` → **29 files, 223 passed, 3 skipped** (the 3 skips are the pre-existing `#06-01-N` findings). No new skips.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: MainDamageCalculator + final effect + comparer** - `5b76cf4` (test)
+2. **Task 2: Auras + special registration** - `b36a4ee` (test)
+3. **Task 3: Map damage views, converter, reducer** - `7b95670` (test)
+
+**Plan metadata:** metadata docs commit follows this SUMMARY (3 task commits + 1 metadata commit = 4 total from `plan_head_before`).
+
+## Files Created/Modified
+
+- `packages-user/data-state/src/enemy/calculator.test.ts` - MainDamageCalculator branch coverage (22 tests)
+- `packages-user/data-state/src/enemy/final.test.ts` - MainEnemyFinalEffect (5 tests)
+- `packages-user/data-state/src/enemy/comparer.test.ts` - MainEnemyComparer (5 tests)
+- `packages-user/data-state/src/enemy/aura.test.ts` - CommonAura/GuardAura + converters (13 tests)
+- `packages-user/data-state/src/enemy/special.test.ts` - registerSpecials registry (6 tests)
+- `packages-user/data-state/src/enemy/mapDamage.test.ts` - map damage views/converter/reducer (19 tests)
+
+## Decisions Made
+
+- Kept every fixture inline per file (D-03); no cross-file factory helper was introduced.
+- Extended the 06-01 harness shape (`vi.hoisted` global/`Map` polyfill stubs + `beforeAll` dynamic module bag + `logger.catch` for warn 137) and added a mutable `core` stub for the `BetweenDamageView` global read.
+- Asserted `BetweenDamageView` by its actual semantics — the right/down adjacent locator qualifies and left/up is excluded (an anti-double-count bias), rather than the plan's parenthetical "both deltas positive".
+- No suspected bugs surfaced, so `06-TEST-FINDINGS.md` gains no `#06-02-N` entry and no `it.skip`/`it.todo` was added (D-05 not triggered).
+
+## Deviations from Plan
+
+None - plan executed exactly as written, except for one documentation clarification recorded below (no code change and no test weakening).
+
+### Clarification (not a code deviation)
+
+**BetweenDamageView qualifier wording**
+- **Found during:** Task 3 (map damage views)
+- **Plan text:** "only the forward-adjacent locator (delta sum 1 and both deltas positive) qualifies".
+- **Implementation:** rejects only `deltaX <= 0 && deltaY <= 0`, so the right `(dx=1,dy=0)` and down `(dx=0,dy=1)` neighbours qualify while left/up do not. This deliberate direction bias prevents the mirrored source enemy from double-counting the same pair.
+- **Action:** Tests assert the implementation's actual (correct) semantics; no `it.skip` and no findings entry. Recorded here for reviewer awareness.
+
+## Issues Encountered
+
+- Windows/PowerShell surfaces pnpm's Browserslist age notice on stderr as a non-terminating `NativeCommandError`; it does not affect the run. Focused runs and the full `pnpm test:ci` are green.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- The `data-state/src/enemy` top-level implementation is behavior-covered and green; later plans (06-03 `data-base/src/enemy`, 06-08 `CoreState` integration) can reuse these inline fixture shapes.
+- Open input for the user: confirm the flagged TEST-01 acceptance assumption (D5 above) and triage the `#06-01-N` findings; no core code was modified in this phase.
+
+## Self-Check: PASSED
+
+- Created files verified present: the 6 `data-state/src/enemy/*.test.ts` files and `06-02-SUMMARY.md`.
+- Task commits verified in history: `5b76cf4`, `b36a4ee`, `7b95670`.
+- `git diff --name-only` from `plan_head_before` lists only the 6 new `*.test.ts` files; no production source changed.
+- Focused runs and full `pnpm test:ci` green (29 files, 223 passed, 3 documented pre-existing skips).
+
+---
+*Phase: 06-unit-tests*
+*Completed: 2026-09-14*
--- a/.planning/phases/06-unit-tests/06-TEST-FINDINGS.md
+++ b/.planning/phases/06-unit-tests/06-TEST-FINDINGS.md
@ -26,3 +26,13 @@
 | `damage.ts` `DamageContext.calculateCritical` / `findNextCritical` | 产出的临界点 `info` 与 `nextValue` 不对应 | 假计算器 `damage = 100 - atk * 10`、`getCriticalLimit = 10`、当前 `atk = 0`；首个临界点 `nextValue = 1`（正确伤害应为 90），但 `info.damage = 0`、`damageDiff = -100` | `findNextCritical` 在 `middleInfo.damage < referenceDamage` 分支只更新 `right`，从不更新 `targetInfo`，`targetInfo` 一直停留在初始 `upperLimit` 处的计算结果 | 临界点查询（数值提示、战斗模拟）展示的伤害与对应属性值不匹配 | 在 `middleInfo.damage < referenceDamage` 分支同步 `targetInfo = middleInfo`，或二分结束后按最终 `right` 重新计算一次 | `damage.test.ts` `reports the damage info matching the yielded critical value`（#06-01-1） | 中 |
 | `mapDamage.ts` `MapDamage.deleteEnemy` | 删除怪物后，该怪物产生的有来源地图伤害仍然存在 | 注册一个怪物视图并转换出伤害（假视图伤害 7）→ `getSeparatedDamage` 有 1 条 → `deleteEnemy(view)` → `getSeparatedDamage` 仍有 1 条（正确应为 0） | `viewStore` 与 `damageStore` 只在读/删路径出现，全文件没有任何 `.set(...)` 写入，因此 `deleteEnemy` / `removeEnemyAffecting` 中 `viewStore.get(viewItem)` 恒为 `undefined`，清理循环被整体跳过；`sourcedDamage` 点位与 `affectedBy` 都不会被移除 | 怪物死亡/离场后地图伤害不消失，`getSeparatedDamage` / `getReducedDamage` 继续返回幽灵伤害，并会污染后续 `refreshIndex` 的重新聚合 | 在 `refreshEnemy` / `refreshEnemyAndClearCache` 建立 sourced 伤害时同步写入 `viewStore.set(viewItem, { damages, enemy })` 与 `damageStore.set(damage, { sourceView, sourceEnemy, index })`，或改为在 `deleteEnemy` 中直接遍历 `sourcedDamage` 的 `affectedBy` 反向清理 | `mapDamage.test.ts` `removes enemy-sourced damage when the enemy is deleted`（#06-01-2） | 中 |
 | `combat.ts` `CombatFlow.combatFlow` / `ICombatScript.before` | 实现与接口文档语义相反：接口声明返回 `false` 放弃战斗，实现却在返回**真值**时短路 | 加载一个 `onBeforeCombat` 钩子，脚本 `before` 返回 `false`；`battle()` 仍会执行该钩子（正确实现应直接返回并放弃） | `const skip = await script.before(...); if (skip) return damage;` 以真值短路，与文档「返回 false 会立刻停止并放弃此次战斗」相反；文档或实现其一有误 | 所有战斗脚本的短路约定：按接口文档编写的脚本会得到相反效果，可能漏战或误战 | 先与接口设计者确认语义，再二选一统一：以 `true` 短路为准则修正接口注释，以文档为准则改为 `if (!skip) return damage;` | `combat.test.ts` `abandons the battle when the before script returns false`（#06-01-3） | 中 |
+
+## #06-02 顶层战斗实现（data-state/src/enemy）
+
+本计划未发现疑似 bug，无 `it.skip` / `it.todo`，`pnpm test:ci` 全绿（29 文件 / 223 通过 / 3 跳过）。
+
+仅有一处**计划措辞与实现不符**（非代码缺陷，不登记为 bug）：`mapDamage.ts` 的 `BetweenDamageView.getDamageWithoutCheck` 计划描述为「两个 delta 都为正才命中」，实现实际是排除 `deltaX <= 0 && deltaY <= 0`，即向右/向下相邻格命中、向左/向上不命中。该方向偏置使相邻两只怪中只有一只的视图产出伤害，从而避免同一对怪被重复计算，属实现的有意去重。测试按实现实际语义断言（`packages-user/data-state/src/enemy/mapDamage.test.ts`），无跳过用例。
+
+| 模块/接口 | 现象 | 最小复现 | 疑似原因 | 影响面 | 建议修复方向 | 关联 skip 用例 | 严重度 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| （无） | — | — | — | — | — | — | — |
--- a/.planning/state.json
+++ b/.planning/state.json
@ -31,7 +31,7 @@
    {
      "number": "6",
      "name": "单元测试",
-      "status": "pending"
+      "status": "in_progress"
    }
  ],
  "next": {
@ -39,5 +39,5 @@
    "label": "Advance to the next step",
    "reason": "Phase 06 of 6 · executing"
  },
-  "updated_at": "2026-09-14T00:53:00.361Z"
+  "updated_at": "2026-09-14T01:08:51.893Z"
 }