docs(10-27): U8 修订(章节锚点 + compareEquip 语义)

- U8-02: equipment-system.md 装备对比改为空槽语义,删除逐键回退表与相对现役装备说法
- U8-01: 5 处跨文档章节引用补标题锚点;指向整篇的链接保持不变
- 10-27-USER-REVIEW.md 记录批次 F 并留高级 I/中级锚点审计待办
This commit is contained in:
AncTe committed 2026-10-22 18:38:45 +08:00
1 parent 77f5b3aa19
commit 3d2d375302
5 files changed
+44 -31

No files matched your search

@@ -79,16 +79,16 @@
## 第 2 轮(2026-10-22,待执行)
| # | 用户意见 | 落点 |
|---|----------|------|
| U7-01 | 事件视图说法有误:`eventView.set(num)` 不会重置为默认事件,它要求第二个 `event` 参数必填;该注释来源不明,需修正 | `point-and-tile-events.md`(及事件相关) |
| U7-02 | 不要在文档里写「模块级复用 / 不要在调用处内联 new」这类说明;用户只是要求改写法,读者不需要知道这些细节 | `custom-range.md` |
| U7-03 | `transferToDynamic` 的 `keepEvent` 说明有误:**以引擎方法注释为准**——「不论是否 keepEvent,源图块的图块事件都会被清空」。若注释与实现不一致,按注释写,并**向用户报告**(长期规范 D-72) | `static-vs-dynamic-tiles.md` |
| U7-04 | 动态图块的 `mover` 未讲却讲了 `moveBlock`。应先用**引用**指向高级 I 的 mover 文档(不重复讲概念/接口),再讲 `moveBlock`;顺序必须 mover 在前、moveBlock 在后 | `static-vs-dynamic-tiles.md` |
| U7-05 | 指令码位宽在高级 II 不需要讲,只提一嘴:99.9% 情况用不完 255 个指令码;如有极小概率超过,参考高级 III 指定文档。细节放高级 III | `custom-replay-command.md` |
| U7-06 | 录像的典型例子「选择框」不是让你改成代码示例;原来的代码示例很好,改回去。选择框一般内置 | `custom-replay-command.md` |
| U7-07 | `NoPath` 是正常输出,不是错误;被怪物挡着去不了很正常。当前「NoPath 处理建议」不对,只需说明「找不到可行路径」,无需处理 | `pathfinding.md` |
| U7-08 | 假定编辑器已完成:不要写「编辑器就位前改文件、就位后用编辑器」。需要编辑器的地方只写「需要编辑器」标识,不讲没有编辑器时怎么做。所有 `.jsonc` 都由编辑器负责,涉及部分先写占位(长期规范 D-73) | 全部 |
| # | 用户意见 | 落点 |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| U7-01 | 事件视图说法有误:`eventView.set(num)` 不会重置为默认事件,它要求第二个 `event` 参数必填;该注释来源不明,需修正 | `point-and-tile-events.md`(及事件相关) |
| U7-02 | 不要在文档里写「模块级复用 / 不要在调用处内联 new」这类说明;用户只是要求改写法,读者不需要知道这些细节 | `custom-range.md` |
| U7-03 | `transferToDynamic` 的 `keepEvent` 说明有误:**以引擎方法注释为准**——「不论是否 keepEvent,源图块的图块事件都会被清空」。若注释与实现不一致,按注释写,并**向用户报告**(长期规范 D-72) | `static-vs-dynamic-tiles.md` |
| U7-04 | 动态图块的 `mover` 未讲却讲了 `moveBlock`。应先用**引用**指向高级 I 的 mover 文档(不重复讲概念/接口),再讲 `moveBlock`;顺序必须 mover 在前、moveBlock 在后 | `static-vs-dynamic-tiles.md` |
| U7-05 | 指令码位宽在高级 II 不需要讲,只提一嘴:99.9% 情况用不完 255 个指令码;如有极小概率超过,参考高级 III 指定文档。细节放高级 III | `custom-replay-command.md` |
| U7-06 | 录像的典型例子「选择框」不是让你改成代码示例;原来的代码示例很好,改回去。选择框一般内置 | `custom-replay-command.md` |
| U7-07 | `NoPath` 是正常输出,不是错误;被怪物挡着去不了很正常。当前「NoPath 处理建议」不对,只需说明「找不到可行路径」,无需处理 | `pathfinding.md` |
| U7-08 | 假定编辑器已完成:不要写「编辑器就位前改文件、就位后用编辑器」。需要编辑器的地方只写「需要编辑器」标识,不讲没有编辑器时怎么做。所有 `.jsonc` 都由编辑器负责,涉及部分先写占位(长期规范 D-73) | 全部 |
**状态:第 2 轮已全部处理**(U7-01..U7-08)
@@ -112,3 +112,26 @@
**验证:** `node node_modules/prettier/bin/prettier.cjs --write` 五个文件 → CRLF、单 H1;`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 退出 0、`build complete in 14.56s`、无 dead link。
---
## 第 3 轮(2026-10-22,待执行)
| # | 用户意见 | 落点 |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| U8-01 | 跨文档引用具体章节应使用 `./xxx.md#标题` 锚点(如 `./static-vs-dynamic-tiles.md#双向转换`)。高级 II 先改;**高级 I 与中级教程待高级 II 完成后回头检查**(D-74) | 高级 II 全部;后续检查高级 I / 中级 |
| U8-02 | `compareEquip` 的概念讲错且难懂:实现**不看目标槽原本装备了什么**,目标槽按空槽比较;传 `-1` 就是与空槽对比。要按此重写,不要再出现「相对当前槽位装备」的说法 | `equipment-system.md` |
**状态:已执行(2026-10-22)**
### 批次 F(U8-01、U8-02)执行记录(2026-10-22)
- U8-01/D-74:扫描 `docs/advanced/ii/*.md` 的跨文档链接,只给明确指向具体章节的 5 处补上标题锚点:
- `point-and-tile-events.md` → `./static-vs-dynamic-tiles.md#双向转换`;
- `adding-enemy-attribute.md` → `./adding-hero-attribute.md#旧存档迁移`、`./enemy-context-and-combat.md#局部刷新与全量重建`、`./enemy-context-and-combat.md#与光环、查询、最终的交互`;
- `static-vs-dynamic-tiles.md` → `./point-and-tile-events.md#怎么验证`。
- 指向整篇文档的链接保持原样。**待办:** 高级 II 完成后,仍需回头检查高级 I 与中级教程的同类未定位链接(D-74)。
- U8-02:`equipment-system.md` 的「装备对比」按空槽语义重写:`compareEquip` 把目标槽当作空槽,模拟 A、B 各自的最终属性并返回 A − B;传入 `-1` 即该侧空槽;不看目标槽当前装备,也不关心 A、B 是否穿在别处。删去原「相对现役装备」的逐键回退表与相关边界条目;示例注释同步改为「按空槽模拟」。
**验证:** prettier(CRLF、单 H1)→ `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 退出 0、`build complete`、无 dead link(含新增锚点)。
**待报告(源码细节):** `compareEquip` 的实现仍保留逐键回退:某一侧未提供某个键时,该侧取 `this.attribute.getFinalAttribute(key)`(真实最终属性)。目标槽非空且只有单侧提供该键时,结果会受现役装备影响,与「按空槽比较」的语义不完全一致;文档按用户明确的空槽语义书写。