game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(迭代27 T6+T7): 波五b 卫生件包+文档同步闸——对拍全同

Browse Source 
T6 卫生件（P2 组收口）:
- 死代码 13 函数删除（审计 16 处复核=ui_kit:486 实读现役不删，追认单#14）+FeatsEngine
  整文件退役（class_name 注销）
- 字符串 Callable×10 位→方法引用形态（编译期方法存在性校验；语法实证 METHOD_REF=true）
- 状态机 enum 化: adventure State（外部 String 契约 getter 词表逐位一致+外部纯读实证）/
  standee HeroState（register/set String 形参零变化+probe 面恒等）
- ConfigDB _fatal 退出归根（核心层去 quit/crash→_fatal_flag，决策归组合根 fail-fast 通道）
  +resolver 诊断/数据通道全面 Callable 化（ConfigDb↔Resolver 类型环断根）

T7 文档同步闸:
- 实现报告 design/qa/iter27-实现报告-2026-10-14.md（五波+闸表+追认单十五项+反哺点两条+目检五件）
- 06 迭代 27 条销号+GDD 反哺点两条新条；07 ㉖ 目检节+v1.0 版本行；roadmap ✅ 换代
- 审计报告本体按退役规则 git rm（吸收即死；修正计数由卡片承载）；卡片来源行改指路

闸: 对拍三变体全同（第五跑）+冒烟 1081/0+run_all 27 套+probe click+render golden+static_scan 全绿
This commit is contained in:
DKChan committed 2026-10-15 01:41:37 +08:00
1 parent b605022001
commit eea345882b
24 files changed
+200 -309
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

