diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 6f0634c5..087faa46 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -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。 diff --git a/design/engineering/code-conventions.md b/design/engineering/code-conventions.md index db31143a..0e56f8fe 100644 --- a/design/engineering/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -34,6 +34,12 @@ ### 1.5 禁止事实约定 任何"大家默认这么做"的惯例必须成文进本文件（或 AGENTS.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。 +### 1.6 拆分交接与封装边界 +本节管拆分类改动的交接面与封装面，与 §1.1 拆分判据（职责轴）配合使用：§1.1 管怎么切，本节管切完之后件与件之间怎么往来。 + +1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——架构文档「战斗编排域拆件定稿」节 BoardInstaller 行在册）。 +2. **封装边界**：任何代码不得访问其他对象的下划线成员；跨对象往来只走公开方法与属性。为什么：下划线只是命名约定，语言不设防、无编译期检查——此条是封装硬纪律，违者即红。 + --- ## 2. 契约纪律——跨层/跨类调用的语义 diff --git a/reports/处置-架构审查5.1封装修复-2026-11-03.md b/reports/处置-架构审查5.1封装修复-2026-11-03.md new file mode 100644 index 00000000..d7432405 --- /dev/null +++ b/reports/处置-架构审查5.1封装修复-2026-11-03.md @@ -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 的登记原样出处）。