From 78b029544bd1c64b73db054b494fe9ac79bcc05e Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Thu, 10 Sep 2026 09:42:29 +0800 Subject: [PATCH] docs(02-04): complete pathfinding contract gap closure plan --- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 18 +- .planning/WINDOWS.md | 19 +- .../phases/02-pathfinding/02-04-SUMMARY.md | 203 ++++++++++++++++++ 4 files changed, 234 insertions(+), 14 deletions(-) create mode 100644 .planning/phases/02-pathfinding/02-04-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 54c1e92..980b4b9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -80,7 +80,7 @@ Plans: 2. 移动端点击地图上的可达格时，角色自动寻路移动到该格 3. 寻路正确避开不可通行格（碰撞/障碍/墙体） -**Plans**: 3/5 plans executed +**Plans**: 4/5 plans executed **UI hint**: yes Plans: @@ -88,7 +88,7 @@ Plans: - [x] 02-02-PLAN.md — L0 坐标回写缺陷修复 + L2 寻路核心（有向图 + 最小损失 + 仅取路径 + 回退策略槽位） - [x] 02-03-PLAN.md — L3 接线（逐步/瞬移/回退默认策略/D-08 双语义/打断接管）+ barrel/logger 装配 + 阶段门禁 -- [ ] 02-04-PLAN.md — 恢复用户授权的 path/types.ts 契约并收口 moverImpl TS18047 +- [x] 02-04-PLAN.md — 恢复用户授权的 path/types.ts 契约并收口 moverImpl TS18047 - [ ] 02-05-PLAN.md — 稳定全量 Vitest 门禁并提供非 watch 测试命令 **Wave 1** @@ -105,7 +105,7 @@ Plans: ### Wave 4 *(gap closure; blocked on Wave 3 completion)* -- [ ] 02-04-PLAN.md — 用户契约范围与阶段类型错误收口 +- [x] 02-04-PLAN.md — 用户契约范围与阶段类型错误收口 - [ ] 02-05-PLAN.md — 全套件超时与跳过测试门禁收口 ### Phase 3: 数据端完成 @@ -173,7 +173,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| | 1. 事件系统 | 13/13 | In Progress| | -| 2. 寻路系统 | 3/3 | In Progress| | +| 2. 寻路系统 | 4/5 | In Progress| | | 3. 数据端完成 | 0/TBD | Not started | - | | 4. 渲染适配与双布局 | 0/TBD | Not started | - | | 5. Legacy 移植 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index b8af2f6..6992c6e 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,16 +4,16 @@ milestone: v1.0 current_phase: 02 current_phase_name: 寻路系统 status: verifying -stopped_at: Completed 02-03-PLAN.md -last_updated: "2026-09-09T13:26:49.286Z" +stopped_at: Completed 02-04-PLAN.md +last_updated: "2026-09-10T01:41:42.684Z" last_activity: 2026-09-09 last_activity_desc: Phase 02 execution started -state_head: 7a3b6e35c1dfce17e605ba870a023524acba8eec +state_head: 93453db41702d3d14d2cc69c992bfb92fee48eee progress: total_phases: 6 completed_phases: 0 - total_plans: 16 - completed_plans: 16 + total_plans: 18 + completed_plans: 17 milestone_name: milestone --- @@ -72,6 +72,7 @@ Progress: [█████████░] 92% | Phase 02 P01 | 25min | 3 tasks | 2 files | | Phase 02 P02 | 29min | 3 tasks | 10 files | | Phase 02 P03 | 30 min | 4 tasks | 9 files | +| Phase 02 P04 | 10 min | 2 tasks | 7 files | ## Accumulated Context @@ -114,6 +115,9 @@ Recent decisions affecting current work: - [Phase 02]: L3 HeroPathfinding 注入 DefaultHeroMoveTopImpl 的 IPassPredicate，L2 图搜索与 hero mover 共享同一通行性语义。 - [Phase 02]: D-08 no-pass 目标采用可达相邻格 + 面朝目标 + source-aware OnTouch 直派；无相邻可达格返回空路径。 - [Phase 02]: 同步寻路接口通过 queued controller 实现 stop 后 await，再从最新坐标重算并启动新路径。 +- [Phase 02]: D-07 remains authoritative: path/types.ts matches the user baseline except for the two authorized nullable returns; graph helper contracts stay implementation-owned. +- [Phase 02]: The concrete useMover bridge remains in PathfindingSystem so HeroPathfinding can bind IObjectMover without expanding the user-authored interface. +- [Phase 02]: D-11 remains intact: this plan modifies no client click adapter or Phase 1 file. ### Pending Todos @@ -136,6 +140,6 @@ None yet. ## Session Continuity -Last session: 2026-09-09T13:26:49.198Z -Stopped at: Completed 02-03-PLAN.md +Last session: 2026-09-10T01:41:42.588Z +Stopped at: Completed 02-04-PLAN.md Resume file: None diff --git a/.planning/WINDOWS.md b/.planning/WINDOWS.md index b9a178d..7f16795 100644 --- a/.planning/WINDOWS.md +++ b/.planning/WINDOWS.md @@ -1,10 +1,10 @@ --- schema_version: 1 -open_count: 3 +open_count: 4 waived_count: 0 fixed_count: 2 -total_count: 5 -last_updated: 2026-09-09T13:24:24.755Z +total_count: 6 +last_updated: 2026-09-10T01:38:48.570Z --- # Broken Windows Ledger @@ -20,6 +20,7 @@ last_updated: 2026-09-09T13:24:24.755Z | 3 | 01 | deviation | packages-user/data-base/src/map/mapLayer.ts | | Replaced unsupported Map upsert runtime calls so the raw map event path runs under Node Vitest. | open | | 2026-09-08T15:54:23.173Z | | | 4 | 02 | skipped-test | packages-user/data-common/src/common/mover.test.ts | | 4 个 it.skip 坐标回写回归用例（x/y 正交、斜向、传送），待 02-02 修复 mover.ts:651 后翻绿 | fixed | | 2026-09-09T07:51:25.555Z | 2026-09-09T09:34:39.843Z | | 5 | 02 | stub | packages-user/data-system/src/path/system.ts | 254 | interrupt() is an intentional placeholder that only stops the in-flight move; takeover sequencing (stop-then-await per approved option 1) is implemented by 02-03 Task 4 | fixed | | 2026-09-09T09:34:59.707Z | 2026-09-09T13:24:24.755Z | +| 6 | 02 | stub | packages-user/data-state/src/hero/moverImpl.ts | 284 | Existing cannotEnter() is intentionally empty because no event trigger corresponds to movement blocked by an impassable mask; D-08 direct OnTouch dispatch handles allowed adjacent no-pass targets. | open | | 2026-09-10T01:38:48.570Z | | ````json [ @@ -82,6 +83,18 @@ last_updated: 2026-09-09T13:24:24.755Z "reason": "", "recorded_at": "2026-09-09T09:34:59.707Z", "resolved_at": "2026-09-09T13:24:24.755Z" + }, + { + "id": 6, + "kind": "stub", + "phase": "02", + "file": "packages-user/data-state/src/hero/moverImpl.ts", + "line": 284, + "description": "Existing cannotEnter() is intentionally empty because no event trigger corresponds to movement blocked by an impassable mask; D-08 direct OnTouch dispatch handles allowed adjacent no-pass targets.", + "status": "open", + "reason": "", + "recorded_at": "2026-09-10T01:38:48.570Z", + "resolved_at": null } ] ```` diff --git a/.planning/phases/02-pathfinding/02-04-SUMMARY.md b/.planning/phases/02-pathfinding/02-04-SUMMARY.md new file mode 100644 index 0000000..5a8f1a8 --- /dev/null +++ b/.planning/phases/02-pathfinding/02-04-SUMMARY.md @@ -0,0 +1,203 @@ +--- +phase: 02-pathfinding +plan: 04 +subsystem: pathfinding +tags: [pathfinding, public-contract, graph, nullable-types, event-sources] + +# Dependency graph +requires: + - phase: 02-pathfinding (plan 03) + provides: L3 hero pathfinding integration, shared pass predicate, and source-aware movement events +provides: + - User-owned path contract restored to commit 7a011b2 plus only the two authorized nullable returns + - Implementation-only graph contracts exported from graph.ts while L2 pathfinding behavior remains intact + - Nullable-safe static event collection with dynamic event collection and ordering preserved +affects: [02-05, phase-04-rendering, PATH-01] + +# Actuals (#2632) +actuals: + tokens: 2820 + tasks: 2 + commits: 2 +plan_head_before: 3809b40b41d919b3ecfa69765ca9f31073237ac9 + +# Tech tracking +tech-stack: + added: [] + patterns: + - "User-owned public contracts remain baseline-faithful; implementation-only graph types stay beside graph construction" + - "Nullable static map data is narrowed before tile-event access while dynamic sources continue through the same sorted executor path" + +key-files: + created: [] + modified: + - packages-user/data-system/src/path/types.ts + - packages-user/data-system/src/path/graph.ts + - packages-user/data-system/src/path/finder.ts + - packages-user/data-system/src/path/system.ts + - packages-user/data-state/src/hero/moverImpl.ts + - packages-user/data-state/src/path/heroPathfinding.ts + - .planning/phases/02-pathfinding/deferred-items.md + +key-decisions: + - "D-07 remains authoritative: path/types.ts matches the user baseline except for moveTo and teleportTo nullable returns." + - "The concrete useMover bridge remains implementation-owned so HeroPathfinding can bind IObjectMover without expanding the user contract." + - "D-11 remains intact: no client click adapter or Phase 1 file was modified." + +patterns-established: + - "Graph helper interfaces are exported from graph.ts rather than the user-owned contract file." + - "Static event sources are collected only after a non-null guard; dynamic sources retain their existing priority and executor semantics." + +requirements-completed: [PATH-01] + +coverage: + - id: D1 + description: "Restored path/types.ts to the authorized user contract with only nullable moveTo/teleportTo return corrections." + requirement: PATH-01 + verification: + - kind: other + ref: "normalized git comparison against 7a011b2 path/types.ts" + status: pass + - kind: integration + ref: "pnpm exec vitest run packages-user/data-system/src/path packages-user/data-state/src/path/heroPathfinding.test.ts (35 passed)" + status: pass + human_judgment: false + - id: D2 + description: "Kept graph/search/hero pathfinding behavior reachable after moving graph helper contracts out of types.ts." + requirement: PATH-01 + verification: + - kind: unit + ref: "packages-user/data-system/src/path (28 path tests plus performance tests passed)" + status: pass + - kind: integration + ref: "packages-user/data-state/src/path/heroPathfinding.test.ts (7 passed)" + status: pass + human_judgment: false + - id: D3 + description: "Closed the moverImpl nullable static diagnostic without changing dynamic event collection or core event behavior." + requirement: PATH-01 + verification: + - kind: other + ref: "pnpm check:type output contains no moverImpl.ts diagnostic" + status: pass + - kind: unit + ref: "packages-user/data-state/src/coreEventLayer.test.ts (1 passed)" + status: pass + - kind: integration + ref: "packages-user/data-state/src/path/heroPathfinding.test.ts (7 passed)" + status: pass + human_judgment: false + +# Metrics +duration: 10 min +completed: 2026-09-10 +status: complete +--- + +# Phase 02 Plan 04: Pathfinding Contract and Type-Gap Closure Summary + +**The user-authored path contract is restored, graph helper types are implementation-owned, and nullable static event collection is type-safe without changing pathfinding behavior.** + +## Performance + +- **Duration:** 10 min +- **Started:** 2026-09-10T01:30:00Z +- **Completed:** 2026-09-10T01:39:49Z +- **Tasks:** 2 +- **Files modified:** 6 plan-listed files plus the required compatibility adjustment in `heroPathfinding.ts` + +## Accomplishments + +- Restored `path/types.ts` to the exact `7a011b2` user baseline with only the authorized `moveTo` and `teleportTo` `| null` corrections +- Relocated `IPathGraphEdge`, `IPathGraphNode`, `IPathGraph`, and `IPathfindingGraphBuilder` to `graph.ts`, preserving L2 search, controller, fallback, and HeroPathfinding integration +- Guarded nullable `loc.static` access in `moverImpl.ts`; dynamic tile events, source ordering, environments, and the single executor call remain unchanged +- Recorded the resolved `moverImpl.ts` TS18047 diagnostic while leaving unrelated repository type/lint baselines open + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Restore the authorized path contract while preserving the end-to-end path stack** - `a2aedb3` (refactor) +2. **Task 2: Close the nullable static event-source type gap** - `93453db` (fix) + +**Plan metadata:** pending final metadata commit + +## Files Created/Modified + +- `packages-user/data-system/src/path/types.ts` - baseline-faithful user-owned path contract +- `packages-user/data-system/src/path/graph.ts` - implementation-owned graph contracts and builder +- `packages-user/data-system/src/path/finder.ts` - graph contract import relocation +- `packages-user/data-system/src/path/system.ts` - public `useMovable` plus implementation-only `useMover` bridge +- `packages-user/data-state/src/hero/moverImpl.ts` - nullable-safe static event-source collection +- `packages-user/data-state/src/path/heroPathfinding.ts` - compatibility implementation of the restored `useMovable` contract +- `.planning/phases/02-pathfinding/deferred-items.md` - TS18047 marked resolved + +## Verification Results + +- Normalized baseline comparison: **PASS** +- `pnpm exec vitest run "packages-user/data-system/src/path" "packages-user/data-state/src/path/heroPathfinding.test.ts"`: **4 files, 35 tests passed** +- `pnpm exec vitest run "packages-user/data-state/src/coreEventLayer.test.ts"`: **1 test passed** +- Targeted ESLint for all modified TypeScript path/mover files: **0 problems** +- `pnpm check:type`: **repository command exits 2**, but contains no diagnostic for `packages-user/data-state/src/hero/moverImpl.ts`; remaining diagnostics are unrelated client, legacy, TileStore, and pre-existing data-state baseline errors +- No client-side click wiring or Phase 1 file was modified; D-11 remains preserved + +## Decisions Made + +- D-07 remains authoritative over later implementation convenience: the user-authored contract is not expanded with graph/helper types or `useMover`. +- `useMover` is retained only as a concrete implementation bridge in `PathfindingSystem`; the public user contract continues to expose `useMovable`. +- D-11 remains data-side only; mobile click integration is deferred to Phase 4. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Restored HeroPathfinding compatibility with the user contract** +- **Found during:** Task 2 type-gate verification after Task 1 restored `useMovable` +- **Issue:** `HeroPathfinding` still implemented the restored `IPathfindingSystem` through its local interface but lacked the newly required `useMovable` method, producing TS2420 +- **Fix:** Added a delegating `useMovable` method; the existing implementation-only `useMover` bridge remains unchanged +- **Files modified:** `packages-user/data-state/src/path/heroPathfinding.ts` +- **Verification:** `pnpm check:type` no longer reports the HeroPathfinding contract diagnostic; focused hero integration tests pass +- **Committed in:** `93453db` + +**2. [Rule 3 - Blocking] Restored repository-required CRLF/Prettier formatting after edits** +- **Found during:** Task 1 targeted ESLint verification +- **Issue:** Patch tooling wrote LF line endings, and the project Prettier rule reported line-ending and import-format errors +- **Fix:** Ran the existing Prettier formatter on the edited TypeScript files, then re-ran ESLint and the focused tests +- **Files modified:** `packages-user/data-system/src/path/types.ts`, `graph.ts`, `finder.ts`, `system.ts`, `packages-user/data-state/src/hero/moverImpl.ts`, `heroPathfinding.ts` +- **Verification:** Targeted ESLint reports 0 problems; focused tests pass +- **Committed in:** `a2aedb3` and `93453db` + +--- + +**Total deviations:** 2 auto-fixed (2 blocking issues) +**Impact on plan:** Both fixes were required by the restored contract and repository formatting gate; no client-side or Phase 1 scope was added. + +## Known Stubs + +- `packages-user/data-state/src/hero/moverImpl.ts:284` — `cannotEnter()` remains intentionally empty because the event model has no trigger for movement blocked by an impassable mask. D-08 allowed adjacent no-pass targets use the direct source-aware OnTouch path instead. Recorded in `.planning/WINDOWS.md` entry 6. + +## Issues Encountered + +- The repository-wide `pnpm check:type` command remains non-zero because of unrelated client, legacy, TileStore, and existing data-state diagnostics. The plan-owned `moverImpl.ts`, path contract, and HeroPathfinding contract diagnostics are clean; the existing phase ledger remains scoped to unrelated baselines. +- Browserslist emitted its existing stale `caniuse-lite` informational notice during Vitest; no package update was performed. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- Plan 02-04 is complete and ready for Plan 02-05's full-suite timeout and CI-command gap closure. +- PATH-01 data-side behavior remains reachable and D-07/D-11 boundaries are preserved. +- The repository-wide type baseline and pre-existing broken-windows entries remain open outside this plan's scope. + +--- +*Phase: 02-pathfinding* +*Completed: 2026-09-10* + +## Self-Check: PASSED + +- All listed implementation, ledger, and SUMMARY files exist +- Task commits `a2aedb3` and `93453db` are present in git history +- Normalized contract comparison, focused path/hero tests, core-event test, target ESLint, and the moverImpl type-diagnostic filter passed +- No client-side or unrelated Phase 1 changes were introduced