docs(迭代34卡④): 实现报告补第五节（对照表 fv1–fv9／六条偏差／变异 M1–M10／闸读数 1211 项与 40 套件）＋代拍板六条备案＋反哺点 ⑥–⑭

2026-10-22 06:11:54 +08:00
1 parent 6f04f29bf0
commit 477fd0f57f
@@ -16,3 +16,17 @@
 ## 白名单外未代拍事项

 无。实现期未遇到需要超出 §10 清单自决的设计分歧。
+
+## 卡④ 信息迷雾可见性批
+
+> 白名单依据＝`reports/需求卡片-信息迷雾可见性批-2026-10-21.md` §9（六条）。
+
+| # | 白名单条目 | 实际做法 | 约束核验 |
+|---|---|---|---|
+| 1 | provisional N＝2（§9-1） | `level.tres` 挂 `info_visible_layers = 2`；`validate` 只校验 int ≥ 1 | 定值仍在数据表，代码零硬编码；N=1/3 改表实测可见窗随动 |
+| 2 | API/探针命名（§9-2） | `info_visible_layers`／`type_visible_ids`／`node_display`／`display_probe` | 均无 `fog_` 前缀，与战斗「视野迷雾」零撞词 |
+| 3 | 雾下节点呈现落点（§9-3） | 图标/类型文字改读 `node_display` 输出；节点方块、编号、连线结构通道零改动 | 编号保留、类型文字不绘制；结构通道冒烟与渲染闸全绿 |
+| 4 | 大图夹具规模（§9-4） | 12 个 BFS 层构造（跨层跳边压层后布局实得 11 层×6 槽）、含双 Boss、跨层跳边 | 满足 ≥10 层 × ≥5 槽；断言按布局实测 `maxl/maxslot` 推导 |
+| 5 | 常数锚同源化方式（§9-5） | 探针直接引 `LevelMapScreen.LAYER_BASE_X/LAYER_STEP_X/NODE_HALF` 导出常量 | 与 `_fit_canvas` 公式逐项同源，无手抄数字副本 |
+| 6 | 提交切分与分支命名（§9-6） | 分支 `iter34-fog`；三笔：实现与断言（`ed8e0f9f`）、⑱ 判据改绑（`4ef154b9`）、类型闸归零＋探针补尾缀（`6f04f29b`） | 三笔均在 `game/` 内；报告随批落 `reports/` |
+
@@ -35,3 +35,59 @@
 - 文件与位置：`roadmap.md` 迭代 34 行（两卡并列，本卡为卡③）与顶部「当前位」节
 - 改成：卡③状态记为已实现；卡④（信息迷雾可见性）仍在同一迭代内推进；「当前位」按实际进度改写。
 - 依据：迭代实现批的收尾义务（`iter` 技能第 5 步账面随批）；实现批不写该文件，换代归批后收尾或用户发令。
