DKChan
bbd49abfb0
- 术语表 v1.13：GP 唯一正式命名（删「局内金币」别名）＋旗/控制词条更名封印/控制＋封印定性由「插旗的对外表达」更正为正式动作名（全库统一、非比喻）＋禁用字面从对外命名扩为全库＋删「机制文档内部用语不受限」条款＋退役词对照表补三行（金币→GP/插旗→封印/旗→封印印记）＋危险格词条「被旗控制」→「被封印控制」＋B3 豁免例举去旗 - 机检扩容 tools/doc_term_audit.py：RETIRED_TERMS 新增 金币→GP、插旗|标旗→封印 两行（DEFAULT_DIRS 不变，game/ 扫描归代码批）；拔旗|撤旗行继任措辞随批换代（插旗不可逆→封印不可逆） - GDD 全域正文换代约 200 行/31 文件：金币→GP（金币袋→GP 袋）、插旗/标旗→封印、雷格/惩罚格→危险格（2026-10-11 退役批存量补扫）、旗概念→封印印记（旗判定→封印判定/标中旗→封印标中/标错旗→标错封印/旗格→封印格/旗位→封印位等复合词系）；00-游戏概念「封印降级为类型风味词」定性翻转；修订记录/版本历史/禁令引举/更名记载等留档行零动 - registry/entities.yaml（信标网络可达性/事件序/回执驱动三处）＋art 五件（art-bible 封印印记六处/comfyui 背旗→背负封印印记/两清单）＋dev 七件（architecture 旗集→封印集/code-conventions-cases/test-conventions/架构图 html json 四件）随批换代 - tools 四脚本注释与图内标注换代（clear_dominance_audit/render_sample_sheet×2/analyze_playtest；代码标识符零动归代码批） - design/qa/代码术语审计报告-2026-10-18.md 随批入库（本批参考素材，06:578 引用闭合 doc_link 死链） - 06-待办清单/术语表两在途脏件（代码术语批 06 登记＋A 表头「不用→禁用」）随批一并入库 自检：doc_term_audit --strict 零疑似现行（45 文件 434 命中全留档类）；文档域六闸验收通过无新增红（gdd_lint R3 对 00 正文修订注记一次打回已去注记化改写；doc_link 死链经报告入库闭合）；正文残留仅 06:73「拔旗」一处（件派生动词白名单豁免语境、机检同款豁免，设计意图记录不动）
56 lines
3.1 KiB
Markdown
56 lines
3.1 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 跨尺度推演 |
|