15 KiB
需求卡片：架构审查 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〕）。单一变化原因＝单一事实源（词表归一），非阈值驱动。禁凑计数袋：本卡无成员打包面。