+
+## ⑥ 关卡节点地图.md：调参表 N 状态行与可见性语义注记
+
+- 文件与位置：`design/gdd/systems/冒险循环/关卡节点地图.md` :172（调参表「信息迷雾可见层数」行）、:100（可见范围「邻近 N 层」节）
+- 改成：调参表状态由「定值批落数据表」改为「已落数据表 provisional 2（`level.tres` `info_visible_layers`）」；:100 节补实现语义三句——层距＝入口 BFS 层差、Boss/终点与当前候选双豁免、单圈零记忆（已过节点回雾）。
+- 依据：卡④ T1 已实现并在 `level_runner.type_visible_ids()` 钉死；`level_map_type_vis_test` 五组断言〔fv1〕〔fv3〕〔fv4〕〔fv7〕覆盖。
+
+## ⑦ 关卡节点图生成.md：屏预算约束行与「下一跳必在可见范围」兑现标注
+
+- 文件与位置：`design/gdd/systems/冒险循环/关卡节点图生成.md` :105–114（调参表）、:83（「下一跳必在可见范围」）
+- 改成：调参表补一行「图包络 ≤ 屏预算（1280×800 下约 10 层×8 槽；超预算只许限参数档，禁改画布冻结公式）」；:83 该句标注「实现侧已兑现：候选集强制豁免类型可见性」。
+- 依据：卡④契约 6 与 G6 定值（参数限图）；`type_visible_ids()` 候选豁免断言〔fv4〕。
+
+## ⑧ level-map.md：画布公式漂移订正＋类型可见性层级行
+
+- 文件与位置：`design/gdd/ux/level-map.md` :68（节点图区「冻结公式」句）
+- 改成：宽 70+层深×122+34 → 70+层深×122+44.5（`NODE_HALF.x`36.5+8）；高 52+槽位×58+26+8 → 52+槽位×58+25+24（`NODE_HALF.y`25+标签行 24）；下限 620×240 → 620×256（抬高容纳标签行）。Information Hierarchy 节补「类型可见性（邻近 N 层显隐）」层级行。
+- 依据：`level_map_screen.gd:289–304` 现行 `_fit_canvas` 公式与大图拟合断言〔fv8〕；下限定值 256 是当前代码与渲染闸全绿的实际约束。**注意**：本条只订正文档记数，不动冻结件本身（画布公式语义与像素档位不变），是否接受改写由用户裁。
+- **呈报项（禁本批落文）**：「雾的正式视觉规格」（雾纹理/灰化遮罩/明度层）属冻结件域，本卡只做显隐语义最小呈现，视觉规格待用户裁后另立。
+
+## ⑨ 术语表.md：登记「信息迷雾」并区别于「视野迷雾」
+
+- 文件与位置：`design/gdd/术语表.md`
+- 改成：新增词条「信息迷雾」＝关卡节点图上按邻近层数隐藏节点类型的信息可见性；与「视野迷雾」（战斗棋盘按英雄曼哈顿半径遮挡）并列，注明两系统同词根易混、代码标识符禁 `fog_` 前缀。
+- 依据：卡④契约与风险 3；实现侧 API 全用 `info_visible_layers`／`type_visible_ids`／`node_display`／`display_probe`。
+
+## ⑩ 关卡节点地图.md：Boss 描边口径冲突择一
+
+- 文件与位置：`design/gdd/systems/冒险循环/关卡节点地图.md` :67
+- 改成：Boss 描边口径「封印黑 #000000」与 `level-map.md`／现役代码「紫赤＋深墨环」不一致，请文档批核对后择一（现役实现与视觉终稿样张 v1 为紫赤＋深墨环）。
+- 依据：卡④ G8 定值（实现随现役代码＋level-map.md）；本批未动描边视觉。
+
+## ⑪ 待办清单.md：卡④条目状态回写
+
+- 文件与位置：`待办清单.md` 中卡④登记条目
+- 改成：状态推进为「已实现（迭代 34）」并写明本批实现报告路径；按中间文档退役规则登记本卡与迭代产出物的退役去向。
+- 依据：五段流水线状态机（`doc-conventions` §12）；实现批不写该文件，回写归批后收尾或用户发令。
+
+## ⑫ roadmap.md：迭代 34 行两卡均完成＋「当前位」换代
+
+- 文件与位置：`roadmap.md` 迭代 34 行与顶部「当前位」节
+- 改成：卡④状态记为已实现；「当前位」按迭代 34 收口后的实际进度改写。
+- 依据：迭代实现批收尾义务；实现批不写该文件，换代归批后收尾或用户发令。
+
+## ⑬ 呈报项：超预算图策略升级路径
+
+- 位置：无文档落点（用户在会话中裁）
+- 内容：若后续定值批需要大于「约 10 层×8 槽」的完整可见图，两条路都动冻结件——等比缩放（动「20px 烘焙 1:1」「2/3/4px 折线」）或滚动视口（新交互范式）。本卡按 G6 走参数限图，两案均需用户裁。
+- 依据：卡④风险 2 与 G6 淘汰案。
+
+## ⑭ test-conventions.md：验收断言应绑可观测提交面（方法论反哺）
+
+- 文件与位置：`design/engineering/test-conventions.md` §9.4（撤销/变异证明）
+- 改成：补一句判据——端到端断言的判据应绑「被测改动特有的可观测提交面」（信号发射、事件、入参），不绑多层防御下的终态；否则单点变异可能被下游兜底吸收、终态不变而假绿。示例：探针「雾不扩可点域」首版只看屏/选路态终态，命中面放宽的变异仍绿；改绑 `route_chosen` 发射面后变异即红。
+- 依据：卡④ T4 实测（`提交=[3] visible=true 选路态=true`；终态与未点击一致）。
+
@@ -154,4 +154,94 @@

 ## 五、卡④ 信息迷雾可见性批

