docs(08-07): complete path test alignment plan

2026-10-17 11:40:16 +08:00 · 2026-10-05 18:54:54 +08:00 · 2026-10-05 18:54:54 +08:00 · 3e22e3e14a
commit 3e22e3e14a
parent ba92f5291b
3 changed files with 183 additions and 10 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -450,7 +450,7 @@ Plans:
  3. 重构遗漏的细节问题已修复（测试面或经用户确认的数据端细节），不弱化既有断言
  4. `pnpm test:perf` 仍可运行；不新增跳过用例

-**Plans**: 6/11 plans executedned（08-01..08-11；规划 2026-10-04，`gsd-plan-checker` 判 PASS / 0 blocker / 3 非阻塞 warning）——迁移 `08-01`（独立先行）→ 子系统对齐 `08-02..08-09` → 错误码与接口覆盖 `08-10` → 收口 `08-11`；每个计划 `autonomous: false`，以 blocking-human Task 0 汇报关卡开头
+**Plans**: 7/11 plans executedned（08-01..08-11；规划 2026-10-04，`gsd-plan-checker` 判 PASS / 0 blocker / 3 非阻塞 warning）——迁移 `08-01`（独立先行）→ 子系统对齐 `08-02..08-09` → 错误码与接口覆盖 `08-10` → 收口 `08-11`；每个计划 `autonomous: false`，以 blocking-human Task 0 汇报关卡开头

 Plans:

@ -460,7 +460,7 @@ Plans:
 - [x] 08-04-PLAN.md — data-base hero 对齐（录像桩 `array`、删 `.load()`、真实 `TileStore`/`ItemStore(tileStore)`、`setFloor(IGameMap|null)`、`getItem`→`addItem`；含经确认的 `equipment.loadState` 读档禁录修复）
 - [x] 08-05-PLAN.md — data-base map 对齐（`addLayer(alias)`、`MapState(state)`；陈旧码 62/63/64/84/130/125 裁决；含 D-10 生产修复，map 聚焦 108/108 通过）
 - [x] 08-06-PLAN.md — data-system combat+event 对齐（`CombatFlow` 构造、`.load()` 移除、DEV 守卫码）
- [ ] 08-07-PLAN.md — data-system path 对齐（`useMapState` 删除、`useFaceHandler` 注入）
+- [x] 08-07-PLAN.md — data-system path 对齐（`useMapState` 删除、`useFaceHandler` 注入）
 - [ ] 08-08-PLAN.md — data-state src 对齐（`createCoreState` 删除→`CoreState({loadStarter,coreURL})`；`coreEventLayer` A1/A2）
 - [ ] 08-09-PLAN.md — data-state 集成对齐（共享夹具 `closed-loop.ts`、`tileLegacy` 去留、寻路注入）
 - [ ] 08-10-PLAN.md — 错误码 21 缺口 + loader 公共接口覆盖盘点与补测
@ -483,4 +483,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8
 | 5. Legacy 移植 | 0/TBD | Not started | - |
 | 6. 单元测试 | 18/18 | In Progress|  |
 | 7. 数据端缺陷修复 | 15/16 | Complete（07-16 superseded） | - |
-| 8. 测试重构与接口对齐 | 6/11 | In Progress|  |
+| 8. 测试重构与接口对齐 | 7/11 | In Progress|  |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -4,16 +4,16 @@ milestone: v1.0
 current_phase: 08
 current_phase_name: 测试重构与接口对齐
 status: executing
-stopped_at: Completed 08-06-PLAN.md（combat 4 test + 2 perf 与 event 1 文件对齐 shipped 接口：删 addHook(...).load() 链、CombatFlow/EnemyContext/MapState 单参构造、删 DirectionMapper、事件层改 GameMap.eventLayer；聚焦 96/96 通过、perf 6/6、eslint 0；零生产改动）
-last_updated: "2026-10-05T09:30:06.601Z"
+stopped_at: Completed 08-07-PLAN.md（path 3 测试文件对齐 shipped 注入面 + 用户授权 B1/B2 生产修复与 F5 断言 183：聚焦 28/28、eslint 0）
+last_updated: "2026-10-05T10:54:20.389Z"
 last_activity: 2026-10-05
 last_activity_desc: Phase 08 execution started
