docs(10-20): 修订模板结构与注释（用户第5轮）

docs/advanced/data-stores.md

@@ -6,9 +6,17 @@
 
 阅读前需要会基础语法：`class`、`new`、`Map`、`import`。
 
-## 先看读模板
+## Store 是什么
 
-五个 Store 都是 `state` 上的只读字段，没有各自的管理器，也不需要你 `new` 一个出来。日常使用基本就是下面这些读法：
+Store 里存的是「定义」，游戏里跑的是按定义构造出来的「实例」。图块定义告诉你这个数字代表什么地形、能不能走，真正的图块对象则在楼层加载时按定义创建。
+
+Store 是查表用的注册表，不进存档。勇士、地图、Flag 这些游戏状态才进存档；读档不会把 Store 退回原样，也不会恢复你运行期对它的改动。
+
+运行时读 Store 是正常操作：查表、算数、拼提示文本、给界面提供数据都可以。运行时写 Store 会绕过加载、存档与录像这一整套机制，问题会在不确定的时机表现出来。
+
+## 读 Store 的示例
+
+五个 Store 都是 `state` 上的只读字段，没有各自的管理器，也不需要你 `new` 一个出来。它们不是需要你实现的模板——接口已经由 `data-common` 提供，你只需要调用。如果你想在代码里读这些定义，可以参考下面的示例：
 
 ```ts
 import { ICoreState } from '@user/data-state';
@@ -18,11 +26,13 @@ export function readStores(state: ICoreState): void {
     // 图块：先按 id 查数字，再取完整定义与类型
     const tileNum = state.tileStore.num('my-tile');
     if (tileNum !== undefined) {
+        // getData 返回定义，getType 返回逻辑类型
         console.log(state.tileStore.getData(tileNum));
         console.log(state.tileStore.getType(tileNum));
     }
 
     // 道具与怪物：数字或 id 都接受
+    // getData / getEnemy 返回定义本身，不是副本
     const item = state.itemStore.getData('my-item');
     const enemy = state.enemyStore.getEnemy('my-enemy');
 
@@ -34,45 +44,37 @@ export function readStores(state: ICoreState): void {
 }
 ```
 
-下面先说明 Store 与实例、存档的区别，再逐个讲每个 Store 存什么、能做什么。
-
-## Store 是什么
-
-Store 里存的是「定义」，游戏里跑的是按定义构造出来的「实例」。图块定义告诉你这个数字代表什么地形、能不能走，真正的图块对象则在楼层加载时按定义创建。
-
-Store 是查表用的注册表，不进存档。勇士、地图、Flag 这些游戏状态才进存档；读档不会把 Store 退回原样，也不会恢复你运行期对它的改动。
-
-运行时读 Store 是正常操作：查表、算数、拼提示文本、给界面提供数据都可以。运行时写 Store 会绕过加载、存档与录像这一整套机制，问题会在不确定的时机表现出来。
+这个示例只做读取：图块先换算数字，再取定义与类型；其余四个 Store 按各自的键直接查询。返回的不是副本，下面逐个讲每个 Store 存什么、能做什么。
 
 ## tileStore：图块定义
 
-存的是图块的原始定义：图块数字、字符串 id、默认事件、逻辑类型、四方向通行性，以及事件是撞上去触发还是走上去触发。以图块数字为键。
+每条记录是一个图块的原始定义，以图块数字为键。定义里包含：图块数字本身；字符串 id，供数据里按名字引用；默认事件表，键是事件优先级、值是事件 id；图块逻辑类型，例如地形、动画、道具、怪物、NPC、自动元件；四方向通行性；以及 `eventPass`，它决定触发器的触发方式——`false` 是撞上去触发，`true` 是走上去触发。
 
-它能按数字取完整定义、默认事件和类型，也能在图块数字与字符串 id 之间换算。登记新定义用 `addTile`；数字或 id 与已有定义冲突时会告警（错误码 `133` / `134`）并覆盖。
+接口方面，它能按数字取完整定义、默认事件和类型，也能在图块数字与字符串 id 之间换算。登记新定义用 `addTile`；数字或 id 与已有定义冲突时会告警（错误码 `133` / `134`）并覆盖。
 
 ## itemStore：道具定义
 
-存的是道具的原始定义：图块数字、分类、名称、描述、是否在道具栏隐藏、使用 / 拾取效果，以及装备数据。以道具图块数字为键。
+每条记录是一个道具的原始定义，以道具图块数字为键。定义里包含：图块数字；道具分类（永久、一次性、即捡即用、装备）；显示名称与描述文本；是否在道具栏中隐藏；以及两个效果字段——`effect` 描述使用或拾取时做什么，`equip` 描述装备后的槽位、动画、数值与百分比加成。两个字段都是必填。
 
-它能按数字或 id 取整份定义，也能只取分类。登记用 `addItem`；同一个图块数字重复登记会告警（错误码 `181`）并覆盖。
+接口方面，它能按数字或 id 取整份定义，也能只取分类。登记用 `addItem`；同一个图块数字重复登记会告警（错误码 `181`）并覆盖。
 
 ## mapStore：地图原始数据
 
-存的是地图的原始数据：楼层 id、地图宽度、每一层的图块矩阵、每个图层的字符串别名，以及每个图层指定位置上的事件。以楼层 id 为键。
+每条记录是一张地图的原始数据，以楼层 id 为键。记录里包含：楼层 id、地图宽度、每一层的图块矩阵、每个图层的字符串别名，以及每个图层指定位置上的事件。
 
-它能按楼层 id 取整份原始数据。登记用 `addMap`；同一个楼层 id 直接覆盖，不告警。
+接口方面，它能按楼层 id 取整份原始数据。登记用 `addMap`；同一个楼层 id 直接覆盖，不告警。
 
 ## enemyStore：怪物定义
 
-存的是怪物的原始定义：图块数字、怪物属性，以及特殊属性的编号与参数。以怪物图块数字为键。
+每条记录是一只怪物的原始定义，以怪物图块数字为键。定义里包含：图块数字、怪物属性模板，以及特殊属性的编号与参数值。
 
-它能按数字或 id 取整份定义。登记用 `addEnemy`；同一个图块数字重复登记会告警（错误码 `181`，与道具共用）并覆盖。
+接口方面，它能按数字或 id 取整份定义。登记用 `addEnemy`；同一个图块数字重复登记会告警（错误码 `181`，与道具共用）并覆盖。
 
 ## eventStore：事件实例
 
-存的是事件实例本身，不是事件定义。以事件 id 为键。
+存的是事件实例本身，不是事件定义。每条记录以事件 id 为键，取回的就是当初登记的那个对象。
 
-它能按 id 取回存储的那个实例，不是副本。登记用 `addEvent(id, event)`，第一个参数是事件 id，第二个才是实例；重复 id 会告警（错误码 `170`）并覆盖。
+接口方面，它能按 id 取回存储的那个实例，不是副本。登记用 `addEvent(id, event)`，第一个参数是事件 id，第二个才是实例；重复 id 会告警（错误码 `170`）并覆盖。
 
 ## 为什么运行期只读