diff --git a/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md b/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md index edeadcef..393678c6 100644 --- a/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md +++ b/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md @@ -412,4 +412,5 @@ S13 闸＝「当前扫描 vs 基线对账」：判红仅两种——基线外新 4. **波 8 config_db 公开方法收敛＝纯代码**（删冗余、私有化内部方法，不动对外语义；架构表「对外暴露」列属现状登记，实现批后随动改写）。 5. **判定口径**：全部波不改游戏规则与玩家可见行为——design/gdd/systems/ 零修订预期；唯一设计改动面＝波 1 的 architecture.md；owner 契约若被触碰走迭代批反哺点通道（正常机制）。波 5 已实查落定：open_ticket 12 参全是单据声明形态，「九栏目」只在架构模块描述层、GDD 无此契约，参数收束不改单据栏目与明细行发射协议，纯代码。 6. **2026-10-26 独立审查折入（grilling＋godot-master 双子代理并行审查，双判「回炉补裁级」——骨架成立、接线未闭合）**：阻断 8 条去重 6 组全折入 architecture.md v1.18——①S13 键账：12 随迁键（use_treasure×4／_grant_routed 参数 8／_dispatch_row／_apply_percent_row／_apply_gp_row／_apply_flat_row 参数＋返回／_submit_flat_hero／_fx_fact 返回）随函数入新文件＝基线外 NEW，卡内同步收敛定为本波义务、禁波 0 合并 refresh 吸收；②跨件单向接线裁死（RewardGrant 持 fx 件引用、fx 件对授予面走注入兑付 Callable——禁 RefCounted 双向环）；③settlement/ 段类随动（段类直持三引用，Middle Man 禁壳，读写面点名）；④两新件消费依赖列补全＋引用束注入防 _init 参数新键＋TreasureItems 经宿主 setter 转发（注入时序）；⑤treasure_interact_controller 三触点分家（现值回调＋双取值面，防每战新建悬挂）；⑥_fx_revealing 再入闸归 fx 件、揭示态投影消费方订正为宿主订阅旁路判定。建议 5 条全折入：S8_FILES 与 S7_B1_SET 同批随动、battle_orchestrator 行旧述过渡指路、头注发射点指址随动许可、nest_preview_count 留宿主＋两外部直读面冻结、fx_reveal 流随件迁移取号序不变。 +7. **2026-10-27 写卡整合裁定（用户裁「太分散，整合」——波次归并为 3 张需求卡，消除文件交叠）**：卡 1「B1 战斗域拆件批」＝波 1＋波 3＋damage_controller 9 键（B1 域件，拆件已触其调用面）＋treasure_interact_controller 2 键（三触点分家必触）＝45 键，设计事实源＝architecture.md v1.18；卡 2「核心数据面结构收敛批」＝波 2（40）＋波 4（17）＋effect_engine（8，归 core/data 面防与卡 1 文件交叠）＋波 8 core/data 侧 10 文件 21 键＝86 键；卡 3「呈现层结构收敛批」＝波 6（54）＋波 8 呈现侧 8 文件 17 键＝71 键。合计 45＋86＋71＝202 键＋三宿主规避 14＝216（账目闭合）。波 7 复用现成卡不重写；波 0 直改不写卡。归并收益＝写卡/审计/闸批开销降、文件交叠冲突归零（grant_segment 一卡内先随动再拆 run）、PARITY 对拍与 golden 锚各一次；代价＝卡 2 覆盖约 20 文件最厚、审计抽检面变大。编排预测：迭代 A＝卡 1＋卡 3、迭代 B＝卡 2＋波 7（均为常规区间）。 diff --git a/reports/需求卡片-B1战斗域拆件批-2026-10-27.md b/reports/需求卡片-B1战斗域拆件批-2026-10-27.md new file mode 100644 index 00000000..f954ba6d --- /dev/null +++ b/reports/需求卡片-B1战斗域拆件批-2026-10-27.md @@ -0,0 +1,366 @@ +# 需求卡片：B1 战斗域拆件批（gdstyle 存量债·波 1＋波 3＋damage/treasure 收编） + +- 版本：**v1.0**（自审六查＋grilling 自检一轮全折入，记录见 §12） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋待写卡）（唯一事实源：[architecture](../design/engineering/architecture/architecture.md) **v1.18**「战斗编排域拆件定稿」节全文＋功能层表 BattleFxHost／RewardGrant 两行） +- 归并与账目：[审计报告](./审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 7 条（2026-10-27 写卡整合裁定）——本卡收编波 1（22 键）＋波 3（12 键）＋damage_controller（9 键）＋treasure_interact_controller（2 键）＝**45 键** +- 归属：`game/core/` 新二件＋battle_orchestrator／settlement/ 两段／damage_controller／settlement_table 改造＋treasure_interact_controller 三触点分家＋测试与装配面改址＋static_scan 两清单随动 +- 排期：未编入（迭代批卡片；估时 ≈4.25–5.0 个工作日） +- 开工门：U0＋复核门过（§12）；**待裁点 2 项（§11）由用户裁决清零后方可编入迭代** +- 同日姊妹卡：核心数据面结构收敛批（卡 2）、呈现层结构收敛批（卡 3）——整合裁定后三卡文件交叠为零 + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话）**：来源条目＝设计线条目（gdstyle 存量债清偿，逐波设计段闭合），波 1 闭合凭据＝architecture v1.18（「战斗编排域拆件定稿」节＋功能层两新件行），状态已到「待写卡」，放行。波 3／damage／treasure 三收编件按 §六第 5 条定性纯代码（零设计改动）＋重测读数写卡。 +- **attune 族领地隔离**：同调配装 8 成员原位保留（v1.18 第 4 款）——语义领地归迭代 39 副卡（AttuneLoadout 充能单源化）。本卡禁触 attune 族与 adventure_runner／level_runner／board_view 三宿主（迭代 39 在册规避）；level_runner 对本卡零改动（其 treasure_inventory 注入 `level_runner.gd:502` 与 set_treasure_unlocked `:640` 走宿主公有面不变）。 +- **并行冲突注记**：与卡 2（波 2/4/8 core/data 面＋effect_engine）、卡 3（波 6/8 呈现面）文件交叠零（整合裁定消除）；与波 7 现成卡（结构小件定点修批）文件交叠零。同迭代排波先后自便（本卡自持 worktree 批）。 +- **PARITY 触面预告**：本卡改动面命中 `run_all_gates.sh:227` PARITY_TOUCH_FACES 三路径（battle_orchestrator.gd／settlement/／damage_controller.gd）——对拍发起与否归用户裁（§11 待裁点 1）。 + +## 1. 目标与完成定义 + +**目标**：battle_orchestrator（1313 行／50 类变量／S13 全库单文件最大户）按变化原因拆出 **BattleFxHost**（效果引擎宿主件）与 **RewardGrant**（奖励授予件）两协作件；settlement/ 授予段与战斗段随动改指；grant/combat 两段 run() 与 settlement_table.validate() 段内拆私有函数族；damage_controller 函数级拆分＋open_ticket 参数束；treasure_interact_controller 三触点分家＋ctx 束构造。**游戏行为零变化**（契约 1），iter38 行数恶化债（c4c69701）本批还债归绿。 + +**改动单元清单**（与 §7 文件结构图同源）： + +| # | 单元 | 内容 | +|---|---|---| +| u1 | BattleFxHost 建件＋fx 族迁移 | 事件发射面（_fx_emit）、事实判定（_fx_fact）、AC 基线与本轮/本战累积、bonus_delta 四轴累积（战末宿主 drain）、揭示待兑队列与兑付（含 _fx_revealing 再入闸）、round/battle 桶计数器持有（桶随编排器生灭）、round_start 发射、订阅重建 | +| u2 | RewardGrant 建件＋grant 族迁移 | 极性路由兑付（grant_routed）、三种行应用（flat/percent/gp）、伤害单据提交面（submit 族）、清图奖励与身份授予、GP 缓冲 escrow、案C 暂存闸（defer） | +| u3 | use_treasure 拆分＋三触点分家 | use_treasure 四步编排迁 RewardGrant＋体拆分；treasure_interact_controller 经组合根现值回调改注 RewardGrant，minesweeper 读与 attune_convert_state 仍走宿主取值回调（双取值面） | +| u4 | 段类随动 | GrantSegment／CombatSegment 构造注入直持宿主＋两新件三引用（Middle Man 禁壳，调用点改指；读写面=架构 v1.18 第 3 款点名清单） | +| u5 | run() 族拆分 | grant_segment.run()＋_judge_seal、combat_segment.run()、settlement_table.validate() 段内拆私有函数族 | +| u6 | damage_controller 拆分 | open_ticket 参数束（4 参 spec 形态）、_hero_attack_ctx／_hero_attack_redeem／_resolve_enemy_skill 拆分、类变量 19→15 收敛（inject 束＋fx_calls 束） | +| u7 | 改址＋随动 | 测试/探针/装配面改址 123 处（§3 G11 清单）；static_scan.sh S7_B1_SET／S8_FILES 登记两新件 | +| u8 | 撤销证明＋产出物 | 逐 wr 撤销证明；三份产出物落位 | + +**完成定义**： +1. u1–u7 落地；代码域闸全绿；行数恶化债归绿——拆件后宿主与两新件文件行数全部 ≤1000（宿主实测预估 ≈950）。 +2. 45 键账逐键核对（读数表进实现报告）：44 键清零＋1 键结构性残留如实呈报（settlement_table 类变量 18/15——@export 表 schema 数据列，见 §11 待裁点 2）；宿主残留键 8 个＝改善非清零达标线（v1.18 第 8 款：begin_battle×4＋_place_variants×3＋_emit_row×1）。 +3. 行为零变化验收落地（§11 待裁点 1 裁定案执行）：同种子逐位一致。 +4. 撤销证明逐 wr 行落地；三份产出物写齐（T6）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | [architecture](../design/engineering/architecture/architecture.md) **v1.18** | 「战斗编排域拆件定稿」节八款全文（轴甲两件／跨件单向接线／段类随动读写面点名／attune 原位／呈现零变化／S13 键账收敛义务／验收红线／S7-S8 随动）＋功能层表 BattleFxHost 行（消费依赖 9 类）与 RewardGrant 行（消费依赖 12 类）＋battle_orchestrator 行过渡注记 | +| D2 | [审计报告](./审计-gdstyle存量债清点与清偿方案-2026-10-26.md) | §三波次表（波 1/3/5 病根与注意）、§六第 5 条（open_ticket 12 参单据声明形态定性）、第 6 条（独立审查 6 组折入）、第 7 条（三卡整合裁定与 45 键账目） | +| D3 | [战斗结算](../design/gdd/systems/战斗循环/战斗结算.md)（只读引用） | :175「单据九个栏目」＝单据字典语义面契约（兑付配方／来源三件／显示名／通道／攻击类型／威力基数／目标规则／必中附加分量），未绑定函数签名——本卡零修订（同步面见 §6） | + +## 3. 现状事实（2026-10-27 写卡会话实查于 master 8b146321；开工日 T0 复核行号） + +| # | 事实 | 出处 | +|---|---|---| +| G1 | battle_orchestrator.gd 实测 1313 行（gdstyle 读数 1314，口径差 1 以闸为准；基线登记 1302——**恶化债在案**）；类变量 50（逐员对账一致）；信号 4／const 2。键 22 条＝行数＋类变量＋begin_battle×4＋_place_variants×3＋use_treasure×4＋_grant_routed 参数＋_dispatch_row/_apply_percent_row/_apply_gp_row 参数×3＋_apply_flat_row 参数＋返回＋_submit_flat_hero 参数＋_fx_fact 返回＋_emit_row 参数 | `game/core/battle_orchestrator.gd` 全读＋`python tools/gdstyle_gate.py` 实跑（216 命中／恶化 2）＋`tools/gdstyle_baseline.txt` | +| G2 | fx 族成员 11：_fx_hero_ac_base:78／_fx_ac_round:79／_fx_ac_battle:81／_fx_bonus_delta:82／_fx_new_resource_types:83／_fx_pending_reveals:84／_fx_revealing:85／_fx:91／fx_counters_round:92／fx_counters_battle:93／counters_ctx:94；fx 族函数 9：_fx_emit:98／_emit_round_start:107／_sync_hero_ac:118／_apply_ac_bonus:126／_fx_enqueue_reveal:138／_flush_pending_reveals:145（fx_reveal 流 :158 随件迁移点）／_fx_fact:173。fx_counters_round/battle 两成员在 _init:283-284 挂入 counters_ctx 后全库零读者（「同物异名同字典」自注）——迁入后可删 | 实读＋grep 全库（tests 命中均为行键文本/ctx 读） | +| G3 | grant 族成员 3：escrow:53／_defer_board_damage:59／_deferred_board:60；grant 族函数 11：use_treasure:710（62 行／8 返回／18 分支／11 局部）／_grant_routed:778（8 参）／_dispatch_row:810（6 参）／_apply_percent_row:820（6 参）／_apply_gp_row:844（6 参）／_apply_flat_row:859（7 参/9 返回）／_submit:900／_outcome_of:909／_submit_flat_hero:914（7 参）／_grant_clear_reward:924／_grant_clear_identity:943。_pool_effective:1016／perfect_sweep_earned:1312／四 helper（_feat_yield_adjust:654／_harmful_variants:668／_harmful_adjacent:680／_hits_of:691）留宿主（v1.18 第 3 款点名） | 实读 | +| G4 | 宿主保留面（v1.18 第 1 款）：状态机与生命周期（begin_battle:310-449／_install_new_board:452／_battle_over:1121）、轮 facts 缓冲（_facts_reveals/seals/path:55-57）、A2 三事件订阅（_on_cell_revealed:586／_on_seal_judged:615／_on_round_end:619）、五段驱动（_settle:634）、attune 族 8 成员原位（attune_has/attune_param_sum/_attune_charge_safe_row/_reseed_attune_charges/attune_convert_state/_attune_safe_seen 等 :74-76/:199-265）、行发射基建（_emit_row:1269／_assert_row_source:1294／_fatal:1304）、呈现投影（presentation_snapshot:1179／diagnostic_snapshot:1241——两出口均不读迁移态，实查载荷字段全宿主成员）、刷新面（can_refresh:1100／player_request_refresh:1110）、nest_preview_count:80 | 实读 | +| G5 | grant_segment.gd 329 行：run() :18-229（211 行/36 局部/33 分支/6 嵌套——全库最大单函数）、_judge_seal :234-316（84 行/14 分支/11 局部/6 嵌套）、_apply_counter_hit:320／_apply_material_hit:326。对迁移面引用实测：oc._grant_routed×5（:59/:122/:290/:316/:329）／oc._submit×6（:79/:114/:127/:156/:195/:209）／escrow 写 :217／_fx_new_resource_types :42-44／_feat_first_dig_used :46/:74-75／_fx_bonus_delta 写 :108-109/:266-267／_apply_ac_bonus :151/:263／_fx_enqueue_reveal :67/:121／_flush_pending_reveals :228／_grant_clear_reward :227／counters_ctx :100/:202/:322／oc._fx（engine 判定）:224 | `game/core/settlement/grant_segment.gd` 全读 | +| G6 | combat_segment.gd 100 行：run() :17-100（83 行/13 局部）。对迁移面引用实测：_defer_board_damage 复位 :18、_deferred_board 结账 :92-99、_damage.dig_streak/charge_layers 注入 :29/:32、_hits_of :50（宿主 helper 留守） | `game/core/settlement/combat_segment.gd` 全读 | +| G7 | aura/decay/verdict 三段对迁移面引用 **零命中**（grep 实测）——维持 _init(host) 单引用，不入三引用随动面 | grep 实测 | +| G8 | settlement_table.gd 89 行：@export 18 列（=类变量键 18/15 的全部构成——表 schema 数据列）、validate() :44-89（16 分支）、结构冻结 const 4 | `game/data/schemas/settlement_table.gd` 全读 | +| G9 | damage_controller.gd 629 行／类变量 19（逐员对账一致）：open_ticket :144-173（12 参——单据声明形态，返回单据字典含九栏目+requires/source_unit）、_hero_attack_ctx :266-325（61 行/9 分支/16 局部）、_hero_attack_base_value :330-360（达标）、_hero_attack_redeem :365-417（54 行/10 分支/12 局部）、_resolve_enemy_skill :440-482（13 局部）、fx_reveal_request/fx_ac_request :99-100（begin_battle :393-394 同点注入）、dig_streak/charge_layers/rider_tier×2 :51-54（combat_segment 与 begin_battle 注入） | `game/core/damage_controller.gd` 实读 | +| G10 | treasure_interact_controller.gd 159 行：_init :20-28（7 参）、inventory_projection :102-146（11 局部）；三触点实测——use_treasure 经 _settlement_get :85-89、minesweeper 读 :107-111、attune_convert_state :113。构造点唯一＝main_ui_build.gd:66-67（两 lambda 现值回调） | `game/presentation/treasure_interact_controller.gd` 全读＋grep | +| G11 | 测试/探针/装配面改址清单（grep 实测，非注释直引）：**counters_ctx 80 处**（adventure_feats_test 71／treasure_effects_test 5／round_flow_skill_pool_test 3〔:653/:673/:711/:1019 等〕／settle_segments_test 1）；**_fx_emit 4**（adventure_feats :751-754）；**_fx_enqueue_reveal 2＋_flush_pending_reveals 2**（round_flow :1040-1041/:1057-1058）；**_grant_routed 8**（seal_polarity :724/:732/:743/:752/:754、level_shop_economy :902/:924、meta_progression_forge :676）；**_grant_clear_reward 2**（seal_polarity :380/:395）；**use_treasure 3**（treasure_effects :167/:236/:285）；**.escrow 成员直读 3**（level_shop :892/:894/:904——:810-850 系行载荷键零改址）；**open_ticket 直调 16**（damage_controller_test 15＋system_contracts_test :74）；**构造点 1**（main_ui_build :66-67）；**段构造 2 行**（settle_segments_test :20/:22）。合计 **123 处**。零改址面：nest_preview_count（main.gd:531-532／treasure_effects:151——留宿主）、attune_convert_state 2／attune_param_sum 3（treasure_effects——留宿主）、query_reward_identity/presentation_snapshot/diagnostic_snapshot（board_resolvers:34/:32、hud_presenter:41/:329、main_debug_flow:14、ui_tune_probe:112、ui_click_probe:890、damage_probe:338/:421、auto_player——留宿主）、行协议 escrow 键（battle_log_view:160／level_shop _escrow_sum_of）、cross_system_flow:70 与 adventure_feats:496/:746 的 open_ticket 均为 triggers 载荷字符串非函数调用 | grep 全库实测 | +| G12 | static_scan.sh 两清单各 7 文件：S8_FILES :315、S7_B1_SET :357（battle_orchestrator＋settlement/ 五段＋damage_controller）；PARITY_TOUCH_FACES＝`tools/run_all_gates.sh:227-236` | 实读 | +| G13 | GDD 定性：`design/gdd/systems/战斗循环/战斗结算.md:175` 描述单据九栏目（语义面），全节无函数签名契约——open_ticket 参数收束定性纯代码（与审计 §六第 5 条一致） | 实查 | +| G14 | 事件总线现状：minesweeper 三信号连接宿主方法（_init:296-298）；damage/action_economy/reward_economy 三 set_fx 注入（_init:293-295）；_damage.emit_row_cb = _emit_row（_init:292）——拆件后经 fx_host.engine/counters_ctx 转注，形态不变 | 实读 | + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 行为零变化**：RNG 消费序零漂移——fx_reveal 封闭流随件迁移**取号序不变**（_flush_pending_reveals 掷格时机/候选序/流名逐字，G2 迁移点 :158）；信号顺序契约冻结（step_row/battle_finished/round_started/board_changed/settlement_snapshot 发射点与时序零改动）；明细行协议词表零触碰（基础 9 类＋扩展行 effect_id 词表与头注清单不动）；同种子逐位一致（§11 待裁点 1 两案之一定期执行）。 + +🔴 **契约 2 · 行数恶化债还债归绿**：iter38 特批带红合并挂账（commit c4c69701，battle_orchestrator 行数 1314＞基线 1302）本批还债——拆件后宿主与两新件文件行数全部 ≤1000；禁以 refresh 换绿、禁删注释凑行数。 + +🔴 **契约 3 · S13 键账纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh；还债＝数值下降自然绿；**12 个随迁键卡内收敛为本批义务**（use_treasure×4／_grant_routed 参数 8／_dispatch_row/_apply_percent_row/_apply_gp_row 参数×3／_apply_flat_row 参数＋返回／_submit_flat_hero 参数／_fx_fact 返回——随函数迁入新文件即基线外 NEW，禁波 0 合并 refresh 吸收）；机检键与卡内契约互斥时实现段一律停卡呈报；禁为迎合机检消息文本保留或新增无效成员/别名（§13）。 + +🔴 **契约 4 · PARITY 触面**：battle_orchestrator.gd／settlement/／damage_controller.gd 三面被改即触对拍触面表——实跑对拍须经用户批准（PARITY_APPROVED=1 机制）、**不得借机重锚**；对拍差异非零即红。发起方式与不发起时的替代验收见 §11 待裁点 1。 + +🔴 **契约 5 · 跨件单向接线（禁 RefCounted 双向环）**：RewardGrant 持 BattleFxHost 引用（treasure_used 发射与 counter_spend 消费）；BattleFxHost 对授予面走 bind 时注入的兑付 Callable（揭示队列 flush 回调）——禁反向强引用。行发射经注入 emit Callable（协议面单点留宿主，CurioDeck bind_handlers 同款先例）；fatal 经注入 Callable 转宿主 _fatal（battle_result 状态机唯一写点留宿主）；facts 缓冲留宿主、fx 件经注入 facts Callable 取值；_seal_consumed 留宿主（与 A2 seal_judged 订阅同域）。禁件回调宿主私有族、禁转发壳（Middle Man）。 + +🔴 **契约 6 · 呈现零变化**：presentation_snapshot／diagnostic_snapshot 两出口签名与载荷逐字不变（G4 实查不读迁移态，零改写压力）；treasure_interact_controller 三触点分家——use_treasure 经组合根现值回调改注 RewardGrant（**每战新建编排器，禁一次性直引防悬挂**），minesweeper 读与 attune_convert_state 仍走宿主取值回调（双取值面）；nest_preview_count 直读面零变化（main.gd:531-532 与 treasure_effects_test:151 冻结零改址）。 + +🔴 **契约 7 · attune 族原位**：同调配装 8 成员不进新件（迭代 39 副卡语义领地）；RewardGrant 经宿主 attune 读投影 Callable 取 _attune_safe_seen（use_treasure 拒绝文案读数）；attune_convert_state/attune_param_sum 留宿主。 + +🔴 **契约 8 · open_ticket 参数束不改单据栏目**：参数收束为 spec 束形态（4 参），返回单据字典九栏目与 requires/source_unit 键逐字不变（GDD :175 九栏目为语义面契约、无签名绑定——G13）；spec 必载键（channel/base_value/target_rule/ri）缺载即 assert（fail-fast 同现行缺省纪律）；禁改单据字段名、禁改明细行发射协议。 + +🔴 **契约 9 · 测试改址非削弱**：≈118 处改址＝访问路径改写与 spec 束键值搬运，断言语义与判据逐条保持；实现期不得借改址删断言/放宽判据（测试削弱申报＝零，§8.2）。 + +## 5. 范围边界 + +**做**：u1–u7（§7 全部任务卡）；§8 全部验收；撤销证明；产出物。 + +**不做**（去向明示）： +- attune 族迁移／AttuneLoadout 建件 → 迭代 39 副卡（在册）； +- aura/decay/verdict 三段（迁移面零触及，G7）→ 零改动； +- effect_engine／数据面 schema 文件 → 卡 2（核心数据面结构收敛批）； +- 呈现层视图面（golden 锚批）→ 卡 3（呈现层结构收敛批）； +- 波 0 基线对账 refresh（陈旧键清理）→ 直改批不写卡，本卡只保证不新增恶化； +- MC 调参与数值表任何触碰 → 零数值改动，MC 不跑（无数值改动零跑铁规）； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 | +|---|---|---| +| `design/engineering/architecture/architecture.md` | 功能层 battle_orchestrator 行「已定稿拆出 BattleFxHost」过渡注记改写为现状；BattleFxHost／RewardGrant 两行「设计定稿——实现批建件」标注换代为现状；「战斗编排域拆件定稿」节头注转现状登记 | 反哺点 · 列清单 | +| `game/tests/验证集清单.md` | ≈118 处改址与两新件断言登记的清单同步（机器提取重生成） | 批内机械同步（game 内 .md，非禁写面） | +| `design/gdd/systems/战斗循环/战斗结算.md` | **零修订预期**——单据九栏目与行协议词表零触碰（契约 8）；若实现期发现冲突即停卡呈报 | 无（零修订预期） | +| `待办清单.md` | 来源条目状态推进（实现批收尾由 batch-closure 承接） | 反哺点 · 列清单 | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/core/battle_fx_host.gd`（**新增**） | 效果引擎宿主件：fx_emit 发射面／fx_fact 事实判定／AC 三值累积与同步／bonus_delta 累积与 drain／揭示队列与兑付（再入闸）／两桶＋ctx 持有／round_start 发射／订阅重建（结构图与预检互指：标「新增」，理由见 §7 预检） | 新件（承载迁移态，行为不变）→ wr1 | +| `game/core/reward_grant.gd`（**新增**） | 奖励授予件：grant_routed 极性路由／三种行应用（flat 拆四）/submit 案C 闸／清图奖励／escrow／use_treasure 四步（拆 _apply_use_kinds） | 新件（承载迁移态＋12 随迁键收敛）→ wr2/wr3 | +| `game/core/battle_orchestrator.gd`（修改） | 宿主保留面（G4）＋建件接线（_init 建两件并注入引用束/bind_grant 接线）＋begin_battle 各调用点改指＋_on_cell_revealed 旁路读改 reveal_busy＋_battle_over bonus drain＋新增 _fx_host_fact 方法＋组件出口两枚：`fx_host() -> BattleFxHost`／`reward_grant() -> RewardGrant`（取件方法非委托壳——姊妹卡 hero()/stop() 同款先例，呈现与测试经此取件，禁链式穿透） | 结构改动，行为不变 → wr1/wr2 | +| `game/core/settlement/grant_segment.gd`（修改） | 三引用构造＋读写面改指（G5 清单）＋run() 拆私有函数族＋_judge_seal 两分 | 结构改动 → wr4/wr5 | +| `game/core/settlement/combat_segment.gd`（修改） | 三引用构造＋defer/dig_streak/charge_layers 改指＋run() 拆三私有 | 结构改动 → wr4/wr5 | +| `game/data/schemas/settlement_table.gd`（修改） | validate() 拆四私有校验器（@export 18 列零触碰） | 结构改动 → wr5 | +| `game/core/damage_controller.gd`（修改） | open_ticket spec 束＋_hero_attack_ctx/_hero_attack_redeem/_resolve_enemy_skill 拆分＋类变量收敛（inject 束＋fx_calls 束） | 结构改动 → wr6 | +| `game/presentation/treasure_interact_controller.gd`（修改） | _init(ctx 束)＋attempt_use 改注 grant_get＋inventory_projection 拆两私有（三触点分家） | 结构改动 → wr3 | +| `game/presentation/main_ui_build.gd`（修改） | 秘宝交互构造改 ctx 束形态（:66-67 一处） | 装配面改址 → wr3 | +| `game/tests/static_scan.sh`（修改，工具面随动） | S7_B1_SET／S8_FILES 各增两新件路径＋头注计数 7→9 | 工具面随动（非行为）→ wr7 | +| `game/tests/` 改址 9 文件（修改） | G11 清单：adventure_feats 75／treasure_effects 8／round_flow 7／seal_polarity 7／level_shop 5／forge 1／damage_controller_test 15／system_contracts 1／settle_segments 3 | 测量面改址 → wr1/wr2/wr3/wr6 | +| `game/tests/unit/core/settle_segments_test.gd`（修改） | 两新件直构断言＋grant/combat 段三引用构造改形 | 新增断言（随 T2/T4）→ wr4 | + +（两新件与新增束的复用/唯一性核查见「落位与可复用性预检」；无新增数据件。） + +### 接口块 + +**BattleFxHost（`game/core/battle_fx_host.gd`）** + +```gdscript +class_name BattleFxHost extends RefCounted # 生命周期＝随编排器（编排器 _init 同建同灭；桶随编排器生灭语义不变） +func _init(bundle: Dictionary) -> void +# bundle 封闭键集（缺一键 assert——引用束注入防 _init max-parameters 新键；v1.18 两新件消费依赖列）： +# db:ConfigDb／rng:RngServiceCore（fx_reveal 封闭流）／minesweeper:MinesweeperRules（板读与 fx_reveal）／ +# action_economy:ActionEconomy（queue_ap_delta/charge_layers/ap_exhausted_last_round）／ +# damage:DamageController（set_hero_ac_override）／ +# emit_cb:Callable（宿主 _emit_row——行协议面单点，8 参同签名）／ +# facts_cb:Callable（宿主 _fx_host_fact——round_index/battle_index/seals_count/nest_count/hp_ratio 五事实宿主侧单点） +func bind_grant(cb: Callable) -> void # 揭示兑付回调＝RewardGrant.grant_routed（宿主 _init 建两件后接线—— + # 构造序解法：RewardGrant bundle 持 fx_host、fx_host 对授予面走注入 Callable，禁双向强引用） +var engine: EffectEngine # 效果引擎（原 _fx；宿主 _init 经此转注 damage/action_economy/reward_economy 三 set_fx） +var counters_ctx: EffectContext # 四桶引用束（round/battle 两桶本件自有；adventure/level 桶 begin_battle mount_buckets 挂引用） +func fx_emit(event: String, payload: Dictionary) -> Array # 原 _fx_emit——18 发射点统一入口 +func emit_round_start() -> void # 原 _emit_round_start（含 ac_round 清零与同步） +func apply_ac_bonus(h: Dictionary) -> void # 原 _apply_ac_bonus +func enqueue_reveal() -> void # 原 _fx_enqueue_reveal +func flush_pending_reveals(ri: int) -> void # 原 _flush_pending_reveals（fx_reveal 流随件迁移取号序不变） +func rebuild_subscriptions(feats: Array, attunement: Array, tree_rules: Array) -> void # 原 _fx.rebuild 调用点（装载序 feats→treasure→树规则写死） +func mount_buckets(adv_bucket: Dictionary, level_bucket: Variant) -> void # begin_battle 桶挂引用（level 非 Dictionary 即不挂——现 :390-392 语义） +func reset_battle_state(ac_base: int) -> void # begin_battle 运行态清零（ac 三值/bonus_delta 四轴/new_resource_types/揭示队列+闸——现 :381-386 原序） +func bonus_delta_drain() -> Dictionary # 战末 drain（读后清零；宿主 _battle_over 单消费——现 :1132-1135 读改清三拍合一，时序等价） +func reveal_busy() -> bool # 揭示兑付中读投影（宿主 _on_cell_revealed 旁路判定——v1.18 第 6 款揭示态消费方） +# 内部：fx_fact(fact)（charge_layers 自答、余五事实转 facts_cb——2 返回）；_sync_hero_ac（经 damage 注入引用） +# 类变量封闭面（14≤15）：bundle 7 项＋grant_cb＋engine＋counters_ctx＋ac{base,round,battle}＋_fx_bonus_delta＋ +# _fx_new_resource_types＋reveal{queue,busy}——ac/reveal 两束键集封闭、头注声明（原 fx_counters_round/battle +# 两成员迁入即删——同物异名零读者，G2） +``` + +**RewardGrant（`game/core/reward_grant.gd`）** + +```gdscript +class_name RewardGrant extends RefCounted # 生命周期＝随编排器 +func _init(bundle: Dictionary) -> void +# bundle 封闭键集（12 项）：db:ConfigDb／reward_economy:RewardEconomy（polarity_row/grant/grant_clear/query_full_snapshot）／ +# damage:DamageController（open_ticket/submit）／fx_host:BattleFxHost（treasure_used 发射与 counters_ctx 消费）／ +# minesweeper:MinesweeperRules（校验回调/fx_reveal/remove_mines_in/hero_pos）／action_economy:ActionEconomy（相位闸/grant_ap/queue_ap_delta）／ +# status_effects:StatusContainer（apply_effect）／units:UnitContainer（hero_unit/heal）／ +# emit_cb:Callable／fatal_cb:Callable（宿主 _fatal——battle_result 唯一写点留宿主）／ +# attune_safe_seen_cb:Callable（宿主 attune 读投影——use_treasure 拒绝文案）／pool_effective_cb:Callable（宿主 _pool_effective——percent 行池值读） +var escrow := 0 # 战斗内 GP 缓冲（原宿主成员语义逐字；宿主 _roll_gp_drop 读投影） +var defer := {"on": false, "queue": []} # 案C 暂存闸（原 _defer_board_damage/_deferred_board 二合一；键集封闭） +var treasure_inventory: TreasureItems = null # 经宿主 setter 转发注入（库存注入时序在宿主构造之后） +func bind_battle(ledger_ref: RunLedger) -> void # begin_battle 账本引用挂接（attune_charge_consume/vision_count_add 消费） +func reset_battle() -> void # begin_battle 现 :315 语义（escrow 清零＋defer 复位） +func use_treasure(handle: int, target: Vector2i) -> Dictionary # 原 use_treasure 四步（拆 _apply_use_kinds——12 随迁键收敛） +func grant_routed(snap: Dictionary, polarity: String, att: Dictionary) -> bool # 原 _grant_routed +func submit(t: Dictionary, sync: bool) -> int # 原 _submit（案C 闸承载：defer.on 即入 defer.queue） +func outcome_of(ticket_id: int) -> String # 原 _outcome_of +func grant_clear_reward(ri: int, skip_on_refresh: bool, perfect: bool) -> void # 原 _grant_clear_reward（宿主态读经参传入） +# att 归因束封闭键集（全 grant 族共用）：source_class:String／cell:Vector2i／ri:int／ +# highlight:String（缺省""）／label_suffix:String（缺省""）／halve_pct:int（缺省 0） +# 内部族（签名随 att 束改形，全部 ≤5 参）：_apply_use_kinds(v, target) -> Dictionary（拒收字典/空字典=受理）／ +# _dispatch_row(row, att)／_apply_percent_row(row, att)／_apply_gp_row(row, att)／ +# _apply_flat_row(row, att, sync) -> String（按 ctype 分派 _flat_action/_flat_blast/_flat_typed/_flat_heal 四私有， +# 返回 ≤6）／_submit_flat_hero(display, power, att, sync)／_grant_clear_identity(snap, ri, suffix) +# 类变量封闭面（15≤15）：bundle 12 项＋escrow＋defer＋treasure_inventory +``` + +**damage_controller 改形（`game/core/damage_controller.gd`）** + +```gdscript +var inject := {"dig_streak": 0, "charge_layers": 0, "rider_tier_bonus": 0, "rider_tier_crit": false} + # 每轮/每战注入运行态（原四散成员收敛；键集封闭——combat_segment 写前两键、begin_battle 写后两键、 + # _fx_fact/管线读同键；19→15 收敛之一） +var fx_calls := {"reveal": Callable(), "ac": Callable()} + # 效果引擎入站回调（原 fx_reveal_request/fx_ac_request；begin_battle 同点注入 fx_host 两方法 Callable） +func open_ticket(kind: String, source_class: String, display: String, spec: Dictionary = {}) -> Dictionary + # spec 必载键：channel/base_value/target_rule/ri（缺载 assert——fail-fast）；可选键缺省=现签名缺省： + # origin_cell=(-1,-1)/attack_type=""/rider=0/highlight=""/context={} + # 返回单据字典九栏目+requires/source_unit 逐字不变（契约 8） +# 拆分族：_ctx_rewrites(t, target, matchup, ar_hits) -> Dictionary（按序改写族四拍——threshold/crit/discount/ +# spike_ready/roll_read 穿线）／_ctx_clamp_delta(atk_type, armor, matchup) -> int（克制点数读值+订阅改写）／ +# _kill_overflow(t, target, landed) -> void（kill 发射+贯穿弹射）／ +# _enemy_roll(t) -> Dictionary（掷点/折扣/克制/池乘/下限）／_enemy_shield_apply(hits, total) -> Dictionary（damage_taken 施加面——{total,shield} 穿线） +``` + +**treasure_interact_controller 改形（`game/presentation/treasure_interact_controller.gd`）** + +```gdscript +func _init(ctx: Dictionary) -> void +# ctx 封闭键集（8 项）：db／meta／info_panel:HeroInfoPanelView／toast:ToastStack／board_view:BoardView／ +# settlement_get:Callable（宿主取值回调——minesweeper 读与 attune_convert_state 双取值面之一）／ +# runner_get:Callable／grant_get:Callable（现值回调——use_treasure 直注 RewardGrant，每战取现值防悬挂） +# attempt_use/on_slot_clicked 空值守卫升级：settlement/runner/grant 三现值同查（null 即静默 return——现 settlement null 同语义） +# inventory_projection 拆两私有：_projection_row(rec, cs) -> Dictionary＋_auto_row(cs) -> Dictionary（自动兑付件展示行） +``` + +**段类随动（`game/core/settlement/grant_segment.gd`／`combat_segment.gd`）** + +```gdscript +func _init(host, fx_host: BattleFxHost, reward_grant: RewardGrant) -> void # 三引用构造注入（两段同形） +# 读写面改指（v1.18 第 3 款点名＋G5/G6 实测）： +# grant 段：oc._grant_routed×5→reward_grant.grant_routed（att 束拼装）／oc._submit×6→reward_grant.submit／ +# escrow 写→reward_grant.escrow／_fx_new_resource_types→fx_host._fx_new_resource_types／ +# _apply_ac_bonus→fx_host.apply_ac_bonus／_fx_enqueue_reveal→fx_host.enqueue_reveal／ +# _flush_pending_reveals→fx_host.flush_pending_reveals／_grant_clear_reward→reward_grant.grant_clear_reward +# （skip_on_refresh/perfect 两实参经宿主引用现读：oc._board_from_midround_refresh／oc.perfect_sweep_earned()）／ +# counters_ctx→fx_host.counters_ctx；_feat_first_dig_used 与四 helper 仍经宿主（留守面） +# combat 段：_defer_board_damage 复位→reward_grant.defer["on"]=false／_deferred_board 结账→reward_grant.defer["queue"]／ +# _damage.dig_streak/charge_layers→_damage.inject 同键／oc._fx→fx_host.engine（:224 finish_round_stop 判定，G5） +# aura/decay/verdict 三段维持 _init(host) 单引用（G7 迁移面零触及） +``` + +**settlement_table 拆分（`game/data/schemas/settlement_table.gd`）** + +```gdscript +func validate() -> Array # 编排骨架：errs 建账＋四私有校验＋return（分支 ≤8） +# 私有族（errs: Array[Dictionary] 追加式，与现 fail-fast 载荷逐字同构）： +# _validate_scalars(errs) # 标量域（equivalence/p_perfect/premium/roll_faces/crit_roll/crit_multiplier/damage_floor/attack_bonus/armor_roll_stream） +# _validate_frozen(errs) # 结构冻结（segment_order 恒等/round_direction/pool_clamp） +# _validate_tier_table(errs)# 档位表形状（bounds 升序/discounts 降序/档数=边界数+1） +# _validate_armor_matrix(errs) # 克制矩阵 3×3 域 [-3,+3] +# @export 18 列零触碰（§11 待裁点 2） +``` + +**T 卡间接口**：T1 产出 BattleFxHost 全 API 与 fx 族改址完成态（T2/T3 取用 fx_host.engine/counters_ctx/三回调）；T2 产出 RewardGrant 全 API、att 束键集、use_treasure 迁移完成态与 grant_get 回调（T3/T4 取用）；T3 产出段三引用构造形（T5 改址取用）；T4 产出 open_ticket spec 束形态（T5 damage 测试改址取用）；各卡验收断言随卡落地。 + +### 落位与可复用性预检 + +| 新增件 | 复用面（为何不能复用既有） | 唯一面 | 分层与交互 | +|---|---|---|---| +| battle_fx_host.gd | 效果引擎宿主职责现散在 battle_orchestrator（本批迁出）——无同职责既有件；grep `BattleFxHost`/`battle_fx_host` 零命中；EffectEngine 是解释器本体非宿主（宿主=施加面+计数器桶+揭示队列），不可互代 | fx 族状态与施加面唯一所有者；桶随编排器生灭语义唯一落点 | Core 纯逻辑（RefCounted）；由 battle_orchestrator _init 建并注入引用束；对宿主单向（兑付/发射/事实走注入 Callable——契约 5）；随机只经注入 rng 的 fx_reveal 封闭流 | +| reward_grant.gd | 授予管线现散在 battle_orchestrator（本批迁出）；grep 零同名类；B4 RewardEconomy 是资源身份/字典查询件（路由执行归 B1 授予段——architecture 功能层表明文），不可互代 | 奖励授予唯一兑付管线；escrow 与案C 闸唯一落点 | Core 纯逻辑；持 fx_host 引用（单向）；宿主态（perfect/装板 provenance/attune/pool 值）全经参传或注入 Callable，不持宿主引用——禁环 | +| att 归因束／spec 束／ctx 束／inject/fx_calls 束（数据面约定，非新文件） | 项目 Dictionary 载荷惯例（行协议 extra/单据 context/encounter 装配同法）；CurioFlowContext 先例同法（curio_interact_controller 装配 ctx）——不另立类型文件 | 每束键集封闭并头注声明（缺一 assert 或缺省显式）；单一声明处=各件头注 | 随所属件生灭；键名在接口块定死，禁实现期增删 | + +### T0 事实坐实＋改前基线采集（≈0.25d） + +- [ ] 复核 G1–G14 行号与读数（吸收并行批漂移）；记录改前读数表：S13 六文件键读数（gdstyle_gate 实跑输出）＋行数/类变量计数——进实现报告素材。可核查结果：改前读数表在案。 +- [ ] 改前确定性基线采集：`…console.exe --headless --path . --script res://sim/dump_battle.gd -- 2 42`（既有 dump 载体——step_row 逐行 JSON，关卡/种子两参数）跑种子矩阵 {42, 779401, 779501}×关卡 {1, 2}，stdout 重定向落 `reports/` 实现报告素材目录（六文件）。可核查结果：改前 JSONL 六份在案（待裁点 1 两案共用——案 A 为对拍外冗余证据，案 B 为替代验收本体）。 + +### T1 BattleFxHost 建件＋fx 族迁移＋S7/S8 登记（≈0.75d） + +- [ ] 实装 battle_fx_host.gd（接口块全签名；fx 族 11 成员＋9 函数自 battle_orchestrator :77-94/:97-196 语义逐字迁入；_fx_fact 改形两返回、charge_layers 自答余五事实转 facts_cb；ac/reveal 两束键集封闭）。可核查结果：件可 `new()` 直构单测。 +- [ ] battle_orchestrator 接线：_init 建 _fx_host（引用束 7 键）→建 _reward_grant→`_fx_host.bind_grant(_reward_grant.grant_routed)`（构造序禁环）＋组件出口 `fx_host()`/`reward_grant()` 两取件方法＋`_damage.set_fx(_fx_host.engine, _fx_host.counters_ctx)` 等三处转注（G14）＋新增 `_fx_host_fact(fact) -> Variant` 五事实方法（:173-196 五分支搬运）；begin_battle 各调用点改指（reset_battle_state/mount_buckets/rebuild_subscriptions/board_installed emit/emit_round_start 原位替换）＋fx_calls 注入；_on_cell_revealed 旁路改 `not _fx_host.reveal_busy()`（:592）；_battle_over 改 bonus_delta_drain（:1132-1135）；宿主 fx 族 11 成员删除（fx_counters 两零读者成员一并删——G2）。 +- [ ] fx 族测试改址（G11，经组件出口）：adventure_feats 75 处（counters_ctx 71＋_fx_emit 4→`orch.fx_host().` 前缀）；round_flow 7 处（counters_ctx 3＋enqueue/flush 4→`o_fx.fx_host().`）；treasure_effects 5 处（counters_ctx）；settle_segments 1 处。 +- [ ] static_scan.sh 两清单登记：S8_FILES :315 与 S7_B1_SET :357 各追加 `game/core/battle_fx_host.gd game/core/reward_grant.gd`＋头注计数 7→9（:309）。可核查结果：S7/S8 段扫描含两新件且零命中。 +- [ ] 验收步骤：〔fx1〕现役揭示管线断言改址后全绿（round_flow 扩展行收敛 V6：`o_fx._fx_host.enqueue_reveal()`→`flush_pending_reveals(1)`→兑付行/落空行同判据）；〔fx2〕battle 桶隔离断言（round_flow :1019 改 `oB._fx_host.counters_ctx` 读 insurance_used=0）；〔fx3〕空订阅零命中断言（adventure_feats :751-754 改 `_fx_host.fx_emit` 同判据）。撤销证明见 wr1。 + +### T2 RewardGrant 建件＋grant 族迁移＋use_treasure 拆分＋三触点分家（≈1.0d） + +- [ ] 实装 reward_grant.gd（接口块全签名；grant 族 3 成员＋11 函数自 battle_orchestrator :698-957 语义逐字迁入；use_treasure 拆 `_apply_use_kinds(v, target) -> Dictionary`——③步逐 kind 应用迁出，四步编排骨架留守；_apply_flat_row 按 ctype 分派 _flat_action/_flat_blast/_flat_typed/_flat_heal；grant 族签名随 att 束改形）。可核查结果：12 随迁键在迁入形下逐键过阈值（T0 gdstyle 复跑两新件零基线外 NEW）。 +- [ ] battle_orchestrator 接线：_init 建 _reward_grant（引用束 12 键）＋`treasure_inventory` 改带 setter 转发（`set(v)` 同步写 _reward_grant.treasure_inventory——外部赋值路径零改址，G11 treasure_effects 三处直赋保持）；begin_battle :315 改 `_reward_grant.reset_battle()`、:388 后加 `_reward_grant.bind_battle(_ledger)`；宿主 grant 族 3 成员删除；_roll_gp_drop 读 `_reward_grant.escrow`（:1169）。 +- [ ] 三触点分家：treasure_interact_controller._init 改 ctx 束（8 键）＋attempt_use 改 `grant_get.call().use_treasure(handle, target)`＋inventory_projection 拆 _projection_row/_auto_row 两私有＋守卫三现值同查；main_ui_build :66-67 构造改 ctx 束（新增 grant_get＝经 `root.run_scope.settlement.reward_grant()` 现值取件、null 即 null——每战取现值防悬挂）。 +- [ ] grant 族测试改址（G11，经组件出口）：seal_polarity 7 处（_grant_routed 5 直调改 `settlement.reward_grant().grant_routed(snap, 极性, {source_class, cell, ri}` att 束＋_grant_clear_reward 2 直调改三参形）；level_shop 5 处（_grant_routed 2＋.escrow 直读 3→`.reward_grant().escrow`）；forge 1 处（_grant_routed att 束）；treasure_effects 3 处（use_treasure→`obX.reward_grant().use_treasure`）。 +- [ ] 验收步骤：〔rg1〕负向字典直验断言改址后全绿（seal_polarity :720-754 五型逐型同判据）；〔rg2〕escrow 隔离断言（level_shop :892/:894/:904 改址后同值判据）；〔rg3〕use_treasure 真链三例（treasure_effects :167/:236/:285——overlay/AP/拒绝零消耗同判据）；〔rg4〕use_treasure 拆分后同种子受理序列逐位一致（本卡 T0 JSONL 复跑——案 B 裁定时；案 A 裁定时由对拍承载）。撤销证明见 wr2/wr3。 + +### T3 段类随动＋run() 族拆分（≈0.75d） + +- [ ] 授予/战斗两段三引用构造（接口块签名）；读写面改指按接口块清单逐条（G5 ×12 面＋G6 ×3 面）；aura/decay/verdict 三段零改动（G7）；settle_segments_test :20/:22 两行构造改三参形（实例经 `oc.fx_host()`/`oc.reward_grant()` 取件）。 +- [ ] grant_segment run() 拆私有函数族：`run(ri)` 编排骨架＋`_reveal_batch(ri)`＋`_reveal_safe(evt, snap, ri)`（施加面拆 `_reveal_safe_apply(dr_hits, evt, snap, ri)`）＋`_reveal_mine(evt, snap, ri)`（施加面拆 `_reveal_mine_apply(mh_hits, snap, ri)`）＋`_terrain_batch(ri)`＋`_seal_batch(ri)`＋`_round_end_apply(ri)`；_judge_seal 两分 `_judge_seal_hit(evt, ri)`（施加面拆 `_seal_hit_effects(fh_hits, cell, ri)`）＋`_judge_seal_miss(evt, ri)`。段序/发射序逐字（run 内调用序=现行 :22-229 执行序）。 +- [ ] combat_segment run() 拆：`run(ri)` 骨架＋`_hero_strike(ri)`＋`_enemy_actions(ri)`＋`_board_deferred_settle(ri)`。 +- [ ] settlement_table.validate() 拆四私有校验器（接口块签名；@export 18 列与错误载荷逐字不动）。 +- [ ] 验收步骤：〔sg1〕同种子完整局 step_row 逐位一致（现役断言面全绿——round_flow/seal_polarity/level_shop 全套）；〔sg2〕五段段直构断言（settle_segments_test 改形后绿）；〔sg3〕validate 拆分后错误载荷逐字断言（现役 validate 单测继承）。撤销证明见 wr4/wr5。 + +### T4 damage_controller 拆分＋参数束（≈0.75d） + +- [ ] open_ticket 改 spec 束（接口块签名；必载四键 assert）；core 调用点 13 处改形（RewardGrant 内 grant 族 3 处〔T2 已迁入〕、grant_segment 6 处 :76/:112/:125/:154/:192/:206、combat_segment 3 处 :44/:54/:84、控制器内部 overflow 1 处 :410；KIND_HERO_ATTACK 分支内构造逻辑不动）。 +- [ ] 类变量收敛：inject 束（4→1）＋fx_calls 束（2→1）——combat_segment :29/:32 与 begin_battle :393-394/:398-399 注入点随动改键写；_fx_fact/管线读改键读；19→15。 +- [ ] 拆分族落地（接口块签名）：_ctx_rewrites＋_ctx_clamp_delta（自 _hero_attack_ctx 拆出）；_kill_overflow（自 _hero_attack_redeem 拆出）；_enemy_roll＋_enemy_shield_apply（自 _resolve_enemy_skill 拆出）。拆后逐函数过 gdstyle 阈值；仍超者按施加面/兑付面继续两分，命名=`<名>_apply`/`<名>_roll` 形态。 +- [ ] damage 测试改址（G11）：damage_controller_test 15 处直调改 spec 束（键值搬运，断言逐字）＋system_contracts :74 一处＋combat/grant 段内 open_ticket 调用随 T3 已改指处套 spec 形。 +- [ ] 验收步骤：〔dc1〕damage_controller_test 全套改址后全绿（A/B 两模式、死亡作废、requires 门、flush_submit 同批契约逐条同判据）；〔dc2〕九栏目契约断言（system_contracts :74 改址后——单据字典九键+requires/source_unit 逐键同值）；〔dc3〕伤害真链断言继承（round_flow 主角先手/敌方还手/地图账殿后现役断言）。撤销证明见 wr6。 + +### T5 改址收尾＋键账逐键复测（≈0.5d） + +- [ ] 改址扫尾：grep 六旧符号全库零残留（`_grant_routed\|_flush_pending_reveals\|_fx_enqueue_reveal\|\.escrow\b` 于 tests/probe 的成员访问形态；open_ticket 12 参位置形态）——G11 清单逐条对账（≈118 处）。 +- [ ] 键账复测：`python tools/gdstyle_gate.py`——预期基线外新违规 0、恶化 0；六文件 45 键逐键读数记录进实现报告（44 清零＋settlement_table 类变量 1 残留＋宿主残留 8 键达标线核对）。可核查结果：键账对照表在案。 +- [ ] 验证步骤：全套闸按本批改动域选档跑一次全绿（里程碑出口；波内修复只做出红最小单元最窄确认）。撤销证明见 wr7。 + +### T6 撤销证明＋产出物落位卡（≈0.25d，末卡） + +- [ ] 逐 wr 行撤销证明（§8.1 末列——回退对应 hunk→最窄闸红→还原复绿，记录进实现报告）。 +- [ ] 写齐三份产出物（实现报告〔45 键账对照＋改前改后读数＋实机目检总清单〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈4.25d**（区间 4.25–5.0：T2 use_treasure 拆分与三触点、T4 拆分族为上界来源）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 fx 族迁移建件 | battle_fx_host 新件＋宿主接线＋counters_ctx/_fx_emit/enqueue/flush 改址 86 处 | 〔fx1〕揭示管线〔fx2〕桶隔离〔fx3〕空订阅零命中〔T1，round_flow/adventure_feats/settle_segments 改址后〕 | 单元＋集成 | 编排器 begin_battle 真链→挖掘→揭示兑付 | 回退 fx 接线 hunk→fx1 红（`_fx_host` 路径不存在） | +| wr2 grant 族迁移＋12 随迁键收敛 | reward_grant 新件＋att 束改形＋escrow 直读改址 5 处 | 〔rg1〕负向字典直验〔rg2〕escrow 隔离〔T2〕＋T5 gdstyle 键账（12 键清零） | 单元＋集成＋静态 | grant_routed 直调（seal_polarity）＋完整战斗真链（level_shop） | 回退 grant 接线 hunk→rg1 红 | +| wr3 use_treasure 拆分＋三触点分家 | use_treasure 迁 RewardGrant＋_apply_use_kinds 拆分＋treasure_interact ctx 束＋main_ui_build 构造 | 〔rg3〕use_treasure 真链三例〔T2〕＋ui_click_probe 秘宝使用流直跑绿 | 单元＋探针 | C 区槽选→点格使用真链（探针/单测装配） | 回退三触点 hunk→rg3 红（use_treasure 旧路径失配） | +| wr4 段类随动 | 两段三引用＋读写面改指 14 面 | 〔sg1〕同种子逐位一致〔sg2〕段直构〔T3〕 | 集成＋单元 | 完整战斗真链（现役结算断言面） | 回退段构造 hunk→sg2 红 | +| wr5 run() 族拆分 | grant/combat run 拆族＋_judge_seal 两分＋validate 四拆 | 〔sg1〕同种子逐位一致〔sg3〕validate 载荷逐字〔T3〕＋T5 gdstyle 键账（run/_judge_seal/validate 键清） | 集成＋单元＋静态 | 完整战斗真链＋表加载期校验 | 回退拆分 hunk→行为断言恒绿＋gdstyle 对应键读数回升（键账断言红） | +| wr6 damage_controller 拆分＋参数束 | open_ticket spec 束＋拆分族＋inject/fx_calls 束＋改址 16 处 | 〔dc1〕控制器全套〔dc2〕九栏目契约〔dc3〕伤害真链〔T4〕 | 单元＋契约＋集成 | open_ticket→submit→flush 真链（damage_controller_test 装配） | 回退 spec 束 hunk→dc2 红（构造形态缺失） | +| wr7 S7/S8 随动＋改址收尾 | static_scan 两清单＋改址扫尾 | S7/S8 段扫描含两新件零命中＋T5 全套闸按域选档全绿＋键账对照表 | 静态＋全套 | 闸机（工具面） | 回退清单 hunk→S7/S8 红（新文件越集命中/缺位） | +| wr8 产出物 | T6 三份 | 件核〔wr8〕 | — | — | 缺项红 | + +### 8.2 测试削弱申报 + +零（改址＝访问路径改写与 spec 束键值搬运，断言语义与判据逐条保持——契约 9；无任何断言删除/阈值放宽/扫描面缩小）。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝12 随迁键清零逐键核对、S13 基线未改（git diff 查 `tools/gdstyle_baseline.txt` 零变化）、改址断言语义等价抽检（adventure_feats/seal_polarity/damage_controller_test 各 ≥3 处）、两快照出口载荷逐字比对、同种子基线（对拍或 JSONL 按待裁点 1 裁定案）、撤销证明复现。未过不得合并。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 基线对照自核）；测试改址等价写法微调；拆分族仍超阈值时的续拆（按 §7 T4 命名规则）。 +- **L2（记录继续）**：迁移代码注释随迁措辞（语义不变）；spec/att 束键拼装顺序（键集不变）。 +- **L3（停机呈报）**：同种子逐位断言红（对拍非零差异/JSONL diff 非空）；信号顺序或行协议词表漂移；机检键与卡内契约互斥（契约 3）；跨件接线需求与契约 5 冲突（如发现新件必须回调宿主私有族）；S7/S8 与架构文档冲突；attune 族被牵连触碰。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 提交切分与 worktree 分支命名。 +2. 测试改址的等价访问写法（语义不变前提下）。 +3. 迁入代码的注释随迁措辞（语义不变前提下）。 +4. att/spec/ctx/inject 束键拼装的写法细节（键集与缺省不变前提下）。 +5. 拆分族续拆的函数内局部组织（签名与命名规则不变前提下）。 + +## 11. 待裁点 + +1. **PARITY/MC 对拍是否发起**（触面=存档/RNG/结算面，发起权归用户；MC 零数值改动不跑、此处只裁确定性对拍）： + - **案 A（推荐）**：发起实跑对拍——批末设 `PARITY_APPROVED=1` 跑全套闸即实跑，对拍非零差异即红，**不得借机重锚**。理由：重构批最硬的逐位证明，闸机制现成、成本一次跑批。 + - **案 B**：不发起对拍——替代验收＝T0 改前 JSONL 与改后复跑逐行 diff（`sim/dump_battle.gd` 种子矩阵 {42, 779401, 779501}×关卡 {1, 2} 六组）非空即红＋现役同种子逐位断言面（round_flow/seal_polarity/level_shop 全套）全绿。淘汰依据：diff 覆盖面囿于单战斗驱动、不及对拍三变体全冒险口径。 +2. **settlement_table 类变量 18/15 键处置**： + - **案 A（推荐）**：判结构性残留随批保留——18 键全部为 @export 表 schema 数据列（G8），删除或分组即改 .tres 数据件结构、违「现行数值=data/tables 单一事实源」红线；基线持平不红、键账如实记实现报告残留项。 + - **案 B**：强行清零——须改表 schema/迁移 .tres 数据件，超出本卡「结构整改不改数据」边界，若裁此案须退回设计段重裁（本卡不预设执行路径）。 + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 写卡会话）**：①规格覆盖——u1→T1/wr1、u2→T2/wr2、u3→T2/wr3、u4→T3/wr4、u5→T3/wr5、u6→T4/wr6、u7→T1/T5/wr7、u8→T6/wr8，完成定义四条各有落点；②步骤扫描——每步一动作一可核查结果，无「TBD/酌情」行（续拆规则=T4 命名规则、非待定）；③类型一致性——接口块签名与 T 卡引用逐字一致（grant_routed/att 束六键/spec 必载四键/reveal_busy/bonus_delta_drain 名源）；④审查焦点＋改动覆盖——最可能坑玩家面＝RNG 取号序（fx_reveal 迁移点）与行发射序，已挂 fx1/sg1 双断言＋契约 1；文件结构图各行均指到 wr 行；⑤篇幅比例——接口块为签名非实现体，无函数体抄写；⑥落位预检——新增二件与四束各有不能复用理由与唯一落点，与结构图「新增」标记对上。 + +**grilling 自检一轮（2026-10-27，写卡会话对抗视角逐款过）**——阻断 7 条全折入本版：①随迁键收敛与段类随动先后矛盾（先迁移后收敛会在 T1/T2 间留下基线外 NEW 红窗）→ T2 增「迁入形下逐键过阈值」核查步、12 键收敛钉死在 T2；②fx host 类变量超阈漏算（deps+state 初算 16-23>15）→ 接口块重定：nest_count/hp_ratio 等五事实转宿主 facts_cb、fx_counters 两零读者成员删除、ac/reveal 两束收敛，封闭面 14≤15；RewardGrant 同法补 pool_effective_cb 注入（_apply_percent_row 的 _pool_effective 留宿主依赖）、封闭面 15≤15——两件键账红线入契约面；③grant_clear_reward 读宿主私态（_board_from_midround_refresh/perfect_sweep_earned）与禁环冲突 → 签名改三参形（ri/skip_on_refresh/perfect 经实参传入，调用点 grant 段经宿主引用现读）；④对拍替代案不可执行（原写「新增 dump 脚本」违反复用优先）→ 改用既有 `sim/dump_battle.gd`（step_row JSON、关卡/种子两参数——零新码）；⑤两新件构造循环依赖（RewardGrant bundle 持 fx_host、fx_host 兑付需 grant_cb——互为构造前件）→ fx host bundle 减为 7 键＋`bind_grant(cb)` 建后接线（宿主 _init 建 fx_host→建 reward_grant→bind，禁双向环的构造序解法）；⑥改址面封装违规（测试与 main_ui_build 直取 `_fx_host`/`_reward_grant` 私成员）→ 宿主补组件出口 `fx_host()`/`reward_grant()` 两取件方法（姊妹卡 hero()/stop() 先例），全部改址经出口取件；⑦计数与行号订正——改址合计 118→123、grant_segment open_ticket 4→6 处（:76/:112/:125/:154/:192/:206）、settle_segments 段构造行号 :20-21→:20/:22、grant 段随动漏 `oc._fx`（:224 engine 判定）补 G5 与接口块、结构图逐文件计数对齐 G11。建议 3 条折入：level_runner 零改动显式声明（§0）；cross_system_flow/adventure_feats 的 open_ticket 命中定性为 triggers 载荷字符串零改址（G11）；S7/S8 头注计数同步 7→9（T1）。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名：本批迁移面中 fx_counters_round/fx_counters_battle 两零读者成员随迁即删（G2）、12 随迁键以真实拆分/签名改形收敛、禁以「基线计数」「测试便利」等理由在宿主保留任何迁移成员的同名转发或别名；机检键与卡片契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/reports/需求卡片-呈现层结构收敛批-2026-10-27.md b/reports/需求卡片-呈现层结构收敛批-2026-10-27.md new file mode 100644 index 00000000..8388b3a3 --- /dev/null +++ b/reports/需求卡片-呈现层结构收敛批-2026-10-27.md @@ -0,0 +1,349 @@ +# 需求卡片：呈现层结构收敛批（gdstyle 存量债清偿·波 6＋波 8 呈现侧——视图内部拆私有函数＋工厂/参数面收敛） + +- 版本：**v1.0**（写卡会话初稿，自审六查＋grilling 一轮自检记录见 §12） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋待写卡）——**需求性工程条目，证据指认形态**（唯一事实源：[审计-gdstyle存量债清点与清偿方案-2026-10-26.md](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 3 条〔波 6 视图内部拆私有函数、不拆构建步件〕＋第 7 条〔归并裁定：本卡＝波 6（54 键/17 文件）＋波 8 呈现侧 8 文件（17 键）＝71 键〕）；设计段裁定＝纯代码内部收敛、**零设计改动** +- 归属：`game/presentation/` 25 文件（波 6 十七件＋波 8 呈现侧八件）＋消费面随动改址八处（§7 结构图注记）；treasure_interact_controller 已移卡 1（B1 战斗域拆件批），不在本卡 +- 排期：未编入（迭代批卡片；估时 ≈3.5–4.0 个工作日） +- 开工门：U0＋复核门过（§12）；待裁点一项（§11 测量面卫生键处置，裁决前不得开工 T4 对应两件） + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话）**：来源条目＝需求性工程条目（状态行含「文档设计已闭合＋待写卡」；证据指认＝清点报告 §六逐波裁定＋本卡 §3 逐文件实查），放行。设计段闭合凭据（2026-10-26 用户裁）＝①纯代码波写卡前确认零设计改动＋按当时 master 重测读数（已做，见 §3）；②波 6 形态＝视图内部拆私有函数、不拆构建步件；③波 8 呈现侧散条随本卡收编（§六第 7 条归并裁定）。 +- **与迭代 39 卡组的文件交叠（串行义务，呈编排段裁先后）**：iter 39 主卡（冒险域拆件批）触 `level_map_screen.gd`（:334-343 bonus 读面改指 hero）、`hud_presenter.gd`（:20/313 同面）、`curio_interact_controller.gd`（16 处调用改指 stop()）、`main.gd`（装配面）——与本卡四文件重叠。两批无论先后，后开工批 T0 自吸收行号漂移；**禁编入同迭代同波并行**。姊妹副卡（同调配装）触 core 域零叠；技能池触发器卡触 core/data 零叠。 +- 与同事项卡 1（B1 战斗域拆件批：battle_orchestrator/settlement/damage_controller/treasure_interact_controller）、卡 2（核心数据面：core/data 侧）**零文件交叠**。 +- 本卡禁触三宿主（adventure_runner/level_runner/board_view——iter 39 规避清单）；禁触 battle_orchestrator（其行数恶化债 c4c69701 归卡 1 还债）。 + +## 1. 目标与完成定义 + +**目标**：呈现层 25 文件 71 键结构收敛——超长构建/绘制/格式化函数拆私有函数族（波 6 形态裁定）、工厂件公开面与参数族收敛（波 8）、组合根死成员清点、测量面 print 残留处置（随 §11 裁点）。**游戏行为与玩家可见呈现零变化**（契约 1）：本批零行为改动、零新文件、零新公开概念。 + +**改动单元清单**（需求点，逐单元验收行见 §8 对照表；键数＝2026-10-27 实测，与清点报告 §五逐条吻合）： + +| # | 单元（文件） | 现行键（值/阈值） | 改法 | +|---|---|---|---| +| u1 | camp_overlay_view.gd | 类变量 19/15；循环内 new×7；_init 149 行 28 局部（:42）；_rebuild_tree 61 行 21 局部（:222）；_rebuild_forge 72 行 20 局部（:301）；refresh_camp 61 行 17 局部（:386） | _init 拆四柜台构建私有族；_rebuild_*/refresh_camp 拆行板构建私有族；循环体提行板构建私有函数 | +| u2 | level_map_screen.gd | **类变量 22/15（基线登记 21——iter38 恶化债 c4c69701，本卡归绿义务）**；_init 135 行 21 局部（:58）；_draw_graph 78 行 9 分支 27 局部（:423） | _init 拆构建私有族；_draw_graph 拆绘制私有族（节点/通道/底栏）；换层装饰域归并（_node_icons/_noise_rect/_tint_level→一域字典，22→20 归绿） | +| u3 | board_cell_unit.gd | 类变量 31/15；_draw 147 行 29 分支 19 局部（:135） | _draw 拆绘制私有族（底面/接触带/数字徽标/封印/高亮/点迹各域）；类变量改善非清零 | +| u4 | standee_body.gd | 类变量 29/15；循环内 new×2（:268/:296）；_draw 84 行 26 局部（:414） | _draw 拆绘制私有族（立绘/血条/意图/护甲徽标/顺位徽标）；循环体提私有构建函数 | +| u5 | hero_info_panel_view.gd | 循环内 new×2（:55/:189）；_init 74 行（:24）；set_treasure_inventory 57 行 13 局部（:162） | _init 拆段构建私有族；槽位循环体提私有构建函数 | +| u6 | battle_end_overlay.gd | 类变量 20/15；循环内 new×4（:222/:251/:271/:303）；_init 81 行（:31）；open_victory 参数 8/5（:116） | _init 拆行板构建私有族；循环体提私有构建函数；open_victory 可选尾参收拢 opts 字典（4 参） | +| u7 | debug_overlay.gd | 类变量 17/15；_build 124 行 22 局部（:153） | _build 拆五区块构建私有族（探针直引公开面逐字保留） | +| u8 | ui_assembler.gd | 循环内 new（:156）；build_start_overlay 83 行 16 局部（:97） | build_start_overlay 拆列/行构建私有族；立绘循环体提私有构建函数 | +| u9 | battle_stage_view.gd | 循环内 new（:266）；_init 97 行（:27）；_enemy_portrait_tex return 9/6（:233） | _init 拆子视口/世界/壳层构建私有族；_enemy_portrait_tex 改查表＋回退（映射语义零变化） | +| u10 | curio_pick_overlay.gd | _init 52 行（:27）；_icon_for_id return 7/6（:192） | _init 拆构建私有族；_icon_for_id 改查表＋回退 | +| u11 | settings_overlay.gd | _build 77 行 13 局部（:31） | _build 拆行构建私有族 | +| u12 | battle_log_view.gd | _format_row 68 行 21 局部 13 return 9 分支（:144） | _format_row 按行型拆私有格式化函数族（iter38 卡⑥类型修复后现行形态为准） | +| u13 | curio_interact_controller.gd | 类变量 18/15 | 改善非清零：交互态域真实归并顺带下降（iter39 主卡将改其调用面——串行注记 §0） | +| u14 | ap_bar_view.gd | _init 69 行（:34） | _init 拆构建私有族（源码锚句逐字保留） | +| u15 | board_zone_view.gd | _init 59 行（:21） | _init 拆构建私有族 | +| u16 | board_fx_view.gd | 循环内 new（:93） | play_perfect_sweep 循环体提私有 band 构建函数 | +| u17 | legend_overlay.gd | 循环内 new×2（:35/:37） | ENTRIES 循环体提私有行构建函数 | +| u18 | ui_kit.gd | 公开方法 26/20；beams_rect 13 局部（:333）；modal_shell 参数 6（:453）；BCard._init 参数 6（:752）；bcard 参数 6（:812） | ①删零消费 frame_skinned（:566）/verb_button（:662）②私有化 modal_dim/beams_rect/gradient_base/switch_toggle（消费方全在本卡触面文件或单条测试行随动；load_font 保留公开——探针三行直引，收敛算术不需要它）→26→20 ③modal_shell 尾参哨兵收拢（6→5）④BCard._init/bcard 可选尾参收拢 opts（6→5）⑤beams_rect 像素循环拆私有函数 | +| u19 | hud_presenter.gd | refresh 参数 8（:14）；_refresh_out_of_battle 参数 6（:147）；tune_sim_report 参数 10（:188） | refresh/_refresh_out_of_battle 运行态尾参收拢 ctx 字典（4 参）；tune_sim_report 统计束收拢（5 参）；文案逐字不变 | +| u20 | curio_flow_context.gd | 类变量 16/15；_init 参数 16/5（:25） | 参数与成员按域收拢三束（views/getters/flow 字典）→ 4 参 4 成员 | +| u21 | camp_flow_context.gd | _init 参数 12/5（:21） | 同 u20 三束收拢 → 4 参 | +| u22 | battle_narrator.gd | bonus_card_text return 9/6（:100） | match 分支拆私有文案函数/查表（文案逐字不变，现役单测断言零改动） | +| u23 | tune_sim_controller.gd | print 残留（:43）；循环内 await（:65）；run 11 局部（:36） | 统计六成员收拢一 stats 字典（与 u19 束同构）→≤10 局部；print 与 await 处置随 §11 裁点 | +| u24 | playtest_logger.gd | print 残留×2（:160/:161） | 处置随 §11 裁点 | +| u25 | main.gd | 类变量 49/15 | 逐成员消费方对账（产品码＋probe/sim/tests＋字面量断言面），零消费成员删除；探针一级句柄面零迁移（architecture「三屏壳与组合根句柄面」条款）——改善非清零口径 | + +**完成定义**： +1. u1–u25 落地；`python tools/gdstyle_gate.py` 读数：**基线外新违规（NEW）＝0**；**恶化（WORSENED）＝1 条且仅为 battle_orchestrator 行数（卡 1 义务，不归本卡）**——level_map_screen 类变量恶化债归绿（≤21）；71 键中 62 键清偿（键消失）、9 键残留基线内绿（§8.4 账目）。 +2. 呈现逐像素零变化：§7 T0 建锚面（甲/乙/丙三组）改后对拍全 0.00%。 +3. 现役全套断言面绿：探针面（含源码锚字面量契约）与单元/集成套件零红、零删改（契约 5）。 +4. 撤销证明逐行落地（§8 对照表末列）；三份产出物写齐（T5）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | [审计-gdstyle存量债清点与清偿方案-2026-10-26.md](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 3 条 | 波 6 形态＝视图内部拆私有函数、**不拆构建步件**（main_ui_build 先例动机是组合根超限，普通视图不类比——2026-10-26 用户裁） | +| D2 | 同上 §六第 7 条 | 归并裁定：本卡＝波 6＋波 8 呈现侧 8 文件＝71 键；treasure_interact_controller 归卡 1 | +| D3 | 同上 §三波次表＋§四纪律 | 改前建 golden 基线或对拍 0.00%；基线禁改禁 refresh；还债＝数值下降自然绿；呈现零变化 | +| D4 | [architecture](../design/engineering/architecture/architecture.md) v1.18「三屏壳与组合根句柄面」节（:181） | 探针挂载假设 `main.X` 路径零迁移 | +| D5 | 本卡 §3 逐文件实查（2026-10-27，master 8b146321） | 现状行号与键值；**逐文件实查确认不触碰任何 owner 契约（GDD 零修订预期）——实现段查到触碰点立即停笔呈报，禁内联求裁** | + +## 3. 现状事实（2026-10-27 写卡会话实测于 master 8b146321；开工日 T0 复核行号） + +**S13 读数**（`python tools/gdstyle_gate.py`）：命中 216 条／基线内 216／基线外新违规 0／恶化 2（battle_orchestrator 文件行数 1314>1302＝卡 1 义务；level_map_screen 类变量 22>21＝**本卡还债义务**，iter38 卡① _layout_cache 缓存成员特批带红挂账 c4c69701）。25 文件逐文件读数见 §1 改动单元清单（gdstyle v0.4.0 实测，与清点报告 §五 2026-10-26 读数逐条吻合、行号为本次实测）。 + +**探针与测试直引面**（重构冻结面，逐条实测）： + +| # | 事实 | 出处 | +|---|---|---| +| S1 | debug_overlay 公开面被 8 探针＋系统测试直引：set_sliders/effect_text/press_apply_for_probe/press_reset_for_probe/press_simulate_for_probe/set_sim_count/visible/get_index/seed_edit；ui_tune_probe 另有**源码契约**：debug_overlay.gd 源码禁含 "create_t"/"UiKit.motion" token（零动效契约）＋子树零 AnimationPlayer | `game/probe/ui_tune_probe.gd:46-67/225-239`；`game/tests/system_test.gd:204/228/258` | +| S2 | camp_overlay_view **双重源码契约**：ui_struct_probe 源扫描 `count("UiKit.STONE") == count("UiKit.STONE_DEEP")`（裸 STONE 禁令）；theme_projection_test 源锚 `custom_minimum_size = Vector2(0, 336)` 恰 3 处、`size_flags_vertical = Control.SIZE_FILL` 恰 4 处、`SIZE_SHRINK_CENTER` ≥3 处 | `game/probe/ui_struct_probe.gd:46-50`；`game/tests/unit/presentation/theme_projection_test.gd:722-730` | +| S3 | camp_overlay 探针直引成员：_tree_buy_btns/_tree_fork_btns/_workshop_holder/_workshop_rows/_balance_label＋refresh_camp/closed/visible | `game/probe/ui_click_probe.gd`、`ui_probe.gd`、`screen_flow_probe.gd`（grep 实测） | +| S4 | settings_overlay 探针直引：retarget/_motion_btn/_volume/find_button 面；legend_overlay：visible/close/get_index＋player_copy_sweep_test 直构 `.new()`＋`ENTRIES` 常量消费＋smoke_boot `main.get("legend_overlay")` | `game/probe/ui_click_probe.gd:286-343`；`game/tests/unit/presentation/player_copy_sweep_test.gd:69-71`；`game/tests/smoke_boot.gd:76` | +| S5 | ap_bar/log_view/info_panel/level_screen/stage/_end_overlay/board_zone/curio_overlay 探针直引成员与方法面（含私有成员 _cand_ids/_hover_id/_btn_stop/_log/_summary/_curio_section/_gp_val 等）逐条在案：press_candidate/status_badge/route_chosen/abandon_btn/press_card/press_confirm/press_continue/open_pick/is_open/verdict_text/continue_pressed/_btn_legend/_btn_stop/_dots/is_refresh_ready/confirm_visible/press_refresh_for_probe/press_confirm_for_probe/refresh_remaining_text/parsed_text/mode/armor_text/attack_text/item_slots/hero_standee/enemy_body_at/enemy_box/round_label/status_badge/legend_toggled/toast | `game/probe/` 八探针 grep 实测（深访问清单已录实现报告素材口径，T0 复核） | +| S6 | standee_body 直构面：fx_probe `new("enemy")`/box/set_data/set_pending/intent_probe()；standee_fx_sweep_test preload 直构；theme_projection 源锚四句（GOLD_BRIGHT 顺位行/HERO_BLUE_BRIGHT/GOLD_BRIGHT 护甲/`_intent_charge = pid in CHARGE_SKILL_IDS`＋GOLD_DEEP 旧判据禁句） | `game/probe/fx_probe.gd:15-30`；`game/tests/unit/presentation/theme_projection_test.gd:689-696` | +| S7 | ap_bar_view 源锚：`UiKit.label("",UiKit.FS_CAPTION, false, UiKit.STONE_DEEP)` 逐字在位＋"STONE_FAINT" 全文零命中 | `game/tests/unit/presentation/theme_projection_test.gd:696-700` | +| S8 | ui_kit 工厂消费方普查（逐方法 grep 产品码＋probe/sim/tests，2026-10-27 实测）：**零消费＝frame_skinned/verb_button**（仅注释提及）；消费方全在本卡触面＝modal_dim（camp:45）/beams_rect（ui_assembler:104＋theme:639）/gradient_base（level_map:65＋theme:664）/switch_toggle（settings_overlay:76/:91）；测量面直引（保留公开）＝load_font＋FONT_UI（board_shot_probe:49/type_glow_shot_probe:71/ui_font_asset_test:15）；跨面消费（保留公开）＝label 137/motion 96/panel_flat 35/load_tex 35/button 44/modal_shell 9/panel_skinned 9/primary_button 7/glow 族 7/keystone_badge 5/page_shell 5/scaled 5/vignette_rect 4/tg_band 3/backdrop_tile 3/danger_button 3/icon_rect 2/bcard 2＋static var motion_scale（探针 15 处直引）/victory_fx_style | `game/presentation/views/ui_kit.gd:566/662/333/453/752/812`；grep 普查表（T0 存档） | +| S9 | ui_kit **扫描契约**：ui_contrast_probe 全 presentation 递归扫描——裸 `Color8(` 计数逐文件对空白名单（ui_kit 本体为合法定义面）、素材 preload 红线＝0；theme T5② 源锚 `UiKit.panel_flat(SLOT_BACKDROP_SOFT, PANEL_BORDER, 0, 1)`；V4 四文件（ui_kit/ui_assembler/settings_overlay/debug_overlay）源码零 "styled_slider/tooltip_theme/_tip_theme/overlay.theme" token；theme V1-V3 直接调用 button()/vignette_rect()/beams_rect()/gradient_base() 做 Linear 白名单断言 | `game/probe/ui_contrast_probe.gd:164-195`；`game/tests/unit/presentation/theme_projection_test.gd:524-535/584-668` | +| S10 | main.gd 类变量 49 个（:61-148 实数）；探针 `main.X` 一级句柄直引 46 名（run_scope/level_screen/debug_overlay/camp_overlay/settings_overlay/legend_overlay/ap_bar/log_view/info_panel/board_zone/stage/curio_overlay/_end_overlay/_start_overlay/save_select_overlay/career_overlay/status_panel/shop_overlay/node_overlay/board_view/db/meta/save_manager/settings_store/debug_badge/LAYER_CONTRACT/_modals/_deferred_modal/_confirm_consumer/_row_queue/_row_pacer/_settlement_stop_pending/_inter_overlay/_battle_root/_menu_screen/_camp_screen/_adventure_screen/_treasure_ui/_bonus/_camp_pres/_modal_flow/_tune_sim/_debug/_debug_entry/_seed_edit/confirm_dialog 等——46 名全量清单 T0 存档）；装配拆件经 root 显式传参消费 main 成员（main_ui_build/main_*_flow 五件） | `game/presentation/main.gd:61-148`；`game/probe/` 12 探针 grep 实测 | +| S11 | hud_presenter 单调用面：refresh 唯一产品消费方＝main.gd:810；tune_sim_report 唯一消费方＝tune_sim_controller.gd:67；hud_presenter_test 直测静态族（feat_holdings_lines 等）不经 refresh；**核心读取只走 settlement.presentation_snapshot() 成文快照面（头注纪律）** | `game/presentation/main.gd:810`；`game/presentation/tune_sim_controller.gd:67`；`game/presentation/hud_presenter.gd:1-14` | +| S12 | flow context 单装配面：CurioFlowContext 构造＝main_ui_build.gd:132（16 参 lambda 束）；CampFlowContext 构造＝main_ui_build.gd:152（12 参）；成员消费＝curio_interact_controller（ctx.X 读 16 处）/camp_shop_presenter（:23-34 读 12 处） | `game/presentation/main_ui_build.gd:130-153`；`game/presentation/curio_interact_controller.gd:31`；`game/presentation/camp_shop_presenter.gd:21-34` | +| S13 | open_victory 现行 8 参（:116-117）；消费方 8 处——传可选参者 5 处须随动（main.gd:454/:459 八参、main_adventure_flow.gd:100/:166 四参、ui_struct_probe 四参），三参调用 3 处（fx_probe:53/standee_fx_sweep_test×2/curio_interact:107）缺省兼容零改动；open_defeat 不在收编账目零触碰 | grep 实测（§8 wr 行） | +| S14 | 测量面：playtest_logger print 两行（:160/:161——诊断转储路径与上下文 JSON）；同路径信息已由 toast 承载（main_debug_flow.gd:16 `show_toast("已转储诊断: "+path)`）且转储 JSONL 文件本身落盘；tune_sim_controller print 一行（:43 日志路径）＋循环内 await（:65 逐帧让出驱动浮窗进度刷新）；playtest_logger 被 4 个 sim 驱动件构造消费（adventure_monte_carlo:104/rhythm_batch:21/level_autoplay:40,118/verifier_batch:41） | `game/presentation/playtest_logger.gd:160-161`；`game/presentation/tune_sim_controller.gd:43/65`；`game/presentation/main_debug_flow.gd:15-16` | +| S15 | golden 现行基线集五张：棋盘三图（900×760 裁剪区）/menu_boot（全屏）/level_map（全屏，iter38 卡①改前建锚先例——对拍经 golden_compare 直跑，render_gate 现行只对拍棋盘三图＋menu_boot）；shot_probe 七屏帧（menu/settings/career/camp/level/battle/status）；加严口径＝棋盘三图裁剪区内差异一律判失效 | `game/tests/golden/README.md`；`tools/render_gate.sh` | +| S16 | level_map_screen 探针冻结成员：_cand_ids（ui_struct/ui_click）/ _hover_id、_content_size（ui_input）/ display_probe()→_drawn_disp（绘制记录唯一读出）/ layout_probe()（缓存判同实例断言 V1/V2）——_layout_cache 本体不经成员直读 | `game/probe/ui_struct_probe.gd:157/289`、`ui_input_probe.gd:109/152`、`ui_click_probe.gd:491-492`；`game/tests/unit/presentation/level_map_info_fog_test.gd:199-230` | + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 呈现零变化**：一切视图/工厂/投影改动像素级零变化——§7 T0 建锚面改后对拍差异非零即红（golden 逐像素）；文案拼装逐字不变（battle_narrator_test 等现役断言零改动）；信号面、`main.LAYER_CONTRACT` 层序合同、模态编排（ModalFlow/ModalStack）、装配序零触碰。 + +🔴 **契约 2 · 探针断言面禁削弱**：S1–S7/S9/S10/S16 所列探针直引公开面（方法/成员/常量/信号）逐字保留——**私有化、改名、搬文件均不进口径**；源码锚字面量契约（camp STONE 等式与三组计数锚、ap_bar 锚句、standee 四句、debug 三句、V4 token 禁令、ui_contrast Color8/preload 扫描）随拆分逐字保持——拆分只许把锚句整行原样留在文件内，禁改写措辞、禁换行重排锚句。测试与探针随动仅限消费面迁移（访问路径改写），断言语义与判据逐条保持。 + +🔴 **契约 3 · main.X 句柄面零迁移**（architecture :181）：main.gd 成员收敛只许删除逐成员对账零消费的成员；探针直引 46 名与装配拆件消费成员一个不删不改名；`main.LAYER_CONTRACT` 常量零触碰。 + +🔴 **契约 4 · S13 纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh（还债＝数值下降自然归绿，残留键基线内不判红）；本批不得引入基线外新违规——**拆出的每个私有函数自身在阈值内**（≤50 行/≤10 局部/≤8 分支/≤6 return/≤5 参数），批末 gate NEW=0 是验收判据；机检键与本卡契约互斥时一律停卡呈报，禁自造第三条路。 + +🔴 **契约 5 · 测试削弱申报＝零**：现役断言（单元/集成/探针/源码锚）零删除、零放宽、零缩小扫描面；测试直构面的随动改址只改访问路径；实现期任何「顺手简化断言」判红。 + +🔴 **契约 6 · 波 6 形态裁定**：视图内部拆私有函数，**不拆构建步件**——禁新建任何 .gd 文件（D1）；拆分零行为变化、零新信号、零新公开成员（ui_kit 净 −6 公开方法是唯一减面）；私有函数命名与归属属代拍板白名单（§10）。 + +🔴 **契约 7 · 恶化债归绿**：level_map_screen 类变量拆分后 ≤21（gdstyle 判红线以下）；归并手段＝真实同域成员收编（u2 换层装饰域三成员一字典），**禁为计数造转发属性/别名/空壳成员**（§13）。 + +## 5. 范围边界 + +**做**：u1–u25；消费面随动改址八处（§7 结构图注记行）；T0 锚面采集；撤销证明；产出物。 + +**不做**（去向明示）： +- 三宿主（adventure_runner/level_runner/board_view）→ iter 39 主卡；battle_orchestrator/settlement/damage_controller/treasure_interact_controller → 卡 1；core/data 侧 86 键 → 卡 2；波 7 现成卡与波 0 基线 refresh → 各自通道（本批禁自行 refresh，契约 4）； +- **不拆构建步件**（main_ui_build 分步形态不类比到普通视图——D1）；不新建任何文件；不动 open_defeat 与任何清单外公开方法语义； +- 残留 9 键（类变量大户 7＋await 1＋main 1，§8.4）→ 键留基线内绿，iter39 合回后尾波重新清点处置；清偿读数与豁免理由记实现报告； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）；MC/对拍锚零触碰（数值与 RNG 零改动＝零 MC，纪律 §四.4）； +- user 目检项登记不阻塞（§8.2）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `game/tests/golden/README.md` | 乙组新建基线（camp/settings/battle 帧）判定记录＋甲组判读记录 | 批内机械同步（game 内 .md，非禁写面） | +| `game/tests/验证集清单.md` | 测试直构面随动改址不改断言语义与数量——预期零变化；若实现期补静态判据则机器提取重生成（tools/extract_checks.py） | 批内机械同步（game 内 .md，非禁写面） | +| `design/engineering/architecture/architecture.md` | 预期零修订——零新件、模块归属表零行变化、组合根句柄面条款不受影响；ui_kit 公开面收敛不动模块表（无 ui_kit 独立行） | 反哺点 · 列清单（预期零改动注记；实现中若发现表述漂移逐条列） | +| `待办清单.md` | 来源条目状态推进（写卡段回写归主会话；实现批收尾归 batch-closure） | 反哺点 · 列清单 | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/presentation/views/camp_overlay_view.gd` | u1 拆私有函数族（复用既有·修改） | 非行为 → wr1 | +| `game/presentation/views/level_map_screen.gd` | u2 拆私有函数族＋换层装饰域归并（复用既有·修改） | 非行为；**恶化债归绿** → wr2 | +| `game/presentation/views/board_cell_unit.gd` | u3（复用既有·修改） | 非行为 → wr3 | +| `game/presentation/views/standee_body.gd` | u4（复用既有·修改） | 非行为 → wr4 | +| `game/presentation/views/hero_info_panel_view.gd` | u5（复用既有·修改） | 非行为 → wr5 | +| `game/presentation/views/battle_end_overlay.gd` | u6 拆私有＋open_victory 4 参化（复用既有·修改） | 非行为（签名收拢缺省兼容）→ wr6 | +| `game/presentation/views/debug_overlay.gd` | u7（复用既有·修改） | 非行为 → wr7 | +| `game/presentation/ui_assembler.gd` | u8（复用既有·修改） | 非行为 → wr8 | +| `game/presentation/views/battle_stage_view.gd` | u9（复用既有·修改） | 非行为 → wr9 | +| `game/presentation/views/curio_pick_overlay.gd` | u10（复用既有·修改） | 非行为 → wr10 | +| `game/presentation/views/settings_overlay.gd` | u11（复用既有·修改） | 非行为 → wr11 | +| `game/presentation/views/battle_log_view.gd` | u12（复用既有·修改） | 非行为 → wr12 | +| `game/presentation/curio_interact_controller.gd` | u13 域归并＋ctx 束读随动（复用既有·修改） | 非行为 → wr13 | +| `game/presentation/views/ap_bar_view.gd` | u14（复用既有·修改） | 非行为 → wr14 | +| `game/presentation/views/board_zone_view.gd` | u15（复用既有·修改） | 非行为 → wr15 | +| `game/presentation/views/board_fx_view.gd` | u16（复用既有·修改） | 非行为 → wr16 | +| `game/presentation/views/legend_overlay.gd` | u17（复用既有·修改） | 非行为 → wr17 | +| `game/presentation/views/ui_kit.gd` | u18 公开面收敛＋参数收拢（复用既有·修改） | 非行为（消费面随动改址承载撤销证明）→ wr18 | +| `game/presentation/hud_presenter.gd` | u19 参数束收拢（复用既有·修改） | 非行为 → wr19 | +| `game/presentation/curio_flow_context.gd` | u20 三束收拢（复用既有·修改） | 非行为 → wr20 | +| `game/presentation/camp_flow_context.gd` | u21 三束收拢（复用既有·修改） | 非行为 → wr21 | +| `game/presentation/battle_narrator.gd` | u22（复用既有·修改） | 非行为 → wr22 | +| `game/presentation/tune_sim_controller.gd` | u23 stats 束＋裁点处置（复用既有·修改） | 非行为（print 删除＝stdout 诊断文本，随裁点）→ wr23 | +| `game/presentation/playtest_logger.gd` | u24 裁点处置（复用既有·修改） | 非行为（随裁点）→ wr24 | +| `game/presentation/main.gd` | u25 死成员清点删除＋refresh/open_victory 调用随动（复用既有·修改） | 非行为（零消费成员删除）→ wr25 | +| 随动·`game/presentation/main_ui_build.gd` | u20/u21 两构造行改束传参（清单外单行随动） | 非行为 → wr20/21 | +| 随动·`game/presentation/camp_shop_presenter.gd` | u21 ctx 束读改址 12 处（清单外随动） | 非行为 → wr21 | +| 随动·`game/presentation/main_adventure_flow.gd` | u6 open_victory 四参调用改址 2 处（清单外随动） | 非行为 → wr6 | +| 随动·`game/presentation/shop_overlay_view.gd` | u18 bcard 五参调用改址 1 处（清单外随动） | 非行为 → wr18 | +| 随动·`game/presentation/views/node_overlay.gd`／`status_panel.gd`／`confirm_dialog.gd`／`settlement_review_overlay.gd` | u18 modal_shell 尾参改址各 1 处（清单外随动） | 非行为 → wr18 | +| 随动·`game/probe/fx_probe.gd` | u6 open_victory 四参改址 1 处（测量面随动） | 非行为 → wr6 | +| 随动·`game/probe/ui_struct_probe.gd` | u6 open_victory 四参改址 1 处（测量面随动） | 非行为 → wr6 | +| 随动·`game/tests/unit/presentation/theme_projection_test.gd` | u18 beams/gradient 私有化改址 2 处（断言语义不变） | 断言面随动 → wr18 | + +（零新增文件；私有函数族随各宿主文件内新增——落位预检见下节。） + +### 接口块 + +**T0 产出（T1–T5 取用）**：①改前 S13 读数表（25 文件 71 键现行值 `文件|规则|函数 = 值`，实现报告素材）；②golden 锚三组（甲组在库基线判读记录；乙组 camp/settings/battle 三帧基线入 `game/tests/golden/`＋README 判定记录；丙组 battle_end/curio_pick/legend/debug 直构改前帧——落临时区，批末退役）。 + +**u18 ui_kit 新形态**（T3 落地，wr18 断言取用）： + +```gdscript +# 删除：frame_skinned / verb_button（全库零消费，S8 普查凭据） +# 私有化（改名加下划线，消费方随动）：_modal_dim / _beams_rect / _gradient_base / _switch_toggle +# （load_font 保留公开——board_shot/type_glow 探针与 ui_font_asset_test 三行直引，收敛算术不需要它） +# 公开方法 26→20（≤阈值，键清偿） +const PANEL_DEFAULT := true # modal_shell 面板哨兵（非 StyleBox 实例） +static func modal_shell(parent: Control, dim_color: Color, min_size := Vector2.ZERO, + separation := 12, panel_sb = null) -> Dictionary +# panel_sb == null → 无面板（原 with_panel=false） +# panel_sb == PANEL_DEFAULT → 默认样式盒面板（原 with_panel=true+panel_sb=null——settlement_review 形态） +# panel_sb is StyleBox → 自定义样式盒面板（原双参形态） +static func bcard(title: String, desc: String, band: Color, icon_path: String, opts := {}) -> BCard +# opts 键 {price: String = "", footnote: String = ""}——BCard._init 同形收拢（6→5 参） +``` + +**u19 hud_presenter 新签名**（T3/T4 取用）： + +```gdscript +static func refresh(stage: BattleStageView, info: HeroInfoPanelView, ap_bar: ApBarView, ctx: Dictionary) -> void +# ctx 五键：{settlement, runner, level_active: bool, db, refresh_remaining: int}（原 :14 尾五参收拢） +static func _refresh_out_of_battle(stage: BattleStageView, info: HeroInfoPanelView, ap_bar: ApBarView, ctx: Dictionary) -> void +static func tune_sim_report(n: int, atk_pct: int, hp_pct: int, stats: Dictionary, base_hp: int) -> String +# stats 六键：{wins: int, dmg_all: Array, hp_left_win: Array, hp_boss: Array, rounds_all: Array, death_nodes: Dictionary} +``` + +**u20/u21 flow context 新形态**（T4 取用）： + +```gdscript +# CurioFlowContext / CampFlowContext 同形： +func _init(db_ref, views: Dictionary, getters: Dictionary, flow: Dictionary) -> void +# views = {curio_overlay, end_overlay, board_view, toast}／camp 侧 {camp_overlay, shop_overlay, toast, start_overlay, logger} +# getters = {meta_get, save_get, adventure_get, runner_get, adventure_mode_get}／camp 侧 {meta_get, save_get, runner_get}（Callable 活引用——禁快照语义不变） +# flow = {open_modal, open_modal_after_playback, close_modal, refresh_presentations, fatal_screen, gp_summary}／camp 侧 {open_modal, close_modal, refresh_presentations} +``` + +**u6 battle_end 新签名**：`open_victory(verdict_line: String, continue_label: String, board_rect: Rect2, opts := {}) -> void`，opts 键 `{gp_summary: String = "", ks_summary: String = "", bonus_summary: String = "", gp_gain: int = -1, gp_total: int = -1}`。 + +**T 卡间接口**：T0 产出锚面与读数表（全部卡取用）；T1 产出 level_map 归绿读数（T5 复核取用）；T3 产出 ui_kit/hud_presenter 新签名（T4 tune_sim stats 束按 u19 stats 六键构造）；各卡验收随卡落地。 + +### 落位与可复用性预检 + +| 新增件 | 复用面（为何不能复用既有） | 唯一面 | 分层与交互 | +|---|---|---|---| +| 各宿主文件内私有函数族（约 60–80 个私有函数，随拆分产生） | **零新增文件、零新增公开件**——全部落既有宿主文件内（契约 6）；私有函数非「新增件」意义上可复用单元：它们是被拆函数的原文分段，禁抽共享骨架（波 2 同款裁定精神：13 文件结构各异，强行归一有抽象层风险） | 每个私有函数唯一归属其宿主视图；禁把 helper 散落到别的文件（波 6 形态裁定） | 视图内部自调用，零跨层交互新增；Core 零 UI 不破（本批零触 core/）；随机零消费、ConfigDB 读面零新增 | +| golden 三帧基线（乙组 camp/settings/battle） | 复用 shot_probe 现成七屏帧采集面与 golden_compare.py 判据（iter38 卡① 手法）——不扩 golden_baseline_refresh.sh（工具改动超本批面） | 三帧各一，落 `game/tests/golden/`＋README 判定记录 | 采集＝探针隔离档（无断点＋出厂设置 1280）；对拍判据复用现行容差 | +| u18 `PANEL_DEFAULT` 哨兵常量 | modal_shell 六参收拢的最小形态——拆分两个函数会 +1 公开方法破 20 收敛（S8 收敛算术），哨兵是唯一不加方法的收拢形态 | 常量唯一，定义于 ui_kit | 纯 ui_kit 内部判别语义，消费方仅改传参形态 | + +### T0 事实坐实＋改前锚面采集（≈0.4d，**时点铁序：本卡全部锚面采集先于一切生产码改动**） + +- [ ] 复核 S1–S16 行号与直引清单（吸收 iter39 批漂移——若 iter39 已合回，u2/u13/u19/u25 相关行号重定位）；产出探针直引 46 名全量清单与 ui_kit 消费方普查表存档实现报告素材。可核查结果：复核清单在案。 +- [ ] 产出改前 S13 读数表（71 键现行值逐键）。可核查结果：读数表进实现报告素材。 +- [ ] **甲组判读**（在库 golden 五张）：跑渲染闸对拍段＋golden_compare 直跑 level_map——棋盘三图/level_map/menu_boot changed 全 0.00% 方可动码（棋盘三图按加严口径裁剪区内差异一律停机呈报）。可核查结果：判读记录进 golden/README 判定记录节。 +- [ ] **乙组建锚**（无在库基线三屏）：改前采集 shot_probe 的 camp/settings/battle 三帧→各自连采两轮逐像素比对实测跨跑次一致性＝0.00%→直拷落盘 `game/tests/golden/`（文件命名属代拍板白名单 §10.2，随 README 判定记录登记）＋README 判定记录（改前建锚、触发原因＝呈现层结构收敛批对拍锚）。**battle 帧若两轮比对非 0.00%（动效相位不确定）→ 该屏锚降级丙组直构对拍**，判定记录写明。可核查结果：三帧基线或降级注记在案。 +- [ ] **丙组改前帧**（模态/覆盖层四件）：临时抓帧脚本（--script 或临时场景，直构 battle_end_overlay.open_victory/curio_pick_overlay.open_pick/legend_overlay.open/debug_overlay 构建态，落 mktemp 临时区，禁入 git、批末退役）；同法采集改前帧存档。可核查结果：四件改前帧与采集脚本在案（脚本禁入 git）。 + +### T1 营地与地图面拆分（≈1.0d） + +- [ ] u1 camp_overlay_view：_init 拆四柜台构建私有族、_rebuild_tree/_rebuild_forge/refresh_camp 拆行板构建私有族、七处循环体提私有构建函数；源码锚句（S2 两组）整行原样保留。可核查结果：gdstyle 单文件复扫该文件键仅剩类变量 1 键；ui_struct camp 源扫描绿；theme camp 三锚绿。 +- [ ] u2 level_map_screen：_init/_draw_graph 拆私有族；换层装饰域归并（_node_icons/_noise_rect/_tint_level→`_layer_decor` 域字典，22→20）；S16 冻结成员与 layout_probe/display_probe 行为逐字不变。可核查结果：单文件复扫类变量 ≤21（恶化债归绿）；level_map_info_fog_test 全绿（V1/V2 缓存断言继承）；level_map golden 对拍 0.00%。 +- [ ] u3/u4 board_cell_unit＋standee_body：_draw 拆绘制私有族、循环体提私有构建函数；standee 源锚四句（S6）逐字保留、fx_probe 直构面回归绿。可核查结果：两文件函数级键全清；standee_fx_sweep_test＋theme 源锚段绿。 +- [ ] 验证步骤：甲/乙组对应锚复拍（board 三图＋level_map＋camp＋battle 帧）全 0.00%；波内出红只跑红件最小单元。 + +### T2 战斗屏与覆盖层拆分（≈1.0d） + +- [ ] u5/u6/u7：hero_info_panel（段构建私有族＋槽位循环提函数）、battle_end_overlay（行板私有族＋open_victory 四参化——S13 五处传参消费点按接口块改址）、debug_overlay（五区块私有族——S1 全部公开面与源码契约零触碰）。可核查结果：三文件函数级键全清（battle_end 类变量键除外）；ui_tune/debug 系探针直跑绿；ui_struct/丙组 battle_end 对拍 0.00%。 +- [ ] u8–u12：ui_assembler（build_start_overlay 拆列/行私有族＋立绘循环提函数）、battle_stage_view（拆构建私有族＋_enemy_portrait_tex 查表化）、curio_pick_overlay（拆构建＋_icon_for_id 查表化）、settings_overlay（拆行私有族）、battle_log_view（_format_row 按行型拆私有格式化族）。可核查结果：五文件函数级键全清；ui_struct/丙组 curio_pick/settings 帧对拍 0.00%；reward_overlay_test/player_copy_sweep_test/theme 源锚段绿。 +- [ ] u14–u17：ap_bar（拆构建私有族，S7 锚句逐字保留）、board_zone（拆构建私有族）、board_fx（循环体提 band 构建函数）、legend（ENTRIES 循环提行构建函数）。可核查结果：四文件键清；ui_probe/ui_click ap_bar 直引面回归绿；fx_probe 直构面绿。 +- [ ] 验证步骤：乙组 battle/settings 帧＋丙组四件对拍全 0.00%；波内出红只跑红件最小单元。 + +### T3 装配与工厂件收敛（≈0.75d） + +- [ ] u18 ui_kit 按接口块落地五步：删 frame_skinned/verb_button→私有化四件（消费方改址：camp:45/ui_assembler:104/level_map:65/settings:76/:91＋theme:639/:664）→modal_shell 哨兵收拢（八消费点改址）→BCard._init/bcard opts 收拢（curio_pick:99/shop_overlay:212 改址）→beams_rect 像素循环拆私有函数。可核查结果：单文件复扫公开方法 ≤20（键清偿）、参数键全清；theme V1–V3/T5② 段绿；ui_contrast 扫描段绿（ui_kit 素材 preload=0、Color8 面零外溢）。 +- [ ] u19 hud_presenter 按接口块三签名收拢；消费方改址＝main.gd:810（ctx 五键）＋tune_sim_controller:67（stats 六键）。可核查结果：参数键三键清；hud_presenter_test＋system_test 呈现段绿；refresh 后呈现与改前逐帧同像（battle golden 帧 0.00%）。 +- [ ] u25 main.gd 死成员清点：逐成员 grep 对账表（产品码＋probe/sim/tests＋字面量断言面），**零消费成员才删除**——对账表进实现报告；探针直引 46 名与装配拆件消费成员零触碰（契约 3）。可核查结果：类变量读数下降（改善非清零）；12 探针＋system_test 全绿（main.X 零迁移实证）。 +- [ ] 验证步骤：全套闸按改动域选档跑一次全绿（里程碑步出口）。 + +### T4 交互与上下文件＋测量面裁点（≈0.45d） + +- [ ] u20/u21 flow context 三束收拢（接口块形态）；消费方改址＝main_ui_build 两构造行＋curio_interact_controller 16 处 ctx 读＋camp_shop_presenter 12 处 ctx 读（束键访问改写，零语义变化）。可核查结果：curio_flow_context 类变量 16→4、_init 4 参（两键清偿）；camp_flow_context _init 4 参（键清偿）；ui_click/ui_struct 三选一与营地段回归绿。 +- [ ] u13 curio_interact_controller 交互态域真实归并（类变量改善非清零）＋u22 battle_narrator bonus_card_text 拆私有文案族（battle_narrator_test 零改动全绿）。可核查结果：两文件读数改善在案；battle_narrator_test 绿。 +- [ ] u23/u24 测量面处置按 §11 裁点结果执行（stats 束收拢两件 print 处置；await 处置随裁点）；tune_sim 链路回归＝ui_tune_probe 批量模拟段直跑绿（wall-clock/进度语义按裁点保持）。可核查结果：tune_sim/playtest 两文件键读数与裁点一致。 +- [ ] 验证步骤：全套闸按改动域选档跑一次全绿。 + +### T5 撤销证明＋产出物落位卡（≈0.4d，末卡） + +- [ ] 逐 wr 行撤销证明（§8.1 末列——读数对拍类：回退该文件 hunk→对照 T0 读数表该文件键读数回升＝红→还原复绿；消费面迁移类：回退生产 hunk→随动消费方调用断红＝更强证明；print 类：回退→源码 grep 命中＝红）。记录进实现报告。 +- [ ] S13 批末读数对拍：gate 输出 NEW=0、WORSENED 仅 battle_orchestrator 一条、level_map_screen ≤21；71 键清偿/残留账目对账表（§8.4）逐键核对。可核查结果：读数对拍表进实现报告。 +- [ ] 写齐三份产出物（实现报告〔各卡状态＋读数对照＋实机目检总清单——乙组三屏与丙组四态实机开合目检登记（登记不阻塞）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）；临时抓帧脚本与丙组过程帧按中间产物纪律退役。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈4.0d**（区间 3.5–4.0；超软盒预挂＝iter39 先行合回致行号重定位面扩大时 T0 +0.2d）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +撤销证明两型：**读数型**＝回退该文件 hunk → 对照 T0 改前读数表该文件键读数回升＝红 → 还原复绿（结构拆分单元的断言载体）；**迁移型**＝回退生产 hunk → 随动消费方调用断红（签名/改名单元的更强证明，迁移不对称作断言）。对拍锚＝T0 三组（甲：棋盘三图/level_map/menu_boot；乙：camp/settings/battle 帧；丙：battle_end/curio_pick/legend/debug 直构帧）。 + +| 需求点 | 改动（文件） | 验收测试（名称＋落点） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 u1 营地覆盖层拆分 | camp_overlay_view | S13 单文件键读数（9 键清）；ui_struct camp 源扫描＋theme camp 三锚；乙组 camp 帧对拍 0.00% | 静态＋探针＋golden | ui_struct_probe 真实驱动＋shot_probe 帧 | 读数型＋锚句 grep | +| wr2 u2 关卡地图拆分＋恶化债归绿 | level_map_screen | S13 读数：类变量 ≤21（归绿）＋函数级 5 键清；level_map_info_fog_test（V1/V2 继承）；level_map golden 0.00% | 静态＋单元＋golden | open_choices 真实入口（测试白盒夹具） | 读数型 | +| wr3 u3 棋盘格单元拆分 | board_cell_unit | S13 读数（3 键清）；棋盘三图 golden 0.00%（甲组） | 静态＋golden | board_shot_probe 真实抓帧 | 读数型 | +| wr4 u4 站桩拆分 | standee_body | S13 读数（3 键清）；fx_probe＋standee_fx_sweep_test；theme 源锚四句 | 静态＋单元＋探针 | fx_probe 直构真链 | 读数型＋锚句 grep | +| wr5 u5 信息面板拆分 | hero_info_panel_view | S13 读数（4 键清）；player_copy_sweep_test；ui_probe info_panel 直引面 | 静态＋单元＋探针 | 直构＋探针真链 | 读数型 | +| wr6 u6 战末覆盖层＋open_victory 收拢 | battle_end_overlay（＋随动 5 消费点） | S13 读数（3 键清）；迁移型断言（回退→五消费点断红）；丙组对拍 0.00%；t17_defer/ui_struct/ui_probe _end_overlay 面绿 | 静态＋探针＋golden | ui_struct_probe open_victory 真链 | 迁移型 | +| wr7 u7 调试浮窗拆分 | debug_overlay | S13 读数（2 键清）；ui_tune_probe 全段（公开面＋零动效源码契约）；system_test 调试段；theme V4/debug 源锚 | 静态＋探针＋系统 | ui_tune_probe 真实驱动 | 读数型＋契约 grep | +| wr8 u8 装配器拆分 | ui_assembler | S13 读数（3 键清）；theme V4/退役判据段；ui_probe 启动态 | 静态＋单元＋探针 | shot_probe 启动态真链 | 读数型 | +| wr9 u9 战斗舞台拆分 | battle_stage_view | S13 读数（3 键清）；ui_probe stage 直引面；乙组 battle 帧对拍 | 静态＋探针＋golden | 探针真链 | 读数型 | +| wr10 u10 三选一覆盖层拆分 | curio_pick_overlay | S13 读数（2 键清）；reward_overlay_test；丙组对拍 0.00%；ui_struct/ui_click curio 段 | 静态＋单元＋探针＋golden | 直构＋探针真链 | 读数型 | +| wr11 u11 设置覆盖层拆分 | settings_overlay | S13 读数（2 键清）；乙组 settings 帧对拍；ui_click 设置段＋theme V4 | 静态＋探针＋golden | 探针真链 | 读数型 | +| wr12 u12 结算日志拆分 | battle_log_view | S13 读数（4 键清）；theme_projection :386 直构断言＋player_copy :100 | 静态＋单元 | 直构真链 | 读数型 | +| wr13 u13 三选一交互件归并 | curio_interact_controller | S13 读数（改善）；ui_click/ui_struct 三选一真链段 | 静态＋探针 | 探针真链 | 读数型 | +| wr14 u14 AP 条拆分 | ap_bar_view | S13 读数（1 键清）；S7 源锚逐字；ui_probe/ui_click ap_bar 直引面 | 静态＋探针 | 探针真链 | 读数型＋锚句 grep | +| wr15 u15 棋盘区容器拆分 | board_zone_view | S13 读数（1 键清）；board_zone 直引面（status_badge/legend_toggled/toast） | 静态＋探针 | 探针真链 | 读数型 | +| wr16 u16 棋盘动效循环提函数 | board_fx_view | S13 读数（1 键清）；fx_probe 逻辑层＋棋盘三图 golden（fx 不入静止帧对拍） | 静态＋探针＋golden | fx_probe 真链 | 读数型 | +| wr17 u17 图例循环提函数 | legend_overlay | S13 读数（1 键清）；player_copy_sweep 直构＋ui_struct legend 段；丙组对拍 | 静态＋单元＋探针＋golden | 直构＋探针真链 | 读数型 | +| wr18 u18 ui_kit 公开面收敛 | ui_kit（＋随动 6 文件：theme/shop_overlay/node_overlay/status_panel/confirm_dialog/settlement_review_overlay） | S13 读数（5 键清）；迁移型断言（回退→随动消费点断红）；theme V1–V3/T5②＋ui_contrast 扫描；menu_boot/camp/battle 帧对拍 | 静态＋单元＋探针＋golden | theme 直构真链＋探针 | 迁移型 | +| wr19 u19 HUD 投影参数收拢 | hud_presenter（＋main:810/tune_sim:67） | S13 读数（3 键清）；迁移型断言；hud_presenter_test＋battle golden 帧 | 静态＋单元＋golden | 真实 refresh 调用链 | 迁移型 | +| wr20 u20 三选一流上下文收束 | curio_flow_context（＋main_ui_build:132） | S13 读数（2 键清）；迁移型断言；ui_click 三选一段 | 静态＋探针 | 装配真实构造链 | 迁移型 | +| wr21 u21 营地流上下文收束 | camp_flow_context（＋main_ui_build:152/camp_shop_presenter） | S13 读数（1 键清）；迁移型断言；ui_click 营地段 | 静态＋探针 | 装配真实构造链 | 迁移型 | +| wr22 u22 叙述件拆分 | battle_narrator | S13 读数（1 键清）；battle_narrator_test 零改动全绿 | 静态＋单元 | 直构真链 | 读数型 | +| wr23 u23 批量模拟控制器 | tune_sim_controller（随裁点） | S13 读数（按裁点）；ui_tune_probe 批量模拟段（进度/报告语义） | 静态＋探针 | ui_tune_probe 真实驱动 | 读数型＋print grep | +| wr24 u24 试玩日志器 | playtest_logger（随裁点） | S13 读数（按裁点）；sim 四驱动件直构回归＋诊断转储 toast 链 | 静态＋集成 | main_debug_flow 转储真链 | 读数型＋print grep | +| wr25 u25 组合根死成员清点 | main.gd | S13 读数（类变量下降）；对账表零消费凭据；12 探针＋system_test 全绿（main.X 零迁移实证） | 静态＋探针＋系统 | 探针 main.X 真链 | 读数型＋对账表复核 | +| wr26 产出物 | T5 三份 | 件核（wr26） | — | — | 缺项红 | + +### 8.2 测试方式两分法与目检登记 + +本批零行为改动＝无调试接口验证项；能力面（debug_overlay/批量模拟）经 ui_tune_probe 真链回归即闭环。用户目检项（登记不阻塞，入实现报告实机目检总清单）：乙组三屏（camp/settings/battle）开合观感、丙组四态（战末/三选一/图例/调试浮窗）开合观感、营地三柜台与锻造工坊交互回归——全部为「与改前一致」判读。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝①T0 时点铁序（锚面采集先于码改——git 提交序核）②golden 对拍读数复现（抽 3 锚直跑）③S13 读数对拍表逐键复核＋基线文件 git diff 零变化④源码锚字面量契约抽检（S2/S6/S7/S9）⑤撤销证明抽两条复现⑥探针直引 46 名零迁移抽检。未过不得合并。 + +### 8.4 S13 账目（71 键清偿账） + +清偿 62 键（键消失）：u1×9／u2×5／u3×3／u4×3／u5×4／u6×3／u7×2／u8×3／u9×3／u10×2／u11×2／u12×4／u14×1／u15×1／u16×1／u17×1／u18×5／u19×3／u20×2／u21×1／u22×1／u23×2（print 案①时）／u24×1。残留 9 键（键留基线内绿、尾波处置）：camp 19/15、level_map 20/15（**恶化债已归绿**）、board_cell 31/15、standee 29/15、battle_end 20/15、debug 17/15、curio_interact 18/15（类变量改善非清零七条）＋tune_sim await 1（§11 裁点案①时）＋main 49→N/15（改善非清零）。u23 若裁案②则清偿 63、残留 8。回归措辞：里程碑步（T 卡段）出口跑一次全套闸；波内修复只做出红最小单元的最窄确认；新增测试/工具先行孤立验证再并入全套。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 复核自吸收）；私有函数命名与注释措辞；对拍帧采集的等价实现形态（探针帧直拷 vs 临时脚本）。 +- **L2（记录继续）**：乙组 battle 帧跨跑次非 0.00% 降级丙组（判定记录写明）；消费面随动改址的单行等价写法；读数改善幅度与预估偏差（非归绿义务单元）。 +- **L3（停机呈报）**：任何 golden 对拍差异非零（契约 1）；探针直引面/源码锚契约与拆分互斥（契约 2）；main 死成员对账发现探针断言缝成员（契约 3——禁删，若与收敛目标互斥停呈）；机检键与契约互斥（契约 4）；拆分产生基线外新违规且不可在阈值内消化（契约 4）；发现收编清单外同病根新键（禁扩面——呈报由用户裁）；**逐文件实查发现触碰 owner 契约/GDD 陈述**（D5——停笔呈报，禁内联求裁）。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 各宿主内私有函数命名、分组与注释随迁措辞（语义不变前提下）。 +2. 乙组基线帧文件命名（随 golden/README 现行命名规则）与丙组临时采集脚本的实现形态。 +3. wr 断言挂点与读数表格式。 +4. 提交切分与 worktree 分支命名。 +5. u25 对账表中「装配拆件 root.X 消费」与「探针消费」两类的成员归类判定（对账表随 T5 追认）。 + +## 11. 待裁点 + +**W1 · 测量面卫生键处置**（唯一待裁点；三项一并裁，裁决前 T4 对应两件不得开工）： + +- **print 残留×3**（playtest_logger :160/:161 两行＋tune_sim_controller :43 一行）： + - **案①（推荐）删除**：playtest_logger 两行删——路径信息已由 toast 承载（main_debug_flow:16 `show_toast("已转储诊断: "+path)`）、上下文 JSON 已落转储文件，stdout 重复输出零独有信息；tune_sim 一行删（模拟日志落盘目录与真人试玩 JSONL 同目录惯例，路径可从 logger 会话产物定位——禁改 set_sim_report 文本，契约 1 文案逐字不变）。键清 2，信息零损失。 + - 案②（淘汰依据）：留档豁免注记保留——「测量面惯例」论据不成立于本仓：S13 扫描面内现行 print 仅此两件（无豁免惯例在案），且基线格式明文「只记基线不记豁免理由」，注记无处落；留档＝键永不清偿，与条目「存量债全部清除」目标相抵。 +- **循环内 await×1**（tune_sim_controller :65，逐帧 `await panel.get_tree().process_frame` 驱动浮窗进度刷新）： + - **案①（推荐）保留**：await 是批量模拟逐局让出主线程的承载结构（删则浮窗冻结直至跑完＝工具行为变化）；递归/回调化清键属为机检改写异步结构（栈深随模拟数增长、可读性降），第 13 条反向病；键留基线内绿（存量不判红），豁免理由记实现报告。 + - 案②递归化消除（`_run_batch(n, i)` 尾递归形态）：键清 1、71 键账目最优；代价＝为机检改写异步结构，测量语义虽可保持但收益为负。 + +（除 W1 外零待裁点——u1–u22/u25 改法全部由形态裁定与实查闭死；W1 两项互不绑定，可分别裁。） + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 写卡会话）**：①规格覆盖——u1–u25→wr1–wr25 逐条对上、T0–T5 各卡可指认、恶化债/锚面/裁点各有落点；②步骤扫描——每步一动作一可核查结果，接口块给签名不给实现体，无「TBD/酌情」行（T0 乙组降级分支为带判据的条件路径非酌情）；③类型一致性——接口块签名与 §3 实查、wr 行、T3/T4 取用关系逐字一致（refresh ctx 五键＝main:810 现八参尾五；stats 六键＝tune_sim:67 现十参中六）；④审查焦点——呈现零变化（三组锚）与探针直引面（S1–S16）为最可能坑点，已逐文件挂 wr 行与契约 2；行为改动覆盖：本批零行为改动，唯一边缘面＝print 删除（stdout 文本——wr23/24 以 grep 与 ui_tune 真链承载）；⑤篇幅比例——零实现体抄写，接口块全为签名与键清单；⑥落位预检——零新增文件、私有函数族与 golden 基线、PANEL_DEFAULT 三件各有不能复用理由与唯一落点，与结构图对上。 + +**grilling 自检一轮（2026-10-27，写卡会话内对抗复核）折入记录**：①收敛算术复核——ui_kit 26−2−4＝20 成立（modal_shell 哨兵收拢不增方法；拆分方案会 21 超阈，已弃）；②open_victory 三参消费点缺省兼容免改址（fx_probe/standee_fx_sweep/curio_interact）——S13 改为「传参者 5 处随动」；③level_map 恶化债归绿判据写死 ≤21（gdstyle 判红线＝登记值 21，「回到登记值以下」歧义消除）；④撤装置教训回扣——u2 换层装饰域归并禁计数迎合（契约 7 显式禁转发/别名，_cand_ids/_hover_id/_content_size/_drawn_disp 四探针直引成员排除出归并候选）；⑤撤销证明两型分层（读数型/迁移型）补强——纯拆分文件回退后现役套件仍绿，读数对拍表是唯一断言载体，已在对照表末列写死；⑥补 S16（level_map 探针冻结成员清单）与 §8.4 残留键账目（9 键去向尾波）——完成定义第 1 条账目闭合；⑦**load_font 私有化撤换（实查翻案）**——初稿拟私有化 load_font，逐消费方复核发现其直引含两处渲染闸探针（board_shot_probe:49/type_glow_shot_probe:71）＋ui_font_asset_test:15，私有化须动渲染闸探针；换选 switch_toggle（消费方 settings_overlay:76/:91 全在本卡触面、零探针测试面），收敛算术不变、随动面缩 3 行且零探针触碰——S8/接口块/T3/wr18/结构图五处随改；⑧W1 案① tune_sim print 处置收紧为「删除」并禁改 set_sim_report 文本（并入报告文本属文案变化，违契约 1 文案逐字不变）；⑨乙组基线帧命名改挂代拍板白名单（初稿行内命名自造，禁行句式剔除）。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名/转发属性；本批收敛不得以「探针便利」「基线计数」为由保留任何清单外死成员或新增同种装置；u2 域归并/u13/u25 清点的每一笔收编必须以真实同域或真实零消费为凭据（对账表在案）；机检键与本卡契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md b/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md new file mode 100644 index 00000000..7b6670eb --- /dev/null +++ b/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md @@ -0,0 +1,316 @@ +# 需求卡片：核心数据面结构收敛批（gdstyle 存量债清偿·卡 2——数据校验族／生成器族／效果引擎／core-data 散条 86 键） + +- 版本：**v1.0**（写卡段成文；grilling 自检一轮已折入，记录见 §12） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋待写卡）（唯一事实源：清点报告 [审计-gdstyle存量债清点与清偿方案-2026-10-26](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 2／3／4／7 条裁定——证据指认形态，见 §2） +- 归并账目（清点报告 §六第 7 条）：本卡收编＝**波 2（40 键／13 文件）＋波 4（17 键／2 文件）＋effect_engine（8 键）＋波 8 core/data 侧 10 文件（21 键）＝86 键／26 文件**；与卡 1（B1 战斗域拆件批 45 键）、卡 3（呈现层结构收敛批 71 键）账目闭合 45＋86＋71＝202＋三宿主规避 14＝216 +- 归属：`game/data/schemas/` 12 文件＋`game/core/` 14 文件＋`game/data/tables/adventure.tres`（等值迁移）＋测量面改址（`game/tests/`、`game/probe/` 约 30 文件） +- 排期：未编入（迭代批卡片；估时 ≈4.9 个工作日，区间 4.6–5.3，逐 T 卡实估见 §7） +- 开工门：U0＋复核门过（§12）＋§11 两项待裁点裁决落定 + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话）**：来源条目＝需求性工程条目（整行无设计线段、首段落「文档设计已闭合＋待写卡」）——逐波裁定（清点报告 §六第 1–6 条）＋2026-10-27 整合裁定（§六第 7 条）即证据指认，放行。 +- **卡间文件零交叠（整合裁定 §六第 7 条既定收益）**：卡 1 文件集＝battle_orchestrator／grant_segment／combat_segment／settlement_table／damage_controller／treasure_interact_controller——本卡零触；卡 3 文件集＝呈现层——本卡零触。effect_engine 归本卡即「防与卡 1 文件交叠」的既裁结果。 +- **unit_container spawn 参数键因此留残**（详见 K6）：spawn 签名收敛（10→≤5 参）必改全部调用方，含 `battle_orchestrator.gd:364` 一行＝卡 1 文件集——为守住零交叠义务，本卡只做 spawn 体内私有拆分（清 81 行／17 局部两键），参数键随卡 1 批或尾波随动。 +- **与迭代 39 两卡（已编）的文件触碰**：副卡（同调配装充能域封装批）触 effect_engine.gd（仅 :94 注释面 RunLedger 表述清）与 meta_progression_forge_test.gd（:290-291 直构改址）——本卡重构 effect_engine.gd 本体并改址同一测试文件的其他行；**同文件异行域，编排须错波，后行者 T0 吸收行号漂移**。 +- **与波 7 现成卡（结构小件定点修批 v1.2，停卡待裁）**：同触 board_generator.gd（其 :396-398 _fatal）与 reward_economy.gd（其 :366-368 _fatal）——波 7 行号锚在本卡合回后须按其 T0 重核（其卡已自带该义务），编排串行。 +- **PARITY／MC 纪律**：本批零数值改动、零 RNG 流改动、零 PARITY 触面（S8_FILES／PARITY_TOUCH_FACES 零命中）→ 零 MC、零对拍补跑。 + +## 1. 目标与完成定义 + +**目标**：86 键收编文件的结构债清偿——①数据校验族 13 文件 validate()／cross_validate() 按校验域拆私有函数族（2026-10-26 用户裁：各文件内部拆、不抽共享骨架）；②生成器族两件拆私有阶段函数（RNG 消费序冻结）；③effect_engine 拆解释器与校验私有域（全同步语义、装载声明序、四词表封闭零变化）；④波 8 core/data 散条按 §7-K 清单收敛（删冗余／私有化／合并，公开面改动逐项列明消费方影响面）。**游戏行为零变化**（契约 1）。 + +**清偿账目**：86 键中 **81 键本卡清偿**（gdstyle 直扫键消失，闸读数下降自然绿）＋**5 键裁定集内不可全清、申报残留**（config_db 公开方法／类变量、save_manager 公开方法、meta_progression 公开方法、unit_container spawn 参数——各键改法与消费方影响面见 §7-K，清偿深度两案并列见 §11 待裁点）。81＋5＝86 账目闭合。 + +**完成定义**： +1. §7 结构图全部行落地；`tools/gdstyle_gate.py` 改前改后读数对拍：基线外 NEW＝0、恶化＝0、在案键计数较 216 下降（读数表进实现报告）； +2. 行为等价证据齐：数据校验族断言面（data_config 八套件＋core 直引 12 文件）全绿；生成器同种子逐位一致（现役 determinism 断言继承）；效果引擎现役四套件全绿； +3. 撤销证明逐 wr 行落地（§8.1 末列）；三份产出物写齐（T7）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 待办清单条目「gdstyle 存量债全量清偿」（需求性工程条目证据指认） | 波次框架、纪律、本卡放行凭据 | +| D2 | 清点报告 §六**第 2 条**（波 2 形态＝各文件内部拆校验域私有函数族、不抽共享骨架、零新概念零架构登记） | 校验族拆分形态 | +| D3 | 清点报告 §六**第 3 条**（全部波不改游戏规则与玩家可见行为；design/gdd/systems/ 零修订预期） | 行为零变化总纲 | +| D4 | 清点报告 §六**第 4 条**（波 8 config_db 公开方法收敛＝纯代码：删冗余、私有化内部方法，不动对外语义；架构表「对外暴露」列实现批后随动改写） | config_db 收敛方法集与边界 | +| D5 | 清点报告 §六**第 7 条**（2026-10-27 整合裁定：本卡＝波 2＋波 4＋effect_engine＋波 8 core/data 侧＝86 键；文件交叠冲突归零） | 收编范围与卡间边界 | +| D6 | 2026-10-27 写卡会话**逐文件实查声明**：26 收编文件全数实读＋gdstyle 0.4.0 直扫复测（读数与 2026-10-26 基线零漂移）；公开面消费方 grep 全域核验（§7-K 逐项）；**未发现触碰任何 owner 契约／GDD 陈述的病根**——三处文档机械指址漂移（§6 反哺点承载，陈述本体不变） | 本卡写法③证据基座 | + +## 3. 现状事实（2026-10-27 写卡会话实查于 master 8b146321，gdstyle 0.4.0 直扫——与基线零漂移；开工日 T0 复核行号） + +### 3.1 数据校验族（波 2，40 键／13 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/data/schemas/meta_tree_table.gd` | validate 长度 86/50·分支 26/8·局部 13/10·嵌套 5/4 | :27-111（单循环体＋requires/requires_level/彩蛋三尾段） | +| `game/data/schemas/treasure_item_table.gd` | validate 长度 147/50·分支 44/8·局部 26/10·嵌套 6/4 | :61-206（行头校验／活行校验／同调行校验三段可分，:104 调 EffectEngine.validate_trigger_row） | +| `game/data/schemas/board_gen_table.gd` | validate 长度 67/50·分支 20/8·局部 16/10 | :14-81 | +| `game/data/schemas/enemy_table.gd` | validate 长度 116/50·分支 32/8·局部 29/10 | :36-150（行核心／池模板／行序纪律／锚行四段） | +| `game/data/schemas/forge_table.gd` | validate 长度 95/50·分支 30/8·局部 20/10 | :31-126（行校验＋初始持有覆盖尾段＋默认轴交叉尾段） | +| `game/data/schemas/level_gen_params.gd` | validate 长度 59/50·分支 15/8·局部 18/10 | :15-72（行校验＋层深递进尾段） | +| `game/data/schemas/meta_table.gd` | validate 长度 60/50·分支 14/8·局部 14/10 | :15-74（boss_keystone／conversion／attune_refresh 三行族天然分段） | +| `game/data/schemas/reward_table.gd` | validate 长度 99/50·分支 30/8·局部 20/10 | :16-113（行校验＋字典完整性／池护栏／clear_default 三尾段） | +| `game/data/schemas/skill_table.gd` | validate 长度 80/50·分支 29/8 | :19-97（按 type=basic/damage/buff/debuff 四段类型校验） | +| `game/data/schemas/variation_table.gd` | validate 长度 58/50·分支 20/8 | :24-80（行校验＋互锁段） | +| `game/data/schemas/status_effect_table.gd` | validate 分支 12/8 | :14-51（按 unit=percent/flat/ac 三段量纲域） | +| `game/core/config_db_cross_validator.gd` | cross_validate 长度 107/50·分支 21/8·局部 24/10·嵌套 5/4；validate_skill_pool_links 局部 11/10 | :8-113（①①b②③⑤⑥⑦编号块天然分段）；:121-159 | +| `game/core/config_db_resolver.gd` | resolve_enemy_rowset 分支 12/8；_resolve_progress 长度 52/50·分支 16/8·局部 11/10 | :33-81（行集寻址）；:107-157（缺位标注 if 链＋告警去重块） | + +### 3.2 生成器族（波 4，17 键／2 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/board_generator.gd` | generate 长度 62/50·局部 14/10；_attempt 长度 51/50；measure_inferability 长度 64/50·分支 12/8·局部 13/10·嵌套 5/4；_finalize 参数 6/5 | :20-80（params 快照段 :26-39 可提）；:85-134（布雷＋剃雷段可提）；:151-213（single／subset 两算子与派生约束段可提）；:336（`_db` 形参全函数零消费——删即 5 参） | +| `game/core/node_map_generator.gd` | check_params 分支 12/8；validate_output 长度 132/50·返回 7/6·分支 34/8·局部 22/10；_build 局部 15/10；_add_forks 局部 12/10；_assign_types 分支 11/8；_check_fork_rules 嵌套 5/4 | :68-106（域校验段／结构可行性段两分）；:111-241（六阶段早退结构天然分拆）；:246-286；:292-334（锚收集段无 RNG 可提）；:359-402（配比填余段／岔口修型段两分——后者零 RNG）；:468-514（支路签名比较嵌套） | + +### 3.3 effect_engine（8 键） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/effect_engine.gd` | rebuild 长度 55/50·嵌套 5/4；_cond_ok 长度 52/50·返回 19/6·嵌套 5/4；validate_trigger_row 分支 14/8·局部 11/10；多余 else（no-else-return） | :95-148（feats装载／同调装载／树规则合成三段，装载序 feats→treasure→tree）；:259-309（13 算子 match——比较族／ends_with／has／计数器族四组）；:341-388（when 键校验段／do 键校验段）；:210/:212＝bucket_of 的 elif-after-return（:207-214） | + +### 3.4 波 8 core/data 散条（21 键／10 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/config_db.gd` | 公开方法 44/20；类变量 25/15 | 公开方法实测 44 个（写卡会话逐个枚举）；类变量＝19 类型化表持有＋is_ready＋5 私有。**公开方法外部消费全量核验：44 个全部有 ≥1 消费方，其中零生产消费 3 个**（meta_conversion_row＝测试 2 文件 3 处；forge_weapon_route_by_type＝forge_table_test 2 处；validate_skill_pool_links 门面包装＝测试 2 文件 9 处）。类变量外部直读核验：19 持有变量全部有生产直读（db.hero 159 处／db.settlement 177 处／db.adventure 137 处等） | +| `game/core/save_manager.gd` | 公开方法 52/20；_peek_summary_at 返回 7/6；load_from_disk 返回 8/6 | 公开方法实测 52 个；**零生产消费 10 个**（attach_path 16 处／attach_slot_template 23 处／slot_path 3／active_slot 17／has_write_target 9／peek_summary_at 4／load_from_disk 36〔生产路径＝自身 _ready 内部调用，autoload 升格后无外部生产调用〕／register_migration 2／add_keystone 22／forge_routes_snapshot 7——全部为测试／探针测量面消费，合计约 139 处改址）；:175-209／:318-355 两函数与迁移循环同构可提 | +| `game/core/status_container.gd` | apply_effect 返回 9/6·嵌套 5/4；_new_instance 参数 7/5 | :28-66（三臂 match 公共尾部都是 `_instances.append(_new_instance(...)); return true`）；:69-80 | +| `game/core/unit_container.gd` | spawn 长度 81/50·参数 10/5·局部 17/10 | :36-118（英雄段 :55-63／行集段 :69-112 两分）；签名 10 参，调用方＝battle_orchestrator.gd:364＋测试 6 文件（参数键改法受卡间零交叠约束——K6） | +| `game/core/reward_economy.gd` | roll_board 长度 54/50·局部 11/10；_skewed_cell_rows 局部 13/10 | :37-88（资格清单规范化段 :42-52 在开流前，可无虞提取）；:220-259（分摊量计算段／权重装配段两分） | +| `game/core/meta_progression.gd` | 公开方法 31/20；tree_can_buy 返回 8/6 | **全库零消费死件 3 个**（forge_weapon_atk_bonus／forge_armor_ac_bonus／tree_stat_flat——生产零、测量零）；**零生产消费 3 个**（tree_can_buy＝测试 2 文件 8 处〔内部被 tree_buy 调用〕／tree_gate_text＝测试 1 文件 2 处／tree_spent_total＝仅内部自用）；:320-350（requires／requires_level 两循环段可提） | +| `game/core/treasure_items.gd` | validate_use 分支 11/8·嵌套 5/4 | :88-131（空间解析段／预读窗口段两分） | +| `game/core/action_economy.gd` | 类变量 18/15 | 18 变量逐个核验：**`_next_round_mode` 只写零读（死存储，:36 声明／:219 写入，全库无第三处）**；**`_ap_exhausted_last` 可派生**（:275 在 _finish_round 内由 path_tag 派生，与 :274 `_last_round_end` 同源同刻——ap_exhausted_last_round() :280-282 改派生读语义逐字）；**`last_round_end` 属性对外仅 minesweeper_rules.gd:495 一处消费**（architecture.md :102 该行只列「last_round_end」于消费依赖列，未钉属性形态；「ap/rap/phase 只读」三属性在架构对外暴露列——不动） | +| `game/core/minesweeper_rules.gd` | _do_dig 长度 53/50 | :280-332（连锁揭示循环段 :301-329 可提——cell_revealed 发射序即链序，整体搬迁零漂移） | +| `game/data/schemas/adventure_table.gd` | 类变量 44/15 | 44 变量＝37 个 @export 标量槽＋0 常量（const 不计入 gdstyle 类变量）。**外部直读核验：36 个配额/件值/cap 槽生产直读为零**（仅 2 处测试例外：pool_case_d_test.gd:164/165/190 直写 curio_cap_gp 模拟满层、adventure_feats_test.gd:206 直读 curio_value_max_hp_common）；生产消费全走 curio_quota()/curio_value()/curio_cap() 三个访问器与 9 个 knob 槽（clear_heal_pct／curio_candidate_count／shop_refresh_free／shop_refresh_cost_base／shop_refresh_cost_curve／feat_ticket_* 四件）。adventure.tres 在册 36 个标量属性（等值迁移载体） | + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 行为零变化**：①fail-fast 契约与校验覆盖面零变化——全部 validate／cross_validate 对同一输入的错误清单**逐字等价**（类别、文案、追加顺序）；②生成结果逐位零变化——board_generator／node_map_generator 同种子同参产出与改前逐位一致，**RNG 消费序冻结**（拆分只许整段搬迁取数代码，禁重排任何 rng_stream／纯流取号调用）；③伤害数值与效果语义零触碰；④效果引擎**装载声明序**（feats→treasure→树规则，行内数组序）与**四词表封闭**（EVENTS／EFFECT_KINDS／FACTS／OPS 常量零改动）零变化；⑤玩家可见呈现零变化。 + +🔴 **契约 2 · 断言面逐字保留**：现有 validate 系单测（data_config 八套件＋core 直引 12 文件）与生成器断言面（board_generator_test／node_map_generator_test／node_map_determinism_test 等）**禁删禁改判据**；确需改判据＝测试削弱申报节逐条列明理由。测量面改址（§7-K 列明的调用点换址）＝访问路径改写，断言语义与判据逐条保持。 + +🔴 **契约 3 · S13 纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh；还债＝数值下降自然绿；在案键的函数**禁搬移文件**（搬移＝基线外 NEW 键——本卡全部改动原文件内完成）；机检键与卡片契约互斥时停卡呈报。 + +🔴 **契约 4 · 禁为机检文本保留无效成员**（req-card 第 13 条，本卡属重构类）：禁为迎合机检消息文本（含计数）保留或新增无效成员／别名／死存储（action_economy `_next_round_mode` 删除即本契约的执行例）；机检键与本卡契约互斥时实现段一律停卡呈报，不得自造第三条路。 + +🔴 **契约 5 · 公开面收敛边界**：只准动私有函数体与私有签名；公开签名／公开方法数／类变量数的改动**逐项按 §7-K 清单执行**（每项已列改法与消费方影响面），清单外公开面禁动。 + +🔴 **契约 6 · 核心层纪律不破**：Core 层零 UI 依赖（拆分后完整战斗仍可 `--headless --script` 跑通）；数值单一事实源（adventure_table 词典化后玩法数值仍只存 `data/tables/*.tres` 经 ConfigDB 单点读取，访问器语义不变）；RNG 单点（零新增随机）。 + +## 5. 范围边界 + +**做**：§3 所列 26 文件的结构拆分与 §7-K 六项公开面收敛；adventure.tres 等值迁移；测量面改址（§7-K 列明）；撤销证明；产出物。 + +**不做**（去向明示）： +- config_db 公开方法 44→20 级的访问器归位重组、config_db 类变量词典化、save_manager 域对象拆件、meta_progression 域拆件 → §11 待裁点两案并列，用户裁后另立或扩本卡； +- unit_container spawn 签名收敛 → 随卡 1 批或尾波（K6，卡间零交叠义务）； +- 三宿主残留债（迭代 39）与呈现层 71 键（卡 3）、波 7 五小件（现成卡 v1.2）、波 0 基线 refresh（直改）→ 各归其位； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）； +- MC／对拍锚重跑 → 用户发起（本批零触发）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `design/gdd/systems/战斗循环/地图战斗资源.md` | :83 引 `reward_economy.gd#roll_board` 内部行号（「循环第 65-67 行」）——roll_board 提取规范化段后行号漂移；`_rollable_rows()` 207-213 指址不变 | 反哺点 · 列清单（①：行号随动，陈述本体——收 pool 全集与资格一视同仁语义——零变化） | +| `design/gdd/systems/冒险循环/冒险结构.md` | :267「adventure_table curio_value_*（…列族）」——词典化后标量槽名消失，值域陈述（int [0,999]／kind×tier）不变 | 反哺点 · 列清单（②：落点列改指词典键） | +| `design/engineering/architecture/architecture.md` | :88 ConfigDB 行对外暴露列（删 2 访问器＋私 1 包装随动——裁定 D4 既定）；:124 meta_progression 行对外暴露列（tree_can_buy 私有化随动）；:102 minesweeper 行消费依赖列「A3 last_round_end」属性→方法注记；:90 action_economy 行（ap/rap/phase 只读不变——零改动预期）；:92/:93/:103/:104 四行（status_container／effect_engine／unit_container／reward_economy 公开 API 零变化——零改动预期） | 反哺点 · 列清单（③：前三条随动改写；后五条 T0 核后记「零改动」注记） | +| `game/tests/验证集清单.md` | 测量面改址涉及测试文件的调用点地址（机器提取重生成） | 批内机械同步（game 内 .md，非禁写面） | +| `待办清单.md` | 来源条目状态推进（主会话统一回写——本卡代理禁改） | 反哺点 · 列清单（④：状态核对注记） | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/data/schemas/meta_tree_table.gd` | validate 拆行校验域＋requires/requires_level 尾段（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/treasure_item_table.gd` | validate 拆行头／活行／同调行三域（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/enemy_table.gd` | validate 拆行核心／池模板／行序域（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/forge_table.gd` | validate 拆行校验＋两尾段（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/reward_table.gd` | validate 拆行校验＋三尾段（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/board_gen_table.gd` | validate 拆行校验域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/level_gen_params.gd` | validate 拆行校验＋层深递进尾段（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/meta_table.gd` | validate 拆三行族域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/skill_table.gd` | validate 拆四类型域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/variation_table.gd` | validate 拆行校验＋互锁域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/status_effect_table.gd` | validate 拆量纲域（复用既有·修改） | 非行为 → wr2 | +| `game/core/config_db_cross_validator.gd` | cross_validate 拆七编号块域＋_check_cast_side（复用既有·修改） | 非行为 → wr3 | +| `game/core/config_db_resolver.gd` | 拆键收集／缺位标注／告警发射域（复用既有·修改） | 非行为 → wr3 | +| `game/core/board_generator.gd` | 拆 params 快照／布雷／single-subset 算子域＋_finalize 删 _db 参（复用既有·修改） | 非行为 → wr4 | +| `game/core/node_map_generator.gd` | validate_output 拆六阶段＋check_params 两分＋构建域拆分（复用既有·修改） | 非行为 → wr5 | +| `game/core/effect_engine.gd` | rebuild 三装载域＋_cond_ok 四算子域＋validate_trigger_row 两键域＋bucket_of elif 收口（复用既有·修改） | 非行为 → wr6 | +| `game/core/save_manager.gd` | 10 方法私有化（K2）＋读盘/窥视迁移域提取（复用既有·修改） | 非行为 → wr7 | +| `game/core/status_container.gd` | apply_effect 公共尾部收口＋_new_instance 打包 5 参（K 清单·修改） | 非行为 → wr7 | +| `game/core/treasure_items.gd` | validate_use 拆空间解析／预读窗口域（复用既有·修改） | 非行为 → wr7 | +| `game/core/meta_progression.gd` | 删 3 死件＋私 3 件＋tree_can_buy 拆 requires 域（K3） | 非行为 → wr7 | +| `game/core/config_db.gd` | 删 2 冗余访问器＋私 1 包装（K1） | 非行为 → wr8 | +| `game/data/schemas/adventure_table.gd`＋`game/data/tables/adventure.tres` | 36 标量槽合并三词典＋.tres 等值迁移（K4） | 非行为 → wr9 | +| `game/core/action_economy.gd` | 删死存储＋派生合并＋last_round_end 属性→方法（K5） | 非行为 → wr10 | +| `game/core/reward_economy.gd` | roll_board 拆规范化域＋_skewed_cell_rows 两域（复用既有·修改） | 非行为 → wr10 | +| `game/core/minesweeper_rules.gd` | _do_dig 拆连锁揭示域（复用既有·修改） | 非行为 → wr10 | +| `game/core/unit_container.gd` | spawn 体内私有拆分（签名不动——K6） | 非行为 → wr10 | +| `game/tests/`…（约 30 文件）＋`game/probe/`… | K2/K3/K4 改址与测量面随动（复用既有·修改） | 断言面（改址非削弱）→ wr7/wr8/wr9 | + +（零新增文件；新增件＝各文件内部私有函数族，逐文件预检见下节。） + +### 落位与可复用性预检 + +- **零新增文件**：全部改动为既有件内私有函数族——拆分产物是既有函数体的域化重组，不是新能力，无「复用既有实现」候选（其本体就是既有实现）。 +- **唯一面**：每个新增私有函数只落其所属文件；不抽共享骨架为既裁（D2——13 文件结构各异，强行归一有抽象层风险）；跨文件同名私有方法（如多个 schema 各自的 `_validate_row`）属 GDScript 类作用域私有，互不冲突，grep 全库名`_validate_row`／`_apply_single` 等拟用名确认盘上无第二处同职责实现。 +- **分层与交互面**：全部新私有函数在本文件本层内被调用，零新跨层路径；Core 零 UI 不破（全套件 headless 可跑）；随机只经既有 rng_stream／纯流，消费序冻结（契约 1②）；公开面改动仅 §7-K 六项，消费方改址全部是测量面或既有访问路径等价改写。 +- **K1–K6 逐项**（公开面收敛清单，契约 5 载体——每项改法与消费方影响面）： + - **K1 config_db（44→41）**：删 `meta_conversion_row()`（:371，生产零消费；测试 3 处改直读 `db.meta.conversion` 行集——断言语义不变）；删 `forge_weapon_route_by_type()`（:421，生产零消费；forge_table_test 2 处改扫 `forge_routes()` 同判据）；私 `validate_skill_pool_links()`→`_validate_skill_pool_links()`（:185 门面包装，测试 2 文件 9 处改 _ 前缀调用；cross_validator 自有公开同名方法不动）。 + - **K2 save_manager（52→42）**：私 10 件零生产消费方法（§3.4 列名）——约 139 处调用点全部为测试／探针测量面，改 _ 前缀调用，断言语义逐条保持；生产路径零触碰（load_from_disk 生产调用＝自身 _ready 内部，随私有化同步改）。 + - **K3 meta_progression（31→25）**：删 `forge_weapon_atk_bonus()`／`forge_armor_ac_bonus()`／`tree_stat_flat()`（全库零消费死件——grep 生产零＋测量零＋内部零调用）；私 `tree_can_buy()`→`_tree_can_buy()`（测试 2 文件 8 处改址；内部调用点 tree_buy 同步）、`tree_gate_text()`→`_tree_gate_text()`（测试 1 文件 2 处）、`tree_spent_total()`→`_tree_spent_total()`（仅内部自用）。 + - **K4 adventure_table（44→12）**：36 个 curio_quota_*/curio_value_*/curio_cap_* 标量槽合并三词典 `curio_quotas`／`curio_values`／`curio_caps`（**键形＝"kind/tier" 复合键**，如 "attack/common"）；`curio_quota(kind, tier)`／`curio_value(kind, tier)`／`curio_cap(kind)` 三访问器签名与返回语义逐字不变（未列组合 = 0／缺省 99 语义保持）；9 个 knob 槽与既有常量不动；`adventure.tres` 等值迁移（在册值逐槽照抄入词典、缺省槽保持缺省语义）；测试改址 2 文件 4 处（pool_case_d_test.gd:164/165/190 直读写→词典键读写；adventure_feats_test.gd:206 直读→词典键读——断言语义不变）。改后类变量＝3 词典＋9 knob＝12 ≤ 15 ✓。 + - **K5 action_economy（18→15）**：删 `_next_round_mode` 死存储（:36 声明＋:219 死写；`notify_settlement_done` 形参保留签名不变）；`_ap_exhausted_last` 删除、`ap_exhausted_last_round()` 改派生读 `_last_round_end.get("path_tag", "") == "ap_exhausted"`（同源同刻等值——:274/:275 实查依据）；`last_round_end` 属性→方法 `func last_round_end() -> Dictionary`（消费方仅 minesweeper_rules.gd:495 一处改方法调用）。 + - **K6 unit_container（spawn 参数键残留）**：spawn 签名 10 参不动（收敛必触 battle_orchestrator.gd:364＝卡 1 文件集，与卡间零交叠义务冲突——整合裁定 D5 优先）；81 行／17 局部两键经体内私有拆分清偿。 + +### T0 事实坐实＋改前读数采集（≈0.2d） + +- [ ] 复核 §3 全部 file:line（吸收迭代 39／并行批漂移）；跑 `python tools/gdstyle_gate.py` 记录改前读数（在案键计数、NEW/WORSENED 判定）。可核查结果：改前读数表进实现报告素材。 +- [ ] 留档行为等价对拍基线：对 data_config 八套件与生成器 determinism 断言记录改前全绿读数；坏表夹具错误清单留档（现役测试的断言面即清单——记录套件名与断言数）。可核查结果：改前基线读数在案。 +- [ ] 核实窄确认载体：单元面直跑形态（`--headless --path . --script res://tests/run_all.gd`）与单套件过滤机制。可核查结果：T1–T6 验证步骤的命令形态定稿。 + +### T1 数据校验族·大表组（5 文件 17 键，≈0.7d） + +- [ ] meta_tree_table：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary, fork_seen: Dictionary) -> Array`（行内全判据，fork_seen 引用传递）＋`func _validate_requires_dangling(rows: Array, seen: Dictionary) -> Array`＋`func _validate_requires_level(rows: Array, seen: Dictionary) -> Array`（requires 与 requires_level 两尾段分离）；validate 本体留空表护栏＋行循环 append_array＋彩蛋计数尾段。可核查结果：错误追加序与改前逐字等价（现役 meta_progression_forge_test／table_structure_guard 断言绿）。 +- [ ] treasure_item_table：validate 拆 `func _validate_row_head(row: Dictionary, iid: String) -> Array`（:76-107 display_name→form 段）＋`func _validate_row_active(row: Dictionary, iid: String) -> Array`（:111-141 活行段，kind_seen 内建）＋`func _validate_row_attunement(row: Dictionary, iid: String, kind_seen: Dictionary) -> Array`（:142-205 同调段）；validate 本体留空表护栏＋seen/dup＋三域顺序调用（retired/deferred continue 位置逐字）。可核查结果：treasure_target_violation_test／table_structure_guard／config_db_test 秘宝段全绿，EffectEngine.validate_trigger_row 调用点零变化。 +- [ ] enemy_table：validate 拆 `func _validate_row_core(row: Dictionary) -> Array`（:52-88 进度键/枚举/值域段）＋`func _validate_row_pool(row: Dictionary, eid: String) -> Array`（:90-116 池模板段）＋`func _validate_rowset_order(rowset_key: String, last_rowset_key: String, closed_rowset: Dictionary, L: int, rk: String, band: int) -> Array`（:129-138 行序纪律段）；validate 本体留 seen/dup、行序状态机、锚行尾段。可核查结果：现役敌人表断言面（config_db_test／round_flow_skill_pool_test 前置）全绿。 +- [ ] forge_table：validate 拆 `func _validate_route_row(row: Dictionary, kind_by_id: Dictionary) -> Array`（:47-106 行段）＋`func _validate_initial_coverage(routes: Array) -> Array`（:107-125 初始持有覆盖＋默认轴交叉尾段）。可核查结果：forge_table_test 全绿（含 13 处行级判据）。 +- [ ] reward_table：validate 拆 `func _validate_row(row: Dictionary, cell_dict: Dictionary, tallies: Dictionary) -> Array`（:25-101 行段；tallies＝{cell_positive_live, clear_value_ok} 引用传递）＋validate 本体留三尾段（字典完整性/池护栏/clear_default）。可核查结果：reward_dangling_treasure_test／table_structure_guard／seal_polarity_test 前置全绿。 +- [ ] 验证步骤：数据面窄确认（data_config＋受涉 core 套件直跑全绿）＋`D:/code/gdstyle/gdstyle.exe` 直扫五文件——17 键全部消失。 + +### T2 数据校验族·小表组＋跨表校验器＋解析器（8 文件 23 键，≈0.7d） + +- [ ] board_gen_table：validate 拆 `func _validate_row(row: Dictionary, levels: Dictionary, anchor_ok: Dictionary) -> Array`；validate 本体留空表护栏＋锚行尾段。 +- [ ] level_gen_params：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary, layers_by_level: Dictionary) -> Array`；本体留层深递进尾段。 +- [ ] meta_table：validate 拆 `func _validate_boss_keystone() -> Array`＋`func _validate_conversion() -> Array`＋`func _validate_attune_refresh() -> Array`；本体留三行族空护栏＋顺序拼接。 +- [ ] skill_table：validate 拆 `func _validate_basic_row(sid: String, row: Dictionary, cd: int) -> Array`／`func _validate_damage_row(...)`／`func _validate_buff_row(...)`／`func _validate_debuff_row(...)`（同签名形态）；本体留 seen/type 分派＋普攻存在性＋pity 尾段。 +- [ ] variation_table：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary) -> Array`；本体留互锁段（或并入 _validate_row——以分支 ≤8 为准）。 +- [ ] status_effect_table：validate 拆 `func _validate_magnitude_domain(row: Dictionary, eid: String) -> Array`（percent/flat/ac 三段量纲域）。 +- [ ] config_db_cross_validator：cross_validate 拆七编号块域——`func _cv_reward_dangling(st, rt, push_diag: Callable) -> void`／`func _cv_reward_treasure(st, rt, loaded: Dictionary, push_diag: Callable) -> void`／`func _cv_poolmap(st_tab, effect_ids: Dictionary, push_diag: Callable) -> void`／`func _cv_source_labels(st_tab, push_diag: Callable) -> void`／`func _cv_counter_closure(loaded: Dictionary, treasure_tab, feats_tab, push_diag: Callable) -> void`（①①b②③⑤⑥⑦对应；货架块 ⑥ 并入 _cv_reward_treasure 或独立 `_cv_shelf_pool`——以各件 ≤50 行/≤8 分支为准）；validate_skill_pool_links 拆 `func _check_cast_side(skill_table: SkillTable, status_table: StatusEffectTable) -> Array`。 +- [ ] config_db_resolver：resolve_enemy_rowset 拆 `func _level_keys_of(rows: Array) -> Array[int]`＋`func _band_keys_of(rows: Array, l_star: int, row_kind: String) -> Array[int]`＋`func _band_rows(rows: Array, l_star: int, row_kind: String, d_star: int) -> Array[Dictionary]`（纯行扫描，告警发射序不变）；_resolve_progress 拆 `func _depth_keys_of(rows: Array, l_star: int) -> Array[int]`＋`func _missing_label(l_clamped: bool, d_clamped: bool, l_star: int, L: int, d_star: int, D: int) -> String`＋`func _emit_missing_warning(table_id: String, missing: String, l_star: int, d_star: int, L: int, D: int) -> void`（去重注册表语义逐字）。 +- [ ] 验证步骤：数据面窄确认全绿（config_db_fatal_oob／counter_prefix_fatal／level_gen_params_test／config_db_resolver_test／config_db_cross_validator_test 等）＋直扫八文件——23 键全部消失。 + +### T3 生成器族（2 文件 17 键，≈0.7d） + +- [ ] board_generator：拆 `func _board_params(row: Dictionary, L: int, D: int) -> Dictionary`（:26-39 快照段——零 RNG）；`func _populate_mines(b: BoardData, params: Dictionary, rng_stream: RandomNumberGenerator) -> int`（:93-127 布雷＋剃雷段——Fisher-Yates 取号段整体搬迁，返回 ring_removed）；`func _apply_single_rules(constraints: Array, r: Dictionary, known_mines: Dictionary) -> bool`＋`func _derived_constraints(constraints: Array) -> Array`＋`func _apply_derived_rules(derived: Array, r: Dictionary, known_mines: Dictionary) -> bool`（measure_inferability 的 single／subset 算子域——返回 changed，主循环序不变）；`_finalize` 删 `_db` 形参（:336，调用点 :79 一处随动）。可核查结果：board_generator_test／board_gen_reward_test 全绿＋同种子改前改后逐位一致断言绿（RNG 消费序冻结——契约 1②）。 +- [ ] node_map_generator：validate_output 拆六阶段域——`func _vo_node_fields(nodes: Array, errs: Array) -> Dictionary`（字段/dup/类型/深度，返回 {by_id, indeg, ok}）＋`func _vo_edges(nodes: Array, by_id: Dictionary, indeg: Dictionary, errs: Array) -> bool`＋`func _vo_flow_facts(nodes: Array, indeg: Dictionary, errs: Array) -> Dictionary`（entries/terminals/Boss 终点判据）＋`func _vo_depth_reach(nodes: Array, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> bool`（最长路径＋可达性）＋`func _vo_shop_rules(nodes: Array, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> bool`（摆放约束①＋_all_paths_one_shop＋_check_fork_rules）＋`func _vo_count_rules(nodes: Array, params: Dictionary, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> void`（多终点深度互异＋宽度上限＋参数档对照）——validate_output 本体＝空图护栏＋六阶段顺序调用＋阶段间早退合并（返回 ≤6）；check_params 拆 `func _cp_domain(params: Dictionary) -> Array`＋`func _cp_structural(params: Dictionary) -> Array`；_build 拆 `func _build_region(rg: RandomNumberGenerator, r: int, e: int, t: int, prevs: Array) -> void`（区域段——_build 本体零 RNG，拆分自由）；_add_forks 拆 `func _collect_fork_anchors(L: int, t: int, e: int) -> Array`（锚收集——零 RNG，shuffle 与扩岔循环留本体保取号序）；_assign_types 拆 `func _fill_ratios(rg: RandomNumberGenerator) -> void`（e==1 配比填余段——shuffle+randf 取号序整体搬迁）＋`func _fix_detour_heads() -> void`（岔口修型段——零 RNG）；_check_fork_rules 拆 `func _fork_signature(outs: Array, by_id: Dictionary) -> Array`＋`func _fork_has_unique(comps: Array, i: int) -> bool`（嵌套 5→≤4）。可核查结果：node_map_generator_test／node_map_growth_test／node_map_determinism_test 全绿＋同参数同种子逐位一致（纯流取号序冻结）。 +- [ ] 验证步骤：核心面窄确认全绿＋直扫两文件——17 键全部消失。 + +### T4 效果引擎（8 键，≈0.35d） + +- [ ] rebuild 拆 `func _load_feat_triggers(feat_ids: Array) -> void`＋`func _load_attune_triggers(item_ids: Array) -> void`＋`func _push_tree_rules(tree_rules: Array) -> void`——**调用序＝装载声明序 feats→treasure→tree 逐字**（契约 1④），sense_sharp/guard 双行 push 序随段整体搬迁。 +- [ ] _cond_ok 拆四算子域：`func _cmp_ok(op: String, actual: Variant, val: Variant) -> bool`（eq..lte 六比较）＋`func _ends_with_ok(actual: Variant, val: Variant) -> bool`＋`func _has_ok(c: Dictionary, actual: Variant) -> bool`＋`func _counter_op_ok(ctx: EffectContext, c: Dictionary, op: String, actual: Variant) -> bool`（mod_zero/mod_eq/advantageous/gte_ref/lt_ref）；_cond_ok 本体＝fact/op/val 取值＋分派＋未知算子 assert(false)+return false（返回 ≤6、嵌套 ≤4）。语义逐字：判定结果与 unknown-op 致命路径零变化。 +- [ ] bucket_of 的 elif-after-return 收口（:207-214）→ 独立 if 序或 match——前缀判定序 round→lvl→adv→battle 缺省逐字（no-else-return 键消失）。 +- [ ] validate_trigger_row 拆 `func _vtr_when_keys(rid: String, tr: Dictionary, errs: Array) -> void`＋`func _vtr_do_keys(rid: String, tr: Dictionary, row: Dictionary, errs: Array) -> void`——错误追加序逐字（:341-388 现序＝trigger 键→on→when→do 键→kind→counter_id→value_from 双侧）。 +- [ ] 验证步骤：效果面窄确认全绿（effect_words_t1_test／tree_rules_v11_test／counter_prefix_fatal_test／adventure_feats_test／round_flow_skill_pool_test）＋直扫——8 键全部消失。 + +### T5 散条组 A——save_manager／status_container／treasure_items／meta_progression（4 文件 10 键中清 8＋K2/K3，≈1.0d） + +- [ ] save_manager 私有化 10 件（K2 清单）＋全部测量面调用点改址（约 139 处／约 25 文件——tests/probe 面逐处改 _ 前缀调用，断言语义逐条保持）。可核查结果：save_manager_domain／save_slot_isolation／save_slot_summary／save_boot_no_activate／breakpoint_resume／feat_vouchers／level_shop_economy／meta_progression_forge／table_structure_guard＋integration 三件＋probe 直跑全绿。 +- [ ] save_manager 读盘域提取：`func _load_parsed(f: FileAccess) -> bool`（:320-355 解析/版本/迁移/规整段——corrupt_fallback 调用点随段迁移，副作用序逐字）＋`func _peek_migrated(parsed: Variant) -> Variant`（迁移循环提取，失败返回 null＝现「返回未填充 out」逐字）；load_from_disk 本体留文件存在分支＋corrupt 委托（返回 ≤6）。 +- [ ] status_container：apply_effect 按「三臂语义逐字＋公共尾部收口」重构——守卫两 return 保留，independent/refresh/stack 三臂与未知 policy 告警保持现行为（independent 恒追加／refresh 命中改 R 未命中追加／stack 满层拒零写入·未满加层·未命中追加／未知 policy 告警拒），追加尾部收口单点；`_new_instance` 签名改 `func _new_instance(effect_id: String, layers: int, dur: int, source: Dictionary, snap: Dictionary) -> Dictionary`（7→5 参，snap＝{m, unit, display}）。可核查结果：seal_polarity／roll_multiplier／damage_controller／system_contracts 四套件全绿（满层拒绝/空刷新/快照语义现役断言面）。 +- [ ] treasure_items：validate_use 拆 `func _spatial_reject_reason(row: Dictionary, kinds: Array, target: Vector2i, board_size: Vector2i) -> String`＋`func _window_cells(target: Vector2i, board_size: Vector2i) -> Array`＋`func _preview_window_dead(resolved: Array, cell_unrevealed_cb: Callable) -> bool`。可核查结果：treasure_items_test 全绿。 +- [ ] meta_progression：删 3 死件＋私 3 件（K3）＋测试改址 10 处（tree_requires_level_test 6 处＝tree_can_buy 4＋tree_gate_text 2；meta_progression_forge_test 4 处）＋`func _tree_requires_ok(row: Dictionary) -> bool`（requires＋requires_level 两循环提取，tree_can_buy 返回 8→6）。可核查结果：两测试文件直跑全绿。 +- [ ] 验证步骤：受涉套件窄确认全绿＋直扫四文件——8 键消失＋2 键读数记录（save_manager 公开方法 52→42／meta_progression 公开方法 31→25——残留申报）。 + +### T6 散条组 B——config_db／adventure_table／action_economy／reward_economy／minesweeper_rules／unit_container（6 文件 11 键中清 8，≈0.9d） + +- [ ] config_db：K1 三件（删 meta_conversion_row＋删 forge_weapon_route_by_type＋私 _validate_skill_pool_links）＋测试改址 5 处（config_db_test 2 处改直读 `db.meta.conversion`、table_structure_guard_test 1 处同、forge_table_test 2 处改扫 forge_routes）。可核查结果：grep 两删除名零命中＋受涉套件全绿＋直扫公开方法 44→41（读数记录）。 +- [ ] adventure_table＋adventure.tres：K4 词典化——三词典声明（`@export var curio_quotas: Dictionary = {}` 等同形）＋36 槽等值迁移（.tres 在册值照抄入 "kind/tier" 复合键；缺省槽不写入＝缺省语义保持）＋curio_quota()/curio_value()/curio_cap() 内部改词典读（签名与返回语义逐字）＋validate() 不动（现役域判据经访问器读数不变）＋测试改址 4 处（pool_case_d_test :164/:165/:190、adventure_feats_test :206）。可核查结果：adventure_feats/pool_case_d/feat_vouchers/table_structure_guard 全绿＋deck_total()=102 结构锚断言绿＋直扫类变量 44→12。 +- [ ] action_economy：K5 三件（删 _next_round_mode 死存储＋_ap_exhausted_last 派生合并＋last_round_end 属性→方法）＋minesweeper_rules.gd:495 改址一处。可核查结果：minesweeper_rules_test／round_flow_skill_pool_test 的 round_end 载荷断言全绿（ap_exhausted_last_round 派生读等值——一滴不剩 when 面现役断言）＋直扫类变量 18→15。 +- [ ] reward_economy：拆 `func _normalize_eligible(eligible: Array) -> Array`（:42-52 去重/排序段——开流前，零 RNG 风险）＋`func _skew_amounts(down: Array, up: Array) -> Array`（两次 _largest_remainder_split 调用段）＋`func _apply_skew(base: Array, down: Array, up: Array, drops: Array, gains: Array) -> Array`（权重装配段——守恒 assert 随段迁移）。可核查结果：board_gen_reward_test／seal_polarity_test 前置全绿＋roll_board 取号序冻结（同种子身份批/清图批尾/区间行逐位一致——现役 reward_roll 流断言）。 +- [ ] minesweeper_rules：拆 `func _reveal_chain(c: Vector2i, reveal_order: Array, was_sealed: bool) -> void`（:301-329 揭示循环段——cell_revealed 发射序即链序，整体搬迁）。可核查结果：minesweeper_rules_test 全绿（cell_revealed 事件序现役断言）。 +- [ ] unit_container：spawn 体内拆 `func _spawn_hero_unit(hero_hp: int, atk_override: int, max_hp_override: int, hero_attack_type: String, hero_armor_type: String) -> bool`＋`func _spawn_rowset(rowset: Array, unit_count_overrides: Array, enemy_atk_overrides: Array, hp_mult: float, atk_mult: float) -> bool`（签名不动——K6；行集守卫/实例化段随分）。可核查结果：damage_controller／roll_multiplier／round_flow_skill_pool／skill_unlock／level_shop_economy 前置全绿。 +- [ ] 验证步骤：受涉套件窄确认全绿＋直扫六文件——8 键消失＋3 键读数记录（config_db 公开方法 41／config_db 类变量 25／spawn 参数 10——残留申报）。 + +### T7 读数对拍＋撤销证明＋产出物落位卡（≈0.35d，末卡） + +- [ ] 改后 `python tools/gdstyle_gate.py` 对拍：基线外 NEW＝0、恶化＝0、在案键计数较改前下降；81 键消失清单与 5 键残留读数表写进实现报告。可核查结果：读数对拍表在案。 +- [ ] 逐 wr 行撤销证明（§8.1 末列——回退对应文件 hunk→gdstyle 直扫该键重现（或改址断言红）→还原复绿），记录进实现报告。 +- [ ] 写齐三份产出物（实现报告〔81 键清偿清单＋5 键残留申报＋读数对拍表＋实机目检总清单——启动冒烟实机一屏登记（行为零变化批，登记不阻塞）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈4.9d**（区间 4.6–5.3：T0 0.2／T1 0.7／T2 0.7／T3 0.7／T4 0.35／T5 1.0／T6 0.9／T7 0.35；T5 扩容主因 K2 的 139 处测量面改址——机械改写）。 + +### T 卡间接口 + +- **取用**：T1–T6 各自文件域独立、零相互取用；T7 取用各卡读数记录。 +- **产出**：T1–T6 各产出本组「键清偿读数＋受涉套件绿读数」（T7 汇总）；T6 产出 K4 词典键形（"kind/tier" 复合键）与 K5 方法签名 `last_round_end() -> Dictionary`（反哺点③改写依据）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动（文件:行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 校验族大表组 17 键 | 五 schema validate 拆分 | data_config＋core 受涉套件直跑全绿〔现役错误清单断言面＝逐字等价载体〕＋gdstyle 直扫五文件键消失 | 单元 | ConfigDb.load_tables 真实加载入口（套件经 _ready/load_tables 驱动） | 回退该文件 hunk→gdstyle 直扫该键重现→还原复绿 | +| wr2 校验族小表组＋跨表＋解析 23 键 | 八文件拆分 | 同上形态（八文件受涉套件）＋直扫键消失 | 单元 | 同上 | 同上 | +| wr3 跨表校验器/解析器错误序等价 | cross_validate 七域＋resolver 三域 | config_db_cross_validator_test（悬空/池构成判据）＋config_db_resolver_test（ceil/clamp/告警去重判据）全绿 | 单元 | load_tables 加载期跨表通道＋resolve_* 调用 | 同上 | +| wr4 board_generator 8 键 | 四域拆＋_finalize 5 参 | board_generator_test／board_gen_reward_test 全绿＋同种子逐位一致（T0 基线对拍） | 单元＋集成 | generate 真实调用（表驱动+rng_stream 注入） | 回退 hunk→同种子对拍失配或直扫键重现 | +| wr5 node_map_generator 9 键 | 六阶段拆＋两分＋构建域 | node_map_generator_test／node_map_growth_test／node_map_determinism_test 全绿 | 单元＋集成 | generate(参数档, 种子) 纯函数入口 | 回退 hunk→determinism 断言红或直扫键重现 | +| wr6 effect_engine 8 键 | 三装载域＋四算子域＋两键域＋elif 收口 | effect_words_t1／tree_rules_v11／counter_prefix_fatal／adventure_feats／round_flow_skill_pool 全绿（装载序/词表/计数器面现役断言） | 单元 | rebuild→dispatch 真实战斗链 | 回退 hunk→直扫键重现 | +| wr7 散条 A 10 键中清 8＋K2/K3 | save/status/treasure/meta 拆分＋私有化＋改址 | §T5 所列受涉套件全绿（断言语义逐条保持）＋直扫四文件键读数 | 单元＋探针 | autoload _ready＋套件真实驱动 | K2/K3 撤证＝改址测试红（_ 前缀方法不存在）；拆分键＝直扫键重现 | +| wr8 config_db K1 | 删 2 访问器＋私 1 包装 | grep 两删除名零命中＋config_db_test／forge_table_test／table_structure_guard 全绿 | 静态＋单元 | load_tables 入口 | 恢复方法→gdstyle 直扫公开方法键回 44 | +| wr9 adventure_table 词典化 K4 | 36 槽→3 词典＋.tres 迁移＋4 处改址 | adventure_feats/pool_case_d/feat_vouchers/table_structure_guard 全绿＋deck_total()=102 结构锚＋直扫类变量键消失 | 单元 | 表加载→访问器读数真实链 | 回退 hunk（含 .tres）→改址测试红（词典键不存在） | +| wr10 散条 B 其余 8 键中清 7＋K5/K6 | action/reward/minesweeper/unit 拆分与合并 | minesweeper_rules_test／round_flow_skill_pool round_end 载荷／reward_roll 流序／spawn 前置套件全绿 | 单元 | 各系统真实调用链 | 回退 hunk→对应断言红（last_round_end() 方法不存在/取号序失配/事件序失配）或直扫键重现 | +| wr11 读数对拍＋产出物 | T7 | 读数对拍表＋三份产出物件核〔wr11〕 | — | — | 缺项红 | + +回归措辞：里程碑步（T 卡）出口跑一次全套闸（按本批改动域选档）；卡内修复只做出红最小单元的最窄确认；新增测试先行孤立验证再并入全套。本批零新增测试断言（现役断言面即验收载体）。 + +### 8.2 测试削弱申报 + +零（无断言删除、无阈值放宽、无扫描面缩小；全部测试改动＝K2/K3/K4/K5 列明的调用点改址，断言语义与判据逐条保持——契约 2）。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝①错误清单逐字等价（任选三 schema 改前改后坏表对拍读数）②生成器同种子逐位一致记录③效果引擎装载序与词表零 diff（git diff 查 EVENTS/EFFECT_KINDS/FACTS/OPS 四常量）④K1–K6 消费方改址抽检（每项 ≥3 处断言语义等价）⑤S13 基线未改（git diff 查 `tools/gdstyle_baseline.txt` 零变化）⑥撤销证明复现。未过不得合并。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 基线对照自核）；私有 helper 命名与注释措辞；拆分域边界微调（各件 ≤阈值前提下）。 +- **L2（记录继续）**：K2 改址中发现清单外测量面调用点（同法改址＋计数记录进实现报告）；词典键形实现细节微调（复合键分隔符）。 +- **L3（停机呈报）**：任何断言红且非测试问题；拆分后错误清单与改前不等价；RNG 取号序失配；发现触碰 GDD/owner 契约的病根（停卡呈报，禁内联求裁）；机检键与契约互斥（契约 3/4）；K 清单外须动公开面的场景（实现段零裁断——退回上游）。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 私有 helper 的命名与注释措辞（语义不变前提下）。 +2. 拆分域边界的等价微调（各件 ≤阈值、错误序/RNG 序不变前提下）。 +3. K2 改址的等价调用写法（_ 前缀调用语义不变前提下）。 +4. 提交切分与 worktree 分支命名。 + +## 11. 待裁点（两项，裁决后开工门=U0） + +**裁点 1 · config_db 双键清偿深度**（公开方法 44/20、类变量 25/15）： +- **案 A（推荐）＝本卡裁定集内收敛（44→41、25→25 零改善）＋残留申报尾波**。依据＝2026-10-26 裁定（D4）方法集为「删冗余、私有化内部方法，不动对外语义」——该集内可删除件＝3 个零生产消费方法，可达上限 41；类变量 19 个类型化持有变量是全部生产消费路径（实测 db.hero 159 处／db.settlement 177 处等数百处直读），可删集＝空集。残留 21＋10 键随尾波或另立项。 +- **案 B＝访问器归位＋持有词典化（可清零）**：32 个行族访问器迁 owner 表类（shop_* 9／meta_* 3／forge_* 6／treasure_* 3／feat_* 2／tree_* 2／skill_row／status_effect_row／level_* 3／variant_* 2——owner 表已有同源读取方法，config_db 保留 12 个加载/解析/诊断公开件 ≤20 ✓）＋消费方约 40 文件改址（+≈1.5d）；类变量词典化另需数百处直读改址且破坏类型化读取（不推荐，若采 B 则类变量仍残留）。依据＝语义不变但属门面重组，触及 AGENTS.md「经 ConfigDB 单点读取」表述的解释边界（db.shop.gp_drop_row() 仍经 ConfigDB 持有）——**超出 D4 方法集，须用户明示裁准**。 +- **淘汰依据**：案 B 在 D4 既裁方法集之外，写卡段不得自援。 + +**裁点 2 · save_manager／meta_progression 公开方法清偿深度**（52/20、31/20）： +- **案 A（推荐）＝本卡私有化收敛（52→42、31→25）＋残留申报**。依据＝零生产消费方法共 13 个已全数纳入 K2/K3；余 42＋25 件全部有生产消费方，收敛到 20 需域对象拆件（槽位域／生涯计数域／锻造域子对象化）＝新文件＋架构登记（波 1 BattleFxHost 先例形态），超出波 8 纯代码裁定。 +- **案 B＝域对象拆件另立项**（清零两键）：按变化原因拆 SaveSlots／MetaTree 等域件，架构模块表登记新件行——独立走设计段＋写卡。 +- **淘汰依据**：案 B 需设计前置，非本卡（纯代码批）可承载。 + +两裁点均不影响本卡已承诺的 81 键清偿范围；裁 A＝本卡即终态（残留键数进尾波账），裁 B＝扩大或另立（编排段重排）。 + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 写卡会话，grilling 自检一轮合并执行——对抗审点逐条过并就地折入）**： +- ①规格覆盖：86 键逐文件→T1–T6（大表组/小表组/生成器/效果引擎/散条 A/散条 B）→wr1–wr10，读数与产出物→T7/wr11；81 清＋5 残账目闭合；K1–K6 公开面改动逐项有改法＋消费方影响面＋验收行。**折入**：初稿曾漏 unit_container spawn 参数键的卡 1 冲突处置——补 K6 残留裁定与 §0 说明。 +- ②步骤扫描：每步一动作一可核查结果（拆分步挂「受涉套件绿＋直扫键消失」双结果）；无 TBD/酌情行；实现体零抄写（helper 只给签名与域边界）。 +- ③类型一致性：K4 词典键形（"kind/tier"）、K5 方法签名 `last_round_end() -> Dictionary`、K6 私有拆分签名与 T6 步骤逐字一致；wr 行与 T 卡引用对得上。 +- ④审查焦点＋改动覆盖：最可能坑到玩家的失败模式＝①错误清单不等价（fail-fast 面变形）→ 现役 data_config 断言面逐字保留＋审计①对拍；②RNG 取号序漂移（生成/奖励面）→ 契约 1②＋T3/T6 同种子对拍；③效果引擎装载序漂移（种子复放）→ 契约 1④＋T4 调用序钉死＋审计③四常量零 diff；④K4 .tres 迁移值错位 → 等值迁移＋deck_total=102 结构锚。结构图中全部行为改动行＝「非行为」并指到 wr 行——**查毕确认零行为改动、无未覆盖失败模式**。 +- ⑤篇幅比例：全文无函数体，helper 为签名＋域边界；§3 现状表为键账载体非抄写。 +- ⑥落位与复用：零新增文件/数据件/新能力函数——私有函数族＝既有函数体域化重组，与「不抽共享骨架」既裁（D2）一致；唯一面（各文件私有作用域＋拟用名 grep 无同职责第二处）与分层面（零新跨层路径）已答；K1–K6 每项公开面改动可指到预检节条目。**折入**：初稿预检节未答「跨文件同名 `_validate_row` 是否散落」——补答（类作用域私有、既裁形态）。 + +**grilling 自检一轮结论（写卡段内自检，独立复核门仍须在开工前由用户/独立会话执行）**：骨架成立——账目闭合（86＝81＋5；45＋86＋71＋14＝216）、两待裁点均有代码事实支撑的推荐案与淘汰依据、零行为改动契约族完备。遗留提示三件随卡在案：①K2 改址 139 处为机械改写、工作量已计入 T5；②波 7 现成卡行号锚因本卡加重漂移（其 T0 义务）；③本卡与迭代 39 副卡同触 effect_engine.gd/meta_progression_forge_test.gd——编排错波。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员／别名／死存储；本批删除的 `_next_round_mode` 死存储与 3 个死方法即该契约的执行例——不得以「基线计数」「调试便利」等理由保留任何在删清单成员或新增同种件；机检键与卡片契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/待办清单.md b/待办清单.md index 3b3ed1f6..993a15bc 100644 --- a/待办清单.md +++ b/待办清单.md @@ -7,15 +7,18 @@ **实况**：S13 闸实测存量债 216 键／60 文件（2026-10-26，master f3b148ce，gdstyle v0.4.0 默认阈值；基线登记 234 键＝实存 216＋陈旧 18）。全量清单、波次方案与纪律见清点报告（本条目裁决源）。2026-10-26 用户裁：撤销「一条总账」与「按病根拆多条」两案，并为本条单账（存量债全部清除，紧急优先级）；原「gdstyle 基线陈旧键待人工清理」条目并入波 0（基线对账刷新），原「结构审查未立项小件候审」条目并入波 7（卡已写、停卡待裁）。**2026-10-26 设计段闭合（逐波裁定全数落定）**：①段组织＝逐波开设计段，纯代码波（波 0/2/3/4/5/6/8）写卡前确认零设计改动＋按当时 master 重测读数即可写卡；②波 2 各文件内部拆、波 6 视图内部拆私有函数、波 8 config_db 纯代码收敛（三处零设计改动）；③波 1 拆件定稿＝轴甲两件——battle_orchestrator 拆出 BattleFxHost（效果引擎宿主域）＋RewardGrant（奖励授予域），宿主保留状态机/facts 缓冲/订阅/段驱动/行发射基建/呈现投影，attune 族原位保留（迭代 39 副卡语义领地），emit 经 bind 注入 Callable，行数恶化债（c4c69701 挂账）本波还债归绿，残留债「改善非清零」口径预计 8–10 键；定稿落文 architecture.md v1.18（功能层两新件行＋「战斗编排域拆件定稿」节）；**同日独立审查折入**（grilling＋godot-master 双子代理并行、双判回炉补裁级——骨架成立、接线未闭合）：阻断 8 条去重 6 组＋建议 5 条全数折入 v1.18——跨件单向接线裁死（RewardGrant 持 fx 件引用/fx 兑付走注入 Callable，禁 RefCounted 环）、settlement/ 段类随动（直持三引用封转发壳）、12 随迁键卡内收敛义务（禁波 0 refresh 吸收）、两新件消费依赖列补全＋引用束注入、treasure_interact_controller 三触点分家（现值回调双取值面）、_fx_revealing 再入闸归 fx 件（裁定全文见清点报告 §六第 6 条）；④全部波不改游戏规则与玩家可见行为，design/gdd/systems/ 零修订预期；波 5 已实查落定纯代码（open_ticket 12 参＝单据声明形态）。波 7 的 wr5/wr6 验收载体重裁为写卡段用户裁点（卡 v1.2 在册，写卡补呈报）。裁定全文见清点报告 §六。 关联文档清单： -- 清点报告 reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（2026-10-26，216 键全量清单＋波次方案＋纪律＋设计段裁定记录 §六） +- 清点报告 reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（2026-10-26，216 键全量清单＋波次方案＋纪律＋设计段裁定记录 §六含整合裁定第 7 条） - 设计定稿 design/engineering/architecture/architecture.md v1.18（2026-10-26，波 1 两新件行＋「战斗编排域拆件定稿」节含审查折入） +- 需求卡片 reports/需求卡片-B1战斗域拆件批-2026-10-27.md（2026-10-27 v1.0，收编 45 键＝波1＋波3＋damage_controller＋treasure_interact_controller，估时 ≈4.25d；待裁点 2 项待用户裁） +- 需求卡片 reports/需求卡片-核心数据面结构收敛批-2026-10-27.md（2026-10-27 v1.0，收编 86 键＝波2＋波4＋effect_engine＋波8 core/data 侧，估时 ≈4.9d；待裁点 2 项待用户裁） +- 需求卡片 reports/需求卡片-呈现层结构收敛批-2026-10-27.md（2026-10-27 v1.0，收编 71 键＝波6＋波8 呈现侧，估时 ≈4.0d；待裁点 1 项两项可分别裁） - 需求卡片 reports/需求卡片-冒险域拆件与账本实体化批-2026-10-26.md v1.2（规避指向：三宿主债归此卡与姊妹副卡，本事项禁触，残留归尾波） - 需求卡片 reports/需求卡片-同调配装充能域封装批-2026-10-26.md v1.2（同上规避指向） - 需求卡片 reports/需求卡片-结构小件定点修批-2026-10-26.md v1.2（波 7 现成卡：iter38 卡②停卡退回上游，随本事项重裁验收载体） **改动面**：游戏代码＋工具代码 -**状态**：文档设计已闭合＋待写卡 +**状态**：文档设计已闭合＋已写卡 #### AdventureRunner 职责真拆分——三宿主共 25 条转发属性属 S13 计数迎合装置，须按变化原因重立协作件（2026-10-25 登记，来源=批次移交，优先级＝P0）