diff --git a/.planning/phases/10-docs-restructure/10-23-SUMMARY.md b/.planning/phases/10-docs-restructure/10-23-SUMMARY.md new file mode 100644 index 0000000..ca4ed16 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-23-SUMMARY.md @@ -0,0 +1,163 @@ +--- +phase: 10-docs-restructure +plan: 23 +subsystem: docs +tags: [vitepress, pathfinding, hero-attribute, damage-calculator] + +# Dependency graph +requires: [] +provides: + - "docs/advanced/ii/pathfinding.md:自动寻路的分工、四段流程、结果状态、两种移动方式与可替换点" + - "docs/advanced/ii/adding-hero-attribute.md:新增勇士属性的接口、默认值、初始值、修饰器与伤害计算接入" +affects: [10-24, 10-25] + +# Actuals (#2632) +actuals: + tokens: 4921 + tasks: 2 + commits: 2 + plan_head_before: 0d3645989fc78d71319d0c10c1aabb1f91f3f8a5 + +# Tech tracking +tech-stack: + added: [] + patterns: + - "高级教程按库文档方式叙述:概念先行、完整代码块、解释性注释充足" + - "主干与边界分离:边界情况集中在「边界与注意」一节" + - "数据端专属内容;渲染端与编辑器用 D-47 非断链占位" + +key-files: + created: + - docs/advanced/ii/pathfinding.md + - docs/advanced/ii/adding-hero-attribute.md + modified: [] + +key-decisions: + - "寻路篇只讲流程与替换点,不展开最小损失搜索的内部实现" + - "属性篇以 atkSpeed(基础 100)与 armor(基础 0)为例,接入伤害计算器" + - "装备 percentage 使用倍率写法 0.15 表示 15%,与属性自身以百分数存储的 15 区分" + +patterns-established: + - "寻路绑定:初始化注入谓词与移动器,切换楼层时重新绑定图层与方向处理器" + - "新增属性五处链路:接口 → 默认值 → 内容配置 → 计算接入 → 显示" + +requirements-completed: [] + +coverage: + - id: D1 + description: "自动寻路篇:四段流程、结果状态、moveTo/teleportTo、损失函数、瞬移策略与钩子" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "文档内容与源码一致性、叙述难度需按 D-46/D-57 由用户审阅" + - id: D2 + description: "新增勇士属性篇:改 IHeroAttr、补默认值与内容配置、修饰器、伤害计算接入与验证" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "示例数值与示例选型需用户确认;编辑器与状态栏为 D-47 占位" + +# Metrics +duration: 30min +completed: 2026-10-21 +status: complete +--- + +# Phase 10 Plan 23: 高级 II 寻路与勇士属性 Summary + +**高级 II 的自动寻路流程篇与新增勇士属性链路篇,源码核对完成,构建通过且无死链** + +## Performance + +- **Duration:** 约 30 分钟 +- **Started:** 2026-10-21T18:20:00Z(约) +- **Completed:** 2026-10-21T18:50:41Z +- **Tasks:** 2(Task 0 审批门已由派发上下文放行) +- **Files created:** 2 + +## Accomplishments + +- `pathfinding.md` 讲清「绑定移动器 → 构建图 → 求路径 → 交给移动器」四段流程,给出损失函数、瞬移策略与瞬移钩子的完整示例。 +- `adding-hero-attribute.md` 以攻速与护甲为例,覆盖接口、默认值、内容配置、修饰器、伤害计算器与装备衔接。 +- 两篇均按 D-59 库文档风格书写,CRLF、单 H1,构建 `build complete`,无 dead link。 + +## Task Commits + +1. **Task 1: 编写自动寻路 pathfinding.md** - `64fb049` (docs) +2. **Task 2: 编写新增勇士属性 adding-hero-attribute.md** - `548007c` (docs) + +**Plan metadata:** 本 SUMMARY 提交(docs) + +## Files Created/Modified + +- `docs/advanced/ii/pathfinding.md` - 自动寻路的分工、流程、状态、移动方式、损失函数、策略与钩子。 +- `docs/advanced/ii/adding-hero-attribute.md` - 新增勇士属性的完整数据端链路与伤害计算接入。 + +## Decisions Made + +- 寻路篇不解释最小损失搜索的内部实现,只保留输入输出与替换点(D-67)。 +- 初始化只注入通行谓词与移动器,图层初始为 `null`;文档明确说明方向处理器需在绑定楼层时自行注入,否则 `getPath` 返回 `InvalidInput`。 +- 属性示例选攻速与护甲:攻速参与每回合伤害并影响回合数,护甲在最终伤害上按百分比减免。 +- 装备 `percentage` 采用倍率写法(`0.15` = 15%),与属性自身以百分数存储(`15` = 15%)在文中区分说明。 + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] 装备 percentage 示例改为 0.15 以匹配源码语义** +- **Found during:** Task 2 +- **Issue:** 计划任务书写 `percentage: { atkSpeed: 15 }`,但 `PercentageModifier.modify` 按 `baseValue * this.value` 计算,`15` 会得到 1500%;现有 `equipment-system.md` 与中级 `hero-attribute.md` 也约定 `0.1` 表示 10%。 +- **Fix:** 示例改为 `percentage: { atkSpeed: 0.15 }`,并说明属性自身按百分数存储、装备 `percentage` 是倍率;基础 100 加 15% 仍得到 115,与计划验证预期一致。 +- **Files modified:** `docs/advanced/ii/adding-hero-attribute.md` +- **Verification:** 对照 `packages-user/data-base/src/hero/modifier.ts` 与 `equipStore.ts`;构建通过。 +- **Committed in:** `548007c` + +**2. [Rule 1 - Bug] 瞬移钩子的触发范围按源码修正** +- **Found during:** Task 1 +- **Issue:** `onBeforeTeleportTo` 只在瞬移分支触发,而 `onAfterTeleportTo` 挂在所有 `startMove` 的控制器结束回调上,普通逐步移动也会触发;计划文字容易读成两者都只在瞬移时触发。 +- **Fix:** 文档分别说明两个钩子的触发条件,并提醒任意绑定到 `useMover` 的移动器都会触发,不只勇士。 +- **Files modified:** `docs/advanced/ii/pathfinding.md` +- **Verification:** 对照 `packages-user/data-system/src/path/system.ts`;构建通过。 +- **Committed in:** `64fb049` + +--- + +**Total deviations:** 2 auto-fixed(均为源码一致性的 Rule 1 修正) +**Impact on plan:** 不扩大范围;修正后示例与源码、既有装备文档保持一致。 + +## Issues Encountered + +- PowerShell 执行策略阻止直接运行 `pnpm`,改用 `cmd /c "pnpm ..."` 完成 prettier 与构建命令。 +- 工作区存在与本计划无关的既有修改 `packages/system/src/hotkey/type.ts`,未纳入任何提交。 + +## Known Stubs + +- `docs/advanced/ii/adding-hero-attribute.md` 的编辑器与状态栏显示按 D-47 占位:`编辑器 · 新增英雄属性项`、`渲染端 · 状态栏`,并附 ``。 +- 两篇末尾的渲染端表现占位分别是 `` 与 ``。 + +这些占位是计划明确要求的非断链占位,不影响数据端内容的完整性。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 10-24 可直接沿用本篇「改接口 → 补默认值 → 接入系统」的链路,对照编写新增怪物属性。 +- 10-25 接入侧边栏时新增这两篇入口;本计划未修改 `docs/.vitepress/config.ts`。 +- 两篇均需按 D-46/D-57 进入用户主导的修订循环后再收尾。 + +--- +*Phase: 10-docs-restructure* +*Completed: 2026-10-21* + +## Self-Check: PASSED + +- `docs/advanced/ii/pathfinding.md` 存在,提交 `64fb049` +- `docs/advanced/ii/adding-hero-attribute.md` 存在,提交 `548007c` +- `.planning/phases/10-docs-restructure/10-23-SUMMARY.md` 存在 +