diff --git a/.planning/phases/10-docs-restructure/10-24-SUMMARY.md b/.planning/phases/10-docs-restructure/10-24-SUMMARY.md new file mode 100644 index 0000000..81fb4ff --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-24-SUMMARY.md @@ -0,0 +1,145 @@ +--- +phase: 10-docs-restructure +plan: 24 +subsystem: docs +tags: [vitepress, enemy-attribute, enemy-context, combat, buildup, damage-system] + +# Dependency graph +requires: + - phase: 10-docs-restructure + provides: "10-23 的勇士属性篇与高级 II 写作基线(D-59 库文档风格)" +provides: + - "docs/advanced/ii/adding-enemy-attribute.md:新增怪物属性的接口、默认模板与内容、读取修改、伤害/光环/查询/最终接入" + - "docs/advanced/ii/enemy-context-and-combat.md:上下文职责、三种怪物对象、buildup 五段、优先级边界、局部刷新与伤害缓存" +affects: [10-25] + +# Actuals (#2632) +actuals: + tokens: 6506 + tasks: 2 + commits: 2 + plan_head_before: 4f48ad5aa1cbfddc37c20062008145ce703fd99a + +# Tech tracking +tech-stack: + added: [] + patterns: + - "高级教程按库文档方式叙述:概念先行、完整代码块、解释性注释充足" + - "主干与边界分离:优先级告警、缓存失效等特殊情况集中在「边界与注意」" + - "数据端专属内容;编辑器与怪物图鉴用 D-47 非断链占位" + +key-files: + created: + - docs/advanced/ii/adding-enemy-attribute.md + - docs/advanced/ii/enemy-context-and-combat.md + modified: [] + +key-decisions: + - "怪物属性示例沿用 D-67 暂定的攻速 atkSpeed(100 为正常)与护甲 armor(百分比减伤)" + - "怪物护甲解释为「怪物受到的伤害按百分比下降」,因此会拉长回合数;攻速缩放怪物每回合伤害" + - "战斗篇只讲时序与交互,光环/查询/最终效果的接口写法回指中级教程,不重复展开" + - "明确写出引擎未内置查询效果:initializeEnemy 未注册任何查询,查询需自行注册" + +patterns-established: + - "新增怪物属性链路:接口 → 默认模板与内容 → 读取/修改 → 伤害、光环、查询、最终接入" + - "构建顺序:reset → buildupSpecials → buildupBase → buildupQuery → buildupFinal → 伤害标脏与地图伤害刷新" + +requirements-completed: [] + +coverage: + - id: D1 + description: "新增怪物属性篇:改 IEnemyAttr、补默认模板与内容、读取修改、伤害/光环/查询/最终接入与验证" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "示例数值与叙述难度需按 D-46/D-68 由用户审阅;编辑器与图鉴为 D-47 占位" + - id: D2 + description: "怪物上下文与战斗深入篇:上下文职责、三种怪物对象、buildup 五段、优先级、局部刷新、伤害缓存与交互表" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "buildup 顺序、优先级边界与脏标记语义需按 D-46/D-68 由用户对照源码审阅" + +# Metrics +duration: 25min +completed: 2026-10-21 +status: complete +--- + +# Phase 10 Plan 24: 高级 II 怪物属性与战斗深入 Summary + +**高级 II 的怪物属性扩展篇与怪物上下文/战斗深入篇,按源码核对 buildup 顺序与伤害缓存,构建通过且无死链** + +## Performance + +- **Duration:** 约 25 分钟 +- **Started:** 2026-10-21T18:35:00Z(约) +- **Completed:** 2026-10-21T19:00:17Z +- **Tasks:** 2(Task 0 审批门已由派发上下文放行) +- **Files created:** 2 + +## Accomplishments + +- `adding-enemy-attribute.md` 以攻速与护甲为例,覆盖 `IEnemyAttr`、默认模板与内容数据、读取/修改、伤害计算器、光环、常规查询、最终效果与验证;编辑器与怪物图鉴按 D-47 占位。 +- `enemy-context-and-combat.md` 讲清上下文职责、三种怪物对象、`buildup()` 五段、优先级边界、`needTotallyRefresh` 与局部刷新、伤害缓存,以及四个阶段与地图伤害的交互。 +- 两篇均按 D-59 库文档风格书写,CRLF、单 H1,代码块完整并带解释性注释;构建 `build complete`,无 dead link。 + +## Task Commits + +1. **Task 1: 编写新增怪物属性 adding-enemy-attribute.md** - `ed7e174` (docs) +2. **Task 2: 编写怪物上下文与战斗深入 enemy-context-and-combat.md** - `c154fae` (docs) + +**Plan metadata:** 本 SUMMARY 提交(docs) + +## Files Created/Modified + +- `docs/advanced/ii/adding-enemy-attribute.md` - 新增怪物属性的完整数据端链路:接口、默认模板与内容、读取修改、伤害/光环/查询/最终接入、D-47 占位与验证。 +- `docs/advanced/ii/enemy-context-and-combat.md` - 怪物上下文的构建顺序、优先级边界、局部刷新、伤害缓存与阶段交互。 + +## Decisions Made + +- 怪物攻速按百分数存储,`100` 为正常速度;护甲同样按百分数存储,`0` 为不减伤。 +- 怪物护甲解释为降低勇士对怪物的每回合伤害,因此护甲越高回合数越多、总伤害越大;攻速则直接缩放怪物每回合伤害。这与勇士属性篇「攻速缩放勇士每回合伤害、护甲减免最终伤害」形成对照,但两者都遵循同一套百分比约定。 +- 战斗篇不重复中级教程的接口细节,只讲 `buildup()` 的时序、优先级边界与缓存失效。 +- 明确说明 `src/data/enemy/initialize.ts` 未注册任何查询实现,避免把查询效果误写成内置能力。 +- 全局光环示例使用 `addAura`,并补充「测试里手建空上下文时需先注册转换器或特殊查询」的实现约束。 + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +- 首次运行 Task 1 验证脚本时,正文只出现 `IEnemyAuraView`,未包含计划要求的字面量 `IAuraView`;补充「`IEnemyAuraView` 继承自 `IAuraView`」一句后验证通过。这是为满足验收门禁的措辞补充,不涉及内容变更。 +- PowerShell 执行策略阻止直接运行 `pnpm` 的部分场景,统一改用 `cmd /c "pnpm ..."` 完成 prettier 与构建。 +- 工作区存在与本计划无关的既有修改 `packages/system/src/hotkey/type.ts`,未纳入任何提交。 + +## Known Stubs + +- `docs/advanced/ii/adding-enemy-attribute.md` 的编辑器属性项与怪物图鉴按 D-47 占位:代码 span `编辑器 · 新增怪物属性项` 与 `怪物图鉴`,并附 ``。 +- 这些占位是计划明确要求的非断链占位,不影响数据端内容的完整性。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 10-25 接入侧边栏时新增这两篇入口;本计划未修改 `docs/.vitepress/config.ts`。 +- 两篇均需按 D-46/D-68 进入用户主导的修订循环后再收尾。 +- 战斗篇可作为高级 II 数据端的收束页,供后续高级 III 引用上下文与伤害时序。 + +--- + +*Phase: 10-docs-restructure* +*Completed: 2026-10-21* + +## Self-Check: PASSED + +- `docs/advanced/ii/adding-enemy-attribute.md` 存在,提交 `ed7e174` +- `docs/advanced/ii/enemy-context-and-combat.md` 存在,提交 `c154fae` +- `.planning/phases/10-docs-restructure/10-24-SUMMARY.md` 存在