From 0a3122c7449b4ec8a932fbf7f32feb89ea13c7ad Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Wed, 9 Sep 2026 15:51:52 +0800 Subject: [PATCH] =?UTF-8?q?docs(02-01):=20complete=20=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E8=8D=89=E6=A1=88=E4=B8=8E=E6=8B=8D=E6=9D=BF=E5=85=B3=E5=8D=A1?= =?UTF-8?q?=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 31 ++-- .../phases/02-pathfinding/02-01-SUMMARY.md | 147 ++++++++++++++++++ 3 files changed, 168 insertions(+), 16 deletions(-) create mode 100644 .planning/phases/02-pathfinding/02-01-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 11e94e1..543722f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -80,11 +80,11 @@ Plans: 2. 移动端点击地图上的可达格时，角色自动寻路移动到该格 3. 寻路正确避开不可通行格（碰撞/障碍/墙体） -**Plans**: 3 plans +**Plans**: 1/3 plans executed **UI hint**: yes Plans: -- [ ] 02-01-PLAN.md — 接口草案 + mover.ts:651 缺陷调查 + 回归脚手架 + D-07 用户拍板关卡（checkpoint） +- [x] 02-01-PLAN.md — 接口草案 + mover.ts:651 缺陷调查 + 回归脚手架 + D-07 用户拍板关卡（checkpoint） - [ ] 02-02-PLAN.md — L0 坐标回写缺陷修复 + L2 寻路核心（有向图 + 最小损失 + 仅取路径 + 回退策略槽位） - [ ] 02-03-PLAN.md — L3 接线（逐步/瞬移/回退默认策略/D-08 双语义/打断接管）+ barrel/logger 装配 + 阶段门禁 @@ -165,7 +165,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| | 1. 事件系统 | 13/13 | In Progress| | -| 2. 寻路系统 | 0/TBD | Not started | - | +| 2. 寻路系统 | 1/3 | 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 bc3744a..e43a6d8 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,13 +2,13 @@ gsd_state_version: "1.0" milestone: v1.0 current_phase: 02 -current_phase_name: pathfinding +current_phase_name: 寻路系统 status: executing -stopped_at: Phase 2 context gathered -last_updated: "2026-09-09T07:10:43.282Z" +stopped_at: Completed 02-01-PLAN.md (用户六项拍板已记录) +last_updated: "2026-09-09T07:49:55.948Z" last_activity: 2026-09-09 -last_activity_desc: "Phase 01 verification passed: user confirmed compile-cache reuse and setRaw invalidation with no issue reported" -state_head: 1ad8176f682f182b71a76f800412d5050e8aeacb +last_activity_desc: Phase 02 execution started +state_head: 5a1b12e146705983ab9f598da185cb0f5973b982 progress: total_phases: 6 completed_phases: 0 @@ -24,14 +24,14 @@ milestone_name: milestone See: .planning/PROJECT.md (updated 2026-09-07) **Core value:** 引擎能完整跑通一部魔塔——开局到结局，存档、战斗、地图、事件、剧情全链路可玩。 -**Current focus:** Phase 01 — event +**Current focus:** Phase 02 — 寻路系统 ## Current Position -Phase: 02 (pathfinding) — READY TO EXECUTE -Plan: 13 of 13 (point-event reference/storage refactor complete) -Status: Plan 01-13 verification complete; ready for phase completion transition -Last activity: 2026-09-09 — Plan 01-13 focused tests/lint passed; repository-wide type diagnostics remain deferred outside plan scope +Phase: 02 (寻路系统) — EXECUTING +Plan: 2 of 3 +Status: Ready to execute +Last activity: 2026-09-09 — Phase 02 execution started Progress: [█████████░] 92% @@ -69,6 +69,7 @@ Progress: [█████████░] 92% | Phase 01 P11 | 13min | 2 tasks | 3 files | | Phase 01 P12 | 20min | 2 tasks | 6 files | | Phase 01 P13 | 30 | 3 tasks | 11 files | +| Phase 02 P01 | 25min | 3 tasks | 2 files | ## Accumulated Context @@ -100,6 +101,10 @@ Recent decisions affecting current work: - [Phase 01]: Gap-closure Plan 01-12 preserves serialized registration/map-id binding, rawEvent/cache/Promise/as, and eventStore-cycle deferrals. - [Phase 01]: Plan 01-13: LayerEventView owns point-event refs with O(1) dirty state; MapLayer uses flat index storage and ref-first overlays; MapTileBase centralizes default restoration. - [Phase 01]: Plan 01-13 preserves the approved save shape, resize semantics, locked deferrals, and leaves types.ts and executor.ts user edits untouched. +- [Phase 02]: [Phase 02] 02-01 拍板：pathfinding/types.ts 由用户亲自编写（接口事实源），02-02/02-03 不得创建或重写该文件 +- [Phase 02]: [Phase 02] 02-01 拍板：mover.ts:651 坐标回写缺陷 go——授权 02-02 改为 || 并翻绿 4 个回归用例 +- [Phase 02]: [Phase 02] 02-01 拍板：D-08 触发语义=通行掩码允许到达且目标 no-pass 才触发 hit/OnTouch，掩码不可达一律不触发；实现机制须与该语义一致 +- [Phase 02]: [Phase 02] 02-01 拍板：打断时序选选项 1（stop 后 await 兑现再起新寻路）；图方向性仅 4 正交向；文件归属按草案原样（types.ts 除外） ### Pending Todos @@ -122,6 +127,6 @@ None yet. ## Session Continuity -Last session: 2026-09-09T06:27:22.453Z -Stopped at: Phase 2 context gathered -Resume file: .planning/phases/02-pathfinding/02-CONTEXT.md +Last session: 2026-09-09T07:49:38.684Z +Stopped at: Completed 02-01-PLAN.md (用户六项拍板已记录) +Resume file: None diff --git a/.planning/phases/02-pathfinding/02-01-SUMMARY.md b/.planning/phases/02-pathfinding/02-01-SUMMARY.md new file mode 100644 index 0000000..89759ee --- /dev/null +++ b/.planning/phases/02-pathfinding/02-01-SUMMARY.md @@ -0,0 +1,147 @@ +--- +phase: 02-pathfinding +plan: 01 +subsystem: pathfinding +tags: [pathfinding, interface-draft, dijkstra, mover, zero-dependency, user-decision-gate] + +# Dependency graph +requires: + - phase: 01-event-system + provides: source-aware 事件派发（IGameEventInvocation / IBlockEventEnv）、HeroMover + DefaultHeroMoveTopImpl 移动链路、IMapLayer 点事件生命周期 +provides: + - 寻路系统接口草案 02-INTERFACE-DRAFT.md（六节齐备 + 六项拍板记录，02-02/02-03 的执行依据） + - 用户拍板结论：types.ts user-owned、P1 修复 go、D-08 触发语义、打断时序选项 1、4 向图 + - L0 mover.ts:651 坐标回写缺陷回归测试脚手架（4 个 skip 用例，02-02 翻绿） +affects: [02-02, 02-03, phase-04-rendering] + +# Actuals (#2632) +actuals: + tokens: 5622 # chars/4 over realized diff (packages-user + draft + planning docs) + tasks: 3 + commits: 3 # MEASURED: git rev-list --count gsd-plan-head-before-02-01..HEAD at SUMMARY write + +# Tech tracking +tech-stack: + added: [] # 零新依赖（D-07 / T-02-SC：无安装对象） + patterns: + - "D-07 明锁：AI 起草 → 用户逐项拍板 → 才实现（接口事实源由用户持有）" + - "回归脚手架先行：缺陷修复前以 it.skip 提交用例，修复后翻绿" + +key-files: + created: + - .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md + - packages-user/data-common/src/common/mover.test.ts + modified: [] + +key-decisions: + - "types.ts（packages-user/data-system/src/pathfinding/）由用户亲自编写，为接口事实源；02-02/02-03 不得创建或重写" + - "文件归属按草案原样：L2 data-system/src/pathfinding/（graph/system/index）+ L3 data-state/src/pathfinding/heroPathfinding.ts，types.ts 除外" + - "P1 修复 go：mover.ts:651 条件 && → || 授权 02-02 执行并翻绿 4 个回归用例" + - "D-08 触发语义（用户原话）：掩码（CannotIn/CannotOut）允许到达且目标为 no-pass 才触发 hit/OnTouch；掩码不可达一律不触发；实现机制须与该语义一致" + - "打断时序：选项 1 —— stop() 后 await 兑现，再查新位置起新寻路（无竞态，最多延迟一步）" + - "图方向性：仅 4 正交向（与 PassBit 四位掩码一致，不含斜向）" + +patterns-established: + - "user-owned 接口文件模式：接口事实源文件由用户编写，AI 实现计划只消费不创建" + - "skip-first 回归脚手架：缺陷确认后先铺 skip 用例，修复任务负责翻绿" + +requirements-completed: [] # PATH-01/PATH-02 为 02-02/02-03 共享声明，按 shared-ID 门延迟至实现计划完成 + +# Coverage metadata (#1602) +coverage: + - id: D1 + description: 寻路系统接口草案 02-INTERFACE-DRAFT.md（签名清单、文件归属、D-08 两方案、P1 调查、打断时序、图方向性六节 + 拍板记录） + requirement: PATH-01 + verification: [] + human_judgment: true + rationale: 草案质量与签名取舍由用户在 checkpoint 逐项拍板验收——六项明确结论（含原话）已忠实记录于草案「拍板记录」节，即为人工验收凭证 + - id: D2 + description: 六项用户拍板记录（接口签名 types.ts user-owned、文件归属、P1 go、D-08 触发语义、打断选项 1、4 向图）逐字落档 + verification: [] + human_judgment: true + rationale: 拍板本身就是人类判断，无法自动化验证；用户决策原话已记录并同步标注至草案各节（0 处「待拍板」残留） + - id: D3 + description: L0 mover 坐标回写回归测试脚手架（4 个 it.skip 用例：x 正交 / y 正交 / 斜向 / 传送步） + requirement: PATH-01 + verification: + - kind: unit + ref: "packages-user/data-common/src/common/mover.test.ts (pnpm exec vitest run — 4 skipped, 0 failed)" + status: pass + human_judgment: false + +# Metrics +duration: 25min +completed: 2026-09-09 +status: complete +--- + +# Phase 02 Plan 01: 接口草案与拍板关卡 Summary + +**寻路系统接口草案（六节）产出并经用户六项逐字拍板落档，P1 mover.ts:651 坐标回写缺陷获 go 授权，4 用例回归脚手架以 skip 状态通过 vitest——02-02/02-03 的执行依据齐备** + +## Performance + +- **Duration:** 25 min（Task 1 提交 07:30 UTC 起算至 SUMMARY 落档） +- **Started:** 2026-09-09T07:30:19Z（Task 1 commit） +- **Completed:** 2026-09-09T07:55Z 左右 +- **Tasks:** 3（Task 1 / Task 2 / Task 3 checkpoint 拍板） +- **Files modified:** 2（+STATE/ROADMAP/SUMMARY 元数据） + +## Accomplishments + +- 02-INTERFACE-DRAFT.md：六节齐备（接口签名草案、文件归属提案、D-08 两方案并列、P1 缺陷调查、打断时序两选项、图方向性两选项）+ 边界守卫要求（T-02-01/T-02-02）+ 拍板记录 +- 用户六项拍板逐字落档：types.ts 由用户亲自编写（02-02/02-03 不得创建/重写）；文件归属按草案原样；P1 修复 **go**（mover.ts:651 `&&`→`||`）；D-08 触发语义 = 掩码允许到达且目标 no-pass 才触发（掩码不可达一律不触发）；打断时序选项 1；图方向性仅 4 正交向 +- 草案全文 0 处「待拍板」残留，各节已同步标注拍板结论 +- mover.test.ts：4 个 it.skip 回归用例（x 正交 / y 正交 / 斜向 / 传送步坐标回写），vitest 0 failed，生产代码零改动 + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: 起草寻路系统接口草案与决策问题清单** - `a9b1ba1` (docs) +2. **Task 2: 铺设 L0 mover 坐标回写回归测试脚手架（skip 状态）** - `9477b2c` (test) +3. **Task 3: 用户拍板接口草案与全部待决选项（D-07 关卡）** - `5a1b12e` (docs) + +**Plan metadata:** (本提交 — docs(02-01): complete) + +## Files Created/Modified + +- `.planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md` - 接口草案 + 拍板记录（接口事实源声明：types.ts user-owned） +- `packages-user/data-common/src/common/mover.test.ts` - L0 坐标回写回归脚手架（4 skip 用例，02-02 翻绿） + +## Decisions Made + +见 frontmatter `key-decisions` —— 全部为用户 checkpoint 拍板结论，原话忠实记录于草案「拍板记录」节。 + +## Deviations from Plan + +None - plan executed exactly as written.（Task 3 checkpoint 由用户逐项拍板后正常恢复，属计划内流程。） + +## Issues Encountered + +- PATH-01/PATH-02 同时被 02-02/02-03 声明，按 shared-ID 门（#2388）本计划不标记 requirements 完成——待实现计划完成 SUMMARY 后由其触发 `requirements.mark-complete`。 + +## Known Stubs + +| 文件 | 位置 | 原因 | +| ---- | ---- | ---- | +| `packages-user/data-common/src/common/mover.test.ts` | 4 个 `it.skip` 用例 | 刻意脚手架（02-01 不修生产代码，D-07）：待 02-02 执行已获 go 授权的 mover.ts:651 `&&`→`||` 修复后翻绿 | + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 02-02（L2 graph/system + P1 修复 + 用例翻绿）与 02-03（L3 hero 接线）可依拍板结果开工；**开工前先等待用户提交其编写的 `packages-user/data-system/src/pathfinding/types.ts`**（接口事实源，02-02/02-03 不得代写） +- D-08 实现机制须与用户指定触发语义（掩码允许到达 + 目标 no-pass）一致；打断时序按选项 1；图仅 4 正交向 + +--- +*Phase: 02-pathfinding* +*Completed: 2026-09-09* + +## Self-Check: PASSED + +- SUMMARY.md 存在；Task 1/2/3 提交（`a9b1ba1`、`9477b2c`、`5a1b12e`）均在 git log 中确认 +- 草案验证命令通过（拍板记录 / go/no-go / 方案 A|B 均命中，0 处「待拍板」残留） +- mover.test.ts skip 脚手架已登记 broken-windows 台账（entry #4, skipped-test, open）