diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index c7db53d6..0449bbb4 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -93,7 +93,7 @@ | **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):全同步解释器——事件由宿主在明确代码点位显式调 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 已随迭代 39 拆件批退役,桶字典由 adventure_runner 持有) | 无(零随机全确定) | -| **save_system**(D3,Alpha;iter27 已升格 autoload「SaveManager」) | 存档格式与版本比较 | (契约规范源:`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚:SCHEMA_VERSION + master_seed + 各流 scope 计数器快照,须在无正在执行中的 open_stream 实例时切出) | ConfigDB、RngService 只读计数器 | FileAccess——LOW | +| **save_system**(D3,Alpha;iter27 已升格 autoload「SaveManager」) | 存档格式与版本比较 | (契约规范源:`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚:SAVE_FORMAT_VERSION + master_seed + 各流 scope 计数器快照,须在无正在执行中的 open_stream 实例时切出) | ConfigDB、RngService 只读计数器 | FileAccess——LOW | | **settings/localization**(D6,愿景) | 设置项、翻译数据 | (契约规范源:`../../gdd/systems/表现与支撑/设置与本地化.md`) | ConfigDB | 无 | ### 核心层 @@ -346,7 +346,7 @@ D1 ◀──呈现数据源:A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB ### 3. 存档/读档路径 - 存档系统已实装:格式、三槽位、断点域与迁移链的现行契约以 `design/gdd/systems/表现与支撑/存档序列化.md`(owner)为准。 -- RNG 快照契约(现行仍成立):断点续玩回填 = master_seed + 各流 scope 计数器;快照切出须发生在无正在执行中的 open_stream 实例时(scope 事件边界外——B1 编排保证:切点 = board install 边界);SCHEMA_VERSION 高版本拒读。 +- RNG 快照契约(现行仍成立):断点续玩回填 = master_seed + 各流 scope 计数器;快照切出须发生在无正在执行中的 open_stream 实例时(scope 事件边界外——B1 编排保证:切点 = board install 边界);SAVE_FORMAT_VERSION 高版本拒读。 ### 4. 打包与字体(CJK 随包发行) diff --git a/design/gdd/systems/表现与支撑/存档序列化.md b/design/gdd/systems/表现与支撑/存档序列化.md index 8dc2235e..66dd87d7 100644 --- a/design/gdd/systems/表现与支撑/存档序列化.md +++ b/design/gdd/systems/表现与支撑/存档序列化.md @@ -138,7 +138,7 @@ v4/v5/v6 各域缺键由读取方按默认值补齐(空集合/0),旧档零 | 版本更高(未来版本的档) | **拒读且禁写**:不加载、后续写盘一律拒绝、内存以默认新档运行——保护未来版本的档不被当前版本覆写 | | 版本更低(旧档) | 读档时逐级迁移:从旧版本起逐个调用注册的迁移函数升到当前版本;任一步失败按损坏兜底处理 | -迁移函数按旧版本号逐一注册:函数把数据从「旧版本」改写成「旧版本 + 1」。生产迁移链现行六件(v2 起自注册):v1→v2 = 断点域补空;v2→v3 = 断点附随件与摘要 keystone_drops 补键(读取方 .get 兜底);v3→v4 = 同调三域补键;v4→v5 = 树域两键补齐(原挂接的「三体系迁移」体已随迭代 21 T5 攻防所有权切分删除;forge_levels 旧域同批清退,加载时按默认模型键集白名单收窄);v5→v6 = 生涯两终身计数域补零;**v6→v7 = 锻造工坊域 forge_routes 缺键补齐(迭代 23 T5——无结构迁移体,版本号推进仅为表结构版本对齐;解锁态派生不落档:初始持有〔表 initial_owned〕∨ 直购〔unlocked 清单〕∨ 练满前一档〔levels[prereq]≥cap〕)**。任一步失败按损坏兜底处理。 +迁移函数按旧版本号逐一注册:函数把数据从「旧版本」改写成「旧版本 + 1」。生产迁移链现行六件(v2 起自注册):v1→v2 = 断点域补空;v2→v3 = 断点附随件与摘要 keystone_drops 补键(读取方 .get 兜底);v3→v4 = 同调三域补键;v4→v5 = 树域两键补齐(原挂接的「三体系迁移」体已随迭代 21 T5 攻防所有权切分删除;forge_levels 旧域同批清退,加载时按默认模型键集白名单收窄);v5→v6 = 生涯两终身计数域补零;**v6→v7 = 锻造工坊域 forge_routes 缺键补齐(迭代 23 T5——无结构迁移体,版本号推进仅随表结构变化;解锁态派生不落档:初始持有〔表 initial_owned〕∨ 直购〔unlocked 清单〕∨ 练满前一档〔levels[prereq]≥cap〕)**。任一步失败按损坏兜底处理。 旧单档一次性迁移(迭代 33 卡①,用户裁决 Q1 甲):本系统从单档制换代为 3 存档位制时,盘上残留的旧单档 `user://save.json` 在启动时被处理——文件**字节级原样搬运**进槽 1(`user://save_slot_1.json`,零解析零改造:损坏或高版本的旧档也原样迁入,之后由该槽进档时的损坏兜底/高版本拒读接管,不静默丢数据),源文件改名 `user://save.json.migrated.bak` 留痕不删;槽 1 文件已存在则不重迁(幂等,二次启动零操作);迁移失败(拷贝或改名失败)源文件保留、下次启动重试。留痕与结果记在启动日志(开发者向,非玩家面)。 diff --git a/design/gdd/systems/表现与支撑/数据配置.md b/design/gdd/systems/表现与支撑/数据配置.md index b3ec19da..c7d70409 100644 --- a/design/gdd/systems/表现与支撑/数据配置.md +++ b/design/gdd/systems/表现与支撑/数据配置.md @@ -28,7 +28,7 @@ | 不负责 | 归谁 | |---|---| | 各表数值定值与玩法公式 | 各回填责任方(清单见核心规则的表清单),平衡总归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | -| 存档格式与版本比较逻辑 | [存档序列化](存档序列化.md),本系统只出版本常量与随机快照契约 | +| 存档格式与版本比较逻辑 | [存档序列化](存档序列化.md),本系统只出随机快照契约 | | 界面呈现 | [HUD 框架](HUD框架.md) | | 随机用途的设计合理性 | 消费方系统自证(随机须有界、可见或可推理),新增随机走扩签通道 | @@ -155,7 +155,7 @@ | 下游 | [冒险结构](../冒险循环/冒险结构.md) | 关卡表与冒险表承载(登记现状见「待办」);主种子注入入口 | | 下游 | [难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | 难度表承载(占位);进度坐标查行的消费方 | | 下游 | [元进度](../跨局循环/元进度.md) | 元进度表占位承载 | -| 下游 | [存档序列化](存档序列化.md) | 表结构版本常量;随机快照契约(主种子 + 全局取数计数器) | +| 下游 | [存档序列化](存档序列化.md) | 随机快照契约(主种子 + 全局取数计数器) | | 下游 | [HUD 框架](HUD框架.md) | 调试热重载完成通知(仅调试构建) | | 外发 | 无订阅 | 本系统不订阅任何玩法事件 | @@ -186,7 +186,6 @@ | 参数 | 现行值 | 说明 | |---|---|---| | 表路径清单 | data/tables/ 固定(调试注入根除外) | 冻结:散装路径破坏单点访问 | -| 表结构版本 | 当前 = 2 | 全部表结构携带版本字段;高于当前支持的版本拒读,比较逻辑归[存档序列化](存档序列化.md) | | 随机流口径 | 统一流单盐单计数器 + 七用途标签封闭词表 | 统一口径为 2026-09-27 裁决;扩签 = 改代码 + 评审,有意设卡 | | 进度坐标解析策略 | 可取范围内向上取整 + 警告(保证偏难);超出最大行封顶取最大值 + 警告;域越界致命(2026-09-18 两段拍板,原「就近向下」退役) | 冻结:静默降难会掩盖难度断档 | | 入口锚行校验 | 写死开 | 非调参项;重议走文档修订流程 | @@ -202,7 +201,6 @@ - 向上取整解析:请求无精确行时返回**不低于**请求坐标的最近行并留一条警告;请求超出最大已有行时封顶取最大行并留警告;同类警告去重;精确命中零警告。 - 越域与未播种:坐标低于合法域(关卡序号 <1、节点深度 <0)在进入解析前致命中止(Fatal 级诊断 + 进程非 0 退出,无兜底);高于最大已有行走封顶取最大行(警告留痕,不致命);未设主种子就取随机数致命中止,无默认种子兜底。 - 热重载门:战斗中重载被拒绝且读数不变、不发通知;门未置位时新值可读且通知恰一次;校验失败保留旧表停留就绪态。 -- 版本常量在位:表结构版本常量存在且全部表结构携带版本字段(高版本拒读判定归存档序列化)。 - 零字面量、零第二路径:静态扫描加人工复核确认玩法代码无数值字面量、无读取口之外的表加载、无全局随机函数调用。 - 零界面依赖:本系统代码不引用任何界面类,无窗口实跑通过(静态扫描与实跑两项合成判定)。 - 表实一致:各表结构与已锁字段和 `data/schemas/` 对应声明逐字段一致。 diff --git a/待办清单.md b/待办清单.md index 0c00bc45..f721fe07 100644 --- a/待办清单.md +++ b/待办清单.md @@ -70,7 +70,7 @@ #### 迭代 41 测试债修复——9 个套件失败与静态扫描三项红(2026-10-29 登记,来源=批次移交) -**实况**:证据=能力审计上电批(worktree 分支 `capgate-20261029`,提交 48e6e551)全量闸复跑,首次实测迭代 41 两卡合回(合并提交 eb9bb537,测试特许移交+直接合回,见 roadmap 收口注脚)后的代码面真实状态:①02 单元与集成测试 9 套件失败——`config_db_test`(`if` 块内声明的变量在块外引用,解析错误)、`config_db_fatal_oob_test`(退出码 2≠期望 1)、`table_structure_guard_test`(`_TreeSaveMock` 缺 `meta_state`)、`treasure_items_test`(`StubDB` 缺 `crossrun`)、`standee_fx_sweep_test`(`set_trans` 空引用)、`forge_workbench_test`(120 秒超时挂死)、`tree_requires_level_test`(`row_by_id` 在空基址)、`save_manager_domain_test`(缺 `_migrate_legacy_save`)、`theme_projection_test`(`CampOverlay` 缺 `_recent_list`);②09 静态扫描红项清单与基线不一致——S9 类型闸 24 处(迭代 41 拆出的新件缺 `# type-hint: ignore` 注解与参数类型)、S10 文件头 4 处(`config_db` 与三个域容器头注日期)、S11 注释禁用词 1 处(`adventure_table.gd:55`),而 gdstyle 与 S13 已随迭代 41 还清(基线两条存量红已过期,须随修复实测重生成)。本条目只修测试与注解债、不改游戏行为。本批合入经用户 2026-10-29 裁带红合并:能力审计上电批只动闸件与规约(代码域零新增红),代码域现存红全部由本条目承接。 +**实况**:证据=能力审计上电批(worktree 分支 `capgate-20261029`,提交 48e6e551)全量闸复跑,首次实测迭代 41 两卡合回(合并提交 eb9bb537,测试特许移交+直接合回,见 roadmap 收口注脚)后的代码面真实状态:①02 单元与集成测试 9 套件失败——`config_db_test`(`if` 块内声明的变量在块外引用,解析错误)、`config_db_fatal_oob_test`(退出码 2≠期望 1)、`table_structure_guard_test`(`_TreeSaveMock` 缺 `meta_state`)、`treasure_items_test`(`StubDB` 缺 `crossrun`)、`standee_fx_sweep_test`(`set_trans` 空引用)、`forge_workbench_test`(120 秒超时挂死)、`tree_requires_level_test`(`row_by_id` 在空基址)、`save_manager_domain_test`(缺 `_migrate_legacy_save`)、`theme_projection_test`(`CampOverlay` 缺 `_recent_list`);②09 静态扫描红项清单与基线不一致——S9 类型闸 24 处(迭代 41 拆出的新件缺 `# type-hint: ignore` 注解与参数类型)、S10 文件头 4 处(`config_db` 与三个域容器头注日期)、S11 注释禁用词 1 处(`adventure_table.gd:55`),而 gdstyle 与 S13 已随迭代 41 还清(基线两条存量红已过期,须随修复实测重生成)。本条目只修测试与注解债、不改游戏行为。本批合入经用户 2026-10-29 裁带红合并:能力审计上电批只动闸件与规约(代码域零新增红),代码域现存红全部由本条目承接。**2026-10-29 用户裁(「表结构版本」数值冲突甲案+孤儿常量可删)**:文档侧已随文档域直改落地——数据配置.md 删「表结构版本」调参行、依赖表与验收项中的版本常量表述,存档序列化.md 迁移链「表结构版本对齐」改「随表结构变化」,architecture.md 两处常量名改现役 `SAVE_FORMAT_VERSION`;代码侧 `game/core/config_db.gd` 的死常量 `SCHEMA_VERSION`(全仓零引用,值为 1,与文档原载 2 无对应)随本批删除。 **改动面**:游戏代码