docs(架构文档·知识沉淀批): 三件补文——通信形态选型理由(数据流§2:同步直连=可回放红线,Godot信号=同步派发,无事件循环)＋效果引擎「全同步解释器不是事件总线」定位(基础层表,删T3扩签冻结计数括注)＋架构原则9「停点权威在核心层」(两层阻塞机制)；十处删改——未决问题表已落定三行(QQ-01/02/03,gdUnit4决定迁测试与质量域)＋引擎知识缺口节压缩为engine-reference指针＋覆盖GDD行八计数普查改根索引指针＋层项「18项」两处冻结计数＋RngService流词表枚举改PURPOSE_TAGS指针(实测缺九流)＋存档路径节「MVP无存档」过时陈述与旧契约句修正(意图序列/窗口选择序列已非现行)＋MVP关键路径行＋数据流节重号4→5；doc-conventions §5新增「活体清单不冻结计数」(三实例评估)；architecture v1.14→v1.15；待办清单登记直改批
This commit is contained in:
DKChan committed
1 parent
ba90743806
commit
b6f11c1f8a
3 files changed
+26
-24
No files matched your search
@@ -2,11 +2,11 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.14
|
||||
- 最近更新：2026-10-26（改动域判据由路径前缀改为文件性质——`game/` 内 `.md` 归文档域）
|
||||
- 版本：1.15
|
||||
- 最近更新：2026-10-26（通信形态选型理由、效果引擎定位、架构原则 9 停点机制补文＋已落定未决项、过时陈述与冻结计数清扫）
|
||||
- 引擎：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）均已立项成文
|
||||
- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准）
|
||||
- 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；测试层级＝冒烟/单元/集成/系统四级＋UI 探针与渲染 golden（2026-10-22 用户裁，测试术语与层级重构批），闸机按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
@@ -16,13 +16,9 @@
|
||||
|
||||
## 引擎知识缺口摘要
|
||||
|
||||
- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/engineering/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。
|
||||
- 引擎事实现行事实源＝`design/engineering/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices 四件）——迁移核实结论、语义变化与编码注意一律查那里，本文不重复。
|
||||
- 渲染器与窗口基座＝gl_compatibility + 1280×800（2026-09-12 裁）；UI/渲染域为引擎风险集中地，采纳引擎增量前对照 engine-reference 核实。
|
||||
- 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。
|
||||
- 三类必须入编码纪律的引擎事实（详见 `design/engineering/engine-reference/godot/current-best-practices.md`）：
|
||||
1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。
|
||||
2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。
|
||||
3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。
|
||||
- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地——渲染器与窗口基座已定（gl_compatibility + 1280×800，2026-09-12），采纳引擎增量前对照文档核实。
|
||||
|
||||
---
|
||||
|
||||
@@ -77,7 +73,6 @@
|
||||
| D3 存档序列化 | 基础层 | Alpha | ✅ | LOW |
|
||||
| D6 设置/本地化 | 基础层 | 完整愿景 | ✅ | LOW |
|
||||
|
||||
**MVP 关键路径**（实现已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。
|
||||
**依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。
|
||||
|
||||
---
|
||||
@@ -91,11 +86,11 @@
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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()`；诊断收集器 | 无（基础层顶点） | 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（无） | 无——纯逻辑 |
|
||||
| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 |
|
||||
| **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh / notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；effect_engine（事件发射 dispatch——基础层内同层引用）；B1 回发 next_round_mode/battle_over | 无 |
|
||||
| **variation 定义**（A4） | VariationTable schema（现行 6 行：六 region——贫矿脉 global 行 2026-10-16 用户令屏蔽删行，global 型机制代码保留）与 F1 候选池门控谓词 | `variant_pool(level_index, board_type, node_type="")`（门控三维：unlock+board_types+节点身份——global 行仅 boss/elite 入池，缺省跳过零扰动）；`global_variant_row(level_index, board_type, node_type)`（全局型单行决议访问器） | ConfigDB（VariationTable） | 无 |
|
||||
| **status_container**（B3） | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 5 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB（StatusEffectTable） | 无（RefCounted） |
|
||||
| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：事件/事实/效果类型/算子四词表封闭（迭代 21 T3 扩签：EVENTS 18→19 +seal_missed 标错判定、FACTS +battle_index 关卡域战斗序）+ 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） |
|
||||
| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：全同步解释器——事件由宿主在明确代码点位显式调 dispatch 进件，命中序＝装载声明序（feats→treasure→树规则）写死保种子复放，不是事件总线/事件循环；事件/事实/效果类型/算子四词表封闭 + 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） |
|
||||
| **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 | 无 |
|
||||
|
||||
@@ -161,9 +156,9 @@
|
||||
|
||||
### 视觉层装配合同
|
||||
|
||||
- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（现行 18 项，kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。
|
||||
- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。
|
||||
- 全仓唯一落位口 = `_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟 V1d 源码断言判红；**改层序只改合同表**。
|
||||
- 具体层清单不复制进本文（双写失同步禁令）——查现行 18 项直接读 `main.gd`。
|
||||
- 具体层清单不复制进本文（双写失同步禁令）——查现行层项直接读 `main.gd`。
|
||||
|
||||
### 会话生命周期（RunScope）
|
||||
|
||||
@@ -194,7 +189,7 @@
|
||||
|
||||
## 测试与质量域
|
||||
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。第三方测试框架（gdUnit4）经 2026-09-12 评估不引入，现行测试载体＝本节自制闸体系。
|
||||
|
||||
### 模块归属
|
||||
|
||||
@@ -311,21 +306,20 @@ B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)─
|
||||
D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name
|
||||
```
|
||||
|
||||
- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。
|
||||
- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。选型理由＝可回放（架构原则 3）：同步直连让调用顺序显式可见，「同种子逐位相同」才可断言；Godot 信号本身就是同步函数派发，全库不存在事件循环。事件驱动形态服务的是并发/IO 场景对外部不确定时序的反应性，与本作「顺序确定」的需求相反。
|
||||
- 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。
|
||||
- **呈现层订阅禁令（切片缺陷②教训固化）**：呈现层永不直接订阅 排雷玩法／行动经济 的事件流，只订 战斗结算 步骤流与 `level_runner`——核心事件形态变化不得直接冲击界面。
|
||||
|
||||
### 3. 存档/读档路径（MVP 无存档；契约已锁）
|
||||
### 3. 存档/读档路径
|
||||
|
||||
- MVP 无元进度持久化（C4/D3 归 Alpha）。**已锁契约**：续玩/复盘快照 = master_seed + 各流 scope 计数器 + 意图序列 + 窗口选择序列；快照切出须发生在无正在执行中的 `open_stream` 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）。
|
||||
- 可回放性已实证：切片冒烟同种子双跑步骤流逐行相同（B1 AC-33 前身）。
|
||||
- D3 Alpha 期按此契约设计格式；SCHEMA_VERSION 高版本拒读。
|
||||
- 存档系统已实装：格式、三槽位、断点域与迁移链的现行契约以 `design/gdd/systems/表现与支撑/存档序列化.md`（owner）为准。
|
||||
- RNG 快照契约（现行仍成立）：断点续玩回填 = master_seed + 各流 scope 计数器；快照切出须发生在无正在执行中的 open_stream 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）；SCHEMA_VERSION 高版本拒读。
|
||||
|
||||
### 4. 打包与字体（CJK 随包发行）
|
||||
|
||||
CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无中文字形。此项是 HUD框架 正式化的硬性前置，同时进导出 checklist 核对项。
|
||||
|
||||
### 4. 初始化顺序
|
||||
### 5. 初始化顺序
|
||||
|
||||
```
|
||||
进程启动
|
||||
@@ -380,6 +374,7 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无
|
||||
6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边 = A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象（切片 1100 行 main.gd 反面案例 → 9 单元拆分）。
|
||||
7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷 ①②④⑤ 教训沉淀）。
|
||||
8. **系统无状态**——效果引擎这类系统零运行时可变状态：数据由宿主对象持有并随宿主生灭，状态按参数传入系统，系统只做判定（立项判据=2026-10-19 用户会话裁定；落地=迭代 32 卡②，2026-10-21 用户裁写入）。系统实例不持计数器——计数器住桶（round/battle/level/adventure 四桶，EffectContext 引用束），桶住宿主。
|
||||
9. **停点权威在核心层**——玩家决策停点（选路、三选一、商店、恢复这类）的推进守卫住核心层状态机：停点未兑付，推进口一律拒绝（零自动推进契约）；呈现层模态只做开合与输入锁——阻塞是两层结构，核心守卫为权威、模态为体验；停点态是核心状态、随断点序列化，headless 跑批与真实局同一套规则，中断续玩恢复到同一停点。
|
||||
|
||||
---
|
||||
|
||||
@@ -387,9 +382,6 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无
|
||||
|
||||
| ID | Summary | Priority | Resolution Path |
|
||||
|----|---------|----------|-----------------|
|
||||
| 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 调参 + 切片数据复测 |
|
||||
|
||||
@@ -69,6 +69,7 @@
|
||||
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |
|
||||
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |
|
||||
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |
|
||||
| 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 |
|
||||
|
||||
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。
|
||||
|
||||
|
||||
@@ -19,6 +19,15 @@
|
||||
|
||||
**状态**：待文档设计
|
||||
|
||||
#### 架构文档知识沉淀与冻结计数清扫批——通信选型理由/效果引擎定位/停点原则补文＋过时陈述删改（2026-10-26 登记，来源=会话提及）
|
||||
|
||||
**实况**：来源＝AdventureRunner 拆分设计会话（原会话进行中）的架构讨论沉淀＋顺带删除扫描，方案经用户逐条审毕。三件补文＋十处删改落 architecture.md（v1.14→v1.15）；含可选项＝MVP 关键路径行删除与 doc-conventions §5「活体清单不冻结计数」规则（用户审定顺带执行）。总线不立的裁定与现行登记一致，零动作。证据＝三处实测——RngService 行流词表记 2 流而 game/core/rng_service.gd:9 PURPOSE_TAGS 实为 11 流；层项「18 项」两处计数写死（v1.14 视觉层装配合同节）；数据流§3「MVP 无存档」与存档系统现行事实（game/core/save_manager.gd，存档序列化.md v7）相反。
|
||||
- 相关文档：design/engineering/architecture/architecture.md v1.15（本批产出）
|
||||
|
||||
**改动面**：文档
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交）
|
||||
|
||||
**实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。
|
||||
|
||||
Reference in new issue
Block a user