6.6 KiB
概念与引用规范（Dungeon Sweeper）
约束范围：设计文档的概念建模与跨文档引用。写作层（句子、结构、骨架）归
design/engineering/doc-conventions.md；本文管概念怎么切、文档怎么互链。 概念只在 owner 文档里定义一次；跨系统术语的规范名、定义与互斥关系登记在design/gdd/术语表.md。某概念被谁引用，靠全仓搜索它的规范名得出，不设第二处登记表。
定文档方案前必须通读本文。
1. 概念封装纪律（概念对象化建模）
定方案前先做概念建模：像写代码划分对象那样，把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则，概念之间靠显式关系（包含、挂载、引用）连接，而不是把所有内容揉进一个概念里。概念没有边界，删除修改就得全仓翻找。
| 规则 | 内容 |
|---|---|
| 概念即对象 | 核心概念各自独立成体，有规范名、有属性、有规则边界；下笔前先能用一句"它是谁、它管什么"说清，说不清就是还没想完 |
| 属性归属唯一 | 每个属性只归一个概念——离开 A 就没有意义的属性写在 A 名下，禁止上提给容器、也不下压给成员 |
| 包含关系显式写 | 容器与成员的关系明文写出谁是容器、谁是成员、一对几（例：棋盘包含多个格）；禁止让读者从散文里反推结构 |
| 概念状态用枚举 | 概念的类型与状态写成封闭枚举并列全成员（例：格的类型 = 安全格 / 危险格，格的状态 = 未开 / 已开）；禁止用散文形容词零散罗列状态 |
| 附加物独立成对象 | 挂在概念上的附加内容若自己有一组属性或规则要写（例：格上的奖励/惩罚 = 格面资源），就是独立对象——父概念只保留挂载位（如"有无资源资格"），禁止把附加物摊平成父概念的一堆属性字段 |
| 关系不吸内容 | 概念间关系只写"有没有关系、是什么关系"；对方的属性与规则留在对方名下——与第 2 节"引用不转述"同源 |
| 落位五要素 | 概念的权威文档必须写全五要素：定义（它是什么）/ 作用对象与范围（作用在谁、什么范围内有效）/ 生命周期（何时出现、何时变化、何时消失、怎么重置）/ 关联（与谁衔接、边界归谁、哪些指路别处）/ 状态（已定稿/待实施/已退役）。缺任何一项都是半成品概念，如同对象缺了构造函数 |
切分正例（现行排雷循环即按此切分）：棋盘是地图级对象，包含多个格；格是成员对象，危险格/安全格是它的枚举属性；格上可能挂的奖励或惩罚（格面资源）是独立对象，本体与规则归地图战斗资源与战斗结算，格只保留"有无资源资格"一个挂载位。反面基准：把奖励的类型、数值、极性全摊开写成格子的属性字段——奖励规则一改，棋盘文档就得跟着改，这便是没封装。
无权威文档，不下定义：一个概念还没有权威文档时，任何其他文档都禁止替它下定义——只能引用概念名，并在 待办清单.md 登记「待落位」；谁先立权威文档，谁拿走全部定义权。（反例：某概念长期无权威文档，art-bible 复述、待办清单登记、需求卡片摘要三处各自给出口径，范围限定词在层层复述中丢失，最终放大成「全板常显」的错误事实。）
与引用纪律的关系：第 1 节管单个概念的边界与归属（概念级封装），第 2 节管概念之间、文档之间的引用（跨文档解耦）——先有封装，第 2 节的单点定义、反向边与删除 SOP 才有干净的作用对象。
2. 引用纪律（跨文档高内聚低耦合）
目标：修改或删除一个概念时，只改它的 owner 文档；引用方最多删掉一个链接。反例模式：同一概念多名并存、机制被织进多份文档的规则正文——删除时全仓几十处文字修改与大量事后一致性复查。
| 规则 | 内容 |
|---|---|
| 单点定义 | 每个概念只在 owner 文档里定义一次，其规范名与定义收进 design/gdd/术语表.md |
| 规范名唯一 | 正文只准用规范名，禁止别名散开——否则删除时 grep 搜不全 |
| 引用不转述 | 跨文档引用 = 规范名 + 链接，禁止复述对方的规则细节、公式、数值与口径；确需携带口径时，作用对象/范围/生命周期必须随句写全或显式指路——禁止只复述形容词，「常显」「恒亮」这类词不带范围就是半句话；若发现自己需要一条规则，那是自己的概念，先立权威文档再定义 |
| 引用落到对外承诺 | 跨文档链接只锚到对方文档明示的对外内容（事件、接口、规则条目），不锚其内部细节 |
| 依赖逐条列出 | 系统文档的「依赖与输出」节逐条列出本系统依赖的他人概念（规范名 + 链接）——这份清单就是删除概念时的影响面清单 |
| 引用可查 | 需要某概念的影响面时，全仓搜索它的规范名即得；被引方在自己的「依赖与输出」节写明谁依赖它。人工维护的反向边清单已废止（2026-10-19 核出旧登记漏 7 份、多 1 份） |
| 链接断了也好读 | 引用处的句子在链接失效后仍通顺完整（写"变异规则见《地形变异》"，不把半截语义挂在链接里） |
| 待办单点登记 | 全项目待办事项单点登记于 待办清单.md：系统文档的「待办」节只留指路存根，禁止自建条目表；新增待办条目直接登记清单，裁决后改「状态」列留痕、不删条目 |
引用格式：一律 Markdown 相对链接，指向文件、必要时带节锚点（例：[地形变异 · 变异类型](systems/排雷循环/地形变异.md#变异类型)）——机械可查，死链可被工具检出。
删除概念 SOP：① 全仓搜索该概念的规范名，得到影响面清单 → ② owner 文档删除概念 → ③ 纯引用方删链接即完事；机制被织入对方规则的，按清单逐处修订 → ④ 收尾跑一遍死链检查，全绿即干净。
诚实边界：机制耦合无法靠删链接消灭——别人的规则真的因你的概念而改变时，改内容不可避免。引用纪律保证的是：这类修改有一份现成清单（反向边 + 依赖节），不用事后全仓搜索。
3. 归档与事实源
- 旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：已退役机制禁止作为现行机制引用）。