DKChan
7aee5eb71a
两文件是流水线流程件而非游戏描述件，此前住在 design/gdd/ 造成三处不适配： gdd_lint 必须为它们逐条关掉体裁规则、格式权威却写在 doc-conventions §12、 与同族的 roadmap（在仓库根）分居两处。迁到根后按 roadmap.md 的无编号风格改名。 - 迁出：design/gdd/06-待办清单.md → 待办清单.md；07-体验验证清单.md → 体验验证清单.md - 指向改写 53 个文件：GDD 各系统文档指路存根、四份规约、02 根索引、README/roadmap/AGENTS - 两份清单自身 74 处出站链接按新基址重指（../art → design/art、systems → design/gdd/systems） - gdd_lint：待办/体验验证两文件的 R1/R3/R5/R7 豁免行随迁删除（已脱离扫描面），后门表清零 - pipeline_gate 默认路径、log_analysis/render_gate 称谓、repo_structure_audit 根文件白名单同步 - 保护面补写：两份清单列入实现批禁写清单（AGENTS 两类批条 / process-conventions §12 / 架构文档域表）， 条目状态只由流水线各段推进 - 范围外未动（用户令「全不碰」）：reports/ 与 design/research/ 的 22 处历史指向、game/ 两处注释
54 lines
6.6 KiB
Markdown
54 lines
6.6 KiB
Markdown
# 概念与引用规范（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. 归档与事实源
|
||
|
||
- 旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：已退役机制禁止作为现行机制引用）。
|