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 引用），未动
56 lines
3.0 KiB
Markdown
56 lines
3.0 KiB
Markdown
# 代码规范反面案例库（code-conventions 配套）
|
||
|
||
> 本文件是 `code-conventions.md` 各条规则对应的真实反例，说明每条规则针对什么缺陷；规则本体以规约为准，规约与本文冲突时以规约为准。不随规约常驻加载——写码前不必通读，对某条规则的适用有疑义时再查。
|
||
|
||
## 1.1 上帝对象
|
||
|
||
main.gd 曾长到 ~1100 行——棋盘渲染、HUD、结算日志格式化、四种模态覆盖层、调整板、模拟器、关卡流程全部内联；后拆分为 9 个单一职责单元（views/ + hud_presenter），main 回到 ~430 行组合根。
|
||
|
||
## 1.2 裸函数堆
|
||
|
||
供给控制器曾以裸函数伪代码呈现被否；正式实现按私有组合件 RewardSupplyController 封装。
|
||
|
||
## 1.4 ID 前缀命名
|
||
|
||
ID 前缀是跟随 GDD 文档名的事实约定，从未成文；`config_db`/`rng_service` 无前缀与 A/B/C 系列并存——两套命名并行即规范缺失。
|
||
|
||
## 1.4.1 文件头失守
|
||
|
||
main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后仍剩 31 行，约 2/3 是对 code-conventions §1.3 与架构文档的整段复制、场景结构/生命周期机制描述（对规约与代码零新信息）。
|
||
|
||
## 2.1 信号契约缺失（软锁）
|
||
|
||
旗动作花完末点 AP 后相位翻 Waiting 但不发 round_end，结算点依赖该事件 → 整局软锁；自动玩家不用旗，冒烟路径覆盖不全没抓住。
|
||
|
||
## 2.2 标识符语义错位
|
||
|
||
窗口选择契约 = 窗口条目位置，UI 却传库存数组句柄——未消耗时二者巧合相等；消耗一件后错位 → 选中件不消耗、邻件被误耗。
|
||
|
||
## 2.3 覆盖层不可达
|
||
|
||
数值调整板已实现，但打开时被不透明的开始覆盖层完全遮住 = "点击无反应"。功能存在 ≠ 功能可达。
|
||
|
||
## 2.4 状态字段语义隐式
|
||
|
||
spawn 把 hero 的 max_hp 设为入参 hero_hp——跨战斗携带 HP 时上限被压扁，恢复点/治疗包的满血守卫全部失效。
|
||
|
||
## 5.3 单尺度校准的关卡灾难
|
||
|
||
可选类 25% 格子配比在单战斗尺度校准（击杀需求 18/54），×"库存关内延续"× 5 张板复合后 = 每关 24.8 件、刀总伤 180 > Boss 130 HP——单尺度合理的参数在关卡尺度坐实灾难。
|
||
|
||
## 5.4 拍板范围外自行发挥
|
||
|
||
清图奖励被自行设计成入库刀，用户纠正为"一次性高额伤害不入库"。
|
||
|
||
## 缺陷-规范对照表
|
||
|
||
| 缺陷 | 现象 | 对应规则 |
|
||
|---|---|---|
|
||
| UI 抖动 / "第3轮"消失 | 悬停文案换行推挤侧栏，末行被挤出视口 | 1.1 拆分 + 视图定长槽 |
|
||
| Boss 战 AP 用完不结算（软锁） | 插旗耗尽末点 AP 后整局冻结 | 2.1 事件发射完整性 |
|
||
| 道具使用后不消失 | 选用件留存、邻件被误耗 | 2.2 标识符语义单一 |
|
||
| 调整板点击无反应 | 面板已实现但被开始层遮挡 | 2.3 层级规则 + test-conventions §2 |
|
||
| 上帝对象 | main.gd ~1100 行 | 1.1–1.3 |
|
||
| ID 前缀命名 | 两套命名并存 | 1.4–1.5 |
|
||
| 可选类每关 24.8 件 | 速杀退化、囤刀秒 Boss | 5.3 跨尺度推演 |
|