From f22adb55645e21224b894c10dd768fac28eeaf50 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Thu, 15 Oct 2026 23:02:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=90=BD=E5=BA=93=2010-15=20=E6=97=A5?= =?UTF-8?q?=E9=97=B4=E6=9C=AA=E6=8F=90=E4=BA=A4=E6=96=87=E6=A1=A3=E6=94=B9?= =?UTF-8?q?=E5=8A=A8=E2=80=94=E2=80=94architecture.md=20v1.5=EF=BC=88?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E4=B8=8E=E8=B4=A8=E9=87=8F=E5=9F=9F=E8=8A=82?= =?UTF-8?q?=E8=BF=81=E5=85=A5+=E4=B8=AD=E6=96=87=E5=8C=96+=E7=8E=B0?= =?UTF-8?q?=E7=8A=B6=E5=90=8C=E6=AD=A5=EF=BC=89/=20CLAUDE.md=20=E8=A7=84?= =?UTF-8?q?=E7=BA=A6=E5=AF=BC=E8=88=AA=E8=A1=A8=E5=8E=BB=20adr=20=E6=8C=87?= =?UTF-8?q?=E9=92=88=EF=BC=88=E5=90=8C=20diff=20=E5=88=A0=E4=BA=86=20RNG?= =?UTF-8?q?=20=E5=8D=95=E7=82=B9=E7=BA=A2=E7=BA=BF=E4=B8=80=E8=A1=8C?= =?UTF-8?q?=EF=BC=8C=E7=96=91=E4=BC=BC=E8=AF=AF=E5=88=A0=EF=BC=8C=E7=94=B1?= =?UTF-8?q?=20ADR=20=E6=B8=85=E9=99=A4=E6=89=B9=E5=A4=84=E7=90=86=EF=BC=89?= =?UTF-8?q?/=2002-=E7=B3=BB=E7=BB=9F=E6=B8=85=E5=8D=95=E8=A1=A5=2008-Alpha?= =?UTF-8?q?=20=E7=99=BB=E8=AE=B0=E8=A1=8C=EF=BC=8810-13=20=E9=81=97?= =?UTF-8?q?=E7=95=99=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 5 +- design/dev/architecture/architecture.md | 212 +++++++++++++++--------- design/gdd/02-系统清单.md | 2 + 3 files changed, 140 insertions(+), 79 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5271cdbf..b7574ee2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ - `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格） - `design/registry/` — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记） - `design/art/` — 美术纯文档（圣经/清单/提示词卡 + references/）；评估调研归 `design/research/`；不放图片 -- `design/dev/` — 工程规范（五份规约 + architecture(ADR) + engine-reference） +- `design/dev/` — 工程规范（五份规约 + architecture + engine-reference） - `design/qa/` — 验证报告 + QA 呈现产物图；`design/research/` — 调研/提案/评估/历史验收 - `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/` - `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/` — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成） @@ -45,7 +45,7 @@ | 写文档 / 改文档前 | `design/dev/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 | | 概念切分与互链 | `design/dev/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | | 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | -| 架构与决策记录 | `design/dev/architecture/architecture.md` + 同目录 `adr-*.md` | +| 架构 | `design/dev/architecture/architecture.md` | | 术语、已锁数值 | `design/registry/entities.yaml`——仅 owner 文档可修订，冲突须显式提出 | | 会话进度 / 路线图 | 根 `active.md`（状态文件：只记现在，每行当下为真；快照+未决面+滚动条目）· 根 `roadmap.md` | @@ -63,7 +63,6 @@ - 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务，禁以等目检为停工理由或收口前置 - 文件头 = `##` 文档注释 ≤8 行白名单制（code-conventions §1.4.1；写法权威 = Google Python Style Guide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py） - 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径 -- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流（ADR-0007） - Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退 - spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离） - 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节） diff --git a/design/dev/architecture/architecture.md b/design/dev/architecture/architecture.md index 596a6676..eb0cccb8 100644 --- a/design/dev/architecture/architecture.md +++ b/design/dev/architecture/architecture.md @@ -1,24 +1,24 @@ -# Dungeon Sweeper — Master Architecture +# Dungeon Sweeper — 总体架构文档 -## 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 +- 版本：1.5 +- 最近更新：2026-10-15（①新增「测试与质量域」节——测试域事实源自 ADR-0004 迁入承接；②全文标题/状态键/表头中文化；③现状同步：覆盖 GDD 改指现行中文域结构、现存 ADR 七份、实现实证改为完整游戏开发版本、四处失效路径订正） +- 引擎：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＝变更记录留档、非事实源；测试域事实源见本文「测试与质量域」节 +- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 28 已入库合并——冒烟 1125/0、单元 27 套件、本地五闸在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计 +- 技术总监签核：2026-09-12 — 有条件通过（条件：应立 ADR 于正式工程骨架搭建前定稿；`.claude/docs/director-gates.md` 缺失已登记技术债） +- 主程序可行性：跳过 — solo 模式 --- -## 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 协议均不受影响）。 +- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/dev/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`）： +- 三类必须入编码纪律的引擎事实（详见 `design/dev/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 表资源复制语义注意。 @@ -26,103 +26,105 @@ --- -## System Layer Map +## 系统分层图 -20 系统按 systems-index 依赖分层表（systems-design 门禁已评审）映射到标准五层。切片实现已验证该分层（core/ 纯逻辑零 UI 依赖 headless 可跑、presentation/ 组合根模式）。 +20 系统按 `design/gdd/02-系统清单.md` 依赖分层表映射到标准五层。实现已验证该分层（core/ 纯逻辑零 UI 依赖 headless 可跑、presentation/ 组合根模式）。 ``` ┌────────────────────────────────────────────────────────────┐ -│ PRESENTATION LAYER │ -│ D1 HUD 与界面框架 (MVP) · B5 战斗表现 (切片后) │ -│ D4 音频 (Alpha) · D5 教学引导 (Alpha) │ +│ 呈现层 │ +│ D1 HUD 与界面框架 (MVP) · B5 战斗表现 │ +│ D4 音频 (Beta) · D5 教学引导 (Beta) │ ├────────────────────────────────────────────────────────────┤ -│ FEATURE LAYER │ -│ B1 战斗结算编排 (MVP) · C1 关卡节点地图 (切片已含 lite) │ +│ 功能层 │ +│ B1 战斗结算编排 (MVP) · C1 关卡节点地图 (lite 已实装) │ │ C2 冒险结构 · C3 难度曲线 · C4 元进度 (Alpha) │ ├────────────────────────────────────────────────────────────┤ -│ CORE LAYER │ +│ 核心层 │ │ A1 扫雷棋盘生成 · A2 排雷玩法规则 · B2 敌人系统 │ -│ B4 地图战斗资源 · A5 扫雷秘宝 (垂直切片) │ +│ B4 地图战斗资源 · A5 扫雷秘宝 │ ├────────────────────────────────────────────────────────────┤ -│ FOUNDATION LAYER │ +│ 基础层 │ │ D2 数据配置与数值表 · A3 行动经济 · A4 地形变异 │ │ B3 增益/状态系统 · D3 存档序列化 (Alpha) · D6 设置/本地化│ ├────────────────────────────────────────────────────────────┤ -│ PLATFORM LAYER │ +│ 平台层 │ │ Godot 4.7.2 引擎 API 面（GDScript / Resource / │ │ SceneTree / Control / InputEvent）——无游戏系统 │ └────────────────────────────────────────────────────────────┘ ``` +> 层名对照：基础层＝Foundation、核心层＝Core、功能层＝Feature、呈现层＝Presentation、平台层＝Platform——本文一律用中文名；跨文档与代码目录仍见英文名（`game/core/`、`game/presentation/` 等目录名不改）。 + | 系统 | 层 | 里程碑 | 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 | +| D2 数据配置 | 基础层 | MVP | ✅ 完整可跑 | LOW（Resource/.tres 基线稳定） | +| A3 行动经济 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） | +| A4 地形变异 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） | +| B3 状态系统 | 基础层 | MVP | ✅ 完整可跑 | LOW（RefCounted 纯逻辑） | +| A1 棋盘生成 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑；性能姿态归 ADR-0005） | +| A2 排雷规则 | 核心层 | MVP | ✅ 完整可跑 | LOW（零表读取零 UI） | +| B2 敌人系统 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） | +| B4 地图战斗资源 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） | +| B1 战斗结算编排 | 功能层 | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑；事件载体归 ADR-0001） | +| C1 关卡节点地图 | 功能层 | MVP（切片期实装） | ✅（切片 level_runner 先例） | LOW | +| C2 冒险结构 | 功能层 | MVP（切片期实装） | ✅ | LOW | +| C3 难度曲线 | 功能层 | MVP（切片期实装） | ✅ | LOW | +| C4 元进度 | 功能层 | Alpha | ✅ | LOW | +| D1 HUD | 呈现层 | MVP | ❌（UI 层——场景级探针测试承载） | **MEDIUM**（Control/Input/文本域） | +| B5 战斗表现 | 呈现层 | 切片后立项（未实装，前置战斗表现美术测试） | ❌ | **MEDIUM**（Animation/Tween/渲染） | +| D4 音频 / D5 教学 | 呈现层 | Beta（2026-10-13 Alpha 版本标准裁：与游戏内容无关者一律排 Beta） | 部分 | LOW-MEDIUM | +| D3 存档序列化 | 基础层 | Alpha | ✅ | LOW | +| D6 设置/本地化 | 基础层 | 完整愿景 | ✅ | LOW | -**MVP 关键路径**（切片已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。 +**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/…）。切片已按此规范完成领域命名批。 +> 命名遵循 `design/dev/code-conventions.md`：领域命名、禁 ID 前缀、头注溯源行（实现 GDD：design/gdd/…）。切片已按此规范完成领域命名批。 -### Foundation 层 +### 基础层 -| 模块 | Owns（独占） | Exposes | Consumes | 引擎 API | +| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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 | +| **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()`；诊断收集器 | 无（基础层顶点） | 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 | 无 | +| **save_system**（D3，Alpha；iter27 已升格 autoload「SaveManager」） | 存档格式与版本比较 | （契约规范源：`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚：SCHEMA_VERSION + master_seed + 各流 scope 计数器快照，须在无在飞 open_stream 实例时切出） | ConfigDB、RngService 只读计数器 | FileAccess——LOW | +| **settings/localization**（D6，愿景） | 设置项、翻译数据 | （契约规范源：`../../gdd/systems/表现与支撑/设置与本地化.md`） | ConfigDB | 无 | -### Core 层 +### 核心层 -| 模块 | Owns | Exposes | Consumes | 引擎 API | +| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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 | 无 | +| **helper_items**（A5，切片已实装秘宝域） | HelperItemTable、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 | -### Feature 层 +### 功能层 -| 模块 | Owns | Exposes | Consumes | 引擎 API | +| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| | **battle_orchestrator**（B1） | 段序骨架（七段结构冻结）、轮 facts 缓冲、可回放步骤流、[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（15 类行 + 字段分层）、条款③⑤闭合对账、**战斗域全部跨系统调用权**、效果引擎宿主（每战 rebuild/战末 adventure 计数器导出回写）+ 树规则挂点施加面（posture 窗/sense 限次/守侧 flag_missed 发射/聚乘算入账前） | `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 冒烟实证可回放） | -| **effect_engine**（Core——内容数据驱动扩展批 iter17 建域） | 事件/事实/效果类型/算子四词表封闭（迭代 21 T3 扩签：EVENTS 18→19 +flag_missed 标错判定、FACTS +battle_index 关卡域战斗序）+ 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·domain=adventure 跨战斗持久） | rebuild（每战重建）/dispatch/validate_trigger_row/counters_export·counters_seed | ConfigDB（feats/treasure 行集） | 无（零随机全确定） | +| **effect_engine**（核心层——内容数据驱动扩展批 iter17 建域） | 事件/事实/效果类型/算子四词表封闭（迭代 21 T3 扩签：EVENTS 18→19 +flag_missed 标错判定、FACTS +battle_index 关卡域战斗序）+ 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·domain=adventure 跨战斗持久） | rebuild（每战重建）/dispatch/validate_trigger_row/counters_export·counters_seed | ConfigDB（feats/treasure 行集） | 无（零随机全确定） | | **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 | 无 | +| **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （契约规范源：`../../gdd/systems/冒险循环/冒险结构.md`） | RngService.set_master_seed、C3/D2 | 无 | | **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 | | **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编） | tree_can_buy/tree_buy/tree_buy_fork/tree_toggle_fork（写口唯一）、hero_override 注入（树淬炼 flat+锻造路线加值位预留 0）、tree_rule_keys | D3、C2、ConfigDB | 无 | -### Presentation 层 +### 呈现层 -| 模块 | Owns | Exposes | Consumes | 引擎 API | +| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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 图片参数两轮变化） | -| **battle_presentation**（B5，垂直切片后） | 结算动画 / 伤害数字 / 战斗舞台 | （未设计——前置"战斗表现美术测试"锁双舞台陷阱） | B1 步骤流（回放脚本源）、D1 | **MEDIUM**：AnimationPlayer（String→StringName 变更）/ Tween | +| **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 各教学条目） | 各上游 | 无 | @@ -130,7 +132,63 @@ --- -## Data Flow +## 测试与质量域 + +> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。原登记于 ADR-0004 的测试载体与静态扫描域约束已迁入本节承接；ADR-0004 保留为历史变更记录，不回改、不再作为现行依据引用（2026-10-15 立规：ADR = 变更记录，不是事实源）。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。 + +### 模块归属 + +| 模块 | 载体 | 独占职责 | 对外暴露 | 判定口径 | +|---|---|---|---|---| +| **run_smoke**（系统级断言面） | `tools/run_smoke.py` | 冒烟总入口与判定权：headless 跑 `res://smoke/smoke_all.gd` 全量（轻闸首项，迭代 28 后在册 1125 项检查）+ 三闸判定 | 进程退出码（0=PASS / 1=FAIL） | 三闸齐备、判定无洞：①退出码 = 0；②摘要行「冒烟完成：N 项检查，0 项失败」在案且失败数为 0；③输出扫 `SCRIPT ERROR` / `Parse Error` 标记行。外部 wall-clock 超时在位（超时 = FAIL） | +| **run_all**（单元套件） | `game/tests/run_all.gd` | 27 套件单元测试统一入口：套件 manifest 逐条「套件 → 期望退出码」，致命类 expect=1 独立子进程实跑 | 逐套件结果 + 汇总退出码（任一套件失败 quit(1)） | 套件级退出码协议在位；**SCRIPT ERROR 扫描缺失**（脚本错误不改套件退出码时静默漏过）；**断言数下限缺失**（套件零断言退出 0 照样绿） | +| **probe_gate**（场景探针） | `tools/probe_gate.sh` | headless 场景探针段编排：默认段 ui_input_probe / ui_struct_probe / ui_contrast_probe，`--click` 加跑 ui_click_probe，`--full` 加跑 ui_probe / ui_tune_probe / t17_defer_probe / fx_probe；孤儿 Godot 预清 + 批末残留清点（必须 0） | 段级 FAIL 输出 + 汇总退出码 | 每段 timeout 守卫在位（挂死 124/137 = FAIL，不静默）；**多数探针不查进程退出码**（仅个别段以 grep PASS 标记兜底）——退出码判定缺失 | +| **render_gate**（视觉 golden） | `tools/render_gate.sh` | 窗口化渲染闸：①shot_probe 七屏截图 → shot_checker A-D 语义断言；②fx_shot_probe / board_shot_probe 取证（超时/零字节/文件缺失任一 = FAIL）；③棋盘 golden 逐像素容差比对（差 ≤16 / changed ≤2%，provisional）+ 菜单 golden；④批末孤儿残留清零 | 段级 FAIL 输出 + 汇总退出码 | 查退出码在位（每段 timeout 守卫 + 退出码/取证文件双检）；**SCRIPT ERROR 扫描缺失**；断言数下限不适用（判定主体 = golden 容差与取证文件存在性，非断言计数） | +| **static_scan**（静态扫描域） | `game/tests/static_scan.sh` | 静态扫描域 S1–S10 可执行载体（grep 规则 + `tools/audit_type_hints.py`〔S9〕+ `tools/audit_file_headers.py`〔S10〕） | fail 聚合退出码（任一硬失败规则命中即 exit 1） | 查退出码在位；SCRIPT ERROR 扫描与断言数下限不适用（逐规则命中即红，无运行时错误面与断言计数）；S3 现为 warning 级、不参与 fail 判定（见下表） | + +### 三条判定硬闸现行状态 + +| 硬闸 | run_smoke | run_all | probe_gate | render_gate | static_scan | +|---|---|---|---|---|---| +| **退出码优先** | 已落实（闸①） | 已落实（套件 manifest expect 协议） | **缺失**（多数探针不查退出码） | 已落实（段级退出码 + 取证双检） | 已落实（fail 聚合退出） | +| **SCRIPT ERROR 扫描** | 已落实（闸③，外部扫描——GDScript 无脚本错误陷阱 API，闸设在外部包装） | **缺失** | **缺失** | **缺失** | 不适用（静态域无运行时错误面） | +| **断言数下限** | 无独立下限（闸②摘要行必须在案，防「跑一半仍 PASS」；脚本错误吞断言路径由闸③兜住） | **缺失**（27 套件跑完不校验断言总数，零断言套件可绿） | 不适用（逐段 PASS 标记判定，无断言总数概念） | 不适用（golden 容差 + 取证存在性判定） | 不适用（逐规则命中判定） | + +背景事实（run_smoke 头注在案）：GDScript 运行时脚本错误不改进程退出码、不计入冒烟失败数、且静默中断所在函数剩余断言——2026-09-19 台账 83 实证「309 项 0 失败」实为断言未跑全。这是 SCRIPT ERROR 扫描必须存在于判定层的原因。 + +### 静态扫描域 S1–S8 承接清单 + +规则语义源自 ADR-0004 §Decision 3（原文留档不动，下表为现行事实登记）： + +| # | 规则 | 状态 | +|---|---|---| +| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator`（D2 Rule 5） | **在位**（硬失败；扫描面 game/core + game/presentation） | +| S2 | 禁全局随机函数 `randi()` / `randf()` / `randf_range()`——全局 RNG 绕开 RngService（specialist 补登） | **在位**（与 S1 同段硬失败；实例方法 `.randi()` 排除、`ADR-0007-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 注记在案） | +| 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 行 + 日期/变更叙事黑名单）。 + +### 依赖约束 + +测试域不得反向依赖呈现层具体实现。五闸及其调用的探针场景、审计脚本只允许依赖两类边界： + +1. **autoload 边界**——ConfigDB / RngService 的公开面（--script 模式不加载 autoload 且不注册全局标识符，测试文件自带显式实例化夹具）； +2. **场景契约**——探针场景的信号外发面与视图单元接口（信号外发、setter 只读注入），禁直引呈现层实现内部（如 UiKit 工厂内部状态、BoardView 绘制细节）。 + +测试域是所有层的消费方，进入方式限于上述两类边界；除此之外的依赖方向一律与「模块归属」节依赖单向性同规。 + +### 事实源声明 + +本节取代 ADR-0004 作为测试域（测试载体、判定口径、静态扫描域）的事实源；ADR-0004 原文保留为历史变更记录，不回改。新增违规案例仍须先补 static_scan 规则再修码（code-conventions 缺陷-规范对照表纪律）。 + +--- + +## 数据流 ### 1. 帧更新路径（2D 回合制：无逐帧玩法逻辑） @@ -179,7 +237,7 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB --- -## API Boundaries +## API 边界 > 完整 API 面（含封闭枚举负空间、布尔受理口径、输入×相位矩阵）以各 GDD AC 前言为**规范源**——本节列边界契约与不变式，实现须与 GDD 逐字一致；冲突时以 GDD 为准并走接口漂移修订。 @@ -200,9 +258,9 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB --- -## ADR Audit +## ADR 审计 -**现存 ADR：0 份**（`docs/architecture/` 本文档为首个产物；此前架构约束由 GDD 门禁评审 + CLAUDE.md + code-conventions 事实承载）。 +**现存 ADR：7 份**（adr-0001–0007，`design/dev/architecture/`；ADR＝变更记录留档、非事实源，2026-10-15 立规）。以下子节为 2026-09-12 时点的盘点快照，保留留档；其中「现存 ADR：0 份」与「ADR 覆盖 0 条」均为当时实况，非现行状态。 ### 已锁决策盘点（GDD 层已定稿，不重复立项 ADR） @@ -216,13 +274,13 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB | 多敌 side-wide / 出招确定性（技能池批改型：零随机纪律保持、开轮摇号走 behavior_roll 封闭流）/ 固定顺位 / 伏击 cap=4 | B2（2026-09-09 用户拍板；2026-09-16 技能池批改型） | | 奖励五值两类交付轴 / install 预分配 / 关卡域库存 / 窗口单件制 | B4（2026-09-11 用户裁决批） | | weake­n 锚 F0 瞬时当量 / 条款①③⑤闭合对账 owner = B1 | B1 F0–F5 | -| 领域命名禁 ID 前缀 / 组合根模式 / 呈现层契约成文 | CLAUDE.md + docs/code-conventions.md（切片教训批） | +| 领域命名禁 ID 前缀 / 组合根模式 / 呈现层契约成文 | CLAUDE.md + design/dev/code-conventions.md（切片教训批） | -### GDD 登记的"实现期 ADR 裁决项"汇总（= Required ADRs 的来源） +### 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）。 -### Traceability Coverage Check +### 溯源覆盖检查 Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在）；按覆盖载体分层： @@ -232,23 +290,25 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 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 正式化批）。 +**结论：0 条孤儿需求**——46 条由本文档+GDD 承载、12 条待 ADR（见下）、5 条随未设计系统。**2026-09-12 更新：ADR-0001~0004（基础层四项）已落定 → 正式工程骨架解冻**；ADR-0005~0008 随对应系统开工前裁决（切片代码可作为参考实现，生产化迁移待 ADR-0008 正式化批）。 --- -## Required ADRs +## ADR 立项清单 -### 必须在正式编码开始前（Foundation 裁决）——✅ 已全部落定（2026-09-12，solo 授权代决，godot-specialist 校验通过） +### 必须在正式编码开始前（基础层裁决）——✅ 已全部落定（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`。 +实现级立场已登记 `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 校验⑧先例）。 @@ -256,7 +316,7 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 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 零缺口闭合。 +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），基础层零缺口闭合。 ### 可推迟 @@ -268,7 +328,7 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在） --- -## 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）。 @@ -280,7 +340,7 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在） --- -## Open Questions +## 未决问题 | ID | Summary | Priority | Resolution Path | |----|---------|----------|-----------------| @@ -292,5 +352,5 @@ Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在） | 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-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 模式约定 | diff --git a/design/gdd/02-系统清单.md b/design/gdd/02-系统清单.md index 438b6097..a8846104 100644 --- a/design/gdd/02-系统清单.md +++ b/design/gdd/02-系统清单.md @@ -15,6 +15,7 @@ | `术语表.md` | 全库专用术语的唯一对照表——危险格/安全格/同调位/RAP/GP/真视等定义+退役词对照（2026-10-11 建立，v1.0） | | `06-待办清单.md` | 全项目待办事项的唯一登记处；各系统文档的「待办」节只留指路存根 | | `07-体验验证清单.md` | 需要真人试玩观测的验证项登记处（与 06 分工：06 是"要拍板的事"，本篇是"要玩过才知道的事"）；每条注明结论回流路径 | +| `08-Alpha版本标准.md` | Alpha 版本包含哪些东西的清单——里程碑 M3 的完成标准；只列条目不写内容，定义一律指路各权威文档（**已定稿 v1.0**，2026-10-13） | ## systems/ 五个循环 @@ -154,3 +155,4 @@ | v1.22 | 2026-10-11 | 锻造工坊更名批随迁：`武器锻造.md` 改名 `锻造工坊.md`（系统更名，用户令），顶层文档表行与系统总表行随名换代并顺延版本注（v0.3）；版本历史行内旧名按历史记载保留 | | v1.23 | 2026-10-11 | 锻造工坊 A 组定案随迁：锻造工坊行版本注换代 v0.4（A 组三裁+攻防所有权切分〔树脊柱砍攻/护两线，树侧 29→21 归天赋树会话交接批〕+钥匙无前置+2c/5a 结案） | | v1.25 | 2026-10-12 | **锻造工坊 B 组定案随迁（用户逐点裁决）**：锻造工坊行版本注换代 v0.5、描述格随裁换代——两区定名（武器锻造区/护甲锻造区）、三甲型统一命名「魔法护甲」、一次冒险各选一件、**满级特效本期不做留扩展位**；**17 裁点清零**（推翻推荐案四行 2a/3b/6/8a，撤回呈报子问 4a-1），开工门裁点侧已满足、仅剩用户发令；设计文档「裁决结果清单」+「工作间内容清单」两节为实装批需求卡片输入 | +| v1.26 | 2026-10-13 | **Alpha 版本标准立文（用户令「先定里程碑内容」）**：顶层文档表补 `08-Alpha版本标准.md` 行——Alpha 版本包含哪些东西的清单，即里程碑 M3 的完成标准；只列条目不写内容，定义一律指路各权威文档。本文只管「有什么」，系统与内容的定义权仍归各自权威文档，本表不复制其内容 |