From 14637151e733ed2e6dff0669b12259e5fe70b225 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 9 Nov 2026 01:58:26 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=94=B6=E6=95=9B=E6=89=B9?= =?UTF-8?q?=E7=AC=AC1=E6=AD=A5:=20architecture.md=20v2.0=E2=86=92v3.0=20?= =?UTF-8?q?=E4=BE=9D=E8=B5=96=E8=A7=84=E5=88=99=E5=BD=A2=E6=80=81(290?= =?UTF-8?q?=E2=86=92221=E8=A1=8C)=E3=80=82=E5=88=A0=E3=80=8C=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E5=BD=92=E5=B1=9E=E3=80=8D=E6=95=B4=E8=8A=82(38?= =?UTF-8?q?=E8=A1=8C=E6=A8=A1=E5=9D=97=E8=A1=A8)=E6=8D=A2=E3=80=8C?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=BD=92=E5=B1=9E=E3=80=8D=E8=A1=A8(7?= =?UTF-8?q?=E8=A1=8C=E2=80=94=E2=80=94=E7=9B=AE=E5=BD=95=3D=E5=B1=82?= =?UTF-8?q?=E7=BA=A7=E7=89=A9=E7=90=86=E6=89=BF=E8=BD=BD,=20=E5=90=8C?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=90=8C=E5=B1=82=E7=BA=A7=E5=90=8C=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E5=B1=9E=E6=80=A7,=20=E9=A2=86=E5=9F=9F=E4=B8=8D?= =?UTF-8?q?=E5=88=87=E7=9B=AE=E5=BD=95=E4=BB=85=E9=A2=86=E5=9F=9F=E5=86=85?= =?UTF-8?q?=E9=83=A8=E5=86=8D=E9=9C=80=E4=B8=80=E5=B1=82=E6=97=B6=E7=AB=8B?= =?UTF-8?q?=E5=AD=90=E7=9B=AE=E5=BD=95=E5=A6=82settlement;=20=E5=B1=82?= =?UTF-8?q?=E7=BA=A7=E4=BD=9C=E7=94=A8+=E7=BA=A6=E6=9D=9F=E5=B1=9E?= =?UTF-8?q?=E6=80=A7=E4=B8=A4=E5=88=97,=20=E6=96=87=E4=BB=B6=E4=B8=8E?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E8=81=8C=E8=B4=A3=E5=BD=92=E5=A4=B4=E6=B3=A8?= =?UTF-8?q?);=20=E5=88=A0=E3=80=8CAPI=20=E8=BE=B9=E7=95=8C=E3=80=8D?= =?UTF-8?q?=E6=95=B4=E8=8A=82(11=E8=A1=8C=E6=A8=A1=E5=9D=97=E5=AF=B9?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=E8=A1=A8+=E5=BC=95=E6=93=8E=E7=B1=BB?= =?UTF-8?q?=E5=9E=8B=E6=B3=A8=E8=AE=B0=E2=80=94=E2=80=94=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E6=BA=90=E5=8D=95=E7=82=B9=3D=E5=90=84GDD,=20=E6=89=A7?= =?UTF-8?q?=E6=B3=95=3DS=E9=97=B8+=E5=A5=91=E7=BA=A6=E6=B5=8B=E8=AF=95,=20?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3=E4=B8=8D=E5=81=9A=E8=BD=AC?= =?UTF-8?q?=E8=BF=B0);=20=E4=BF=9D=E7=95=99=E5=88=86=E5=B1=82=E5=9B=BE+?= =?UTF-8?q?=E5=94=AF=E4=B8=80=E5=9B=9E=E8=BE=B9/=E5=91=88=E7=8E=B0?= =?UTF-8?q?=E5=B1=82=E8=A3=85=E9=85=8D=E5=90=88=E5=90=8C/RunScope=E5=AD=98?= =?UTF-8?q?=E6=B4=BB=E6=80=A7=E7=9F=A9=E9=98=B5/=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=E5=9F=9F=E4=BE=9D=E8=B5=96=E7=BA=A6=E6=9D=9F/=E6=95=B0?= =?UTF-8?q?=E6=8D=AE=E6=B5=81=E4=BA=94=E8=8A=82/=E4=B9=9D=E5=8E=9F?= =?UTF-8?q?=E5=88=99=E3=80=82=E5=87=AD=E6=8D=AE:=20--docs=20=E5=9F=9F?= =?UTF-8?q?=E9=97=B8=E3=80=90=E9=AA=8C=E6=94=B6=E9=80=9A=E8=BF=87=E3=80=91?= =?UTF-8?q?=E6=97=A0=E6=96=B0=E5=A2=9E=E7=BA=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../engineering/architecture/architecture.md | 95 +++---------------- 待办清单.md | 6 ++ 2 files changed, 19 insertions(+), 82 deletions(-) diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index a7a3fea8..f6b4ac2c 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,11 +2,11 @@ ## 文档状态 -- 版本：2.0（收窄为约束面形态——分层/模块归属/数据流/API 边界；实现现状归代码与代码头注，实现历史归 git commit log，闸清单与判定口径归 `game/tests/README.md`，见 doc-conventions「架构事实唯一源」行） +- 版本：3.0（依赖规则形态——分层/目录归属/数据流/原则；模块级归属登记与模块对接口契约均不进本文：前者归代码文件头注，后者规范源单点＝各系统 GDD、执法＝静态扫描域与契约测试） - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`——门禁按 solo 跳过） - 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） -- 事实源地位：本文是架构约束的唯一权威（分层/模块归属/数据流/API 边界）；写权限＝用户专属（agent 与技能只读） +- 事实源地位：本文是架构约束的唯一权威（分层/目录归属/数据流/架构原则）；写权限＝用户专属（agent 与技能只读） - 实现实证：`game/`（完整游戏开发版本；本文分层与所有权经实现验证）。测试层级＝冒烟/单元/系统三级＋UI 探针与渲染 golden，识别三元组权威＝`design/engineering/test-conventions.md`「测试层三元组」节 --- @@ -74,66 +74,19 @@ --- -## 模块归属 +## 目录归属 -> 命名遵循 `design/engineering/code-conventions.md`：领域命名、禁 ID 前缀。本表只写约束：模块的职责语句、对外封闭面概述与消费依赖——各件的完整公开方法面、成员与接线明细归代码文件头注（`##` 文档注释）与代码自身承载；文件路径是导航索引。 +> 目录＝层级的物理承载：同一目录内的文件同层级、同受该层约束属性管辖，职责各自独立、归各文件头注（`##` 文档注释）承载；领域不做目录切分，仅当领域大到内部再需要一层时才立子目录。命名遵循 `design/engineering/code-conventions.md`：领域命名、禁 ID 前缀。逻辑依赖层级（基础/核心/功能/呈现）见「系统分层图」——`game/core/` 一目录内按依赖层级再分三段，层级约束由分层图与架构原则承载，目录不再切分。 -### 基础层 - -| 模块 | 文件 | 独占职责 | 对外封闭面 | 消费依赖 | -|---|---|---|---|---| -| **ConfigDB**（autoload，D2） | `game/core/config_db.gd` | 全部玩法数值表唯一加载与持有单点（`.tres` 经校验后入容器）；行族访问器归各 schema 表类（表管自己的行查询），本类只留加载/校验/override/诊断门面，表持有按域收进域容器 Resource | 类型化域容器属性＋load_tables / reload / set_reload_gate / diagnostics 族 | 无（基础层顶点） | -| **RngService**（autoload，D2） | `game/core/rng_service.gd` | master_seed 与各封闭流 scope 计数器单点（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准，增流走 P1 评审） | set_master_seed（唯一调用方 C2）/ open_stream 有状态门面 / derive_at 纯函数 / 只读计数器 | 无 | -| **save_system**（SaveManager，autoload，D3） | `game/core/save_manager.gd` | 存档格式与版本比较、序列化接线单点；槽位文件域归 SlotStore、元进度数据归 MetaStateStore | 写盘/读回/槽位管理/断点快照公开面（契约规范源：`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚：SAVE_FORMAT_VERSION + master_seed + 各流 scope 计数器快照） | ConfigDB、RngService 只读计数器 | -| **SlotStore**（D3） | `game/core/slot_store.gd` | 存档三槽位文件域唯一所有者：槽位挂载与模板、激活与建删、摘要窥视 | 槽位读写原语族＋摘要投影 | save_manager（注入路径与模板配置） | -| **MetaStateStore**（D3） | `game/core/meta_state_store.gd` | 存档内元进度数据的读写唯一层（数据读写原语，不含业务规则） | 写口原语族＋只读投影（消费方经 `save.meta_state.` 直连） | save_manager（序列化接线） | -| **MetaProgression**（autoload，C4） | `game/core/meta_progression.gd` | 元进度账本服务：钥石收束入账、营地消费定价与解锁判定的纯被动服务，零信号零外发；业务层（数据读写全经 MetaStateStore） | 写口族（天赋树/锻造/同调）＋解锁判定与读投影；四个 Autoload 中唯一有跨 Autoload 依赖（ConfigDB/SaveManager） | ConfigDB、SaveManager | -| **action_economy**（A3） | `game/core/action_economy.gd` | AP/RAP 账本、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 意图与通知布尔面（request_dig / request_stop / request_refresh / notify_* 族）＋预授权通道；ap/rap/phase 只读 | ConfigDB、EffectPort、B1 回发 | -| **variation**（A4） | `game/core/variation*.gd` | VariationTable schema 与 F1 候选池门控谓词 | variant_pool（门控三维）/ global_variant_row 访问器 | ConfigDB | -| **status_container**（B3） | `game/core/status_container.gd` | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 五 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB | -| **effect_engine** | `game/core/effect_engine.gd` | 零运行时可变状态的全同步解释器（架构原则 8）：事件由宿主在明确代码点位显式 dispatch 进件，命中序＝装载声明序，不是事件总线/事件循环 | rebuild / dispatch / validate_trigger_row ＋静态计数口；事件/事实/效果类型/算子四词表封闭＋树规则合成订阅六键 | ConfigDB 行集、EffectContext 引用束（四桶由宿主持有） | -| **settings/localization**（D6，愿景） | — | 设置项、翻译数据 | （契约规范源：`../../gdd/systems/表现与支撑/设置与本地化.md`） | ConfigDB | - -### 核心层 - -| 模块 | 文件 | 独占职责 | 对外封闭面 | 消费依赖 | -|---|---|---|---|---| -| **board_generator**（A1） | `game/core/board_generator.gd` | 生成算法（五阶段管线）、合法性谓词（clearable / R₀≠S / min_safe）、可推理率度量；生成姿态＝MVP 同步生成＋加载幕（WorkerThread 留扩展） | `generate(L, D, rng) -> Board`；度量独立入口 | ConfigDB；board_gen 封闭流（一次 open_stream＝一张图） | -| **minesweeper_rules**（A2） | `game/core/minesweeper_rules.gd` | 棋盘状态（已开集/封印集/小人位）、批次仲裁、install 四不变式 | `install_board` / `settle_batch`（唯一提交入口）/ 查询只读面 / preview_reveal 只读预览口 / retire_board；三事件封闭（cell_revealed / flag_judged / round_end，payload 字段封闭） | A1 Board 契约（class_name 数据契约）；A3 try_spend | -| **unit_container**（B2） | `game/core/unit_container.gd` | hero/enemy 单位实例（hp/atk/实例池） | spawn / query_alive / 动作与伤害面 | ConfigDB | -| **reward_economy**（B4） | `game/core/reward_economy.gd` | 格面资源身份映射（install 期预分配、换图映射消亡）、极性路由字典面、受理账面（装配期摇号归掷格件 RewardRoller） | 封闭 API：roll_board / query_identity / grant / grant_clear / retire_mapping / polarity_row / phase | ConfigDB；BattleFxHost 偏运合计查询（注入 Callable） | -| **helper_items**（A5） | `game/core/helper_items*.gd` | HelperItemTable、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口＋A4 counter_item_ids） | A2 / A4 / B4 | -| **CurioDeck**（A5） | `game/core/curio_deck.gd` | 三选一/商店共享令牌池、抽签、cap 库存与专长凭证判定唯一所有者（停点编排与兑付推进留 CurioStop） | draw_candidates 抽签 / consume 族池消耗 / cap_ok / 凭证判定 / stock 只读投影 | ConfigDB；注入 RngServiceCore（reward_pick 封闭流） | -| **ShopSession** | `game/core/shop_session.gd` | 关卡商店双模式（legacy 固定三件／pool 共享令牌池）的货架、定价、购买与刷新唯一宿主；账本/钱包经宿主 LevelRunner 注入共享引用 | 货架与定价只读面＋写入口；调用方经宿主公开成员 `shop` 直连 | ConfigDB；注入 RngServiceCore；pool 模式经注入 Callable 转 CurioDeck | -| **HeroStats** | `game/core/hero_stats.gd` | 冒险生命周期主角数值域唯一所有者：生命账与特性持有集、生效公式单点 | 构造注入；单写原语族＋只读投影 | ConfigDB；注入 GainJournal（只读）；AdventureRunner 创建 | -| **GainJournal** | `game/core/gain_journal.gd` | 统一冒险加算区与获得记录唯一所有者（三层结构：记录→明细→四轴汇总） | gain_bonus 单写原语；记录与汇总只读投影 | AdventureRunner 创建，注入各消费方 | -| **GpWallet** | `game/core/gp_wallet.gd` | 冒险局内货币唯一所有者（不入存档不入摘要） | gain / spend / clear 单写原语 | AdventureRunner 创建，宿主与商店注入读写 | -| **RefreshBank** | `game/core/refresh_bank.gd` | 三选一刷新三源账唯一所有者＋GP 付费刷报价公式（零停点态依赖，编排归 CurioStop） | 支出与余量原语＋报价公式；断点自交片段（refresh_stock / attune_refresh_y） | ConfigDB；注入 CurioStop 支出路径 | -| **AttuneLoadout** | `game/core/attune_loadout.gd` | 装备中的秘宝件对象集与同调充能唯一所有者（种行/补行改写时同步） | 构造注入；充能查询/消耗/按周期重置原语 | ConfigDB；TreasureItems 投放面；注入使用路径 | -| **CurioStop** | `game/core/curio_stop.gd` | 三选一停点编排唯一所有者（架构原则 9 本域承载）：停点三态、刷新编排、兑付方法族、零自动推进语义 | 开停点/刷新/兑付/放行谓词/交断点片段五组入口＋信号面（curio_choice_presented / curio_resolved） | ConfigDB；注入 CurioDeck、HeroStats、GainJournal、RefreshBank | -| **breakpoint_store** | `game/core/breakpoint_store.gd` | 存档断点组装与回放唯一承载：断点快照拼盘、回放回填、读侧策略分发 | `BREAKPOINT_FIELDS` 键登记单源（键名/策略标签/键序冻结） | 注入引用束 | - -### 功能层 - -| 模块 | 文件 | 独占职责 | 对外封闭面 | 消费依赖 | -|---|---|---|---|---| -| **battle_orchestrator**（B1，域文件集＝编排器＋`settlement/` 五段段类＋其拆件：BattleFxHost / RewardGrant / DamageController / BattleRefreshFlow / BoardInstaller / RoundCycle / BattleFacts / EffectPort / RewardRoller） | `game/core/battle_orchestrator.gd` 等 | 战斗域编排唯一宿主：战斗状态机与生命周期、A2 三事件订阅、结算五段驱动（授予/增益减益/战斗/衰减/判定，段序冻结于 SettlementTable.segment_order）、行发射基建、呈现投影；**战斗域全部跨系统调用权集中本域**（静态扫描域 S7 执法，文件集清单单点＝`game/tests/static_scan.sh`） | `begin_battle(encounter)`；窗口/刷新意图提交面；`level_clear()`；步骤流（输出契约）；[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) | B2/B3/B4 全调用面；A2 订阅；A1 generate；A3 代理+回发；D2 SettlementTable | -| **level_runner**（C1） | `game/core/level_runner.gd` | 关卡域生命周期：节点链推进、共享 B4、HP 携带、关卡末 level_clear；依赖构造注入一次给齐 | 节点推进接口；LevelTable（ConfigDB 跨表校验） | B1（直构接线战斗）、ConfigDB | -| **run_structure**（C2） | — | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （契约规范源：`../../gdd/systems/冒险循环/冒险结构.md`） | RngService.set_master_seed、C3/D2 | -| **difficulty**（C3） | — | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表 | 调参输出（经 D2 解析传递，禁反向调用生成） | ConfigDB、B1 对账输出、A1 报告 | -| **meta_progression**（C4，业务层） | `game/core/meta_progression.gd` | MetaTable、钥石账本、天赋树域、同调位槽位判定（业务规则与写口编排；数据原语归 MetaStateStore） | tree_* / forge_* / attune_* / settle_adventure / hero_override 族 | MetaStateStore、ConfigDB | - -### 呈现层 - -| 模块 | 文件 | 独占职责 | 对外封闭面 | 消费依赖 | -|---|---|---|---|---| -| **D1 HUD** | `game/presentation/main.gd`（组合根）＋三屏壳＋`views/` 视图单元族＋`ui_registry.gd` | 全部 Control/CanvasLayer；输入→意图翻译（**唯一提交路径＝settle_batch，不直调 A3**）；组合根＝信号接线与核心写调用唯一出口；views/ 各域呈现拆件的职责与接口归各件头注 | 组合根公开服务面与注册面句柄寻址合同（`main.ui.<域容器>.<句柄>`）归 main.gd / ui_registry.gd 头注承载 | A2 compute_move_path；A3 只读；B1 步骤流；ConfigDB display_name；**MEDIUM**：Control/CanvasLayer/draw_*/InputEvent/RichTextLabel | -| **组合根拆件** | `game/presentation/*_controller.gd` / `camp_shop_presenter.gd` | 代组合根执行核心写调用（冒险节点推进／营地购买与刷新／道具使用） | 各拆件写入口（仅组合根装配面可达；视图零直连） | 构造注入的核心写引用 | -| **HudPresenter** | `game/presentation/hud_presenter.gd` | 战斗屏数据投影＋文案拼装静态族（核心状态→呈现文案的全部翻译集中于此） | refresh 全量重查装配＋只读静态投影族 | 只走 `settlement.presentation_snapshot()` 成文快照面（禁链式穿透） | -| **board_resolvers** | `game/presentation/board_resolvers.gd` | 棋盘每格渲染数据只读解析回调四函数（与无态静态投影族职责互斥） | 构造注入产出绑定 Callable 供组合根接线 | ConfigDB / 结算活态取值 Callable | -| **battle_presentation**（B5，垂直切片后） | — | 结算动画 / 伤害数字 / 战斗舞台 | （契约规范源：`../../gdd/systems/战斗循环/战斗表现.md`——前置「战斗表现美术测试」锁双舞台陷阱） | B1 步骤流、D1；**MEDIUM**：AnimationPlayer/Tween | -| **audio**（D4，Alpha） | — | 音频挂点 | 挂点＝B1 明细行类型流（负反馈聚合——单结算至多一次） | B1 流水 | -| **tutorial**（D5，Alpha） | — | 教学条目 | 口径来源＝A2/A3/B3/B1 各教学条目 | 各上游 | +| 目录 | 层级作用 | 该层约束属性 | +|---|---|---| +| `game/core/` | 全部玩法逻辑的承载（配置、RNG、存档域件、棋盘生成、排雷规则、经济与账本、效果引擎、战斗编排、关卡与冒险域件）——依赖逻辑层级内分基础/核心/功能三段，见分层图 | 纯逻辑：零 Control/场景引用、构造注入、fail-fast、`--headless --script` 完整可跑、玩法数值零字面量（读 `game/data/tables`）、随机只经封闭流 | +| `game/core/settlement/` | 领域子目录——战斗结算五段段件（领域大到内部再需要一层时切分的在案先例） | 同 core；段类可直接 new() 单测、段类对编排器零引用 | +| `game/presentation/` | 呈现层——全部 Control/CanvasLayer、输入→意图翻译、组合根装配 | 视图零核心写调用（信号外发为主）、组合根＝核心写调用唯一出口、呈现数据只走成文快照面；引擎风险域对照 breaking-changes | +| `game/data/` | 数据承载——玩法数值表（tables/*.tres）与字段契约（schemas/*.gd），对应基础层 D2 数据配置 | 数值单一事实源；表值直接改变游戏运行结果 | +| `game/tests/` | 测试域——冒烟/单元/系统三闸承载 | 依赖只经 autoload 边界与场景契约两类入口；禁反向依赖呈现层实现内部 | +| `game/probe/` | 探针域——场景级探针与取证探针 | 同测试域边界；在闸件与手动测量件两分 | +| `game/sim/` | 测量域——MC/调参/数值验证驱动件 | 不入 CI、用户手动发起、随机显式定种 | **依赖单向性**：上层可消费下层，禁止反向（C3 禁调用 A1 生成、D1 不直调 A3、A2/B3/B4 零相互直调）。全项目唯一回边＝A2 事件订阅面。 @@ -253,28 +206,6 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无 4. 续玩钮可见态恒等于断点在档态（双向）。 5. 闲时会话已在树（`run_scope` 永非 null 契约的启动侧证明）。 6. 调试浮窗 boot 不自动开（菜单优先）＋调试入口全局浮层角标 boot 可见。 - ---- - -## API 边界 - -> 完整 API 面（含封闭枚举负空间、布尔受理口径、输入×相位矩阵）以各 GDD AC 前言为**规范源**——本节列边界契约与不变式，实现须与 GDD 逐字一致；冲突时以 GDD 为准并走接口漂移修订。 - -| 边界 | 契约要点 | 调用方必须遵守的不变式 | 模块保证 | -|---|---|---|---| -| D1 → A2 | 意图经 `settle_batch(intents)` 提交；不直调 A3 | 单意图帧收集；stop 经批次委托 | 语义序仲裁 + voided 零副作用 | -| A2 → A3 | 挖/插/拔＝先棋盘面判定后 `try_spend`；A2 不可自行扣减 | 相位判定两侧一致（同一矩阵） | 原子事务（余量+扣减+仲裁一体） | -| A2 → 下游 | 只外发三事件，payload 字段封闭（digit 恒真透传 / reward_eligible / variant_ids） | 增删事件＝接口漂移 | 发射面封闭 + 规范序 | -| B1 → B2/B3/B4 | 全调用面集中 B1；调用序钉死（按摇定技能行兑现→apply_damage→commit_action；先兑付后衰减；段内伤害序＝主角先手→逐敌还手→地图账殿后） | 禁第二调用方（静态扫描域 S7：API 符号命中文件 ⊆ B1 文件集） | 恰一次编排纪律（roll_board/decay/清理全序） | -| B1 ↔ A3 | 编排期代理 `request_refresh`（玩家意图，禁 RAP 满自动刷）；回发 next_round_mode/battle_over | stopped/ap_exhausted 未刷新回发 new_board＝违约 fail-fast | 刷新受理契约（同 Waiting 多次合法） | -| 各系统 → D2 | ConfigDB 类型化属性单点读取 | 禁绕过 ConfigDB load 表、禁缓存副本、禁玩法数值字面量、禁 randomize()/自建 RNG | 校验双通道 + fail-fast 致命 | -| A1 → A2 | Board 产物 class_name 数据契约 | install 四不变式校验（violation＝拒绝 + 五类诊断枚举） | 生成期合法性闸（R₀≠S / clearable / min_safe） | -| A1 ↔ B1 | attempt 边界非 scope 事件；actuals p10 为对账输入（非 target 参数） | 编排不把重试当取号 | 生成期指标集输出（实测可推理率 / 实际雷数与安全格数 / 重试次数 / 降级与非法产物标记） | -| B4 → B3 | buff 类经 B1 调 apply_effect（B4 零跨系统读、零直接接口） | 满层拒绝＝零兑付 + 明细行（无折算） | 授予时数值快照（抗热重载） | -| B1 → D1 | [步骤流行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（基础行型＋扩展行两层封闭 + 公共字段 type/source_class/origin_cell/round_index/display_name/value/highlight? + 特有字段 target/effect_id/pool_value） | 无来源行＝断言失败；呈现侧禁按行序重演 B2 状态机 | 可回放步骤流（同种子逐行相同） | - -**引擎类型核验注记**：接口使用的引擎类型＝Resource / .tres（D2 全表）、RefCounted（容器类）、Signal/Callable（事件载体）、Control/CanvasLayer/Drawing（D1）、SceneTree headless 协议（测试）——均属 4.x 基线稳定面；4.7 Control 域增量已在 breaking-changes.md 登记，D1 采纳前对照核实。 - --- ## 架构原则 diff --git a/待办清单.md b/待办清单.md index cd3574e9..3291bdd8 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,6 +2,12 @@ 本清单是流水线的唯一登记处：以后才做的事在此登记一条，随流水线段推进改状态，做完整条删除（条目记进度，不是各段的开工前置）；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 +#### 架构文档收敛第二批——依赖规则形态（2026-11-09 登记，来源=会话提及） + +**实况**：方案经用户批准（模块归属表目录化+API 边界表删除+29 处判据锚迁 GDD/规约规范源+四文档引用改指+架构图同步）；分层依据＝依赖方向、目录＝层级承载、同目录同层级同约束。证据＝design/engineering/doc-conventions.md 架构事实唯一源行（只写约束面条款）+用户 2026-11-09 会话裁决。 +**改动面**：文档＋游戏代码＋工具代码 +**状态**：待执行 + #### 未决问题迁移——轮内刷新数值连锁重算（2026-11-07 登记，来源=批次移交） **实况**：原 architecture.md「未决问题」QQ-04（git 历史可考，架构收窄批迁出）。清图支配性条款⑤的轮内刷新数值连锁重算，判据＝真人刷图行为获取期望。