-state_head: e024e2d2ea2ce610d6ca2e79236c074b9985fadb
+state_head: ba92f5291b19f3c6e3a55c52da76dceaf9d2b910
 progress:
  total_phases: 8
  completed_phases: 0
  total_plans: 98
-  completed_plans: 92
+  completed_plans: 93
 milestone_name: milestone
 ---

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

 Phase: 08 (测试重构与接口对齐) — EXECUTING
-Plan: 2 of 11
+Plan: 3 of 11
 Status: Ready to execute
 Last activity: 2026-10-05 — Phase 08 execution started

@ -102,6 +102,7 @@ Progress: [█████░░░░░] 50%
 | Phase 04 P4 | ~45min | 4 tasks | 3 files |
 | Phase 04 P7 | 35min | 3 tasks | 10 files |
 | Phase 08 P06 | 10min | 2 tasks | 3 files |
+| Phase 08 P07 | 40min | 2 tasks | 4 files |

 ## Accumulated Context

@ -236,6 +237,10 @@ Recent decisions affecting current work:
 - [Phase 08]: [Phase 08] 08-06 Q1：combat 测试沿用各文件既有 {} as IStateBase 最小桩装配 CombatFlow/EnemyContext 单参构造，不新建 Phase 6 风格夹具
 - [Phase 08]: [Phase 08] 08-06 Q2：eventDispatch 删除已废弃 DirectionMapper 注入与 import/module 条目、MapState 改单参 commonState；getLayerByAlias 已删故事件层改用 GameMap.eventLayer
 - [Phase 08]: [Phase 08] 08-06 Q3（用户授权偏离计划 must_haves）：不触发/不补测 DEV 守卫码 98/99/101、忽略无 emit 点错误码；保持 Vitest 默认 mode=test，不改配置；记录于 08-06-SUMMARY Deviations
+- [Phase 08]: [Phase 08] 08-07 Q1–Q3：path 注入面对齐——默认注入 Dir4FaceHandler、useMapState 在 builder/finder 两处删除、performance 规模参数与阈值逐字不变
+- [Phase 08]: [Phase 08] 08-07 B1（用户授权 D-10）：graph.build 补 mapped.add(startIndex)，修复单向门/死路起点漏出图导致 finder 恒返 NoPath
+- [Phase 08]: [Phase 08] 08-07 B2（用户授权 D-10）：resolveCost 恢复 174 守卫——NaN/负数告警并回退 1，Infinity 仍是合法损失
+- [Phase 08]: [Phase 08] 08-07 F5（用户授权）：越界起点用例注入谓词与处理器，走真实越界分支断言 183

 ### Roadmap Evolution

@ -275,6 +280,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-10-05T09:30:06.319Z
-Stopped at: Completed 08-06-PLAN.md（combat 4 test + 2 perf 与 event 1 文件对齐 shipped 接口：删 addHook(...).load() 链、CombatFlow/EnemyContext/MapState 单参构造、删 DirectionMapper、事件层改 GameMap.eventLayer；聚焦 96/96 通过、perf 6/6、eslint 0；零生产改动）
+Last session: 2026-10-05T10:54:20.093Z
+Stopped at: Completed 08-07-PLAN.md（path 3 测试文件对齐 shipped 注入面 + 用户授权 B1/B2 生产修复与 F5 断言 183：聚焦 28/28、eslint 0）
 Resume file: None
