From 3213722fed19972370d1c2e11068e38135660498 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Thu, 29 Oct 2026 02:13:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E8=BF=AD=E4=BB=A341=E5=8F=8D=E5=93=BA?= =?UTF-8?q?=E8=90=BD=E6=96=87):=20architecture=20v1.23=E2=80=94=E2=80=94?= =?UTF-8?q?=E5=85=A8=E6=B8=85=E5=AE=9A=E7=A8=BF=E6=B3=A8=E8=AE=B0=E8=BD=AC?= =?UTF-8?q?=E7=8E=B0=E7=8A=B6=E7=99=BB=E8=AE=B0=EF=BC=88ConfigDB=20?= =?UTF-8?q?=E4=B8=89=E5=9F=9F=E5=AE=B9=E5=99=A8=207/7/5=20=E4=B8=8E?= =?UTF-8?q?=E5=85=AC=E5=BC=80=E9=9D=A2=208=E3=80=81SlotStore=2010/4=20?= =?UTF-8?q?=E7=BB=8F=20save.slots=20=E7=9B=B4=E8=BF=9E=E3=80=81MetaStateSt?= =?UTF-8?q?ore=20=E5=86=99=E5=8F=A313+=E8=AF=BB=E6=8A=95=E5=BD=B16=20?= =?UTF-8?q?=E7=BB=8F=20save.meta=5Fstate=20=E7=9B=B4=E8=BF=9E=E3=80=81meta?= =?UTF-8?q?=5Fprogression=20=E5=85=AC=E5=BC=80=E9=9D=A2=2020=20=E5=AE=9A?= =?UTF-8?q?=E7=A8=BF=E4=B8=89=E5=B9=B6=E7=BB=84=EF=BC=89=EF=BC=8Bminesweep?= =?UTF-8?q?er=5Frules=20=E6=B6=88=E8=B4=B9=E4=BE=9D=E8=B5=96=E8=A1=A5=20la?= =?UTF-8?q?st=5Fround=5Fend=20=E6=96=B9=E6=B3=95=E5=BD=A2=E6=80=81?= =?UTF-8?q?=E6=B3=A8=E8=AE=B0=EF=BC=9BB7/B8/B9=20=E4=B8=89=E6=9D=A1?= =?UTF-8?q?=E5=B7=B2=E9=9A=8F=E5=B9=B6=E8=A1=8C=E6=96=87=E6=A1=A3=E7=BA=AF?= =?UTF-8?q?=E5=BA=A6=E6=89=B9=2000312e12=20=E5=85=A5=E5=BA=93=EF=BC=88B7?= =?UTF-8?q?=20=E5=BC=95=E7=94=A8=E5=9D=97=E6=95=B4=E5=88=A0=E6=89=BF?= =?UTF-8?q?=E8=BD=BD=E3=80=81B8/B9=20=E8=B0=83=E5=8F=82=E8=A1=A8=E8=90=BD?= =?UTF-8?q?=E7=82=B9=E6=94=B9=E6=AE=B5=E8=B7=AF=E5=BE=84=E4=B8=89=E8=A1=8C?= =?UTF-8?q?=E9=9A=8F=E6=89=B9=E5=85=A5=E5=BA=93=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/engineering/architecture/architecture.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index d951ea53..c7db53d6 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,8 +2,8 @@ ## 文档状态 -- 版本：1.22 -- 最近更新：2026-10-28（迭代 40 拆件批反哺落文——编排域拆件定稿节转现状登记：reward_economy 消费依赖改注入 Callable 口径、BattleFxHost 补 luck_bias_for 查询口、接线款补注入 Callable 款与 battle_hooks 三键回调束形态、补 RunLedger 退役后战斗域读面款、S13 豁免登记补第三条 battle_orchestrator 类变量键） +- 版本：1.23 +- 最近更新：2026-10-29（迭代 41 反哺落文——ConfigDB／SlotStore／MetaStateStore／meta_progression 四行全清定稿注记转现状登记＋minesweeper_rules 消费依赖补 last_round_end 方法形态注记；action_economy／variation／status_container／board_generator／unit_container／reward_economy 六行公开面零语义变化未动） - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调） - 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） @@ -85,9 +85,9 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| -| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机。**2026-10-27 全清设计定稿：行族访问器归位各 schema 表类（表管自己的行查询），本类只留加载/校验/override/诊断门面（≤20）；表持有成员按域收进域容器 Resource（分组建档于实现卡，消费方改址随该批）**——红线不变：本类仍是唯一加载与持有单点，"经 ConfigDB 单点读取"＝经其持有的表对象 | 类型化域容器属性（每域一张容器）；`load_tables(root, collect_only)`；诊断门面；`set_reload_gate()`；`reload` | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW | -| **SlotStore**（`core/slot_store.gd`，D3 存档槽位域件，2026-10-27 全清设计定稿——实现批建件） | 存档三槽位文件域唯一所有者（自 save_manager 收编槽位族）：槽位挂载与模板、激活与建删、槽位摘要窥视（peek 族） | 槽位读写原语族＋摘要投影（SaveManager 与菜单消费方直连） | save_manager（注入路径与模板配置）；FileAccess——LOW | -| **MetaStateStore**（`core/meta_state_store.gd`，D3 存档内元进度数据件，2026-10-27 全清设计定稿——实现批建件） | 存档内元进度数据的读写唯一层（自 save_manager 收编 accessor 族：钥石/道具解锁/树节点与叉侧/锻造路线/同调/真视/计数器/摘要——数据读写原语，不含业务规则）；save_manager 与 meta_progression 双 God Class 的共同病根＝该数据域摊在两文件，本件即其归一 | 数据读写原语族＋只读投影（MetaProgression 业务层与营地/锻造 UI 消费方直连；meta 的纯转发读方法随件退役） | save_manager（序列化接线）；FileAccess——LOW | +| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机。**行族访问器归位各 schema 表类（表管自己的行查询），本类只留加载/校验/override/诊断门面；表持有成员按域收进三张域容器 Resource（`config_domain_combat/run/crossrun.gd`——已建件（迭代 41），类型化成员 7/7/5）；三张 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）、类变量 9 | 无（基础层顶点） | 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 | | **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}、结束仲裁 | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh / notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；effect_engine（事件发射 dispatch——基础层内同层引用）；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） | 无 | @@ -101,7 +101,7 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| | **board_generator**（A1） | 生成算法（五阶段管线）、BoardGenTable 回填、生成期指标集、合法性谓词（clearable / R₀≠S / min_safe）、可推理率度量（metric_version）；生成姿态 = MVP 同步生成 + 加载幕（切片实证 10×10/12×12 同步可接受，WorkerThread 留扩展） | `generate(L, D, rng) -> Board`；度量独立入口×3（推理器 / F3 度量 / 合法性谓词——独立纯函数、同一实现） | ConfigDB（BoardGenTable/VariationTable）；board_gen 流（一次 open_stream = 一张图）；dig_ap_cost 只读 | 无 | -| **minesweeper_rules**（A2） | 棋盘状态（已开集 O / 封印集 G / 小人位）、三事件面、批次仲裁、install 四不变式 | `install_board(board)`；`settle_batch(intents)`（唯一提交入口）；查询只读面（current_board / hero_pos / is_revealed / has_seal 等）；`compute_move_path(cell)` 只读；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end / 相位 | 无（零表读取、零 UI——切片实证） | +| **minesweeper_rules**（A2） | 棋盘状态（已开集 O / 封印集 G / 小人位）、三事件面、批次仲裁、install 四不变式 | `install_board(board)`；`settle_batch(intents)`（唯一提交入口）；查询只读面（current_board / hero_pos / is_revealed / has_seal 等）；`compute_move_path(cell)` 只读；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end（迭代 41 由属性改方法）/ 相位 | 无（零表读取、零 UI——切片实证） | | **unit_container**（B2） | hero/enemy 单位实例（hp/atk/实例池：池快照+冷却+摇定动作+保底计数）、行值快照 | spawn / query_alive / rollable_skills / special_skills / check_trigger_unlocks / set_pending_action / pending_action / basic_streak / commit_action / tick_cooldowns / apply_damage / heal / default_target / check_skill_unlocks / despawn_all（2026-09-16 敌人技能池批：query_beat/query_attack/advance 随行为环退役；rollable_skills/special_skills/check_trigger_unlocks 带 facts 参——2026-10-27 情境条件触发器实装，事实缺键=条件假拦下，百分比事实走阈值式折算） | ConfigDB（EnemyTable/SkillTable/HeroTable） | 无 | | **reward_economy**（B4） | 格面资源身份映射（install 期预分配、Ready 只读、换图映射消亡）、极性路由字典面（（类型, 极性）→ 字典行查询；路由执行归 B1 授予段）、F6 当量供给投影 | 封闭 API：roll_board / query_identity / query_full_snapshot / grant / grant_clear / retire_mapping / polarity_row / phase / weighted_pick；另有 is_mapped 静默布尔投影（批量工具用） | ConfigDB（RewardTable）；BattleFxHost 经注入 Callable `luck_bias_query` 取偏运合计（reward_roll 发射与 bias_rewards 求和移至效果层完成）；reward_roll 流（scope = 每次 install 批） | 无 | | **helper_items**（A5，切片已实装秘宝域） | HelperItemTable、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 | @@ -123,7 +123,7 @@ | **level_runner**（C1-lite，切片已建） | 关卡域生命周期（节点链推进、共享 B4 + HP 携带、关卡末 level_clear） | 节点推进接口；LevelTable（`level.tres`——节点 enum {battle,reward,rest,boss}、末节点必须 Boss、ConfigDB 跨表校验⑧） | B1（直构 BattleOrchestrator 接线战斗）、ConfigDB LevelTable | 无 | | **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （契约规范源：`../../gdd/systems/冒险循环/冒险结构.md`） | RngService.set_master_seed、C3/D2 | 无 | | **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 | -| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编）。**2026-10-27 全清设计定稿：存档内元进度数据读写原语归 MetaStateStore（新件），本类纯转发读方法随件退役（消费方直连 store），业务规则与写口编排留本类（≤20）** | tree_can_buy/tree_buy/tree_buy_fork/tree_toggle_fork（写口唯一）、hero_override 注入（树淬炼 flat+锻造路线加值位预留 0）、tree_rule_keys | D3、C2、ConfigDB | 无 | +| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编）。**存档内元进度数据读写原语归 MetaStateStore——已落地（迭代 41）：本类纯转发读已退役（消费方直连 meta_state），业务规则与写口编排留本类；hero_override 内联锻造加值与树淬炼 flat；并组三组（forge_select(kind,route_id)／hero_type_axes()→{attack,armor}／tree_camp_status()→{rows,fork_groups}）；补 meta_state 成员装配** | 公开面 20 定稿：buy_treasure_unlock / refresh_treasure_unlocks / treasure_shop_status / forge_buy_level / forge_buy_unlock / forge_select / hero_type_axes / forge_shop_status / settle_adventure / hero_override / tree_can_buy / tree_buy / tree_toggle_fork / tree_buy_fork / tree_rule_keys / tree_camp_status / toggle_attunement / attune_camp_status / attune_refresh_charges / buy_attune_refresh | D3、C2、ConfigDB | 无 | ### 战斗域装配现状（迭代 27——2026-10-17 用户裁写入；RunLedger 段已随迭代 39 拆件批退役，四账去向见下「冒险域拆分（现状登记）」节）