296 lines
31 KiB
Markdown
296 lines
31 KiB
Markdown
# Dungeon Sweeper — Master Architecture
|
||
|
||
## Document Status
|
||
|
||
- Version: 1.3
|
||
- Last Updated: 2026-09-26（战斗舞台 Node2D 迁移 Phase B：D1 层表 BattleStageView 形态注记——引 ADR-0006；Phase A 注记 2026-09-23）
|
||
- Engine: Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||
- Review Mode: solo（`production/review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||
- GDDs Covered: game-concept · game-pillars · systems-index · d2-data-config · a3-action-economy · a4-terrain-variation · b3-status-effect · a1-board-generation · a2-minesweeper-rules · b2-enemy-system · b4-reward-item-economy · b1-settlement（12 份；A5/C1–C4/B5/D3–D6 未设计，按 systems-index 依赖分层预留）
|
||
- ADRs Referenced: 无（0 份现存）——本文档 Phase 5/6 列出的实现期裁决项即为首批 ADR 候选
|
||
- Implementation Evidence: 垂直切片 `game/`（2026-09-10 起，冒烟 88/88、三 UI 探针 PASS）——本文档的分层/所有权/数据流均经切片实现验证，非纯纸面设计
|
||
- Technical Director Sign-Off: 2026-09-12 — APPROVED WITH CONDITIONS（条件：Required ADRs 于正式工程骨架搭建前定稿；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||
- Lead Programmer Feasibility: SKIPPED — Solo mode
|
||
|
||
---
|
||
|
||
## Engine Knowledge Gap Summary
|
||
|
||
- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `docs/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。
|
||
- 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。
|
||
- 三类必须入编码纪律的引擎事实（详见 `docs/engine-reference/godot/current-best-practices.md`）：
|
||
1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。
|
||
2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。
|
||
3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。
|
||
- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地，随 ADR-0002/0003 裁决时对照引擎文档核实。
|
||
|
||
---
|
||
|
||
## System Layer Map
|
||
|
||
20 系统按 systems-index 依赖分层表（systems-design 门禁已评审）映射到标准五层。切片实现已验证该分层（core/ 纯逻辑零 UI 依赖 headless 可跑、presentation/ 组合根模式）。
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ PRESENTATION LAYER │
|
||
│ D1 HUD 与界面框架 (MVP) · B5 战斗表现 (切片后) │
|
||
│ D4 音频 (Alpha) · D5 教学引导 (Alpha) │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ FEATURE LAYER │
|
||
│ B1 战斗结算编排 (MVP) · C1 关卡节点地图 (切片已含 lite) │
|
||
│ C2 冒险结构 · C3 难度曲线 · C4 元进度 (Alpha) │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ CORE LAYER │
|
||
│ A1 扫雷棋盘生成 · A2 排雷玩法规则 · B2 敌人系统 │
|
||
│ B4 地图战斗资源 · A5 扫雷秘宝 (垂直切片) │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ FOUNDATION LAYER │
|
||
│ D2 数据配置与数值表 · A3 行动经济 · A4 地形变异 │
|
||
│ B3 增益/状态系统 · D3 存档序列化 (Alpha) · D6 设置/本地化│
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ PLATFORM LAYER │
|
||
│ Godot 4.7.2 引擎 API 面（GDScript / Resource / │
|
||
│ SceneTree / Control / InputEvent）——无游戏系统 │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| 系统 | 层 | 里程碑 | headless 约束 | 引擎风险域 |
|
||
|---|---|---|---|---|
|
||
| D2 数据配置 | Foundation | MVP | ✅ 完整可跑 | LOW（Resource/.tres 基线稳定） |
|
||
| A3 行动经济 | Foundation | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| A4 地形变异 | Foundation | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B3 状态系统 | Foundation | MVP | ✅ 完整可跑 | LOW（RefCounted 纯逻辑） |
|
||
| A1 棋盘生成 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑；性能姿态归 ADR-0005） |
|
||
| A2 排雷规则 | Core | MVP | ✅ 完整可跑 | LOW（零表读取零 UI） |
|
||
| B2 敌人系统 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B4 地图战斗资源 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B1 战斗结算编排 | Feature | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑；事件载体归 ADR-0001） |
|
||
| C1 关卡节点地图 | Feature | 垂直切片（lite 已入切片） | ✅（切片 level_runner 先例） | LOW |
|
||
| C2 冒险结构 | Feature | 垂直切片 | ✅ | LOW |
|
||
| C3 难度曲线 | Feature | 垂直切片 | ✅ | LOW |
|
||
| C4 元进度 | Feature | Alpha | ✅ | LOW |
|
||
| D1 HUD | Presentation | MVP | ❌（UI 层——场景级探针测试承载） | **MEDIUM**（Control/Input/文本域） |
|
||
| B5 战斗表现 | Presentation | 垂直切片 | ❌ | **MEDIUM**（Animation/Tween/渲染） |
|
||
| D4 音频 / D5 教学 | Presentation | Alpha | 部分 | LOW-MEDIUM |
|
||
| D3 存档序列化 | Foundation | Alpha | ✅ | LOW |
|
||
| D6 设置/本地化 | Foundation | 完整愿景 | ✅ | LOW |
|
||
|
||
**MVP 关键路径**（切片已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。
|
||
**依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。
|
||
|
||
---
|
||
|
||
## Module Ownership
|
||
|
||
> 命名遵循 `docs/code-conventions.md`：领域命名、禁 ID 前缀、头注溯源行（实现 GDD：design/gdd/…）。切片已按此规范完成领域命名批。
|
||
|
||
### Foundation 层
|
||
|
||
| 模块 | Owns（独占） | Exposes | Consumes | 引擎 API |
|
||
|---|---|---|---|---|
|
||
| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机 | 类型化属性读取；`load_tables(root, collect_only)`；`resolve()`（R1 floor）；debug override；`set_reload_gate()`；诊断收集器 | 无（Foundation 顶点） | Resource/.tres 加载、autoload 生命周期——LOW |
|
||
| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流：board_gen / reward_roll；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 |
|
||
| **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 8 API 全布尔面：notify_round_start / request_dig / request_flag_place / request_flag_pull / request_stop / request_refresh / notify_settlement_done / notify_combat_end；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；B1 回发 next_round_mode/battle_over | 无 |
|
||
| **variation 定义**（A4） | VariationTable schema（现行 7 行：六 region + skewed_veins 一 global——全局作用域变异首发批 2026-10-04）与 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） | 无 |
|
||
| **status_container**（B3） | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 5 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB（StatusEffectTable） | 无（RefCounted） |
|
||
| **save_system**（D3，Alpha） | 存档格式与版本比较 | （未设计——契约锚：SCHEMA_VERSION + master_seed + 各流 scope 计数器快照，须在无在飞 open_stream 实例时切出） | ConfigDB、RngService 只读计数器 | FileAccess——LOW |
|
||
| **settings/localization**（D6，愿景） | 设置项、翻译数据 | （未设计） | ConfigDB | 无 |
|
||
|
||
### Core 层
|
||
|
||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||
|---|---|---|---|---|
|
||
| **board_generator**（A1） | 生成算法（五阶段管线）、BoardGenTable 回填、生成期指标集、合法性谓词（clearable / R₀≠S / min_safe）、可推理率度量（metric_version） | `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)`（唯一提交入口）；try_dig / try_flag_place / try_flag_pull / try_move（便捷形）；`compute_move_path(cell)` 只读；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end / 相位 | 无（零表读取、零 UI——切片实证） |
|
||
| **unit_container**（B2） | hero/enemy 单位实例（hp/atk/实例池：池快照+冷却+摇定动作+保底计数）、行值快照 | spawn / query_alive / rollable_skills / special_skills / set_pending_action / pending_action / basic_streak / commit_action / tick_cooldowns / apply_damage / heal / default_target / ambush_grant_plan / despawn_all（2026-09-16 敌人技能池批：query_beat/query_attack/advance 随行为环退役——architecture.md 旧口径残留归 API 面 ADR 批整表复核） | 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 / equivalence_supply / phase / weighted_pick；另有 is_mapped 静默布尔投影（批量工具用） | ConfigDB（RewardTable）；reward_roll 流（scope = 每次 install 批） | 无 |
|
||
| **helper_items**（A5，垂直切片） | HelperItemTable、探测显影语义 | （未设计——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 |
|
||
|
||
### Feature 层
|
||
|
||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||
|---|---|---|---|---|
|
||
| **battle_orchestrator**（B1） | 段序骨架（七段结构冻结）、轮 facts 缓冲、可回放步骤流、[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（15 类行 + 字段分层）、条款③⑤闭合对账、**战斗域全部跨系统调用权** | `begin_battle(encounter)`；窗口/刷新意图提交面（扮演 D1）；`level_clear()`；步骤流（输出契约） | B2/B3/B4 全调用面（**唯一调用方**）；A3 request_refresh 代理 + 回发；A2 install/retire + 三事件订阅；A1 generate（attempt 非 scope 事件）；D2 SettlementTable + set_reload_gate | 无（零随机、禁 await——切片 88 冒烟实证可回放） |
|
||
| **level_runner**（C1-lite，切片已建） | 关卡域生命周期（节点链推进、共享 B4 + HP 携带、关卡末 level_clear） | 节点推进接口；LevelTable（`level.tres`——节点 enum {battle,reward,rest,boss}、末节点必须 Boss、ConfigDB 跨表校验⑧） | B1 begin_battle、B4 grant_node_active、ConfigDB LevelTable | 无 |
|
||
| **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （未设计） | RngService.set_master_seed、C3/D2 | 无 |
|
||
| **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 |
|
||
| **meta_progression**（C4，Alpha） | MetaTable、钥石/天赋 | （未设计） | D3、C2、ConfigDB | 无 |
|
||
|
||
### Presentation 层
|
||
|
||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||
|---|---|---|---|---|
|
||
| **D1 HUD**（切片 lite 已拆 9 单元：BoardView / HUDView / HudPresenter / BattleLogView / ItemWindowOverlay / NodeOverlay / LevelStripView / TunePanel / UiKit + 组合根 main.gd） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——ADR-0006 棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26）、输入→意图翻译（**唯一提交路径 = settle_batch，不直调 A3**）、呈现义务台账（A2×6 / B2×4 / B3×4 / B4×5 / B1×3） | 视图单元接口（信号外发、setter 只读注入） | A2 compute_move_path / ActionOutcome；A3 ap/rap；B1 步骤流行协议（数据源）；ConfigDB display_name | **MEDIUM**：Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目（CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化） |
|
||
| **battle_presentation**（B5，垂直切片后） | 结算动画 / 伤害数字 / 战斗舞台 | （未设计——前置"战斗表现美术测试"锁双舞台陷阱） | B1 步骤流（回放脚本源）、D1 | **MEDIUM**：AnimationPlayer（String→StringName 变更）/ Tween |
|
||
| **audio**（D4，Alpha） | 音频挂点 | （挂点 = B1 明细行类型流；负反馈聚合——单结算至多一次） | B1 流水 | AudioStreamPlayer（4.7 area_mask 默认 1→0 注意） |
|
||
| **tutorial**（D5，Alpha） | 教学条目 | （口径来源：A2/A3/B3/B1 各教学条目） | 各上游 | 无 |
|
||
|
||
**依赖单向性**：上层可消费下层，禁止反向（C3 禁调用 A1 生成、D1 不直调 A3、A2/B3/B4 零相互直调）。全项目唯一回边 = A2 事件订阅面。
|
||
|
||
---
|
||
|
||
## Data Flow
|
||
|
||
### 1. 帧更新路径（2D 回合制：无逐帧玩法逻辑）
|
||
|
||
```
|
||
Input（鼠标）→ D1 输入翻译 → 意图对象 → A2.settle_batch（唯一提交入口）
|
||
→ A3.try_spend（原子扣减）→ A2 棋盘效果（挖/连锁/旗/移动）→ 三事件外发
|
||
→ [棋盘渲染：D1 BoardView 按事件增量重绘；无事件帧 = 静态 + 动效]
|
||
→ 轮次结束 → A3 Waiting → B1 结算编排（段序七段）→ 明细步骤流 → D1 结算屏逐行呈现
|
||
```
|
||
|
||
- 回合制下每帧只做：输入采样、呈现刷新、动效推进——**玩法状态只在意图事务内变更**（单意图帧输入收集：stop 点击终结当帧）。
|
||
- 无跨线程玩法数据流（Godot 主线程假设，D2 EC13）；A1 生成若引入 WorkerThread 须走 ADR-0005 裁决（join 先于任何快照切出）。
|
||
|
||
### 2. 事件/信号路径（系统间通信，无紧耦合）
|
||
|
||
```
|
||
A2 ──cell_revealed / flag_judged / round_end(棋盘路径)──▶ B1（轮 facts 缓冲）
|
||
A3 ──round_end(stopped 直发，payload 同构)──────────────▶ B1
|
||
B1 ──notify_settlement_done(next_round_mode) / notify_combat_end──▶ A3
|
||
B1 ──apply_effect / apply_damage / grant / stock / advance...──▶ B3/B2/B4（唯一调用方）
|
||
B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)──▶ A1
|
||
D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name
|
||
```
|
||
|
||
- **载体裁决待 ADR-0001**：切片事实 = 组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；推荐沿用（单线程回合制，KISS），autoload 全局事件总线为否决倾向。
|
||
- 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。
|
||
|
||
### 3. 存档/读档路径（MVP 无存档；契约已锁）
|
||
|
||
- MVP 无元进度持久化（C4/D3 归 Alpha）。**已锁契约**：续玩/复盘快照 = master_seed + 各流 scope 计数器 + 意图序列 + 窗口选择序列；快照切出须发生在无在飞 `open_stream` 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）。
|
||
- 可回放性已实证：切片冒烟同种子双跑步骤流逐行相同（B1 AC-33 前身）。
|
||
- D3 Alpha 期按此契约设计格式；SCHEMA_VERSION 高版本拒读。
|
||
|
||
### 4. 初始化顺序
|
||
|
||
```
|
||
进程启动
|
||
→ autoload 实例化：ConfigDB → RngService（顺序固定；战斗编排器为普通类、由组合根按局实例化——切片形态）
|
||
→ ConfigDB._ready()：load_tables 加载 + 校验（致命通道；失败 = 构建中止 + 错误清单）
|
||
→ 主场景（D1 组合根）装配视图单元 + 信号接线
|
||
→ C2 begin_run：RngService.set_master_seed()（唯一接线方；两流计数器全零前提）
|
||
→ B1.begin_battle(encounter)：set_reload_gate(true) → B3 开域 → B2 spawn → A2 install_board(A1.generate) + B4 roll_board（恰一次）→ A3 notify_round_start
|
||
→ 挖掘循环 …… → battle_over 清理序列 → set_reload_gate(false)
|
||
→ 关卡末：level_clear()（clear_inventory 恰一次 + 快照计数）
|
||
```
|
||
|
||
---
|
||
|
||
## API Boundaries
|
||
|
||
> 完整 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；调用序钉死（query_attack→apply_damage→advance；先兑付后衰减） | 禁第二调用方（静态扫描域：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#明细流水每一行都能指回你刚才的哪一步棋)（15 类封闭枚举 + 公共字段 type/source_class/origin_cell/round_index/display_name/value/highlight? + 特有字段 target/effect_id/pool_value） | 无来源行 = 断言失败；呈现侧禁按行序重演 B2 状态机 | 可回放步骤流（同种子逐行相同） |
|
||
|
||
**引擎类型核验注记**：接口使用的引擎类型 = Resource / .tres（D2 全表）、RefCounted（容器类）、Signal/Callable（事件载体，ADR-0001）、Control/CanvasLayer/Drawing（D1）、SceneTree headless 协议（测试）——均属 4.x 基线稳定面；4.7 Control 域增量（offset_transform_* 等）已在 breaking-changes.md 登记，D1 采纳前对照核实。
|
||
|
||
---
|
||
|
||
## ADR Audit
|
||
|
||
**现存 ADR：0 份**（`docs/architecture/` 本文档为首个产物；此前架构约束由 GDD 门禁评审 + CLAUDE.md + code-conventions 事实承载）。
|
||
|
||
### 已锁决策盘点（GDD 层已定稿，不重复立项 ADR）
|
||
|
||
| 决策 | 锁定来源 |
|
||
|---|---|
|
||
| GDScript 单语言；autoload = ConfigDB + RngService（定名勿改） | technical-preferences + D2 GDD |
|
||
| 全部玩法数值 .tres 单一事实源；零字面量；R1 floor 解析；fail-fast 双通道 | D2 Core Rules 1–8 |
|
||
| RNG 封闭流 + scope 派生（R2 黄金向量）；可回放 = 硬承诺 | D2 R2 + B1 Core Rule 15 |
|
||
| A2 纯规则引擎（零随机/零表读取/零 UI）+ 三事件面封闭 | A2 Core Rule 1/2 |
|
||
| B1 编排唯一性 + 七段段序骨架 + 明细行协议 | B1 Core Rule 1/4/14 |
|
||
| 多敌 side-wide / 出招确定性（技能池批改型：零随机纪律保持、开轮摇号走 behavior_roll 封闭流）/ 固定顺位 / 伏击 cap=4 | B2（2026-09-09 用户拍板；2026-09-16 技能池批改型） |
|
||
| 奖励五值两类交付轴 / install 预分配 / 关卡域库存 / 窗口单件制 | B4（2026-09-11 用户裁决批） |
|
||
| weaken 锚 F0 瞬时当量 / 条款①③⑤闭合对账 owner = B1 | B1 F0–F5 |
|
||
| 领域命名禁 ID 前缀 / 组合根模式 / 呈现层契约成文 | CLAUDE.md + docs/code-conventions.md（切片教训批） |
|
||
|
||
### GDD 登记的"实现期 ADR 裁决项"汇总（= Required ADRs 的来源）
|
||
|
||
A2 OQ2（事件外发载体）· B1 OQ1（事件总线载体，与 A2 OQ2 同一裁决）· A1 OQ2/OQ3（生成性能姿态 + 度量独立入口）· B2 OQ1（query_attack/ambush_grant_plan 两 face 归属）· B2 OQ5（HeroTable 单行校验落点）· B2 OQ9（零伤害死局跨字段护栏落点）· D2 OQ1（gdUnit4 取舍）· technical-preferences（渲染器选择）· 切片新增正式化批（轮内刷新方案 A / RewardSupplyController / LevelTable / grant_node_active / clear_blast——GDD+registry 修订义务在切片 README）。
|
||
|
||
### Traceability Coverage Check
|
||
|
||
Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在）；按覆盖载体分层：
|
||
|
||
| 覆盖载体 | TR 数 | 说明 |
|
||
|---|---|---|
|
||
| ✅ 本架构文档（分层/所有权/数据流/API 边界）+ GDD 契约 | 46 | 数据/RNG/核心行为/编排协议类——已锁且切片实证，无需 ADR |
|
||
| 🔶 待 ADR 裁决 | 12 | 引擎/测试/实现形态类：TR-gc-008（渲染器）、TR-a1-011/012（生成姿态）、TR-d2-014/016（测试载体）、TR-a3-004+TR-b1-001/002（事件载体）、TR-b2-005/006（face 归属）、TR-d2-010+TR-gc-002（D3 契约正式化） |
|
||
| ⏳ 未设计系统预留 | 5 | A5/C1–C4/D3 关联 TR（随各系统 GDD 立项） |
|
||
|
||
**结论：0 条孤儿需求**——46 条由本文档+GDD 承载、12 条待 ADR（见下）、5 条随未设计系统。**2026-09-12 更新：ADR-0001~0004（Foundation 四项）已落定 → 正式工程骨架解冻**；ADR-0005~0008 随对应系统开工前裁决（切片代码可作为参考实现，生产化迁移待 ADR-0008 正式化批）。
|
||
|
||
---
|
||
|
||
## Required ADRs
|
||
|
||
### 必须在正式编码开始前（Foundation 裁决）——✅ 已全部落定（2026-09-12，solo 授权代决，godot-specialist 校验通过）
|
||
|
||
1. **✅ ADR-0001 `event-bus-and-orchestration-carrier`**（`adr-0001-event-bus-and-orchestration-carrier.md`）：组合根直连 signal 接线 + B1 Waiting 相位触发；autoload 全局事件总线否决。specialist 增补两条静态规则（方法 Callable only / 发射者禁反向引用）。
|
||
2. **✅ ADR-0002 `renderer-and-window-config`**（`adr-0002-renderer-and-window-config.md`）：gl_compatibility（绕开 D3D12 新驱动线）；基座 1280×800 + canvas_items + expand 显式落盘。
|
||
3. **✅ ADR-0003 `scene-structure-and-board-rendering`**（`adr-0003-scene-structure-and-board-rendering.md`）：autoload 仅 {ConfigDB, RngService}；core RefCounted / presentation 九单元组合根；**棋盘渲染 MVP 沿用切片逐格控件形态**（specialist 纠正：切片并非自绘 _draw——迁移登记为 D1 候选工作项含探针改造）；CJK 字体随包为硬性前置。
|
||
4. **✅ ADR-0004 `test-carrier-and-ci`**（`adr-0004-test-carrier-and-ci.md`）：双载体 + 静态扫描域 S1–S8（specialist 增补 S2 全局 rand* 禁令 / S5 core 禁裸引用 autoload 标识符）+ CI 外部超时；gdUnit4 deferred（D2 OQ1 关闭形态）。
|
||
|
||
实现级立场已登记 `docs/registry/architecture.yaml`。
|
||
|
||
### 相关系统开工前应有
|
||
|
||
5. `/architecture-decision "board-generation-performance"` → ADR-0006：A1 生成性能与异步化（F2c 常数 C 定稿；切片证据 = 10×10/12×12 同步生成可接受——推荐 MVP 同步+加载幕，WorkerThread 留扩展）；度量独立入口确认（切片已实现三入口）。
|
||
6. `/architecture-decision "unit-api-face-ownership"` → ADR-0007：B2/B1 两 face 归属（query_attack / ambush_grant_plan）+ HeroTable 单行校验落点。
|
||
7. `/architecture-decision "zero-damage-guard-locus"` → ADR-0008：零伤害死局跨字段/跨表护栏落点（推荐落 D2 跨表校验——切片 LevelTable 校验⑧先例）。
|
||
8. `/architecture-decision "slice-mechanism-formalization"` → ADR-0009：切片新增机制正式化批（轮内刷新方案 A / RewardSupplyController / LevelTable / grant_node_active / clear_blast）——GDD+registry 接口漂移修订的 ADR 化登记。
|
||
|
||
### 已落定（2026-09-12 追加）
|
||
|
||
0. **✅ ADR-0005 `save-contract-and-schema-versioning`**（`adr-0005-save-contract-and-schema-versioning.md`）：Foundation 层收口——SCHEMA_VERSION 比较归属 + RNG 快照切点契约 ADR 化（TR-d2-010 / TR-gc-002），Foundation 零缺口闭合。
|
||
|
||
### 可推迟
|
||
|
||
- ADR-0010 A1 EC5 运行期熔断（连续降级确定性回退已知好种子）
|
||
- ADR-0011 B5 战斗舞台（棋盘上 vs 独立场景）——"战斗表现美术测试"后裁决
|
||
- ADR-0012 A5 探测显影接口
|
||
- ADR-0013 D3 存档格式（RNG 快照契约已由 ADR-0005 锁定，格式归 Alpha）
|
||
- C2/C3/C4 结构性决策随各系统 GDD 立项
|
||
|
||
---
|
||
|
||
## Architecture Principles
|
||
|
||
1. **Core 纯逻辑、headless 完整可跑**——Core/Feature 玩法逻辑零 Control/场景引用、零 UI 依赖；`--headless --script` 可跑完整战斗（D2 Rule 7 工程债；切片 88 冒烟实证）。输入是意图对象、输出是事件流/步骤流，D1 与输入设备皆可替换。
|
||
2. **单一事实源与零字面量**——玩法数值只存在于 `data/tables/*.tres`，经 ConfigDB 类型化单点读取；代码零玩法数值字面量；参数禁止跨系统复制（D2 Rule 1/2）。
|
||
3. **封闭 RNG 与可回放**——玩法代码零随机；一切随机经 RngService 具名封闭流（增流走 P1 评审）；同种子 + 同输入序列 ⇒ 事件流/步骤流逐位相同（结算禁 await，B1 承重约束）。
|
||
4. **编排唯一性与事件面封闭**——战斗域跨系统调用权集中 B1（静态扫描承载）；A2 三事件面封闭即负空间；每格受理、每雷转化、每次推进、每次衰减各恰一次。
|
||
5. **fail-fast + 零特判**——数据错误一律致命中止（错误数值上线比崩溃更伤）；API 非法 = 拒绝 + 诊断不静默；变异零运行时分支（行为差异全部由生成端约束保证）。
|
||
6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边 = A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象（切片 1100 行 main.gd 反面案例 → 9 单元拆分）。
|
||
7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷 ①②④⑤ 教训沉淀）。
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
| ID | Summary | Priority | Resolution Path |
|
||
|----|---------|----------|-----------------|
|
||
| QQ-01 | 渲染器选择（Forward+ vs gl_compatibility）与项目窗口基线 | High | ADR-0002（正式骨架前） |
|
||
| QQ-02 | 事件总线载体与 A2 事件捕获测试 API | High | ADR-0001（正式骨架前） |
|
||
| QQ-03 | gdUnit4 是否引入并迁移冒烟用例 | Medium | ADR-0004（可推迟到正式 CI 期；D2 OQ1） |
|
||
| QQ-04 | 轮内刷新数值连锁（清图支配性条款⑤ / 真人刷图行为获取期望）重算 | Medium | playtest 实测 + ADR-0008 正式化批 |
|
||
| QQ-05 | 战斗末可选类"j==0 补发 1 件"兜底是否采纳（切片遗留待办） | Medium | playtest + B4 GDD 修订批 |
|
||
| QQ-06 | 可选类退出格子池后 buff 频率被动上升（44%→59%）的难度对冲杠杆（敌 HP / 权重 / 幅度） | High | C3 调参 + 切片数据复测 |
|
||
| QQ-07 | 标错惩罚（A2 OQ1：候选敌方伏击+1；hit=false 无去重的不对称裁决） | Medium | 原型小补丁实测会话（可与 v3 终验合并） |
|
||
| QQ-08 | B5 双舞台陷阱（战斗发生在棋盘上还是独立场景） | Low（B5 前） | 战斗表现美术测试 → ADR-0010 |
|
||
| QQ-09 | C3 消费 B1 对账输出的事实依赖回写 systems-index | Low | C3 GDD 定稿时 |
|
||
| QQ-10 | `.claude/docs/director-gates.md` 缺失（TD-ARCHITECTURE/LP-FEASIBILITY 判据无载体） | Low | 补建 gate 定义文件或维持 solo/lean 模式约定 |
|