mirror of
https://github.com/motajs/template.git
synced 2026-09-12 17:58:51 +08:00
docs(02-04): complete pathfinding contract gap closure plan
This commit is contained in:
parent
93453db417
commit
78b029544b
@ -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 | - |
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
}
|
||||
]
|
||||
````
|
||||
|
||||
203
.planning/phases/02-pathfinding/02-04-SUMMARY.md
Normal file
203
.planning/phases/02-pathfinding/02-04-SUMMARY.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user