合并 master 入本分支(解冲突): 敌人系统取 master 版(敌种名录表已随工程批退役)并删 hobgoblin 缺口登记块、v1.6→v1.7; 难度曲线保留本支 v1.4(行序「熊地精 + 地精」订正)与混编投放记录; 待办清单保留本支(旧「内容三件套补齐」条目删除、新「L1 深度 3 改混编」条目在册)并按合并后的文档版本订正实况引用; 卡片同步 v1.7 与敌种名录表退役口径。验证: pipeline_gate PASS(28 条目/卡片口径 6 张)。
This commit is contained in:
commit
caf7f853d6
20 files changed
+1205
-135
No files matched your search
@@ -0,0 +1,93 @@
|
||||
# 处置:架构审查 5.1 封装修复批(2026-11-03)
|
||||
|
||||
> **性质**:设计讨论段过程稿(裁决记录+取证事实)。**接收方**=reports/需求卡片-架构审查5.1封装修复批-2026-11-03.md + 待办清单条目「架构审查优化讨论——全库架构审计读数的逐条裁决与整改分批」(2026-10-29 登记)。**寿命**:需求卡片成立即退役(吸收即死——结论吸收进卡片与 code-conventions,未决迁待办清单)。
|
||||
> **输入**:reports/审计-全库架构审查-2026-10-29.md §5.1(settlement 五段类直读写编排器私有成员;讨论段把普查扩到全库同模式面)+ 2026-11-03 讨论会话用户逐项裁决 + 2026-11-03 会话取证(19 符号逐个核过、行号为当日现址——行号写卡段复核)。
|
||||
|
||||
## 一、总判据(用户 2026-11-03 裁,本批一切设计遵循)
|
||||
|
||||
1. **拆分判「错」的口径=交付物缺交接**:拆分的完整交付物是一个独立的类,须同时含职责边界与交接定义——构造时拿到什么、回调原类什么、只经公开面往来。五次拆件五次不合格。
|
||||
2. **修复=把五次拆件没做完的交接补完**:代码位置不动、职责归属零改动,只补构造交付与回调。
|
||||
3. **编排器保留面=architecture.md:141 登记原样**(战斗状态机与生命周期、行发射基建 _emit_row/_assert_row_source/_fatal、呈现投影、刷新面、nest_preview_count),本批零增零减。
|
||||
4. **法律先于修复**:code-conventions 两条增补先落(=§1.6 拆分交接定义+封装边界,本批交付二),两条是本批修复与后续闸件的共同依据。
|
||||
5. **GDD 零改动**(零行为变更的设计讨论,不触任何系统规则)。
|
||||
6. **范围**:core 五处进卡(编入需求卡片);presentation 层约 227 行出卡(不在本卡,冻结期内单开设计讨论——修法=视图补公开设置方法、装配代码改走设置方法);sim/probe/tests 出卡(测量面直构惯例+测试受控例外)。
|
||||
|
||||
## 二、根因(定稿陈述)
|
||||
|
||||
拆件交付物只写了职责边界、没写交接定义——拆出的件没拿到它需要的东西,每次需要都变成伸手回原类内部。三层防护全部缺位,三无叠加:
|
||||
|
||||
- 语言层:GDScript 无访问修饰符,下划线纯命名约定;
|
||||
- 规约层:code-conventions 全文无跨对象访问条文(已核);
|
||||
- 闸层:S1–S13 无此扫描。
|
||||
|
||||
局部每处合理(19 符号逐个核过全是正当需要),整体边界溶解:累计约 390 行、20+ 文件。
|
||||
|
||||
## 三、普查五处(core 层;2026-11-03 会话取证现址,行号写卡段复核)
|
||||
|
||||
1. **settlement 七段→编排器**:105 行/107 处/19 符号(七段=五段段类+round_cycle+battle_refresh_flow)。分布=grant_segment 54/combat_segment 23/round_cycle 10/verdict_segment 9/battle_refresh_flow 5/aura_segment 2/decay_segment 2。构成=成员引用 72 处+编排器方法 35 处(逐符号与修后归属见五、总表)。
|
||||
2. **adventure_runner→BreakpointStore**:37 处直读写/32 行(5 行各含 2 处访问;_pending_next_level、_loadout_seeded、_resume_bp、_save_manager、_last_level_payload、_last_treasure_cleared、_bp_read)——adventure_runner.gd:37 注释自述「宿主读写经件」未落实。
|
||||
3. **save_manager→SlotStore**:9 行(slots._path 直读写 ×8+slots._migrate_legacy_save 私有方法调用;save_manager.gd:51/66/69/105/111/118-119/285-286)。
|
||||
4. **grant_segment→BattleFxHost**:6 行直写 _fx_new_resource_types(:82/:84)与 _fx_bonus_delta(:169-170/:378-379)。
|
||||
5. **config_db→三表容器**:3 行装配期写 _resolver(config_db.gd:157-159)。
|
||||
|
||||
presentation 层同模式约 227 行(抽样核实、未逐行判读)——出卡另议:
|
||||
|
||||
| 文件 | 行数 |
|
||||
|---|---|
|
||||
| level_map_screen | 87 |
|
||||
| main_ui_build | 70 |
|
||||
| main_adventure_flow | 25 |
|
||||
| standee_body | 16 |
|
||||
| main_overlay_flow | 15 |
|
||||
| main_debug_flow | 11 |
|
||||
| main_esc_flow | 2 |
|
||||
| board_view | 1 |
|
||||
|
||||
## 四、逐项裁决记录
|
||||
|
||||
| 项 | 裁决 |
|
||||
|---|---|
|
||||
| 方向=补交接 | settlement 七段构造时收六个子对象引用(战斗事实 BattleFacts、单位容器 UnitContainer、伤害控制器 DamageController、奖励经济 RewardEconomy、状态容器 StatusContainer、效果宿主件 BattleFxHost)+七个编排器方法回调(_emit_row、_fatal、_install_and_reset、_battle_over、_exit_distribution、_emit_settlement_snapshot、_emit_composition_effects,以 Callable 交付)+段间引用(授予段引用直接交换——battle_refresh_flow 不再经编排器 _rounds 链式取授予段,改为直接持有授予段引用);编排器公开读数(round_index、db、action_economy、battle_result)一并改注入;段类对编排器引用归零。 |
|
||||
| 搬家五方法 | _hero_atk→伤害域、_feat_yield_adjust→奖励域(奖励授予件)、_harmful_variants 与 _harmful_adjacent→地形棋盘域、_hits_of→伤害域。 |
|
||||
| verdict 轮推进保留 | verdict 段经 _exit_distribution 触发轮推进保留现设计(架构在册七段结构,battle_orchestrator 段序骨架冻结——architecture.md:119)。 |
|
||||
| battle_refresh_flow 同形 | battle_refresh_flow 同批同形改造(can_refresh/execute 两入口的 oc/self 入参一并改依赖交付)。 |
|
||||
| 其余三处补公开面 | BreakpointStore 补公开读写方法;SlotStore 补路径公开读取口与迁移方法(或序列化职责归位,写卡定形态);BattleFxHost 补两个公开累积方法;表容器补 resolver 公开挂载方法。 |
|
||||
| S13 成员数约束 | 段类新增依赖受 gdstyle 成员阈值约束,依赖可经束成员持有(先例=BoardInstaller 引用束注入——architecture.md:124「构造=引用束注入」)。 |
|
||||
| 验证方式 | 同种子逐项比对(主证,手法先例=3.1+3.2 卡 battle_driver_drive_test 动作序列快照)+battle_settlement 套件全绿+五搬家方法各配真实入口断言+core 五处跨对象私取 grep 恒零(扫描面非空前置+零命中);对照表按「非行为改动+零行为变更证明」登记;禁变异类测试、禁撤销类取证。 |
|
||||
| 排序 | 实现排队在 reports/需求卡片-架构审查3.1+3.2整改批-2026-11-02.md 之后(combat_segment 同文件避让——该卡甲案删 attack_segments 分支 :59-70)。 |
|
||||
| 估时域 | 2–3 个工作日(写卡期精估)。 |
|
||||
|
||||
## 五、19 符号行为归属总表(2026-11-03 会话取证)
|
||||
|
||||
| 符号 | 处数 | 现在长在哪 | 修后归属 | 段类修后怎么拿到 |
|
||||
|---|---|---|---|---|
|
||||
| _facts | 24 | 编排器成员(BattleFacts 件引用,battle_orchestrator.gd:38) | BattleFacts 件(战斗事实域,架构在册) | 构造注入 BattleFacts 引用(六子对象之一) |
|
||||
| _enemy_system | 22 | 编排器成员(UnitContainer 引用,battle_orchestrator.gd:48) | UnitContainer(B2 单位容器) | 构造注入 UnitContainer 引用 |
|
||||
| _damage | 18 | 编排器成员(DamageController 引用,battle_orchestrator.gd:51) | DamageController(伤害单据管线) | 构造注入 DamageController 引用 |
|
||||
| _reward_economy | 5 | 编排器成员(RewardEconomy 引用,battle_orchestrator.gd:50) | RewardEconomy(B4 奖励经济) | 构造注入 RewardEconomy 引用 |
|
||||
| _status_effects | 2 | 编排器成员(StatusContainer 引用,battle_orchestrator.gd:49) | StatusContainer(B3 状态容器) | 构造注入 StatusContainer 引用 |
|
||||
| _fx_host | 1 | 编排器成员(BattleFxHost 引用,battle_orchestrator.gd:52) | BattleFxHost(效果宿主件) | 构造注入 BattleFxHost 引用 |
|
||||
| _rounds._grant_seg(链式) | 1 | battle_refresh_flow.gd:42 经编排器 _rounds 链式取授予段成员 | 段间引用——授予段引用直接交换 | 组装期直接交付授予段引用,不再穿编排器 |
|
||||
| _emit_row | 16 | 编排器私有方法(行发射基建,架构在册保留面) | 留宿主(保留面登记原样,零增零减) | 构造注入 Callable(七回调之一) |
|
||||
| _hits_of | 5 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _emit_composition_effects | 2 | 编排器私有方法 | 留宿主(保留面) | 构造注入 Callable |
|
||||
| _battle_over | 2 | 编排器私有方法(battle_result 状态机写点域) | 留宿主(保留面) | 构造注入 Callable |
|
||||
| _feat_yield_adjust | 2 | 编排器私有方法 | 搬家→奖励域(奖励授予件) | 经注入的奖励授予件公开方法直调 |
|
||||
| _fatal | 1 | 编排器私有方法(行发射基建族) | 留宿主(保留面) | 构造注入 Callable |
|
||||
| _hero_atk | 1 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _harmful_variants | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 经注入的所属域件公开方法直调(具体形态写卡定) |
|
||||
| _harmful_adjacent | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 同上 |
|
||||
| _install_and_reset | 1 | 编排器私有薄壳(装板复位,架构在册轴丙) | 留宿主(保留面) | 构造注入 Callable |
|
||||
| _exit_distribution | 1 | 编排器私有方法(verdict 段经它触发轮推进) | 留宿主(现设计保留——七段结构冻结) | 构造注入 Callable |
|
||||
| _emit_settlement_snapshot | 1 | 编排器私有方法(结算快照发射) | 留宿主(呈现投影出口不变) | 构造注入 Callable |
|
||||
| **合计** | **107 处/105 行** | — | — | — |
|
||||
|
||||
取证注意:成员七符号逐项加总 73、编排器方法十二符号逐项加总 34,与三、构成行记写的 72+35 有 ±1 出入(总处数 107 两路一致);普查处 2 读数按写卡代理实核修正为 37 处/32 行(首版记 37 行——5 行各含 2 处访问);godot-master 终审补查出普查漏项——SlotStore→SaveManagerCore 反向私取约 13 处(slot_store.gd:26-28/38-39/61-76/92-97/119/129/134/159-162,直用 _save._read_only/_reset_to_default/_data/_rename_overwrite/_peek_summary_at),与普查处 3(save_manager→SlotStore)为同一对类的相反方向,处置去向=并入需求卡片 T3 存档面(卡片已同步折入);行号与计数一律以写卡段复核为准。
|
||||
|
||||
## 六、架构锚点(architecture.md)
|
||||
|
||||
- :119——B1 battle_orchestrator 职责列:段序骨架(七段结构冻结)、B2/B3/B4 唯一调用方=B1 域文件集。
|
||||
- :124——BoardInstaller 行:构造=引用束注入先例(装板薄壳+表数据、随机流、装板所需对象与出错回调一次性交付)。
|
||||
- :137——「战斗编排域拆件定稿」节头(拆件定稿全文入口)。
|
||||
- :139——轴甲两件:宿主保留面首登记与呈现投影「唯一出口不变」。
|
||||
- :141——轴丁两件:零豁免裁宿主保留面原文(总判据 3 的登记原样出处)。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 工程改动报告:验收档分级与待办条目限长批(2026-11-04)
|
||||
|
||||
> 接收方:待办清单「验证与清单体系整改——四方向分阶段推进」条(阶段 3+阶段 4 收口凭据)
|
||||
> 性质:工程改动+文档设计改动直改批(用户 2026-11-04 发令开工;W 层八裁点当日全裁——档名高/中/低、判据=失败代价单维、三档、强度差只落审计深度且每批必有审计、U0 确认权、行数硬上限、入 pipeline_gate 机检、存量同批压缩;How 细则由本批推导落文)
|
||||
|
||||
## 1. 改动清单
|
||||
|
||||
| 面 | 改动 |
|
||||
|---|---|
|
||||
| `design/engineering/test-conventions.md` | §8.3 新增「验收档申报」:三档高/中/低,判据=失败代价单维,卡头申报、U0 确认或改判,2026-11-05 起对文件名日期不早于该日的卡生效,未申报旧卡按高档全量审计。§8.7 新增「审计深度分级」梯度表:高档=现行四件事全量;中档=对照表逐行保留、复跑省略以 CI 回执代证;低档=对照表抽查 ≥1/3(新增行与改判行必抽)+复跑省略;测试削弱检查与直查例外核对三档全保留;档位存疑按高档。 |
|
||||
| `design/engineering/doc-conventions.md` §12.1 | 新增「条目正文限长」:正文只写现行状态+证据指针,过程叙事归 git 提交信息;≤12 行且 ≤700 字(去空白)双判据,流水线闸机检。 |
|
||||
| `tools/pipeline_gate.py` | ①待办条目限长双判据机检(行/字,超限判据名「条目超长」);②卡片验收档申报机检 C4(GRADE_RULE_DATE=2026-11-05)。 |
|
||||
| `.zcode/skills/req-card`(不入 git) | 必备结构新增第 16 节「验收档申报」。 |
|
||||
| `.zcode/skills/iter`(不入 git) | 独立验收审计节挂深度分级口径(逐卡定档、旧卡按高档)。 |
|
||||
| `待办清单.md` | 存量超限条目 9 条压缩(架构审查余项/三关色相/验证与清单体系整改/数值标定窗口/棋盘键盘/二三关观感/封印印记/生涯/EffectPort 删键)——过程叙事归 git 提交信息与既有过程件,正文留现行状态+证据指针+缺口。 |
|
||||
|
||||
## 2. How 数值与判据推导
|
||||
|
||||
- **限长 12 行**=实况说明行 1+文档指针行至多 8+缺口/改动面/状态各 1;**700 字**≈8 条指针(约 320 字)+现行状态叙述余量——以现行合规条目实测校准(压缩后的整改条目约 400 字)。行数与字数并用:单判据皆可绕(多行蔓延/单行堆砌),实证=整改条目原实况为单段 1500+ 字。
|
||||
- **审计深度梯度锚定现行 §8.7 四件事**:机械且堵造假向量的两件(削弱检查、例外核对)三档全保留不抽;昂贵的判断件(逐行核对、复跑)按档放宽;中/低档复跑省略的执行证据由 CI 回执承担(CI 全量强制档不因档位变化——迭代 44 实证的跨卡漏网兜底保持原样)。
|
||||
- **档名取「高/中/低」**:P0/P1/P2 记号已被 doc-conventions §12.1 占用为待办紧急度专用(新文档禁另立别义)。
|
||||
- **生效日 2026-11-05**:沿用卡片按文件名日期生效的惯例(§8.8 同型),当日已写卡(EffectPort 批 2026-11-04)不回头改。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
- `pipeline_gate.py` 全仓 PASS(压缩后零超限);负证:临时超长条目行数与字数两判据各自触发红(临时件在 /tmp,未入库)。
|
||||
- `run_all_gates.sh --docs` 全绿;合回后远端 CI 追验(文档批=文档域秒级闸)。
|
||||
|
||||
## 4. 同批发现与登记(不在本批修)
|
||||
|
||||
- `tools/ci_watch.sh` 在 run 未落定时把中间态写成终局红回执:2026-11-04 run 37(commit 536dc072)实证——回执 16:59:55 写入 verdict=red,而该 run 17:03:10 才以「Job succeeded」落定,现查 Gitea API 组合状态=success;回执与真值相反,下游按「红未修不开新批」被误阻塞(本批开工时人工查 API 解封)。已登记待办清单新条目(直改类,修复方向=只认 run conclusion 落定后的终局态)。
|
||||
@@ -1,46 +0,0 @@
|
||||
# 盘点:验证与清单体系(阶段 0)
|
||||
|
||||
> 2026-10-28 · 服务待办清单「验证与清单体系整改——四方向分阶段推进」条
|
||||
> 性质:过程件(吸收即死)——结论吸收进待办条目与阶段 1 设计文档后删除。
|
||||
|
||||
## 1. 结论
|
||||
|
||||
1. **验证集清单零机器闸依赖**:`tools/run_all_gates.sh`、hooks、五个项目技能均不引用它;规范性锚点只有 `design/engineering/test-conventions.md` §8.3 一处。退役不需要改闸、改钩子、改技能。
|
||||
2. **测试名尾缀不是全量追溯键**:47 个有断言的文件中 19 个零尾缀(含三条 35 条以上断言的大套件)。能力清单只能按「能力→代表用例」建,不能要求逐断言尾缀。
|
||||
3. **对照表与待办清单都有机器闸**:前者的列结构、后者的条目格式均由 `tools/pipeline_gate.py` 强制;这两处瘦身要动闸,属阶段 3/4,不是阶段 1 的顺手活。
|
||||
4. **能力清单已有现成形态**:`game/tests/README.md` 的「集成旅程清单」5 行,扩面成本低;`repo_structure_audit.py` 不限制 `game/tests/` 下的 .md 文件名。
|
||||
|
||||
## 2. 依赖面盘点
|
||||
|
||||
| 件 | 消费方 | 机器闸依赖 | 退役/改动成本 |
|
||||
|---|---|---|---|
|
||||
| `game/tests/验证集清单.md` | test-conventions §8.3、待办清单 1 条、2 份过程报告、`tools/extract_checks.py` | 无 | 低:改 1 条规约+删文件 |
|
||||
| `tools/extract_checks.py` | 无自动调用;手工生成/对账 | 无 | 可保留为审计工具,或随清单退役 |
|
||||
| 改动—验收对照表 | req-card 技能、iter 技能、`pipeline_gate.check_ledger`(强制 5 列) | 有 | 中:规约+两技能+闸三处 |
|
||||
| 待办清单 | `pipeline_gate`(格式全套)、`doc_ref_audit`、`doc_term_audit`、`repo_structure_audit`、各技能 | 有 | 低:正文压缩不触机检;新增「≤5 行」规则才动闸 |
|
||||
| 独立验收审计 | iter 技能、req-card 技能、`pipeline_gate`(只查「验收审计」字样) | 有(字样) | 中:改抽样规则要动两技能+规约 |
|
||||
| 集成旅程清单 | 无机器消费 | 无 | 低:直接扩面 |
|
||||
|
||||
## 3. 覆盖数据
|
||||
|
||||
- `game/tests/**/*.gd` 共 70 个文件;静态 `check(` 粗口径 1607 处(含 `test_kit` 定义行与 `smoke_boot` 等提取器口径外宿主),清单口径 1587 处。
|
||||
- 标签尾缀〔…〕756 个(上限口径,一条标签一个)。
|
||||
- 有断言的文件 47 个:28 个有尾缀,19 个零尾缀。
|
||||
- 零尾缀大套件:`seal_polarity` 69、`variant_placement` 42、`roll_multiplier` 35、`cross_system_flow` 22、`damage_math` 21、`skill_unlock` 20、`type_glow` 20、`minesweeper_rules` 16、`system_contracts` 15。
|
||||
- 静默收集通道 `check_quiet` 约 407 站点在提取口径外(既有备案,test-conventions §5 工具局限)。
|
||||
|
||||
## 4. 对四阶段的影响
|
||||
|
||||
| 阶段 | 盘点结论对它的约束 |
|
||||
|---|---|
|
||||
| 1 换尺子(A) | 先扩「集成旅程清单」到核心域;每行=能力|真实入口|代表用例|最后验证批次|缺口。退役验证集清单;`extract_checks.py` 去留在设计讨论裁 |
|
||||
| 2 按新尺子精简(B) | 删并对象改为能力项;每项能力保留至少一个代表用例;不要求逐断言尾缀 |
|
||||
| 3 调验收强度(C) | 对照表列与审计抽样一起改,触 `pipeline_gate`、req-card、iter 三处;不要与阶段 1 同批 |
|
||||
| 4 文档减肥(D) | 待办正文压缩可直接做;「≤5 行」入闸需改 `pipeline_gate` |
|
||||
|
||||
## 5. 未决点(阶段 1 设计讨论)
|
||||
|
||||
1. 能力清单落点:`game/tests/README.md` 扩面,还是独立文件?
|
||||
2. 能力项粒度与覆盖面:按哪些域切、预计多少行?
|
||||
3. `tools/extract_checks.py` 去留:随清单退役,还是保留为审计工具?
|
||||
4. 验证集清单退役时点:立即冻结,还是阶段 1 设计定稿后一并退役?
|
||||
@@ -0,0 +1,174 @@
|
||||
# 需求卡片:EffectPort 蓄力层删键批
|
||||
|
||||
> 来源:待办清单「EffectPort biz_fact 键 charge_layers——无属主数据游离出领域实体的处置」(2026-11-02 登记,来源=审计发现;需求性工程条目,证据指认在条目实况)。**唯一事实源:该条目实况所引证据链+本卡「现状事实」节代码级考证(2026-11-04 全部实查复核)。**
|
||||
> 裁决沿革:删除方向 2026-11-02 用户裁(总判据「机制数据一律长在所属封装实体的内部属性(表行字段)里,全局常量与无主账本清零」);2026-11-04 本会话全仓考证确认死代码(零内容消费面)后用户发令删除;2026-11-04 grilling 复核四裁(注释口径甲=只清 charge_layers 关联语义/改写族孤儿另立待办/req-card 落盘时点条款落技能/编排意向凑批)。
|
||||
> 版本:v1.1(2026-11-04)
|
||||
|
||||
## 1. 目标与完成定义
|
||||
|
||||
把 `charge_layers`(玩家侧蓄力层)这条从未运转的死链整链退役:
|
||||
|
||||
- biz_fact 闭面五键收窄为四键(charge_layers/dig_streak/hp_ratio/rider_tier_bonus/rider_tier_crit → 后四键);
|
||||
- 行动经济侧蓄力层账本、上限常量、转蓄分支、`charge_full` 事件发射全部删除;`finish_round_stop` 签名简化为纯 RAP 转存;
|
||||
- 效果引擎两词表位(事件 `charge_full`、事实 `charge_layers`)退役;
|
||||
- 代码注释里引用退役专长名(整备军备/铁壁整备/厚积薄发)与蓄力层的全部残留句清零。
|
||||
|
||||
**完成定义**:`game/` 下除 `swap_charge_layers` 计数器域(蓄力周转专长,在役另物)外,「蓄力层」概念零残留(grep 判据见 T1);两套件既有断言全绿+本卡新断言绿;`--code` 域全套闸绿;RAP 转存读数逐位零漂移。
|
||||
|
||||
## 2. 设计事实源
|
||||
|
||||
需求性工程条目(删死码,无设计线):设计事实源=**证据指认**——待办清单条目实况证据链(`reports/审计-全库架构审查-2026-10-29.md` §3.1 B 类第 2 行+`game/core/effect_port.gd:4`+`game/core/action_economy.gd:14/37/203`)+本卡第 3 节 2026-11-04 代码级复核(file:line 逐条实查)。
|
||||
|
||||
## 3. 现状事实(2026-11-04 代码级考证)
|
||||
|
||||
死链判据——入口死、出口假想、内容零注册三面同时成立:
|
||||
|
||||
1. **入口死**:账本唯一写点=「停手转蓄力」分支(`game/core/action_economy.gd:202-205`),触发条件=效果表有行注册 `grant_ap(mode:transfer)`(`game/core/settlement/grant_segment.gd:281` 经 `has_effect_on` 查询);全仓 `.tres` 零命中(feats.tres 三条 grant_ap 行 :46/:284/:719、treasure_items.tres 两条 :38/:150,全无 transfer)。transfer 形态无执行体——唯一读点就是这条存在性查询(`game/core/effect_engine.gd:203/461/467` 三处注释句为仅余痕迹)。
|
||||
2. **出口假想**:消费面「厚积薄发/整备军备/铁壁按层缩放」只存在于 `game/core/damage_controller.gd:271/338/352/433` 四处注释;三名词=2026-10-08 退役旧专长(armory_prep/iron_wall/patient_burst,`design/content-archive/道具退役素材库.md:53-55`),GDD 与专长表零行。
|
||||
3. **满层事件无订阅**:`charge_full` 发射(`action_economy.gd:205`)自注「现无订阅者」(:199);`game/core/effect_engine.gd:14` 事件词表位在册。
|
||||
4. **transfer=true 分支零测试**:全仓仅 `game/tests/unit/core/treasure_effects_test.gd:132/138/144` 三处调用 `finish_round_stop(false, …)`(RAP 转存态)。
|
||||
5. **RAP 转存=在役正路**:术语表.md:34-35(RAP 词条与停手/转存率词条)、行动经济.md:80-82(停手整节)、`game/tests/README.md:123`(「停手转存储备与轮内刷新」能力行)。
|
||||
|
||||
残留面全清单(13 处+词表注释 3 处,处置见 T 卡):
|
||||
|
||||
| # | 文件:行 | 残留 |
|
||||
|---|---|---|
|
||||
| 1 | `game/core/action_economy.gd:14` | `CHARGE_LAYER_CAP := 3` 常量 |
|
||||
| 2 | `game/core/action_economy.gd:35-43` | 蓄力流注释块+`_charge_layers` 账本+`charge_layers` getter |
|
||||
| 3 | `game/core/action_economy.gd:168` | 「转蓄力层替代 RAP 转存」注释句 |
|
||||
| 4 | `game/core/action_economy.gd:196-205` | `finish_round_stop` transfer 分支+`charge_full` 发射 |
|
||||
| 5 | `game/core/effect_port.gd:4-5` | 闭面五键声明 |
|
||||
| 6 | `game/core/effect_engine.gd:14` | EVENTS 词表 `charge_full` 位 |
|
||||
| 7 | `game/core/effect_engine.gd:59` | FACTS 词表 `charge_layers` 位 |
|
||||
| 8 | `game/core/effect_engine.gd:203/461/467` | transfer 订阅查询与族分类注释句三处 |
|
||||
| 9 | `game/core/battle_fx_host.gd:2/37` | 头注与 facts_inject 注释句 |
|
||||
| 10 | `game/core/battle_fx_host.gd:92-98/219-223` | charge_layers 应答分支两处(读 `action_economy.charge_layers`) |
|
||||
| 11 | `game/core/battle_orchestrator.gd:113` | 「charge_layers 归 fx_host 自答」注释句 |
|
||||
| 12 | `game/core/damage_controller.gd:271/338/352/433` | 退役专长名注释四处 |
|
||||
| 13 | `game/core/settlement/grant_segment.gd:262/279-282` | 「整备转蓄力」注释+`has_effect_on(…,"transfer")` 判定入参 |
|
||||
| 14 | `game/core/settlement/combat_segment.gd:35-36` | 蓄力层注释 |
|
||||
| 15 | `game/tests/unit/battle_settlement/effect_port_test.gd:16/57/103` | 注释把在役蓄力周转计数器误标为「整备军备蓄力层」、把合成对照行说成「现役铁壁」 |
|
||||
|
||||
## 4. 设计契约(🔴 违反即 L3 停机呈报)
|
||||
|
||||
1. 🔴 **RAP 转存路径逐位零变化**——`finish_round_stop` 的 RAP 分支、`transfer_pct` 通道、`rap_transfer_mult`(储备罐 125=1.25:1)读数逐位不动;`treasure_effects_test` 既有断言期望值零变化(仅调用签名适配,见第 8 节申报)。
|
||||
2. 🔴 **蓄力周转专长域零触碰**——`feats.tres:1007-1056`(swap_charge_layers 计数器行)、`refresh_feats_test.gd` V8 全组、`game/tests/README.md:126` 能力行、GDD 战斗结算.md:278 与奇物.md:109 行,全部不动。
|
||||
3. 🔴 **敌方蓄力域零触碰**——empower 增益技(status_effects.tres)、敌方节点级蓄力层(01-核心循环.md:79/88)、音频.md 蓄力拍等 GDD 行,全部不动;术语表**不新增**任何「蓄力」词条。
|
||||
4. 🔴 **biz_fact 闭面只收窄不扩**——四键为终态,禁顺手加新键;未绑缺省与未知事实回落 null 语义不变(fail-fast 既有机制零回归)。
|
||||
5. 🔴 **禁保留无效成员**——禁兼容别名、空 getter、词表空位、恒 false 分支、注释式「以后要用」存根;机检键与本卡契约互斥时停卡呈报,禁自造第三条路。
|
||||
6. 🔴 **实现批禁写 `design/` 整个目录与根规则文件**——architecture.md 两处(:124/:146)走反哺点清单由文档批落文。
|
||||
7. 🔴 **MC/模拟零跑**——本批无数值改动(死码删除零表值触面)。
|
||||
8. 🔴 **车道铁律**——实现走独立 worktree,主区只作合并落点。
|
||||
|
||||
## 5. 范围边界
|
||||
|
||||
**做**:上表 15 处残留一次清完+两处测试适配+1 条新断言。
|
||||
**不做**:
|
||||
- `test_charge_layers_consumed_same_round` 函数**不改名**——它是 swap_charge_layers(蓄力周转)测试,函数名属该计数器域;且 README:126 能力行代表用例名锚定此名,实现批禁写 README。
|
||||
- 蓄力周转、敌方蓄力、RAP/转存率任何面(契约 1–3)。
|
||||
- 蓄力周转测试面牵连核对结论:`refresh_feats_test` V8 组全部经效果引擎计数器域运行,不触 `action_economy.charge_layers`(全仓 grep 已证)——零牵连,无需同批改动。
|
||||
- **改写族内容孤儿机制**(grilling 2026-11-04 新发现,另立待办):damage_controller.gd 按序改写族通用机制的 spike/armor_rewrite/discount_shift/trade_* 子分支零内容注册(全仓唯一 modify_ticket 在役行=淬毒刃纹 clamp_bonus,feats.tres:854)+五拍注释退役名叙事层(矿工重锤/专注/猎弱本能)——不持数据键、非本卡对象,已立待办清单专条,处置方向归其自己的设计讨论。
|
||||
**明示不收件的去向**:无——单链清退一次做完,无拆尾。
|
||||
|
||||
## 6. 关联文档同步面
|
||||
|
||||
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务 |
|
||||
|---|---|---|
|
||||
| `design/engineering/architecture/architecture.md` | :124(BattleFxHost 行「A3 action_economy(queue_ap_delta/charge_layers 读)」依赖句);:146(轴戊 EffectPort 句「闭面五键」与「facts 取值束 dig_streak/charge_layers/rider_tier_*」) | 实现批禁写——逐条登记进 `reports/iter<N>-反哺点-<日期>.md`,由用户裁决后归文档批改四键、删读依赖句 |
|
||||
| `game/tests/README.md` | :88 能力行「效果发射端口单点」代表用例 `_test_biz_fact_face_closed` | 实现批禁写——计划函数名不变,批末收尾核对名实一致;若实现改名则回表(记反哺点) |
|
||||
| 待办清单 | 本条目状态(写卡段→已写卡;实现完成→整条删除) | 状态推进由流水线各段承载,实现批不碰 |
|
||||
| 术语表/GDD 各系统文档 | 零关联(敌方蓄力/蓄力周转/RAP 各行不受影响) | 无同步义务 |
|
||||
|
||||
## 7. 任务卡
|
||||
|
||||
**卡前文件结构图**(本批零新增文件;改动文件 9+测试 2,全部「非行为改动/行为改动」已标):
|
||||
|
||||
| 文件 | 职责与改动 | 行为改动 |
|
||||
|---|---|---|
|
||||
| `game/core/action_economy.gd` | 删常量/账本/getter/transfer 分支;`finish_round_stop` 签名简化;注释两处清 | 是(对照表行 2) |
|
||||
| `game/core/settlement/grant_segment.gd` | 调用简化(删 has_effect_on 入参)+注释清 | 是(对照表行 2) |
|
||||
| `game/core/effect_engine.gd` | EVENTS/FACTS 删位+注释三处清 | 是(对照表行 3) |
|
||||
| `game/core/battle_fx_host.gd` | 应答分支两处删+头注/注释清 | 是(对照表行 1) |
|
||||
| `game/core/effect_port.gd` | 闭面五键句改四键 | 否(注释) |
|
||||
| `game/core/battle_orchestrator.gd` | 注释句清 | 否(注释) |
|
||||
| `game/core/settlement/combat_segment.gd` | 注释清 | 否(注释) |
|
||||
| `game/core/damage_controller.gd` | 退役专长名注释四处清 | 否(注释) |
|
||||
| `game/tests/unit/battle_settlement/effect_port_test.gd` | 新断言+误标注释三处清 | 是(对照表行 1) |
|
||||
| `game/tests/unit/core/treasure_effects_test.gd` | 三处调用签名适配(断言值零变化) | 否(适配,申报见第 8 节) |
|
||||
|
||||
### T0 契约收窄原子批(≈0.625 工作日)
|
||||
|
||||
> 九文件一次改完——`battle_fx_host.gd:98/223` 读 `action_economy.charge_layers`,拆卡必产生不可编译中间态,故同卡原子交付。
|
||||
|
||||
- [ ] `action_economy.gd`:删 :14 常量、:35-43 账本块(`_charge_layers`/getter/注释)、:168 句;`finish_round_stop` 改签名 `func finish_round_stop(transfer_pct: int = 100) -> void`,体只留 RAP 转存行 `_rap += _last_stop_ap * maxi(1, transfer_pct) / 100` 与 `_last_stop_ap = 0`;:196-199 注释改写为纯 RAP 转存口径(禁残留 transfer/charge_full 字样)
|
||||
- [ ] `grant_segment.gd`::281-282 调用改 `oc.action_economy.finish_round_stop(rap_pct if rap_pct > 0 else 100)`;:262 注释删「整备转蓄力」句(保留 round_end 其余语义句)
|
||||
- [ ] `effect_engine.gd`:EVENTS 删 `"charge_full"` 位(:14)、FACTS 删 `"charge_layers"` 位(:59);:203 句改「发射点缺省行为仲裁用——round_end 走 RAP 转存」、:461/:467 删「grant_ap(mode:transfer)」字样(族分类句同步改写)
|
||||
- [ ] `battle_fx_host.gd`:删 :92-98 与 :219-223 两处 charge_layers 分支(`biz_fact`/补充事实面走既有「未知事实回落 null」末行);:2 头注「charge_layers 自答,余五事实转宿主」改「余事实转宿主」口径;:37 注释删 charge_layers 句
|
||||
- [ ] `effect_port.gd`::4-5 闭面句改四键(dig_streak/hp_ratio/rider_tier_bonus/rider_tier_crit)
|
||||
- [ ] `battle_orchestrator.gd:113`:注释删「charge_layers 归 fx_host 自答」句
|
||||
- [ ] `combat_segment.gd:35-36`:注释改写(删蓄力层句,保留端口闭面语义句)
|
||||
- [ ] `effect_port_test.gd`:V3 组 `_test_biz_fact_face_closed` 末尾增断言——经 `begin_battle` 真实装配链取宿主 `biz_fact("charge_layers")`,`Kit.check("V4 闭面收窄:charge_layers 键退役——宿主事实应答 null", orch.fx_host().biz_fact("charge_layers") == null)`(print 标签文案可代拍板)
|
||||
- [ ] `treasure_effects_test.gd:132/138/144`:三处调用改单参 `finish_round_stop(100)`/`finish_round_stop(125)`/`finish_round_stop(125)`(断言期望值逐字不动)
|
||||
- [ ] 孤立验证:`…console.exe --script res://tests/run_all.gd` 单测域全绿(重点 effect_port_test/treasure_effects_test/refresh_feats_test 三套件)
|
||||
|
||||
### T1 注释清尾与零残留核验(≈0.25 工作日)
|
||||
|
||||
- [ ] `damage_controller.gd` 四处只清 charge_layers 关联语义、改机制语言,五拍块其余退役名(矿工重锤/专注/猎弱本能——grilling Q1 甲裁)不动::271 第三拍句删「when charge_layers≥3 在 dispatch 判定——满层持续状态口径」分句与「厚积薄发」点名,spike_ready 机制行为描述保留;:338 删「整备军备」点名,句改「attack_bonus per 计数器层值」机制口径;:352 删「厚积薄发」点名,改「modify_ticket mode=spike 满层口径」;:433 删「铁壁整备」点名,shield 订阅面机制描述保留(禁残留整备军备/铁壁/厚积薄发/charge_layers 字样)
|
||||
- [ ] `effect_port_test.gd:16/57/103`:三处误标注释改写——:16 改「蓄力周转计数器(feats.tres swap_charge_layers 行)」、:57/:103 删「整备军备/铁壁」字样改现状描述
|
||||
- [ ] 零残留判据:`grep -rn "charge_layers\|charge_full\|CHARGE_LAYER\|蓄力层\|转蓄力\|厚积薄发\|铁壁\|整备军备" game/ --include="*.gd" --include="*.tres"` 除 `swap_charge_layers` 域(`refresh_feats_test.gd` 函数名 `test_charge_layers_consumed_same_round` 与 `feats.tres` swap 行)外零命中
|
||||
- [ ] S13 核对:`action_economy.gd` 类变量数较登记值只降不升(删 `_charge_layers` 后预期 10→9);其余触面同判据
|
||||
- [ ] 里程碑步出口:`tools/run_all_gates.sh --code` 全绿
|
||||
|
||||
### T2 产出物落位卡(≈0.125 工作日)
|
||||
|
||||
- [ ] `reports/iter<N>-实现报告-<日期>.md`:各卡状态+实现决定记录+测试削弱申报执行情况+实机目检总清单(本批无玩家可观测变化——登记「无实机目检项」并写明死码删除零提交面)
|
||||
- [ ] `reports/iter<N>-反哺点-<日期>.md`:architecture.md :124/:146 两条逐条落点
|
||||
- [ ] 待办清单条目整条删除归收尾段(实现批不碰)
|
||||
|
||||
## 8. 验证闸(改动—验收对照表)
|
||||
|
||||
| # | 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 1 | 事实应答面收窄——charge_layers 键退役 | `battle_fx_host.gd:92-98/219-223` 两分支删 | `effect_port_test.gd` V3 组新增「V4 闭面收窄:charge_layers 键退役——宿主事实应答 null」 | 接口(单元) | `BattleOrchestrator.begin_battle()` 真实装配链(端口接线后取宿主 biz_fact) | 宿主事实应答 null 化=本批特有提交面(键在→返 0,键退役→null) | 既有:效果发射端口单点 |
|
||||
| 2 | 蓄力层账本与转蓄分支退役、签名简化 | `action_economy.gd:14/35-43/168/196-205`+`grant_segment.gd:262/281` | `treasure_effects_test.gd` 既有断言三处全绿(停手 1:1 与储备罐 1.25:1 两态读数零变) | 单元 | 真实停手路径 `request_stop()`→`round_end`→`finish_round_stop` | RAP 转存既有读数零漂移(行为零变化回归锚) | 既有:停手转存储备与轮内刷新(上限/AP 不重置/刷新图零清图奖励) |
|
||||
| 3 | 事件/事实两词表位退役 | `effect_engine.gd:14/59` 删位 | 静态判据:T1 零残留 grep 词表零位+`--code` 域全套闸绿 | 静态+单元 | —(词表为常量面) | 静态判据+评审注记:词表位删除无独立运行期提交面(加载期 fail-fast 校验为既有机制,非本批新增) | 既有:效果发射端口单点 |
|
||||
|
||||
**测试方式两分法**:本批全部归调试接口验证(单元/接口断言);**无用户目检项**——死码删除零玩家可观测提交面(实现报告登记「无实机目检项」并写明缘由)。
|
||||
**测试削弱申报**:`treasure_effects_test.gd:132/138/144` 三处调用实参 `(false, 100/125/125)` → `(100/125/125)`——签名适配,断言期望值与检查语义逐字零变化;无断言删除、无阈值放宽、无扫描面缩小。
|
||||
**独立验收审计**:`reports/iter<N>-验收审计-<日期>.md`,由未参与实现的会话或子代理执行,未过不得合并(test-conventions §8.7)。
|
||||
**回归措辞**:里程碑步(T1)出口跑一次 `--code` 域全套闸;卡内修复只做出红最小单元的最窄确认;新断言先行孤立验证再并入全套。
|
||||
|
||||
## 9. 异常分级
|
||||
|
||||
- **L1 自救**:注释改写笔误、grep 白名单笔误、print 标签文案。
|
||||
- **L2 记录继续**:注释改写措辞超出删除语义的级微调(记录进实现报告「实现决定记录」)。
|
||||
- **L3 停机呈报**:①删除时发现任何现役表行/效果规格/内容件引用 `charge_layers`/`charge_full`/transfer 订阅(与「零内容件」考证矛盾=上游考证缺陷,停卡退回写卡段);②S13 键上升;③全套闸红不可最小单元收敛;④机检键与本卡契约互斥(含 static_scan 计数文本冲突——禁改闸件豁免);⑤实测发现 `biz_fact("charge_layers")` 在四键终态下不返 null(宿主回落语义与考证不符)。
|
||||
|
||||
## 10. 代拍板白名单
|
||||
|
||||
1. 注释改写的具体措辞(保持原注释密度与风格,语义=删除后现状)。
|
||||
2. V4 断言的 print 标签文案。
|
||||
3. 删除后空行/排版微调。
|
||||
4. `treasure_effects_test` 三处实参写法跟随文件内既有风格(字面 100/125)。
|
||||
|
||||
## 11. 待裁点
|
||||
|
||||
零待裁点——删除方向 2026-11-02 用户裁、2026-11-04 死代码确认后发令。开工门=本卡经 grilling 复核+用户裁决+迭代编排(编入迭代批次,注意单卡 ≈1.0 工作日,迭代估时总量 <5 工作日=冻结待凑批)。
|
||||
|
||||
## 12. 落位与可复用性预检
|
||||
|
||||
- **复用面**:零新增件——验收断言复用 `effect_port_test.gd` V3 闭面组既有结构(同函数内追加,不新增文件/套件);删码批无「不能复用既有件」问题。
|
||||
- **唯一面**:删除不产生第二落点;grep 同名核查已证 `swap_charge_layers`(在役)与 `charge_layers`(退役)是两个标识符域,删除不触碰前者。
|
||||
- **分层与交互面**:删除面全在 core/settlement 内部与两测试件;效果端口六 Callable 束契约(bind_port 组装期注入)不变;Core 层零 UI 依赖不因删除面新增绕行;无数值表触面。
|
||||
|
||||
## 13. 禁为机检文本保留无效成员
|
||||
|
||||
🔴 适用:禁为迎合机检消息文本(含派生计数、S13 键值)保留或新增无效成员/别名/空位;机检键与本卡契约互斥时实现段一律停卡呈报,不得自造第三条路。
|
||||
|
||||
## 14. 实现规范预算
|
||||
|
||||
零新增文件——三查不适用。存量触面预期:`action_economy.gd` 类变量数只降不升(删 `_charge_layers`,预期 10→9);`battle_fx_host.gd` 分支删除成员数不变;其余触面仅注释行。全部触面 S13 键较登记值只降不升(T1 核对步骤承载)。
|
||||
|
||||
## 15. 拆分边界纪律
|
||||
|
||||
本卡为删除类(非拆分/收敛类),无拆出单元。红线:禁为凑指标或摊薄审查把同链残留拆多批留尾——15 处残留同链一次清完(T0/T1 的切分是审查门粒度,非范围拆分;T0 九文件原子性由编译依赖承载,见 T0 卡头注)。
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求卡片 · L1 深度 3 改地精+熊地精混编(大地精数据行退役)
|
||||
|
||||
来源:待办清单「L1 深度 3 改地精+熊地精混编(大地精数据行退役)」(2026-11-04 登记,文档设计已闭合+已写卡)(唯一事实源:`体验验证清单.md` ⑱「投放内容」段第 (1,3) 行条目——行序、行值取定与静态骰和在该段钉死;机制合法性见 `design/gdd/systems/战斗循环/敌人系统.md` v1.6 核心规则「行集构成纪律」条;投放记录与读数义务见 `design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3 混编注记段)
|
||||
来源:待办清单「L1 深度 3 改地精+熊地精混编(大地精数据行退役)」(2026-11-04 登记,文档设计已闭合+已写卡)(唯一事实源:`体验验证清单.md` ⑱「投放内容」段第 (1,3) 行条目——行序、行值取定与静态骰和在该段钉死;机制合法性见 `design/gdd/systems/战斗循环/敌人系统.md` v1.7 核心规则「行集构成纪律」条;投放记录与读数义务见 `design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3 混编注记段)
|
||||
|
||||
日期 2026-11-04 | 第 2 版(v1.1,2026-11-04 双审复核后改写)| 段位=写卡(第三段)| 开工门=用户发令 U0
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
## 二、设计事实源
|
||||
|
||||
- **行序 + 行值 + 数量取定**:`体验验证清单.md` ⑱ 投放内容段第 (1,3) 条(「行值整行复用 (1,2) 熊地精(1 只 / hp22 / ac2)与 (1,0) 地精(1–2 只 / hp8 / ac0),零数值新增;静态最坏骰和 1+2=3;行序 = 熊地精在前」)
|
||||
- **混编合法性三条纪律**:`design/gdd/systems/战斗循环/敌人系统.md` v1.6 核心规则「行集构成纪律」条
|
||||
- **混编合法性三条纪律**:`design/gdd/systems/战斗循环/敌人系统.md` v1.7 核心规则「行集构成纪律」条
|
||||
- **投放记录与读数义务**:`design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3 混编注记段(只给机制与义务,不给行序)
|
||||
- **Alpha 零读数**:`design/engineering/process-conventions.md` §3 第 5 条 Alpha 阶段口径段
|
||||
- 待办清单条目:`待办清单.md`「L1 深度 3 改地精+熊地精混编(大地精数据行退役)」条
|
||||
@@ -52,7 +52,7 @@
|
||||
3. 🔴 **行序固定**:熊地精行在前、地精行在后(依据 §二 第一条)。行序影响默认单体目标与开战叙述首行,不属实现面可调项。
|
||||
4. 🔴 **不碰深度 4/5**:`(1,battle,6)` 行一字段都不许动;目标句里没有「深度 3–5」这回事。
|
||||
5. 🔴 **Alpha 零读数**:本批不跑 MC、不采改前改后读数;实现报告注明「未取证」,读数义务归数值统一修正批。
|
||||
6. 🔴 **禁碰敌种表与技能表**:`敌人系统.md` 敌种表维持八种;`skills.tres` 零改动。
|
||||
6. 🔴 **禁碰敌种数据面与技能表**:敌种名录表已随工程批退役(`敌人系统.md` 不再维护抄本),`skills.tres` 零改动。
|
||||
7. 🔴 **禁改美术侧键集**:`tools/standee_asset_check.py` 与 `tools/path_check.py` 的 `ENEMY_KEYS` 与本批无关,禁顺手改。
|
||||
|
||||
## 五、范围边界
|
||||
@@ -68,7 +68,7 @@
|
||||
| 文档 | 关联点 | 同步义务 |
|
||||
|---|---|---|
|
||||
| `design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3 | 混编注记段已写 (1,3) 投放记录 | 零动作(文档批已落文,commit 4aaa154e;行序表述由本批前置修复提交更正) |
|
||||
| `design/gdd/systems/战斗循环/敌人系统.md` v1.6 | 缺口登记已删、敌种表维持八种 | 零动作(同上) |
|
||||
| `design/gdd/systems/战斗循环/敌人系统.md` v1.7 | 缺口登记已删;敌种名录表已随工程批退役,行数据逐行读表 | 零动作(同上) |
|
||||
| `体验验证清单.md` ⑱ | L1 节点 3 目检三项 + 读数义务 | 零动作;实现报告抄录目检项 |
|
||||
| `design/gdd/08-Alpha版本标准.md` v1.26 | 混编行集状态行已补 (1,3) | 零动作 |
|
||||
| `game/tests/README.md` 能力表 | 本批不改任何用例函数名,只改函数体内断言与夹具 | 零动作;若实现期必须改名,停卡退回写卡段(实现批禁写该文件) |
|
||||
|
||||
@@ -0,0 +1,291 @@
|
||||
# 需求卡片:架构审查 5.1 封装修复批(2026-11-03)
|
||||
|
||||
来源:待办清单「架构审查优化讨论——全库架构审计读数的逐项裁决与整改分批(2026-10-29 登记,来源=审计发现)」条目 5.1 部分(**唯一事实源**:reports/处置-架构审查5.1封装修复-2026-11-03.md——处置记录与本卡并行成文,本卡开工时该件尚未落盘;T1 首步核其已落盘且与本卡第 3 节逐条一致,冲突即 L3 停卡。设计闭合凭据=2026-11-03 设计讨论会话裁决+审计报告 §5.1+architecture.md:119/:124/:137-146)。
|
||||
状态:已写卡(v1.1,2026-11-03 修订——godot-master 终审两中等发现与四低项折入+SlotStore→SaveManagerCore 反向私取终审补查并入 T3;处置记录已落盘并与本卡第 3 节核过一致)。改动面:游戏代码(含随逻辑写/改的测试代码)。
|
||||
|
||||
## 1. 目标与完成定义
|
||||
|
||||
**这批做什么**:把 2026-11-03 设计讨论裁决的五处跨对象私有访问修复方案全部落码——封装收口、零行为变更:
|
||||
|
||||
| # | 处置对象 | 现状 | 终态 |
|
||||
|---|---|---|---|
|
||||
| 1 | settlement 七段 → 编排器 | 七文件对编排器 `oc._` 私取 105 行/107 处/19 符号(本卡第 3 节 grep 实核) | 段类构造收引用束(六子对象+编排器公开协作件引用)+七个编排器方法回调(Callable 交付)+公开读数注入;段类对编排器引用归零 |
|
||||
| 2 | 编排器五个放错位置的方法 | `_hero_atk`/`_feat_yield_adjust`/`_harmful_variants`/`_harmful_adjacent`/`_hits_of` 留宿主、段类经宿主引用直调(architecture.md:145「现状形态」) | 各归领域宿主(伤害域/奖励域/地形棋盘域),宿主原方法删除禁留壳 |
|
||||
| 3 | adventure_runner → BreakpointStore | `_bp_store._` 直读写 37 处(32 行;adventure_runner.gd:37 注释自述「宿主读写经件」未落实) | BreakpointStore 公开方法面承接,宿主私取清零 |
|
||||
| 4 | save_manager ↔ SlotStore | save_manager→SlotStore:`slots._path` ×8+`slots._migrate_legacy_save` 私有方法调用 ×1(save_manager.gd:51/66/69/105/111/118-119/285-286);SlotStore→SaveManagerCore 反向私取约 13 处(slot_store.gd:26-28/38-39/61-76/92-97/119/129/134/159-162——直用 `_save._read_only`/`_reset_to_default`/`_data`/`_rename_overwrite`/`_peek_summary_at`,godot-master 终审补查) | save_manager 侧=SlotStore 公开读投影 `active_path()`+迁移方法公开化承接;SlotStore 侧=SaveManagerCore 补公开方法面承接(T3 定死) |
|
||||
| 5 | grant_segment → BattleFxHost;config_db → 三表容器 | grant 直写 `fx_host._fx_new_resource_types`(:82/:84)与 `fx_host._fx_bonus_delta`(:169-170/:378-379)共 6 行;config_db.gd:157-159 三行装配直写三表 `_resolver` | BattleFxHost 两个公开累积方法;三表 schema 各加公开挂载方法 `bind_resolver` |
|
||||
|
||||
**什么状态算完**:五处的每一条改动都落码、都有第 8 节对照表配对的验收断言在当轮真实跑批中通过;主证=同种子逐项比对(改前改后动作序列快照逐位同,T1 固化、全程保持绿)+battle_settlement 套件全绿;结构性证据=core 五处跨对象私取 grep 恒零(扫描面非空前置+零命中);代码域闸全绿(冒烟+单元+探针+渲染/静态);两份 reports/ 产出物(实现报告+反哺点清单)写齐。
|
||||
|
||||
**排序义务**:本卡实现排队在 reports/需求卡片-架构审查3.1+3.2整改批-2026-11-02.md 之后(已编迭代 50,未开工)——combat_segment.gd 同文件避让(该卡甲案删 attack_segments 分支 :59-70,本卡第 3 节 combat 行号在其合回后漂移,T1 复核以 grep 符号锚定位)。
|
||||
|
||||
## 2. 设计事实源
|
||||
|
||||
- **处置记录(输入合同,逐条一致)**:`reports/处置-架构审查5.1封装修复-2026-11-03.md`——五处裁决方案、段类终态、出卡边界。本卡第 3 节现状实查与第 4/7 节签名设计是其机械承载;T1 复核两件一致(冲突=上游缺陷,L3 停卡)。**口径注**:处置记录「公开读数一并改注入」=形态族措辞,涵盖本卡第 4 节「调用参数现值交付」(round_index/battle_result 两变值标量构造期注入必陈旧——现值交付即注入的形态之一),T1 核对不按字面机械比对、按此口径核。
|
||||
- **审计背景**:`reports/审计-全库架构审查-2026-10-29.md` §5.1(settlement 五段类直读写编排器私有成员 20+ 处;行号已漂移,以本卡第 3 节实查为准)。
|
||||
- **架构登记**:`design/engineering/architecture/architecture.md`——:119(battle_orchestrator 保留面与 B1 域文件集)、:124(BoardInstaller 引用束注入先例——「构造=引用束注入(……防 _init max-parameters 新键)」)、:137-146(战斗编排域拆件定稿::140 轴丙、:141 编排器保留面登记、:143 跨件单向接线、:145 段类随动现状句)。
|
||||
|
||||
## 3. 现状事实(2026-11-03 worktree arch51-card 实查,基点 6261b36e;开工自行复核)
|
||||
|
||||
### 3.1 五处私取面盘点
|
||||
|
||||
**处 1·settlement 七段 → 编排器**(game/core/settlement/):`grep -c 'oc\._'` 逐文件=grant_segment 54/combat_segment 23/round_cycle 10/verdict_segment 9/battle_refresh_flow 5/aura_segment 2/decay_segment 2,合计 **105 行**;`grep -o "oc\._[a-z_]*" | wc -l`=**107 处**(grant:131 与 grant:424 两行各含 2 处);符号 19 种=`_facts`×24、`_enemy_system`×22、`_damage`×18、`_emit_row`×16、`_reward_economy`×5、`_hits_of`×5、`_status_effects`×2、`_feat_yield_adjust`×2、`_emit_composition_effects`×2、`_battle_over`×2、`_rounds`×1(:42 `oc._rounds._grant_seg` 跨两层)、`_install_and_reset`×1、`_hero_atk`×1、`_harmful_variants`×1、`_harmful_adjacent`×1、`_fx_host`×1、`_fatal`×1、`_exit_distribution`×1、`_emit_settlement_snapshot`×1。另有对编排器**公开**成员访问:action_economy×11、db×7、minesweeper×6、round_index×3、fx_host()×3、battle_result×2、rng×2、attune_param_sum()×1(grant:280)、perfect_sweep_earned()×1(grant:284)。
|
||||
|
||||
**处 2·搬家五方法**(均在 battle_orchestrator.gd,仅段类与编排器自用):
|
||||
|
||||
| 方法 | 现址 | 调用面 |
|
||||
|---|---|---|
|
||||
| `_hero_atk() -> int` | battle_orchestrator.gd:70-71(读 `_facts.encounter` hero_atk 键、缺省 db.combat.hero.atk——E4 派生读,禁快照成员) | combat_segment:55;编排器 spawn 消费点 :282;测试 roll_multiplier_test.gd:45-59 经真实链路覆盖(零直调) |
|
||||
| `_feat_yield_adjust(snap, positive, pos_m, neg_m)` | :452-461(读 `_reward_economy.polarity_row`) | grant_segment:99/:140 |
|
||||
| `_harmful_variants(vids)` | :466-473(读 db.combat.variation) | grant_segment:87;_harmful_adjacent 内部 :484 |
|
||||
| `_harmful_adjacent(cell)` | :478-485(读 minesweeper.current_board) | grant_segment:339 |
|
||||
| `_hits_of(hits, kind)` | :489-494(纯过滤) | grant_segment:110/:115/:138/:356、combat_segment:62(该行随 3.1+3.2 批甲案删除)、测试 adventure_feats_test.gd:671/:691/:727 |
|
||||
|
||||
**处 3·adventure_runner → BreakpointStore**:`grep -o "_bp_store\._[a-z_]*" | wc -l`=**37 处**(32 行)=`_resume_bp`×8、`_pending_next_level`×7、`_save_manager`×6、`_bp_read`×5、`_loadout_seeded`×5、`_last_level_payload`×4、`_last_treasure_cleared`×2。分布:adventure_runner.gd:107/:115/:157/:168/:180/:185/:189/:191/:201/:220/:235/:241/:300-302/:325-326/:376-378/:388/:412/:421/:430/:438/:456/:464/:467-468/:474-476。BreakpointStore(breakpoint_store.gd)类变量 15(:48-63——**贴顶禁再增**,architecture.md:113 同款登记);公开方法现 5(snapshot/restore_ledger/restore_curio_state/apply_resume_params/restore_stop_bank_fragments);`_bp_read`(:196-202)内部消费点 :160。测试面:feat_vouchers_test.gd 与 meta_progression_forge_test.gd 等 12 处 `orch._rounds._grant_seg._judge_seal(...)` 直调与 `orch._rounds.mines_hits` 7 处——`_grant_seg`/`mines_hits` 成员名与归属不变,零波及。
|
||||
|
||||
**处 4·save_manager ↔ SlotStore(双向)**:save_manager→SlotStore=save_manager.gd:51(`slots._migrate_legacy_save(LEGACY_SAVE_PATH, slots.slot_path(1), ...)`)+:66/:69/:105/:111/:118/:119/:285/:286(`slots._path` ×8)。SlotStore→SaveManagerCore 反向私取(godot-master 终审补查,2026-11-03 本会话 grep 精确实数)=**21 处/21 行**:`_save._read_only`×8(:26/:38/:65/:69/:74/:87/:91/:96)、`_save._reset_to_default`×5(:28/:39/:70/:92/:119)、`_save._data`×4(:66/:75/:88/:97)、`_save._peek_summary_at`×2(:129/:134)、`_save._rename_overwrite`×2(:159/:162)。SlotStore(slot_store.gd)`_path` :9;`_migrate_legacy_save` :150-163(唯一外部调用方=save_manager:51;件内零调用);公开读投影先例=`has_write_target()` :53-54(`_path != ""`)。SlotStore 类变量 4、公开方法 10。SaveManagerCore 私有被用面五成员=`_read_only` :23、`_data` :24、`_reset_to_default` :279、`_peek_summary_at` :217(save_manager 件内调用方 :217 定义、slot_store 两处外部)、`_rename_overwrite` :317(件内调用方 :118/:286);公开方法现 7、类变量 5。
|
||||
|
||||
**处 5·grant_segment → BattleFxHost+config_db → 三表容器**:grant_segment.gd:82-84(`fx_host._fx_new_resource_types.has(ctype)` 读+`[ctype] = true` 写——空串短路边界在 :82)与 :169-170、:378-379(`fx_host._fx_bonus_delta.has(axis)` 守卫+`[axis] += delta`)。BattleFxHost 类变量 15(battle_fx_host.gd:23-37——**贴顶禁再增**,头注 :10-16 自封)、公开方法 16、两私 members 无成员外读者(grep 全库仅 grant 四处)。config_db.gd:157-159 三行 `combat.board_gen._resolver = _resolver`/`combat.enemy._resolver = _resolver`/`run.difficulty._resolver = _resolver`;三表 `_resolver` 声明=board_gen_table.gd:113、enemy_table.gd:212、difficulty_table.gd:33(均无类型注解;消费点 :118/:217/:38)。表实例经 `load()` 出 .tres、无法带构造参,装配期注入是唯一时点(config_db.gd:131-159 `_assign_loaded`)。
|
||||
|
||||
### 3.2 写 T 卡依据的其他现状
|
||||
|
||||
- **段类现状形态**:五段构造=grant/combat 三参(host/fx_host_ref/reward_grant_ref)、aura/decay/verdict 单参(host);RoundCycle 三参直构(host/fx_host_ref/reward_grant_ref,round_cycle.gd:22-29);battle_refresh_flow 全 static(can_refresh/execute 收 `oc` 入参,:15-43)。编排器 `_init`(battle_orchestrator.gd:211-237)建件序=facts(218)→reward_economy(219)→damage(221)→fx_host(223)→reward_grant(225)→RoundCycle(237);类变量 15(38→15 后贴顶)。
|
||||
- **编排器回调宿主方法现签名**:`_emit_row(head, ri, display, value, extra)` :750;`_fatal(msg)` :791;`_install_and_reset(during_round := false) -> bool` :392;`_battle_over(result)` :610;`_exit_distribution()` :575(内含 :593 `_rounds.roll_round_actions()`);`_emit_settlement_snapshot(verdict)` :534;`_emit_composition_effects(side, ri)` :524;公开读投影先例=`_attune_safe_seen_read` :139(RewardGrant attune_safe_seen_cb)、`_pool_effective` :513(pool_effective_cb)——**读投影 Callable 交付是既有形态**(architecture.md:121)。
|
||||
- **编排器三调用点**:`can_refresh()`/`player_request_refresh()` 单行转发(:598-607);`_on_round_end` → `_rounds.settle_if_due()`(:445-447);begin_battle → `_rounds.roll_round_actions()`(:262)。facade 公开签名零参(presentation 路径)。
|
||||
- **测试连带面**:settle_segments_test.gd:20-24 五段 `new(oc, ...)` 直构断言、:28-34 宿主回指断言(`oc._rounds._grant_seg.oc == oc` 等 6 条)——随束形态换代改写;adventure_feats_test.gd:671/:691/:727 `orch._hits_of` 直调——随搬家改指。其余 orch._ 访问(`_facts`×6、`_rounds`×13、`_emit_row`×2)所涉宿主成员全保留,零波及。round_flow_skill_pool_test/seal_polarity_test/refresh_feats_test/effect_port_test 等走公开入口,零改写。
|
||||
- **gdstyle 基线**:tools/gdstyle_baseline.txt 仅 5 键(adventure_runner 类变量 23、level_runner 两键、board_view 两键)——本卡触件均无登记值,T1 现场读数即对账基线。S13 默认阈值:公开方法 ≤20/类变量 ≤15/单函数分支 ≤8/返回 ≤6。
|
||||
- **静态闸**:S7_B1_SET 与 S8_FILES(game/tests/static_scan.sh:317/:361)已含七段文件——本批零闸件改动。S9 R1A 判据=`var x: Dictionary|Array` 裸注解(tools/audit_type_hints.py:22)——新增成员一律具体类名或参数化泛型。
|
||||
- **能力清单**:game/tests/README.md 在役(本卡判据引用行=:59/:63/:86/:89/:92/:124/:174,能力名见第 8 节对照表)。
|
||||
|
||||
## 4. 设计契约(违反即返工红线)
|
||||
|
||||
- 🔴 **逐条一致**:本卡一切内容与处置记录逐条一致;实现段发现卡面与处置记录冲突=上游缺陷,停卡退回写卡段(L3)。
|
||||
- 🔴 **零行为变更**:同种子同输入下动作序列、明细行流、结算快照、信号顺序逐位一致(T1 golden 主证全程保持绿);RNG 消费序零漂移(behavior_roll/encounter/fx_reveal/gp_drop 四封闭流的流名、开流时点、取号序逐字);明细行协议词表零触碰。
|
||||
- 🔴 **段类对编排器引用归零**:七个 settlement 文件(grant/combat/round_cycle/verdict/battle_refresh_flow/aura/decay)全文 `\boc\b` 标识符零命中(含头注与行内注释——随改写一并清除)。
|
||||
- 🔴 **编排器保留面零增减**:architecture.md:141 登记原样——战斗状态机与生命周期、行发射基建(_emit_row/_assert_row_source/_fatal)、呈现投影、刷新面、nest_preview_count。七回调的宿主方法体零改动(Callback 交付不搬家:_emit_row/_fatal/_install_and_reset/_battle_over/_exit_distribution/_emit_settlement_snapshot/_emit_composition_effects 全部留宿主)。
|
||||
- 🔴 **搬家五方法禁留壳**:宿主原方法删除,禁兼容别名、禁转发壳、禁注释化残段(第 13 节全款适用)。
|
||||
- 🔴 **束形态(引用束注入,BoardInstaller 先例 architecture.md:124)**:
|
||||
- **编排器束**(`_init` 组装一个 `Dictionary`,封闭 20 键):`facts`/`units`/`damage`/`status_effects`/`reward_economy`/`reward_grant`/`fx_host`/`minesweeper`/`db`/`action_economy`/`rng` + `emit_row_cb`/`fatal_cb`/`install_cb`/`battle_over_cb`/`exit_distribution_cb`/`emit_snapshot_cb`/`emit_composition_cb` + `attune_param_sum_cb`/`perfect_sweep_cb`。前 11 键=六子对象(BattleFacts/UnitContainer/DamageController/RewardEconomy/StatusContainer/BattleFxHost)+四个既有公开协作件引用(minesweeper/rng/reward_grant——段类现役消费面所需)+两公开读数引用(db/action_economy);后 9 键=七个编排器方法回调(Callable 绑宿主对应方法)+两个公开读投影回调(`attune_param_sum(kind) -> int`/`perfect_sweep_earned() -> bool`——RewardGrant attune_safe_seen_cb/pool_effective_cb 同款先例)。
|
||||
- **接收方各取所需**:RoundCycle 收全束并分发五段(各段构造收同一束);RoundCycle 解包自用七键(facts/units/fx_host/db/action_economy/rng/emit_row_cb);各段断言各自必需键在束(BattleFxHost :41-42 assert 缺键先例)。必需键分配=grant 12(facts/units/damage/reward_economy/fx_host/minesweeper/db/action_economy/reward_grant/emit_row_cb/attune_param_sum_cb/perfect_sweep_cb)、combat 10(facts/units/damage/status_effects/fx_host/minesweeper/db/emit_row_cb/fatal_cb/reward_grant)、aura 1(emit_composition_cb)、decay 2(status_effects/emit_row_cb)、verdict 5(units/emit_row_cb/emit_snapshot_cb/battle_over_cb/exit_distribution_cb)。
|
||||
- **换图刷新流程件同批同形**:BattleRefreshFlow 由 static(oc 入参)改实例——`_init(bundle: Dictionary)` 收 8 键(facts/db/action_economy/fx_host/reward_economy/minesweeper/install_cb/grant_seg);can_refresh/execute 两入口的 `oc` 入参改依赖交付,编排器两公开方法单行转发形态不变(architecture.md:123)。grant_seg 键=段间引用(RoundCycle 构造五段后写入副本束再建本件——授予段引用直接交换图流程件,`oc._rounds._grant_seg` 跨两层私取随之消灭)。
|
||||
- **公开读数注入**:db/action_economy=引用注入(构造期稳定);round_index/battle_result=**调用参数现值交付**(两标量每拍变值,构造期值注入必陈旧)——`settle_if_due(battle_result: String, ri: int)`、`roll_round_actions(ri: int)`、`can_refresh(battle_result: String)`、`execute(battle_result: String, round_index: int)`,编排器调用点传现值(:262/:447/:593/:598-607 四处),facade 零参签名不变。
|
||||
- 🔴 **跨件单向接线**:段类↔编排器只经束注入(引用+Callable),禁双向强引用;注入 Callable 亦属接线面、禁为省参数改持对象引用(architecture.md:143 同款;段类/编排器均 RefCounted,环引用随每战新建泄漏)。
|
||||
- 🔴 **读投影消费形态**:Callable.call 返回 Variant,消费一律 `int(...)`/`bool(...)` 包裹(battle_fx_host.gd:128 facts_cb.call 消费先例)。
|
||||
- 🔴 **S9 参数化形态**:本批全部新增成员声明与函数注解——具体类名(`var facts: BattleFacts`)或参数化泛型(`Dictionary[Variant, Variant]`);裸 `Dictionary`/`Array` var 注解=S9 R1A 红。迁移函数(五方法)注解逐字保持原形(原签名已过 S9)。
|
||||
- 🔴 **fail-fast**:束缺键 assert 致命;零软回退。Core 零 UI 依赖不破(全套件 `--headless --script` 可跑通)。
|
||||
- 🔴 **测试纪律**:禁变异类测试、禁撤销类取证;禁删断言/放宽阈值换绿(第 8 节申报清单之外零删改)。
|
||||
|
||||
## 5. 范围边界
|
||||
|
||||
**收件**=第 1 节表五行全部(settlement 七段解耦+搬家五方法+breakpoint_store 公开面+存档双向公开面〔save_manager↔SlotStore 两方向〕+battle_fx_host 两累积方法+三 schema 挂载方法,及各自的调用点改址与测试适配)。
|
||||
|
||||
**不收件**(去向已指认):
|
||||
- presentation 层约 227 行私取面——**另开设计讨论**(本卡裁决范围外;去向=待办清单本条目实况,非本批)。
|
||||
- sim/probe/tests 的测量面直构惯例与测试受控例外——零清扫(orch._facts/orch._rounds/orch._emit_row 等测试直连维持现状)。
|
||||
- 段类→协作件残余私取一处:grant_segment.gd:197 `oc._damage._emit_hero_damage_taken(...)` 随本批改经 `damage.emit_hero_damage_taken(...)`(DamageController 该方法去下划线公开化,见 T2)——除此之外段类对 damage/fx_host/reward_grant 公开成员的直读(counters_ctx/engine/facts_inject/defer)零触碰。
|
||||
- 职责归属零改动(除搬家五方法——已裁的五处归位);编排器七回调宿主方法体零改动;架构七段结构零改动(五段段序、SettlementTable.segment_order、RoundCycle/BattleRefreshFlow/五段段类的文件与职责登记全部在案不动)。
|
||||
- 闸件(static_scan.sh)零改动;MC/模拟零跑(无数值改动);`tools/gdstyle_baseline.txt` 零改动(本批无键恶化,见第 14 节)。
|
||||
|
||||
## 6. 关联文档同步面
|
||||
|
||||
实现批禁写 `design/` 整个目录、两份根流程清单与 `game/tests/README.md`;下表每条的落文义务全部进 `reports/iter<N>-反哺点-<日期>.md`(N=编排段定),由用户裁决后归文档批落文:
|
||||
|
||||
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务(反哺点清单逐条承载) |
|
||||
|---|---|---|
|
||||
| design/engineering/architecture/architecture.md | :125 RoundCycle 行「三参直构(host/fx_host_ref/reward_grant_ref——五段构造透传不落成员)」→ 束注入+持有 BattleRefreshFlow+公开方法 3→4+类变量 8→15(贴顶);:123 BattleRefreshFlow 行 static 两入口收 oc → 实例束注入、宿主改经 RoundCycle 交接 grant_seg、类变量 0→8;:127 settlement/ 五段段类行构造形态句 → 束注入、对编排器零引用;:122 damage_controller 行实测类变量 12→13+公开面净增(hero_atk/hits_of/emit_hero_damage_taken);:121 RewardGrant 行 +feat_yield_adjust;:120 BattleFxHost 行 +两累积方法(类变量 15 不变);核心层表 A2 minesweeper_rules 行公开面 18→20(贴顶);核心层表 breakpoint_store 行公开方法面 5→18;核心层表 save_manager 行公开面 7→14(+5 承接方法+peek_summary_at/rename_overwrite 两更名公开化)+slot_store 行「双向公开面」(21 处反向私取清零) | 反哺点清单逐条列行号与改后登记内容——**机械面文档禁直改** |
|
||||
| design/gdd/systems/战斗循环/战斗结算.md | 无陈述变化(明细流水词表、五段段序、段边界全部零触碰——零行为变更批) | 反哺点清单写「零反哺」确认行 |
|
||||
| 术语表 | 无新术语(引用束注入/读投影/公开方法面均仓库现行词) | 确认行「零新增术语」 |
|
||||
|
||||
(机检口径:本表同步义务格无一条写「随批」。)
|
||||
|
||||
## 7. 任务卡 T1..T5
|
||||
|
||||
### 卡前·文件结构图
|
||||
|
||||
全部行为面=非行为改动(零行为变更批),行标【非行为】+对照表 R 行号;测试件全部为随逻辑写/改的测试代码。一起改的按职责放一起——段类七文件同卡(T2)、存档断点两对同卡(T3)。
|
||||
|
||||
```
|
||||
core 层(编排域)
|
||||
game/core/battle_orchestrator.gd 【非行为 R1/R2】_init 束组装(20 键);:70-71/:452-461/:466-473/:478-485/:489-494 五方法删除;:282 hero_atk 改指 _damage.hero_atk();:262/:447/:593 三调用点传参;:598-607 facade 改经 _rounds.refresh_flow()
|
||||
game/core/settlement/round_cycle.gd 【非行为 R1】束注入(15 成员贴顶)+持有/构建 BattleRefreshFlow+settle_if_due/roll_round_actions 签名扩展+refresh_flow() 读出口
|
||||
game/core/settlement/grant_segment.gd 【非行为 R1/R2/R3】束解包 12 成员+54 处改址+:82-84/:169-170/:378-379 改公开累积方法+头注改写
|
||||
game/core/settlement/combat_segment.gd 【非行为 R1/R2】束解包 10 成员+23 处改址+hero_atk 改指
|
||||
game/core/settlement/aura_segment.gd 【非行为 R1】单回调成员+头注改写
|
||||
game/core/settlement/decay_segment.gd 【非行为 R1】两成员+改址
|
||||
game/core/settlement/verdict_segment.gd 【非行为 R1】束解包 5 成员+四回调改址
|
||||
game/core/settlement/battle_refresh_flow.gd 【非行为 R1】static 改实例+束注入 8 成员+grant_seg 段间引用
|
||||
game/core/damage_controller.gd 【非行为 R2】+facts 成员(12→13)+hero_atk()+static hits_of()+_emit_hero_damage_taken 公开化(:449/:561 内部调用点随改)
|
||||
game/core/reward_grant.gd 【非行为 R2】+feat_yield_adjust()
|
||||
game/core/minesweeper_rules.gd 【非行为 R2】+harmful_variants()/harmful_adjacent()(公开 18→20 贴顶)
|
||||
game/core/battle_fx_host.gd 【非行为 R3】+mark_new_resource_type()/+add_bonus_delta()(成员 15 不变)
|
||||
core 层(冒险/存档域)
|
||||
game/core/breakpoint_store.gd 【非行为 R4】+13 公开读写方法面(成员 15 不变;_bp_read 更名 bp_read 公开化——:160 内部调用点随改)
|
||||
game/core/adventure_runner.gd 【非行为 R4】37 处改址(:107..:476 逐处)
|
||||
game/core/save_manager.gd 【非行为 R5】+5 公开方法(set_read_only/read_only/reset_to_default/data_snapshot/restore_data)+_peek_summary_at/_rename_overwrite 更名公开化(件内调用点随改);:51/:66/:69/:105/:111/:118-119/:285-286 九行改址
|
||||
game/core/slot_store.gd 【非行为 R5】+active_path();_migrate_legacy_save 更名 migrate_legacy_save 公开化;反向私取 21 处改址(_save._ → save_manager 公开面)
|
||||
game/core/config_db.gd 【非行为 R6】:157-159 三行改经 bind_resolver()
|
||||
game/data/schemas/board_gen_table.gd 【非行为 R6】+bind_resolver(resolver: ConfigDbResolver)
|
||||
game/data/schemas/enemy_table.gd 【非行为 R6】同上
|
||||
game/data/schemas/difficulty_table.gd 【非行为 R6】同上
|
||||
测试件(随逻辑写/改)
|
||||
tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd 【非行为 R1·新增】同种子逐项 golden 对拍(主证)
|
||||
tests/unit/core/encapsulation_sweep_test.gd 【非行为 R1–R6·新增】五处结构性零命中扫描(非空前置+正锚)
|
||||
tests/unit/core/settle_segments_test.gd 【非行为 R1】:20-34 束构造与同一性断言适配
|
||||
tests/unit/core/adventure_feats_test.gd 【非行为 R2】:671/:691/:727 hits_of 改指 DamageController.hits_of
|
||||
tests/run_all.gd 【非行为】manifest +2 行(snapshot/sweep)
|
||||
文档件
|
||||
game/tests/README.md 写卡段判断=零编辑(第 8 节能力行判断依据)——实现批禁写,批末只核对表上能力名与对照表引用一致
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**T1 基线固化与主证落盘**(估时 0.25 工作日;区间 0.25–0.5)
|
||||
取用:无(本卡起点)。产出:golden 基线(改前读数冻结)+S13 对账基线+grep 底账;本卡实现排序核对。
|
||||
|
||||
- [ ] 核对实现排序在案:3.1+3.2 卡(迭代 50)未合回则本批不开工(第 1 节排序义务);combat_segment.gd 现址复核(甲案 :59-70 分支已删则以 grep 符号锚定位,行号漂移即记录进实现报告,禁改判据)
|
||||
- [ ] 核对处置记录 `reports/处置-架构审查5.1封装修复-2026-11-03.md` 已落盘且与本卡第 3 节逐条一致(冲突=L3 停卡)
|
||||
- [ ] 新增 tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd(extends SceneTree+Kit.check 主通道,全类型标注):手搭驱动=`ConfigDbScript.new()`+`load_tables("res://data/tables", true)`→`RngServiceCore` set_master_seed(4242)→`BattleOrchestrator.new(db, rng)`;捕获面=`step_row` 全量行数组+`settlement_snapshot` 全量载荷数组+`battle_finished` 载荷+收束时 `presentation_snapshot()` 关键键(round/battle_result/hero.hp/enemies.size())。驱动序(逐字定死):①`begin_battle({"level_index": 1, "node_depth": 1, "hero_hp": int(db.combat.hero.max_hp), "voucher_rap": 20})`;②轮 1:`AutoPlayer.choose_dig(minesweeper)` 返 `{dig_cell, hero_cell}` 非空则 `settle_batch([{"action": "move", "cell": hero_cell}])`→`settle_batch([{"action": "dig", "cell": dig_cell}])`→对首个未揭示且与主角相邻的格 c `settle_batch([{"action": "seal_place", "cell": c}])`(封印已揭示格在棋盘面必拒〔target_revealed〕——封印子链 _judge_seal_hit/_seal_hit_effects/_judge_seal_miss 及封印匠/示警烟火/完美保险扩展行必须真实进入 golden 行流;「封已揭示安全格」的拒绝路径由 seal_polarity_test 既有回归兜底,不入 golden 主证)→`settle_batch([{"action": "stop"}])`;③轮 1 结算后 `player_request_refresh()`(voucher_rap=20 保证 RAP 抵折后价——覆盖换图刷新链:can_refresh/execute/install_cb/grant_seg 成功事实);④轮 2:choose_dig 一挖一停;⑤轮 3:径直 `settle_batch([{"action": "stop"}])`。断言=捕获序列与 `const GOLDEN`(行字典逐位含 type/source_class/origin_cell/round_index/display_name/value/其余载荷键)逐位相等〔封装5.1 V1〕
|
||||
- [ ] **改前取数**:本步骤在任何生产码改动之前执行——先写测试与空跑转储通道(GOLDEN 为空时打印捕获序列 JSON 后按预期码退出),在未改树上跑出 golden、填入 GOLDEN 常量、复跑全绿;golden 即改前基线读数(不构成验收,验收=改后全程保持绿)
|
||||
- [ ] S13 对账基线:对本卡全部 core/data 存量触件(第 14 节清单 15 件)现场跑 gdstyle 记读数为基线(既有登记仅 adventure_runner 类变量 23 一件照登对账);跑 `python tools/run_smoke.py` 冒烟基线全绿读数落实现报告
|
||||
- [ ] grep 底账五件落实现报告:`oc\._`(settlement 七文件)、`_bp_store\._`(adventure_runner)、`slots\._`(save_manager)、`_save\._`(slot_store——反向私取 21 处)、`_fx_new_resource_types|_fx_bonus_delta`(grant)与 `\._resolver =`(config_db)——命中行号清单=T5 sweep 的改前底账
|
||||
|
||||
**T2 settlement 七段解耦+搬家五方法**(估时 1.25 工作日;区间 1–1.5)
|
||||
取用:T1 golden 基线。产出:处 1+处 2 清零——段类对编排器引用归零、五方法归位。
|
||||
|
||||
- [ ] battle_orchestrator.gd `_init`(:211-237):RoundCycle 构造改 `RoundCycle.new(束)`——束 20 键逐字(第 4 节束形态表;Callable 键绑自对应方法:`"emit_row_cb": _emit_row`、`"fatal_cb": _fatal`、`"install_cb": _install_and_reset`、`"battle_over_cb": _battle_over`、`"exit_distribution_cb": _exit_distribution`、`"emit_snapshot_cb": _emit_settlement_snapshot`、`"emit_composition_cb": _emit_composition_effects`、`"attune_param_sum_cb": attune_param_sum`、`"perfect_sweep_cb": perfect_sweep_earned`)
|
||||
- [ ] 搬家五方法落位(宿主体逐字迁移、注解逐字保持):
|
||||
- damage_controller.gd:`_init` 加第五参 `facts_ref`(成员 `var facts: BattleFacts`,:49 构造体加行);新增 `func hero_atk() -> int`(体=battle_orchestrator.gd:70-71 逐字,`_facts`→`facts`);新增 `static func hits_of(hits: Array, kind: String) -> Array`(体=:489-494 逐字);`_emit_hero_damage_taken` 更名 `emit_hero_damage_taken` 公开化(体逐字;内部调用点 :449/:561 随改)
|
||||
- reward_grant.gd:新增 `func feat_yield_adjust(snap: Dictionary, positive: bool, pos_m: int, neg_m: int) -> Dictionary`(体=:452-461 逐字——reward_economy 为本件既有成员 :22)
|
||||
- minesweeper_rules.gd:新增 `func harmful_variants(vids: Array) -> Array` 与 `func harmful_adjacent(cell: Vector2i) -> Array`(体=:466-473/:478-485 逐字——db 为本件构造参、current_board() 自有;**:484 内部自呼 `_harmful_variants(board.variant_ids(n))` 随更名改 `harmful_variants(board.variant_ids(n))`,禁留旧名**)
|
||||
- battle_orchestrator.gd:五方法整段删除(:70-71/:452-461/:466-473/:478-485/:489-494);:282 `hero_atk_override: _hero_atk()` → `_damage.hero_atk()`
|
||||
- [ ] round_cycle.gd 重写:`_init(bundle: Dictionary)`——断言 7 必需键(facts/units/fx_host/db/action_economy/rng/emit_row_cb)后解包为同名成员;五段构造改 `XxxSegment.new(bundle)`;复制束写入 `"grant_seg": _grant_seg` 后构建 `BattleRefreshFlow.new(束副本)`;`settle_if_due(battle_result: String, ri: int)`(:35→参数、:40 删、段驱动用 ri);`roll_round_actions(ri: int)`(:67/:80 用 ri);新增 `func refresh_flow() -> BattleRefreshFlow`;全文 `oc.` 改址(映射表=`oc._facts`→`facts`、`oc._enemy_system`→`units`、`oc._emit_row`→`emit_row_cb.call`、`oc._fx_host`→`fx_host`、`oc.db`→`db`、`oc.action_economy`→`action_economy`、`oc.rng`→`rng`);头注「耦合边界」段改写(束注入+签名扩展+随编排器每战新建同灭语义不变)
|
||||
- [ ] grant_segment.gd 重写:`_init(bundle: Dictionary)` 断言 12 键解包 12 成员(第 4 节分配表);54 处改址——除上表映射外加:`oc._reward_economy`→`reward_economy`、`oc.minesweeper`→`minesweeper`、`oc._hero_atk()`→(无此调用)、`oc._feat_yield_adjust(...)`→`reward_grant.feat_yield_adjust(...)`(:99/:140)、`oc._harmful_variants`→`minesweeper.harmful_variants`(:87)、`oc._harmful_adjacent`→`minesweeper.harmful_adjacent`(:339)、`oc._hits_of`→`DamageController.hits_of`(:110/:115/:138/:356)、`oc.attune_param_sum("rap_transfer_mult")`→`int(attune_param_sum_cb.call("rap_transfer_mult"))`(:280)、`oc.perfect_sweep_earned()`→`bool(perfect_sweep_cb.call())`(:284)、`oc._damage._emit_hero_damage_taken(...)`→`damage.emit_hero_damage_taken(...)`(:197);:82-84 改 `var is_new_type := fx_host.mark_new_resource_type(ctype)`;:169-170 与 :378-379 改 `fx_host.add_bonus_delta(String(h.get("axis", "")), int(h.get("delta", 0)))`;头注改写
|
||||
- [ ] battle_fx_host.gd 新增两公开累积方法(成员零增,头注类变量封闭面句不动):`func mark_new_resource_type(ctype: String) -> bool`——`if ctype == "": return false`;`if _fx_new_resource_types.has(ctype): return false`;置位后 `return true`(空串短路边界=原 :82 形态逐位等价)。`func add_bonus_delta(axis: String, delta: int) -> void`——`if _fx_bonus_delta.has(axis): _fx_bonus_delta[axis] += delta`
|
||||
- [ ] combat_segment.gd 重写:`_init(bundle)` 断言 10 键解包;23 处改址(映射同上+`oc._fatal`→`fatal_cb.call`、`oc._status_effects`→`status_effects`、`oc._hero_atk()`→`damage.hero_atk()`);`oc._hits_of` 行随 3.1+3.2 批已删——复核以 grep 为准;头注改写
|
||||
- [ ] aura_segment.gd(成员 `var emit_composition_cb: Callable`,:15-16 改 `emit_composition_cb.call("hero", ri)`/`("enemy", ri)`)、decay_segment.gd(成员 status_effects+emit_row_cb)、verdict_segment.gd(成员 units+四回调,:18/:20 `units.hero_unit()`/`units.query_alive("enemy")`、:22 `emit_snapshot_cb.call(verdict)`、:25/:29 `battle_over_cb.call(...)`、:32 `exit_distribution_cb.call()`)三件重写+头注改写
|
||||
- [ ] battle_refresh_flow.gd 重写:去 static——`_init(bundle: Dictionary)` 断言 8 键(facts/db/action_economy/fx_host/reward_economy/minesweeper/install_cb/grant_seg)解包;`_effective_refresh_cost()` 无参实例方法(:15-20 体逐字,`oc.db`→`db`、`oc.fx_host().fx_emit`→`fx_host.fx_emit`);`can_refresh(battle_result: String) -> bool`(:24-28 体逐字,`oc.battle_result`→参数、`oc._facts.refresh_used`→`facts.refresh_used`);`execute(battle_result: String, round_index: int) -> bool`(:32-43 体逐字——`oc._facts.refresh_used += 1`→`facts.refresh_used += 1`、`oc._reward_economy.retire_mapping()`→`reward_economy.retire_mapping()`、`oc.minesweeper.retire_board(true)`→`minesweeper.retire_board(true)`、`oc._install_and_reset(true)`→`bool(install_cb.call(true))`、`oc._rounds._grant_seg.apply_board_refreshed(oc.round_index)`→`grant_seg.apply_board_refreshed(round_index)`);头注「调用路径」句改写(编排器单行转发形态不变)
|
||||
- [ ] battle_orchestrator.gd 收口::598-599 `return BattleRefreshFlow.can_refresh(self)`→`return _rounds.refresh_flow().can_refresh(battle_result)`;:606-607 →`return _rounds.refresh_flow().execute(battle_result, round_index)`;:262 `roll_round_actions()`→`roll_round_actions(round_index)`;:447 `settle_if_due()`→`settle_if_due(battle_result, round_index)`;:593 →`roll_round_actions(round_index)`;`can_refresh`/`player_request_refresh`/`_on_round_end`/`begin_battle`/`_exit_distribution` 五处体注释同步+:280-281 注释(「`_hero_atk` 派生读=受理后不变量」句引用将删除的方法名)随 :282 改指一并改写
|
||||
- [ ] 测试适配:settle_segments_test.gd :20-24 五段直构断言改束形态(以真实编排器协作件组装束逐段 `new(bundle)` 成功断言);:28-34 宿主回指断言 6 条改同一性断言(`oc._rounds._grant_seg.facts == oc._facts`、`oc._rounds._combat_seg.fx_host == oc.fx_host()` 等——同一性强度对应回指,削减弱化申报 1);adventure_feats_test.gd :671/:691/:727 `orch._hits_of(...)` → `DamageController.hits_of(...)`(削减弱化申报 2)
|
||||
- [ ] 孤立验证新增段 → 出红只跑红件最小单元 → 并入全套(回归措辞:里程碑卡出口跑一次全套闸;卡内修复只做出红最小单元的最窄确认);本卡出口=golden 快照绿+battle_settlement 套件全绿+冒烟全绿
|
||||
|
||||
**T3 断点与存档公开面**(估时 0.625 工作日;区间 0.5–0.75)
|
||||
取用:T1 底账。产出:处 3+处 4 双向清零。
|
||||
|
||||
- [ ] breakpoint_store.gd 新增公开方法面(13 个,成员零增——类变量 15 贴顶):`func bind_save_manager(sm: SaveManagerCore) -> void`、`func save_manager() -> Variant`(读投影,可 null)、`func set_pending_next_level(v: bool) -> void`/`func pending_next_level() -> bool`、`func set_loadout_seeded(v: bool) -> void`/`func loadout_seeded() -> bool`、`func set_resume_bp(bp: Dictionary) -> void`/`func clear_resume_bp() -> void`/`func resume_bp() -> Dictionary`(返引用零拷贝——宿主读侧只读)、`func bp_read(key: String, bp: Dictionary, fallback: Variant = null) -> Variant`(=_bp_read 更名公开化,:160 内部调用点随改)、`func set_last_level_payload(payload: Dictionary) -> void`/`func last_level_payload() -> Dictionary`、`func set_last_treasure_cleared(v: int) -> void`/`func last_treasure_cleared() -> int`(方法体一律一行转发自有成员,零逻辑增量)
|
||||
- [ ] adventure_runner.gd 37 处改址(逐处)::107/:157/:180/:185/:241/:438 → `set_pending_next_level(...)`;:235 → `pending_next_level()`;:115/:191/:201 → `set_loadout_seeded(false)`;:300-301 → `loadout_seeded()`/`set_loadout_seeded(true)`;:189 → `set_resume_bp(bp.duplicate(true))`;:388 → `clear_resume_bp()`;:302/:376/:377/:378 → `resume_bp()`(读侧零拷贝语义不变);:168/:302/:377/:378/:412 `_bp_read` → `bp_read`;:220 → `bind_save_manager(sm)`;:325-326 → `var sm = _bp_store.save_manager()` 后 `if sm != null: first = not sm.meta_state.career_state()...`;:421 → `set_last_level_payload(payload.duplicate(true))`;:464/:467-468 → `last_level_payload()`;:430 → `set_last_treasure_cleared(...)`;:456 → `last_treasure_cleared()`;:474-476 → `var sm = _bp_store.save_manager()` 后 `sm.clear_breakpoint()`/`sm.write_to_disk()`;:37 头注自述句核改(「宿主读写经件」落实后注释与实态一致)
|
||||
- [ ] slot_store.gd:新增 `func active_path() -> String: return _path`(读投影——has_write_target :53 同族);`_migrate_legacy_save` 更名 `migrate_legacy_save` 公开化(:150 体逐字;禁留旧名壳);**反向私取 21 处改址**(第 3.1 节处 4 清单):`_save._read_only` 写 4 处(:26/:38/:69/:91)→ `_save.set_read_only(false)`、读 2 处(:65/:87)→ `var prev_ro: bool = _save.read_only()`、恢复写 2 处(:74/:96)→ `_save.set_read_only(prev_ro)`;`_save._reset_to_default` ×5(:28/:39/:70/:92/:119)→ `_save.reset_to_default()`;`_save._data` 读 2 处(:66/:88)→ `var prev_data = _save.data_snapshot()`、恢复写 2 处(:75/:97)→ `_save.restore_data(prev_data)`(引用零拷贝语义不变——snapshot 返 `_data` 本引用);`_save._peek_summary_at` ×2(:129/:134)→ `_save.peek_summary_at(...)`;`_save._rename_overwrite` ×2(:159/:162)→ `_save.rename_overwrite(...)`
|
||||
- [ ] save_manager.gd 新增公开方法面承接 SlotStore 反向私取(类变量零增;公开 7→14):`func set_read_only(v: bool) -> void`/`func read_only() -> bool`(体一行转发 `_read_only`)、`func reset_to_default() -> void`(体=:279 逐字公开化——件内调用点零改,同名);`func data_snapshot() -> Dictionary[String, Variant]: return _data`/`func restore_data(data: Dictionary[String, Variant]) -> void: _data = data`(零拷贝——还原引用);`_peek_summary_at` 更名 `peek_summary_at` 公开化(:217 体逐字;**件内调用点复核**——slot_store :129/:134 为外部消费,件内若另有调用随改);`_rename_overwrite` 更名 `rename_overwrite` 公开化(:317 体逐字;件内调用点 :118/:286 随改)
|
||||
- [ ] save_manager.gd 九行改址::51 → `slots.migrate_legacy_save(...)`;:66/:69/:105/:111/:118/:119/:285/:286 `slots._path` → `slots.active_path()`(:118-119 两处同名调用间 `_path` 无变更窗口——单线程同步段,逐位等价)
|
||||
|
||||
**T4 效果宿主累积面与配置挂载面**(估时 0.375 工作日;区间 0.25–0.5)
|
||||
取用:T2(grant 已改指)。产出:处 5 清零(本卡 T2 已落 grant 改址与 battle_fx_host 两方法——本卡复核其孤立验证读数)。
|
||||
|
||||
- [ ] 复核 T2 步骤中 battle_fx_host.gd 两方法与 grant_segment.gd 四处改址已落(T2 内联实装——本卡不重复列);孤立验证:grant_segment 相关套件(seal_polarity/round_flow)出红最小单元
|
||||
- [ ] board_gen_table.gd / enemy_table.gd / difficulty_table.gd 各新增 `func bind_resolver(resolver: ConfigDbResolver) -> void`(体一行 `_resolver = resolver`;三件注解同型)
|
||||
- [ ] config_db.gd:157-159 三行改 `combat.board_gen.bind_resolver(_resolver)` / `combat.enemy.bind_resolver(_resolver)` / `run.difficulty.bind_resolver(_resolver)`(_assign_loaded 装配序零变化)
|
||||
- [ ] **三 schema 解析冒烟(类型环验证义务)**:bind_resolver 引入 schema→ConfigDbResolver 参数类型注解,与 resolver 既有反向引用(config_db_resolver.gd:41/:61 引 EnemyTable.ROW_KINDS/band_of——:3-8 头注「类型环断根」先例)构成类型引用环——孤立验证必含 config_db_resolver_test 全套当轮真实跑(三 schema 经 `load()` 实例化+resolver 注入+resolve_row/resolve_rowset/resolve_modifiers 真实解析,类型环若引入解析失败当轮即炸);出红即 L3 停卡(禁改走 type-hint: ignore 通道——保 schema 类型注解完整)
|
||||
|
||||
**T5 结构性扫描与批收口**(估时 0.375 工作日;区间 0.25–0.5)
|
||||
取用:全部前卡。产出:五处结构性恒零证据+批收口两件。
|
||||
|
||||
- [ ] 新增 tests/unit/core/encapsulation_sweep_test.gd(extends SceneTree+Kit.check,全类型标注;源读取手法沿 player_copy_sweep_test 源 token 扫描先例)——七段断言组,全部带「扫描面非空前置+正锚」:
|
||||
①七段文件集(settlement/ 七 .gd)逐件:文件存在且非空+含对应 `class_name` 正锚+`\boc\b` 全文零命中〔封装5.1 V2〕
|
||||
②battle_orchestrator.gd:非空+`func _hero_atk|func _feat_yield_adjust|func _harmful_variants|func _harmful_adjacent|func _hits_of` 零命中(五方法零残留)〔封装5.1 V3〕
|
||||
③adventure_runner.gd:非空+`_bp_store\._` 零命中+`_bp_store.bp_read(` 正锚(新面在用)〔封装5.1 V4〕
|
||||
④save_manager.gd:非空+`slots\._` 零命中+`slots.active_path()` 正锚;slot_store.gd:非空+`_save\._` 零命中+`_save\.(set_read_only|read_only|reset_to_default|data_snapshot|restore_data|peek_summary_at|rename_overwrite)` 正锚〔封装5.1 V5〕
|
||||
⑤grant_segment.gd:非空+`_fx_new_resource_types|_fx_bonus_delta` 零命中+`mark_new_resource_type(` 正锚〔封装5.1 V6〕
|
||||
⑥config_db.gd:非空+`\._resolver\s*=` 零命中+`bind_resolver(_resolver)` 正锚〔封装5.1 V7〕
|
||||
- [ ] run_all.gd manifest 追加 2 行:settlement_wiring_snapshot_test(expect 0,注记「R1 同种子逐项 golden 对拍主证〔封装5.1〕」)+encapsulation_sweep_test(expect 0,注记「R1–R6 结构性零命中扫描〔封装5.1〕」)
|
||||
- [ ] **实现报告** `reports/iter<N>-实现报告-<日期>.md`:各卡状态+S13 键改前改后对账表(T1 基线逐件核)+golden 改前改后对拍读数+实现决定记录(代拍板白名单逐条回填)
|
||||
- [ ] **反哺点清单** `reports/iter<N>-反哺点-<日期>.md`:第 6 节同步面表逐条落点(architecture.md 八行登记内容、GDD/术语确认行)
|
||||
- [ ] 批末核对:game/tests/README.md 能力名与对照表引用一致(本卡零编辑);独立验收审计(第 8 节末)未过不合并;.uid 收口=`--editor --quit` 一次后确认 2 件新测试件 .uid 已生成随批提交
|
||||
|
||||
### 估时汇总
|
||||
|
||||
T1 0.25|T2 1.25|T3 0.625|T4 0.375|T5 0.375。
|
||||
区间合计 2.25–3.75 工作日;**精确汇总 2.875 工作日**(切分预案:若 T2 超 1.5 工日,把 T3 切出为独立半日卡顺延,其余不动;合计超 3 工作日=超卡面估时域,须用户确认后方可续批)。
|
||||
|
||||
## 8. 验证闸(改动—验收对照表)
|
||||
|
||||
测试方式两分法:下表全部走**调试接口验证**(单元/集成套直构夹具与真实入口调用);**正常流程体验验证**=零项(零行为变更批,无目检点——实机观感逐位同改前)。判据全部绑被测改动特有的可观测提交面(同种子行流逐位/束引用同一性/源码零命中带非空前置与正锚)。
|
||||
|
||||
| 需求点 | 改动(文件:行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| R1 七段解耦+束交付 | settlement 七文件重写+battle_orchestrator 束组装与三调用点+RoundCycle/BattleRefreshFlow 形态换代 | settlement_wiring_snapshot_test.gd:_init 主对拍〔封装5.1 V1〕;settle_segments_test.gd 束构造与同一性断言;round_flow_skill_pool_test/seal_polarity_test/refresh_feats_test 既有全套回归 | 单元+集成 | `BattleOrchestrator.begin_battle()`→`MinesweeperRules.settle_batch()`→`player_request_refresh()`(全程公开入口) | 同种子行流与快照逐位同 golden(改前固化);段持注入引用==编排器实例同一性;`\boc\b` 七文件零命中 | 既有:轮内流与结算五段全序 |
|
||||
| R2 搬家五方法归位 | damage_controller +hero_atk/hits_of/emit_hero_damage_taken 公开化+facts 成员;reward_grant +feat_yield_adjust;minesweeper_rules +harmful_variants/harmful_adjacent;编排器五方法删除+:282 改指 | settlement_wiring_snapshot_test〔封装5.1 V1〕(五方法消费路径全在行流内——主角攻击 base_value/奖励乘区/terrain_kind 事实/奥术矢开单);roll_multiplier_test.gd:_smoke_hero_atk_derived 既有回归;adventure_feats_test hits_of 面回归;encapsulation_sweep_test 编排器五方法定义零命中〔封装5.1 V3〕 | 单元 | `begin_battle()`(enc hero_atk override→spawn→攻击单)/授予段真实结算链 | 攻击单基值随 enc override 走(派生读贯通);行流逐位同;五方法宿主定义唯一(编排器零残留) | 既有:伤害公式与掷点乘区 |
|
||||
| R3 grant→BattleFxHost 累积方法 | battle_fx_host +mark_new_resource_type/+add_bonus_delta;grant :82-84/:169-170/:378-379 改址 | seal_polarity_test/round_flow_skill_pool_test 既有全套回归(血税 bonus_delta 与地质学家 new_resource_type 两订阅行行为面);encapsulation_sweep_test grant 私键零命中+正锚〔封装5.1 V6〕 | 单元 | 授予段真实结算链(mine_hit/seal_hit fx 发射→施加面) | bonus_delta 轴累积值与 new_resource_type 首见判定逐位同;grant 源零私键直写 | 既有:封印与极性路由/不可逆 |
|
||||
| R4 adventure_runner→BreakpointStore | breakpoint_store +13 公开方法面(_bp_read 更名 bp_read);adventure_runner 37 处改址 | save_rng_roundtrip_test.gd:_test_old_version_save_migrates_and_resumes+:_test_disk_roundtrip_preserves_breakpoint 既有回归(断点组装/回放/续玩全链真实入口);encapsulation_sweep_test `_bp_store\._` 零命中〔封装5.1 V4〕 | 单元+集成 | `AdventureRunner.resume_adventure()`/`start_adventure()`→`write_to_disk()`/`load_from_disk()` | 断点续玩逐位同(27 键冻结);adventure_runner 源零 `_bp_store._` 直读写 | 既有:旧档迁移链与断点续玩零跳号(集成) |
|
||||
| R5 save_manager↔SlotStore 双向公开面 | save_manager→SlotStore=slot_store +active_path/_migrate 更名公开化+save_manager 九行改址;SlotStore→SaveManagerCore=save_manager +5 公开方法/2 更名公开化+slot_store 21 处改址 | save_manager_domain_test.gd:_smoke_save+save_slot_isolation_test 既有回归;encapsulation_sweep_test `slots\._` 与 `_save\._` 双向零命中+双正锚〔封装5.1 V5〕 | 单元 | `SaveManagerCore.write_to_disk()`/`load_from_disk()`/`_ready()` 迁移口/`SlotStore.activate_slot()`(三态恢复路径——read_only/data 快照还原)/`peek_slot_summary()`(窥视委托) | 写盘/读回/迁移/激活-恢复/窥视路径逐位同(tmp+rename 原子序、零拷贝还原语义不变);save_manager 源零 `slots._`+slot_store 源零 `_save._` | 既有:存档写盘⇄读回往返保真 |
|
||||
| R6 config_db→三表挂载 | 三 schema +bind_resolver;config_db :157-159 改址 | config_db_resolver_test.gd 既有全套回归(_test_rowset_order_preserved/_test_row_kind_routing/_test_difficulty_clamp——resolver 注入后解析面逐位同);encapsulation_sweep_test `\._resolver =` 零命中+正锚〔封装5.1 V7〕 | 单元 | `ConfigDB.load_tables()`(装配段)→`ConfigDbResolver.resolve_*()` | 行集解析/难度 clamp 逐位同;config_db 源零 `_resolver` 直写 | 既有:行集寻址、行序保序与难度乘数 clamp |
|
||||
|
||||
**零行为改动面的证据义务**:本卡全部六行均为非行为改动(零行为变更批)——不设「行为改动」行;每行的零变更证明=T1 golden 同种子逐项比对(改前固化、改后全程绿)+既有套件零转红+结构性 sweep 恒零。能力行全部「既有」、零新增——判断依据:本批零行为变更=玩家可观测能力面零变化,无新能力可登记;受影响存量行的真实入口与代表用例名零变化(settle_segments_test/adventure_feats_test 文件名与其在册引用不变),故能力清单零编辑(批末核对义务在 T5)。**覆盖登记(test-conventions §8.3 新增 core 件覆盖登记义务,2026-11-04 并 master 后适配)**:本批触碰且曾被审计点名的三件按「经宿主链覆盖」申报——breakpoint_store=R4 行 `AdventureRunner.resume_adventure()/start_adventure()`→`write_to_disk()/load_from_disk()` 链+新增 sweep 源扫描;slot_store=R5 行 `SaveManagerCore.write_to_disk()/load_from_disk()/_ready()` 迁移口链;battle_fx_host=R1/R3 行 `begin_battle()` 全结算链;三件申报面之外零新增点名义务,meta_state_store 本卡零触碰。
|
||||
|
||||
**闸口径**:重闸=`tools/run_all_gates.sh` 按本批改动域选档(改动含 game/ 下非 .md 行为载体 → `--code`);所选域全绿才合并。卡内不写死闸件名单。回归措辞:里程碑卡(T 段)出口跑一次全套闸;卡内修复只做出红最小单元的最窄确认;新增测试先行孤立验证再并入全套。
|
||||
|
||||
**测试削弱申报**(允许改/删的旧断言全清单;未申报的删改由独立验收审计判红):
|
||||
1. settle_segments_test.gd:20-24 五段直构断言——构造签名换代(host 三参/单参 → 束单参),断言对象从构造签名改束构造成功;段类可独立实例化的断言意图保持,强度不减(R1)。
|
||||
2. settle_segments_test.gd:28-34 宿主回指断言 6 条(`.oc == oc`)——段类对编排器引用归零后回指对象消失;改注入引用同一性断言(段持 facts/fx_host==编排器实例),装配面断言意图保持,强度不减(R1)。
|
||||
3. adventure_feats_test.gd:671/:691/:727 `orch._hits_of(...)` → `DamageController.hits_of(...)`——方法搬家改址,断言内容(attack_bonus 命中过滤)零改动(R2)。
|
||||
以上 3 条均为「随被测改动同步的引用形态迁移」,无一条删除断言或放宽阈值。
|
||||
|
||||
**独立验收审计**:入口=批末 T5 后、合并前;报告=`reports/iter<N>-验收审计-<日期>.md`;由没参与实现的会话或子代理执行,核对:对照表逐行断言真实存在且在当轮跑批通过、golden 改前改后对拍读数在案、测试削弱申报 3 条之外零删改、第 13 节无效成员零残留、S13 键只降不升对账。未过不合并。
|
||||
|
||||
## 9. 异常分级
|
||||
|
||||
- **L1 自救**:测试断言笔误、束键名拼写、注释错字、改址遗漏一处编译级报错的就地修复——就地改,记录进实现报告。
|
||||
- **L2 记录继续**:行号 ±5 行内的漂移(以 grep 符号锚定位后继续);测试失败经排查属既有缺陷且与本批改动无因果——登记跳过并报用户。
|
||||
- **L3 停机写报告等用户**:①卡面与处置记录冲突、或处置记录未落盘/与本卡第 3 节不一致(上游缺陷,退写卡段);②golden 改后读数与改前基线出现任何非预期漂移(零行为变更契约被破=上游缺陷停卡,禁就地调和);③束形态与 S13 预算互斥——任一触件成员数超第 14 节预算(RoundCycle 15/BattleFxHost 15/BreakpointStore 15/orchestrator 15 四贴顶件禁再增成员)=上游缺陷停卡退写卡段,禁实现段自行拆件或砍面;④实现中发现第 4 节未登记的第五处编排器私取消费面或搬家方法第 4 个调用方(行为语义不明,禁代裁);⑤机检键与卡片契约互斥(含 schema 校验/静态闸判据冲突)=一律停卡呈报,不得自造第三条路。
|
||||
|
||||
## 10. 代拍板白名单
|
||||
|
||||
- 测试内部夹具命名与组织(束组装辅助函数名、golden 序列化键序、sweep 正则的具体写法——判据面不变)。
|
||||
- 注释与断言消息中文措辞微调(尾缀〔封装5.1 Vn〕与判别词保留)。
|
||||
- 段类/编排器头注的改写措辞(模块介绍职责不变)。
|
||||
- 束 assert 缺键报错文案(「引用束缺键」判别词保留)。
|
||||
- 逐卡内「孤立验证→出红最小单元→并入全套」的执行顺序细节。
|
||||
- T1 golden 转储通道的实现方式(打印格式/临时旗标,用后即删)。
|
||||
超清单的决断记入实现报告「实现决定记录」节。
|
||||
|
||||
## 11. 待裁点
|
||||
|
||||
**零待裁点,开工门=U0**——五处修复方案、段类终态(六子对象+七回调+段间引用+公开读数注入+对编排器零引用)、搬家五方法宿主、出卡边界、排序义务均已在 2026-11-03 设计讨论会话由用户裁决;束键分配、回调精确签名、T 卡分解、验收断言由本卡写卡期实查定死(第 3/4/7 节)。本卡未新增任何备选案。
|
||||
|
||||
## 12. 落位与可复用性预检
|
||||
|
||||
**新增文件(2 件,全部测试件)**:
|
||||
- tests/unit/battle_settlement/settlement_wiring_snapshot_test.gd——为什么不能复用:同种子逐项 golden 对拍需冻结改前全行流为常量基线,既有套件(round_flow_skill_pool 等)断言的是段内序与行为面、无整流 golden;battle_settlement 目录落点(夹具对象=战斗结算全链);grep 同名零命中。驱动夹具复用既有件:ConfigDBScript 显式构造+AutoPlayer.choose_dig(roll_multiplier_test.gd:14-16 同款装配先例,引用不复制)。
|
||||
- tests/unit/core/encapsulation_sweep_test.gd——为什么不能复用:五处结构性零命中是本批特有扫描面(七文件集+五方法残留+四处私取模式),player_copy_sweep_test 扫的是 presentation 文案面——**复用其源 token 扫描手法但不并件**(并件会让两批扫描面与尾缀语义混乱)。唯一落点 tests/unit/core;grep 同名零命中。
|
||||
|
||||
**新增函数/成员(逐条唯一性核查,grep 同名全库实核)**:
|
||||
- `DamageController.hero_atk`/`hits_of`/`emit_hero_damage_taken`——编排器 `_hero_atk`/`_hits_of` 改名迁移非并存(禁别名);`_emit_hero_damage_taken` 去下划线公开化非新增体;`facts` 成员为该件第 13 个类变量(预算内)。grep `func hero_atk`/`func hits_of` 全库零第二处。
|
||||
- `RewardGrant.feat_yield_adjust`——`_feat_yield_adjust` 改名迁移;RewardGrant 持 reward_economy 引用(:22 既有)故体零改动可行。grep 唯一。
|
||||
- `MinesweeperRules.harmful_variants`/`harmful_adjacent`——改名迁移;db 为构造参(:44 既有)。grep 唯一。
|
||||
- `BattleFxHost.mark_new_resource_type`/`add_bonus_delta`——新方法旧账面(成员零增);grep 同名零命中,命名与既有 apply_ac_bonus/counter_add 动词族同型。
|
||||
- `SlotStore.active_path`——grep 全库零同名;has_write_target 同族读投影。
|
||||
- SaveManagerCore 五公开面(承接 slot_store 反向私取)——`set_read_only`/`read_only`/`reset_to_default`/`data_snapshot`/`restore_data` grep 作方法名全库零第二处(现仅为成员名或私有方法);`peek_summary_at`/`rename_overwrite` 为私有方法更名公开化非并存(禁别名,第 13 节适用);`reset_to_default` 件内既有调用点同名零改。
|
||||
- `BreakpointStore` 13 方法——grep `pending_next_level|loadout_seeded|resume_bp|last_level_payload|last_treasure_cleared|bp_read|bind_save_manager` 作为**方法名**全库零命中(现仅为成员名);成员到方法一一对应,无第二落点。
|
||||
- 三 schema `bind_resolver`——grep 零同名;参数类型 ConfigDbResolver 与 config_db.gd:43 既有协作类同一实例。
|
||||
- `RoundCycle.refresh_flow`——grep 零同名;读出口与 stats()/wallet() 组件出口先例同型(adventure_runner.gd:60-82)。
|
||||
|
||||
**复用既有(不新增)**:束注入形态=BoardInstaller/BattleFxHost/RewardGrant/BreakpointStore 四先例;读投影 Callable=attune_safe_seen_cb/pool_effective_cb/facts_cb 三先例;源扫描测试=player_copy_sweep_test 手法;manifest 登记=run_all.gd 既有条目族。零新增生产文件(全部落在既有件——架构七段结构零改动的直接后果)。
|
||||
|
||||
**分层与交互面**:段类→六子对象/协作件=既有 B1 域内调用关系(architecture.md:119 B2/B3/B4 全调用面唯一调用方=B1 域文件集——S7_B1_SET 已含七段,零新增跨域路径);段类→编排器=单向 Callable(禁双向强引用);三 schema bind_resolver=既有 config_db→schema 装配方向(:131-159 同向,禁反向);RngService 红线零触碰(本批零新增随机源);Core 零 UI 红线零触碰(全套件 --headless 可跑);数值单一事实源零触碰(零表改动)。
|
||||
|
||||
## 13. 禁为机检文本保留无效成员
|
||||
|
||||
本卡为重构类卡,全卡适用以下条款(code-conventions §1.1 ⑤同款):禁止为迎合机检消息文本(含计数、sweep 正则、grep 面)而保留或新增无效成员/别名/转发壳;搬家五方法宿主原方法删除后禁留同名或别名转发壳;`_migrate_legacy_save` 更名后禁留旧名壳;`_bp_read` 更名后禁留旧名壳;`_emit_hero_damage_taken` 公开化后禁留私有旧名;BreakpointStore 新方法面禁在成员外另立镜像账本。机检键与卡片契约互斥时(如 S13 贴顶件、sweep 正则与签名冲突),实现段一律停卡呈报,不得自造第三条路。
|
||||
|
||||
## 14. 实现规范预算
|
||||
|
||||
新增 .gd 文件仅 2 个测试件(SceneTree 测试脚本,全类型标注、零公开生产面——接口块预算余量充足)。生产代码全部落既有件,按「存量触面一查」逐件对账(S13 默认阈值:公开方法 ≤20/类变量 ≤15/分支 ≤8/返回 ≤6):
|
||||
|
||||
- **贴顶四件(禁再增成员,T1 读数锁定)**:battle_orchestrator.gd 15(本批成员零净增——五方法删除不涉成员);round_cycle.gd 8→15(束解包 7+_refresh_flow 1+既有 7——贴顶,头注记「贴顶禁再增」);battle_fx_host.gd 15(零增,方法-only);breakpoint_store.gd 15(零增,方法-only)。
|
||||
- **类变量净增件**:grant_segment 3→12、combat_segment 3→10、verdict 1→5、aura 1→1、decay 1→2(两件现各持 oc 一员——aura 换单回调成员 1→1、decay 换两成员 1→2)、battle_refresh_flow 0→8、damage_controller 12→13——全部 ≤15。
|
||||
- **公开方法净增件**:minesweeper_rules 18→**20 贴顶**(+2)、damage_controller 9→12(+hero_atk/hits_of+emit_hero_damage_taken 公开化——2026-11-03 终审实核现值 9)、reward_grant 9→10、battle_fx_host 16→18、slot_store 10→11、breakpoint_store 5→18、save_manager 7→14(+5 承接方法+peek_summary_at/rename_overwrite 两更名公开化)、RoundCycle 3→4、三 schema 各 +1——全部 ≤20。
|
||||
- **迁移函数对账**:搬家五方法+`_migrate_legacy_save`+`_bp_read`+`_emit_hero_damage_taken`+`_peek_summary_at`+`_rename_overwrite` 逐个查 `tools/gdstyle_baseline.txt` 源键——基线无此 10 键(默认阈值内),迁移即原体;若 T1 读数发现任一源函数 branches/returns 超默认登记值,迁移即拆函数(拆分不改语义,不算迎合机检——与第 13 节区分)。
|
||||
- **存量触面 S13 预期**:本卡触件 15 件(第 3.2 节清单)S13 键较 T1 现场基线**只降不升**(净删为主:五方法约 45 行迁出、107 处 oc._ 改址不增行数;净增面=两累积方法+13 bp 方法面+束解包成员行);adventure_runner 既有登记键(类变量 23)照登对账零变化。降不达即检查是否夹带超预算成员,L3 ③兜底。
|
||||
- **指标例外申报**:无(零新件、零超默认阈值新增面;若实现中发现例外,走本卡异常分级 L3 ③停卡,禁就地豁免)。
|
||||
|
||||
## 15. 拆分边界纪律
|
||||
|
||||
见第 4 节红线(结构类卡必填条款,判据权威=code-conventions §1.1):本卡零新拆件——段类七件、RoundCycle、BattleRefreshFlow、DamageController、RewardGrant、MinesweeperRules、BattleFxHost、BreakpointStore、SlotStore 全部架构在册既有件,本批只做接线形态换代与五方法归位。逐件职责语句不变:五段段类=B1 每轮结算序列的分段逻辑件(architecture.md:127)、RoundCycle=轮结算周期推进结构单点(:125)、BattleRefreshFlow=换图刷新流程唯一承载(:123)、五方法归位=各领域宿主既有职责面内的原语归位(伤害基值派生读归伤害管线、奖励乘区调整归授予管线、地形伤害型变异过滤归棋盘状态域、效果命中过滤归伤害域)。单一变化原因=封装边界(跨对象私取清零),非阈值驱动。禁凑计数袋:段类成员束解包以消费面为准(第 4 节分配表逐段列明),无「剩下的成员」式打包。先例=迭代 41 两卡 v1.2(核心数据面契约 7/呈现层契约 9)。
|
||||
@@ -0,0 +1,151 @@
|
||||
# 需求卡片:架构审查 P2 代码面批(2026-11-03)
|
||||
|
||||
来源:待办清单「架构审查优化讨论——全库架构审计读数的逐条裁决与整改分批(2026-10-29 登记,来源=审计发现)」条目 P2 部分(**唯一事实源**:reports/审计-全库架构审查-2026-10-29.md §5.3 NODE_TYPES 项+2026-11-03 设计讨论会话用户授权〔实现层事项按代码规则与架构文档决策〕;热重载侧经用户裁决撤卡——规格保留原状、死开关代码保留为将来实装骨架,实装去向=用户另立待办条目+后续实装卡〔他会话写卡〕)。
|
||||
状态:已写卡(v1.1,2026-11-03 修订——原 R1〔EC8 热重载代码链退役〕经用户裁决撤下,本卡收敛为仅 NODE_TYPES 词表单点化)。改动面:游戏代码(含随逻辑写/改的测试代码)。
|
||||
|
||||
## 1. 目标与完成定义
|
||||
|
||||
**这批做什么**:一处零行为变更的词表单点化——审计 §5.3 的 P2 代码遗留:
|
||||
|
||||
| # | 对象 | 现状 | 终态 |
|
||||
|---|---|---|---|
|
||||
| R1 | NODE_TYPES 词表双份 | `node_map_generator.gd:10` 与 `level_table.gd:11` 各持一份(内容同、序不同);生成器 :136 校验自产节点、schema :78 校验表行——校验双活、词表双写 | 词表单点归 schema(`LevelTable.NODE_TYPES`),生成器删本地副本改 class_name 直引;两处校验语义零变化(`.has()` 只判成员、序无关) |
|
||||
|
||||
**不收件(热重载侧,2026-11-03 用户裁决)**:`config_db.gd` 门标志与两方法、`battle_orchestrator.gd` 两行开门点**原样保留**——热重载规格已在设计文档保留原状(arch51-docs 提交 e614773a 撤回本批一度摘除),代码为将来实装骨架;实装需求卡片由用户另立待办条目后于他会话编写,本卡零触碰。
|
||||
|
||||
**什么状态算完**:词表改指落码、第 8 节对照表配对的验收断言在当轮真实跑批中通过;零行为变更证明=既有套件零转红(node_map_determinism/关卡表校验链/冒烟)+结构性 sweep 恒零(第 8 节 V1/V2);代码域闸全绿;两份 reports/ 产出物(实现报告+反哺点清单)写齐。
|
||||
|
||||
**排序义务**:本卡实现排队在 reports/需求卡片-架构审查5.1封装修复批-2026-11-03.md 之后——battle_orchestrator.gd 虽不再被本卡触碰,排序惯例照旧(同批架构审查卡顺次实现)。
|
||||
|
||||
## 2. 设计事实源
|
||||
|
||||
- **审计读数**:`reports/审计-全库架构审查-2026-10-29.md` §5.3(NODE_TYPES 词表双份)。
|
||||
- **裁决凭据**:2026-11-03 设计讨论会话用户授权(实现层事项按代码规则与架构文档决策)+热重载侧撤卡裁决(规格保留、代码保留、实装另卡)。
|
||||
- **架构登记**:`design/engineering/architecture/architecture.md`——:119 行「NODE_TYPES 词表双份」表述随本卡单点化由反哺点订正。
|
||||
|
||||
## 3. 现状事实(2026-11-03 master 工作区实查,基点 ab5d75a2;开工自行复核)
|
||||
|
||||
- **热重载侧(不收件,保留原状)**:config_db.gd:45(`_reload_gate`)+:174-186(`set_reload_gate`/`reload`)+battle_orchestrator.gd:272/:633(两行开门点)——零触碰;实装排期归用户另立待办条目+后续实装卡。
|
||||
- **NODE_TYPES 双份**:`core/node_map_generator.gd:10`(`["battle", "boss", "reward", "rest", "shop"]`)与 `data/schemas/level_table.gd:11`(`["battle", "reward", "rest", "boss", "shop"]`+注释「关卡节点地图 v2.1」);消费点=node_map_generator.gd:136(`NODE_TYPES.has(String(n["type"]))`——生成器自产节点枚举校验)与 level_table.gd:78(表行加载校验)。全库第三处引用零命中(grep 实核——tests/sim/probe 全零)。两处消费均为 `.has()` 成员判定,词表序不参与行为(内容集相同)。
|
||||
- **闸面现状**:S3(core 禁表加载)对 schema class_name 直引是豁免面(warning 级人工复核口径,static_scan.sh S3 注释「schema class_name 直引豁免」)——生成器改引 `LevelTable.NODE_TYPES` 落在既有豁免形态内(同款先例=config_db 持 BoardGenTable 等四域容器);零闸件改动。
|
||||
- **S13 预算**:node_map_generator 公开面与类变量零变化(删常量不涉成员账)。gdstyle 基线(tools/gdstyle_baseline.txt)对本卡触件零登记键。
|
||||
|
||||
## 4. 设计契约(违反即返工红线)
|
||||
|
||||
- 🔴 **零行为变更**:词表 `.has()` 判定集相同——零变更证明=既有套件零转红+同种子确定链零漂移(node_map_determinism 全绿)。RNG 封闭流、明细行协议、诊断状态机、存档与断点链零触碰。
|
||||
- 🔴 **R1 单点方向**:词表唯一落点=`data/schemas/level_table.gd`(表行校验 owner);生成器删本地 `const NODE_TYPES`,:136 改 `LevelTable.NODE_TYPES.has(String(n["type"]))`——core→data/schemas 前向边,schema class_name 直引(S3 豁免面在案形态);禁反向(schema 引 core);禁把词表搬进第三处(词表唯一落点不可迁)。
|
||||
- 🔴 **fail-fast 不破**:改动不引入任何软回退;配置加载校验路径零改动。
|
||||
- 🔴 **测试纪律**:禁变异类测试、禁撤销类取证;禁删断言/放宽阈值(第 8 节申报清单之外零删改)。
|
||||
|
||||
## 5. 范围边界
|
||||
|
||||
**收件**=R1 词表单点化+一件新 sweep 测试+既有套件回归确认。
|
||||
|
||||
**不收件**(去向已指认):
|
||||
- 热重载全侧(config_db 门与 reload、编排器两行开门点、GDD 规格)——原样保留,实装去向=用户另立待办条目+后续实装卡;本卡零触碰。
|
||||
- architecture.md :119 行「NODE_TYPES 词表双份」表述——反哺点清单承载(实现批禁写 design/,第 6 节)。
|
||||
- 闸面缺口(S1/S2/S9/S13 扫描面扩 sim/probe/tests、S8 目录域)与 S13 三处豁免存废——审计 P1 项,**不在本卡**(待办清单条目未闭合余项,后续讨论段)。
|
||||
|
||||
## 6. 关联文档同步面
|
||||
|
||||
实现批禁写 `design/` 整个目录与根规则文件;下表每条的落文义务全部进 `reports/iter<N>-反哺点-<日期>.md`(N=编排段定),由用户裁决后归文档批落文:
|
||||
|
||||
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务(反哺点清单逐条承载) |
|
||||
|---|---|---|
|
||||
| design/engineering/architecture/architecture.md | :119 行「各持一份 NODE_TYPES 词表(内容同、顺序不同)」表述随单点化删句、改「词表单点归 LevelTable」 | 反哺点清单逐条列行号与改后登记内容——**机械面文档禁直改** |
|
||||
| design/gdd/systems/表现与支撑/数据配置.md | 无陈述变化(热重载规格保留原状——零反哺确认行) | 反哺点清单写「零反哺」确认行 |
|
||||
| 术语表 | 无新术语 | 确认行「零新增术语」 |
|
||||
|
||||
(机检口径:本表同步义务格无一条写「随批」。)
|
||||
|
||||
## 7. 任务卡 T1..T2
|
||||
|
||||
### 卡前·文件结构图
|
||||
|
||||
全部行为面=非行为改动(零行为变更批),行标【非行为】+对照表 R 行号;测试件为随逻辑写/改的测试代码。
|
||||
|
||||
```
|
||||
core 层
|
||||
game/core/node_map_generator.gd 【非行为 R1】:10 本地词表删+:136 改 LevelTable.NODE_TYPES.has(...)
|
||||
测试件(随逻辑写/改)
|
||||
tests/unit/core/encapsulation_p2_sweep_test.gd 【非行为 R1·新增】结构性零命中扫描(非空前置+正锚)
|
||||
tests/run_all.gd 【非行为】manifest +1 行(sweep)
|
||||
文档件
|
||||
game/tests/README.md 写卡段判断=零编辑(第 8 节能力行判断依据)——实现批禁写,批末只核对能力名引用一致
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**T1 NODE_TYPES 单点化+批收口**(估时 0.25 工作日;区间 0.25–0.5)
|
||||
取用:无(本卡起点)。产出:R1 清零+sweep 绿+批收口两件。
|
||||
|
||||
- [ ] 核对实现排序在案:5.1 卡(含 battle_orchestrator 触面)未合回则本批不开工
|
||||
- [ ] node_map_generator.gd::10 本地 `const NODE_TYPES` 删;:136 改 `if not LevelTable.NODE_TYPES.has(String(n["type"])):`——头注如有词表自述随改
|
||||
- [ ] 新增 tests/unit/core/encapsulation_p2_sweep_test.gd(extends SceneTree+Kit.check 主通道,全类型标注;源 token 扫描手法沿 encapsulation_sweep_test.gd〔5.1 卡新增件〕先例)断言组:①node_map_generator.gd 非空+`^const NODE_TYPES` 零命中+`LevelTable.NODE_TYPES.has(` 正锚〔架构P2 V1〕;②全仓 .gd 生产面(core/data/presentation)`NODE_TYPES :=` 定义恰好 1 处且落 data/schemas/level_table.gd〔架构P2 V2〕——两组均带扫描面非空前置
|
||||
- [ ] 孤立验证:新 sweep 单件先跑绿;node_map_determinism_test 全套绿(生成链同种子逐位——R1 零行为变更主证)+关卡表加载路径(level_table 校验活检查)经既有套件覆盖零转红+冒烟零转红
|
||||
- [ ] run_all.gd manifest 追加 1 行:encapsulation_p2_sweep_test(expect 0,注记「R1 结构性零命中扫描〔架构P2〕」)
|
||||
- [ ] **实现报告** `reports/iter<N>-实现报告-<日期>.md`:各卡状态+S13 键改前改后对账(node_map_generator 现场读数)+实现决定记录
|
||||
- [ ] **反哺点清单** `reports/iter<N>-反哺点-<日期>.md`:第 6 节同步面逐条落点(architecture.md :119 一处、GDD/术语确认行)
|
||||
- [ ] 批末核对:README 能力名引用一致(本卡零编辑);独立验收审计(第 8 节末)未过不合并;.uid 收口=`--editor --quit` 一次后确认新测试件 .uid 随批提交
|
||||
|
||||
### 估时汇总
|
||||
|
||||
T1 0.25。区间合计 0.25–0.5 工作日;**精确汇总 0.25 工作日**(超 0.5 工作日=超卡面估时域,须用户确认后方可续批)。
|
||||
|
||||
## 8. 验证闸(改动—验收对照表)
|
||||
|
||||
测试方式两分法:下表全部走**调试接口验证**;**正常流程体验验证**=零项(零行为变更批)。判据绑被测改动特有的可观测提交面(源码零命中带非空前置与正锚/确定链同种子逐位)。
|
||||
|
||||
| 需求点 | 改动(文件:行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| R1 NODE_TYPES 单点化 | node_map_generator :10 删+:136 改指 | encapsulation_p2_sweep_test〔架构P2 V1/V2〕;node_map_determinism_test 既有全套(同种子同参数必产同图逐位) | 单元+集成 | `LevelRunner` 关卡推进→节点图生成真实入口;`LevelTable` 表行加载校验 | 词表定义唯一落点(正锚计数=1);生成链同种子逐位同 | 既有:节点图生成合法性与同种子复现;既有:起关/选路/断点重生成同图(集成) |
|
||||
|
||||
**零行为改动面的证据义务**:本卡一行均为非行为改动——零变更证明=既有套件零转红+sweep 恒零+确定性链逐位。能力行全部「既有」、零新增——判断依据:零行为变更=玩家可观测能力面零变化;能力清单零编辑(批末核对义务在 T1)。
|
||||
|
||||
**闸口径**:重闸=`tools/run_all_gates.sh` 按本批改动域选档(改动含 game/ 下非 .md 行为载体 → `--code`);所选域全绿才合并。卡内不写死闸件名单。回归措辞:里程碑卡出口跑一次全套闸;卡内修复只做出红最小单元的最窄确认;新增测试先行孤立验证再并入全套。
|
||||
|
||||
**测试削弱申报**:零条——本批零删改既有断言(grep 实核:tests 对 NODE_TYPES 零引用,无断言需要迁移)。
|
||||
|
||||
**独立验收审计**:入口=批末 T1 后、合并前;报告=`reports/iter<N>-验收审计-<日期>.md`;由没参与实现的会话或子代理执行,核对:对照表逐行断言真实存在且当轮通过、sweep 非空前置在案、零删改核对、S13 键只降不升对账。未过不合并。
|
||||
|
||||
## 9. 异常分级
|
||||
|
||||
- **L1 自救**:改指行错位、sweep 正则笔误、注释错字——就地改,记录进实现报告。
|
||||
- **L2 记录继续**:行号 ±5 行内漂移(grep 符号锚定位后继续)。
|
||||
- **L3 停机写报告等用户**:①实现中发现 `NODE_TYPES` 出现卡面未登记的第三处消费面(现状事实失实=上游缺陷,禁代裁);②改指后任一既有套件转红(零行为变更契约被破=停卡,禁就地调和);③机检键与卡片契约互斥=停卡呈报,禁自造第三条路。
|
||||
|
||||
## 10. 代拍板白名单
|
||||
|
||||
- sweep 正则具体写法与断言消息措辞(尾缀〔架构P2 Vn〕与判别词保留)。
|
||||
- 逐卡内「孤立验证→出红最小单元→并入全套」执行顺序细节。
|
||||
超清单的决断记入实现报告「实现决定记录」节。
|
||||
|
||||
## 11. 待裁点
|
||||
|
||||
**零待裁点,开工门=U0**——词表单点化方向由审计读数+2026-11-03 会话授权导出;热重载侧经用户裁决撤卡(规格保留、代码保留为实装骨架、实装另卡)。单点落点、T 卡分解、验收断言由写卡期实查定死(第 3/7 节)。本卡未新增备选案。
|
||||
|
||||
## 12. 落位与可复用性预检
|
||||
|
||||
**新增文件(1 件,测试件)**:
|
||||
- tests/unit/core/encapsulation_p2_sweep_test.gd——为什么不能复用 5.1 卡的 encapsulation_sweep_test.gd:两卡独立 worktree 独立实现批(合回顺序未定,并件会让扫描面归属与尾缀语义跨批纠缠);本卡 sweep 仅两组四处、体量小;扫描手法同源(源 token 扫描先例),合回后如需并件归后续纯测试维护批裁决。grep 同名零命中。
|
||||
|
||||
**新增函数/成员**:零(纯删除+一处改指——无任何新增生产函数/成员/数据件)。
|
||||
|
||||
**复用既有**:源 token 扫描手法=encapsulation_sweep_test/player_copy_sweep_test 先例;manifest 登记=run_all.gd 既有条目族;schema class_name 直引形态=config_db 域容器四先例。
|
||||
|
||||
**分层与交互面**:R1 前向边 core→data/schemas=S3 豁免面在案形态(同 config_db 持表容器方向);零新增跨域路径、零新依赖;RngService 红线零触碰;Core 零 UI 红线零触碰;数值单一事实源零触碰(零表改动)。
|
||||
|
||||
## 13. 禁为机检文本保留无效成员
|
||||
|
||||
本卡为收敛类卡:词表删除后生成器禁留本地副本或镜像常量。机检键与卡片契约互斥时实现段一律停卡呈报,不得自造第三条路。
|
||||
|
||||
## 14. 实现规范预算
|
||||
|
||||
新增 .gd 仅 1 个测试件(SceneTree 脚本,全类型标注、零公开生产面)。生产代码全部落既有件,按「存量触面一查」对账(S13 默认阈值):
|
||||
- **零成员变化件**:node_map_generator 公开面与类变量零变化(常量删+一处改指)。
|
||||
- **存量触面 S13 预期**:触件一件 S13 键较现场基线只降不升;gdstyle 基线零登记键,T1 现场读数即对账基线。
|
||||
- **指标例外申报**:无。
|
||||
|
||||
## 15. 拆分边界纪律
|
||||
|
||||
本卡零新拆件——触件全部架构在册既有件,只做词表单点化;逐件职责语句不变(node_map_generator=关卡节点图生成域唯一承载〔词表消费方身份不变、定义权归 schema owner〕)。单一变化原因=单一事实源(词表归一),非阈值驱动。禁凑计数袋:本卡无成员打包面。
|
||||
Reference in new issue
Block a user