docs: ADR 体系废除 + architecture.md 确立为架构唯一事实源（2026-10-15 用户令：决策记录归 git commit log，不另存决策文档）
- 删除 design/dev/architecture/adr-0001~0007 共 7 份文件（内容留 git 历史可查） - architecture.md：删「ADR 审计」「ADR 立项清单」两节；清除全文 ADR-000X 注记、QQ 表/S 表 ADR 引用；未决表关闭已落定项（QQ-01/02/03），立项清单在途事项转登记 QQ-11~14；补 A1 生成姿态事实、autoload 四件清单、board_generator 性能姿态；文档状态立「事实源地位」条 - CLAUDE.md：恢复 RNG 单点硬性红线（去 ADR-0007 引用）；新增「架构事实唯一源」红线；规范导航架构行标注唯一事实源 - doc-conventions：§5 增「架构事实唯一源」行；§11 活文档清单补架构文档 - registry：architecture.yaml 删 18 处 adr 字段、autoload_set 补 SaveManager/MetaProgression、board_rending 更新为 Node2D 已落地事实；entities.yaml 12 处引用清除 - game/ 代码注释约 60 处清 ADR-000X 引用（事实与日期保留）；豁免标记 ADR-0007-exempt → rng-seed-exempt（main.gd/static_scan.sh/architecture.md/06/iter27 五处同步） - GDD/qa 实现报告/research 卡片/roadmap/tests README 引用全清；死链校验 1206 链接 0 死链、gdd_lint 0 不通过 - 代码中 adr/adr5 等为 adventure_runner 既有局部变量名（非 ADR 引用），未动
This commit is contained in:
DKChan committed
1 parent
f22adb5564
commit
6c2dbc37c1
73 files changed
+193
-1118
No files matched your search
@@ -1,129 +0,0 @@
|
||||
# ADR-0001: 事件总线与编排载体（Event Bus & Orchestration Carrier）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；用户迭代期可随时推翻重议——推翻时须走本 ADR 修订 + 下游 AC 连锁复核）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting（Signal/Callable/生命周期） |
|
||||
| **Knowledge Risk** | LOW（4.x 基线稳定；4.5–4.7 变更清单零命中，godot-specialist 校验通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices）；godotengine/godot#6360 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（切片 88/88 冒烟已实证：双源 round_end 汇聚、可回放步骤流） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | ADR-0003（场景结构引用本 ADR 的接线纪律）；A2/B1 全部事件序类 AC 从纸面契约转为可执行 |
|
||||
| **Blocks** | 正式工程骨架搭建（架构文档 Required ADRs 条件） |
|
||||
| **Ordering Note** | 与 ADR-0008（切片机制正式化）并行无冲突；B1 结算触发语义以本 ADR 载体承载 |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
A2（三事件外发）、A3（stopped 直发 round_end，双发射源）、B1（结算触发 = Waiting 相位编排点、不依赖事件到达序）之间的信号载体需要一个落地形态——GDD 层只定行为契约（A2 OQ2 / B1 OQ1 均登记为"实现期 ADR 确认项"）。
|
||||
|
||||
### Constraints
|
||||
- 单线程回合制（D2 EC13）；Core 层零 UI 依赖、headless 可跑（D2 Rule 7）
|
||||
- 结算可回放是硬承诺（B1 Core Rule 15：禁 await、零随机）
|
||||
- 事件序契约：`flag_judged` < `round_end` 全路径统一，但到达序不承载语义
|
||||
- RefCounted 纯逻辑类无场景表示，无法在 .tscn 编辑器里对接信号
|
||||
|
||||
### Requirements
|
||||
- 支持 A2 三事件面 + A3 stopped 直发的双发射源汇聚
|
||||
- 支持多订阅者（B1 facts 缓冲；呈现层只订 B1/runner）
|
||||
- 测试可捕获事件序列（A2/B1 AC 的事件捕获断言面）
|
||||
- 生命周期确定（无悬挂连接、无循环引用）
|
||||
|
||||
## Decision
|
||||
|
||||
**组合根直连 signal 接线 + B1 Waiting 相位触发；否决 autoload 全局事件总线。**
|
||||
|
||||
1. **信号载体**：A2（RefCounted）声明并发射 GDD 三事件——`cell_revealed` / `flag_judged` / `round_end_board`（GDD 概念名 `round_end` 棋盘路径的实现实名）；A3 停手路径发射 `round_end_stopped`（payload 与棋盘路径同构）。回发 `next_round_mode` / `battle_over` 同为 A3/B1 侧 signal。
|
||||
2. **接线位置**：全部 signal.connect 发生在**组合根**（主场景 Node 的装配代码）——core↔core 无静态耦合，依赖单向由接线拓扑保证。RefCounted 无 .tscn 编辑器对接能力，组合根是唯一自然落点。
|
||||
3. **B1 触发**：订阅 A3 相位变更（→Waiting）触发结算事务；触发判定只读 A3 相位观测量与 `last_round_end`，**不消费事件到达序**（同步发射 + 双发射源的正确防御—— specialist 确认信号为同步发射、多订阅者投递序 = 连接序 FIFO）。
|
||||
4. **订阅纪律**：呈现层**永不直接订阅 A2/A3**——只订 B1 步骤流 / runner（切片现状固化，防呈现层绕过编排读核心生命周期状态——切片缺陷②教训）。
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
```
|
||||
[A2 minesweeper_rules]──cell_revealed/flag_judged/round_end_board──┐
|
||||
[A3 action_economy]────round_end_stopped / phase→Waiting──────────┤
|
||||
▼
|
||||
[组合根 main 装配接线]→[B1 battle_orchestrator]
|
||||
│ 步骤流行协议
|
||||
▼
|
||||
[D1 视图单元（只订 B1/runner）]
|
||||
```
|
||||
|
||||
### Key Interfaces
|
||||
|
||||
- 信号均为 **方法 Callable 连接**（见禁令）；信号参数带类型标注仅作文档，无运行时检查——payload 校验由消费侧断言承载（A2 AC 前言口径）。
|
||||
- A2 事件捕获测试 API：冒烟经 signal connect 到捕获数组（AC 前言"事件捕获断言面"的落地形态）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: autoload 全局事件总线
|
||||
- **Description**: 中心 autoload 单例持有全部具名信号，系统经总线收发。
|
||||
- **Pros**: 解耦发射者/订阅者；全局可发现。
|
||||
- **Cons**: 全局耦合（任何系统可达任何信号——与"依赖单向"原则冲突）；单线程回合制无此需求；事件溯源变难。
|
||||
- **Rejection Reason**: 过度设计；切片直连形态已验证且更简单。
|
||||
|
||||
### Alternative 2: 轮询（B1 每帧查 A3 相位）
|
||||
- **Description**: B1 在 process 中轮询 A3 相位观测量。
|
||||
- **Cons**: 延迟（帧粒度）+ 空转；与"回合制无逐帧玩法逻辑"原则冲突。
|
||||
- **Rejection Reason**: 无收益；信号已同步即时。
|
||||
|
||||
### Alternative 3: 回调注册表（A2 持有 handler 列表）
|
||||
- **Description**: A2 暴露 register(handler) API，非 signal。
|
||||
- **Cons**: 非 GDScript 惯用；多订阅者接线繁琐；丢掉引擎信号工具链（.tscn 对接、调试器可视）。
|
||||
- **Rejection Reason**: signal 即本用途的引擎原生方案。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 事件生命周期**确定性优于 Node 方案**：RefCounted 引用计数归零即双向自动断连，无 queue_free 帧末窗口（specialist 核实）——不存在"向半死对象发射"
|
||||
- 组合根接线使依赖方向可视化、可审计；切片 88/88 已验证
|
||||
|
||||
### Negative
|
||||
- 组合根承担全部接线职责——视图单元增多时接线代码线性增长（切片 main.gd 433 行已容纳；演进为装配器函数分组即可）
|
||||
- 信号同步发射的再入语义需实现者理解（本 ADR 的"不依赖到达序"即防御）
|
||||
|
||||
### Risks
|
||||
- **lambda 捕获 self 的循环引用**：GDScript lambda 捕获持强引用——短命 RefCounted 以捕获 self 的 lambda 连到长命发射者会延长生命周期乃至成环，自动断连永不触发 → **缓解（固化为本 ADR 静态规则）**：core↔core 信号连接只许方法 Callable；发射者禁止持有对订阅者的反向引用
|
||||
- 信号参数无运行时类型检查 → 缓解：消费侧断言（既有 AC 口径）+ 呈现载荷 schema 成文义务（code-conventions）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| a2-minesweeper-rules.md | Core Rule 2 三事件回边契约（发射面封闭）；OQ2 事件外发载体 | signal 载体 + 实名映射（round_end→round_end_board）+ 组合根接线；捕获 API 承载 AC 断言面 |
|
||||
| b1-settlement.md | Core Rule 2 结算触发 = Waiting 相位编排点；OQ1 事件总线载体 | 订阅 A3 相位触发、只读 last_round_end、不依赖到达序 |
|
||||
| a3-action-economy.md | Rule 9 round_end 双发射源（stopped 直发、payload 同构） | round_end_stopped 独立信号，同构 payload 由组包纪律保证 |
|
||||
| systems-index.md | 唯一回边裁决（A2 只外发、B4/B1 订阅） | 组合根接线拓扑 = 裁决的落地形态 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 信号发射 = 同步调用链，回合制下每事务个位数次发射——可忽略
|
||||
- **Memory**: 方法 Callable 弱引用目标、不延长生命周期；lambda 禁令消除成环风险
|
||||
- **Load Time**: 无
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片即本决策的实现（`core/minesweeper_rules.gd` 三信号、`action_economy.gd` round_end_stopped、`battle_orchestrator.gd` 双源汇聚）——无迁移，正式化 = 把接线纪律与静态规则写入扫描域（ADR-0004）。
|
||||
|
||||
## Validation Criteria
|
||||
- A2/B1 冒烟事件捕获断言面全绿（既有 88 条覆盖）
|
||||
- 静态扫描：core↔core 连接零 lambda；发射者零反向引用（ADR-0004 扫描域承载）
|
||||
- 回放确定性：同种子同输入步骤流逐行相同（B1 AC-33 先例，切片已证）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（场景结构与组合根）、ADR-0004（测试载体与静态扫描域）
|
||||
- docs/architecture/architecture.md（Data Flow §2 事件路径）
|
||||
@@ -1,119 +0,0 @@
|
||||
# ADR-0002: 渲染器与窗口配置（Renderer & Window Config）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Rendering |
|
||||
| **Knowledge Risk** | MEDIUM（渲染域为 4.5–4.7 变更集中地——本 ADR 相关项已逐条核实，godot-specialist 校验通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；Godot 4.3 release notes（Compatibility 特性补齐）；Godot Docs Environment and post-processing |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | 首次正式导出时核对 gl_compatibility 在目标硬件清单上的实际表现（首次 release 导出 checklist 既有项） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | ADR-0003（工程骨架的 project.godot 基线）；D1 正式化 |
|
||||
| **Blocks** | 正式工程骨架搭建 |
|
||||
| **Ordering Note** | B5 战斗表现若需 HDR 2D 届时复议（见 Risks） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
technical-preferences 将渲染器选择（Forward+ vs gl_compatibility）登记为实现期 ADR；project.godot 的窗口/stretch 基线需要显式定稿——4.7 新项目默认值与训练数据不同（stretch mode canvas_items / aspect expand / Windows 驱动 D3D12），必须显式落盘防漂移。
|
||||
|
||||
### Constraints
|
||||
- 2D 回合制；draw calls < 200 预算；无 3D、无移动端
|
||||
- headless 测试链路不初始化渲染器（dummy DisplayServer）——测试与渲染器解耦
|
||||
- 引擎知识 MEDIUM 风险：渲染域选型必须基于已核实清单
|
||||
|
||||
### Requirements
|
||||
- 满足视觉锚（数字可读性、双通道、绘制优先级）所需的渲染能力
|
||||
- PC（Steam）硬件门槛尽量低
|
||||
- project.godot 各键显式写入（防未来 config_version 升级漂移）
|
||||
|
||||
## Decision
|
||||
|
||||
**渲染器 = gl_compatibility；窗口基座 1280×800（切片已验证值）、stretch mode = canvas_items、aspect = expand；全部键显式写入 project.godot。**
|
||||
|
||||
```ini
|
||||
rendering/renderer/rendering_method="gl_compatibility"
|
||||
rendering/renderer/rendering_method.mobile="gl_compatibility" ; PC 无关，显式对齐防混淆
|
||||
display/window/size/viewport_width=1280
|
||||
display/window/size/viewport_height=800
|
||||
display/window/stretch/mode="canvas_items"
|
||||
display/window/stretch/aspect="expand"
|
||||
; display/window/dpi/allow_hidpi —— 4.x 默认 true，无需写入（勿关闭）
|
||||
```
|
||||
|
||||
- **否决 Forward+**：2D 重 UI 无收益；4.6 起 Windows 新项目 D3D12 默认只作用于 Vulkan 系（Forward+/Mobile）——选 gl_compatibility（OpenGL 3.3）**完全绕开 D3D12 新驱动线**，这是 MEDIUM 风险域里的降险选择；GPU 门槛最低。
|
||||
- **stretch/aspect 与 4.7 新项目默认一致**（canvas_items/expand）——仍显式落盘，防引擎默认未来变化。
|
||||
- **基座 1280×800** = 切片验证值（非引擎默认 1152×648，亦非本 ADR 初稿设想的 1920×1080）；expand 使 16:9 全屏显示正常适配，D1 正式化时如需调整走本 ADR 修订。
|
||||
|
||||
### Architecture Diagram
|
||||
（不适用——配置决策；headless dummy DisplayServer 与本决策完全解耦，冒烟链路不受影响）
|
||||
|
||||
### Key Interfaces
|
||||
- project.godot 键集如上（显式全落盘）；渲染器相关代码面 = CanvasItem/Control 绘制（三渲染器共用管线，重 UI 场景 Compatibility 开销最低——specialist 核实）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: Forward+（Vulkan/D3D12）
|
||||
- **Description**: 4.7 新项目默认渲染器。
|
||||
- **Pros**: HDR 2D、高级后处理全量可用。
|
||||
- **Cons**: 2D 回合制无收益；D3D12 为 4.6 起新默认驱动线（成熟度风险敞口）；GPU 门槛更高。
|
||||
- **Rejection Reason**: 零收益 + 增加风险敞口；B5 若需 HDR 2D 届时复议。
|
||||
|
||||
### Alternative 2: 沿用引擎新项目默认不显式配置
|
||||
- **Cons**: 渲染方法默认 forward_plus；基座默认 1152×648 与切片验证值不符；未来 config_version 升级可能漂移。
|
||||
- **Rejection Reason**: 违背"显式落盘防漂移"要求。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 绕开 D3D12 驱动线与 Vulkan 门槛——MEDIUM 风险域降险
|
||||
- headless 测试与渲染器解耦（已核实），CI 零 GPU 依赖
|
||||
- **B5 复议空间存在**：Compatibility 自 4.3 起已支持 2D 灯光+阴影与 glow/bloom——多数 2D 表现需求无需离开本渲染器
|
||||
|
||||
### Negative
|
||||
- 无 HDR 2D（Forward+/Mobile 专属）；glow 实现不同且部分属性隐藏——B5 视觉上限受此约束
|
||||
- Compatibility 已知渲染问题两条登记（GH-110670 HDR2D+tonemap glow 压暗 / GH-90259 开阴影灯光变亮）——B5 采用相关特性时核对
|
||||
|
||||
### Risks
|
||||
- B5 需要超出现有能力的表现 → 缓解：复议通道 = 本 ADR 修订（迁移成本 2D 项目可控）
|
||||
- OpenGL 3.3 在极旧硬件的覆盖 → 缓解：目标平台 PC Steam 主流硬件；首次导出 checklist 核对
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| technical-preferences.md | Renderer 选择留实现期 ADR；draw calls < 200 | gl_compatibility + 自绘/控件混合渲染在此预算内宽裕 |
|
||||
| game-concept.md | 视觉锚三条硬约束 | canvas_items stretch 保证数字缩放清晰；Compatibility 2D 管线满足绘制优先级栈 |
|
||||
| d2-data-config.md | Rule 7 headless 工程债 | dummy DisplayServer 与渲染器解耦（已核实） |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: Compatibility 2D 管线开销最低（重 UI 场景——specialist 核实）
|
||||
- **Memory**: 三渲染器中最低
|
||||
- **Load Time**: 无差异
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片 project.godot 已写 gl_compatibility——正式工程直接继承；补齐基座尺寸与 stretch 键显式落盘。
|
||||
|
||||
## Validation Criteria
|
||||
- draw calls 实测 < 200（D1 集成时用编辑器 profiler 核对）
|
||||
- 16:9 全屏 / 窗口两种形态下数字可读性目检（视觉锚 1）
|
||||
- headless 冒烟不受渲染器影响（88/88 维持）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（场景结构——project.godot 同批落盘）、ADR-0010（B5 战斗舞台，未立项）
|
||||
- docs/engine-reference/godot/current-best-practices.md §1（新项目默认值差异）
|
||||
@@ -1,139 +0,0 @@
|
||||
# ADR-0003: 场景结构与棋盘渲染（Scene Structure & Board Rendering）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
**部分修订（2026-09-23）**：Decision 3 棋盘渲染形态条款由 [ADR-0006](adr-0006-board-node2d-rendering.md) 部分取代——棋盘本体定向迁 Node2D 渲染（D 区 Phase A 先行，B 区舞台后续批），「禁盲目迁移」条款解除，其登记的探针耦合成本转为迁移批义务（实证收敛为 `_cells` 键面 + `click_cell` + `cell_size` 三点，公共面契约保持即可零改造）。Alternative 2（逐格 Node2D）的否决理由「无必要」因表现层升级需求不再成立；autoload 清单、类形态、CJK 字体前置等其余条款不变。
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting + UI |
|
||||
| **Knowledge Risk** | LOW-MEDIUM（结构决策 LOW；渲染呈现项 MEDIUM——CanvasItem 线条 AA 羽化移除已核实，godot-specialist 校验含 2 项实质修正后通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；godotengine/godot#6360（--script 无 autoload） |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | CJK 字体随包发行的显示核对（首次正式导出 checklist 增补项）；D1 正式化时若执行 _draw 迁移则另核命中测试/无障碍 |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0001（组合根接线纪律）、ADR-0002（project.godot 基线同批落盘） |
|
||||
| **Enables** | 正式工程骨架搭建；D1 正式化 |
|
||||
| **Blocks** | ADR-0004 扫描域（引用本 ADR 的 core 隔离规则） |
|
||||
| **Ordering Note** | 棋盘渲染形态裁决（本 ADR §Decision 3）与 ADR-0004 探针耦合——见 Decision 3 的迁移工作项 |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
正式工程骨架需要定稿：autoload 清单、core/presentation 的类形态与目录结构、棋盘渲染的实现路径。切片已验证一套形态，但初稿 ADR 把"自绘 _draw()"当作切片事实——godot-specialist 校验发现切片 BoardView 实为 **GridContainer + 逐格常驻控件**，本 ADR 按校验修正。
|
||||
|
||||
### Constraints
|
||||
- Core 层零 UI 依赖、headless 可跑（D2 Rule 7）；--script 模式下 core 禁裸引用 autoload 全局标识符（编译期即炸——见 ADR-0004）
|
||||
- 同屏 draw calls < 200；棋盘 ≤12×12（MVP 量级）＋数字/小人/旗/变异多层叠加（视觉锚绘制优先级栈）
|
||||
- 领域命名规范（docs/code-conventions.md：禁 ID 前缀、头注溯源）
|
||||
|
||||
### Requirements
|
||||
- 切片验证过的结构不推倒（用户拍板"按常规老路子"）
|
||||
- 呈现层与核心的写边界：核心写调用唯一发生在组合根
|
||||
- 中文文案可显示（运行时默认字体无 CJK 字形——specialist 核实）
|
||||
|
||||
## Decision
|
||||
|
||||
**1. autoload 清单 = {ConfigDB, RngService}（定名锁定），仅此两个。**
|
||||
战斗编排器等核心类为普通类、由组合根按局实例化——非 autoload、非场景节点。
|
||||
|
||||
**2. 类形态与目录结构：core/ 纯逻辑类 = RefCounted；ConfigDB/RngService = autoload Node 单例（引擎约束：autoload 脚本必须 extends Node）；presentation/ = Control 派生视图单元。**
|
||||
|
||||
```
|
||||
res://
|
||||
├── core/ # RefCounted 纯逻辑（board_generator / minesweeper_rules /
|
||||
│ # action_economy / battle_orchestrator / unit_container /
|
||||
│ # status_container / reward_economy / level_runner / 数据类）
|
||||
│ # —— 零 Control 引用、零 .tscn preload、零 autoload 全局标识符裸引用
|
||||
├── data/
|
||||
│ ├── schemas/ # D2 schema 类（Resource 派生——D2 体系，非本 ADR 变更项）
|
||||
│ └── tables/ # .tres 数值表（单一事实源）
|
||||
├── presentation/
|
||||
│ ├── views/ # 九单元：BoardView / HUDView / BattleLogView / ItemWindowOverlay /
|
||||
│ │ # NodeOverlay / LevelStripView / TunePanel / UiKit
|
||||
│ ├── hud_presenter.gd
|
||||
│ └── main.tscn + main.gd # 组合根：模式流转 + 信号接线 + 核心写调用唯一落点
|
||||
├── smoke/ # 冒烟脚本 + 探针场景（ADR-0004）
|
||||
└── docs/architecture/
|
||||
```
|
||||
|
||||
**3. 棋盘渲染形态：MVP 沿用切片已验证形态——GridContainer + 逐格常驻控件（BoardView 持 `_cells`，refresh 内逐格更新）；自绘 `_draw()` 迁移登记为 D1 正式化候选工作项（非本 ADR 承诺）。**
|
||||
|
||||
- specialist 校验事实：切片 BoardView = GridContainer + 逐格 Button（`_paint_cell` 逐格更新），三探针与该形态耦合（ui_probe 断言 `_cells` 非空、click_probe 依赖 `click_cell` 入口）。初稿"_draw 是切片形态的正式化"**不成立**，按事实修正。
|
||||
- 形态对比留档：逐格控件（现状）= 命中测试/悬停/焦点由引擎承担、探针兼容；代价 = 控件树随格数增长（12×12=144 控件，实测无压力）。`_draw()` = 单 draw call、绘制优先级栈完全可控；代价 = 自建命中测试/悬停 + **三个探针改造**（`_cells` 断言与 `click_cell` 入口失效）+ 无障碍面缺失 + 需补 `Viewport.push_input` 端到端输入探针。
|
||||
- 裁决：D1 正式化 GDD 评审时按当时视觉需求（biome 色板、雾纹理、动效复杂度）二选一；在此之前禁盲目迁移（探针改造是隐藏成本）。任一形态下 CanvasItem 线条 AA 羽化移除（4.7）需注意——格边框用填充 `draw_rect` 不受影响。
|
||||
|
||||
**4. CJK 字体前置（specialist 补登，两种形态都受影响）**：Godot 运行时默认字体不含 CJK 字形——全部中文文案（按钮/标签/结算明细）必须**随包发行 CJK 字体并设为 theme 默认字体**。登记为 D1 正式化硬性前置项 + 首次导出 checklist 项。
|
||||
|
||||
### Architecture Diagram
|
||||
见 `docs/architecture/architecture.md` System Layer Map + Module Ownership（本 ADR 是其工程形态落点）。
|
||||
|
||||
### Key Interfaces
|
||||
- 组合根 = 唯一核心写调用落点（settle_batch / submit_window_selection / runner 推进）——切片纪律转正
|
||||
- 视图单元 = 信号外发 + setter 只读注入（BoardView 只读 A2、动作信号外发不碰核心写）
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 战斗编排器设为 autoload
|
||||
- **Cons**: 编排器持有跨局状态却永生——生命周期与战斗域契约冲突（Uninit/BattleOver 状态机要求按局重建）；与"autoload = 全局基础设施"边界冲突。
|
||||
- **Rejection Reason**: 切片形态（按局实例化）已验证且语义正确。
|
||||
|
||||
### Alternative 2: 棋盘 = 每格一个 Node2D
|
||||
- **Pros**: 独立节点动画/模组方便。
|
||||
- **Cons**: 每节点处理开销与 Control/Node2D 混管复杂度；无必要（specialist 指出 2D 同材质有批处理，draw call 论据最弱，但节点开销与混管论据成立）。
|
||||
- **Rejection Reason**: 逐格控件已覆盖需求且已验证。
|
||||
|
||||
### Alternative 3: TileMapLayer 承载棋盘
|
||||
- **Cons**: 4.5 物理分块默认变更（纯视觉不踩，但物理用途即触）；瓦片语义与"变体标记/数字/旗多层叠加"不匹配。
|
||||
- **Rejection Reason**: 语义不匹配是硬伤；现形态无此问题。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 结构与切片零迁移成本；core 隔离规则可静态扫描（ADR-0004）
|
||||
- 棋盘形态留有 D1 期复议空间且复议成本已如实登记
|
||||
|
||||
### Negative
|
||||
- 逐格控件形态在 D1 需要高表现力时可能仍需迁移 _draw（成本已登记：探针改造 + 命中测试自建 + push_input 端到端探针）
|
||||
- CJK 字体为新增资产义务（发行体积 +）
|
||||
|
||||
### Risks
|
||||
- D1 正式化时遗漏"探针与形态耦合"约束 → 缓解：本 ADR Decision 3 + ADR-0004 探针节双登记
|
||||
- core 类被随手加 autoload 裸引用 → 缓解：ADR-0004 静态扫描（parse 期即炸的事实使该风险自暴露）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 7 零 UI 依赖；Rule 2 单点访问 | core 隔离规则 + autoload 清单固化（ConfigDB/RngService 定名） |
|
||||
| game-concept.md | 视觉锚（绘制优先级栈、双通道） | 棋盘形态两案对比留档，D1 正式化按锚需求裁决 |
|
||||
| b1-settlement.md | Core Rule 1 编排器按局生命周期 | 编排器非 autoload、组合根按局实例化 |
|
||||
| docs/code-conventions.md | 领域命名 / 组合根纪律 | 目录结构与 Key Interfaces 转正 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 144 常驻控件逐格更新——切片实测无压力；_draw 迁移后更优（单 draw call）
|
||||
- **Memory**: 可忽略
|
||||
- **Load Time**: CJK 字体载入一次性成本
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片即目标形态（结构零迁移）；CJK 字体接入与 _draw 复议归 D1 正式化批次。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟 88/88 + 三探针在正式工程维持全绿
|
||||
- 静态扫描：core/ 零 Control extends / 零 .tscn preload / 零 autoload 全局标识符裸引用（ADR-0004 域）
|
||||
- 中文文案在导出包内显示正常（导出 checklist）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（接线纪律）、ADR-0002（渲染器与窗口键）、ADR-0004（扫描域与探针）
|
||||
- docs/architecture/architecture.md（Module Ownership / Required ADRs——本 ADR 落定后其 §Required ADRs 第 3 项闭合）
|
||||
@@ -1,132 +0,0 @@
|
||||
# ADR-0004: 测试载体与 CI（Test Carrier & CI）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting（测试与工具链） |
|
||||
| **Knowledge Risk** | LOW（--script/探针模式为 4.x 基线；godot-specialist 校验通过，含两条规则升格） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；godotengine/godot#6360（--script 模式不加载 autoload + 不注册全局标识符——官方立场） |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（切片 88/88 + 三探针已实证；CI 外部超时在正式 CI 接入时核对） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0003（core 隔离规则是扫描域的输入） |
|
||||
| **Enables** | 全部 GDD AC 的可执行化；正式 CI 接入 |
|
||||
| **Blocks** | `/gate-check` 前置项之一（`/test-setup` 以本 ADR 为基线） |
|
||||
| **Ordering Note** | gdUnit4 复议登记为 D2 OQ1 的关闭形态（推迟，非否决） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
D2 GDD 定下 `--headless --script` 冒烟载体（脚本 extends SceneTree、autoload 显式实例化），D2 OQ1 留下"gdUnit4 是否引入"待决；切片新增了场景级 UI 探针形态；项目级静态扫描域散落在各 GDD AC（AC-9/17/21/22/43 等）需要一处统一登记。
|
||||
|
||||
### Constraints
|
||||
- headless 全套 < 30s 预算（technical-preferences）
|
||||
- 致命类用例独立进程协议（"调用 → 期望退出码" runner manifest，D2 AC-2b 起）
|
||||
- 呈现层测试必须有承载（切片教训：已定稿 AC 全覆盖 core、呈现层零测试承载 → 缺陷 ①②④⑤ 漏网）
|
||||
|
||||
### Requirements
|
||||
- 双模式边界明确：逻辑冒烟（无 autoload）vs 场景探针（完整项目引导）
|
||||
- 静态扫描规则统一载体，覆盖 D2/A1–B4 各 AC 登记的扫描项
|
||||
- CI 可接入且防挂死
|
||||
|
||||
## Decision
|
||||
|
||||
**双载体 + 统一静态扫描域；gdUnit4 推迟到正式 CI 期。**
|
||||
|
||||
**1. 逻辑冒烟（`--headless --script`）**：脚本 extends SceneTree 以获得 `quit(code)`；ConfigDB/RngService 由脚本显式实例化（引擎事实：--script 模式**不加载 autoload 且不注册全局标识符**——裸引用 = parse error 编译期即炸，GH #6360 官方确认）。Windows 用 console 版 exe 取 stdout。承载：D2/A1–B4 全部纯逻辑 AC + 致命类独立进程 manifest。
|
||||
|
||||
**2. 场景探针（headless 跑 .tscn 探针场景）**：以探针场景为运行目标（`godot --headless --path . res://smoke/<probe>.tscn`）走正常项目引导——autoload 在位、真实 SceneTree、`await process_frame` 有效。承载：呈现层场景级测试（切片三探针 ui_probe / ui_click_probe / ui_tune_probe 为先例）。
|
||||
- **口径修正（specialist 校验）**：click_probe 走 `BoardView.click_cell` 是"真实翻译出口"，**绕过 Viewport GUI 管线**（无命中测试/悬停/焦点）。表述定为"合成输入走真实翻译出口"；真正的端到端输入测试 = `Input.parse_input_event()` / `Viewport.push_input` 带坐标——若 ADR-0003 的 _draw 迁移执行（Button 命中测试消失），push_input 探针从加分项变为**必需项**（登记入迁移工作项）。
|
||||
|
||||
**3. 项目级静态扫描域（统一登记，CI 与冒烟前置双跑）**：
|
||||
|
||||
| # | 规则 | 来源/动机 |
|
||||
|---|---|---|
|
||||
| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator` | D2 Rule 5（既有） |
|
||||
| S2 | **禁全局随机函数 `randi()` / `randf()` / `randf_range()`**（全局 RNG 绕开 RngService——specialist 补登漏洞） | D2 Rule 5 补全 |
|
||||
| S3 | core/ 禁 ConfigDB 外 data 表加载（`load(` / `preload(` / `ResourceLoader.load`；schema class_name 直引豁免） | D2 Rule 2（既有） |
|
||||
| S4 | core/ 禁 `extends Control/Node2D`、禁 `.tscn` preload | D2 Rule 7（既有） |
|
||||
| S5 | **core/ 禁裸引用 autoload 全局标识符**（`ConfigDB` / `RngService` 直接写 = script 模式 parse error）——构造注入 only | specialist 升格（切片已合规，规则防复发） |
|
||||
| S6 | core↔core 信号连接只许方法 Callable（禁 lambda 捕获 self）；发射者禁持有订阅者反向引用 | ADR-0001（防循环引用/生命周期延长） |
|
||||
| S7 | B1 编排唯一性：B2/B3/B4 API 符号命中文件 ⊆ B1 文件集；A2/B3/B4 零相互直调 | B1 AC-43（既有） |
|
||||
| S8 | 结算路径 `await` 零命中（B1 结算/编排文件集）；字面量扫描 = warning 级 + 人工三要素复核（D2 AC-14 口径） | B1（既有） |
|
||||
|
||||
**4. CI 防挂死**：任何探针/冒烟调用旁必须配**外部 wall-clock 超时**（命令行 timeout）——引擎自身无死锁探测；探针内 30 帧停滞检测（click_probe 先例）是第一道、外部超时是最后防线。headless 全套 < 30s 预算不变。
|
||||
|
||||
**5. gdUnit4：推迟到正式 CI 期再议**（D2 OQ1 以"deferred"关闭）。它运行在项目模式（autoload 在位），与 SceneTree 冒烟机制正交，引入不废弃既有用例。
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
```
|
||||
提交 → [静态扫描 S1–S8（秒级）] → [逻辑冒烟 --script（独立进程 manifest，<30s）]
|
||||
→ [场景探针 ×N（headless + 外部超时）] → 全绿放行
|
||||
```
|
||||
|
||||
### Key Interfaces
|
||||
- 冒烟 runner manifest：条目 = "调用 → 期望退出码"（独立进程、游戏通道）——D2 AC-2b 协议延续
|
||||
- 探针退出码：0 = PASS；非 0 = 失败类别；停滞 quit(2)
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 立即引入 gdUnit4 并迁移全部冒烟用例
|
||||
- **Pros**: 标准 assertions/参数化/报告；编辑器面板。
|
||||
- **Cons**: 88 条用例迁移成本即刻发生；切片框架已验证且快（~3s）；MVP 期无 CI 基建需求。
|
||||
- **Rejection Reason**: 收益在 CI 期才兑现——推迟（非否决），D2 OQ1 关闭形态。
|
||||
|
||||
### Alternative 2: 仅保留逻辑冒烟、UI 靠人工
|
||||
- **Cons**: 切片缺陷 ①②④⑤ 全部漏过既有 AC 的教训直接否定——呈现层无承载 = 呈现层缺陷零防线。
|
||||
- **Rejection Reason**: 呈现层契约测试是 code-conventions 硬性要求。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 双模式边界以引擎事实固化（parse 期炸 vs 完整引导），不再靠约定俗成
|
||||
- S2/S5/S6 三条 specialist 补登规则堵住静默翻车路径（全局随机绕开、裸引用编译炸、lambda 成环）
|
||||
- 呈现层探针形态沉淀为项目标配（code-conventions 承载）
|
||||
|
||||
### Negative
|
||||
- 静态扫描规则 8 条的维护成本（新规则须挂真实反面案例——code-conventions 纪律）
|
||||
- "真实 UI 路径"表述收窄后，端到端输入覆盖存在已知缺口（_draw 迁移前可接受）
|
||||
|
||||
### Risks
|
||||
- 未被停滞检测覆盖的死锁挂死 CI → 缓解：外部 wall-clock 超时为硬性要求
|
||||
- 扫描规则漏报（启发式）→ 缓解：行为级硬证据并行（可回放断言、headless 实跑合成判定——D2 AC-9/10 模式）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 6 校验双通道；AC-2b 独立进程协议；OQ1 gdUnit4 | 冒烟框架定稿；manifest 延续；OQ1 关闭为 deferred |
|
||||
| a1–b1 各 GDD | 各自静态扫描 AC（AC-9/17/18/19/21/22/43 模式） | S1–S8 统一登记为项目级域，各 AC 引用本 ADR |
|
||||
| docs/code-conventions.md | 场景探针标配 / 提交前全量 | 双载体 + CI 链路承载 |
|
||||
| b1-settlement.md | AC-43 编排唯一性单向扫描 | S7 载体 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 全套冒烟 ~3s（切片实测），预算 <30s 富余
|
||||
- **Memory**: headless dummy server 极低
|
||||
- **Load Time**: 探针场景引导一次性
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片 smoke/ 目录即载体（零迁移）；正式 CI 接入时补外部超时包装与 S1–S8 脚本化；`/test-setup` 以本 ADR 为基线脚手架。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟 + 探针全绿为提交门（code-conventions"提交前全量"）
|
||||
- 扫描域脚本化后：新增违规案例必须先补扫描规则再修码（缺陷-规范对照表纪律）
|
||||
- `<30s` 预算在 CI 环境复核
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（S6 规则来源）、ADR-0003（S4/S5 规则来源、探针形态耦合）
|
||||
- docs/code-conventions.md（缺陷-规范对照表）、各 GDD AC 前言（规范源）
|
||||
@@ -1,104 +0,0 @@
|
||||
# ADR-0005: 存档契约与版本化（Save Contract & Schema Versioning）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；轻量契约 ADR——实现归 D3 Alpha，本 ADR 只锁契约使 Foundation 层 TR 覆盖闭合）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core（数据/序列化契约） |
|
||||
| **Knowledge Risk** | LOW（契约层； FileAccess/JSON 基线稳定） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；D2 GDD Rule 8 / EC9 / RNG 生命周期 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（D3 实现期按契约验证） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | D3 存档序列化（Alpha）——契约先行，实现期免重议 |
|
||||
| **Blocks** | None |
|
||||
| **Ordering Note** | 清零 Foundation 层 TR 覆盖缺口（需求追溯矩阵（已退役，git 历史可查） 的最后两条 pending） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
Technical Setup → Pre-Production 门要求"Foundation 层需求 ADR 覆盖零缺口"。63 条 TR 基线中 Foundation 层尚有两条无 ADR 承载：TR-d2-010（SCHEMA_VERSION 版本化）与 TR-gc-002（RNG 快照存续契约）。两者的契约在 D2 GDD 已定但散落，未 ADR 化——本 ADR 收拢，D3 Alpha 实现时照契约执行。
|
||||
|
||||
### Constraints
|
||||
- MVP 无元进度存档（C4/D3 归 Alpha）——本 ADR 不引入任何 MVP 实现
|
||||
- RNG 快照语义已被 D2 GDD（RNG 生命周期）与 B1 GDD（回放切点）锁定——本 ADR 只做契约归集，不改语义
|
||||
|
||||
### Requirements
|
||||
- 版本不匹配拒绝读取（高版本拒读，D2 EC9）
|
||||
- 续玩/复盘可从快照精确恢复随机序列
|
||||
- 快照切点与在飞流实例的互斥有明确归属
|
||||
|
||||
## Decision
|
||||
|
||||
**1. 版本化契约**：`SCHEMA_VERSION` 常量归 D2（既定）；存档文件携带该版本号；**比较逻辑归 D3**（D2 EC9 既有分工）——存档版本 > 当前 SCHEMA_VERSION → 拒绝读取 + 明确错误信息；低版本存档的迁移策略归 D3 Alpha 设计时定（候选：拒读 / 迁移器——届时另议，非本 ADR 范围）。
|
||||
|
||||
**2. RNG 快照契约（从 D2/B1 GDD 收拢为 ADR 登记）**：
|
||||
- 快照内容 = `master_seed` + 各封闭流 scope 计数器 + 意图序列 + 窗口选择序列
|
||||
- **切点规则**：快照切出必须发生在 scope 事件边界之外（无在飞 `open_stream` 实例时）；运行期 scope 事件边界 = board install（A1 取号 / B4 取号）——B1 编排保证无在飞实例跨界（消费侧遵守义务，B1 GDD 回放切点条款）
|
||||
- 违反后果：续玩/复盘与实况分叉（D2 AC-15 语义失效）——该前提由 D3 消费侧遵守，B1 侧编排义务已在位
|
||||
|
||||
**3. 存档内容归属预告（D3 Alpha 实现的输入清单，非本 ADR 决策）**：冒险结构（C2 域）、关卡进度（C1 域）、HP/库存（B1/B4 关卡域）、钥石/天赋（C4 MetaTable）、RAP 不持久（战斗域清零）。D3 GDD 立项时按此清单展开。
|
||||
|
||||
### Architecture Diagram
|
||||
（不适用——契约 ADR；数据流见 architecture.md §Data Flow 3）
|
||||
|
||||
### Key Interfaces
|
||||
- D3 → D2：读取 `SCHEMA_VERSION`（比较方向：存档版本 ≤ 当前才可读）
|
||||
- D3 → RngService：只读计数器接口（D2 已暴露）+ `set_master_seed`（仅 C2 调用——D3 只读快照、恢复时经 C2 重放接线）
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 不立 ADR，依赖 D2/D3 GDD 散落条款
|
||||
- **Cons**: gate 的 Foundation 零缺口检查失败；契约散落三处（D2 EC9 / D2 RNG 生命周期 / B1 回放切点），D3 实现时需跨三文档拼装。
|
||||
- **Rejection Reason**: 收拢成本一次会话内，收益是门检查全绿 + D3 立项输入就绪。
|
||||
|
||||
### Alternative 2: 现在就设计存档格式（JSON vs 二进制 vs Resource）
|
||||
- **Cons**: C4/D3 未设计，过早——MVP 无存档需求牵引。
|
||||
- **Rejection Reason**: 违背"schema 先行、数值回填"的项目节奏；格式决策留给 D3 GDD。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Foundation 层 TR 覆盖零缺口（门检查全绿）
|
||||
- D3 立项时的硬输入就绪（版本比较方向、快照内容、切点规则、内容归属清单）
|
||||
|
||||
### Negative
|
||||
- 无（纯收拢，零新约束）
|
||||
|
||||
### Risks
|
||||
- D3 Alpha 实现时偏离切点规则 → 缓解：本 ADR + D2 AC-15 / B1 AC-34 双侧断言承载
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 8 版本化；EC9 高版本拒读；RNG 快照生命周期 | 契约收拢 + 版本比较归属（D3）成文 |
|
||||
| b1-settlement.md | 回放切点契约（快照语义 = seed + 计数器 + 两类输入序列） | 切点规则 ADR 化（无在飞实例时切出，scope 边界 = board install） |
|
||||
| game-concept.md | 存档/冒险/关卡术语层级（C4/D3 Alpha 范围） | 存档内容归属预告清单 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU / Memory / Load Time / Network**: 无（MVP 零实现；Alpha 期存档体积预期 < 1MB 量级）
|
||||
|
||||
## Migration Plan
|
||||
无迁移（MVP 零实现）。D3 GDD 立项（Alpha 期）以本 ADR 为硬输入。
|
||||
|
||||
## Validation Criteria
|
||||
- D3 实现后：同快照恢复 → 随机序列逐位一致（D2 AC-15 / B1 AC-34 形态）
|
||||
- 版本不匹配路径拒绝读取且错误信息含两侧版本号
|
||||
- tests/integration/ 收录存档往返测试（D3 落地时）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（回放输入序列的载体）、ADR-0004（集成测试载体）
|
||||
- 需求追溯矩阵（已退役，git 历史可查）（TR-d2-010 / TR-gc-002 覆盖闭合）
|
||||
@@ -1,141 +0,0 @@
|
||||
# ADR-0006: 战斗棋盘 Node2D 渲染迁移（Board Node2D Rendering Migration）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-23 用户拍板方向；本 ADR 落文。Phase A 棋盘实施另批执行；B 区舞台迁移为后续批，本 ADR 只定分工不排期）
|
||||
部分取代 ADR-0003 Decision 3（形态条款定向 Node2D，「禁盲目迁移」解除；autoload 清单 / 类形态 / CJK 字体前置等其余条款不变）
|
||||
|
||||
## Date
|
||||
2026-09-23
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | UI / 棋盘渲染 |
|
||||
| **Knowledge Risk** | MEDIUM（SubViewport 内 theme 传播与像素缩放纹路两项待实施批实证；其余为已验证引擎面） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`；ADR-0003 Decision 3 形态对比留档；art-bible §8.2 画布暂定档 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | SubViewport 内 CJK 字体显式注入核对（实施批）；分辨率两档装板校验（实施批） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0001（组合根接线纪律）、ADR-0002（渲染器与窗口键）、ADR-0003（场景结构与渲染形态——本 ADR 修订其 Decision 3） |
|
||||
| **Enables** | 表现层升级（B 区站桩 / 意图三档动画 / P3 演出需要 Node2D 载体）；美术终稿资产 1:1 换入的槽位体系 |
|
||||
| **Blocks** | 无（B 区舞台迁移为本 ADR 分工内的后续批，不阻塞他批） |
|
||||
| **Amends** | ADR-0003 Decision 3（逐格控件形态维持条款）与 Alternative 2（逐格 Node2D 否决——否决理由「无必要」因表现层升级需求不再成立，节点开销论据维持有效） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
ADR-0003 Decision 3 将棋盘渲染冻结为「GridContainer + 逐格常驻控件」，并登记 _draw/自绘迁移为 D1 正式化候选、迁移前禁盲目动手（探针耦合是登记成本）。2026-09-23 用户拍板：表现层走 Node2D 重构，**只迁战斗棋盘**，开始菜单（ui_assembler build_start_overlay）与各覆盖层保持 Control——分工不是替换。原「禁盲目迁移」条款与现行裁决冲突，需要新 ADR 定向解禁并落分工边界。
|
||||
|
||||
### Constraints
|
||||
- 战斗屏四区布局与分区尺寸是 HUD框架 结构冻结项——本迁移只换渲染技术，四区结构、双舞台常驻、尺寸表零改动（战斗屏进度条退场与四区→三区重排由停点前移批按文档修订流程另行落地，与本批解耦）
|
||||
- 组合根纪律（ADR-0001）：核心写调用唯一落点不变；BoardView 信号外发 + 只读注入模式不变
|
||||
- 性能预算（HUD框架 引用值）：同屏 draw calls < 200；进入战斗屏 500ms 内首格可点
|
||||
- 美术终稿资产全部缺位（样张批未跑）——迁移必须以程序化占位服役为前提，不新增素材前置
|
||||
- core/ 零 UI 依赖（D2 Rule 7）——本迁移全部发生在 presentation/，逻辑层零接触
|
||||
|
||||
### Requirements
|
||||
- B 区战斗画面（站桩立绘、意图三档动画、受击/死亡演出）的后续迁移不被本批堵死——骨架同构可复制
|
||||
- 分辨率两档（1280×800 / 1920×1080，2026-09-22 定案）与「格边长按分辨率档位计算」口径（2026-09-18 拍板，推翻两档定值冻结）继续成立
|
||||
- 三探针（ui_probe / ui_click_probe / ui_layout_probe）与冒烟全量基线不破
|
||||
|
||||
## Decision
|
||||
|
||||
**1. D 区棋盘本体迁 Node2D 渲染，BoardView 类名与公共面契约保持不变。**
|
||||
|
||||
BoardView（`presentation/views/board_view.gd`，现 extends Control + 内部 GridContainer）重构为：Control 壳参与屏幕栅格布局不变，壳内经 **SubViewportContainer + SubViewport + Node2D 世界**（BoardWorld）渲染棋盘。对外契约逐项保持：
|
||||
|
||||
| 契约面 | 消费方 | 保持方式 |
|
||||
|---|---|---|
|
||||
| 类名 `BoardView` / extends Control | ui_assembler 组装、屏幕栅格布局 | 不变 |
|
||||
| 信号 `action_requested` / `hover_forbidden` / `chord_attempted` | 组合根动作通道 | 不变 |
|
||||
| `click_cell(cell, button)` 公共入口 | ui_click_probe 直调路径（ui_click_probe.gd:257–277） | 不变 |
|
||||
| `_cells` 字典（Vector2i → 格单元） | ui_probe `_cells.is_empty()/.size()` 断言（ui_probe.gd:73/187）、ui_click_probe.gd:97 | 键面不变，值 Button → 格单元 Node2D |
|
||||
| `board()` / `set_desaturated()` / `set_identity_resolver()` / `set_variant_mask_resolver()` / `set_cell_area()` / `rebuild()` / `refresh()` | 组合根与探针 | 不变 |
|
||||
| `cell_size` 只读属性 | ui_layout_probe `get("cell_size")`（现返回 null——`_cell` 为私有名） | 增补只读属性，顺手修正 |
|
||||
|
||||
**2. 渲染技术分工表（本 ADR 核心裁决——「三块模型」）。**
|
||||
|
||||
战斗屏渲染技术按内容形态切分，与屏幕布局正交。**战斗屏目标形态 = B/C/D 三区**（2026-09-23 用户裁定：战斗画面不再保留关卡进度条——战斗结束后返回关卡画面，节点链进度只留关卡画面）：
|
||||
|
||||
| 内容 | 渲染技术 | 批次 |
|
||||
|---|---|---|
|
||||
| D 区棋盘本体（格面/数字/旗/徽章/变异纹带/高亮/微光） | **Node2D**（本 ADR） | Phase A（本批立项） |
|
||||
| B 区战斗舞台（主角/敌人站桩、意图三档动画、受击/死亡演出、FX） | **Node2D** | Phase B（后续批，本 ADR 只定分工） |
|
||||
| A 区关卡进度条 | Control | **战斗屏退场且代码退役**（裁定见下；退场落地随停点前移批——流程未倒置前 A 区仍是战斗中唯一节点链可视面，先删致盲，本批不动其现状） |
|
||||
| C 区角色信息（数据框/状态槽/立绘） | Control | 不动 |
|
||||
| D 区 AP 条、按钮组、toast 槽 | Control | 不动 |
|
||||
| B 区结算明细带、回合阶段指示、战斗日志 | Control（文本件） | 不动（Phase B 时留 B 区 Control 半区） |
|
||||
| 全部弹层（选路/节点/结算/图例/营地/开始菜单） | Control | 不动（2026-09-23 用户拍板） |
|
||||
|
||||
**A 区退场形态（2026-09-23 追问裁定）**：LevelStripView **退役，不迁移**；关卡画面**不重新实现**——由 RouteOverlay（整幅节点图选路层，节点态色板语义与压缩条同族、候选按钮与放弃入口在役）升级为常驻页面承接。压缩条唯一存在理由（战斗屏无整图时的常显替代面）随零进度裁定消亡，无独有资产流失；唯一继承面 = 逻辑层节点数据面（runner 只读出口零改动）。退役删除面清单见迁移方案 §1。
|
||||
|
||||
**3. 命中测试 = 整图公式换算单点，非逐格 Area2D。**
|
||||
|
||||
鼠标输入经 BoardView 壳层 `_gui_input` 接收（Control 已有的矩形命中），格坐标 = `floor(local_pos / 格边长)` 单点公式换算——悬停/点选/双击 chord/长按全部复用现有逻辑入口。不为 144 格建 Area2D（节点开销无必要，Alternative 2 论据沿用）；ADR-0003 登记的「自建命中测试」成本由此收敛为一个公式函数。无障碍面缺失为接受后果（沿 ADR-0003 Decision 3 已登记口径，键盘寻格体系延后）。
|
||||
|
||||
**4. 素材槽位按圣经 §8.2 暂定档预留，程序化占位继续服役。**
|
||||
|
||||
格单元内部为固定叠层序的精灵槽位（砖面 < 变异纹带 < 数字/徽章 < 旗 < 焦点高亮），本批全部槽位由程序化绘制填充（现行占位等价平移）；终稿纹理（格面 32×32 暂定档）到位后 1:1 换入，零结构返工。**美术缺口不阻塞本迁移**——样张批终值（格边长×格源占比摩擦，v1.9 待决注记①路线）只换 `set_cell_area` 单点数值，不动架构。
|
||||
|
||||
**5. SubViewport 模式为两舞台统一骨架，Phase B 复制不返工。**
|
||||
|
||||
Phase B 届时将 BattleStageView 同构改造（PanelContainer → Control 壳 + SubViewport 舞台 + 结算明细带 Control 半区）。本批在 ui_assembler 组装侧不引入「单舞台」写死假设，SubViewport 内 theme/字体注入做成可复用挂点（两舞台共用）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 维持逐格控件形态（ADR-0003 现行）
|
||||
- **Cons**: 表现层升级（站桩动画/演出/FX）在 Control 树内无载体，最终仍需二次迁移；两次改造总成本高于一次定向。
|
||||
- **Rejection Reason**: 2026-09-23 用户已定向 Node2D；本 ADR 职责是把方向落为工程边界。
|
||||
|
||||
### Alternative 2: 直挂 Node2D（Control 壳内手挂 Node2D，无 SubViewport）
|
||||
- **Cons**: 屏幕坐标↔棋盘坐标换算、缩放纪律、两档分辨率适配全部自建；布局联动手工维护。
|
||||
- **Rejection Reason**: SubViewportContainer 是 Control——容器栅格布局引擎原生参与，鼠标坐标引擎换算，内部分辨率固定使像素缩放纪律有单点可管。
|
||||
|
||||
### Alternative 3: 逐格 Area2D 承载命中
|
||||
- **Cons**: 144 个 Area2D 节点开销与信号接线量；命中语义（相邻约束/chord/长按）仍要自建。
|
||||
- **Rejection Reason**: 整图公式换算单点已覆盖全部交互语义，物理命中是纯开销。
|
||||
|
||||
### Alternative 4: TileMapLayer 承载棋盘
|
||||
- **Rejection Reason**: ADR-0003 已否（瓦片语义与变体标记/数字/旗多层叠加不匹配），维持。
|
||||
|
||||
### Alternative 5: B 区与棋盘同批迁移
|
||||
- **Cons**: B 区站桩形态绑美术样张批（剪影/动画方案未冻结），混批互卡。
|
||||
- **Rejection Reason**: 2026-09-23 用户拍板分批——先只迁棋盘，战斗画面 Node 后续完成。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 表现层升级获得渲染载体；棋盘先行验证 SubViewport 骨架，B 区复制模式即可
|
||||
- BoardView 公共面契约保持——三探针与组合根零改造（实证耦合面仅 `_cells` 键面/`click_cell`/`cell_size`，全部保留）
|
||||
- 素材终稿 1:1 换入，样张批与渲染批解耦，互不阻塞
|
||||
- 逻辑层（core/）零接触——MC/模拟试玩/verifier 读数面零影响
|
||||
|
||||
### Negative
|
||||
- Node2D 世界内 theme 不自动继承主场景 Control 主题——CJK 字体与 ui_kit 样式需显式注入（实施批义务，ADR-0003 Decision 4 关联）
|
||||
- 键盘寻格/无障碍面缺失口径延续（已登记接受）
|
||||
- 非整数缩放的像素纹路风险（45/36px 锚点 × 32px 格源非整倍）——沿 §8.2 路线归样张批定终值，架构只保证 `set_cell_area` 单点可调
|
||||
|
||||
### Risks
|
||||
- SubViewport 渲染目标在低端机的显存/带宽开销 → 缓解：棋盘区逻辑分辨率小（≤ 12×12×36px 量级），实施批实测帧预算
|
||||
- 输入路径改 `_gui_input` 后现探针全走 `click_cell` 直调，公式换算无自动化覆盖 → 缓解：实施批增补 push_input 端到端输入探针（ADR-0003 已登记项，本批转义务）
|
||||
|
||||
## Migration Plan
|
||||
Phase A（棋盘，实施另批）：BoardView 内部重构 + 探针增补 + 冒烟全量回归 + 文档随批（HUD框架渲染注记/battle.md 实现注记/architecture.md 模块归属行）。Phase B（B 区舞台，后续批）：同构复制 + 站桩精灵迁移 + 意图动画承载；开工前置 = 样张批冻结剪影与动画方案。战斗屏进度条退场的 GDD 修订面（HUD框架 四区表、关卡节点地图 节点链常显条款、battle.md 像素布局表与 28px 纵向空间再分配）随停点前移批（关卡画面成为常驻枢纽）落地，不随本批。工程细节见同目录 `Node2D 迁移计划（已执行完毕，文件已退役）`。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟全量绿（现行基线不破）；三探针（ui / ui_click / ui_layout）绿
|
||||
- 新增 push_input 端到端输入探针绿（悬停/左键/右键/chord 各一case）
|
||||
- 功能等价清单：数字/旗/徽章/危险红/变异纹带/呼吸微光/悬停/路径预览/灰化（set_desaturated）/出生展开区 R₀ 豁免，逐项可点可验
|
||||
- 性能预算：同屏 draw calls < 200；进入战斗屏 500ms 内首格可点
|
||||
- 分辨率两档（1280×800 / 1920×1080）装板校验通过（12×12 与 10×10 板各验）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（本 ADR 部分取代其 Decision 3；Alternative 2 否决理由更新）
|
||||
- ADR-0001（组合根纪律——BoardView 信号外发模式沿袭）
|
||||
- art-bible §8.2（画布暂定档与缩放纪律）、HUD框架（四区结构冻结与性能预算引用值）、battle.md（格尺寸公式锚点）
|
||||
@@ -1,80 +0,0 @@
|
||||
# ADR-0007: 全游戏随机流统一评估（RNG Single Stream Evaluation）
|
||||
|
||||
## Status
|
||||
|
||||
**已裁决：方案丙（并流 + 全事件日志）——2026-09-27 用户裁决，随批落地**。推荐案甲未被采纳，评估书正文保留原样作决策记录；丙的实施 = 统一随机流批（rng_service.gd 重写 + 七消费点迁移 + 单盐黄金向量重登记 + 事件日志会话制），验证与工单清单见文末「落地记录」。
|
||||
|
||||
背景：2026-09-27 用户在[关卡节点图生成](../../gdd/systems/冒险循环/关卡节点图生成.md)拍板点②两轮复裁终选「随机数统一用一个流」（全面执行），并拍板执行路径 = **先出本评估书再动手**、节点图特性实施排队其后。本评估书按用户要求如实给出：现行机制事实、统一流的真实改动面、三个备选与推荐。裁决本 ADR 后按裁决执行。
|
||||
|
||||
## Date
|
||||
|
||||
2026-09-27
|
||||
|
||||
## Context
|
||||
|
||||
### 用户动因（如实记录）
|
||||
|
||||
用户质疑链全程：①问「增流是什么、文档没说明」→ ②质疑「借流复现口径变含糊」论断：「如果所有的随机数获取都是有完整记录的，那不是都可以一一复现吗？我觉得你的理论不对」→ ③收到机制澄清（复现=主种子+计数器按位重推导、非日志回放）与两条代价说明后，仍两轮终裁「统一用一个流」。动因解读：用户重视**单一随机源的心智简洁**，对"七条流"的分栏结构存疑（直觉=繁琐），并认为完整记录即可复现一切。
|
||||
|
||||
### 现行机制事实（全部带代码锚）
|
||||
|
||||
| 事实 | 锚点 |
|
||||
|---|---|
|
||||
| 唯一主种子：冒险开始恰一次注入，禁中途重播种（全零断言） | `game/core/rng_service.gd:80-105` |
|
||||
| 唯一派生公式族：derive(stream, scope) = mix64(SALT_s XOR (master + scope×GOLDEN)) | `game/core/rng_service.gd:61-77` |
|
||||
| 七条流 = 七个盐值常量（同一公式、同一主种子） | `game/core/rng_service.gd:14-24` |
|
||||
| 零旁路随机：randomize()/自建 RNG 硬性红线 | CLAUDE.md 硬性红线；`rng_service.gd:4` |
|
||||
| 每流独立计数器；快照观测面 counter() | `rng_service.gd:36,140-142` |
|
||||
| 复现 = 按（流，号位）重新推导，非日志回放 | registry `rng_service`/`stream_seed_derivation` 条目 |
|
||||
| 计数器实际持久化：**现行存档未写各流计数器**（adventure_runner 摘要只落 master_seed） | `game/core/adventure_runner.gd:59,83,217` |
|
||||
| 黄金向量断言（R3 8 常量） | `game/smoke/smoke_all.gd:34-36,3121+` |
|
||||
| MC 逐局独立种子 | `game/smoke/adventure_monte_carlo.gd:15,52` |
|
||||
|
||||
**核心发现**：字面目标「全游戏随机数派生自同一个源、可逐位复现、没有多套随机」——**现行架构已经满足**。七条流不是七个随机源，是同一主种子的七个盐值分栏（分栏只改派生种子，不改源）。真正剩下的唯一改动 = **把七条分栏计数器并为一个全局计数器**（物理并流）。
|
||||
|
||||
### 七流消费点清单（并流迁移面）
|
||||
|
||||
| 流 | 消费点 | 取号时机 |
|
||||
|---|---|---|
|
||||
| board_gen | `board_generator.gd:16`、`battle_orchestrator.gd:141` | 每张棋盘 |
|
||||
| reward_roll | `reward_economy.gd:61` | 每次装板批 |
|
||||
| encounter | `battle_orchestrator.gd:116` | 每次战斗实例化（数量骰） |
|
||||
| armor_roll | `damage_controller.gd:286`（流名走配置 `db.settlement.armor_roll_stream`） | 每次命中掷点 |
|
||||
| behavior_roll | 战斗结算开轮摇号（SkillLottery；子流 scope = spawn_index×1000000+序） | 每敌每轮 |
|
||||
| variant_place | `battle_orchestrator.gd:198` | 每板变异布置 |
|
||||
| gp_drop | `battle_orchestrator.gd:737` | 每战末掉落掷定 |
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### 方案甲：字面达成·维持分栏（node_map 作第八栏）
|
||||
|
||||
承认字面目标已满足（核心发现）；节点图抽签按既有增流纪律接入第八栏。零迁移、位置语义（号位=第 N 次某类事件）完整保留、黄金向量与对拍口径不动。
|
||||
|
||||
### 方案乙：物理并流（用户终裁方向，如实评估）
|
||||
|
||||
单盐单全局计数器：derive(scope) = mix64(SALT_0 XOR (master + scope×GOLDEN))，scope = 全局顺序号。三个后果（均已向用户两轮呈报，此处落档）：
|
||||
|
||||
1. **号位失去事件语义**——第 N 号只回答"全局第 N 次取数"，不再回答"第 N 次什么"。玩家换条路（战斗次数变化）后，同一 N 号对应的事件种类漂移。
|
||||
2. **路线依赖**——任何一处随机事件数量/顺序变化平移其后全部骰子；对拍工具"行数恒等纯次序位移"性质失效；"这局 Boss 为什么没中"类单点归因需全序重放。
|
||||
3. **连带改动面**——七消费点迁移（上表 6 文件）；armor_roll 流名配置语义失效（`db.settlement.armor_roll_stream` 并流后无意义）；behavior_roll 子流位（spawn_index×STRIDE）重设计；快照契约登记面变更（7 计数器→1，实际存档未持久化计数器故代码迁移面小）；R3 黄金向量 8 常量全量重生成；MC/对拍读数与旧基线断档（全部历史基线作废重测）。
|
||||
|
||||
### 方案丙：并流 + 全事件日志（用户的「完整记录」模型落地）
|
||||
|
||||
乙 + 每次取数落盘（流名/号位/用途/返回值），以此恢复单点定位能力。代价 = 乙全部代价 + 每次取数的写盘开销与日志体积；且日志回放与按位重推导并存 = 两套复现机制并存。
|
||||
|
||||
## Recommendation
|
||||
|
||||
**推荐甲**：用户的核心诉求（单一随机源、完整可复现、无多套随机）现行架构字面满足；乙/丙是为一个已满足的目标支付真实的分析能力与一次性迁移成本。本 ADR 按用户裁决路径交付评估，**若用户裁决维持乙，上表「连带改动面」即实施批工单，按乙执行，本特性排队其后**——两个方向都已备好，裁决即动。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 裁决甲：节点图生成实施批按第八栏增流推进（改代码+金向量+冒烟断言三件套），本评估书归档为架构记录。
|
||||
- 裁决乙：先开 rng 架构批（迁移工单如上），全量回归后节点图生成实施批接续；历史 MC 基线全部作废重测归曲线调参批。
|
||||
- 裁决丙：同乙，另加日志面设计与写盘性能验收。
|
||||
|
||||
## 落地记录（统一随机流批 2026-09-27）
|
||||
|
||||
- 代码：rng_service.gd 重写（单盐 SINGLE_SALT=原 board_gen 盐 / 全局计数器 / 用途标签 open_stream(purpose) / derive_at(scope) 单参 / open_scope 与 BEHAVIOR_SUBSTREAM_STRIDE 退役 / 事件日志会话制 user://logs/rng_log_<主种子>.jsonl）；消费点七处迁移（board_generator/reward_economy/battle_orchestrator×4/damage_probe/skill_rhythm_probe/smoke_all 向量与计数断言）；behavior_roll 子流派生向量退役（逐敌顺序取号替代，单敌轨迹独立复放面随之退役——冒烟 ③ 测试同批退役，同种子全战斗对拍由 ② 承载）。
|
||||
- 向量：统一流 8 常量重登记（scope 0-3 与旧 board_gen 向量逐位连续——单盐沿用其盐）；registry stream_seed_derivation 全量改版。
|
||||
- 测试：冒烟 557/0 三闸全过（nat20/极性路由/L2 max 三处种子硬编码测试改行为面扫描——并流后随机值面漂移的测试面重锚）；四场景探针全绿（ui_input_probe 加「移位扩边」前置——板面种子漂移下前沿不足两格时沿已开区点击移位）；MC 20 局逐局独立跑通，事件日志逐冒险落盘实证。
|
||||
- 行为面基线：并流后全部历史 MC/verifier 基线作废，重测归曲线调参批（测量对账条款既有口径）。
|
||||
@@ -2,14 +2,14 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.5
|
||||
- 最近更新：2026-10-15（①新增「测试与质量域」节——测试域事实源自 ADR-0004 迁入承接；②全文标题/状态键/表头中文化；③现状同步：覆盖 GDD 改指现行中文域结构、现存 ADR 七份、实现实证改为完整游戏开发版本、四处失效路径订正）
|
||||
- 版本：1.6
|
||||
- 最近更新：2026-10-15（①废除历史决策文档体系：七份决策文件删除（沿革归 git commit log），原审计与立项两节移除，全部在效事实并入本文；②「测试与质量域」节改纯事实陈述；③现状同步：autoload 清单补 SaveManager/MetaProgression，A1 生成姿态与事件载体事实登记，未决问题表已落定项关闭）
|
||||
- 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||||
- 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||||
- 覆盖 GDD：现行全集——`design/gdd/` 顶层 00–08 共 9 件 + `systems/` 五域 25 件（排雷循环 4 / 战斗循环 5 / 冒险循环 5 / 跨局循环 5 / 表现与支撑 6）+ `ux/` 8 件；原英文命名 12 份系统 GDD 已全部迁入中文域目录，原「未设计」预留（A5 扫雷秘宝 / C1–C4 / B5 / D3–D6）均已立项成文
|
||||
- 引用 ADR：7 份现存（adr-0001–0007，`design/dev/architecture/`）——ADR＝变更记录留档、非事实源；测试域事实源见本文「测试与质量域」节
|
||||
- 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 28 已入库合并——冒烟 1125/0、单元 27 套件、本地五闸在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 技术总监签核：2026-09-12 — 有条件通过（条件：应立 ADR 于正式工程骨架搭建前定稿；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
- 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
- 主程序可行性：跳过 — solo 模式
|
||||
|
||||
---
|
||||
@@ -22,7 +22,7 @@
|
||||
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 裁决时对照引擎文档核实。
|
||||
- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地——渲染器与窗口基座已定（gl_compatibility + 1280×800，2026-09-12），采纳引擎增量前对照文档核实。
|
||||
|
||||
---
|
||||
|
||||
@@ -62,11 +62,11 @@
|
||||
| A3 行动经济 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| A4 地形变异 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B3 状态系统 | 基础层 | MVP | ✅ 完整可跑 | LOW（RefCounted 纯逻辑） |
|
||||
| A1 棋盘生成 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑；性能姿态归 ADR-0005） |
|
||||
| A1 棋盘生成 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| A2 排雷规则 | 核心层 | MVP | ✅ 完整可跑 | LOW（零表读取零 UI） |
|
||||
| B2 敌人系统 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B4 地图战斗资源 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B1 战斗结算编排 | 功能层 | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑；事件载体归 ADR-0001） |
|
||||
| B1 战斗结算编排 | 功能层 | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑） |
|
||||
| C1 关卡节点地图 | 功能层 | MVP（切片期实装） | ✅（切片 level_runner 先例） | LOW |
|
||||
| C2 冒险结构 | 功能层 | MVP（切片期实装） | ✅ | LOW |
|
||||
| C3 难度曲线 | 功能层 | MVP（切片期实装） | ✅ | LOW |
|
||||
@@ -102,9 +102,9 @@
|
||||
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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 只读 | 无 |
|
||||
| **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)`（唯一提交入口）；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） | 无 |
|
||||
| **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 随行为环退役） | 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、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 |
|
||||
|
||||
@@ -123,7 +123,7 @@
|
||||
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **D1 HUD**（切片 lite 已拆 9 单元：BoardView / HUDView / HudPresenter / BattleLogView / ItemWindowOverlay / NodeOverlay / LevelStripView / TunePanel / UiKit + 组合根 main.gd；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕） | 全部 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 图片参数两轮变化） |
|
||||
| **D1 HUD**（切片 lite 已拆 9 单元：BoardView / HUDView / HudPresenter / BattleLogView / ItemWindowOverlay / NodeOverlay / LevelStripView / TunePanel / UiKit + 组合根 main.gd；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——棋盘 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，垂直切片后） | 结算动画 / 伤害数字 / 战斗舞台 | （契约规范源：`../../gdd/systems/战斗循环/战斗表现.md`——前置「战斗表现美术测试」锁双舞台陷阱） | 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 各教学条目） | 各上游 | 无 |
|
||||
@@ -134,7 +134,7 @@
|
||||
|
||||
## 测试与质量域
|
||||
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。原登记于 ADR-0004 的测试载体与静态扫描域约束已迁入本节承接；ADR-0004 保留为历史变更记录，不回改、不再作为现行依据引用（2026-10-15 立规：ADR = 变更记录，不是事实源）。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。
|
||||
|
||||
### 模块归属
|
||||
|
||||
@@ -158,20 +158,20 @@
|
||||
|
||||
### 静态扫描域 S1–S8 承接清单
|
||||
|
||||
规则语义源自 ADR-0004 §Decision 3（原文留档不动，下表为现行事实登记）：
|
||||
静态扫描域规则（2026-09-12 立，沿革见 git commit log；下表为现行事实登记）：
|
||||
|
||||
| # | 规则 | 状态 |
|
||||
|---|---|---|
|
||||
| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator`（D2 Rule 5） | **在位**（硬失败；扫描面 game/core + game/presentation） |
|
||||
| S2 | 禁全局随机函数 `randi()` / `randf()` / `randf_range()`——全局 RNG 绕开 RngService（specialist 补登） | **在位**（与 S1 同段硬失败；实例方法 `.randi()` 排除、`ADR-0007-exempt` 豁免注记在案） |
|
||||
| S2 | 禁全局随机函数 `randi()` / `randf()` / `randf_range()`——全局 RNG 绕开 RngService（specialist 补登） | **在位**（与 S1 同段硬失败；实例方法 `.randi()` 排除、`rng-seed-exempt` 豁免注记在案） |
|
||||
| S3 | core/ 禁 ConfigDB 外 data 表加载（`load(` / `preload(` / `ResourceLoader.load`；schema class_name 直引豁免）（D2 Rule 2） | **未落地**（脚本内仅 warning 级占位、不参与 fail 判定；且扫描路径 `core/` 自 2026-09-24 布局迁移后不存在——实际为 game/core，现行实跑恒零命中） |
|
||||
| S4 | core/ 禁 `extends Control/Node2D`、禁 `.tscn` preload（D2 Rule 7） | **在位**（硬失败） |
|
||||
| S5 | core/ 禁裸引用 autoload 全局标识符（`ConfigDB` / `RngService` 直接写 = --script 模式 parse error）——构造注入 only（specialist 升格） | **未落地**（脚本 TODO 注记在案：grep 近似误报多，需 AST 级或精确白名单；已有真实反面案例） |
|
||||
| S6 | core↔core 信号连接只许方法 Callable（禁 lambda 捕获 self）；发射者禁持有订阅者反向引用（ADR-0001） | **未落地**（脚本 TODO 注记在案） |
|
||||
| S6 | core↔core 信号连接只许方法 Callable（禁 lambda 捕获 self）；发射者禁持有订阅者反向引用 | **未落地**（脚本 TODO 注记在案） |
|
||||
| S7 | B1 编排唯一性：B2/B3/B4 API 符号命中文件 ⊆ B1 文件集；A2/B3/B4 零相互直调（B1 AC-43） | **未落地**（脚本 TODO 注记在案） |
|
||||
| S8 | 结算路径 `await` 零命中（B1 结算/编排文件集）；字面量扫描 = warning 级 + 人工三要素复核（D2 AC-14 口径） | **未落地**（脚本 TODO 注记在案） |
|
||||
|
||||
域外扩充两件（非 ADR-0004 范围，均硬失败在位）：**S9** 类型闸（`tools/audit_type_hints.py`，迭代 27 T5——产品码无类型容器/有值返回缺类型/参数缺类型）；**S10** 文件头闸（`tools/audit_file_headers.py`——头注 ≤8 行 + 日期/变更叙事黑名单）。
|
||||
域外扩充两件（均硬失败在位）：**S9** 类型闸（`tools/audit_type_hints.py`，迭代 27 T5——产品码无类型容器/有值返回缺类型/参数缺类型）；**S10** 文件头闸（`tools/audit_file_headers.py`——头注 ≤8 行 + 日期/变更叙事黑名单）。
|
||||
|
||||
### 依赖约束
|
||||
|
||||
@@ -184,7 +184,7 @@
|
||||
|
||||
### 事实源声明
|
||||
|
||||
本节取代 ADR-0004 作为测试域（测试载体、判定口径、静态扫描域）的事实源；ADR-0004 原文保留为历史变更记录，不回改。新增违规案例仍须先补 static_scan 规则再修码（code-conventions 缺陷-规范对照表纪律）。
|
||||
本节为测试域（测试载体、判定口径、静态扫描域）的事实源。新增违规案例仍须先补 static_scan 规则再修码（code-conventions 缺陷-规范对照表纪律）。
|
||||
|
||||
---
|
||||
|
||||
@@ -200,7 +200,7 @@ Input（鼠标）→ D1 输入翻译 → 意图对象 → A2.settle_batch（唯
|
||||
```
|
||||
|
||||
- 回合制下每帧只做：输入采样、呈现刷新、动效推进——**玩法状态只在意图事务内变更**（单意图帧输入收集：stop 点击终结当帧）。
|
||||
- 无跨线程玩法数据流（Godot 主线程假设，D2 EC13）；A1 生成若引入 WorkerThread 须走 ADR-0005 裁决（join 先于任何快照切出）。
|
||||
- 无跨线程玩法数据流（Godot 主线程假设，D2 EC13）；A1 生成若引入 WorkerThread，join 必须先于任何快照切出（既定约束）。
|
||||
|
||||
### 2. 事件/信号路径（系统间通信，无紧耦合）
|
||||
|
||||
@@ -213,7 +213,7 @@ B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)─
|
||||
D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name
|
||||
```
|
||||
|
||||
- **载体裁决待 ADR-0001**：切片事实 = 组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；推荐沿用（单线程回合制，KISS），autoload 全局事件总线为否决倾向。
|
||||
- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。
|
||||
- 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。
|
||||
|
||||
### 3. 存档/读档路径（MVP 无存档；契约已锁）
|
||||
@@ -226,7 +226,7 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB
|
||||
|
||||
```
|
||||
进程启动
|
||||
→ autoload 实例化：ConfigDB → RngService（顺序固定；战斗编排器为普通类、由组合根按局实例化——切片形态）
|
||||
→ autoload 实例化：ConfigDB → RngService → SaveManager → MetaProgression（顺序固定；战斗编排器等核心类为普通类、由组合根按局实例化）
|
||||
→ ConfigDB._ready()：load_tables 加载 + 校验（致命通道；失败 = 构建中止 + 错误清单）
|
||||
→ 主场景（D1 组合根）装配视图单元 + 信号接线
|
||||
→ C2 begin_run：RngService.set_master_seed()（唯一接线方；两流计数器全零前提）
|
||||
@@ -254,77 +254,7 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB
|
||||
| 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 审计
|
||||
|
||||
**现存 ADR：7 份**（adr-0001–0007，`design/dev/architecture/`；ADR＝变更记录留档、非事实源，2026-10-15 立规）。以下子节为 2026-09-12 时点的盘点快照，保留留档；其中「现存 ADR：0 份」与「ADR 覆盖 0 条」均为当时实况，非现行状态。
|
||||
|
||||
### 已锁决策盘点（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 + design/dev/code-conventions.md（切片教训批） |
|
||||
|
||||
### GDD 登记的「实现期 ADR 裁决项」汇总（= ADR 立项清单的来源）
|
||||
|
||||
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）。
|
||||
|
||||
### 溯源覆盖检查
|
||||
|
||||
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（基础层四项）已落定 → 正式工程骨架解冻**；ADR-0005~0008 随对应系统开工前裁决（切片代码可作为参考实现，生产化迁移待 ADR-0008 正式化批）。
|
||||
|
||||
---
|
||||
|
||||
## ADR 立项清单
|
||||
|
||||
### 必须在正式编码开始前（基础层裁决）——✅ 已全部落定（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 关闭形态）。
|
||||
|
||||
实现级立场已登记 `design/registry/architecture.yaml`。
|
||||
|
||||
### 相关系统开工前应有
|
||||
|
||||
> ⚠ 编号漂移注记（2026-10-15 查）：实际落地的 adr-0006＝board-node2d-rendering（棋盘/舞台 Node2D 渲染）、adr-0007＝rng-single-stream（RNG 单流收口），与本清单原计划的「0006 生成性能 / 0007 单元 API 归属」编号错位；下述 5–8 项的编号计划按实际占用顺延重排，重排归属归 ADR 立项批裁决。
|
||||
|
||||
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`）：基础层收口——SCHEMA_VERSION 比较归属 + RNG 快照切点契约 ADR 化（TR-d2-010 / TR-gc-002），基础层零缺口闭合。
|
||||
|
||||
### 可推迟
|
||||
|
||||
- ADR-0010 A1 EC5 运行期熔断（连续降级确定性回退已知好种子）
|
||||
- ADR-0011 B5 战斗舞台（棋盘上 vs 独立场景）——"战斗表现美术测试"后裁决
|
||||
- ADR-0012 A5 探测显影接口
|
||||
- ADR-0013 D3 存档格式（RNG 快照契约已由 ADR-0005 锁定，格式归 Alpha）
|
||||
- C2/C3/C4 结构性决策随各系统 GDD 立项
|
||||
**引擎类型核验注记**：接口使用的引擎类型 = Resource / .tres（D2 全表）、RefCounted（容器类）、Signal/Callable（事件载体）、Control/CanvasLayer/Drawing（D1）、SceneTree headless 协议（测试）——均属 4.x 基线稳定面；4.7 Control 域增量（offset_transform_* 等）已在 breaking-changes.md 登记，D1 采纳前对照核实。
|
||||
|
||||
---
|
||||
|
||||
@@ -344,13 +274,17 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在）
|
||||
|
||||
| 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-01 | 渲染器选择（Forward+ vs gl_compatibility）与项目窗口基线 | High | **已落定**（2026-09-12）：gl_compatibility + 1280×800 基座（canvas_items + expand）；沿革见 git 历史 |
|
||||
| QQ-02 | 事件总线载体与 A2 事件捕获测试 API | High | **已落定**（2026-09-12）：组合根直连 signal + Waiting 相位触发；autoload 全局总线否决 |
|
||||
| QQ-03 | gdUnit4 是否引入并迁移冒烟用例 | Medium | **已落定**：deferred（现行双载体承载；D2 OQ1 关闭） |
|
||||
| QQ-04 | 轮内刷新数值连锁（清图支配性条款⑤ / 真人刷图行为获取期望）重算 | Medium | playtest 实测 |
|
||||
| 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-08 | B5 双舞台陷阱（战斗发生在棋盘上还是独立场景） | Low（B5 前） | 战斗表现美术测试后裁决 |
|
||||
| QQ-09 | C3 消费 B1 对账输出的事实依赖回写 `design/gdd/02-系统清单.md` | Low | C3 GDD 定稿时 |
|
||||
| QQ-10 | `.claude/docs/director-gates.md` 缺失（TD-ARCHITECTURE/LP-FEASIBILITY 判据无载体） | Low | 补建 gate 定义文件或维持 solo/lean 模式约定 |
|
||||
| QQ-11 | A1 生成性能姿态（F2c 常数 C 定稿；切片实证 10×10/12×12 同步生成可接受，WorkerThread 留扩展） | Medium | A1 GDD 修订批 |
|
||||
| QQ-12 | 零伤害死局跨字段/跨表护栏落点（B2 OQ9；推荐 D2 跨表校验——切片 LevelTable 校验⑧先例） | Medium | D2 校验设计批 |
|
||||
| QQ-13 | A1 EC5 运行期熔断（连续降级确定性回退已知好种子） | Low | A1 GDD 修订批 |
|
||||
| QQ-14 | A5 探测显影接口 / D3 存档格式（RNG 快照契约已在案，格式归 Alpha） | Low | 秘宝域正式化 / D3 Alpha 设计批 |
|
||||
@@ -16,7 +16,7 @@ ID 前缀是跟随 GDD 文档名的事实约定，从未成文；`config_db`/`rn
|
||||
|
||||
## 1.4.1 文件头失守
|
||||
|
||||
main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后仍剩 31 行，约 2/3 是对 code-conventions §1.3 与 ADR-0001 的整段复制、场景结构/生命周期机制描述（对规约与代码零新信息）。
|
||||
main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后仍剩 31 行，约 2/3 是对 code-conventions §1.3 与架构文档的整段复制、场景结构/生命周期机制描述（对规约与代码零新信息）。
|
||||
|
||||
## 2.1 信号契约缺失（软锁）
|
||||
|
||||
|
||||
@@ -25,9 +25,9 @@
|
||||
|
||||
文件头注释只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8 行（不含空行，从文件首个非空行到首个非注释代码行）。写法权威 = Google Python Style Guide §3.8 + PEP 257（GDScript 官方风格指南对文件头零条款，语法近 Python，沿用其规范——不自造标准）。
|
||||
|
||||
白名单（只许五类，超出一类即违规）：①一行职责摘要——这是什么；②用途/验证问题一行——它为什么存在；③GDD 锚行（§1.4 格式）；④硬使用约束——使用本文件前必须知道的禁令，每条一行；⑤指路行——架构文档/ADR/契约文档的位置。
|
||||
白名单（只许五类，超出一类即违规）：①一行职责摘要——这是什么；②用途/验证问题一行——它为什么存在；③GDD 锚行（§1.4 格式）；④硬使用约束——使用本文件前必须知道的禁令，每条一行；⑤指路行——架构文档/契约文档的位置。
|
||||
|
||||
黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读对应迭代实现报告；与 code-conventions、ADR、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）。
|
||||
黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读对应迭代实现报告；与 code-conventions、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）。
|
||||
|
||||
机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限+黑名单机械可判子集；信号契约成文位置见 §2.1）。存量头注按白名单清偿后挂入收口闸序列；此间新增/改动的文件头必须即合规。
|
||||
|
||||
|
||||
@@ -61,6 +61,7 @@
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
|
||||
| 架构事实唯一源 | `design/dev/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |
|
||||
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |
|
||||
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
|
||||
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入 `design/registry` 或附录 |
|
||||
@@ -102,7 +103,7 @@
|
||||
|
||||
## 11. 文档生命周期：吸收即死
|
||||
|
||||
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、registry、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。
|
||||
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、registry、架构文档（`design/dev/architecture/architecture.md`）、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
- **TSCN 格式**：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 变大（可 Project > Tools > Upgrade Project Files 预升级）—— 🔵
|
||||
- **Glow 默认值大改**（blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排）；Mobile 渲染器 glow 重写 —— 🔵 D1/B5 用 2D Glow 时注意视觉基底已变
|
||||
- AStar2D/AStar3D/AStarGrid2D：`from_id` 被禁用/固体时返回空路径 —— ⚪（自研 BFS）
|
||||
- **新项目默认值**：Windows 渲染驱动 D3D12；3D 物理引擎 Jolt —— 🔵 创建 project.godot 时须知（本项目 2D、无 3D 物理，渲染驱动选择归实现期 ADR）
|
||||
- **新项目默认值**：Windows 渲染驱动 D3D12；3D 物理引擎 Jolt —— 🔵 创建 project.godot 时须知（本项目 2D、无 3D 物理；渲染驱动已定 = gl_compatibility，2026-09-12）
|
||||
|
||||
## 4.7（2026-06；4.7.2 = 本项目锁定版本）
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
| `rendering/rendering_device/driver.windows` | Vulkan（Forward+） | D3D12 | 4.6（新项目） |
|
||||
| `physics/3d/physics_engine` | GodotPhysics3D | Jolt | 4.6（新项目；本项目 2D、无 3D 物理，无关） |
|
||||
|
||||
本项目为 2D 棋盘 UI：stretch mode / aspect 的最终选择归渲染器实现期 ADR，但须知道**引擎新项目默认值已不是训练数据里的那个**——新建工程后检查这三项。
|
||||
本项目为 2D 棋盘 UI：stretch mode / aspect 已定（canvas_items + expand，2026-09-12），但须知道**引擎新项目默认值已不是训练数据里的那个**——新建工程后检查这三项。
|
||||
|
||||
## 2. GDScript 4.7 两条语义变化（建议入编码规范）
|
||||
|
||||
|
||||
Reference in new issue
Block a user