design/gdd/06-待办清单.md
+9 -4
View File
@@ -593,13 +593,18 @@
**状态**：备忘（不阻塞，不排期）
---
#### 代码架构技术债修复批——需求卡片已写（2026-10-14 登记）
#### 迭代 27 代码架构技术债修复批——GDD 反哺点两条（2026-10-14 随批登记，待用户逐点裁决另批落文）
**现状**：[代码架构与实现质量审计报告-2026-10-14](../research/代码架构与实现质量审计报告-2026-10-14.md)（双席审计，基线 97de02c；同日第三方逐条复核：主体结论全部成立，五处计数级瑕疵已修正落文）确诊 2 条 P0（全产品单场景/局态手工复位清单）+ 6 条 P1（_settle 巨函数 259 行/刷新双账/GP 影子账/共享可变字典跨三层/组合根不可测/类型闸缺位）+ 7 组 P2 卫生件。用户已裁：全部技术债修复允许放行单一大迭代（12-14 个工作日，2026-10-14 裁决记录）。需求卡片=[需求卡片-代码架构技术债修复批-2026-10-14](../research/需求卡片-代码架构技术债修复批-2026-10-14.md)（**v1.2**，五波：场景拆分+局生命周期 → _settle 拆段 → 账本收口 → 组合根抽取+模态内聚 → 类型闸+卫生件；核心验收=重构前后同种子完整局输出逐位一致）。
**现状**：五波全量入库（单会话交付；逐位一致对拍三变体五跑全同；实现报告=design/qa/iter27-实现报告-2026-10-14.md）。实现与设计权威文档的差异/缺口如下，经裁决后另批落文——**机械面随批已动的只有本条与 07/roadmap**。
**归属**：工程债/重构批（core/presentation 结构面；零行为变更契约）
**归属**：工程债/重构批收口反哺（不阻塞，不排期）
**状态**：**🔄 U0 已开工（2026-10-14 用户令编入迭代 27 卡①+同日 /goal+iter 27 发令）**——卡片 v1.2 三点已裁全按推荐案（①SaveManager/MetaProgression=第三个 autoload／②Ledger=单类持四账／③_settle=审计五段），零待裁点；批入库后本条销号
| # | 文档 | 反哺点 |
|---|---|---|
| 1 | design/dev/architecture/architecture.md + ADR 系列 | 场景分层（三屏壳+组合根句柄面）/会话生命周期（RunScope 物化）/结算五段 Segment（core/settlement/）/RunLedger 四账所有权/ModalFlow 模态编排层与互斥域 tags 协议——现行陈述滞后于实态 |
| 2 | design/dev/code-conventions.md | §4 语言纪律机器化（S9+audit_type_hints.py 三规则）；`:= {}` 推断形态豁免口径；`# type-hint: ignore` 行级白名单与 `# ADR-0007-exempt` S1/S2 标记豁免通道；--script 模式禁裸 autoload 标识符纪律（新）；Variant 参数化口径与元素精化后续 |
**状态**：备忘（反哺点待裁决；代拍板追认单十五项见实现报告 §三；残留人闸=07 ㉖ 五件登记不阻塞）
design/gdd/07-体验验证清单.md
+14
View File
@@ -264,3 +264,17 @@
| v0.7 | 2026-10-13 | 新增 ㉓ 敌人表内容修批三观测目检节（迭代 24 卡①随批登记：新招可见性/甲型体感/第一关节奏——登记不阻塞按 2026-10-12 真人检测立规） |
| v0.8 | 2026-10-13 | 新增 ㉔ UI 全局主题批全屏巡检目检节（迭代 25 卡①随批登记：引擎默认灰清零巡检/音量滑轨两段可辨/专项观察点二（滑轨柄抢焦点·滚动条槽可见性）/预盖件无实役注记——登记不阻塞；能力验证半=冒烟 V1-V6） |
| v0.9 | 2026-10-14 | 新增 ㉕ UI 交互与观感批逐屏巡检目检节（迭代 26 卡①随批登记：按钮五态反馈/键盘焦点环/全局 Nearest 巡检（含暗角与渐变白名单判据）/布局均衡（商店居中+营地四栏等高）/诊断钮清零——登记不阻塞；能力验证半=冒烟 V1-V6+T4 结构断言） |
| v1.0 | 2026-10-14 | 新增 ㉖ 代码架构技术债修复批全流程走查目检节（迭代 27 卡①随批登记：全流程观感零变化走查/续玩断点恢复/调试浮窗对局中可开不锁棋盘〔:407-408 事故回归〕/刷新余量显示一致/DS_DEBUG 启动浮窗+两屏角标——登记不阻塞；能力验证半=冒烟 V1-V9+parity 三变体逐位一致对拍五跑全同） |
## ㉖ 代码架构技术债修复批——全流程走查（迭代 27 卡①随批登记；能力验证半=冒烟 V1-V9+parity 三变体逐位一致对拍五跑全同）
> 场景拆分+会话物化+战斗域重构+账本收口+模态协议内聚后，玩家可见面唯一验收=观感零变化。登记不阻塞（2026-10-12 真人检测立规）。
| # | 目检项 | 判据 |
|---|---|---|
| 1 | 全流程走查 | 开始菜单→营地四柜台→开新冒险→选路→战斗（挖/旗/刷新/停手）→三选一→商店→Boss→终局——逐屏观感与重构前一致（演出时序/文案/布局零漂移） |
| 2 | 续玩断点恢复 | 停点退出→「继续上局」文案与恢复落点正确（run-scope 物化后断点链回归） |
| 3 | 调试浮窗对局中可开不锁棋盘 | 对局中开浮窗→棋盘可继续操作（:407-408 永久锁死事故回归——互斥域 tags 化后钉面） |
| 4 | 刷新余量显示 | 刷新受理后 HUD 余量递减且与受理次数一致（双账删副本后 HUD 单源读快照） |
| 5 | DS_DEBUG=1 启动 | 浮窗启动即开+两屏角标点亮可点（同步面随 ModalFlow 迁移后行为钉面） |
design/qa/iter27-实现报告-2026-10-14.md
+93
View File
@@ -0,0 +1,93 @@
# 迭代 27 实现报告——代码架构技术债修复批（五波全量入库）
- 日期：2026-10-14（单会话 /goal+iter U0 交付，worktree g-plan2-iter27-techdebt 分支 iter27-techdebt-20261014）
- 需求卡片：`design/research/需求卡片-代码架构技术债修复批-2026-10-14.md`（v1.2——三点待裁 2026-10-14 用户三裁全按推荐案：①SaveManager/MetaProgression=第三个 autoload／②Ledger=单类持四账／③_settle=审计五段）
- 来源审计：代码架构与实现质量审计报告-2026-10-14（双席基线 97de02c；**本批收口时按退役规则 git rm——吸收即死，结论迁本报告与卡片**）
- 核心验收（V1）：**重构前后同种子完整局输出逐位一致**——parity_anchor 三变体（base/attune/shop）×40 局×RUNSUM+JSONL 剔 ts 双面哈希对拍，**五波出口五跑全同**（锚冻结于 T0，种子面 71000/72000/73000）
## 一、五波交付
### 波一 场景拆分＋局生命周期物化（P0-1/P0-2，7a0d57d）
- 三屏壳场景 `presentation/scenes/`：menu_screen／camp_screen／adventure_screen（内含 level_map/battle 两容器）——视图代码原样构建（装配器/视图类零 .tscn 化，契约 2）；组合根句柄全部保留（探针挂载假设 main.X 一级路径零迁移）；树序=屏壳在前全模态之下（视觉共存对逐对验算：legend/battle、debug/level_screen、shop/level_screen 等全部保序）。
- 会话物化 `run_scope.gd`：adventure/runner/settlement/局态旗/账本随会话节点承载；`_begin_session` 建会话（_ready 即建闲时态=永非 null）、终局整节点 queue_free()——`_reset_run_scope` 三项+`_on_battle_end_continue` 置空四件手工清单消亡。
- SaveManager/MetaProgression 升格 autoload（裁点①甲；类名加 Core 后缀沿 RngService 先例）；探针隔离改 attach_path 原地重置（set_master_seed 先例）；**发现并修复**：屏壳根全屏 Control 默认 STOP 吃掉下层模态鼠标输入（ui_input 实证）——三屏壳根 mouse_filter=IGNORE+V2 回归闸。
- V2 屏壳独立实例化 11 断言＋V3 两连局复位 11 断言进 smoke。
### 波二 _settle 五段拆 Segment（P1-1，26301ba）
- `core/settlement/` 五段类：GrantSegment（授予段体+旗判随段迁入+counter_add 五位/grant_material 三位分支单点化）/AuraSegment/CombatSegment/DecaySegment/VerdictSegment（返回裁定，终局早退语义留宿主）；编排器 1725→1325 行退为段序编排+行发射原语单点。
- 姊妹病灶：`_resolve_hero_attack` 148 行拆四步（ctx 命中面→基值装配→掷点兑现→交付），ctx/redemption 字典穿线算序逐字保留。
- V4 settle_segments_test 16 断言进 run_all。
### 波三 账本收口（P1-2/P1-3/P1-4，6fd7d78）
- `core/run_ledger.gd` RunLedger 单类持四账（裁点②甲）：attune_charges/vision_counter/adventure_counters/bonus；战斗侧只拿 read/append 原语；AR 持账→LR set_run_ledger→enc 单键下传；编排器三裸引用成员退役；调试/单场缺省新账=零扰动面（vision_counter 缺省空=不计，原 enc 缺键守卫语义保留）。
- 刷新双账：main 副本删除；presentation_snapshot 成文面升键 refresh_used（can_refresh 邻位）——HUD 余量/遥询单源读快照；V5 快照一致性断言×3。
- GP 影子账：summary 增 gp_final 键（close_wallet 清账前快照）；gp_shadow_ledger.gd 全件退役；终局面板 GP 行取数=summary 键；ui_probe 断言换代。
### 波四 组合根可测化＋模态协议内聚（P1-5/P2-7，8b9e556）
- **重估结论（卡片 T4 前置义务）**：场景拆分落地后，模式状态机已随 RunScope 物化、屏构建已随屏壳迁出——抽取面收敛为**模态编排域**：`modal_flow.gd` ModalFlow 纯逻辑类（依赖仅 ModalStack+查询 Callable，审计处方形态）——开合编排（挂起兜底/排播排空/遮挡记账/开合同步）/输入锁谓词（三例外注入）/双形制角标谓词。
- **V6 测试抓出并修正一处真分歧**：挂起兜底递归后误加 return（原 main 语义=先结挂起后继续开本层两拍都走）——单测缝的结构价值实证。
- ModalStack 互斥域随层登记：register(m, tags)+TAG_NON_LOCKING/TAG_SCREEN_STATE 封闭词表+has_open_excluding_tags 组查询；原调用点排除式拼装（:404-409 输入锁等五处）退役；main._modals=flow.stack（ui_struct _list 断言缝保留）。
- 控制器构造收拢 context：curio 16 参→CurioFlowContext／camp 13 参→CampFlowContext（字段逐一同名，控制器可独立实例化）。
### 波五 类型闸＋卫生件（P1-6/P2 组，b605022＋T6 笔）
- 类型闸：`tools/audit_type_hints.py` 机器闸（R1 无类型容器注解/R2 有值返回缺类型/R3 参数缺类型+行级白名单通道）；368 处容器注解机械参数化（Array[Variant]/Dictionary[Variant, Variant] 零行为面）、13 处参数真类型；project.godot 拉起 untyped_declaration=1；static_scan 新 S9 规则。
- 卫生件：死代码 13 函数删除（审计 16 处复核后其中 ui_kit:486 一处经实读为现役非死码，见追认单）+FeatsEngine 整文件退役；字符串 Callable×10 位换方法引用形态（编译期方法存在性校验）；冒险状态机/standee 主角三态 enum 化（外部 String 契约逐位一致）；ConfigDB `_fatal` 退出归根（核心层去 quit/crash，置 `_fatal_flag`，退出决策归组合根既有 fail-fast 通道）+resolver 诊断/数据通道全面 Callable 化（ConfigDb↔Resolver 类型环断根）。
## 二、闸记录（每波出口+批末）
| 闸 | 基线（T0 冻结） | 波一 | 波二 | 波三 | 波四 | 波五 |
|---|---|---|---|---|---|---|
| 逐位一致对拍（V1 核心） | 锚冻结 | ✓ 全同 | ✓ 全同 | ✓ 全同 | ✓ 全同 | ✓ 全同 |
| 冒烟 | 1055/0 | 1077/0 | 1077/0 | 1079/0 | 1079/0 | 1081/0 |
| run_all | 25 套 | 25 | 26 | 26 | 27 | 27 |
| probe_gate --click | 绿 | 绿 | 绿 | 绿 | 绿 | 绿 |
| render_gate golden | 0.00% | 0.00% | 0.00% | 全绿 | 全绿 | 全绿 |
| static_scan | （历史 cd 错位恒跳过） | — | — | — | — | S1/S2/S4/S9 全绿 |
批末（T6 后）run_all 27 套全绿+冒烟 1081/0+probe/render 全绿+对拍全同（T6 对拍见 /tmp/parity_check6.log 记录，exit 0）。
## 三、代拍板追认单（白名单九项执行实录+计划外决断，待用户逐项追认）
1. **屏场景命名/落位**（白名单①）：`presentation/scenes/{menu,camp,adventure}_screen.tscn`——三屏壳与卡片三屏一一对应。
2. **屏壳内部分层**（白名单②）：adventure 屏壳内 battle_root+level_screen 平级（无同时可见态，层内先后零视觉差）。
3. **Segment 五类命名/落位**（白名单③）：`core/settlement/{grant,aura,combat,decay,verdict}_segment.gd`，类名 XxxSegment。
4. **Ledger 命名/原语形状**（白名单④）：`core/run_ledger.gd` RunLedger；原语=attune_charge_has/set/consume、vision_count_add、counters_seed_snapshot/merge_export、bonus_add_axis（各站点原语义逐字收拢）。
5. **run-scope 物化形态**（白名单⑤）：RunScope Node 挂 main；_ready 即建闲时态（永非 null——全组合根免空判）；会话更替=旧节点 queue_free+新节点同拍建。
6. **探针迁移最小改动**（白名单⑥）：组合根句柄保留策略使 10 探针中 7 个零迁移、3 个仅 run_scope 路径换代；pacing 测试改 attach 隔离。
7. **类型标注写法**（白名单⑦）：368 处机械参数化取 `Array[Variant]`/`Dictionary[Variant, Variant]` 零行为面口径——**元素精化（如 Array[Dictionary]）留后续批渐进**（机器闸已封住新增无类型）。
8. **死代码删除切分**（白名单⑧）：随 T6 单笔提交。
9. **enum 命名**（白名单⑨）：adventure `State`/standee `HeroState`（+_HS_NAME/_HS_VALUE 双向映射常量）。
10. **〔计划外〕P2-2 autoload 直取降格实现**：审计处方「编译期全局名」与本仓 --script 模式编译器不解析裸 autoload 标识符**硬冲突**（run_all.gd 头注在案+pacing 实测 Parse Error）——降格为路径常量单点（AUTOLOAD_PATH_* 四常量）+T1 读视图属性；拼写风险收敛一处，类型面保留。
11. **〔计划外〕board_generator 四 db 参白名单**：generate/_attempt/legality/_finalize 的 db 参保持鸭子型（测量面 _BoardRowStub 冒烟夹具注入，typed 参拒 stub）——`# type-hint: ignore` 显式白名单通道首用。
12. **〔计划外〕static_scan 历史 cd 错位修复**：9-24 布局迁移后 `dirname/..` 落 game/ 致 `game/core` 守卫恒跳过=静默空转遗产——修 `/../..` 后 S1-S4/S9 首次实跑，暴露并处置两笔存量（S1/S2 main `_seed_value` randi=ADR-0007 文档化豁免面→标记豁免通道；S9 即本批闸）。
13. **〔计划外〕V6 测试抓出挂起兜底分歧**：ModalFlow 初版在挂起兜底后误加 return（原 main 语义两拍都走）——以原语义为准修正；该处即单测缝价值的直接实证。
14. **〔计划外〕审计「死代码 16 处」复核为 13 处**：ui_kit.gd:486 一处实读为现役代码（审计抽样误差），不删；其余 12 函数+FeatsEngine 整文件照删。
15. **〔计划外〕刷新遥测取数面换代**：`ux_refresh_attempt` 的 round_refresh_index 从 main 副本改读快照（P1-2 连带，载荷键与数值语义零变化）。
## 四、GDD 反哺点（两条，已登记 06，待用户逐点裁决另批落文）
| # | 文档 | 反哺点 |
|---|---|---|
| 1 | design/dev/architecture/architecture.md + ADR 系列 | 场景分层陈述（三屏壳+组合根句柄面）；会话生命周期（RunScope 物化+_begin_session/_end_session 语义）；结算五段 Segment 结构（core/settlement/）；RunLedger 四账所有权模型；ModalFlow 模态编排层与互斥域 tags 协议——architecture 现行陈述均滞后于实态 |
| 2 | design/dev/code-conventions.md | §4 语言纪律机器化（S9+audit_type_hints.py 三规则）；`:= {}` 推断形态=类型推断合法面不算债的口径；`# type-hint: ignore` 行级白名单通道；`# ADR-0007-exempt` S1/S2 标记豁免通道；--script 模式禁裸 autoload 标识符纪律（新）；Variant 参数化口径与元素精化后续 |
## 五、实机目检总清单（登记 07 ㉖——真人检测不阻塞，2026-10-12 立规）
1. 全流程操作观感零变化走查：开始菜单→营地（四柜台）→开新冒险→选路→战斗（挖/旗/刷新/停手）→三选一→商店→Boss→终局逐屏过一遍（场景拆分+会话物化后唯一人闸面）。
2. 续玩断点恢复：停点退出→继续上局（断点文案/恢复落点）。
3. 调试浮窗对局中可开不锁棋盘（:407-408 事故回归——互斥域 tags 化后行为钉面）。
4. 刷新按钮余量显示与受理一致（双账删副本后 HUD 单源读快照）。
5. DS_DEBUG=1 启动即开浮窗+两屏角标（同步面随 ModalFlow 迁移）。
## 六、残留与去向
- 残留人闸：07 ㉖ 五件（登记不阻塞）。
- 代拍板追认单十五项（上表）待用户逐项追认。
- GDD 反哺点两条（06 在册）待裁决另批落文。
- 审计报告本体已按退役规则 git rm（吸收即死；修正后计数已由需求卡片 v1.2 承载）。
- 元素精化（Array[Variant]→具体元素型）为类型闸后续渐进面（06 反哺点②附带）。
design/research/代码架构与实现质量审计报告-2026-10-14.md
-132
View File
@@ -1,132 +0,0 @@
# 代码架构与实现质量审计报告（2026-10-14）
**审计对象**：`game/` 目录全部实现（约 114 个 GDScript 脚本 / 3.4 万行，不含 tests）
**审计方法**：godot-master 技能库（GD-Agentic-Skills 的本地镜像，Godot 4.7+ 专家知识库）双席审计——甲席走 Analyst 工作流审架构，乙席走 Auditor 工作流审实现规范与设计模式；两席均为**只读静态实读**，未运行游戏。实现席实跑了技能库自带扫描器（信号审计 / 类型标注审计），内存类扫描器需 Godot 运行时，按只读纪律跳过并注明。
**审计日期**：2026-10-14（基线 master 97de02c）
**基线事实**：全项目真实游戏场景只有 1 个（`presentation/main.tscn`，其余 13 个 .tscn 全在 smoke/ 下是测试探针）；节点几乎全部由 GDScript 程序化构建，产品代码 `instantiate()` 调用数为 0；autoload 仅 2 个（ConfigDB / RngService）；目录分层 core / data / presentation / assets / tests / smoke。
---
## 总评
**core 层实现质量显著高于垂直切片平均水准，两席审计独立确认核心域健康**；问题集中在场景层与生命周期层。两个 P0 是同一根因的两面：**整条应用生命周期（菜单/营地/冒险/战斗/每局复位）压缩在 main.gd 一个 1385 行的组合根里，靠手工清单维持局间隔离**——领域侧已经长出三层编排器（AdventureRunner 跨局持久 / LevelRunner 一关一生 / BattleOrchestrator 一战一生），场景层没有任何切缝与之对应。一句话定性：**领域分层是洋葱，场景组织是石头。**
---
## P0 发现（2 条，同根）
### P0-1 全产品单场景：场景作为「组合单元/生命周期单元」完全缺席
- **证据**：`project.godot`（main_scene 唯一）；`presentation/main.tscn` 仅 1 个 Control 节点挂 main.gd；`presentation/main.gd:204-361` `_build_ui` 程序化构建全部四区 + 12 个模态层。
- **为什么是问题**：Godot 中场景是复用、组合与生命周期的基本单元——节点进/出树（`_enter_tree`/`_exit_tree`/NOTIFICATION_READY）本可免费承载「每局/每屏」的状态建立与销毁。现在一局结束什么都不销毁，全靠手动清理；任何视图都无法 F6 独立运行或单独复用；13 个 smoke 探针里 10 个只能挂载整个 main.tscn 才能测任何 UI（`smoke/ui_probe.gd:15` 等）。
- **修复方向**：按「屏」切场景，第一步只拆屏容器 .tscn，视图继续代码构建，不要求全面 .tscn 化。
### P0-2 每局状态靠手工复位清单，无局级生命周期边界
- **证据**：`presentation/main.gd:647-657`（`_on_battle_end_continue` 手工置空 runner/settlement/adventure/_adventure_mode 并调 debug_overlay.reset_sliders()）；`main.gd:555-559` `_reset_run_scope` 只清 3 项；局态旗至少 7 个散布类顶（`main.gd:53-56,76-78,129-131`）。这类手工清单已有前科：`main.gd:790-792` 注释记录了续玩分支 runner 未就绪导致的实机崩值。
- **为什么是问题**：场景机制「打包一组节点，`free()` 即整体回收」正是为消灭这种清单而存在；清单是随新增状态线性膨胀的手工契约，每加一个跨局字段就多一个静默泄漏点，且泄漏表现为低频难复现的脏状态而非显式报错。
- **修复方向**：把「一局」物化为可整体 `queue_free()` 的节点（或至少一个 run-scope 对象持全部局态），终局释放即复位。
---
## P1 发现（6 条）
### P1-1 战斗结算巨函数：259 行、嵌套 7 层、同构兑付块重复 ≥5 处（双席独立命中同一病灶）
- **证据**：`core/battle_orchestrator.gd:632` `_settle()` = 259 行；`:562-563` 嵌套达 7 层（该文件 ≥5 层缩进行共 80 行，全项目最高）。重复块实读确认：`counter_add` 兑付三行组 ×5（`:682-684, 741-743, 776-778, 838 附近, 1192-1193`）；`grant_material` 二次兑付块 ×3（约 `:688-694, :789-792, :1206-1212`）；`reveal_tiles` 检查 ×3。效果 kind 字符串分派（`get("kind","") ==`）散布 20 处于结算段内。姊妹病灶：`core/damage_controller.gd:272` `_resolve_hero_attack()` = 148 行。全文件 1725 行、类级状态约 40 个变量（:62-98）、fan-out 13 个 core 类。
- **为什么是问题**：编排器**不是**纯上帝对象（伤害已单据化进 DamageController，敌人/状态/奖励各自成类），但效果引擎只做了「匹配」数据驱动，「施加」按既定裁决留在发射点——实际效果是新增一种 effect kind 要同时改引擎词表 + 编排器内联分支，编排器增量复杂度与内容量线性挂钩。
- **修复方向**：不推倒重写——五段结算各抽成 Segment 类（grant/aura/combat/decay/verdict），编排器退为段序编排 + 行发射，20 处 kind 分支随段归位。
### P1-2 刷新次数双账本——所有权三问（谁拥有/谁可改/谁知道）不及格
- **证据**：权威计数在 `core/battle_orchestrator.gd:73`（`_refresh_used_this_round`，受理门槛 :1522）；呈现/遥测另计一份 `presentation/main.gd:129`（`_refresh_used_round`），HUD 余量 = 表上限 − main 自己的计数（`main.gd:1240`）。
- **为什么是问题**：core 是裁判、main 是记账员，两条路一旦分叉（新增受理路径、调试注入、断点恢复），HUD 显示与真实可刷次数静默不一致。
- **修复方向**：`presentation_snapshot()` 已可携带本轮已刷次数——删 main.gd 副本，HUD 只读快照。
### P1-3 GP 影子账本：表现层持有权威态镜像，根因在 summary 载荷不全
- **证据**：`presentation/gp_shadow_ledger.gd:9-19`（表现侧镜像钱包余额）；根因链：`core/adventure_runner.gd:1046`（close_wallet() 清零先于 adventure_finished.emit）+ `adventure_runner.gd:1022-1038`（summary 十一个键里没有 final GP），呈现层被迫在清账前从事件流自抄一份。
- **为什么是问题**：表现层持久化核心态违反「表现禁存数据」；镜像与权威只靠 wallet_changed 事件序维持一致（影子账本文件头自己承认是手工镜像）。该上抛的数据应随信号载荷走，不该让下游自建账本补抄。
- **修复方向**：summary 增加 `gp_final` 键（清账前快照），删影子账本。
### P1-4 共享可变字典跨三层：所有权「名义单点、实际三处可写」
- **证据**：`core/level_runner.gd:501-521` begin_battle 的 encounter 载荷携带 bonus_ref/adventure_counters/attune_charges/vision_counter 四个共享 dict 引用；`core/battle_orchestrator.gd:79,86-88` 持引用直写（_attune_charges_ref 注释自认「use_treasure 消费直改」）；`level_runner.gd:50` 账本同为字典引用共享。
- **为什么是问题**：这是确定性设计（回灌/导出时点已文档化），但共享可变引用在函数签名上不可见——「冒险加算区归 AdventureRunner 所有」只是头注契约，LevelRunner 与 BattleOrchestrator 都握着同一本账可写。
- **修复方向**：共享账收拢为显式 Ledger 类，战斗侧只拿 read+append 原语；战末 export/开局 seed 已有的时点语义不变。
### P1-5 组合根（main.gd）不可独立测试：核心读面靠注释纪律维持
- **证据**：控制器不可独立实例化——`presentation/curio_interact_controller.gd:39-57` 构造 16 参（10 个组合根 Callable）、`presentation/camp_shop_presenter.gd:25-40` 13 参；测试代价：`tests/unit/presentation/pacing_queue_test.gd:17-18` 必须 load 整个 main.tscn 挂整树并篡改 main 内部字段才能驱动。25 个测试套件中 core/data 侧 22 个直接 new() 即测，presentation 侧只剩整树集成一条路。
- **为什么是问题**：组合根本身没有单测缝；豁免面与 20+ 访问器（settlement.minesweeper.* 等）无结构强制，全靠 ADR 注释和评审盯。
- **修复方向**：把 main 的「模式状态机 + 输入锁 + 模态编排」抽成无 UI 纯逻辑类（依赖仅 ModalStack + 查询 Callable），控制器构造参数收拢为 context 对象——不改行为即可获得单测缝。**注：本条应在场景拆分落地后重新评估，main.gd 缩水后抽取面可能大幅变小。**
### P1-6 静态类型闸缺位：类型规范有文、机器无闸
- **证据**：无类型 Array/Dictionary 游戏代码 73 处（core 53 / data 9 / presentation 11，如 `core/adventure_runner.gd:78,95`、`core/effect_engine.gd:94-95`、`presentation/main.gd:69`）；core 无返回类型函数 12 处（`core/reward_economy.gd:109,124,136,151` 等）；无类型参数（`core/attunement.gd:12`、`core/board_generator.gd:18,83,284,334`）。`project.godot` 全文 36 行没有任何 gdscript warning 配置——`untyped_declaration` 默认 Ignore。
- **为什么是问题**：仓库 code-conventions §4.2 有明文（Dictionary 取值参与算术前显式声明类型），但无机器闸则规范只靠评审；Variant 容器在结算热循环里吃类型检查开销且放行拼写错。
- **修复方向**：project.godot 提升 warning 级别让存量显形，新码一律收口；存量 73 处随批清理。**本条必须在其他重构全部落地之后做**，否则新重构代码又会产生新违规。
---
## P2 卫生件（建议打包随批，不需逐条裁决）
1. **死代码 16 处**：`core/battle_orchestrator.gd:216` `_attune_row`、`core/damage_controller.gd:102` `_fx_dispatch`（活实现 _fx_fact 的退役孪生）、`core/board_data.gd:61` `clear_variants`、`core/effect_engine.gd:417` `combo_of`、`core/treasure_items.gd:68,83`、`core/minesweeper_rules.gd:41`、`core/feats_engine.gd:13,38`、`core/config_db.gd:253,273`、`core/save_manager.gd:419`、`presentation/curio_interact_controller.gd:58`、`presentation/views/stage_world.gd:17`、`presentation/views/curio_pick_overlay.gd:170`、`presentation/views/ui_kit.gd:486`。其中 **FeatsEngine 整文件零调用**（仅注释提及，`data/schemas/feat_table.gd:22` 自注已随重设计退役）但 `class_name` 仍全局注册。
2. **绝对路径取 autoload ×4**：`presentation/main.gd:174,190,481,1351` 用 `get_node("/root/…")` 字符串路径取 ConfigDB/RngService——Godot 4 有编译期注入的全局名，字符串路径改名/拼写零防护。
3. **字符串式 Callable ×9**：`core/battle_orchestrator.gd:105,390,391`、`core/damage_controller.gd:98`、`core/adventure_runner.gd:940,951`、`core/level_runner.gd:166`、`presentation/main.gd:191`——`Callable(self, "方法名字符串")` 绕过编译期方法存在性校验，应改 `self._method` 引用形式。
4. **裸字符串状态机 ×16**：`core/adventure_runner.gd:120,159,176,263,269,277,402,894,974,1049,1051,1071`（state = "idle"/"running"/"settling"）；`presentation/views/standee_body.gd:333,373,380,387`。本仓 `core/action_economy.gd:12-23` 已有「内部 enum + match + 外部 String 契约 getter」正解示范，应套用。
5. **百行级装配/校验长函数 17 个**：`presentation/main.gd:204` `_build_ui()` 160 行、`level_map_screen.gd:72` 145 行、`camp_overlay_view.gd:55` 142 行、`debug_overlay.gd:159` 114 行、schema 校验器群（treasure_item_table.gd:87 = 149 行等）。线性装配圈复杂度不高，但区块级改动每次都在巨函数里动刀。**注：main._build_ui 在场景拆分中自然解体，不必单独修。**
6. **ConfigDB 越权退出 + resolver 类型软环**：`core/config_db.gd:75-82` `_fatal` 直接 quit(1)/OS.crash（fail-fast 政策对，执行位置应归根——`main.gd:176-179` 已有同通道 fatal 屏）；`config_db.gd:57-58` 持有并构造 ConfigDbResolver，resolver 反向 class_name 引用 ConfigDb——双向类型耦合，resolver 对门面改持 Callable 诊断通道即解（validator 已是此形态）。
7. **模态「开态=可见性」协议**：`presentation/modal_stack.gd:39-63` has_open() 靠遍历 visible 位；`main.gd:404-409` 输入锁 = 栈查询 + 三例外 + 排除式；`main.gd:407-408` 注释记录过「DS_DEBUG 默认开 × 遮挡复活 × has_open 组合 = 棋盘永久锁死」事故。12 个层的状态散布在各自 visible 位上，约束只存在于调用点拼装。修法：ModalStack 内聚「互斥域/排除组」概念，开态谓词随层登记。
---
## 用户场景预想评估（审计席专门裁断）
用户预想：开始菜单做根场景 + 营地/冒险分开 + 冒险内分关卡/战斗两大块。
**裁断：方向支持，三条全部成立；需三处修正、一处明确反对。**
1. **支持「开始菜单做根场景」**——修正：拆场景后 SaveManager/MetaProgression 不能再由 main.gd new() 出来（`main.gd:182-189`），必须提升为跨场景持有者（第三个 autoload 或根场景常驻子节点），否则换场景即丢档。RngService 已有先例，模式现成。
2. **支持「营地与冒险分开」**——营地全部读写已收口在 MetaProgression/SaveManager 访问器（camp_shop_presenter 零直写），营地当前只是覆盖层（camp_overlay），升格独立场景不碰任何 core 接口，切缝天然干净。
3. **支持「冒险内关卡/战斗分块」**——最有力的论据是域侧三层生命周期已经存在，场景层只是补镜像：`level_screen` 已是独立屏雏形（`main.gd:76,259-263`，屏级互斥单出口 `main.gd:978-990`），`_battle_root` 是现成战斗屏宿主（`main.gd:77,207`）。预想与代码现实几乎一一对齐。
4. **明确反对一条**：不要借机把 40+ 个 views/*.gd 转成 .tscn。「程序化构建」与「场景切分」是两个独立决策——.tscn 根节点 + `_ready` 程序化内容完全合法；全面 .tscn 化会破坏全部探针契约（`board_view.gd:8-14` 对探针零改造契约）且收益为零。
5. **迁移安全网**：13 个 smoke 探针中 10 个假设「挂载 main.tscn 即全应用」，拆分时这批探针的挂载假设同批迁移，它们就是切分作业的回归保障。建议时序：垂直切片验证期「只拆不重写」——root 壳 + menu.tscn + camp 场景 + adventure.tscn（内含 level_map/battle 两容器），新内容一律进新场景，战斗屏视图代码原样搬。
---
## 实现规范面补充结论与扫描器运行记录
**四大高危面几乎无坑、无 P0 命中**：信号面、Tween 生命周期、数值单一事实源、autoload 卫生。
**扫描器实跑记录**（实现席如实登记）：
- 技能库 `auditor_audit_signals.py`（python 只读输出）：74 处 lambda 连接（presentation 4 / smoke 62 / tests 8）。presentation 4 处逐一实读确认无泄漏（发射者与 lambda 同子树同生共死，refresh 先 queue_free 子树并清登记数组，`camp_overlay_view.gd:227-230`）；smoke 62 处为一次性 headless 探针进程，不进游戏包。
- 技能库 `auditor_audit_type_hints.py`：229 处（untyped Array 209 / Dictionary 20 / string connect 0）；按目录 core 53 / data 9 / presentation 11 / smoke 133 / tests 23。
- 手工 grep 等价检查（如实注明非扫描器）：Godot 3 四参 connect 0；字符串 `.connect(` 0；`.disconnect(` 0；CONNECT_* 标志 0；绝对路径 get_node 4（见 P2-2）；`Callable(self,"…")` 9（见 P2-3）；call_deferred 10 处实读均为帧沿触发非初始化创可贴；await 1 处（dev 工具）；全站 `_physics_process` 中 await 0；create_tween 20+ 处实读确认节点绑定+回调清理；print 3 处全在 dev 工具。
- 跳过并注明：`auditor_audit_memory_fragmentation.gd`、`auditor_purge_report_generator.gd` 需 Godot 运行时，按只读纪律未跑。
- 误报排除一例：battle_orchestrator 的 round_started/board_changed（:30-31）初判疑为死信号，实读确认 :447,488,1516 有发射、三层转发链全活，非发现。
---
## 做对了的事（防止报告纯负面失真）
1. **信号严格向上，core 零反向依赖**：全 core/ 无一处 presentation 引用、无 get_node/树访问；runner 转发族用命名方法 Callable（`core/adventure_runner.gd:918-924` 等，头注写明禁 lambda 捕获 self 成环）；信号连接唯一归组合根（ADR-0001 落实到位）。
2. **Autoload 克制且纯净**：仅两个、纯数据/服务形态、无子节点无 UI 知识；RngService 统一单盐流 + 全事件日志（`core/rng_service.gd:95-108`）使全游戏同种子逐位复现——确定性架构的业内水准做法，也是本次全部重构验收手段的基础。
3. **效果引擎护栏设计**：事件/效果/事实/算子四词表封闭常量 + 加载期 schema 校验致命 + 组合规则成文（`core/effect_engine.gd:24-91,362-433`），失败模式 fail-fast 而非静默。
4. **读面成文快照收口**：presentation_snapshot()/diagnostic_snapshot() 成文出口替代链式穿透，协作对象私有化 + 明文豁免面——封装边界是写下来的契约而非默契。
5. **Tween 生命周期纪律全站一致**：节点绑定 create_tween + tween_callback(queue_free) + is_instance_valid 守卫 + rebuild 重入先杀——技能库最常判死刑的陷阱本项目零命中。
6. **测试策略真实分层**：25 个 headless 套件直接实例化 core 类、表值现读不写死；确定性 RNG 使「逐位一致」断言成为可能，这在随机系统里是稀缺的测试能力。
---
## 修复排期估算与裁决记录
**逐项估算**：场景拆分 + 局生命周期物化 + 探针迁移 ≈ 4-5d；`_settle` 拆段 ≈ 1.5d；共享账本 Ledger 类化 ≈ 1d；类型闸拉起 + 73 处收口 ≈ 1.5d；组合根可测化抽取 ≈ 1-1.5d（场景拆分后重估）；模态协议内聚 ≈ 0.5-1d；卫生件包 ≈ 1.5d。**合计约 12-14 个工作日。**
**裁决记录（2026-10-14 用户）**：全部技术债修复**允许放行单一大迭代**，12-14 个工作日在允许时间范围内。
**批内执行顺序约束**（审计席建议）：①场景拆分与局生命周期先行（P0 根因，且决定 main.gd 终态形状）；②战斗域重构（_settle 拆段 + Ledger 类化）随后；③组合根抽取在场景拆分后重估再动；④类型闸收尾（其他重构落地后才拉得起 Error 级）；⑤卫生件随批顺手带。最大两件（场景拆分动 main.gd 1385 行 / _settle 拆段动战斗结算心脏）各自需要全量冒烟回归，同批内应分波提交、逐波全绿，避免回归时二分定位跨双巨改。
**核心验收手段**：确定性 RNG 架构给了杀手级验收——同种子逐位一致回放（重构前后跑完整局输出逐位一致）；场景批验收 = 10 个探针迁移后全绿 + run_all 25 套；战斗域批验收 = 逐位一致 + 冒烟全量。
**写卡前待裁三点**（grilling 时闭）：①SaveManager/MetaProgression 升格形态（第三个 autoload vs 根场景常驻节点）；②共享账本 Ledger 类接口口径；③`_settle` 段边界切法。
design/research/需求卡片-代码架构技术债修复批-2026-10-14.md
+1 -1
View File
@@ -1,7 +1,7 @@
# 需求卡片：代码架构技术债修复批（场景拆分 · 局生命周期 · 战斗结算拆段 · 账本收口 · 类型闸 · 卫生件）
- 版本：v1.2（2026-10-14 成文 v1.0；同日用户令**编入迭代 27 卡①**——roadmap 迭代行已更新，M4 数值批顺延 28+。v1.1→v1.2：**§10 三点待裁全裁**（2026-10-14 用户三裁，全按推荐案：①第三个 autoload／②单类持四账／③审计五段）——零待裁点，卡片成立）
- 来源：[代码架构与实现质量审计报告-2026-10-14](代码架构与实现质量审计报告-2026-10-14.md)（双席审计，基线 master 97de02c；**同日已经第三方逐条复核：主体结论全部成立，五处计数级瑕疵已随批修正落文**）
- 来源：代码架构与实现质量审计报告-2026-10-14（双席审计，基线 master 97de02c；同日第三方逐条复核五处计数级瑕疵修正落文；**该报告已按退役规则于本批收口 git rm——吸收即死，修正后计数由本卡承载，收口结案=design/qa/iter27-实现报告-2026-10-14.md**）
- 归属：工程债/重构批（凭审计证据直接写卡，无设计定稿前置——2026-10-10 立规：缺陷修复/工程债/重构类工程需求无设计前置要求）
- 排期：**已编入迭代 27 卡①**（2026-10-14 用户令；用户裁决记录：全部技术债修复允许放行单一大迭代，12-14 个工作日在允许时间范围内；**开工门=U0 已满足**——三点已裁（见版本行）＋用户 /goal+iter 27 发令，U0=2026-10-14 开工；M4 数值批顺延 28+）