diff --git a/.planning/phases/10-docs-restructure/10-13-SUMMARY.md b/.planning/phases/10-docs-restructure/10-13-SUMMARY.md new file mode 100644 index 0000000..7bd32ca --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-13-SUMMARY.md @@ -0,0 +1,131 @@ +--- +phase: 10-docs-restructure +plan: 13 +subsystem: docs +tags: [vitepress, documentation, declarative, imperative, data-engine] + +# Dependency graph +requires: + - phase: 10-docs-restructure + provides: "中级教程中的特殊属性、战斗总览、伤害计算、数据端与钩子页面" +provides: + - "docs/advanced/declarative-vs-imperative.md(高级 I 第一篇)" +affects: ["10-14", "10-15", "10-16", "10-17"] + +actuals: + tokens: 3056 + tasks: 2 + commits: 2 + plan_head_before: 8f325091998f568b6632d28be8fe8fea7421ca61 + +tech-stack: + added: [] + patterns: + - "旧样板命令式与新样板声明式并排对照" + - "五组源码事实说明声明什么、引擎何时执行、为何更稳" + - "通用模板单独成节,示例只用于演示六步" + +key-files: + created: + - docs/advanced/declarative-vs-imperative.md + modified: [] + +key-decisions: + - "旧样板示例用伪代码并明确标注不可照抄,避免臆造旧接口名" + - "通用模板与六步示例分开,示例不冒充模板" + - "加粗改用 HTML strong,以满足 D-52 与计划中的加粗门禁" + +patterns-established: + - "声明式扩展统一按「实现接口、注册一次、引擎调用」三步理解" + - "计算类扩展必须无副作用;状态修改放到引擎规定的时机" + +requirements-completed: [] + +coverage: + - id: D1 + description: "高级 I 第一篇:声明式 vs 命令式接口" + verification: + - kind: other + ref: "cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\" -> build complete" + status: pass + human_judgment: true + rationale: "文档内容与受众适配需用户人工审阅(D-46 第 2 阶段)" +--- + +# Phase 10 Plan 13: 声明式 vs 命令式接口 Summary + +**高级 I 第一篇落地:用旧样板命令式与新样板声明式并排对照,串起光环、伤害计算器、道具效果、可存档对象与钩子五组源码事实,并给出通用模板、六步示例与可操作验证。** + +## Performance + +- **Duration:** ~30 min +- **Started:** 2026-10-19T13:45:00Z +- **Completed:** 2026-10-19T14:12:26Z +- **Tasks:** 2 +- **Files modified:** 1 created + +## Accomplishments + +- 新建 `docs/advanced/` 并写下 `declarative-vs-imperative.md`,单 H1、CSV/CRLF 规范、数据端 only。 +- 用「谁决定执行时机」讲清命令式与声明式的差别,并给出执行时机、次数、副作用、存档、录像、组合方式的对照表。 +- 五组机制全部落在当前源码事实:`special` + `special.ts` / `aura.ts`、`IDamageCalculator`、`IItemEffect`、`ISaveableContent`、`addHook` / `forEachHook`。 +- 加入独立的「模板:声明式扩展的通用骨架」,与六步示例分开;示例按目标、改哪里、复制什么、改什么、怎么验证、注意组织。 +- 明确「计算器必须无副作用」「地图伤害按计算后怪物结算」「一次性动作仍用命令式但必须计入录像」。 +- 指向高级 II/III 的内容只用代码 span 或 HTML 注释占位,不产生真实链接。 +- prettier 检查通过;`pnpm docs:build` 输出 `build complete`,无 dead link。 + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: 编写 declarative-vs-imperative.md 正文** - `47777bc` (docs) +2. **Task 2: 源码核对、格式与构建收口** - `7285ab9` (docs) + +Task 0 为人工确认关卡,用户已批准,无代码提交。 + +## Files Created/Modified + +- `docs/advanced/declarative-vs-imperative.md` - 高级 I 第一篇,声明式与命令式接口的概念与实操基础 + +## Decisions Made + +- 旧样板命令式示例使用伪代码并标注「不可照抄」,因为无法核实的旧接口名不应臆造。 +- 通用模板与具体示例分开:模板只给「实现接口、注册一次、引擎调用」的骨架,六步示例只演示一条光环声明。 +- 加粗改用 HTML ``:计划中的加粗门禁正则会把闭合 `**` 后紧跟中文标点也判为违规,D-52 明确允许 ``。 + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] 加粗语法改用 HTML strong** +- **Found during:** Task 1(正文写作) +- **Issue:** 计划的 BOLD-FLANK 正则同时匹配「`**` 后紧跟标点」,中文里 `**目标**:` 这类闭合标记会被误判,导致 `**` 无法通过门禁。 +- **Fix:** 按 D-52 允许的方式,统一改用 `…`;渲染效果不变,门禁可通过。 +- **Files modified:** `docs/advanced/declarative-vs-imperative.md` +- **Verification:** STATIC-OK、prettier 检查通过、构建 `build complete`。 +- **Committed in:** `47777bc` + +--- + +**Total deviations:** 1 auto-fixed (1 blocking) +**Impact on plan:** 仅影响加粗的书写形式,不改变内容与结构。 + +## Issues Encountered + +- 构建门禁运行 `pnpm` 时会顺带改写 `pnpm-lock.yaml`(删掉已不存在的 workspace 链接)。该改动与本计划无关,已在每次提交前还原,未纳入提交。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 本篇可作为 10-14 至 10-17 的概念基础:插件、存档、录像与钩子都建立在「声明规则、引擎在合适时机执行」之上。 +- 页面尚未注册到 `docs/.vitepress/config.ts`,按计划留到 10-18 统一处理。 +- 待用户按 D-46 第 2 阶段进行高级 I 读者修订。 + +## Self-Check: PASSED + +- FOUND: `docs/advanced/declarative-vs-imperative.md` +- FOUND: `47777bc` +- FOUND: `7285ab9`