-另行施工，完成后在本文追加对应章节。
+### 5.1 工作树与任务卡状态
+
+工作树 `D:\code\g-plan2-iter34-fog`，分支 `iter34-fog`，起自卡③合并后的 master `43c0f3c1`。提交：`ed8e0f9f`（T1–T3 实现与单测/冒烟/探针）、`4ef154b9`（⑱ 零提交判据改绑信号面）、`6f04f29b`（类型闸归零＋探针补雾下文字通道断言）。
+
+| T 卡 | 内容 | 状态 |
+|---|---|---|
+| T0 | 事实坐实与基线读数 | 完成（改前基线：冒烟 1206 项 0 失败／单元套件全绿／探针全绿） |
+| T1 | N 落表＋越域校验＋`type_visible_ids()`＋核心套件 | 完成（提交 `ed8e0f9f`） |
+| T2 | `node_display` 决策面＋`display_probe`＋`_draw_graph` 接线＋呈现套件 | 完成（提交 `ed8e0f9f`，类型闸修补 `6f04f29b`） |
+| T3 | 探针常数锚同源化＋大图夹具（11 层×6 槽） | 完成（提交 `ed8e0f9f`） |
+| T4 | 冒烟断言＋探针⑱＋变异汇总＋代码域全量闸 | 完成（见 §5.4、§5.7） |
+| T5 | 三份产出物＋独立验收审计＋合并 | 进行中（本报告＋审计＋合并） |
+
+### 5.2 实际改动—验收对照表
+
+生产侧落点：`game/core/level_runner.gd`（`type_visible_ids()` :422–440、`_bfs_layers()` :443–462）；`game/presentation/views/level_map_screen.gd`（`node_display()` :420–437、`_draw_graph` 消费 :478、`display_probe()` :536–547）；`game/data/schemas/level_table.gd:8`（字段）、:23–24（越域校验）；`game/data/tables/level.tres:7`（`info_visible_layers = 2`）；`game/smoke/ui_input_probe.gd:142–145`（常数锚同源化）、:44–90（case⑱）；`game/smoke/smoke_all.gd:4938–4943`（真图可见性断言组）。
+
+| fv | 需求点（简） | 验收断言（文件:行） | 层级 | 真实入口 | 撤销/变异结果 |
+|---|---|---|---|---|---|
+| fv1 | 邻近 N 层见类型 | `level_map_type_vis_test.gd:121`、:122、:123（层距边界）；:142、:143（入口锚层 0）；:166、:167、:168（单链退化）；`smoke_all.gd:4942`（真图） | 单元＋集成 | `LevelRunner.type_visible_ids()` 直调；冒烟真图读面 | M1 `<=N`→`<N` → 边界断言红（实测） |
+| fv2 | 范围外只见结构 | `level_map_info_fog_test.gd:51`、:54、:56（决策面显隐）；:96、:98、:100（label 三态）；`ui_input_probe.gd:60`（真机 `display_probe` 雾下图标/文字双通道） | 单元＋探针 | `node_display` 纯函数；真图 `display_probe()` | M2 `draw_icon` 强制 true → 红（实测） |
+| fv3 | Boss 不入雾＋多终点标记 | `level_map_type_vis_test.gd:144`、:145；`level_map_info_fog_test.gd:65`、:67、:70、:73；`ui_input_probe.gd:64`；`smoke_all.gd:4939` | 单元＋探针＋集成 | `type_visible_ids()`／`node_display`；真机 `display_probe()` | M3 删核心 Boss 豁免 → 红；M4 删决策面 Boss 豁免 → 红（实测） |
+| fv4 | 下一跳恒可见 | `level_map_type_vis_test.gd:132`、:133（跨层跳边）；`smoke_all.gd:4938`；`ui_input_probe.gd:67` | 单元＋集成＋探针 | 同上；真图候选读面 | M5 删候选豁免 → 红（实测） |
+| fv5 | 节点内详情不显示 | `level_map_info_fog_test.gd:87`、:88（携带 `enemy_id/reward_id` 夹具） | 单元 | `node_display` 纯函数 | M6 label 拼 `enemy_id` → 红（实测） |
+| fv6 | N 进数据表 | `level_map_type_vis_test.gd:96`（表读数 2）、:100、:102、:104（越域 validate）、:178、:180、:186（改表随动）；`smoke_all.gd:4940–4941` | 单元＋集成 | `LevelTable.validate()`／`db.level.info_visible_layers`；冒烟读表 | M7a 删越域校验 → 红；M7b N 硬编码 2 → 红（实测） |
+| fv7 | 单圈语义 | `level_map_type_vis_test.gd:155`、:156、:157（visited 不豁免）；:207（续玩重建同值） | 单元 | `type_visible_ids()`＋`start_level_external` resume 路径 | M8 visited 累积可见 → 红（实测） |
+| fv8 | 画布自适应 | `level_map_info_fog_test.gd:169`（夹具规模）、:175（宽）、:177（高）、:185（全节点在画布内）、:192、:195；`ui_input_probe.gd:142–145`（常数锚同源）＋⑬ | 单元＋探针 | `canvas_probe()`／`layout_probe()`；真机 push_input | M9 去 `NODE_HALF.x` 项 → 红（实测） |
+| fv9 | 显隐接线（雾不扩可点域） | `ui_input_probe.gd:89`（点击雾下非候选节点 `route_chosen` 零发射） | 探针 | 真机 `push_input`＋`display_probe()` | M10 命中面放宽到全节点 → ⑱ 红（实测，提交=[3]） |
+
+覆盖说明：`game/` 内新增断言按上表逐条挂〔fv#〕尾缀，fv1–fv9 全覆盖，无未证条目；`level_map_type_vis_test` 26 项、`level_map_info_fog_test` 19 项、冒烟新增 5 项（1206→1211）、探针⑱ 5 项断言。
+
+### 5.3 卡片与实际改动面的偏差（逐条说明）
+
+1. **大图夹具层数换算**：卡片写「11 层×6 槽」，夹具按 12 个 BFS 层构造——跨层跳边（层 1→层 3）会把目标节点压到 BFS 层 2、其后续链整体上移一层，布局实得 11 层（实测 `maxl=10`、`maxslot=6`）。断言按布局实测推导（`maxl >= 10`），规模不变、语义不变。
+2. **⑱ 零提交判据改绑信号面**：按卡片原写法（命中面放宽到全节点 → ⑱ 红）首轮实测仍绿——点击确实穿透并提交，但雾下非战斗节点让本屏保持激活、运行器候选校验又把非法编号拒掉，终态与未点击时相同。改绑 `route_chosen` 发射面后单点变异即红（`提交=[3]`）。属卡片 §8 L1「断言写法」自救范围；同时给⑱ 各断言补 fv2/fv3/fv4/fv9 尾缀。
+3. **类型闸新增红**：T4 首轮全量闸暴露新增 4 处 R1（`Dictionary` 未参数化 1 处、`Array` 未参数化 3 处），已参数化归零（`6f04f29b`）；修复后 09 转绿（相对基线为改善）。
+4. **常数锚行号**：卡片写 `ui_input_probe.gd:98-99`，工作树实落点 :142–145（T0 复核行号），同源化方式＝直接引 `LevelMapScreen` 导出常量，未新增副本。
+5. **画布下限漂移**：`_fit_canvas` 现行为 `max(Vector2(620, 256))`，`level-map.md:68` 冻结公式写「下限 620×240」——本卡不动冻结件，登记反哺点。
+6. **命中面零改动**：`_candidate_at`（:373–386）卡内要求零改动，实现保持候选集循环，fv9 的变异证明正落在此函数。
+
+### 5.4 变异验证记录表（注入 → 最窄闸见红 → 还原）
+
+| # | 注入内容 | 最窄闸 | 红断言（原文摘要） | 还原确认 |
+|---|---|---|---|---|
+| M1 | `type_visible_ids` 层距判定 `<= n` 改 `< n` | `level_map_type_vis_test` | 层距 N 内可见：锚层 1 取节点 4（层距 2）〔fv1〕；单链退化形态：入口锚层 0，下标 2 可见〔fv1〕（连带 fv6/fv7 各 1 条） | `git checkout` 还原，26 项全绿 |
+| M2 | `node_display` 的 `draw_icon` 强制 true | `level_map_info_fog_test` | 雾下节点：图标与类型文字均不绘制〔fv2〕；Boss 豁免不扩散〔fv3〕；大图远处节点入雾〔fv8〕 | 还原，19 项全绿 |
+| M3 | 删 `type_visible_ids` 的 Boss 豁免分支 | `level_map_type_vis_test` | Boss 恒显：层距 6 的末位 Boss 仍在可见集〔fv3〕；单链编号空间＝数组下标〔fv1〕 | 还原，26 项全绿 |
+| M4 | 删 `node_display` 的 Boss 豁免（`type_shown` 只看可见集） | `level_map_info_fog_test` | Boss 豁免独立于可见集：不在 type_vis 的 Boss 仍出示类型〔fv3〕 | 还原，19 项全绿 |
+| M5 | 删 `type_visible_ids` 候选豁免追加段 | `level_map_type_vis_test` | 候选恒显：跨层跳边候选（层距 N+1）仍在可见集〔fv4〕 | 还原，26 项全绿 |
+| M6 | `label_text` 拼接 `node.get("enemy_id")` | `level_map_info_fog_test` | 决策面不消费内容键〔fv5〕；label_text 不含内容值（实际「战斗goblin_secret · 可选」）〔fv5〕 | 还原，19 项全绿 |
+| M7a | 删 `LevelTable.validate` 越域判据（`if false`） | `level_map_type_vis_test` | N 越域 0／-1：validate 判 domain 错〔fv6〕 | 还原，26 项全绿 |
+| M7b | `type_visible_ids` 的 N 硬编码 2（不读表） | `level_map_type_vis_test` | N 读表：N=1 时节点 4 出窗〔fv6〕；N=3 时节点 5 入窗〔fv6〕；N≥层高全可见〔fv6〕 | 还原，26 项全绿 |
+| M8 | 可见集加 `visited_ids().has(nid)`（累积可见） | `level_map_type_vis_test` | 单圈回雾：已过远端节点 0（层距 5）不因 visited 豁免〔fv7〕；中距节点 2 不可见〔fv7〕 | 还原，26 项全绿 |
+| M9 | `_fit_canvas` 宽公式去 `NODE_HALF.x` 项 | `level_map_info_fog_test` | 大图拟合：画布 min.x 覆盖最深节点（1298.0 ≥ 1334.5）〔fv8〕；全节点落在画布内〔fv8〕 | 还原，19 项全绿 |
+| M10 | `_candidate_at` 命中面放宽到全节点 | `ui_input_probe`（⑱） | 雾下节点点击产生提交（提交=[3] visible=true 选路态=true）〔fv9〕 | `git checkout` 还原，探针 PASS |
+
+### 5.5 实机目检总清单（只登记，不阻塞合并）
+
+| # | 项目 | 观测点 | 状态 |
+|---|---|---|---|
+| 1 | 雾下可读性观感 | 未知类型房间是否一眼可辨为「未知」而非「漏画」；编号仍在、类型图标与文字不出现 | 待用户试玩 |
+| 2 | 多终点 Boss 标记观感 | 双 Boss 图上两个终点的紫赤描边是否都清楚可辨 | 待用户试玩 |
+| 3 | 大图完整可见观感 | 大图（11 层×6 槽）整幅在画布内、无节点被裁切或挤在一角 | 待用户试玩 |
+
+### 5.6 遗留读数义务
+
+- 数值零变更（`info_visible_layers` 是呈现参数，不进战斗结算），本卡不发起模拟跑批（MC 档位规则）。
+- 合并后主区需 `--editor --quit` 重刷类名缓存，再跑一次代码域全量闸复跑，读数写入合并提交信息。
+- 合并前回执须与分支尖同 commit（回执 `commit` 字段）。
+
+### 5.7 全量代码闸读数
+
+T4 里程碑跑批 `tools/run_all_gates.sh --code`，起跑 commit `4ef154b9`：
+
+| 闸 | 退出码 | 对基线 |
+|---|---|---|
+| 01 冒烟全量 | 0 | 一致（1211 项检查 0 失败） |
+| 02 单元套件 | 0 | 一致（40 套件，含本卡新增 2 套件） |
+| 03 探针 --click | 0 | 一致 |
+| 04 探针 --full | 0 | 一致 |
+| 05 渲染闸 | 0 | 一致 |
+| 09 静态扫描 | 1 → 0 | 新增 4 处 R1（容器未参数化）→ `6f04f29b` 修复后归零，由红转绿（改善） |
+| 10 熵增闸 | 0 | 一致 |
+| 11 回放确定性对拍 | NEED-APPROVAL | 本卡数值零变更，按档位规则不发起（需用户批准） |
+
+`6f04f29b` 修复后窄验证：`audit_type_hints` PASS；两套件 26＋19 项全绿；`ui_input_probe` PASS。最终合并回执见本批合并提交信息（起跑 commit＝分支尖）。
+
+## 六、卡④ 独立验收审计
+
+待补（审计完成后写入结论与逐行依据）。
+