--- a/.planning/phases/08-test-refactor-alignment/08-07-SUMMARY.md
+++ b/.planning/phases/08-test-refactor-alignment/08-07-SUMMARY.md
@ -0,0 +1,168 @@
+---
+phase: 08-test-refactor-alignment
+plan: 07
+subsystem: data-system/path
+tags: [test-alignment, pathfinding, vitest, authorized-production-fix, D-10]
+status: complete
+requires:
+  - phase: 08-test-refactor-alignment/08-01
+    provides: 测试文件迁入 __test__ 目录的基线
+provides:
+  - "data-system 的 path 子系统 3 个声明测试文件对齐 shipped 注入面（useMapLayer / useFaceHandler / IPathfindingResult），聚焦 28/28 通过、eslint 0"
+  - "经用户授权的两处最小生产修复（D-10）：起始节点登记进图（B1）与 174 NaN/负数损失守卫（B2）"
+affects:
+  - packages-user/data-system/src/path
+tech-stack:
+  added: []
+  patterns:
+    - "已删 useMapState 仅删除，图宽度由 useMapLayer(layer) 内的 indexer.setWidth(layer.width) 承担"
+    - "useFaceHandler 注入真实处理器对象（Dir4FaceHandler / Dir8FaceHandler），不再传数字方向组"
+    - "find() / getPath() 返回 IPathfindingResult（status + path），断言改为 status 与 path"
+key-files:
+  created: []
+  modified:
+    - packages-user/data-system/src/path/graph.ts
+    - packages-user/data-system/src/path/__test__/graph.test.ts
+    - packages-user/data-system/src/path/__test__/system.test.ts
+    - packages-user/data-system/src/path/__test__/performance.test.ts
+decisions:
+  - "Q1：默认注入 Dir4FaceHandler（延续旧默认 InternalDirectionGroup.Dir4 意图）；显式八方向用例注入 Dir8FaceHandler 对象"
+  - "Q2：useMapState 在 builder 与 finder 两处删除，宽度由 useMapLayer 承担；遗留 maps 局部变量按 lint 处理"
+  - "Q3：performance.test.ts 仅改注入面，规模参数与断言阈值逐字不变"
+  - "B1=（a）：授权最小生产修复，build() 中起始节点 mapped.add(startIndex)（D-10）"
+  - "B2=（a）：授权在 resolveCost 恢复 174 守卫，NaN/负数告警并回退为 1；Infinity 仍是合法损失"
+  - "F5=（a）：越界起点用例注入谓词与方向处理器，走真实越界分支并断言 183（而非 173）"
+requirements-completed: [TEST-02]
+actuals:
+  tokens: 5910
+  tasks: 2
+  commits: 3
+  plan_head_before: 4208857eff7a8501b2863875a9d18078a6dccb42
+coverage:
+  - id: D1
+    description: "path 3 个测试文件对齐 shipped 注入面，聚焦 0 失败"
+    requirement: TEST-02
+    verification:
+      - kind: unit
+        ref: "pnpm exec vitest run packages-user/data-system/src/path/__test__ — 3 files / 28 passed / 0 failed"
+        status: pass
+      - kind: lint
+        ref: "pnpm exec eslint packages-user/data-system/src/path/__test__ packages-user/data-system/src/path/graph.ts — 0 errors"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "B1 起始节点建图 + B2 174 守卫恢复，经既有用例验证"
+    requirement: TEST-02
+    verification:
+      - kind: unit
+        ref: "graph.test.ts 单向门用例断言 source 节点存在；graph/system.test.ts 的 NaN 与负数用例断言 174 告警并回退单位损失"
+        status: pass
+    human_judgment: false
+duration: 40min
+completed: 2026-10-05
+---
+
+# 08-07 — path 测试对齐 Summary
+
+**一句话：** 将 `packages-user/data-system` 的 `path` 子系统 3 个声明测试文件对齐 shipped 寻路注入面——删除废弃的 `useMapState`/`DirectionMapper`、`useFaceHandler` 注入真实处理器对象、`find()/getPath()` 断言改为 `IPathfindingResult`（status+path）——并落地经用户授权的两处最小生产修复（B1 起始节点建图、B2 174 损失守卫）；聚焦 **28/28 通过**、eslint **0 报错**。
+
+## Task 0 裁决（Q1–Q3，已 RESOLVED）
+
+- **Q1**：默认注入 `Dir4FaceHandler`（延续旧 builder 默认 `InternalDirectionGroup.Dir4` 的意图）；显式八方向用例改用 `Dir8FaceHandler` 对象确认。
+- **Q2**：`useMapState` 在 builder 与 finder 两处均删除；图宽度由 `useMapLayer(layer)` 内的 `indexer.setWidth(layer.width)` 承担；删除后不再使用的 `maps` 局部变量按 lint 处理。
+- **Q3**：`performance.test.ts` 仅改注入面，性能矩阵规模参数与断言阈值逐字不变。
+
+## 第二轮裁决（生产漂移 B1/B2/F5，已 RESOLVED）
+
+- **B1 = (a)**：授权在 `packages-user/data-system/src/path/graph.ts` 的 `build()` 中，于 `adjacency.set(startIndex, [])` 之后补 `mapped.add(startIndex)`——重构遗漏了起始节点登记，导致单向门/死路起点下 `finder.ts:144` 的 `graph.nodes.has(startIndex)` 恒假、返回 NoPath。属 **D-10 已确认的最小生产修复**。
+- **B2 = (a)**：授权在 `resolveCost` 恢复 174 守卫——以 `this.cost(block)` 求值（无损失函数时默认 1），结果为 `NaN` 或负数时 `logger.warn(174)` 并回退为 1，否则原样返回；`Infinity` 仍是合法损失。用户明确接受该（可忽略的）求值开销。
+- **F5 = (a)**：越界起点用例注入通行谓词（+ 已默认注入的 `Dir4FaceHandler`），使其越过 173 早退、抵达真实越界分支并断言守卫码 **183**；缺失绑定类 173 覆盖由其邻居用例保留。
+
+## 注入面对齐改动（F 族，3 个测试文件）
+
+- **F1** 删除 `useMapState`：`graph.test.ts` 的 `builder.useMapState(maps)`、`system.test.ts` / `performance.test.ts` 的 `finder.useMapState(maps)` 与内联 builder 的 `useMapState` 全部删除；不再使用的 `maps` 局部变量按 lint 处理。
+- **F2** 删除 `DirectionMapper`：`graph.test.ts` 的 import、`TestModules` 条目与所有 `new modules.DirectionMapper()` 使用删除；不再用其四正交组推导期望方向数。
+- **F3** `useDirGroup(<数字>)` → `useFaceHandler(<处理器对象>)`：三个夹具默认注入 `new Dir4FaceHandler()`（对应旧默认意图）。
+- **F4** 显式八方向用例注入 `new Dir8FaceHandler()` 对象（替代旧 `InternalDirectionGroup.Dir8` 数字）。
+- **F5** 越界起点用例改走真实 183 分支并断言 183（见上，本轮完成）。
+- **F6** `find()/getPath()` 形状对齐：断言由直接返回 `IPathfindingStep[]` 改为 `IPathfindingResult` 的 `status`（`Success`/`NoPath`/`InvalidInput`）与 `path`；`performance.test.ts` 的步数统计改用 `find.value.path.length`。
+
+另随 shipped 接口对齐：`MapState` 单参构造、`map.eventLayer` 替代已删的 `getLayerByAlias`，均为既有重构后的正确形状。
+
+## 门禁证据
+
+- **聚焦运行**：`pnpm exec vitest run packages-user/data-system/src/path/__test__` → **Test Files 3 passed（3）；Tests 28 passed（28）**（0 failed）。
+- **eslint**：`pnpm exec eslint packages-user/data-system/src/path/__test__ packages-user/data-system/src/path/graph.ts` → **0 报错**（首轮暴露的 prettier 折叠问题已在 Task 2 修净）。
+- **生产改动范围**：仅 `packages-user/data-system/src/path/graph.ts` 的两处授权点（B1、B2）；`path/**` 下其余生产文件零改动。
+- **skip 计数**：未新增/未删除任何 `it`，`path` 测试内无 `.skip`/`.todo`；仓库级 skipped 仍为 1（`data-base/src/hero/equipment.test.ts` 码 147）。
+
+## 并发保护（D-08）
+
+未触碰、未暂存、未提交任何用户并发改动（`packages-user/client-*`、`packages/system/src/ui/*`、`packages-user/client-modules/src/ui/` 等）。每个任务仅以显式路径 `git add` 声明文件；从未使用 `git add -A`/`git add .`。
+
+## Deviations from Plan
+
+### 1. [用户授权 · D-10] 生产修复 B1：起始节点登记进图
+
+- **Found during:** Task 1（graph 对齐）。
+- **Issue:** 计划 must_haves 明写「零生产改动」，但「单向门方向性」用例在对齐注入面后仍失败——`graph.nodes.get(0)` 为 `undefined`。根因是重构后的 `build()` 只把起始位置写入 `adjacency` 而未写入 `mapped`，节点集遍历 `mapped` 时把起始节点漏出图；对单向门/死路起点，`finder.search` 因 `!graph.nodes.has(startIndex)` 恒返回 NoPath。
+- **Fix（用户裁决 B1=(a)）:** 在 `adjacency.set(startIndex, [])` 之后补 `mapped.add(startIndex);`。
+- **Files modified:** `packages-user/data-system/src/path/graph.ts`
+- **Committed in:** `b62b394`（Task 1）。
+
+### 2. [用户授权 · D-10] 生产修复 B2：恢复 174 损失守卫
+
+- **Found during:** Task 1（graph/system 对齐）。
+- **Issue:** 计划 must_haves 明写「零生产改动」，但图/系统的 NaN 与负数损失用例在注入面修好后仍失败——`resolveCost` 直接返回 `this.cost(block)`，`NaN` 无告警、负数不夹取，与用例期望（告警 174 并回退 1）不符；该守卫在早期 `finder.getNodeCost` 中存在，重构时丢失。
+- **Fix（用户裁决 B2=(a)）:** `resolveCost` 以 `this.cost ? this.cost(block) : 1` 求值，`Number.isNaN(cost) || cost < 0` 时 `logger.warn(174)` 并返回 1，否则返回 cost（`Infinity` 合法保留）。
+- **Files modified:** `packages-user/data-system/src/path/graph.ts`
+- **Committed in:** `b62b394`（Task 1）。
+
+### 3. [用户授权] 越界起点用例断言 183（F5）
+
+- **Found during:** Task 1（graph 对齐收尾）。
+- **Issue:** 未注入谓词时 `build()` 在 `!predicate` 处提前 `warn(173)`，越界起点用例实际测的是缺失绑定而非真实越界分支。
+- **Fix（用户裁决 F5=(a)）:** 用例注入 `FixturePredicate` 后 `build({ x: 3, y: 0 })`，命中 `!layer.inMap(...)` 分支并断言 **183**；173 覆盖由「缺谓词」「缺图层」两个邻居用例保留。
+- **Files modified:** `packages-user/data-system/src/path/__test__/graph.test.ts`
+- **Committed in:** `b62b394`（Task 1）。
+
+### 4. [Rule 3 - Formatting] prettier 折叠修正
+
+- **Found during:** Task 2（提交前 eslint 门禁）。
+- **Issue:** 既有对齐改动留下两处 prettier 折叠违例（`{ builder }` 版应单行、`{ map, builder }` 版应多行）。
+- **Fix:** 按 prettier 期望折叠，纯格式、无语义变化。
+- **Files modified:** `packages-user/data-system/src/path/__test__/graph.test.ts`
+- **Committed in:** `ba92f52`（Task 2）。
+
+---
+
+**Total deviations:** 3 用户授权（B1/B2 两处 D-10 生产修复 + F5 断言改 183） + 1 自动格式修复（prettier）。
+**Impact on plan:** 生产改动严格限于 `graph.ts` 两处授权点；测试改动限于 3 个声明文件；未弱化断言、未删用例、零新增依赖。
+
+## Issues Encountered
+
+- 计划对 B1/B2 两处生产漂移未在 Task 0 预见，执行期由用户二次裁决授权后落地；已在 Deviations 逐条登记提交锚点。
+
+## Known Stubs
+
+None。
+
+## Threat Flags
+
+None——未引入新的网络/鉴权/文件访问/信任边界表面；`T-08-07-01..04/SC` 缓解均满足（性能参数与阈值未动、注入真实处理器对象而非数字/`as never` 伪造、未删用例或新增 skip、未提交用户并发改动、未安装任何包）。B1/B2 为图构建正确性修复，不在信任边界上新增暴露面。
+
+## Next Phase Readiness
+
+- `path` 子系统对齐完成（28/28），为 data-state 集成层（08-09 的 `replayPlayback` 等）复用同一注入面与 `IPathfindingResult` 契约铺路。
+- 无阻塞；后续计划可继续对齐 `data-system/src` 其余 `__test__` 子系统。
+
+---
+
+*Phase: 08-test-refactor-alignment*
+*Completed: 2026-10-05*
+
+## Self-Check: PASSED
+
+- FOUND: .planning/phases/08-test-refactor-alignment/08-07-SUMMARY.md
+- FOUND: b62b394 (Task 1)
+- FOUND: ba92f52 (Task 2)