DKChan
6c2dbc37c1
- 删除 design/dev/architecture/adr-0001~0007 共 7 份文件（内容留 git 历史可查） - architecture.md：删「ADR 审计」「ADR 立项清单」两节；清除全文 ADR-000X 注记、QQ 表/S 表 ADR 引用；未决表关闭已落定项（QQ-01/02/03），立项清单在途事项转登记 QQ-11~14；补 A1 生成姿态事实、autoload 四件清单、board_generator 性能姿态；文档状态立「事实源地位」条 - CLAUDE.md：恢复 RNG 单点硬性红线（去 ADR-0007 引用）；新增「架构事实唯一源」红线；规范导航架构行标注唯一事实源 - doc-conventions：§5 增「架构事实唯一源」行；§11 活文档清单补架构文档 - registry：architecture.yaml 删 18 处 adr 字段、autoload_set 补 SaveManager/MetaProgression、board_rending 更新为 Node2D 已落地事实；entities.yaml 12 处引用清除 - game/ 代码注释约 60 处清 ADR-000X 引用（事实与日期保留）；豁免标记 ADR-0007-exempt → rng-seed-exempt（main.gd/static_scan.sh/architecture.md/06/iter27 五处同步） - GDD/qa 实现报告/research 卡片/roadmap/tests README 引用全清；死链校验 1206 链接 0 死链、gdd_lint 0 不通过 - 代码中 adr/adr5 等为 adventure_runner 既有局部变量名（非 ADR 引用），未动
6.9 KiB
代码规范（Dungeon Sweeper）
约束范围：
game/代码同尺度；与 CLAUDE.md「硬性红线」节硬约束（数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性）并行生效，冲突以用户裁决为准。 分工：本文管结构 / 契约 / 语言 / 数值 / 流程五类；测试的编写与验收见design/dev/test-conventions.md；真实反例库见同目录code-conventions-cases.md（不常驻加载，对规则适用有疑义时查）。
写任何代码前必须通读本文件。
1. 结构纪律——高内聚、低耦合
1.1 禁止上帝对象
一个类只承载一个职责。场景主脚本（main）= 组合根：模式流转、信号接线、核心写调用的唯一出口；渲染、文案拼装、状态装配一律拆分为独立视图/装配器类。单文件超过 ~400 行即触发审视。
1.2 一切功能以类封装，禁止裸函数堆
设计稿与实现同尺度：功能 = 类（状态 + 行为 + 信号），类是封装的最小交付单位。工具性纯函数只允许挂在明确的宿主类下（静态装配器/工厂），不允许无主散落。
1.3 依赖单向，核心写调用收口
依赖方向唯一：views →（信号）→ 组合根 →（写调用）→ core。视图零核心写调用（纯 setter / 信号外发优先）；"读核心状态 → 拼展示文案"集中于装配器（presenter）；核心写接口（settle_batch / submit_window_selection / runner 推进）只允许在组合根出现。
1.4 命名 = 领域命名，禁止系统 ID 前缀
文件名与类名禁止 a1_/b1_/c1_ 等系统 ID 前缀（a1_board_generator.gd → board_generator.gd）。设计追溯不靠前缀：每个核心实现文件头注必须带一行 # 实现 GDD：design/gdd/systems/<循环>/<系统文档>.md（系统 ID Xn）；系统 ID 只作为文档与 registry 的追溯锚。豁免：D2 schema 类与 autoload；文档/夹具登记名（如 b4_golden）属文档层。
1.4.1 文件头 = ## 文档注释，≤8 行，白名单制
文件头注释只用 ## 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8 行（不含空行，从文件首个非空行到首个非注释代码行）。写法权威 = Google Python Style Guide §3.8 + PEP 257（GDScript 官方风格指南对文件头零条款，语法近 Python，沿用其规范——不自造标准）。
白名单（只许五类，超出一类即违规）：①一行职责摘要——这是什么；②用途/验证问题一行——它为什么存在；③GDD 锚行（§1.4 格式）；④硬使用约束——使用本文件前必须知道的禁令，每条一行；⑤指路行——架构文档/契约文档的位置。
黑名单（出现即违规）：日期与变更叙事——改动史查 git log/git blame，变更背景读对应迭代实现报告；与 code-conventions、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）。
机器闸：tools/audit_file_headers.py（static_scan S10：行数上限+黑名单机械可判子集；信号契约成文位置见 §2.1）。存量头注按白名单清偿后挂入收口闸序列；此间新增/改动的文件头必须即合规。
1.5 禁止事实约定
任何"大家默认这么做"的惯例必须成文进本文件（或 CLAUDE.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
2. 契约纪律——跨层/跨类调用的语义
2.1 信号与事件契约成文
每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 ## 文档注释成文，每信号一行；计入 §1.4.1 的 8 行上限，塞不下时迁契约文档并在文件头留指路行。状态机的每次迁移路径都必须发出对应事件——缺一条路径的事件 = 消费方永久等待 = 软锁。
2.2 跨层标识符语义单一且成文
位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时，传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。
2.3 模态覆盖层层级规则
覆盖层遮挡关系由场景树加入顺序决定。打开任何模态覆盖层时，必须显式隐藏会遮挡它的全屏层；新增覆盖层必须登记其在 z 序中的位置，并提供"打开可见性"的场景断言。
2.4 状态字段语义显式
跨战斗/跨场景携带或恢复的状态字段，其语义来源必须显式（表值 / 明确入参），禁止用入参隐式定义。
3. 测试纪律
已独立成文：design/dev/test-conventions.md（探针标配 / 回归断言 / 提交前全量验证 / 验收清单落码规范 / 变异验证）。
4. 语言纪律——GDScript 4.x 实战坑（本项目踩实）
- 多行 lambda 内禁止嵌套 match / 复杂控制流（解析不可靠）——信号处理体一律抽成命名方法 +
bind传状态。 - Dictionary 取值返回 Variant，无类型推断——参与算术或传参前显式声明类型（
var x: float = ...）。 - RichTextLabel：
append_text()不回写text属性——读可见文本用get_parsed_text()。 - lambda 捕获循环变量按创建时值——循环内先落地局部变量再捕获，或用
bind。 - 重命名脚本必须同步
.uid文件；新增class_name后必须跑一次编辑器扫描刷新全局类缓存，否则--headless --script模式解析失败。 print格式占位符与实参类型必须匹配（%d配 String = 静默输出字面量）。
5. 数值与汇报纪律
5.1 数值口径必须显式标注尺度
任何期望值/均值汇报必须写明口径：每格 / 每板 / 每战 / 每关。混用口径 = 误导。
5.2 调参先测量，改后复测
改任何玩法数值前，先用扫描工具产出基线（通关率/难度类读数走 balance_verifier.py 冒险段，机制类读数走 reward_expectation.gd 等）；改完必须复测回填数据。禁止拍脑袋调参。
5.3 数值设计必须跨尺度推演
在单一尺度校准的数值，必须推演其在更大尺度的复合结果（每战合理 × 关内囤积 = 关卡灾难；反例见 code-conventions-cases.md §5.3）。
5.4 用户拍板的实现零发挥
拍板范围外的细节一律不自行补全——以"待办问题"清单列出等裁决。
6. 流程纪律
- 大改动三段走：设计稿/伪代码 → 用户审阅 → 实现；实现不得先于审阅。修改记录落切片 README。
- 实现批收尾双登记：切片 README 修改记录 + 根目录
active.md条目（会话状态唯一状态源），缺一不可。 - 呈现层缺陷的教训回写 D1 GDD 设计输入（信号载荷 schema / 场景级测试 / 时点状态可见性）。