docs(反哺): 迭代 27/28/29 GDD 反哺点八条＋一条建议逐点裁决写入（2026-10-17 用户令「全部按推荐案」）——①③④⑤architecture.md v1.8：新增「战斗域装配现状」（结算五段/RunLedger 四账）与「呈现层装配与会话生命周期」（三屏壳/装配合同立条款不摘录表/RunScope 九阶段×五引用面矩阵认账/ModalFlow tags）两节＋初始化顺序补启动后置条件六条，呈现层 D1 行与实现实证读数换代；②code-conventions.md §4 第 7–12 条（S9 三规则口径/:= {} 不算债/type-hint-ignore 与 rng-seed-exempt 两豁免通道/禁裸 autoload/Variant 参数化口径）；⑥⑦⑨test-conventions.md 新增 §7 判定三硬闸（含新写测试件全类型标注写法纪律）与 §8 判定可靠性优先于覆盖率（含脚本错误静默中断断言的机制事实与自证义务）；⑧07 v1.4：㉖① 保留不注销、加 screen_flow_probe 机检承接注记。同步清三笔在册旧账：iter27/28/29 三份实现报告 git mv 往 reports/（06 条③迁位账清零，全库引用改指新路径、iter24/25/26 等已删报告死指针改「已退役（git 历史可考）」）；iter29 报告 §六第 0 项按合并现实（fff4f120，两红各自结案 dac9a94b/fcb8c3f8＋8c18b52b）改写；06 补登迭代 29 反哺专条（该批漏登）。登记时「16 层/十断言」读数按代码实态 17 项/11 条订正。非迭代批不占迭代号；active.md 改动留主区工作副本不随本批提交，等闸回执。
This commit is contained in:
DKChan committed
1 parent
d984d47c8c
commit
abe5f180fb
10 files changed
+137
-38
No files matched your search
@@ -2,13 +2,13 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.7
|
||||
- 最近更新：2026-10-16（④架构原则层名中文化补漏——原则 1 残留 Core/Feature 英文层名改中文；⑤模块归属命名规约描述同步 code-conventions 文件头新规——头注禁写文档链接，「实现 GDD：xxx」一类已废止）
|
||||
- 版本：1.8
|
||||
- 最近更新：2026-10-17（迭代 27/28 GDD 反哺点写入——新增「呈现层装配与会话生命周期」节（视觉层装配合同/三屏壳/RunScope 生命周期与存活性矩阵/ModalFlow tags 协议）、战斗域现状补结算五段与 RunLedger 四账、初始化顺序补启动后置条件六条，均 2026-10-17 用户裁按推荐案写入；实现实证行读数换代）
|
||||
- 引擎：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）均已立项成文
|
||||
- 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 28 已入库合并——冒烟 1125/0、单元 27 套件、本地五闸在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 29 已入库合并——冒烟 1127/0、单元 33 套（含 1 集成）、重闸按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
- 主程序可行性：跳过 — solo 模式
|
||||
|
||||
@@ -119,11 +119,16 @@
|
||||
| **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 | 无 |
|
||||
|
||||
### 战斗域装配现状（迭代 27——2026-10-17 用户裁写入）
|
||||
|
||||
- **结算五段**：B1 编排器的每轮结算序列拆为 `game/core/settlement/` 五个段类——GrantSegment（①授予段，含旗判与 counter/grant 助手单点）→ AuraSegment（②增益/减益段）→ CombatSegment（③战斗段）→ DecaySegment（④衰减段）→ VerdictSegment（⑤判定段，返回裁定，终局早退语义留 B1）。段序骨架冻结于 `SettlementTable.segment_order` 语义，B1 退为段序编排+接线；段类可直接 `new()` 单测（`settle_segments_test` 在役）。
|
||||
- **RunLedger 四账**：`game/core/run_ledger.gd` 单类持四本共享账——同调充能账／真视使用计数／冒险域计数器／统一冒险加算区。所有权：AdventureRunner 开局构造、全程唯一宿主；LevelRunner 经 `set_run_ledger` 下传装配 encounter；战斗侧（B1）经 `encounter["ledger"]` 拿引用、只走 read/append 原语族。审计 P1-4「共享可变字典跨三层三处可写」由「函数签名上不可见的共享引用」换成签名可见的显式类，时点语义（战末导出/开局回灌）逐字不变。
|
||||
|
||||
### 呈现层
|
||||
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 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 伴随件留壳层〕，探针契约面不变——棋盘 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**（呈现面拆分持续换代：组合根 main.gd + 三屏壳（MenuScreen/CampScreen/AdventureScreen）+ views/ 视图单元（现行承载面见「呈现层装配与会话生命周期」节；早期 9 单元清单与 LevelStripView 已随场景换代退役）；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 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 各教学条目） | 各上游 | 无 |
|
||||
@@ -132,6 +137,46 @@
|
||||
|
||||
---
|
||||
|
||||
## 呈现层装配与会话生命周期（迭代 27/28 完成反哺——2026-10-17 用户裁按推荐案写入）
|
||||
|
||||
### 三屏壳与组合根句柄面
|
||||
|
||||
- 呈现场景拆为三屏壳：MenuScreen（开始菜单屏）／CampScreen（营地屏）／AdventureScreen（冒险屏——内含关卡地图与战斗两容器）。
|
||||
- 屏成员经组合根 main.gd 一级句柄暴露（探针挂载假设 `main.X` 路径零迁移）；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。
|
||||
|
||||
### 视觉层装配合同
|
||||
|
||||
- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（现行 17 项，kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。
|
||||
- 全仓唯一落位口 = `_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟 V1d 源码断言判红；**改层序只改合同表**。
|
||||
- 具体层清单不复制进本文（双写失同步禁令）——查现行 17 项直接读 `main.gd`。
|
||||
|
||||
### 会话生命周期（RunScope）
|
||||
|
||||
- `run_scope.gd` = 纯状态承载 Node：零信号连接、零视图构建、零核心写调用（连接只在组合根，组合根经 `run_scope.X` 读写）。
|
||||
- 会话更替机制：`_begin_session()` 新建会话节点挂树、旧会话节点**整节点 `queue_free()`**——无独立收束函数，跨局字段清理靠节点释放机制（原手工复位清单随其消亡，新增跨局字段零新增泄漏点）；`_ready` 即建闲时会话，`run_scope` 永非 null。
|
||||
- **存活性矩阵**（九阶段 × 五引用面，2026-10-17 用户裁认账阶段划分；执行判据=冒烟 V3a–V3i。计划书原十阶段中「开局停点」与「地图选路」在现行流程同为关卡画面停点态、无可观测中间态，合并为一处断言）：
|
||||
|
||||
| 阶段 | run_scope | adventure | runner | settlement |
|
||||
|---|---|---|---|---|
|
||||
| ① 闲时 | 在树（闲时会话） | null | null | null |
|
||||
| ② 开局停点 | 在树 | alive | alive | null |
|
||||
| ③ 战斗中 | 在树 | alive | alive | alive |
|
||||
| ④ 结算后（胜利停点）／⑤ 选路页 | 在树 | alive | alive | both |
|
||||
| ⑥ 终局面 | 在树 | alive | alive | null |
|
||||
| ⑦ 回菜单收束 | 新闲时会话即刻在树（旧会话已释放——无真空窗） | null | null | null |
|
||||
| ⑧ 各模态开合后（设置/生涯/营地/调试） | 闲时会话零扰动 | null | null | null |
|
||||
| ⑨ 两连局+续玩断点 | 换全新会话在树 | alive | both | both |
|
||||
|
||||
- 三态记号沿用冒烟参数：**alive**=应有实例、**null**=必须缺位（实测非空判红）、**both**=按分支可空可活（如胜停点后走向选路或直接终局）。对象有值但已失效一律判「悬挂」红。
|
||||
- 第五引用面=四持句柄件（`_treasure_ui`／`_bonus`／`_camp_pres`／`_modal_flow`，另有 `_row_pacer`）：其会话取值 Callable 与 `run_scope` 成员**逐面同源比对**（回调悬挂=两值不等即红），会话更替零残留由矩阵每阶段顺带铁证。
|
||||
|
||||
### 模态编排（ModalFlow/ModalStack）
|
||||
|
||||
- `modal_flow.gd` = 模态编排纯逻辑类（依赖仅 ModalStack + 查询 Callable，可直接 `new()` 单测）：开合编排（遮挡记账单口 + T17 演播后排窗挂起）／棋盘输入锁谓词／角标置灰谓词三职责。
|
||||
- 互斥排除语义随层登记（`register(node, tags)`）：`debug_overlay=["non_locking"]`、`level_screen=["screen_state"]`，其余层零标签——原调用点排除式条件拼装已消亡。
|
||||
|
||||
---
|
||||
|
||||
## 测试与质量域
|
||||
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。
|
||||
@@ -259,6 +304,15 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB
|
||||
→ 关卡末：通关结算（钥石/GP/专长 level_clear 渠道——现行语义归 冒险结构 GDD；原 clear_inventory 随库存轴下线退役 2026-09-15）
|
||||
```
|
||||
|
||||
**启动后置条件**（2026-10-17 用户裁入册——迭代 28 以冒烟 V2a–V2f 共 11 条断言把「启动完成后玩家该看到什么」成文；执行判据事实源在 `game/smoke/smoke_all.gd`）：
|
||||
|
||||
1. ConfigDB 就绪且表已载（`is_ready` + hero 表在座）。
|
||||
2. 系统设置已落引擎态——Master 音量 mute/volume_db = settings_store 现值；减动效开关 = `UiKit.motion_scale`。
|
||||
3. 启动态菜单可见（boot 后自树顶向下第一个可见内容层 = 开始层——菜单被冒险屏盖住即红）。
|
||||
4. 续玩钮可见态恒等于断点在档态（双向：无断点隐藏/有断点可见/清断点回隐；boot 路径与刷新单口同源）。
|
||||
5. 闲时会话已在树（`run_scope` 非空、非冒险会话、在树——永非 null 契约的启动侧证明）。
|
||||
6. 调试浮窗 boot 不自动开（菜单优先，2026-10-16 用户令）+ 调试入口全局浮层角标 boot 可见。
|
||||
|
||||
---
|
||||
|
||||
## API 边界
|
||||
|
||||
@@ -68,6 +68,12 @@
|
||||
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。
|
||||
5. **重命名脚本必须同步 `.uid` 文件**；新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存，否则 `--headless --script` 模式解析失败。
|
||||
6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**（迭代 27——2026-10-17 用户裁写入）——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码（`game/core`+`game/data`+`game/presentation`；smoke/tests 豁免——测量面容器直构是既有惯例）。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
8. **`:= {}` 推断形态不算债**——`var x := {}` 类赋值推断属类型推断合法面，不入 R1 扫描；只有显式写的非参数化容器注解才算无类型容器。
|
||||
9. **行级白名单通道 `# type-hint: ignore`**——豁免该行不入 S9；豁免理由必须随行注明（现行例：`board_generator` 四函数的 db 参鸭子型——typed 参拒冒烟夹具 `_BoardRowStub` 注入）。
|
||||
10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）。
|
||||
11. **`--script` 模式禁裸 autoload 标识符**——`ConfigDB`/`RngService` 等 autoload 名在 `--headless --script` 模式编译器不解析（parse error）；产品码与测试夹具一律经节点路径取用（`get_node("/root/…")`／`AUTOLOAD_PATH_*` 常量）；静态扫描域 S5 硬失败承载在位。
|
||||
12. **Variant 参数化现行口径**——账本类字典/数组标注 `Dictionary[Variant, Variant]`/`Array[Variant]` 即合格（满足 R1）；元素类型精化列后续事项、不入硬纪律，口径变更须用户裁决后续批次另行写入。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -65,3 +65,22 @@
|
||||
- **如实标注拦截边界**——判据本身只覆盖弱面的（如「只证伪整框空白／整框糊，不证明框里是何内容」），在断言注释与报告里写明边界，并说明强判据由哪一件承担。
|
||||
|
||||
**判据强弱分层**：同一缺陷面往往需要多件配合——**可见性／状态源类**缺陷由 `is_visible_in_tree`、树序、状态源取值的**运行期断言**抓；**内容／观感类**缺陷由 **golden 逐像素比对**抓；**占比／统计类**判据（墨色占比、纹理幅度）只能兜「整框空白／整框糊／压 busy 纹理」，是补充不是主力。写卡时按此分层配齐，别指望一条断言包打。
|
||||
|
||||
## 7. 判定三硬闸——闸承载的构造义务（迭代 29 三硬闸 2026-10-17 用户裁升格为纪律）
|
||||
|
||||
任何**新增或改写的闸承载**（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归架构文档「测试与质量域」节（本文不另列闸件清单）：
|
||||
|
||||
1. **退出码为唯一权威判据**——输出里的 PASS 串只作附加判据不作判据主体；打印 PASS 后 `quit(1)` 必须判红。
|
||||
2. **SCRIPT ERROR / Parse Error 扫描面在位**——GDScript 脚本错误不改进程退出码、不计失败数（机制事实见 §8），错误标记必须扫输出，且判据必须覆盖「跑了但半途脚本错误」态——退出码 0 但输出缺预期签名同样判红（防静默退出）。
|
||||
3. **断言数下限**——零断言的正常返回与断言失败必须区分开（现行做法：`Kit.finish` 零断言返回专用退出码 2，不与「断言失败=1」混用，否则致命类套件的期望码协议会放过空跑）。
|
||||
- 负面套件（测试目标就是产生错误输出）仅可豁免第 2 闸，且须在 manifest 显式标记，其余两闸照判。
|
||||
- 子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空。
|
||||
|
||||
**新写测试件全类型标注**（2026-10-17 用户裁写法纪律）——新写的测试件（冒烟断言／探针／单测）参数、返回值、容器一律带类型标注，与 S9 对产品码的要求同型；存量不强制清扫，被批次触碰时顺带换代。暂不机器闸（S9 扫描面=产品码，smoke/tests 豁免是测量面直构惯例的既有裁量）。
|
||||
|
||||
## 8. 判定可靠性优先于覆盖率（迭代 29 核心命题 2026-10-17 用户裁成节）
|
||||
|
||||
- 「跑一遍没崩＝通过」无效：测试绿只证明**当前代码没犯这个错**，不证明**犯了这个错会被抓住**；断言存在不等于断言执行。
|
||||
- **脚本错误会静默中断所在函数的剩余断言，而套件仍报全绿**（机制事实）：GDScript 无脚本错误陷阱 API，错误不改进程退出码、不计失败数。三处实证：①2026-09-19「309 项 0 失败」实为断言未跑全（状态记录 83）；②敌人表行集纪律 10 条断言因定型数组赋值错误从未执行（迭代 29 修复后两条正向见红＝夹具本缺锚行）；③`Callable` 形参类型写错致解析函数返回 null、后续断言整段蒸发。
|
||||
- 由此产生两条义务：**写闸件**按 §7 配三硬闸；**写验收函数**必须自证断言全数执行——变异验证（§6）为主证，反例实证（构造缺陷态改前判绿／改后判红）与零命中自检（扫描面为空即判红）为辅证。
|
||||
- **覆盖率不是目标**：行覆盖率度量缺失（Godot 无内建，第三方属新基建，是否引入 06 在册待裁）；现行补洞=零指名单测清单+人工判定，判定可靠性靠上列自证手段，不靠覆盖率数字。
|
||||
Reference in new issue
Block a user