# 代码规范反面案例库（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 跨尺度推演 |