Merge branch 'master' into archp2-card
# Conflicts: # 待办清单.md
This commit is contained in:
DKChan committed
commit
940e6fc256
5 files changed
+405
-9
No files matched your search
@@ -2,8 +2,8 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.34
|
||||
- 最近更新：2026-11-03（架构审查 P1 余项·工程改动批随动——S8 行登记清单单点 `B1_SET` 与 settlement/ 目录域反向对账、S9/S10 空面自检查偏差清偿；沿革查 git）
|
||||
- 版本：1.35
|
||||
- 最近更新：2026-11-04（架构审查 5.2 文档漂移订正并入 P1 余项批之后——主角账三件与刷新账件四行补登记替代失效的 HeroLedger 行、MetaProgression 基础层补登记行（四 Autoload 唯一跨 Autoload 依赖件）、拆件定稿节冻结计数摘除（活体清单不冻结计数）、CurioStop 行落账指称随拆件改指；EC8 热重载规格经用户裁决保留原状（实装排期另立待办条目）、一度摘除已撤回，「抗热重载」快照句随规格保留；沿革查 git）
|
||||
- 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||||
- 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||||
- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准）
|
||||
@@ -88,6 +88,7 @@
|
||||
| **ConfigDB**（autoload，D2） | 全部玩法数值表与表现层布局配置表（`data/tables/*.tres` + `data/schemas/*.gd`）；加载/校验/override/诊断状态机。**行族访问器归位各 schema 表类（表管自己的行查询），本类只留加载/校验/override/诊断门面；表持有成员按域收进四张域容器 Resource（`config_domain_combat/run/crossrun/presentation.gd`——前三件迭代 41 已建件，第四件表现层布局域 2026-10-30 建件，类型化成员 7/7/5/1）；三张 resolver 表（board_gen.resolve_row／enemy.resolve_rowset／difficulty.resolve_modifiers）经 `load_tables` 装配段注入各容器，resolver 文件与键零搬移**——红线不变：本类仍是唯一加载与持有单点，"经 ConfigDB 单点读取"＝经其持有的表对象 | 类型化域容器属性（每域一张容器）；公开面 8（push_diag／is_fatal／reset_diagnostics／diagnostics／diagnostics_count／load_tables／set_reload_gate／reload）、类变量 10 | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW |
|
||||
| **SlotStore**（`core/slot_store.gd`，D3 存档槽位域件，已建件——迭代 41 存量债批） | 存档三槽位文件域唯一所有者（自 save_manager 收编槽位族）：槽位挂载与模板、激活与建删、槽位摘要窥视（peek 族）；改名覆盖原语（_rename_overwrite）留 save_manager（IO 原语单点） | 槽位读写原语族＋摘要投影（公开 10／类变量 4；SaveManager 与菜单消费方经 `save.slots.` 直连） | save_manager（注入路径与模板配置）；FileAccess——LOW |
|
||||
| **MetaStateStore**（`core/meta_state_store.gd`，D3 存档内元进度数据件，已建件——迭代 41 存量债批） | 存档内元进度数据的读写唯一层（自 save_manager 收编 accessor 族：钥石/道具解锁/树节点与叉侧/锻造路线/同调/真视/计数器/摘要——数据读写原语，不含业务规则）；save_manager 与 meta_progression 双 God Class 的共同病根＝该数据域摊在两文件，本件即其归一 | 写口原语 13＋只读投影 6（tree_state/forge_state/attune_state/career_state 四投影＋keystone_balance/item_unlocked）＝公开 19（add_keystone 私有 `_add_keystone`），零 _data 副本零缓存；MetaProgression 业务层与营地/锻造 UI 消费方经 `save.meta_state.` 直连（meta 的纯转发读方法已退役） | save_manager（序列化接线）；FileAccess——LOW |
|
||||
| **MetaProgression**（autoload，`core/meta_progression.gd`，D3 元进度业务层） | 元进度账本服务：钥石收束入账、营地消费定价与秘宝解锁判定的纯被动服务，零信号零外发；数据读写全经注入的 MetaStateStore（`save.meta_state.` 直连）；hero_override() 现算不写表（全零＝白板合法态——生效注入只走冒险开始参数面显式传参） | 写口族（天赋树购买/叉侧切换/锻造解锁与升级与选中/同调装配切换等）＋解锁判定与读投影；**构造双形态**＝autoload 装配走 `.new()` 零参＋`_ready` 从 autoload 链取依赖（工程序 ConfigDB→RngService→SaveManager→MetaProgression，注册顺序即依赖序），单测/工具走 `.new(db, save)` 直构形态（不入树零 _ready）——**四个 Autoload 中唯一有跨 Autoload 依赖的件（ConfigDB/SaveManager）** | ConfigDB（定价与档位表值）；SaveManager（存档访问器，经节点路径延迟取用） | autoload 生命周期——LOW |
|
||||
| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 |
|
||||
| **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁；dig_paid 命中施加抽私有单点（_apply_dig_paid_hits——矿脉储能入池面） | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh（收折后价入参——折价计算归 BattleRefreshFlow 单点）/ notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读；实测类变量 10 | ConfigDB（ActionEconomyTable）；EffectPort（效果端口件——发射经端口单点；2026-11-02 轴戊设计闭合、迭代 49 卡① 建件，effect_engine 直连退役）；B1 回发 next_round_mode/battle_over | 无 |
|
||||
| **variation 定义**（A4） | VariationTable schema（现行 6 行：六 region——贫矿脉 global 行 2026-10-16 用户令屏蔽删行，global 型机制代码保留）与 F1 候选池门控谓词 | `variant_pool(level_index, board_type, node_type="")`（门控三维：unlock+board_types+节点身份——global 行仅 boss/elite 入池，缺省跳过零扰动）；`global_variant_row(level_index, board_type, node_type)`（全局型单行决议访问器） | ConfigDB（VariationTable） | 无 |
|
||||
@@ -107,9 +108,12 @@
|
||||
| **helper_items**（A5，切片已实装秘宝域） | HelperItemTable、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 |
|
||||
| **CurioDeck**（`core/curio_deck.gd`，A5 秘宝域令牌池件，迭代 37 自 AdventureRunner 拆出） | 三选一/商店共享池的持久多重集、抽签（候选抽取）、cap 库存与专长凭证三计数与判定唯一所有者——件只管池与判定，停点编排与兑付推进留冒险编排器 | `draw_candidates(channel)` 抽签；`consume_deck_token` / `consume_pool_purchase` 池消耗；`cap_ok` 上限判定；`feat_ticket_consider` 凭证判定；`stock_snapshot` / `pool_stock` 只读投影；商店购买消费经注入 Callable 链至 CurioStop 兑付单点（迭代 39 起转纯池——bind_handlers 反向回调已退役） | ConfigDB（秘宝令牌行集）；注入 RngServiceCore（reward_pick 封闭流，禁自建随机） | 无（RefCounted 纯逻辑） |
|
||||
| **ShopSession**（`core/shop_session.gd`，商店会话件，迭代 37 自 LevelRunner 拆出） | 关卡商店双模式（legacy 固定三件加定价／pool 共享令牌池）的货架、定价、购买与刷新唯一宿主——账本/钱包/装配集归宿主 LevelRunner（共享引用经 `bind` 注入，出账直接落同一引用改写宿主账本）；legacy 模式零 RNG 零池消费（off 对照承载） | 货架与定价只读面（`shop_products` / `shop_shelf` / `current_price` / `shop_refresh_cost`）＋写入口（`buy_product` / `buy_pool_item` / `shop_refresh` / `player_request_refresh` / `open_pool`）；外部调用面＝调用方经宿主 LevelRunner 公开成员 `shop` 直连（调用直连不留委托壳，2026-10-26 Middle Man 裁定；迭代 42 拆除），直连消费的方法＝`shop_products`／`current_price`／`purchased_tier`／`buy_product`／`player_request_refresh`／`set_shop_pool`／`pool_price`／`shop_shelf`／`shop_refresh_free_left`／`shop_refresh_cost`／`shop_refresh`／`spend_gp`／`buy_pool_item`／`is_shop_pool`／`shop_bp_shelf`／`shop_bp_visit_buys`（另白盒两入口仅测试侧：`_draw_shelf`／`_spend_discounted`）；set_shop_pool 调用面＝pool 注入经 LevelRunner 构造 ctx 供给（构造期内部直调，原委托块注释「AdventureRunner._start_current_level 唯一调用方」系陈旧表述、随壳删除作废），测试面直连 `shop.set_shop_pool` | ConfigDB（商店行集）；注入 RngServiceCore；宿主钱包/账本引用；pool 模式令牌消耗与判定经注入 Callable 转 CurioDeck | 无 |
|
||||
| **HeroLedger**（`core/hero_ledger.gd`，冒险域主角实体账，已实装（2026-10-27 迭代 39 拆件批）） | 冒险生命周期主角数值与获得记录唯一所有者：生命与 GP 钱包（gain/spend/clear 单写原语，钱包事件发射点归件）、锻造强化快照、调试百分比、攻击/甲类型轴快照、特性持有集（活引用注入——关内兑付当关生效）、本局钥石增量与逐杀明细、真视使用记录；获得记录三层结构＝获得记录列表（三选一件/商店购买/战末奖励各一条）→属性增益明细（带来源指回）→四轴汇总（由明细推导）；生效上限与回血封顶公式单点归件 | 构造注入；单写原语族＋只读投影；断点自交片段（账本键＋获得日记键） | ConfigDB（表值读取）；由 AdventureRunner 冒险开始创建、注入 CurioStop／level_runner／ShopSession／战斗 encounter | 无（RefCounted 纯逻辑） |
|
||||
| **HeroStats**（`core/hero_stats.gd`，主角数值账件，已实装（2026-10-27 迭代 39 拆件批——原 HeroLedger 登记行拆件替代）） | 冒险生命周期主角数值域唯一所有者：生命账与特性持有集（活引用注入——关内兑付当关生效）、锻造强化快照、调试百分比通道、攻击/甲类型轴快照、生效上限/攻击/护甲公式与回血封顶公式单点、续玩生命钳制收口；生效公式经注入 GainJournal 只读引用取加算区汇总（无反向引用不成环） | 构造注入；单写原语族＋只读投影；断点自交片段（账本键） | ConfigDB（表值读取）；注入 GainJournal（只读）；由 AdventureRunner 冒险开始创建、注入战斗 encounter | 无（RefCounted 纯逻辑） |
|
||||
| **GainJournal**（`core/gain_journal.gd`，加算日记件，已实装（2026-10-27 迭代 39 拆件批）） | 统一冒险加算区与获得记录唯一所有者：获得记录三层结构＝记录列表（三选一件/商店购买/战末奖励各一条）→属性增益明细（带来源指回）→四轴汇总（由明细同步维护）；三写通道统一走 gain_bonus 单写原语（source_class＝curio_pick/shop_product/battle_export）；本局钥石增量与逐杀明细、真视使用记录、商店已购档数记账同域 | gain_bonus 单写原语；记录与汇总只读投影；断点自交片段（获得日记键） | 由 AdventureRunner 冒险开始创建、注入 CurioStop／level_runner／ShopSession／战斗 encounter（战末 bonus 四轴经 gain_bonus 汇入） | 无（RefCounted 纯逻辑） |
|
||||
| **GpWallet**（`core/gp_wallet.gd`，GP 钱包件，已实装（2026-10-27 迭代 39 拆件批）） | 冒险局内货币唯一所有者（LevelRunner 与 ShopSession 读写全指此单点；冒险开始＝0、收束清零，不入存档不入摘要） | gain/spend/clear 单写原语 | 由 AdventureRunner 冒险开始创建；宿主与商店经注入引用读写 | 无（RefCounted 纯逻辑） |
|
||||
| **RefreshBank**（`core/refresh_bank.gd`，刷新账件，已实装（2026-10-27 迭代 39 拆件批）） | 三选一刷新三源账唯一所有者：X 刷新件每碰三选一重给（优先消耗不结转）／Y 营地升级行冒险周期池（用完即无）／刷新券存量账（冒险级跨停点持久）＋GP 付费刷计数与报价公式；零停点态依赖（免费/付费支出的编排归 CurioStop，本件只记账） | 支出与余量原语＋报价公式；断点自交片段（refresh_stock/attune_refresh_y 两键，Y 缺键回退参数面） | ConfigDB（刷新件与营地升级行表值）；注入 CurioStop 支出路径 | 无（RefCounted 纯逻辑） |
|
||||
| **AttuneLoadout**（`core/attune_loadout.gd`，同调配装件，已实装（2026-10-27 迭代 39 拆件批）） | 装备中的秘宝件对象集唯一所有者（每件内含充能单位与重置周期）；同调充能的物化行为唯一事实源——种行/补行改写时同步（RunLedger 充能字典轨与差额对账函数退役）；旧档 aux_items 同调行迁移归件 | 构造注入；充能查询/消耗/按周期重置原语；断点自交片段（attunement_charges 键，键名与策略不变） | ConfigDB（秘宝行集）；TreasureItems（同调行投放面）；注入战斗使用路径 | 无 |
|
||||
| **CurioStop**（`core/curio_stop.gd`，三选一停点件，已实装（2026-10-27 迭代 39 拆件批）） | 三选一停点编排唯一所有者（架构原则 9 本域承载）：停点三态（关卡完成三选一在途/已兑付待推进/奖励节点三选一在途）、刷新三源账（刷新件 X/营地池 Y/刷新券存量/付费刷新计数）、兑付方法族（pick/refresh/redeem/skip）、凭证出箱（RAP/时沙待注入）；三选一信号面自带；零自动推进停点语义承载 | 对外＝开停点/刷新/兑付/放行谓词/交断点片段五组入口＋信号面（curio_choice_presented/curio_resolved）；由 AdventureRunner 关卡完成受理时调用 | ConfigDB；注入 CurioDeck（抽签/摘牌）与 HeroLedger（落账）；随机只经 CurioDeck 的 reward_pick 封闭流 | 无 |
|
||||
| **CurioStop**（`core/curio_stop.gd`，三选一停点件，已实装（2026-10-27 迭代 39 拆件批）） | 三选一停点编排唯一所有者（架构原则 9 本域承载）：停点三态（关卡完成三选一在途/已兑付待推进/奖励节点三选一在途）、刷新编排（三源账面归 RefreshBank 件、查停点态→支出→重抽重发编排留本件）、兑付方法族（pick/refresh/redeem/skip）、凭证出箱（RAP/时沙待注入）；三选一信号面自带；零自动推进停点语义承载 | 对外＝开停点/刷新/兑付/放行谓词/交断点片段五组入口＋信号面（curio_choice_presented/curio_resolved）；由 AdventureRunner 关卡完成受理时调用 | ConfigDB；注入 CurioDeck（抽签/摘牌）、HeroStats 与 GainJournal（兑付落账单写原语）、RefreshBank（刷新支出）；随机只经 CurioDeck 的 reward_pick 封闭流 | 无 |
|
||||
| **breakpoint_store**（`core/breakpoint_store.gd`，冒险域·断点组装与回放件，已建件——迭代 45） | 存档断点组装与回放唯一承载（自 adventure_runner 收编 6 成员＋函数族）：断点快照拼盘、回放回填、读侧策略分发；`BREAKPOINT_FIELDS` 27 键登记单源随件（键名/策略标签/键序冻结） | 构造＝引用束注入（九引用束成员解包为原名成员——保迁移函数体逐字）；`resume_adventure` 留宿主（壳＋宿主侧回填语句——R2 所有权缝分家）；断点键面零变化；实测类变量 15（贴顶禁再增） | adventure_runner（宿主）；注入主角账三件与 curio/stop/bank/loadout 引用 | 无（RefCounted 纯逻辑） |
|
||||
|
||||
### 功能层
|
||||
@@ -136,7 +140,7 @@
|
||||
|
||||
### 战斗编排域拆件定稿（2026-10-26 用户裁写入——gdstyle 存量债波 1 设计闭合；同日独立审查（grilling＋godot-master 双子代理）阻断 8 条去重 6 组全折入本节，v1.18；2026-10-28 迭代 40 实现批合回（合并提交 514457d1），本节为现状登记）
|
||||
|
||||
- **轴甲两件**：battle_orchestrator（1313 行／50 成员，S13 全库单文件最大户）按变化原因拆出 BattleFxHost（效果引擎宿主域）与 RewardGrant（奖励授予域）两协作件；宿主保留架构在册职责全部——战斗状态机与生命周期、轮 facts 缓冲（_facts_reveals/seals/path）、A2 三事件订阅、结算五段驱动、attune 族原位、行发射基建（_emit_row/_assert_row_source/_fatal）、呈现投影（presentation/diagnostic_snapshot 唯一出口不变）、刷新面、nest_preview_count（巢穴预告读数口——外部直读面 main.gd 与 treasure_effects_test 随批点名冻结）。拆件动机与残留债口径见待办清单「gdstyle 存量债全量清偿」条目。
|
||||
- **轴甲两件**：battle_orchestrator（拆件时 S13 全库单文件最大户——行数与成员数为历史读数，冻结计数不登记，查 git）按变化原因拆出 BattleFxHost（效果引擎宿主域）与 RewardGrant（奖励授予域）两协作件；宿主保留架构在册职责全部——战斗状态机与生命周期、轮 facts 缓冲（_facts_reveals/seals/path）、A2 三事件订阅、结算五段驱动、attune 族原位、行发射基建（_emit_row/_assert_row_source/_fatal）、呈现投影（presentation/diagnostic_snapshot 唯一出口不变）、刷新面、nest_preview_count（巢穴预告读数口——外部直读面 main.gd 与 treasure_effects_test 随批点名冻结）。拆件动机与残留债口径见待办清单「gdstyle 存量债全量清偿」条目。
|
||||
- **轴丙一件（2026-10-29 尾波清偿批设计闭合——实现批建件）**：battle_orchestrator 装板域六函数（`_install_new_board`／`_resolve_global_variant`／`_place_variants`／`_place_variants_apply`／`_variants_fringe`／`_adjacent_to_packs`，约 140 行；全仓仅宿主三调用点——begin_battle／中途刷新受理／player_request_refresh，实查零外部调用）按变化原因拆出 BoardInstaller，职责语句「棋盘安装与变异布置域」（生成→全局变异决议→装板受理→资源摇号→变异布置；单一变化原因＝棋盘设置顺序与变异布置算法）。形态两修正（实测裁，与初案「逐字搬运」之差）：①宿主复位块不随件——`_install_new_board` 体内五处计数清零、板序推进、board_changed 发射与秘宝叠加层退役留宿主薄壳 `_install_and_reset`，三调用点改调薄壳、时序逐字；②`_board_generator` 全文件仅装板族使用——实例随件自建自接线（fatal 经注入 Callable），宿主成员退役（类变量 38→37，禁无效成员义务）。encounter（23 处跨宿主）与 _reward_economy（18 处）确认留宿主、经引用束注入。文件长键（1035/1000）随本件迁出归绿；attune 族与 begin_battle 受理段序禁动不变。
|
||||
- **轴丁两件（2026-10-29 零豁免裁设计闭合——实现批建件）**：RoundCycle（轮循环驱动件）与 BattleFacts（战斗事实件）见功能层表两行——宿主 38（轴丙落地后 37）→15，S13 豁免第三条注销；宿主保留面改登记为「战斗状态机与生命周期、行发射基建（_emit_row/_assert_row_source/_fatal）、呈现投影（两快照出口签名不变）、刷新面、nest_preview_count」；attune 族处置由下一条改判；treasure_inventory 注入改址追认——原「外部赋值路径零改址」句失效，level_runner 经 RewardGrant 出口直注；成员级对账以需求卡片为卡内契约（开工 T0 复核）。
|
||||
- **轴戊两件（2026-11-02 用户裁甲案设计闭合——已建件，迭代 49 卡① 合回，git 提交 848723b5）**：①**效果端口件 EffectPort**（`core/effect_port.gd`）——职责语句「战斗业务类唯一的效果发射出口：收事件与载荷、交效果引擎结算、取回命中批」；实测形态＝六 Callable 路由、bind_port 组装期转注、闭面五键 biz_fact、未绑零扰动缺省；`DamageController`／`ActionEconomy` 各持端口引用（同一实例、构造注入），`EffectEngine`／`EffectContext` 引用与计数器账面（value_counter 层值读后清零）收归宿主侧（BattleFxHost 域），业务类零引擎直连、零账面触碰；facts 取值束（dig_streak/charge_layers/rider_tier_*）与入站回调束（reveal/ac）随发射契约归宿主侧注入面；端口**单实现零接口抽象**（无基类无多态——GDScript 无 interface，本案不需要）；端口与宿主经注入 Callable 束协作、零宿主对象引用（跨件单向接线条款适用，禁双向强引用）。②**掷格件 RewardRoller**（`core/reward_roller.gd`）——职责语句「装配期格面资源摇号：池行装配、区间行 roll、权重合成（偏运硬币/board_skew 两路投影）」；实测形态＝roll 批束四键（mapping/power_roll/clear_identity/clear_power）、选行算子 `_weighted_pick_row` 返表行、fatal 经构造 Callable 链；受理账面（grant/身份查询/快照/retire/polarity_row）留 `RewardEconomy`，衔接面＝格→奖励身份映射（掷格件产出、受理件接收）；掷格件经注入 RngServiceCore 取号（roll_board 流 scope＝每次 install 批不变、取号序零漂移）。行为零变化红线沿本节「验收红线」全款：命中序＝声明序、明细行协议词表零触碰、`_ineffective_row` 载荷 deferred 自描述键观测面不回退（2026-11-02 迭代 48 卡① 甲案在案）、EV/MC 锚同种子逐位零漂移——round_flow 逐位回放 134 检查为主证（红线成立）；两新件 S13 预算随卡「实现规范预算」三查已过（新件全默认阈值内、gdstyle 基线外新违规 0），`RewardEconomy` 类变量随掷格面迁出 15→11；S7 B1 域文件集与 S8 await 文件集已随批增行。
|
||||
@@ -151,9 +155,9 @@
|
||||
|
||||
### 冒险域拆分（现状登记——2026-10-26 设计闭合，2026-10-27 迭代 39 拆件批实装，本节各条即现行形态）
|
||||
|
||||
- **应用层形态**：adventure_runner 退出上帝对象、转薄应用层（DDD 应用层形态）——只留冒险状态机、关序推进、结算受理、建件接线、效果引擎冒险桶字典持有（桶＝效果引擎域数据，应用层只锚定生命周期）；零领域决策。核心层表三新件行（HeroLedger／AttuneLoadout／CurioStop）即本拆分目标。
|
||||
- **应用层形态**：adventure_runner 退出上帝对象、转薄应用层（DDD 应用层形态）——只留冒险状态机、关序推进、结算受理、建件接线、效果引擎冒险桶字典持有（桶＝效果引擎域数据，应用层只锚定生命周期）；零领域决策。核心层表新件行（主角账三件与刷新账件／AttuneLoadout／CurioStop——见基础层与功能层登记）即本拆分目标。
|
||||
- **CurioDeck 转纯池**：bind_handlers 反向回调退役；商店购买消费经注入 Callable 链至 CurioStop 兑付单点——牌库只管抽签/消耗/cap 判定/凭证计数。
|
||||
- **RunLedger 退役**：四账各归其主——加算区/购买记录/钥石增量/特性集/真视记录归 HeroLedger，充能归 AttuneLoadout，冒险桶字典归应用层持有；战斗侧 encounter 注入面由单一账类引用改为多路（桶字典＋实体账＋配装件）；ShopSession 账本引用面同步换代，商店属性商品加算改经 HeroLedger 单写原语。
|
||||
- **RunLedger 退役**：四账各归其主——加算区/购买记录/钥石增量/真视记录归 GainJournal、特性集归 HeroStats（GP 钱包归 GpWallet），充能归 AttuneLoadout，冒险桶字典归应用层持有；战斗侧 encounter 注入面由单一账类引用改为多路（桶字典＋实体账＋配装件）；ShopSession 账本引用面同步换代，商店属性商品加算改经 GainJournal 单写原语。
|
||||
- **level_runner**：依赖改构造注入一次给齐（后置 setter 群与商店重绑机制退役；注入活引用禁快照——特性集共享引用语义保留）；商店白盒转发属性撤除；战斗→关卡信号转发族保留（战斗实例每节点新建，关卡层做战斗域稳定面）。
|
||||
- **断点片段化**：各件自写自读自己的键（关卡层交关卡域五键片段：node_id/visited_ids/aux_items/shop_shelf/shop_visit_buys），缺键回退策略随领域知识归各件；应用层唯一落盘口（收齐各件片段拼成顶层快照后写盘），写触发点不变（五处）；既有 27 键逐键冻结；新增获得日记键沿扩列不升版先例——旧档缺日记回退汇总键直载并跳过比对，日记在档时由日记推导汇总、与留存值不符即报错中止（迁移正确性自检）。2026-10-29 零豁免裁随动：拼盘与读侧策略机组拆出 breakpoint_store（核心层表新行），应用层落盘口与写触发点不变——宿主经件组装快照后写盘，27 键冻结不变。
|
||||
- **信号直连**：adventure_runner 六转发信号族（node_entered/choices_presented/step_row/round_started/board_changed/wallet_changed）退役；呈现层在 level_started 重取点重订阅关卡对象信号（旧实例连接随引用释放消亡）；「关卡开始信号前零发射」契约写进关卡件头注；「恰好连接一次」断言用 is_connected 守卫（release 模板剥 assert）；三选一信号面归 CurioStop。
|
||||
|
||||
@@ -34,6 +34,12 @@
|
||||
### 1.5 禁止事实约定
|
||||
任何"大家默认这么做"的惯例必须成文进本文件（或 AGENTS.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
|
||||
|
||||
### 1.6 拆分交接与封装边界
|
||||
本节管拆分类改动的交接面与封装面，与 §1.1 拆分判据（职责轴）配合使用：§1.1 管怎么切，本节管切完之后件与件之间怎么往来。
|
||||
|
||||
1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——架构文档「战斗编排域拆件定稿」节 BoardInstaller 行在册）。
|
||||
2. **封装边界**：任何代码不得访问其他对象的下划线成员；跨对象往来只走公开方法与属性。为什么：下划线只是命名约定，语言不设防、无编译期检查——此条是封装硬纪律，违者即红。
|
||||
|
||||
---
|
||||
|
||||
## 2. 契约纪律——跨层/跨类调用的语义
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# 处置：架构审查 5.1 封装修复批（2026-11-03）
|
||||
|
||||
> **性质**：设计讨论段过程稿（裁决记录＋取证事实）。**接收方**＝reports/需求卡片-架构审查5.1封装修复批-2026-11-03.md ＋ 待办清单条目「架构审查优化讨论——全库架构审计读数的逐条裁决与整改分批」（2026-10-29 登记）。**寿命**：需求卡片成立即退役（吸收即死——结论吸收进卡片与 code-conventions，未决迁待办清单）。
|
||||
> **输入**：reports/审计-全库架构审查-2026-10-29.md §5.1（settlement 五段类直读写编排器私有成员；讨论段把普查扩到全库同模式面）＋ 2026-11-03 讨论会话用户逐项裁决 ＋ 2026-11-03 会话取证（19 符号逐个核过、行号为当日现址——行号写卡段复核）。
|
||||
|
||||
## 一、总判据（用户 2026-11-03 裁，本批一切设计遵循）
|
||||
|
||||
1. **拆分判「错」的口径＝交付物缺交接**：拆分的完整交付物是一个独立的类，须同时含职责边界与交接定义——构造时拿到什么、回调原类什么、只经公开面往来。五次拆件五次不合格。
|
||||
2. **修复＝把五次拆件没做完的交接补完**：代码位置不动、职责归属零改动，只补构造交付与回调。
|
||||
3. **编排器保留面＝architecture.md:141 登记原样**（战斗状态机与生命周期、行发射基建 _emit_row/_assert_row_source/_fatal、呈现投影、刷新面、nest_preview_count），本批零增零减。
|
||||
4. **法律先于修复**：code-conventions 两条增补先落（＝§1.6 拆分交接定义＋封装边界，本批交付二），两条是本批修复与后续闸件的共同依据。
|
||||
5. **GDD 零改动**（零行为变更的设计讨论，不触任何系统规则）。
|
||||
6. **范围**：core 五处进卡（编入需求卡片）；presentation 层约 227 行出卡（不在本卡，冻结期内单开设计讨论——修法＝视图补公开设置方法、装配代码改走设置方法）；sim/probe/tests 出卡（测量面直构惯例＋测试受控例外）。
|
||||
|
||||
## 二、根因（定稿陈述）
|
||||
|
||||
拆件交付物只写了职责边界、没写交接定义——拆出的件没拿到它需要的东西，每次需要都变成伸手回原类内部。三层防护全部缺位，三无叠加：
|
||||
|
||||
- 语言层：GDScript 无访问修饰符，下划线纯命名约定；
|
||||
- 规约层：code-conventions 全文无跨对象访问条文（已核）；
|
||||
- 闸层：S1–S13 无此扫描。
|
||||
|
||||
局部每处合理（19 符号逐个核过全是正当需要），整体边界溶解：累计约 390 行、20+ 文件。
|
||||
|
||||
## 三、普查五处（core 层；2026-11-03 会话取证现址，行号写卡段复核）
|
||||
|
||||
1. **settlement 七段→编排器**：105 行／107 处／19 符号（七段＝五段段类＋round_cycle＋battle_refresh_flow）。分布＝grant_segment 54／combat_segment 23／round_cycle 10／verdict_segment 9／battle_refresh_flow 5／aura_segment 2／decay_segment 2。构成＝成员引用 72 处＋编排器方法 35 处（逐符号与修后归属见五、总表）。
|
||||
2. **adventure_runner→BreakpointStore**：37 处直读写／32 行（5 行各含 2 处访问；_pending_next_level、_loadout_seeded、_resume_bp、_save_manager、_last_level_payload、_last_treasure_cleared、_bp_read）——adventure_runner.gd:37 注释自述「宿主读写经件」未落实。
|
||||
3. **save_manager→SlotStore**：9 行（slots._path 直读写 ×8＋slots._migrate_legacy_save 私有方法调用；save_manager.gd:51/66/69/105/111/118-119/285-286）。
|
||||
4. **grant_segment→BattleFxHost**：6 行直写 _fx_new_resource_types（:82/:84）与 _fx_bonus_delta（:169-170/:378-379）。
|
||||
5. **config_db→三表容器**：3 行装配期写 _resolver（config_db.gd:157-159）。
|
||||
|
||||
presentation 层同模式约 227 行（抽样核实、未逐行判读）——出卡另议：
|
||||
|
||||
| 文件 | 行数 |
|
||||
|---|---|
|
||||
| level_map_screen | 87 |
|
||||
| main_ui_build | 70 |
|
||||
| main_adventure_flow | 25 |
|
||||
| standee_body | 16 |
|
||||
| main_overlay_flow | 15 |
|
||||
| main_debug_flow | 11 |
|
||||
| main_esc_flow | 2 |
|
||||
| board_view | 1 |
|
||||
|
||||
## 四、逐项裁决记录
|
||||
|
||||
| 项 | 裁决 |
|
||||
|---|---|
|
||||
| 方向＝补交接 | settlement 七段构造时收六个子对象引用（战斗事实 BattleFacts、单位容器 UnitContainer、伤害控制器 DamageController、奖励经济 RewardEconomy、状态容器 StatusContainer、效果宿主件 BattleFxHost）＋七个编排器方法回调（_emit_row、_fatal、_install_and_reset、_battle_over、_exit_distribution、_emit_settlement_snapshot、_emit_composition_effects，以 Callable 交付）＋段间引用（授予段引用直接交换——battle_refresh_flow 不再经编排器 _rounds 链式取授予段，改为直接持有授予段引用）；编排器公开读数（round_index、db、action_economy、battle_result）一并改注入；段类对编排器引用归零。 |
|
||||
| 搬家五方法 | _hero_atk→伤害域、_feat_yield_adjust→奖励域（奖励授予件）、_harmful_variants 与 _harmful_adjacent→地形棋盘域、_hits_of→伤害域。 |
|
||||
| verdict 轮推进保留 | verdict 段经 _exit_distribution 触发轮推进保留现设计（架构在册七段结构，battle_orchestrator 段序骨架冻结——architecture.md:119）。 |
|
||||
| battle_refresh_flow 同形 | battle_refresh_flow 同批同形改造（can_refresh／execute 两入口的 oc/self 入参一并改依赖交付）。 |
|
||||
| 其余三处补公开面 | BreakpointStore 补公开读写方法；SlotStore 补路径公开读取口与迁移方法（或序列化职责归位，写卡定形态）；BattleFxHost 补两个公开累积方法；表容器补 resolver 公开挂载方法。 |
|
||||
| S13 成员数约束 | 段类新增依赖受 gdstyle 成员阈值约束，依赖可经束成员持有（先例＝BoardInstaller 引用束注入——architecture.md:124「构造＝引用束注入」）。 |
|
||||
| 验证方式 | 同种子逐项比对（主证，手法先例＝3.1+3.2 卡 battle_driver_drive_test 动作序列快照）＋battle_settlement 套件全绿＋五搬家方法各配真实入口断言＋core 五处跨对象私取 grep 恒零（扫描面非空前置＋零命中）；对照表按「非行为改动＋零行为变更证明」登记；禁变异类测试、禁撤销类取证。 |
|
||||
| 排序 | 实现排队在 reports/需求卡片-架构审查3.1+3.2整改批-2026-11-02.md 之后（combat_segment 同文件避让——该卡甲案删 attack_segments 分支 :59-70）。 |
|
||||
| 估时域 | 2–3 个工作日（写卡期精估）。 |
|
||||
|
||||
## 五、19 符号行为归属总表（2026-11-03 会话取证）
|
||||
|
||||
| 符号 | 处数 | 现在长在哪 | 修后归属 | 段类修后怎么拿到 |
|
||||
|---|---|---|---|---|
|
||||
| _facts | 24 | 编排器成员（BattleFacts 件引用，battle_orchestrator.gd:38） | BattleFacts 件（战斗事实域，架构在册） | 构造注入 BattleFacts 引用（六子对象之一） |
|
||||
| _enemy_system | 22 | 编排器成员（UnitContainer 引用，battle_orchestrator.gd:48） | UnitContainer（B2 单位容器） | 构造注入 UnitContainer 引用 |
|
||||
| _damage | 18 | 编排器成员（DamageController 引用，battle_orchestrator.gd:51） | DamageController（伤害单据管线） | 构造注入 DamageController 引用 |
|
||||
| _reward_economy | 5 | 编排器成员（RewardEconomy 引用，battle_orchestrator.gd:50） | RewardEconomy（B4 奖励经济） | 构造注入 RewardEconomy 引用 |
|
||||
| _status_effects | 2 | 编排器成员（StatusContainer 引用，battle_orchestrator.gd:49） | StatusContainer（B3 状态容器） | 构造注入 StatusContainer 引用 |
|
||||
| _fx_host | 1 | 编排器成员（BattleFxHost 引用，battle_orchestrator.gd:52） | BattleFxHost（效果宿主件） | 构造注入 BattleFxHost 引用 |
|
||||
| _rounds._grant_seg（链式） | 1 | battle_refresh_flow.gd:42 经编排器 _rounds 链式取授予段成员 | 段间引用——授予段引用直接交换 | 组装期直接交付授予段引用，不再穿编排器 |
|
||||
| _emit_row | 16 | 编排器私有方法（行发射基建，架构在册保留面） | 留宿主（保留面登记原样，零增零减） | 构造注入 Callable（七回调之一） |
|
||||
| _hits_of | 5 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _emit_composition_effects | 2 | 编排器私有方法 | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _battle_over | 2 | 编排器私有方法（battle_result 状态机写点域） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _feat_yield_adjust | 2 | 编排器私有方法 | 搬家→奖励域（奖励授予件） | 经注入的奖励授予件公开方法直调 |
|
||||
| _fatal | 1 | 编排器私有方法（行发射基建族） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _hero_atk | 1 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _harmful_variants | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 经注入的所属域件公开方法直调（具体形态写卡定） |
|
||||
| _harmful_adjacent | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 同上 |
|
||||
| _install_and_reset | 1 | 编排器私有薄壳（装板复位，架构在册轴丙） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _exit_distribution | 1 | 编排器私有方法（verdict 段经它触发轮推进） | 留宿主（现设计保留——七段结构冻结） | 构造注入 Callable |
|
||||
| _emit_settlement_snapshot | 1 | 编排器私有方法（结算快照发射） | 留宿主（呈现投影出口不变） | 构造注入 Callable |
|
||||
| **合计** | **107 处／105 行** | — | — | — |
|
||||
|
||||
取证注意：成员七符号逐项加总 73、编排器方法十二符号逐项加总 34，与三、构成行记写的 72＋35 有 ±1 出入（总处数 107 两路一致）；普查处 2 读数按写卡代理实核修正为 37 处／32 行（首版记 37 行——5 行各含 2 处访问）；godot-master 终审补查出普查漏项——SlotStore→SaveManagerCore 反向私取约 13 处（slot_store.gd:26-28/38-39/61-76/92-97/119/129/134/159-162，直用 _save._read_only/_reset_to_default/_data/_rename_overwrite/_peek_summary_at），与普查处 3（save_manager→SlotStore）为同一对类的相反方向，处置去向＝并入需求卡片 T3 存档面（卡片已同步折入）；行号与计数一律以写卡段复核为准。
|
||||
|
||||
## 六、架构锚点（architecture.md）
|
||||
|
||||
- :119——B1 battle_orchestrator 职责列：段序骨架（七段结构冻结）、B2/B3/B4 唯一调用方＝B1 域文件集。
|
||||
- :124——BoardInstaller 行：构造＝引用束注入先例（装板薄壳＋表数据、随机流、装板所需对象与出错回调一次性交付）。
|
||||
- :137——「战斗编排域拆件定稿」节头（拆件定稿全文入口）。
|
||||
- :139——轴甲两件：宿主保留面首登记与呈现投影「唯一出口不变」。
|
||||
- :141——轴丁两件：零豁免裁宿主保留面原文（总判据 3 的登记原样出处）。
|
||||
@@ -0,0 +1,291 @@
|
||||
# 需求卡片：架构审查 5.1 封装修复批（2026-11-03）
|
||||
|
||||
来源：待办清单「架构审查优化讨论——全库架构审计读数的逐项裁决与整改分批（2026-10-29 登记，来源=审计发现）」条目 5.1 部分（**唯一事实源**：reports/处置-架构审查5.1封装修复-2026-11-03.md——处置记录与本卡并行成文，本卡开工时该件尚未落盘；T1 首步核其已落盘且与本卡第 3 节逐条一致，冲突即 L3 停卡。设计闭合凭据＝2026-11-03 设计讨论会话裁决＋审计报告 §5.1＋architecture.md:119/:124/:137-146）。
|
||||
状态：已写卡（v1.1，2026-11-03 修订——godot-master 终审两中等发现与四低项折入＋SlotStore→SaveManagerCore 反向私取终审补查并入 T3；处置记录已落盘并与本卡第 3 节核过一致）。改动面：游戏代码（含随逻辑写/改的测试代码）。
|
||||
|
||||
## 1. 目标与完成定义
|
||||
|
||||
**这批做什么**：把 2026-11-03 设计讨论裁决的五处跨对象私有访问修复方案全部落码——封装收口、零行为变更：
|
||||
|
||||
| # | 处置对象 | 现状 | 终态 |
|
||||
|---|---|---|---|
|
||||
| 1 | settlement 七段 → 编排器 | 七文件对编排器 `oc._` 私取 105 行／107 处／19 符号（本卡第 3 节 grep 实核） | 段类构造收引用束（六子对象＋编排器公开协作件引用）＋七个编排器方法回调（Callable 交付）＋公开读数注入；段类对编排器引用归零 |
|
||||
| 2 | 编排器五个放错位置的方法 | `_hero_atk`/`_feat_yield_adjust`/`_harmful_variants`/`_harmful_adjacent`/`_hits_of` 留宿主、段类经宿主引用直调（architecture.md:145「现状形态」） | 各归领域宿主（伤害域/奖励域/地形棋盘域），宿主原方法删除禁留壳 |
|
||||
| 3 | adventure_runner → BreakpointStore | `_bp_store._` 直读写 37 处（32 行；adventure_runner.gd:37 注释自述「宿主读写经件」未落实） | BreakpointStore 公开方法面承接，宿主私取清零 |
|
||||
| 4 | save_manager ↔ SlotStore | save_manager→SlotStore：`slots._path` ×8＋`slots._migrate_legacy_save` 私有方法调用 ×1（save_manager.gd:51/66/69/105/111/118-119/285-286）；SlotStore→SaveManagerCore 反向私取约 13 处（slot_store.gd:26-28/38-39/61-76/92-97/119/129/134/159-162——直用 `_save._read_only`/`_reset_to_default`/`_data`/`_rename_overwrite`/`_peek_summary_at`，godot-master 终审补查） | save_manager 侧＝SlotStore 公开读投影 `active_path()`＋迁移方法公开化承接；SlotStore 侧＝SaveManagerCore 补公开方法面承接（T3 定死） |
|
||||
| 5 | grant_segment → BattleFxHost；config_db → 三表容器 | grant 直写 `fx_host._fx_new_resource_types`（:82/:84）与 `fx_host._fx_bonus_delta`（:169-170/:378-379）共 6 行；config_db.gd:157-159 三行装配直写三表 `_resolver` | BattleFxHost 两个公开累积方法；三表 schema 各加公开挂载方法 `bind_resolver` |
|
||||
|
||||
**什么状态算完**：五处的每一条改动都落码、都有第 8 节对照表配对的验收断言在当轮真实跑批中通过；主证＝同种子逐项比对（改前改后动作序列快照逐位同，T1 固化、全程保持绿）＋battle_settlement 套件全绿；结构性证据＝core 五处跨对象私取 grep 恒零（扫描面非空前置＋零命中）；代码域闸全绿（冒烟＋单元＋探针＋渲染/静态）；两份 reports/ 产出物（实现报告＋反哺点清单）写齐。
|
||||
|
||||
**排序义务**：本卡实现排队在 reports/需求卡片-架构审查3.1+3.2整改批-2026-11-02.md 之后（已编迭代 50，未开工）——combat_segment.gd 同文件避让（该卡甲案删 attack_segments 分支 :59-70，本卡第 3 节 combat 行号在其合回后漂移，T1 复核以 grep 符号锚定位）。
|
||||
|
||||
## 2. 设计事实源
|
||||
|
||||
- **处置记录（输入合同，逐条一致）**：`reports/处置-架构审查5.1封装修复-2026-11-03.md`——五处裁决方案、段类终态、出卡边界。本卡第 3 节现状实查与第 4/7 节签名设计是其机械承载；T1 复核两件一致（冲突＝上游缺陷，L3 停卡）。**口径注**：处置记录「公开读数一并改注入」＝形态族措辞，涵盖本卡第 4 节「调用参数现值交付」（round_index/battle_result 两变值标量构造期注入必陈旧——现值交付即注入的形态之一），T1 核对不按字面机械比对、按此口径核。
|
||||
- **审计背景**：`reports/审计-全库架构审查-2026-10-29.md` §5.1（settlement 五段类直读写编排器私有成员 20+ 处；行号已漂移，以本卡第 3 节实查为准）。
|
||||
- **架构登记**：`design/engineering/architecture/architecture.md`——:119（battle_orchestrator 保留面与 B1 域文件集）、:124（BoardInstaller 引用束注入先例——「构造＝引用束注入（……防 _init max-parameters 新键）」）、:137-146（战斗编排域拆件定稿：:140 轴丙、:141 编排器保留面登记、:143 跨件单向接线、:145 段类随动现状句）。
|
||||
|
||||
## 3. 现状事实（2026-11-03 worktree arch51-card 实查，基点 6261b36e；开工自行复核）
|
||||
|
||||
### 3.1 五处私取面盘点
|
||||
|
||||
**处 1·settlement 七段 → 编排器**（game/core/settlement/）：`grep -c 'oc\._'` 逐文件＝grant_segment 54／combat_segment 23／round_cycle 10／verdict_segment 9／battle_refresh_flow 5／aura_segment 2／decay_segment 2，合计 **105 行**；`grep -o "oc\._[a-z_]*" | wc -l`＝**107 处**（grant:131 与 grant:424 两行各含 2 处）；符号 19 种＝`_facts`×24、`_enemy_system`×22、`_damage`×18、`_emit_row`×16、`_reward_economy`×5、`_hits_of`×5、`_status_effects`×2、`_feat_yield_adjust`×2、`_emit_composition_effects`×2、`_battle_over`×2、`_rounds`×1（:42 `oc._rounds._grant_seg` 跨两层）、`_install_and_reset`×1、`_hero_atk`×1、`_harmful_variants`×1、`_harmful_adjacent`×1、`_fx_host`×1、`_fatal`×1、`_exit_distribution`×1、`_emit_settlement_snapshot`×1。另有对编排器**公开**成员访问：action_economy×11、db×7、minesweeper×6、round_index×3、fx_host()×3、battle_result×2、rng×2、attune_param_sum()×1（grant:280）、perfect_sweep_earned()×1（grant:284）。
|
||||
|
||||
**处 2·搬家五方法**（均在 battle_orchestrator.gd，仅段类与编排器自用）：
|
||||
|
||||
| 方法 | 现址 | 调用面 |
|
||||
|---|---|---|
|
||||
| `_hero_atk() -> int` | battle_orchestrator.gd:70-71（读 `_facts.encounter` hero_atk 键、缺省 db.combat.hero.atk——E4 派生读，禁快照成员） | combat_segment:55；编排器 spawn 消费点 :282；测试 roll_multiplier_test.gd:45-59 经真实链路覆盖（零直调） |
|
||||
| `_feat_yield_adjust(snap, positive, pos_m, neg_m)` | :452-461（读 `_reward_economy.polarity_row`） | grant_segment:99/:140 |
|
||||
| `_harmful_variants(vids)` | :466-473（读 db.combat.variation） | grant_segment:87；_harmful_adjacent 内部 :484 |
|
||||
| `_harmful_adjacent(cell)` | :478-485（读 minesweeper.current_board） | grant_segment:339 |
|
||||
| `_hits_of(hits, kind)` | :489-494（纯过滤） | grant_segment:110/:115/:138/:356、combat_segment:62（该行随 3.1+3.2 批甲案删除）、测试 adventure_feats_test.gd:671/:691/:727 |
|
||||
|
||||
**处 3·adventure_runner → BreakpointStore**：`grep -o "_bp_store\._[a-z_]*" | wc -l`＝**37 处**（32 行）＝`_resume_bp`×8、`_pending_next_level`×7、`_save_manager`×6、`_bp_read`×5、`_loadout_seeded`×5、`_last_level_payload`×4、`_last_treasure_cleared`×2。分布：adventure_runner.gd:107/:115/:157/:168/:180/:185/:189/:191/:201/:220/:235/:241/:300-302/:325-326/:376-378/:388/:412/:421/:430/:438/:456/:464/:467-468/:474-476。BreakpointStore（breakpoint_store.gd）类变量 15（:48-63——**贴顶禁再增**，architecture.md:113 同款登记）；公开方法现 5（snapshot/restore_ledger/restore_curio_state/apply_resume_params/restore_stop_bank_fragments）；`_bp_read`（:196-202）内部消费点 :160。测试面：feat_vouchers_test.gd 与 meta_progression_forge_test.gd 等 12 处 `orch._rounds._grant_seg._judge_seal(...)` 直调与 `orch._rounds.mines_hits` 7 处——`_grant_seg`/`mines_hits` 成员名与归属不变，零波及。
|
||||
|
||||
**处 4·save_manager ↔ SlotStore（双向）**：save_manager→SlotStore＝save_manager.gd:51（`slots._migrate_legacy_save(LEGACY_SAVE_PATH, slots.slot_path(1), ...)`）＋:66/:69/:105/:111/:118/:119/:285/:286（`slots._path` ×8）。SlotStore→SaveManagerCore 反向私取（godot-master 终审补查，2026-11-03 本会话 grep 精确实数）＝**21 处／21 行**：`_save._read_only`×8（:26/:38/:65/:69/:74/:87/:91/:96）、`_save._reset_to_default`×5（:28/:39/:70/:92/:119）、`_save._data`×4（:66/:75/:88/:97）、`_save._peek_summary_at`×2（:129/:134）、`_save._rename_overwrite`×2（:159/:162）。SlotStore（slot_store.gd）`_path` :9；`_migrate_legacy_save` :150-163（唯一外部调用方=save_manager:51；件内零调用）；公开读投影先例=`has_write_target()` :53-54（`_path != ""`）。SlotStore 类变量 4、公开方法 10。SaveManagerCore 私有被用面五成员＝`_read_only` :23、`_data` :24、`_reset_to_default` :279、`_peek_summary_at` :217（save_manager 件内调用方 :217 定义、slot_store 两处外部）、`_rename_overwrite` :317（件内调用方 :118/:286）；公开方法现 7、类变量 5。
|
||||
|
||||
**处 5·grant_segment → BattleFxHost＋config_db → 三表容器**：grant_segment.gd:82-84（`fx_host._fx_new_resource_types.has(ctype)` 读＋`[ctype] = true` 写——空串短路边界在 :82）与 :169-170、:378-379（`fx_host._fx_bonus_delta.has(axis)` 守卫＋`[axis] += delta`）。BattleFxHost 类变量 15（battle_fx_host.gd:23-37——**贴顶禁再增**，头注 :10-16 自封）、公开方法 16、两私 members 无成员外读者（grep 全库仅 grant 四处）。config_db.gd:157-159 三行 `combat.board_gen._resolver = _resolver`／`combat.enemy._resolver = _resolver`／`run.difficulty._resolver = _resolver`；三表 `_resolver` 声明＝board_gen_table.gd:113、enemy_table.gd:212、difficulty_table.gd:33（均无类型注解；消费点 :118/:217/:38）。表实例经 `load()` 出 .tres、无法带构造参，装配期注入是唯一时点（config_db.gd:131-159 `_assign_loaded`）。
|
||||
|
||||
### 3.2 写 T 卡依据的其他现状
|
||||
|
||||
- **段类现状形态**：五段构造＝grant/combat 三参（host/fx_host_ref/reward_grant_ref）、aura/decay/verdict 单参（host）；RoundCycle 三参直构（host/fx_host_ref/reward_grant_ref，round_cycle.gd:22-29）；battle_refresh_flow 全 static（can_refresh/execute 收 `oc` 入参，:15-43）。编排器 `_init`（battle_orchestrator.gd:211-237）建件序＝facts(218)→reward_economy(219)→damage(221)→fx_host(223)→reward_grant(225)→RoundCycle(237)；类变量 15（38→15 后贴顶）。
|
||||
- **编排器回调宿主方法现签名**：`_emit_row(head, ri, display, value, extra)` :750；`_fatal(msg)` :791；`_install_and_reset(during_round := false) -> bool` :392；`_battle_over(result)` :610；`_exit_distribution()` :575（内含 :593 `_rounds.roll_round_actions()`）；`_emit_settlement_snapshot(verdict)` :534；`_emit_composition_effects(side, ri)` :524；公开读投影先例＝`_attune_safe_seen_read` :139（RewardGrant attune_safe_seen_cb）、`_pool_effective` :513（pool_effective_cb）——**读投影 Callable 交付是既有形态**（architecture.md:121）。
|
||||
- **编排器三调用点**：`can_refresh()`/`player_request_refresh()` 单行转发（:598-607）；`_on_round_end` → `_rounds.settle_if_due()`（:445-447）；begin_battle → `_rounds.roll_round_actions()`（:262）。facade 公开签名零参（presentation 路径）。
|
||||
- **测试连带面**：settle_segments_test.gd:20-24 五段 `new(oc, ...)` 直构断言、:28-34 宿主回指断言（`oc._rounds._grant_seg.oc == oc` 等 6 条）——随束形态换代改写；adventure_feats_test.gd:671/:691/:727 `orch._hits_of` 直调——随搬家改指。其余 orch._ 访问（`_facts`×6、`_rounds`×13、`_emit_row`×2）所涉宿主成员全保留，零波及。round_flow_skill_pool_test／seal_polarity_test／refresh_feats_test／effect_port_test 等走公开入口，零改写。
|
||||
- **gdstyle 基线**：tools/gdstyle_baseline.txt 仅 5 键（adventure_runner 类变量 23、level_runner 两键、board_view 两键）——本卡触件均无登记值，T1 现场读数即对账基线。S13 默认阈值：公开方法 ≤20／类变量 ≤15／单函数分支 ≤8／返回 ≤6。
|
||||
- **静态闸**：S7_B1_SET 与 S8_FILES（game/tests/static_scan.sh:317/:361）已含七段文件——本批零闸件改动。S9 R1A 判据＝`var x: Dictionary|Array` 裸注解（tools/audit_type_hints.py:22）——新增成员一律具体类名或参数化泛型。
|
||||
- **能力清单**：game/tests/README.md 在役（本卡判据引用行＝:59/:63/:86/:89/:92/:124/:174，能力名见第 8 节对照表）。
|
||||
|
||||
## 4. 设计契约（违反即返工红线）
|
||||
|
||||
- 🔴 **逐条一致**：本卡一切内容与处置记录逐条一致；实现段发现卡面与处置记录冲突＝上游缺陷，停卡退回写卡段（L3）。
|
||||
- 🔴 **零行为变更**：同种子同输入下动作序列、明细行流、结算快照、信号顺序逐位一致（T1 golden 主证全程保持绿）；RNG 消费序零漂移（behavior_roll/encounter/fx_reveal/gp_drop 四封闭流的流名、开流时点、取号序逐字）；明细行协议词表零触碰。
|
||||
- 🔴 **段类对编排器引用归零**：七个 settlement 文件（grant/combat/round_cycle/verdict/battle_refresh_flow/aura/decay）全文 `\boc\b` 标识符零命中（含头注与行内注释——随改写一并清除）。
|
||||
- 🔴 **编排器保留面零增减**：architecture.md:141 登记原样——战斗状态机与生命周期、行发射基建（_emit_row/_assert_row_source/_fatal）、呈现投影、刷新面、nest_preview_count。七回调的宿主方法体零改动（Callback 交付不搬家：_emit_row/_fatal/_install_and_reset/_battle_over/_exit_distribution/_emit_settlement_snapshot/_emit_composition_effects 全部留宿主）。
|
||||
- 🔴 **搬家五方法禁留壳**：宿主原方法删除，禁兼容别名、禁转发壳、禁注释化残段（第 13 节全款适用）。
|
||||
- 🔴 **束形态（引用束注入，BoardInstaller 先例 architecture.md:124）**：
|
||||
- **编排器束**（`_init` 组装一个 `Dictionary`，封闭 20 键）：`facts`/`units`/`damage`/`status_effects`/`reward_economy`/`reward_grant`/`fx_host`/`minesweeper`/`db`/`action_economy`/`rng` ＋ `emit_row_cb`/`fatal_cb`/`install_cb`/`battle_over_cb`/`exit_distribution_cb`/`emit_snapshot_cb`/`emit_composition_cb` ＋ `attune_param_sum_cb`/`perfect_sweep_cb`。前 11 键＝六子对象（BattleFacts／UnitContainer／DamageController／RewardEconomy／StatusContainer／BattleFxHost）＋四个既有公开协作件引用（minesweeper/rng/reward_grant——段类现役消费面所需）＋两公开读数引用（db/action_economy）；后 9 键＝七个编排器方法回调（Callable 绑宿主对应方法）＋两个公开读投影回调（`attune_param_sum(kind) -> int`／`perfect_sweep_earned() -> bool`——RewardGrant attune_safe_seen_cb/pool_effective_cb 同款先例）。
|
||||
- **接收方各取所需**：RoundCycle 收全束并分发五段（各段构造收同一束）；RoundCycle 解包自用七键（facts/units/fx_host/db/action_economy/rng/emit_row_cb）；各段断言各自必需键在束（BattleFxHost :41-42 assert 缺键先例）。必需键分配＝grant 12（facts/units/damage/reward_economy/fx_host/minesweeper/db/action_economy/reward_grant/emit_row_cb/attune_param_sum_cb/perfect_sweep_cb）、combat 10（facts/units/damage/status_effects/fx_host/minesweeper/db/emit_row_cb/fatal_cb/reward_grant）、aura 1（emit_composition_cb）、decay 2（status_effects/emit_row_cb）、verdict 5（units/emit_row_cb/emit_snapshot_cb/battle_over_cb/exit_distribution_cb）。
|
||||
- **换图刷新流程件同批同形**：BattleRefreshFlow 由 static（oc 入参）改实例——`_init(bundle: Dictionary)` 收 8 键（facts/db/action_economy/fx_host/reward_economy/minesweeper/install_cb/grant_seg）；can_refresh/execute 两入口的 `oc` 入参改依赖交付，编排器两公开方法单行转发形态不变（architecture.md:123）。grant_seg 键＝段间引用（RoundCycle 构造五段后写入副本束再建本件——授予段引用直接交换图流程件，`oc._rounds._grant_seg` 跨两层私取随之消灭）。
|
||||
- **公开读数注入**：db/action_economy＝引用注入（构造期稳定）；round_index/battle_result＝**调用参数现值交付**（两标量每拍变值，构造期值注入必陈旧）——`settle_if_due(battle_result: String, ri: int)`、`roll_round_actions(ri: int)`、`can_refresh(battle_result: String)`、`execute(battle_result: String, round_index: int)`，编排器调用点传现值（:262/:447/:593/:598-607 四处），facade 零参签名不变。
|
||||
- 🔴 **跨件单向接线**：段类↔编排器只经束注入（引用＋Callable），禁双向强引用；注入 Callable 亦属接线面、禁为省参数改持对象引用（architecture.md:143 同款；段类/编排器均 RefCounted，环引用随每战新建泄漏）。
|
||||
- 🔴 **读投影消费形态**：Callable.call 返回 Variant，消费一律 `int(...)`/`bool(...)` 包裹（battle_fx_host.gd:128 facts_cb.call 消费先例）。
|
||||
- 🔴 **S9 参数化形态**：本批全部新增成员声明与函数注解——具体类名（`var facts: BattleFacts`）或参数化泛型（`Dictionary[Variant, Variant]`）；裸 `Dictionary`/`Array` var 注解＝S9 R1A 红。迁移函数（五方法）注解逐字保持原形（原签名已过 S9）。
|
||||
- 🔴 **fail-fast**：束缺键 assert 致命；零软回退。Core 零 UI 依赖不破（全套件 `--headless --script` 可跑通）。
|
||||
- 🔴 **测试纪律**：禁变异类测试、禁撤销类取证；禁删断言/放宽阈值换绿（第 8 节申报清单之外零删改）。
|
||||
|
||||
## 5. 范围边界
|
||||
|
||||
**收件**＝第 1 节表五行全部（settlement 七段解耦＋搬家五方法＋breakpoint_store 公开面＋存档双向公开面〔save_manager↔SlotStore 两方向〕＋battle_fx_host 两累积方法＋三 schema 挂载方法，及各自的调用点改址与测试适配）。
|
||||
|
||||
**不收件**（去向已指认）：
|
||||
- presentation 层约 227 行私取面——**另开设计讨论**（本卡裁决范围外；去向＝待办清单本条目实况，非本批）。
|
||||
- sim／probe／tests 的测量面直构惯例与测试受控例外——零清扫（orch._facts/orch._rounds/orch._emit_row 等测试直连维持现状）。
|
||||
- 段类→协作件残余私取一处：grant_segment.gd:197 `oc._damage._emit_hero_damage_taken(...)` 随本批改经 `damage.emit_hero_damage_taken(...)`（DamageController 该方法去下划线公开化，见 T2）——除此之外段类对 damage/fx_host/reward_grant 公开成员的直读（counters_ctx/engine/facts_inject/defer）零触碰。
|
||||
- 职责归属零改动（除搬家五方法——已裁的五处归位）；编排器七回调宿主方法体零改动；架构七段结构零改动（五段段序、SettlementTable.segment_order、RoundCycle/BattleRefreshFlow/五段段类的文件与职责登记全部在案不动）。
|
||||
- 闸件（static_scan.sh）零改动；MC/模拟零跑（无数值改动）；`tools/gdstyle_baseline.txt` 零改动（本批无键恶化，见第 14 节）。
|
||||
|
||||
## 6. 关联文档同步面
|
||||
|
||||
实现批禁写 `design/` 整个目录、两份根流程清单与 `game/tests/README.md`；下表每条的落文义务全部进 `reports/iter<N>-反哺点-<日期>.md`（N=编排段定），由用户裁决后归文档批落文：
|
||||
|
||||
| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务（反哺点清单逐条承载） |
|
||||
|---|---|---|
|
||||
| design/engineering/architecture/architecture.md | :125 RoundCycle 行「三参直构（host/fx_host_ref/reward_grant_ref——五段构造透传不落成员）」→ 束注入＋持有 BattleRefreshFlow＋公开方法 3→4＋类变量 8→15（贴顶）；:123 BattleRefreshFlow 行 static 两入口收 oc → 实例束注入、宿主改经 RoundCycle 交接 grant_seg、类变量 0→8；:127 settlement/ 五段段类行构造形态句 → 束注入、对编排器零引用；:122 damage_controller 行实测类变量 12→13＋公开面净增（hero_atk/hits_of/emit_hero_damage_taken）；:121 RewardGrant 行 +feat_yield_adjust；:120 BattleFxHost 行 +两累积方法（类变量 15 不变）；核心层表 A2 minesweeper_rules 行公开面 18→20（贴顶）；核心层表 breakpoint_store 行公开方法面 5→18；核心层表 save_manager 行公开面 7→14（+5 承接方法＋peek_summary_at/rename_overwrite 两更名公开化）＋slot_store 行「双向公开面」（21 处反向私取清零） | 反哺点清单逐条列行号与改后登记内容——**机械面文档禁直改** |
|
||||
| design/gdd/systems/战斗循环/战斗结算.md | 无陈述变化（明细流水词表、五段段序、段边界全部零触碰——零行为变更批） | 反哺点清单写「零反哺」确认行 |
|
||||
| 术语表 | 无新术语（引用束注入／读投影／公开方法面均仓库现行词） | 确认行「零新增术语」 |
|
||||
|
||||
（机检口径：本表同步义务格无一条写「随批」。）
|
||||
|
||||
## 7. 任务卡 T1..T5
|
||||
|
||||
### 卡前·文件结构图
|
||||
|
||||
全部行为面＝非行为改动（零行为变更批），行标【非行为】＋对照表 R 行号；测试件全部为随逻辑写/改的测试代码。一起改的按职责放一起——段类七文件同卡（T2）、存档断点两对同卡（T3）。
|
||||
|
||||
```
|
||||
core 层（编排域）
|
||||
game/core/battle_orchestrator.gd 【非行为 R1/R2】_init 束组装（20 键）；:70-71/:452-461/:466-473/:478-485/:489-494 五方法删除；:282 hero_atk 改指 _damage.hero_atk()；:262/:447/:593 三调用点传参；:598-607 facade 改经 _rounds.refresh_flow()
|
||||
game/core/settlement/round_cycle.gd 【非行为 R1】束注入（15 成员贴顶）＋持有/构建 BattleRefreshFlow＋settle_if_due/roll_round_actions 签名扩展＋refresh_flow() 读出口
|
||||
game/core/settlement/grant_segment.gd 【非行为 R1/R2/R3】束解包 12 成员＋54 处改址＋:82-84/:169-170/:378-379 改公开累积方法＋头注改写
|
||||
game/core/settlement/combat_segment.gd 【非行为 R1/R2】束解包 10 成员＋23 处改址＋hero_atk 改指
|
||||
game/core/settlement/aura_segment.gd 【非行为 R1】单回调成员＋头注改写
|
||||
game/core/settlement/decay_segment.gd 【非行为 R1】两成员＋改址
|
||||
game/core/settlement/verdict_segment.gd 【非行为 R1】束解包 5 成员＋四回调改址
|
||||
game/core/settlement/battle_refresh_flow.gd 【非行为 R1】static 改实例＋束注入 8 成员＋grant_seg 段间引用
|
||||
game/core/damage_controller.gd 【非行为 R2】+facts 成员（12→13）＋hero_atk()＋static hits_of()＋_emit_hero_damage_taken 公开化（:449/:561 内部调用点随改）
|
||||
game/core/reward_grant.gd 【非行为 R2】+feat_yield_adjust()
|
||||
game/core/minesweeper_rules.gd 【非行为 R2】+harmful_variants()/harmful_adjacent()（公开 18→20 贴顶）
|
||||
game/core/battle_fx_host.gd 【非行为 R3】+mark_new_resource_type()/+add_bonus_delta()（成员 15 不变）
|
||||
core 层（冒险/存档域）
|
||||
game/core/breakpoint_store.gd 【非行为 R4】+13 公开读写方法面（成员 15 不变；_bp_read 更名 bp_read 公开化——:160 内部调用点随改）
|
||||
game/core/adventure_runner.gd 【非行为 R4】37 处改址（:107..:476 逐处）
|
||||
game/core/save_manager.gd 【非行为 R5】+5 公开方法（set_read_only/read_only/reset_to_default/data_snapshot/restore_data）＋_peek_summary_at/_rename_overwrite 更名公开化（件内调用点随改）；:51/:66/:69/:105/:111/:118-119/:285-286 九行改址
|
||||
game/core/slot_store.gd 【非行为 R5】+active_path()；_migrate_legacy_save 更名 migrate_legacy_save 公开化；反向私取 21 处改址（_save._ → save_manager 公开面）
|
||||
game/core/config_db.gd 【非行为 R6】:157-159 三行改经 bind_resolver()
|
||||
game/data/schemas/board_gen_table.gd 【非行为 R6】+bind_resolver(resolver: ConfigDbResolver)
|
||||
game/data/schemas/enemy_table.gd 【非行为 R6】同上
|
||||
game/data/schemas/difficulty_table.gd 【非行为 R6】同上
|
||||
测试件（随逻辑写/改）
|
||||
tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd 【非行为 R1·新增】同种子逐项 golden 对拍（主证）
|
||||
tests/unit/core/encapsulation_sweep_test.gd 【非行为 R1–R6·新增】五处结构性零命中扫描（非空前置＋正锚）
|
||||
tests/unit/core/settle_segments_test.gd 【非行为 R1】:20-34 束构造与同一性断言适配
|
||||
tests/unit/core/adventure_feats_test.gd 【非行为 R2】:671/:691/:727 hits_of 改指 DamageController.hits_of
|
||||
tests/run_all.gd 【非行为】manifest +2 行（snapshot／sweep）
|
||||
文档件
|
||||
game/tests/README.md 写卡段判断＝零编辑（第 8 节能力行判断依据）——实现批禁写，批末只核对表上能力名与对照表引用一致
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**T1 基线固化与主证落盘**（估时 0.25 工作日；区间 0.25–0.5）
|
||||
取用：无（本卡起点）。产出：golden 基线（改前读数冻结）＋S13 对账基线＋grep 底账；本卡实现排序核对。
|
||||
|
||||
- [ ] 核对实现排序在案：3.1+3.2 卡（迭代 50）未合回则本批不开工（第 1 节排序义务）；combat_segment.gd 现址复核（甲案 :59-70 分支已删则以 grep 符号锚定位，行号漂移即记录进实现报告，禁改判据）
|
||||
- [ ] 核对处置记录 `reports/处置-架构审查5.1封装修复-2026-11-03.md` 已落盘且与本卡第 3 节逐条一致（冲突＝L3 停卡）
|
||||
- [ ] 新增 tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd（extends SceneTree＋Kit.check 主通道，全类型标注）：手搭驱动＝`ConfigDbScript.new()`＋`load_tables("res://data/tables", true)`→`RngServiceCore` set_master_seed(4242)→`BattleOrchestrator.new(db, rng)`；捕获面＝`step_row` 全量行数组＋`settlement_snapshot` 全量载荷数组＋`battle_finished` 载荷＋收束时 `presentation_snapshot()` 关键键（round/battle_result/hero.hp/enemies.size()）。驱动序（逐字定死）：①`begin_battle({"level_index": 1, "node_depth": 1, "hero_hp": int(db.combat.hero.max_hp), "voucher_rap": 20})`；②轮 1：`AutoPlayer.choose_dig(minesweeper)` 返 `{dig_cell, hero_cell}` 非空则 `settle_batch([{"action": "move", "cell": hero_cell}])`→`settle_batch([{"action": "dig", "cell": dig_cell}])`→对首个未揭示且与主角相邻的格 c `settle_batch([{"action": "seal_place", "cell": c}])`（封印已揭示格在棋盘面必拒〔target_revealed〕——封印子链 _judge_seal_hit/_seal_hit_effects/_judge_seal_miss 及封印匠/示警烟火/完美保险扩展行必须真实进入 golden 行流；「封已揭示安全格」的拒绝路径由 seal_polarity_test 既有回归兜底，不入 golden 主证）→`settle_batch([{"action": "stop"}])`；③轮 1 结算后 `player_request_refresh()`（voucher_rap=20 保证 RAP 抵折后价——覆盖换图刷新链：can_refresh/execute/install_cb/grant_seg 成功事实）；④轮 2：choose_dig 一挖一停；⑤轮 3：径直 `settle_batch([{"action": "stop"}])`。断言＝捕获序列与 `const GOLDEN`（行字典逐位含 type/source_class/origin_cell/round_index/display_name/value/其余载荷键）逐位相等〔封装5.1 V1〕
|
||||
- [ ] **改前取数**：本步骤在任何生产码改动之前执行——先写测试与空跑转储通道（GOLDEN 为空时打印捕获序列 JSON 后按预期码退出），在未改树上跑出 golden、填入 GOLDEN 常量、复跑全绿；golden 即改前基线读数（不构成验收，验收＝改后全程保持绿）
|
||||
- [ ] S13 对账基线：对本卡全部 core/data 存量触件（第 14 节清单 15 件）现场跑 gdstyle 记读数为基线（既有登记仅 adventure_runner 类变量 23 一件照登对账）；跑 `python tools/run_smoke.py` 冒烟基线全绿读数落实现报告
|
||||
- [ ] grep 底账五件落实现报告：`oc\._`（settlement 七文件）、`_bp_store\._`（adventure_runner）、`slots\._`（save_manager）、`_save\._`（slot_store——反向私取 21 处）、`_fx_new_resource_types|_fx_bonus_delta`（grant）与 `\._resolver =`（config_db）——命中行号清单＝T5 sweep 的改前底账
|
||||
|
||||
**T2 settlement 七段解耦＋搬家五方法**（估时 1.25 工作日；区间 1–1.5）
|
||||
取用：T1 golden 基线。产出：处 1＋处 2 清零——段类对编排器引用归零、五方法归位。
|
||||
|
||||
- [ ] battle_orchestrator.gd `_init`（:211-237）：RoundCycle 构造改 `RoundCycle.new(束)`——束 20 键逐字（第 4 节束形态表；Callable 键绑自对应方法：`"emit_row_cb": _emit_row`、`"fatal_cb": _fatal`、`"install_cb": _install_and_reset`、`"battle_over_cb": _battle_over`、`"exit_distribution_cb": _exit_distribution`、`"emit_snapshot_cb": _emit_settlement_snapshot`、`"emit_composition_cb": _emit_composition_effects`、`"attune_param_sum_cb": attune_param_sum`、`"perfect_sweep_cb": perfect_sweep_earned`）
|
||||
- [ ] 搬家五方法落位（宿主体逐字迁移、注解逐字保持）：
|
||||
- damage_controller.gd：`_init` 加第五参 `facts_ref`（成员 `var facts: BattleFacts`，:49 构造体加行）；新增 `func hero_atk() -> int`（体=battle_orchestrator.gd:70-71 逐字，`_facts`→`facts`）；新增 `static func hits_of(hits: Array, kind: String) -> Array`（体=:489-494 逐字）；`_emit_hero_damage_taken` 更名 `emit_hero_damage_taken` 公开化（体逐字；内部调用点 :449/:561 随改）
|
||||
- reward_grant.gd：新增 `func feat_yield_adjust(snap: Dictionary, positive: bool, pos_m: int, neg_m: int) -> Dictionary`（体=:452-461 逐字——reward_economy 为本件既有成员 :22）
|
||||
- minesweeper_rules.gd：新增 `func harmful_variants(vids: Array) -> Array` 与 `func harmful_adjacent(cell: Vector2i) -> Array`（体=:466-473/:478-485 逐字——db 为本件构造参、current_board() 自有；**:484 内部自呼 `_harmful_variants(board.variant_ids(n))` 随更名改 `harmful_variants(board.variant_ids(n))`，禁留旧名**）
|
||||
- battle_orchestrator.gd：五方法整段删除（:70-71/:452-461/:466-473/:478-485/:489-494）；:282 `hero_atk_override: _hero_atk()` → `_damage.hero_atk()`
|
||||
- [ ] round_cycle.gd 重写：`_init(bundle: Dictionary)`——断言 7 必需键（facts/units/fx_host/db/action_economy/rng/emit_row_cb）后解包为同名成员；五段构造改 `XxxSegment.new(bundle)`；复制束写入 `"grant_seg": _grant_seg` 后构建 `BattleRefreshFlow.new(束副本)`；`settle_if_due(battle_result: String, ri: int)`（:35→参数、:40 删、段驱动用 ri）；`roll_round_actions(ri: int)`（:67/:80 用 ri）；新增 `func refresh_flow() -> BattleRefreshFlow`；全文 `oc.` 改址（映射表＝`oc._facts`→`facts`、`oc._enemy_system`→`units`、`oc._emit_row`→`emit_row_cb.call`、`oc._fx_host`→`fx_host`、`oc.db`→`db`、`oc.action_economy`→`action_economy`、`oc.rng`→`rng`）；头注「耦合边界」段改写（束注入＋签名扩展＋随编排器每战新建同灭语义不变）
|
||||
- [ ] grant_segment.gd 重写：`_init(bundle: Dictionary)` 断言 12 键解包 12 成员（第 4 节分配表）；54 处改址——除上表映射外加：`oc._reward_economy`→`reward_economy`、`oc.minesweeper`→`minesweeper`、`oc._hero_atk()`→（无此调用）、`oc._feat_yield_adjust(...)`→`reward_grant.feat_yield_adjust(...)`（:99/:140）、`oc._harmful_variants`→`minesweeper.harmful_variants`（:87）、`oc._harmful_adjacent`→`minesweeper.harmful_adjacent`（:339）、`oc._hits_of`→`DamageController.hits_of`（:110/:115/:138/:356）、`oc.attune_param_sum("rap_transfer_mult")`→`int(attune_param_sum_cb.call("rap_transfer_mult"))`（:280）、`oc.perfect_sweep_earned()`→`bool(perfect_sweep_cb.call())`（:284）、`oc._damage._emit_hero_damage_taken(...)`→`damage.emit_hero_damage_taken(...)`（:197）；:82-84 改 `var is_new_type := fx_host.mark_new_resource_type(ctype)`；:169-170 与 :378-379 改 `fx_host.add_bonus_delta(String(h.get("axis", "")), int(h.get("delta", 0)))`；头注改写
|
||||
- [ ] battle_fx_host.gd 新增两公开累积方法（成员零增，头注类变量封闭面句不动）：`func mark_new_resource_type(ctype: String) -> bool`——`if ctype == "": return false`；`if _fx_new_resource_types.has(ctype): return false`；置位后 `return true`（空串短路边界＝原 :82 形态逐位等价）。`func add_bonus_delta(axis: String, delta: int) -> void`——`if _fx_bonus_delta.has(axis): _fx_bonus_delta[axis] += delta`
|
||||
- [ ] combat_segment.gd 重写：`_init(bundle)` 断言 10 键解包；23 处改址（映射同上＋`oc._fatal`→`fatal_cb.call`、`oc._status_effects`→`status_effects`、`oc._hero_atk()`→`damage.hero_atk()`）；`oc._hits_of` 行随 3.1+3.2 批已删——复核以 grep 为准；头注改写
|
||||
- [ ] aura_segment.gd（成员 `var emit_composition_cb: Callable`，:15-16 改 `emit_composition_cb.call("hero", ri)`/`("enemy", ri)`）、decay_segment.gd（成员 status_effects＋emit_row_cb）、verdict_segment.gd（成员 units＋四回调，:18/:20 `units.hero_unit()`/`units.query_alive("enemy")`、:22 `emit_snapshot_cb.call(verdict)`、:25/:29 `battle_over_cb.call(...)`、:32 `exit_distribution_cb.call()`）三件重写＋头注改写
|
||||
- [ ] battle_refresh_flow.gd 重写：去 static——`_init(bundle: Dictionary)` 断言 8 键（facts/db/action_economy/fx_host/reward_economy/minesweeper/install_cb/grant_seg）解包；`_effective_refresh_cost()` 无参实例方法（:15-20 体逐字，`oc.db`→`db`、`oc.fx_host().fx_emit`→`fx_host.fx_emit`）；`can_refresh(battle_result: String) -> bool`（:24-28 体逐字，`oc.battle_result`→参数、`oc._facts.refresh_used`→`facts.refresh_used`）；`execute(battle_result: String, round_index: int) -> bool`（:32-43 体逐字——`oc._facts.refresh_used += 1`→`facts.refresh_used += 1`、`oc._reward_economy.retire_mapping()`→`reward_economy.retire_mapping()`、`oc.minesweeper.retire_board(true)`→`minesweeper.retire_board(true)`、`oc._install_and_reset(true)`→`bool(install_cb.call(true))`、`oc._rounds._grant_seg.apply_board_refreshed(oc.round_index)`→`grant_seg.apply_board_refreshed(round_index)`）；头注「调用路径」句改写（编排器单行转发形态不变）
|
||||
- [ ] battle_orchestrator.gd 收口：:598-599 `return BattleRefreshFlow.can_refresh(self)`→`return _rounds.refresh_flow().can_refresh(battle_result)`；:606-607 →`return _rounds.refresh_flow().execute(battle_result, round_index)`；:262 `roll_round_actions()`→`roll_round_actions(round_index)`；:447 `settle_if_due()`→`settle_if_due(battle_result, round_index)`；:593 →`roll_round_actions(round_index)`；`can_refresh`/`player_request_refresh`/`_on_round_end`/`begin_battle`/`_exit_distribution` 五处体注释同步＋:280-281 注释（「`_hero_atk` 派生读=受理后不变量」句引用将删除的方法名）随 :282 改指一并改写
|
||||
- [ ] 测试适配：settle_segments_test.gd :20-24 五段直构断言改束形态（以真实编排器协作件组装束逐段 `new(bundle)` 成功断言）；:28-34 宿主回指断言 6 条改同一性断言（`oc._rounds._grant_seg.facts == oc._facts`、`oc._rounds._combat_seg.fx_host == oc.fx_host()` 等——同一性强度对应回指，削减弱化申报 1）；adventure_feats_test.gd :671/:691/:727 `orch._hits_of(...)` → `DamageController.hits_of(...)`（削减弱化申报 2）
|
||||
- [ ] 孤立验证新增段 → 出红只跑红件最小单元 → 并入全套（回归措辞：里程碑卡出口跑一次全套闸；卡内修复只做出红最小单元的最窄确认）；本卡出口＝golden 快照绿＋battle_settlement 套件全绿＋冒烟全绿
|
||||
|
||||
**T3 断点与存档公开面**（估时 0.625 工作日；区间 0.5–0.75）
|
||||
取用：T1 底账。产出：处 3＋处 4 双向清零。
|
||||
|
||||
- [ ] breakpoint_store.gd 新增公开方法面（13 个，成员零增——类变量 15 贴顶）：`func bind_save_manager(sm: SaveManagerCore) -> void`、`func save_manager() -> Variant`（读投影，可 null）、`func set_pending_next_level(v: bool) -> void`／`func pending_next_level() -> bool`、`func set_loadout_seeded(v: bool) -> void`／`func loadout_seeded() -> bool`、`func set_resume_bp(bp: Dictionary) -> void`／`func clear_resume_bp() -> void`／`func resume_bp() -> Dictionary`（返引用零拷贝——宿主读侧只读）、`func bp_read(key: String, bp: Dictionary, fallback: Variant = null) -> Variant`（=_bp_read 更名公开化，:160 内部调用点随改）、`func set_last_level_payload(payload: Dictionary) -> void`／`func last_level_payload() -> Dictionary`、`func set_last_treasure_cleared(v: int) -> void`／`func last_treasure_cleared() -> int`（方法体一律一行转发自有成员，零逻辑增量）
|
||||
- [ ] adventure_runner.gd 37 处改址（逐处）：:107/:157/:180/:185/:241/:438 → `set_pending_next_level(...)`；:235 → `pending_next_level()`；:115/:191/:201 → `set_loadout_seeded(false)`；:300-301 → `loadout_seeded()`/`set_loadout_seeded(true)`；:189 → `set_resume_bp(bp.duplicate(true))`；:388 → `clear_resume_bp()`；:302/:376/:377/:378 → `resume_bp()`（读侧零拷贝语义不变）；:168/:302/:377/:378/:412 `_bp_read` → `bp_read`；:220 → `bind_save_manager(sm)`；:325-326 → `var sm = _bp_store.save_manager()` 后 `if sm != null: first = not sm.meta_state.career_state()...`；:421 → `set_last_level_payload(payload.duplicate(true))`；:464/:467-468 → `last_level_payload()`；:430 → `set_last_treasure_cleared(...)`；:456 → `last_treasure_cleared()`；:474-476 → `var sm = _bp_store.save_manager()` 后 `sm.clear_breakpoint()`/`sm.write_to_disk()`；:37 头注自述句核改（「宿主读写经件」落实后注释与实态一致）
|
||||
- [ ] slot_store.gd：新增 `func active_path() -> String: return _path`（读投影——has_write_target :53 同族）；`_migrate_legacy_save` 更名 `migrate_legacy_save` 公开化（:150 体逐字；禁留旧名壳）；**反向私取 21 处改址**（第 3.1 节处 4 清单）：`_save._read_only` 写 4 处（:26/:38/:69/:91）→ `_save.set_read_only(false)`、读 2 处（:65/:87）→ `var prev_ro: bool = _save.read_only()`、恢复写 2 处（:74/:96）→ `_save.set_read_only(prev_ro)`；`_save._reset_to_default` ×5（:28/:39/:70/:92/:119）→ `_save.reset_to_default()`；`_save._data` 读 2 处（:66/:88）→ `var prev_data = _save.data_snapshot()`、恢复写 2 处（:75/:97）→ `_save.restore_data(prev_data)`（引用零拷贝语义不变——snapshot 返 `_data` 本引用）；`_save._peek_summary_at` ×2（:129/:134）→ `_save.peek_summary_at(...)`；`_save._rename_overwrite` ×2（:159/:162）→ `_save.rename_overwrite(...)`
|
||||
- [ ] save_manager.gd 新增公开方法面承接 SlotStore 反向私取（类变量零增；公开 7→14）：`func set_read_only(v: bool) -> void`／`func read_only() -> bool`（体一行转发 `_read_only`）、`func reset_to_default() -> void`（体=:279 逐字公开化——件内调用点零改，同名）；`func data_snapshot() -> Dictionary[String, Variant]: return _data`／`func restore_data(data: Dictionary[String, Variant]) -> void: _data = data`（零拷贝——还原引用）；`_peek_summary_at` 更名 `peek_summary_at` 公开化（:217 体逐字；**件内调用点复核**——slot_store :129/:134 为外部消费，件内若另有调用随改）；`_rename_overwrite` 更名 `rename_overwrite` 公开化（:317 体逐字；件内调用点 :118/:286 随改）
|
||||
- [ ] save_manager.gd 九行改址：:51 → `slots.migrate_legacy_save(...)`；:66/:69/:105/:111/:118/:119/:285/:286 `slots._path` → `slots.active_path()`（:118-119 两处同名调用间 `_path` 无变更窗口——单线程同步段，逐位等价）
|
||||
|
||||
**T4 效果宿主累积面与配置挂载面**（估时 0.375 工作日；区间 0.25–0.5）
|
||||
取用：T2（grant 已改指）。产出：处 5 清零（本卡 T2 已落 grant 改址与 battle_fx_host 两方法——本卡复核其孤立验证读数）。
|
||||
|
||||
- [ ] 复核 T2 步骤中 battle_fx_host.gd 两方法与 grant_segment.gd 四处改址已落（T2 内联实装——本卡不重复列）；孤立验证：grant_segment 相关套件（seal_polarity/round_flow）出红最小单元
|
||||
- [ ] board_gen_table.gd / enemy_table.gd / difficulty_table.gd 各新增 `func bind_resolver(resolver: ConfigDbResolver) -> void`（体一行 `_resolver = resolver`；三件注解同型）
|
||||
- [ ] config_db.gd:157-159 三行改 `combat.board_gen.bind_resolver(_resolver)` / `combat.enemy.bind_resolver(_resolver)` / `run.difficulty.bind_resolver(_resolver)`（_assign_loaded 装配序零变化）
|
||||
- [ ] **三 schema 解析冒烟（类型环验证义务）**：bind_resolver 引入 schema→ConfigDbResolver 参数类型注解，与 resolver 既有反向引用（config_db_resolver.gd:41/:61 引 EnemyTable.ROW_KINDS/band_of——:3-8 头注「类型环断根」先例）构成类型引用环——孤立验证必含 config_db_resolver_test 全套当轮真实跑（三 schema 经 `load()` 实例化＋resolver 注入＋resolve_row/resolve_rowset/resolve_modifiers 真实解析，类型环若引入解析失败当轮即炸）；出红即 L3 停卡（禁改走 type-hint: ignore 通道——保 schema 类型注解完整）
|
||||
|
||||
**T5 结构性扫描与批收口**（估时 0.375 工作日；区间 0.25–0.5）
|
||||
取用：全部前卡。产出：五处结构性恒零证据＋批收口两件。
|
||||
|
||||
- [ ] 新增 tests/unit/core/encapsulation_sweep_test.gd（extends SceneTree＋Kit.check，全类型标注；源读取手法沿 player_copy_sweep_test 源 token 扫描先例）——七段断言组，全部带「扫描面非空前置＋正锚」：
|
||||
①七段文件集（settlement/ 七 .gd）逐件：文件存在且非空＋含对应 `class_name` 正锚＋`\boc\b` 全文零命中〔封装5.1 V2〕
|
||||
②battle_orchestrator.gd：非空＋`func _hero_atk|func _feat_yield_adjust|func _harmful_variants|func _harmful_adjacent|func _hits_of` 零命中（五方法零残留）〔封装5.1 V3〕
|
||||
③adventure_runner.gd：非空＋`_bp_store\._` 零命中＋`_bp_store.bp_read(` 正锚（新面在用）〔封装5.1 V4〕
|
||||
④save_manager.gd：非空＋`slots\._` 零命中＋`slots.active_path()` 正锚；slot_store.gd：非空＋`_save\._` 零命中＋`_save\.(set_read_only|read_only|reset_to_default|data_snapshot|restore_data|peek_summary_at|rename_overwrite)` 正锚〔封装5.1 V5〕
|
||||
⑤grant_segment.gd：非空＋`_fx_new_resource_types|_fx_bonus_delta` 零命中＋`mark_new_resource_type(` 正锚〔封装5.1 V6〕
|
||||
⑥config_db.gd：非空＋`\._resolver\s*=` 零命中＋`bind_resolver(_resolver)` 正锚〔封装5.1 V7〕
|
||||
- [ ] run_all.gd manifest 追加 2 行：settlement_wiring_snapshot_test（expect 0，注记「R1 同种子逐项 golden 对拍主证〔封装5.1〕」）＋encapsulation_sweep_test（expect 0，注记「R1–R6 结构性零命中扫描〔封装5.1〕」）
|
||||
- [ ] **实现报告** `reports/iter<N>-实现报告-<日期>.md`：各卡状态＋S13 键改前改后对账表（T1 基线逐件核）＋golden 改前改后对拍读数＋实现决定记录（代拍板白名单逐条回填）
|
||||
- [ ] **反哺点清单** `reports/iter<N>-反哺点-<日期>.md`：第 6 节同步面表逐条落点（architecture.md 八行登记内容、GDD/术语确认行）
|
||||
- [ ] 批末核对：game/tests/README.md 能力名与对照表引用一致（本卡零编辑）；独立验收审计（第 8 节末）未过不合并；.uid 收口＝`--editor --quit` 一次后确认 2 件新测试件 .uid 已生成随批提交
|
||||
|
||||
### 估时汇总
|
||||
|
||||
T1 0.25｜T2 1.25｜T3 0.625｜T4 0.375｜T5 0.375。
|
||||
区间合计 2.25–3.75 工作日；**精确汇总 2.875 工作日**（切分预案：若 T2 超 1.5 工日，把 T3 切出为独立半日卡顺延，其余不动；合计超 3 工作日＝超卡面估时域，须用户确认后方可续批）。
|
||||
|
||||
## 8. 验证闸（改动—验收对照表）
|
||||
|
||||
测试方式两分法：下表全部走**调试接口验证**（单元/集成套直构夹具与真实入口调用）；**正常流程体验验证**＝零项（零行为变更批，无目检点——实机观感逐位同改前）。判据全部绑被测改动特有的可观测提交面（同种子行流逐位／束引用同一性／源码零命中带非空前置与正锚）。
|
||||
|
||||
| 需求点 | 改动（文件:行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| R1 七段解耦＋束交付 | settlement 七文件重写＋battle_orchestrator 束组装与三调用点＋RoundCycle/BattleRefreshFlow 形态换代 | settlement_wiring_snapshot_test.gd:_init 主对拍〔封装5.1 V1〕；settle_segments_test.gd 束构造与同一性断言；round_flow_skill_pool_test／seal_polarity_test／refresh_feats_test 既有全套回归 | 单元＋集成 | `BattleOrchestrator.begin_battle()`→`MinesweeperRules.settle_batch()`→`player_request_refresh()`（全程公开入口） | 同种子行流与快照逐位同 golden（改前固化）；段持注入引用==编排器实例同一性；`\boc\b` 七文件零命中 | 既有：轮内流与结算五段全序 |
|
||||
| R2 搬家五方法归位 | damage_controller +hero_atk/hits_of/emit_hero_damage_taken 公开化＋facts 成员；reward_grant +feat_yield_adjust；minesweeper_rules +harmful_variants/harmful_adjacent；编排器五方法删除＋:282 改指 | settlement_wiring_snapshot_test〔封装5.1 V1〕（五方法消费路径全在行流内——主角攻击 base_value/奖励乘区/terrain_kind 事实/奥术矢开单）；roll_multiplier_test.gd:_smoke_hero_atk_derived 既有回归；adventure_feats_test hits_of 面回归；encapsulation_sweep_test 编排器五方法定义零命中〔封装5.1 V3〕 | 单元 | `begin_battle()`（enc hero_atk override→spawn→攻击单）／授予段真实结算链 | 攻击单基值随 enc override 走（派生读贯通）；行流逐位同；五方法宿主定义唯一（编排器零残留） | 既有：伤害公式与掷点乘区 |
|
||||
| R3 grant→BattleFxHost 累积方法 | battle_fx_host +mark_new_resource_type/+add_bonus_delta；grant :82-84/:169-170/:378-379 改址 | seal_polarity_test／round_flow_skill_pool_test 既有全套回归（血税 bonus_delta 与地质学家 new_resource_type 两订阅行行为面）；encapsulation_sweep_test grant 私键零命中＋正锚〔封装5.1 V6〕 | 单元 | 授予段真实结算链（mine_hit/seal_hit fx 发射→施加面） | bonus_delta 轴累积值与 new_resource_type 首见判定逐位同；grant 源零私键直写 | 既有：封印与极性路由／不可逆 |
|
||||
| R4 adventure_runner→BreakpointStore | breakpoint_store +13 公开方法面（_bp_read 更名 bp_read）；adventure_runner 37 处改址 | save_rng_roundtrip_test.gd:_test_old_version_save_migrates_and_resumes＋:_test_disk_roundtrip_preserves_breakpoint 既有回归（断点组装/回放/续玩全链真实入口）；encapsulation_sweep_test `_bp_store\._` 零命中〔封装5.1 V4〕 | 单元＋集成 | `AdventureRunner.resume_adventure()`／`start_adventure()`→`write_to_disk()`/`load_from_disk()` | 断点续玩逐位同（27 键冻结）；adventure_runner 源零 `_bp_store._` 直读写 | 既有：旧档迁移链与断点续玩零跳号（集成） |
|
||||
| R5 save_manager↔SlotStore 双向公开面 | save_manager→SlotStore＝slot_store +active_path/_migrate 更名公开化＋save_manager 九行改址；SlotStore→SaveManagerCore＝save_manager +5 公开方法/2 更名公开化＋slot_store 21 处改址 | save_manager_domain_test.gd:_smoke_save＋save_slot_isolation_test 既有回归；encapsulation_sweep_test `slots\._` 与 `_save\._` 双向零命中＋双正锚〔封装5.1 V5〕 | 单元 | `SaveManagerCore.write_to_disk()`／`load_from_disk()`／`_ready()` 迁移口／`SlotStore.activate_slot()`（三态恢复路径——read_only/data 快照还原）／`peek_slot_summary()`（窥视委托） | 写盘/读回/迁移/激活-恢复/窥视路径逐位同（tmp+rename 原子序、零拷贝还原语义不变）；save_manager 源零 `slots._`＋slot_store 源零 `_save._` | 既有：存档写盘⇄读回往返保真 |
|
||||
| R6 config_db→三表挂载 | 三 schema +bind_resolver；config_db :157-159 改址 | config_db_resolver_test.gd 既有全套回归（_test_rowset_order_preserved/_test_row_kind_routing/_test_difficulty_clamp——resolver 注入后解析面逐位同）；encapsulation_sweep_test `\._resolver =` 零命中＋正锚〔封装5.1 V7〕 | 单元 | `ConfigDB.load_tables()`（装配段）→`ConfigDbResolver.resolve_*()` | 行集解析/难度 clamp 逐位同；config_db 源零 `_resolver` 直写 | 既有：行集寻址、行序保序与难度乘数 clamp |
|
||||
|
||||
**零行为改动面的证据义务**：本卡全部六行均为非行为改动（零行为变更批）——不设「行为改动」行；每行的零变更证明＝T1 golden 同种子逐项比对（改前固化、改后全程绿）＋既有套件零转红＋结构性 sweep 恒零。能力行全部「既有」、零新增——判断依据：本批零行为变更＝玩家可观测能力面零变化，无新能力可登记；受影响存量行的真实入口与代表用例名零变化（settle_segments_test/adventure_feats_test 文件名与其在册引用不变），故能力清单零编辑（批末核对义务在 T5）。**覆盖登记（test-conventions §8.3 新增 core 件覆盖登记义务，2026-11-04 并 master 后适配）**：本批触碰且曾被审计点名的三件按「经宿主链覆盖」申报——breakpoint_store＝R4 行 `AdventureRunner.resume_adventure()/start_adventure()`→`write_to_disk()/load_from_disk()` 链＋新增 sweep 源扫描；slot_store＝R5 行 `SaveManagerCore.write_to_disk()/load_from_disk()/_ready()` 迁移口链；battle_fx_host＝R1/R3 行 `begin_battle()` 全结算链；三件申报面之外零新增点名义务，meta_state_store 本卡零触碰。
|
||||
|
||||
**闸口径**：重闸=`tools/run_all_gates.sh` 按本批改动域选档（改动含 game/ 下非 .md 行为载体 → `--code`）；所选域全绿才合并。卡内不写死闸件名单。回归措辞：里程碑卡（T 段）出口跑一次全套闸；卡内修复只做出红最小单元的最窄确认；新增测试先行孤立验证再并入全套。
|
||||
|
||||
**测试削弱申报**（允许改/删的旧断言全清单；未申报的删改由独立验收审计判红）：
|
||||
1. settle_segments_test.gd:20-24 五段直构断言——构造签名换代（host 三参/单参 → 束单参），断言对象从构造签名改束构造成功；段类可独立实例化的断言意图保持，强度不减（R1）。
|
||||
2. settle_segments_test.gd:28-34 宿主回指断言 6 条（`.oc == oc`）——段类对编排器引用归零后回指对象消失；改注入引用同一性断言（段持 facts/fx_host==编排器实例），装配面断言意图保持，强度不减（R1）。
|
||||
3. adventure_feats_test.gd:671/:691/:727 `orch._hits_of(...)` → `DamageController.hits_of(...)`——方法搬家改址，断言内容（attack_bonus 命中过滤）零改动（R2）。
|
||||
以上 3 条均为「随被测改动同步的引用形态迁移」，无一条删除断言或放宽阈值。
|
||||
|
||||
**独立验收审计**：入口=批末 T5 后、合并前；报告=`reports/iter<N>-验收审计-<日期>.md`；由没参与实现的会话或子代理执行，核对：对照表逐行断言真实存在且在当轮跑批通过、golden 改前改后对拍读数在案、测试削弱申报 3 条之外零删改、第 13 节无效成员零残留、S13 键只降不升对账。未过不合并。
|
||||
|
||||
## 9. 异常分级
|
||||
|
||||
- **L1 自救**：测试断言笔误、束键名拼写、注释错字、改址遗漏一处编译级报错的就地修复——就地改，记录进实现报告。
|
||||
- **L2 记录继续**：行号 ±5 行内的漂移（以 grep 符号锚定位后继续）；测试失败经排查属既有缺陷且与本批改动无因果——登记跳过并报用户。
|
||||
- **L3 停机写报告等用户**：①卡面与处置记录冲突、或处置记录未落盘/与本卡第 3 节不一致（上游缺陷，退写卡段）；②golden 改后读数与改前基线出现任何非预期漂移（零行为变更契约被破＝上游缺陷停卡，禁就地调和）；③束形态与 S13 预算互斥——任一触件成员数超第 14 节预算（RoundCycle 15/BattleFxHost 15/BreakpointStore 15/orchestrator 15 四贴顶件禁再增成员）＝上游缺陷停卡退写卡段，禁实现段自行拆件或砍面；④实现中发现第 4 节未登记的第五处编排器私取消费面或搬家方法第 4 个调用方（行为语义不明，禁代裁）；⑤机检键与卡片契约互斥（含 schema 校验/静态闸判据冲突）＝一律停卡呈报，不得自造第三条路。
|
||||
|
||||
## 10. 代拍板白名单
|
||||
|
||||
- 测试内部夹具命名与组织（束组装辅助函数名、golden 序列化键序、sweep 正则的具体写法——判据面不变）。
|
||||
- 注释与断言消息中文措辞微调（尾缀〔封装5.1 Vn〕与判别词保留）。
|
||||
- 段类/编排器头注的改写措辞（模块介绍职责不变）。
|
||||
- 束 assert 缺键报错文案（「引用束缺键」判别词保留）。
|
||||
- 逐卡内「孤立验证→出红最小单元→并入全套」的执行顺序细节。
|
||||
- T1 golden 转储通道的实现方式（打印格式/临时旗标，用后即删）。
|
||||
超清单的决断记入实现报告「实现决定记录」节。
|
||||
|
||||
## 11. 待裁点
|
||||
|
||||
**零待裁点，开工门=U0**——五处修复方案、段类终态（六子对象＋七回调＋段间引用＋公开读数注入＋对编排器零引用）、搬家五方法宿主、出卡边界、排序义务均已在 2026-11-03 设计讨论会话由用户裁决；束键分配、回调精确签名、T 卡分解、验收断言由本卡写卡期实查定死（第 3/4/7 节）。本卡未新增任何备选案。
|
||||
|
||||
## 12. 落位与可复用性预检
|
||||
|
||||
**新增文件（2 件，全部测试件）**：
|
||||
- tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd——为什么不能复用：同种子逐项 golden 对拍需冻结改前全行流为常量基线，既有套件（round_flow_skill_pool 等）断言的是段内序与行为面、无整流 golden；battle_settlement 目录落点（夹具对象=战斗结算全链）；grep 同名零命中。驱动夹具复用既有件：ConfigDBScript 显式构造＋AutoPlayer.choose_dig（roll_multiplier_test.gd:14-16 同款装配先例，引用不复制）。
|
||||
- tests/unit/core/encapsulation_sweep_test.gd——为什么不能复用：五处结构性零命中是本批特有扫描面（七文件集＋五方法残留＋四处私取模式），player_copy_sweep_test 扫的是 presentation 文案面——**复用其源 token 扫描手法但不并件**（并件会让两批扫描面与尾缀语义混乱）。唯一落点 tests/unit/core；grep 同名零命中。
|
||||
|
||||
**新增函数/成员（逐条唯一性核查，grep 同名全库实核）**：
|
||||
- `DamageController.hero_atk`/`hits_of`/`emit_hero_damage_taken`——编排器 `_hero_atk`/`_hits_of` 改名迁移非并存（禁别名）；`_emit_hero_damage_taken` 去下划线公开化非新增体；`facts` 成员为该件第 13 个类变量（预算内）。grep `func hero_atk`/`func hits_of` 全库零第二处。
|
||||
- `RewardGrant.feat_yield_adjust`——`_feat_yield_adjust` 改名迁移；RewardGrant 持 reward_economy 引用（:22 既有）故体零改动可行。grep 唯一。
|
||||
- `MinesweeperRules.harmful_variants`/`harmful_adjacent`——改名迁移；db 为构造参（:44 既有）。grep 唯一。
|
||||
- `BattleFxHost.mark_new_resource_type`/`add_bonus_delta`——新方法旧账面（成员零增）；grep 同名零命中，命名与既有 apply_ac_bonus/counter_add 动词族同型。
|
||||
- `SlotStore.active_path`——grep 全库零同名；has_write_target 同族读投影。
|
||||
- SaveManagerCore 五公开面（承接 slot_store 反向私取）——`set_read_only`/`read_only`/`reset_to_default`/`data_snapshot`/`restore_data` grep 作方法名全库零第二处（现仅为成员名或私有方法）；`peek_summary_at`/`rename_overwrite` 为私有方法更名公开化非并存（禁别名，第 13 节适用）；`reset_to_default` 件内既有调用点同名零改。
|
||||
- `BreakpointStore` 13 方法——grep `pending_next_level|loadout_seeded|resume_bp|last_level_payload|last_treasure_cleared|bp_read|bind_save_manager` 作为**方法名**全库零命中（现仅为成员名）；成员到方法一一对应，无第二落点。
|
||||
- 三 schema `bind_resolver`——grep 零同名；参数类型 ConfigDbResolver 与 config_db.gd:43 既有协作类同一实例。
|
||||
- `RoundCycle.refresh_flow`——grep 零同名；读出口与 stats()/wallet() 组件出口先例同型（adventure_runner.gd:60-82）。
|
||||
|
||||
**复用既有（不新增）**：束注入形态=BoardInstaller/BattleFxHost/RewardGrant/BreakpointStore 四先例；读投影 Callable=attune_safe_seen_cb/pool_effective_cb/facts_cb 三先例；源扫描测试=player_copy_sweep_test 手法；manifest 登记=run_all.gd 既有条目族。零新增生产文件（全部落在既有件——架构七段结构零改动的直接后果）。
|
||||
|
||||
**分层与交互面**：段类→六子对象/协作件＝既有 B1 域内调用关系（architecture.md:119 B2/B3/B4 全调用面唯一调用方=B1 域文件集——S7_B1_SET 已含七段，零新增跨域路径）；段类→编排器＝单向 Callable（禁双向强引用）；三 schema bind_resolver＝既有 config_db→schema 装配方向（:131-159 同向，禁反向）；RngService 红线零触碰（本批零新增随机源）；Core 零 UI 红线零触碰（全套件 --headless 可跑）；数值单一事实源零触碰（零表改动）。
|
||||
|
||||
## 13. 禁为机检文本保留无效成员
|
||||
|
||||
本卡为重构类卡，全卡适用以下条款（code-conventions §1.1 ⑤同款）：禁止为迎合机检消息文本（含计数、sweep 正则、grep 面）而保留或新增无效成员/别名/转发壳；搬家五方法宿主原方法删除后禁留同名或别名转发壳；`_migrate_legacy_save` 更名后禁留旧名壳；`_bp_read` 更名后禁留旧名壳；`_emit_hero_damage_taken` 公开化后禁留私有旧名；BreakpointStore 新方法面禁在成员外另立镜像账本。机检键与卡片契约互斥时（如 S13 贴顶件、sweep 正则与签名冲突），实现段一律停卡呈报，不得自造第三条路。
|
||||
|
||||
## 14. 实现规范预算
|
||||
|
||||
新增 .gd 文件仅 2 个测试件（SceneTree 测试脚本，全类型标注、零公开生产面——接口块预算余量充足）。生产代码全部落既有件，按「存量触面一查」逐件对账（S13 默认阈值：公开方法 ≤20／类变量 ≤15／分支 ≤8／返回 ≤6）：
|
||||
|
||||
- **贴顶四件（禁再增成员，T1 读数锁定）**：battle_orchestrator.gd 15（本批成员零净增——五方法删除不涉成员）；round_cycle.gd 8→15（束解包 7＋_refresh_flow 1＋既有 7——贴顶，头注记「贴顶禁再增」）；battle_fx_host.gd 15（零增，方法-only）；breakpoint_store.gd 15（零增，方法-only）。
|
||||
- **类变量净增件**：grant_segment 3→12、combat_segment 3→10、verdict 1→5、aura 1→1、decay 1→2（两件现各持 oc 一员——aura 换单回调成员 1→1、decay 换两成员 1→2）、battle_refresh_flow 0→8、damage_controller 12→13——全部 ≤15。
|
||||
- **公开方法净增件**：minesweeper_rules 18→**20 贴顶**（+2）、damage_controller 9→12（+hero_atk/hits_of＋emit_hero_damage_taken 公开化——2026-11-03 终审实核现值 9）、reward_grant 9→10、battle_fx_host 16→18、slot_store 10→11、breakpoint_store 5→18、save_manager 7→14（+5 承接方法＋peek_summary_at/rename_overwrite 两更名公开化）、RoundCycle 3→4、三 schema 各 +1——全部 ≤20。
|
||||
- **迁移函数对账**：搬家五方法＋`_migrate_legacy_save`＋`_bp_read`＋`_emit_hero_damage_taken`＋`_peek_summary_at`＋`_rename_overwrite` 逐个查 `tools/gdstyle_baseline.txt` 源键——基线无此 10 键（默认阈值内），迁移即原体；若 T1 读数发现任一源函数 branches/returns 超默认登记值，迁移即拆函数（拆分不改语义，不算迎合机检——与第 13 节区分）。
|
||||
- **存量触面 S13 预期**：本卡触件 15 件（第 3.2 节清单）S13 键较 T1 现场基线**只降不升**（净删为主：五方法约 45 行迁出、107 处 oc._ 改址不增行数；净增面＝两累积方法＋13 bp 方法面＋束解包成员行）；adventure_runner 既有登记键（类变量 23）照登对账零变化。降不达即检查是否夹带超预算成员，L3 ③兜底。
|
||||
- **指标例外申报**：无（零新件、零超默认阈值新增面；若实现中发现例外，走本卡异常分级 L3 ③停卡，禁就地豁免）。
|
||||
|
||||
## 15. 拆分边界纪律
|
||||
|
||||
见第 4 节红线（结构类卡必填条款，判据权威=code-conventions §1.1）：本卡零新拆件——段类七件、RoundCycle、BattleRefreshFlow、DamageController、RewardGrant、MinesweeperRules、BattleFxHost、BreakpointStore、SlotStore 全部架构在册既有件，本批只做接线形态换代与五方法归位。逐件职责语句不变：五段段类＝B1 每轮结算序列的分段逻辑件（architecture.md:127）、RoundCycle＝轮结算周期推进结构单点（:125）、BattleRefreshFlow＝换图刷新流程唯一承载（:123）、五方法归位＝各领域宿主既有职责面内的原语归位（伤害基值派生读归伤害管线、奖励乘区调整归授予管线、地形伤害型变异过滤归棋盘状态域、效果命中过滤归伤害域）。单一变化原因＝封装边界（跨对象私取清零），非阈值驱动。禁凑计数袋：段类成员束解包以消费面为准（第 4 节分配表逐段列明），无「剩下的成员」式打包。先例=迭代 41 两卡 v1.2（核心数据面契约 7／呈现层契约 9）。
|
||||
@@ -16,9 +16,11 @@
|
||||
|
||||
**实况**：2026-10-29 全库架构静态审计的四组待裁余项，自「架构审查优化讨论」条目迁入（该条目的 3.1+3.2 部分已随迭代 50 卡③实现合回〔合并提交 8d3a12ec〕，余项不在本卡，按未决先迁再死迁立本条）。四组余项（审计待裁点 ④⑤⑥⑦，读数为审计时点，逐项现值以仓库为准）：①守卫闸面缺口——S1/S2 随机函数扫描面止步 core＋presentation（sim 4 处／probe 1 处／tests 3 处自建 RNG 不在扫）、S9 类型闸与 S13 质量闸扫描面不含 sim/probe/tests、S8 是 9 文件显式清单（缺位自检只防删改不防增）；②S13 质量闸豁免存废——审计时点三处豁免常态化到最大户文件（battle_orchestrator 已随拆件批收窄，余量以闸件为准）；③零测试点名四件（attune_loadout／battle_fx_host／meta_state_store／slot_store）；④架构文档漂移三处（architecture.md 登记的 core/hero_ledger.gd 盘上不存在且测试断言它必须不存在、行数过期、EC8 热重载门后 ConfigDb.reload() 零调用方且走 load() 拿不到磁盘新值）。凭据：reports/审计-全库架构审查-2026-10-29.md（待裁点节）＋reports/处置-架构审查3.1+3.2整改-2026-11-02.md（3.1+3.2 闭合凭据，随迭代 50 合回）。
|
||||
|
||||
**缺口**：四组余项中①②③ 已裁完并落地（见下 2026-11-03 记录）；④**架构文档漂移三处**的落文档由并行 worktree 批（arch51-docs——HeroLedger 行拆件四件补登记＋行数冻结计数摘除＋MetaProgression 补登记行）承载，随其合回销号；同族审计 §5.1 已登记已写卡（arch51-card 批）、§5.3 已写卡（见下 2026-11-04 段，本 worktree）、§5.4（MetaProgression 登记零动作）已随 arch51-docs 落文——均随各自合回入册；presentation 层私取面约 227 行另开设计讨论，为本条最后余项。
|
||||
**缺口**：四组余项中①②③④ 全部闭合销号（④ 架构文档漂移三处已随 arch51-docs 批落文档并合回——HeroLedger 行拆件四件补登记＋行数冻结计数摘除＋MetaProgression 补登记行）；同族审计 §5.1 已写卡并合回（arch51-card 批，见下 2026-11-03/11-04 记录）、§5.3 已写卡（见下 2026-11-04 段，本卡合回后在册）、§5.4（MetaProgression 登记零动作）已随 arch51-docs 落文合回；presentation 层私取面约 227 行另开设计讨论，为本条最后余项。
|
||||
|
||||
**2026-11-03 P2 部分（5.1 封装＋5.2 文档漂移＋5.3 词表）推进**：5.1 设计闭合＋已写卡——处置记录与需求卡片 v1.1（godot-master 终审七项折入，pipeline_gate PASS）落 arch51-card worktree、处置记录落 arch51-docs worktree，随各自合回落 master 后互见；5.2 文档漂移归真已落档（architecture.md——HeroLedger 行拆件四件补登记／冻结计数摘除／MetaProgression 补登记行／CurioStop 与 RunLedger 旧指称订正，arch51-docs worktree 提交 63fc3e74＋e614773a，文档域闸全绿）；**EC8 热重载侧经用户裁决撤卡**——GDD 规格恢复原状（本批一度摘除已撤回）、config_db 门与 reload＋编排器两行开门点代码原样保留为将来实装骨架，实装去向＝用户另立待办条目＋后续实装卡（他会话写卡）；5.3 已写卡——凭据＝reports/需求卡片-架构审查P2代码面批-2026-11-03.md v1.1（archp2-card worktree，仅 NODE_TYPES 词表单点化，零待裁点，估时 0.25 工作日，排序在 5.1 卡后，行号已按迭代 50 合回后现址换代 :136）；**未闭合余项收窄（2026-11-04 并 master 后对账）**＝仅剩 presentation 层私取面约 227 行（另开设计讨论）——闸面缺口、S13 豁免存废、零测试点名三组已随 §4 批（2026-11-03 裁决＋闸件落地，见上裁决段）闭合销号。
|
||||
**2026-11-03 设计闭合＋写卡（5.1 封装修复部分，2026-11-04 并 master 后凭据换代）**：2026-11-03 会话对审计 §5.1（settlement 段类私取编排器私有成员）完成设计讨论并扩面普查，裁决五处跨对象私有访问修复方案（settlement 七段→编排器束交付／搬家五方法／adventure_runner→BreakpointStore／save_manager↔SlotStore 双向公开面／grant_segment→BattleFxHost＋config_db→三表容器；presentation 层约 227 行另开设计讨论不在内）。凭据＝reports/处置-架构审查5.1封装修复-2026-11-03.md（处置记录）＋审计报告 §5.1＋architecture.md:119/:124/:137-146。需求卡片 reports/需求卡片-架构审查5.1封装修复批-2026-11-03.md（**v1.1**——godot-master 终审七项折入〔golden 封印步改封未揭示相邻格／三 schema 解析冒烟义务／T3 签名补注解／成员账两笔订正／harmful_adjacent 自呼随更名／现值交付口径注／SlotStore→SaveManagerCore 反向私取终审补查 21 处并入 T3〕；5 张 T 卡估时精确汇总 2.875 工作日；零行为变更批，能力清单零新增行已写明判断依据）；实现排序在 3.1+3.2 卡之后——该卡已随迭代 50 合回，前置已解除（combat_segment 行号漂移按卡内 grep 锚定位预案处理）。
|
||||
|
||||
**2026-11-03 P2 部分（5.2 文档漂移＋5.3 词表＋EC8 撤卡，2026-11-04 并 master 后入册）**：5.2 文档漂移归真已落档并合回（architecture.md——HeroLedger 行拆件四件补登记／冻结计数摘除／MetaProgression 补登记行／CurioStop 与 RunLedger 旧指称订正，arch51-docs 提交 63fc3e74＋e614773a，文档域闸全绿）；**EC8 热重载侧经用户裁决撤卡**——GDD 规格恢复原状（本批一度摘除已撤回）、config_db 门与 reload＋编排器两行开门点代码原样保留为将来实装骨架，实装去向＝用户另立待办条目＋后续实装卡（他会话写卡）；5.3 已写卡——凭据＝reports/需求卡片-架构审查P2代码面批-2026-11-03.md v1.1（仅 NODE_TYPES 词表单点化，零待裁点，估时 0.25 工作日，排序在 5.1 卡后，消费点行号已按迭代 50 合回后现址换代 :136）。**未闭合余项对账（2026-11-04）**＝仅剩 presentation 层私取面约 227 行（另开设计讨论）——闸面缺口、S13 豁免存废、零测试点名三组已随 §4 批（2026-11-03 裁决＋闸件落地，见上裁决段）闭合销号。
|
||||
|
||||
**改动面**：文档＋游戏代码＋工具代码
|
||||
|
||||
|
||||
Reference in new issue
Block a user