game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(需求卡片): 迭代31两卡冲突修订——卡① v1.3／卡② v1.1

Browse Source 
- 卡② D1 换代 forgive_flag_miss → forgive_seal_miss（2026-10-18 用户补裁），并加「标识符形态通则」：现状事实里的旧名与行号按卡① 合回后的 seal_ 形态复核，新写一律 seal_ 族
- 卡① 补 T3.1 漏链：flag_missed → seal_missed（含 effect_engine.gd:149/:152 天赋树合成行），否则 V1 零命中必红；§3 新增与卡② 的命名接续契约
- 两卡「关联文档同步面」与任务卡的文档义务由旧口径「机械面随批」改列 reports/ 反哺点（req-card §6/§7 2026-10-17 改口径：实现批禁写 design/ 与根规则文件）
- 两卡各补「设计事实源」声明；卡② 契约 8 实证订正为字段集不重叠、文件集重叠（effect_engine/grant_segment/battle_orchestrator 三文件两卡同改，禁并行开 worktree）；§10 补两项前置门
This commit is contained in:
DKChan committed 2026-10-18 19:42:16 +08:00
1 parent 39523dd424
commit ad48d2a2d2
2 files changed
+342 -17
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

design/research/需求卡片-代码术语刷新批-2026-10-18.md
+314
View File
@@ -0,0 +1,314 @@
# 需求卡片：代码术语刷新批（flag→seal＋中文禁用词清扫）
- 版本：**v1.3**（2026-10-18 卡片冲突修订批：补「设计事实源」声明；§5 同步义务由「机械面随批」改为反哺点清单（对齐 req-card §6/§7 2026-10-17 改口径）；T3.1 补 `flag_missed`→`seal_missed` 全链；新增与卡② 的命名接续契约。历史：v1.2 grilling 复核 Q4–Q8 全裁；v1.1 Q1–Q3 全裁）
- 来源：
- [06-待办清单](../gdd/06-待办清单.md)「代码术语刷新批——禁用词全库清扫＋flag→seal 标识符重命名」（2026-10-18 登记，工程直入）
- 用户裁定（2026-10-18，记忆 `project-terminology-rulings-20261018.md`）
- 审计报告：[代码术语审计报告-2026-10-18](../qa/代码术语审计报告-2026-10-18.md)
- 归属：全工程（排雷循环/战斗循环/冒险循环/呈现层/数据表/冒烟测试）；术语权威=[术语表](../gdd/术语表.md)
- 排期：**已编入 roadmap 迭代 31**（2026-10-18 用户确认；卡片状态＝已编入，开工门＝U0）
- **设计前置声明**：本卡属**重构/工程债**类，凭 2026-10-18 用户裁定与审计报告代码级证据直接写卡，跳过设计轨。
- **设计事实源**（req-card §2 三选一之③工程直入证据指认，2026-10-18 立规；v1.3 补声明）：[代码术语审计报告-2026-10-18](../qa/代码术语审计报告-2026-10-18.md)（已入库 HEAD）逐条 file:line ＋ 06 条目「代码术语刷新批——禁用词全库清扫＋flag→seal 标识符重命名（设计面=工程直入）」现状段。两处读数一致：`game/` 命中约 757 处（flag_ 270 处/29 个 .gd ＋ 22 处 .tres；金币 116／插旗 210／雷格 109）。
## 1. 目标与完成定义
| 需求点 | 一句话 |
|---|---|
| **N1** | 代码标识符 flag_* 全族重命名为 seal_*（变量名、函数名、字典键、事件名、数据表字段、字符串值） |
| **N2** | .gd 注释与 UI 字符串中中文禁用词清扫：金币→GP、插旗→封印、雷格→危险格、惩罚格→危险格、旗（游戏概念）→封印印记 |
| **N3** | .tres 数据文件中中文禁用词清扫（display_name、desc、注释） |
| **N4** | game/README.md 同步 |
**完成定义**：game/ 目录内全局搜索 `flag`（排除非游戏语境如 git flag）零命中；全局搜索「金币」「插旗」「雷格」「惩罚格」零命中（术语表对照行不在本卡范围）；全量冒烟（smoke_all.gd）＋单元测试（tests/run_all.gd）全绿，绿数与改前基线一致；`reports/` 三份产出物写齐（实现报告／代拍板追认单／反哺点清单）。
**文档面不在本卡完成定义内**（2026-10-17 req-card §6 改口径：代码实现批禁写 `design/` 整目录与根规则文件，唯一可写目录＝`reports/`）——06 条目状态推进、术语表、entities.yaml、07 目检项一律列进 `reports/iter31-反哺点-<日期>.md`，由用户在会话中裁决后归文档批落文。
## 2. 现状事实（2026-10-18 代码级实查）
### N1 · flag_* 标识符分布
**总量**：~314 处（270 处 .gd + 22 处 .tres + 22 处独立 `flag` 词）
**核心逻辑文件（改动密度前 10）**：
| 文件 | flag_ 命中 | 关键标识符 |
|---|---|---|
| smoke/smoke_all.gd | 105 | flag_place, flag_hit, flag_miss, flag_placed, _flag_consumed |
| core/settlement/grant_segment.gd | 23 | flag_hit, flag_miss, _flag_consumed, flag_settle |
| smoke/ui_input_probe.gd | 23 | flag_place, flag_cell |
| core/minesweeper_rules.gd | 18 | flag_place, has_flag, flag_range_free, _flag_miss_seen |
| core/battle_orchestrator.gd | 17 | flag_hit, flag_hit_premium, _flag_consumed |
| smoke/level_autoplay.gd | 16 | flag_placed, flag_hit, flag_miss |
| data/tables/feats.tres | 15 | "flag_hit"(on 触发), "echo_flags", "smith_flags", "flag_burst"(feat_id) |
| core/effect_engine.gd | 9 | `EVENTS` 含 "flag_hit"（:13）、"flag_missed"（:15）；`MINE_EVENTS` 含 "flag_hit"、"flag_settle"（:20）；天赋树合成行 `_push_trigger("tree", …, {"on": "flag_missed"})` 2 处（:149、:152）；头注 :9 含「flag_missed 标错判定」 |
| presentation/views/battle_end_overlay.gd | 9 | flag_hit, flag_miss 统计显示 |
| presentation/views/board_view.gd | 7 | tex_flag, has_flag, flag_cell |
**数据表字段（.tres 键名，改动必须与 schema .gd 同步）**：
| 文件 | 字段 | 改后 |
|---|---|---|
| action_economy.tres:9 | `flag_place_ap_cost = 1` | `seal_place_ap_cost = 1` |
| settlement.tres:9 | `flag_hit_premium = 125` | `seal_hit_premium = 125` |
| settlement.tres:13 | `"flag_hit": "标中旗"` | `"seal_hit": "封印命中"` |
| settlement.tres:18 | `"flag_miss": "标旗未中"` | `"seal_miss": "封印未中"` |
| feats.tres:257,305,320,328,352,806,844 | `"on": "flag_hit"` | `"on": "seal_hit"` |
| feats.tres:260,269,285,292 | `"echo_flags"` | `"echo_seals"` |
| feats.tres:323,332 | `"smith_flags"` | `"smith_seals"` |
| feats.tres:838 | `"feat_id": "flag_burst"` | `"feat_id": "seal_burst"` |
| feats.tres:615 | `"fact": "dug_under_flag"` | `"fact": "dug_under_seal"` |
| treasure_items.tres:223 | `"flag_range_free"` | `"seal_range_free"` |
**Schema 校验文件（.gd 中读 .tres 键名的代码）**：
| 文件 | 涉及 |
|---|---|
| data/schemas/action_economy_table.gd | 读 flag_place_ap_cost（4 处） |
| data/schemas/settlement_table.gd | 读 flag_hit_premium（3 处） |
| data/schemas/treasure_item_table.gd | 读 flag_range_free（3 处） |
| core/action_economy.gd | "flag_place" 事件名（2 处） |
| core/config_db_cross_validator.gd | required_sources 含 "flag_hit", "flag_miss"（2 处） |
**Godot 信号声明（API 契约，连接方必须同名）**：
| 文件 | 声明/连接 | 改后 |
|---|---|---|
| core/minesweeper_rules.gd:9 | `signal flag_judged(evt: Dictionary)` | `signal seal_judged(evt: Dictionary)` |
| core/battle_orchestrator.gd:287 | `minesweeper.flag_judged.connect(_on_flag_judged)` | `minesweeper.seal_judged.connect(_on_seal_judged)` |
**已知假阳性（显式排除，不改）**：
| 文件 | 标识符 | 原因 |
|---|---|---|
| presentation/views/ui_assembler.gd | `size_flags_vertical` / `size_flags_horizontal` / `size_flags_stretch_ratio` | Godot 引擎 Control 内置属性 |
| core/config_db.gd | `_fatal_flag` | 无关变量（致命错误标记） |
**存档影响面（Alpha 阶段可接受作废，不做迁移）**：
| 持久化路径 | 涉及键 | 影响 |
|---|---|---|
| save.json → breakpoint.adventure_counters | `"echo_flags"`, `"smith_flags"` | 旧档计数器失效，Alpha 阶段可接受（2026-10-18 用户裁定） |
### N2 · 中文禁用词分布（.gd 文件）
| 禁用词 | 命中 | 主要落点 |
|---|---|---|
| 金币 | ~35 处 | UI 字符串（shop_overlay_view 5、camp_shop_presenter 3、battle_narrator 2、curio_pick_overlay 2、legend_overlay 1）＋注释（smoke_all 10、battle_orchestrator 1 等） |
| 插旗 | ~100 处 | 注释为主（grant_segment 6、minesweeper_rules 4、board_view 4、smoke_all 14）＋UI 字符串（hud_presenter 1、main.gd 1、legend_overlay 1） |
| 雷格 | ~80 处 | 注释（battle_orchestrator 11、smoke_all 31、minesweeper_rules 5、grant_segment 3、board_generator 1）＋测试断言文本 |
| 惩罚格 | ~2 处 | treasure_items.gd 注释 |
| 旗（游戏概念） | ~15 处 | UI 字符串（legend_overlay "旗"、hud_presenter "已有旗"）＋注释（"标中旗""标错旗""拔旗"等） |
### N3 · .tres 中文禁用词
| 文件 | 命中 |
|---|---|
| reward.tres:188 | `"display_name": "金币袋"` |
| reward.tres 注释 | 金币袋、雷格（~5 处） |
| feats.tres:10-11 | 注释含「插旗=封印」「禁『雷/插旗』字面」 |
| treasure_items.tres:212 | `"desc": "插旗不限相邻（可对任何未开格插旗）"` |
| settlement.tres:13,18 | `"标中旗"` / `"标旗未中"` |
| action_economy.tres:18 | 注释含「雷格」 |
| status_effects.tres:96 | 注释含「雷格」 |
### N4 · game/README.md
雷格 8 处、插旗 1 处，均为架构说明注释。
### 关联面（本卡不动）
- design/ 目录文档面（另批委派处理）
- tools/*.py 中的「雷格」（analyze_playtest.py 1 处、render_sample_sheet*.py 6 处）——归文档批或工具批
- sim-data/analyze.py（1 处雷格）——同上
- 术语表自身修正——归文档批
## 3. 设计契约（红线，违反＝L3 停机呈报）
- 🔴 **游戏行为零变化**：本批是纯重命名/文本替换，禁止改动任何游戏逻辑、数值、权重、条件判断。改前改后同种子冒烟读数必须逐位一致。
- 🔴 **.tres 键名与 schema .gd 必须同批同步**：改 settlement.tres 的 `flag_hit_premium` 必须同批改 settlement_table.gd 里读它的代码，否则数据加载失败。
- 🔴 **事件名字符串全链一致**：`"flag_hit"` 作为事件名贯穿 effect_engine.gd EVENTS 常量 → grant_segment.gd 发射 → feats.tres `"on"` 触发 → config_db_cross_validator.gd 校验 → battle_log_view.gd 呈现。改一处必须全链同步。
- 🔴 **Godot 信号声明与连接同名**：`signal flag_judged`（minesweeper_rules.gd:9）→ `seal_judged`；连接方 `battle_orchestrator.gd:287` 的 `.connect(_on_flag_judged)` → `.connect(_on_seal_judged)`；回调函数名同步。
- 🔴 **冒烟断言文本同步**：smoke_all.gd 中 check() 的描述字符串含「雷格」「插旗」「金币」的，随批替换；断言逻辑（数值、条件）零改动。
- 🔴 **显式排除清单（假阳性）**：`size_flags_vertical` / `size_flags_horizontal` / `size_flags_stretch_ratio`（Godot 引擎 Control 属性，ui_assembler.gd）与 `_fatal_flag`（config_db.gd 无关变量）**不在重命名范围**，盲替换命中即 L3。
- 🔴 **本批不保证旧存档兼容**：`echo_flags` / `smith_flags` 等 counter_id 持久化在 save.json 的 `breakpoint.adventure_counters` 中，重命名后旧档该键失效。Alpha 阶段可接受存档作废，不做迁移逻辑（2026-10-18 用户裁定）。
- 🔴 **不改 design/ 目录**：实现批禁写 design/（process-conventions §3 第 13 条）。
- 🔴 **不改 tools/*.py**：工具脚本归文档批。
- 🔴 **非游戏语境的 flag 不动**：如 `git flag`、编译标志等（实查 game/ 内无此情况，但作为纪律登记）。
- 🔴 **与卡② 的命名接续（2026-10-18 用户补裁，v1.3 新增）**：本卡合回后，卡②（凭证件裁削批）新写的标识符一律 `seal_` 族——其效果类型名 `forgive_flag_miss` 已由同日补裁换代为 **`forgive_seal_miss`**，事件订阅写 `on: "seal_missed"`。故本卡的 V1「`flag` 零命中」在迭代 31 出口仍成立，不需要为卡② 打排除补丁。本卡执行时 `flag_missed` 必须一并改名为 `seal_missed`（原 v1.2 映射表漏列，v1.3 补入 T3.1）。
## 4. 范围边界
**做**：
- game/ 目录内全部 .gd、.tres、.md 文件的 flag→seal 重命名与中文禁用词替换
- 替换后全量冒烟＋单元测试验证
**不做（去向）**：
| 不做的 | 去向 |
|---|---|
| design/ 全部文档 | 文档批（用户委派另会话） |
| tools/*.py | 文档批或工具批 |
| sim-data/ | 同上 |
| 术语表自身修正 | 文档批 |
| 游戏逻辑/数值改动 | 禁止（本批纯重命名） |
| doc_term_audit.py 词表扩充与扫描域扩展 | 文档批（T5） |
## 5. 关联文档同步面
> **口径（v1.3，2026-10-17 起生效）**：本批禁写 `design/` 整目录与根规则文件，唯一可写目录＝`reports/`。下表凡标「反哺点」者＝把「哪个文件哪一节、改成什么、依据是什么」写进 `reports/iter31-反哺点-<日期>.md`，由用户裁决后归文档批落文；本批一律不落笔 `design/`。v1.2 及以前的「机械面随批」措辞作废。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| [06-待办清单](../gdd/06-待办清单.md) | 「代码术语刷新批」条目状态推进为「已完成（迭代 31 卡①，合并 `<commit>`，2026-10-XX）」 | **反哺点**（`design/` 内，本批禁写）：推进句写进 `reports/iter31-反哺点清单`，文档批落笔后本条清掉 |
| [术语表](../gdd/术语表.md) | flag→seal 重命名后，术语表「旗/控制」条目需同步改为「封印/控制」 | **反哺点**：文档批处理，本卡不改 design/ |
| [entities.yaml](../registry/entities.yaml) | 第 268 行「机制键与规则（flag_place/flag_rules/标中旗三向效果）全不变，纯呈现层命名」＋source_label_map 键集标注「结构冻结」——代码批执行后此条款失效，需解冻并换代为 seal_* | **反哺点**：文档批需显式废止「结构冻结」条款、将 flag_* 契约键全部换代为 seal_*。窗口期（代码已改、registry 未改）可接受——registry 非运行时依赖（2026-10-18 grilling Q4 裁定） |
| game/README.md | 架构说明中雷格/插旗 | **本批直改**（文件在 `game/` 内，不属 `design/` 禁写面）——随批替换 |
| game/tests/evidence/parity/anchor.json | MC 输出基线含 ~600 处 flag_* 键（flag_hit/flag_hit_gain/flag_miss/flag_miss_penalty/flag_placed/flag_burst） | **本批直改**（在 `game/` 内）：手动替换键名（行为零变化故不重跑 MC），替换后跑 parity 闸确认绿 |
| [07-体验验证清单](../gdd/07-体验验证清单.md) | UI 文本换代后目检项 | **反哺点**：登记「商店/图例/HUD 文本是否显示 GP/封印而非金币/插旗」目检项，文档批落 |
## 6. 任务卡
### T0 · 基线记录（≈10min）
1. 跑全量冒烟（smoke_all.gd），记录绿数基线。
2. 跑单元测试（tests/run_all.gd），记录套数与绿数。
3. 记录当前 game/ 内 `flag` 总命中数（grep 计数，作为改后零残留的对照）。
### T1 · .tres 数据文件重命名（≈0.5d）
先改数据层（被 .gd 读取的源头），再改 .gd 消费侧，避免中间态加载失败。
1. action_economy.tres：`flag_place_ap_cost` → `seal_place_ap_cost`；注释中「雷格」→「危险格」
2. settlement.tres：`flag_hit_premium` → `seal_hit_premium`；`"flag_hit": "标中旗"` → `"seal_hit": "封印命中"`；`"flag_miss": "标旗未中"` → `"seal_miss": "封印未中"`；注释中「雷格」→「危险格」
3. feats.tres：全部 `"on": "flag_hit"` → `"on": "seal_hit"`；`echo_flags` → `echo_seals`；`smith_flags` → `smith_seals`；`flag_burst` → `seal_burst`；`dug_under_flag` → `dug_under_seal`；注释中「插旗」→「封印」
4. treasure_items.tres：`flag_range_free` → `seal_range_free`；desc「插旗不限相邻（可对任何未开格插旗）」→「封印不限相邻（可对任何未开格封印）」
5. reward.tres：`"display_name": "金币袋"` → `"display_name": "GP 袋"`；注释中「金币袋」「雷格」替换
6. status_effects.tres：注释中「雷格」→「危险格」
### T2 · Schema .gd 同步（≈0.25d）
与 T1 同批完成（.tres 键名改了，读它的 schema 必须同步）：
1. action_economy_table.gd：flag_place_ap_cost → seal_place_ap_cost（4 处）
2. settlement_table.gd：flag_hit_premium → seal_hit_premium（3 处）
3. treasure_item_table.gd：flag_range_free → seal_range_free（3 处）
4. reward_table.gd：注释中「雷格」→「危险格」
### T3 · 核心逻辑 .gd 重命名（≈1d）
按依赖序改（底层→上层）：
1. core/effect_engine.gd：EVENTS/MINE_EVENTS 常量 "flag_hit"→"seal_hit", "flag_settle"→"seal_settle", **"flag_missed"→"seal_missed"**；天赋树合成行 :149/:152 的 `{"on": "flag_missed"}` 同步改名；头注 :9 文本随批（处数不写死，以 V1 grep 零命中为准）
2. core/minesweeper_rules.gd：flag_place→seal_place, has_flag→has_seal, flag_range_free→seal_range_free, _flag_miss_seen→_seal_miss_seen（18 处）＋注释中「插旗」「雷格」替换
3. core/action_economy.gd："flag_place"→"seal_place"（2 处）
4. core/battle_orchestrator.gd：flag_hit→seal_hit, flag_hit_premium→seal_hit_premium, _flag_consumed→_seal_consumed（17 处）＋注释替换
5. core/settlement/grant_segment.gd：flag_hit→seal_hit, flag_miss→seal_miss, _flag_consumed→_seal_consumed（23 处）＋注释中「插旗」「雷格」替换
6. core/config_db_cross_validator.gd：required_sources 中 "flag_hit"→"seal_hit", "flag_miss"→"seal_miss"（2 处）＋注释「雷格」
7. core/reward_economy.gd：注释「雷格」→「危险格」
8. core/board_generator.gd：注释「雷格」→「危险格」
9. core/treasure_items.gd：注释「插旗」「惩罚格」替换
### T4 · 呈现层 .gd 重命名＋UI 字符串（≈0.5d）
1. presentation/views/board_view.gd：tex_flag→tex_seal, has_flag→has_seal, flag_cell→seal_cell（7 处）＋注释
2. presentation/views/board_cell_unit.gd：tex_flag→tex_seal（2 处）＋注释「插旗」「雷格」
3. presentation/views/shop_overlay_view.gd：UI 字符串「金币」→「GP」（5 处）
4. presentation/camp_shop_presenter.gd：「金币不足」→「GP 不足」（3 处）
5. presentation/curio_interact_controller.gd：「金币不足」→「GP 不足」（1 处）
6. presentation/battle_narrator.gd：「金币」→「GP」（2 处）
7. presentation/views/curio_pick_overlay.gd：「金币」→「GP」（2 处）
8. presentation/views/legend_overlay.gd：「金=金币」→「金=GP」；「右键插旗」→「右键封印」；「旗」→「封印印记」（3 处）
9. presentation/hud_presenter.gd：「不能插旗：此格已有旗」→「不能封印：此格已有封印印记」（1 处）
10. presentation/main.gd：「插旗后轮末自动判定标中」→「封印后轮末自动判定」（2 处）＋注释
11. presentation/views/battle_log_view.gd："flag_miss"→"seal_miss"（1 处）＋注释「金币」
12. presentation/views/battle_end_overlay.gd：flag_hit/flag_miss 统计键（9 处）
13. presentation/views/ui_kit.gd：注释「金币」「插旗」「雷格」＋TEX_ICON_COINBAG 注释
14. presentation/views/level_map_screen.gd：注释「金币」
15. presentation/views/board_fx_view.gd：flag 相关（1 处）
16. presentation/views/standee_body.gd：flag 相关（1 处）
17. presentation/row_pacer.gd："flag_hit"→"seal_hit"（2 处）
18. presentation/views/status_slot_row.gd：flag 相关（1 处）
### T5 · 冒烟与测试 .gd 重命名（≈1d）
1. smoke/smoke_all.gd：105 处 flag_ 替换＋注释/断言文本中「金币」「插旗」「雷格」替换（~50 处）
2. smoke/level_autoplay.gd：16 处 flag_ ＋注释「插旗」
3. smoke/ui_input_probe.gd：23 处 flag_ ＋注释「插旗」
4. smoke/ui_click_probe.gd：注释「插旗」（3 处）
5. smoke/adventure_monte_carlo.gd：5 处 flag_ ＋注释
6. smoke/auto_player.gd：注释「雷格」（4 处）
7. smoke/fx_shot_probe.gd：注释「插旗」（1 处）
8. smoke/board_shot_probe.gd："flag_place"→"seal_place"（1 处）
9. smoke/ui_contrast_probe.gd：注释「金币」（1 处）
10. tests/unit/core/minesweeper_rules_test.gd：flag 相关（5 处）＋「插旗」
11. tests/unit/core/board_generator_test.gd：「雷格」（1 处）
12. tests/unit/core/treasure_effects_test.gd：flag 相关（3 处）＋「插旗」
13. tests/unit/core/feat_vouchers_test.gd：「金币」（1 处）
14. tests/unit/presentation/hud_presenter_test.gd：「插旗」（1 处）
15. tests/unit/presentation/reward_overlay_test.gd：「金币」（2 处）
16. tests/unit/core/tree_rules_v11_test.gd：flag 相关（2 处）
17. tests/unit/core/treasure_items_test.gd：flag 相关（1 处）
18. tests/run_all.gd：注释「插旗」（1 处）
19. tests/smoke/critical-paths.md：「雷格」「插旗」（2 处）
### T6 · game/README.md＋anchor.json＋全量验证（≈0.5d）
1. game/README.md：雷格（8 处）→危险格、插旗（1 处）→封印
2. game/tests/evidence/parity/anchor.json：手动替换全部 flag_* 键名为 seal_*（~600 处：flag_hit→seal_hit, flag_hit_gain→seal_hit_gain, flag_miss→seal_miss, flag_miss_penalty→seal_miss_penalty, flag_placed→seal_placed, flag_burst→seal_burst）
3. 全量冒烟＋单元测试，绿数与 T0 基线一致
4. parity 闸跑通（anchor.json 键名替换后与 MC 新输出一致）
5. 全局搜索验证：game/ 内 `flag`（排除 size_flags_* 和 _fatal_flag）零命中；「金币」「插旗」「雷格」「惩罚格」零命中
6. **产出物落位卡**（req-card §7：末卡必含）：`reports/` 三份写齐——`iter31-实现报告-<日期>.md`（含 V1–V7 读数＋改前改后同种子读数对照＋实机目检总清单）、`iter31-代拍板-<日期>.md`、`iter31-反哺点-<日期>.md`（§5 每条反哺点都要有落点：06 推进句／术语表／entities.yaml／07 目检项）。**禁改 `design/` 与 `roadmap.md`**
**估时合计 ≈3.75d**。
## 7. 验证闸（逐需求点验收清单）
**能力验证（自动化，随批）**：
- **V1（N1）**：改后全局 grep `flag` game/ 目录，排除 `size_flags_*` 和 `_fatal_flag` 后零命中。
- **V2（N1）**：全量冒烟绿数 == T0 基线（行为零变化证词）。
- **V3（N1）**：单元测试绿数 == T0 基线。
- **V4（N2/N3）**：改后全局 grep「金币」「插旗」「雷格」「惩罚格」game/ 目录零命中。
- **V5（N2）**：settlement.tres 的 source_class 显示名不含「旗」字（「封印命中」「封印未中」）。
- **V6（回归）**：同种子冒烟读数逐位一致（纯重命名不改行为的最强证词）。
- **V7（parity）**：anchor.json 键名替换后 parity 闸绿（MC 输出与基线逐位一致）。
**正常流程体验（用户目检，登记 07 不阻塞）**：
1. 商店界面显示「GP」而非「金币」。
2. 图例/HUD 显示「封印」而非「插旗」「旗」。
3. 结算明细来源显示「封印命中」而非「标中旗」。
## 8. 异常分级
- **L1（自救）**：单个文件漏改导致 grep 验证未过——补改即修，不改批结构。
- **L2（记录继续）**：冒烟绿数与基线偏差 ≤2（断言文本替换引起的描述性变化，非逻辑变化）——记录偏差原因，确认非逻辑回归后继续。
- **L3（停机呈报）**：冒烟绿数下降 >2 或出现逻辑断言红（说明重命名触及了行为）；.tres 加载失败（schema 不同步）；同种子读数不一致（行为变化）。
## 9. 代拍板白名单（超清单必呈报）
1. 注释替换时的措辞微调（如「挖雷格」→「挖危险格」vs「挖掘危险格」）——语义等价即可，不必逐条请示。
2. seal_* 的具体拼写形态（如 `_seal_consumed` vs `_consumed_seals`）——与 flag_* 原形态保持同构即可。
3. 测试断言描述文本的替换措辞——语义等价即可。
4. settlement.tres 显示名「封印命中」「封印未中」的具体措辞——若用户有异议呈报。
## 10. 待裁点
**零待裁点，开工门＝U0。** Q1–Q3 于 2026-10-18 用户令「按推荐来」全裁；Q4–Q8 于同日 grilling 复核后用户裁定落定：
| # | 裁定 | 落定结论 |
|---|---|---|
| Q1 | reward.tres display_name | **GP 袋**（金币袋→GP 袋） |
| Q2 | settlement.tres 显示名 | **封印命中 / 封印未中**（标中旗→封印命中、标旗未中→封印未中） |
| Q3 | feats.tres feat_id | **seal_burst**（flag_burst→seal_burst） |
| Q4 | 存档兼容 | **不做迁移，Alpha 阶段旧存档可作废**（echo_flags/smith_flags 计数器失效可接受） |
| Q5 | anchor.json 处理 | **手动替换键名**（行为零变化不重跑 MC），替换后跑 parity 闸确认绿 |
| Q6 | 假阳性排除 | **显式排除清单入红线**：size_flags_*（Godot 引擎属性）、_fatal_flag（config_db 无关变量） |
| Q7 | registry 契约窗口期 | **可接受**（registry 非运行时依赖；文档批紧随其后；entities.yaml「结构冻结」条款标注为反哺点，文档批需显式废止并换代） |
| Q8 | 信号声明补全 | **signal flag_judged → seal_judged 显式入映射表**（Godot 信号=API 契约，连接方必须同名） |
---
**卡片成立前置**：~~grilling 复核门~~（2026-10-18 已过，Q4–Q8 全裁）＋~~用户卡审~~（2026-10-18 已过，用户确认编入迭代 31）。
design/research/需求卡片-凭证件裁削批-2026-10-18.md
+28 -17
View File
@@ -2,7 +2,10 @@
- **批次名**：凭证件裁削批（代码侧）
- **日期**：2026-10-18
- **批次性质**：工程债／错置修正（凭 06 在册条目直接写卡，无设计前置要求——设计已于同日文档批在奇物.md v3.18 定稿）
- **批次性质**：工程债／错置修正（凭 06 在册条目直接写卡；设计已于同日文档批在奇物.md v3.18 定稿）
- **设计事实源**（req-card §2 三选一之①GDD 文档节＋版本号，2026-10-18 立规；v1.1 补声明）：`design/gdd/systems/冒险循环/奇物.md` **v3.18**（删件／迁出／配额净删三段定稿）。**前置门见 §10**。
- **标识符形态通则（v1.1，2026-10-18 用户补裁）**：本卡成文于卡① 之前。凡卡① 改名范围内的标识符（`flag_hit`／`flag_miss`／`flag_missed`／`flag_settle`／`flag_judged`），本卡 §2 现状事实的旧名与行号**按卡① 合回后的 `seal_` 形态**复核执行，不逐处更新旧名；本卡新写的标识符一律 `seal_` 族——效果类型名取 **`forgive_seal_miss`**（取代 D1 原裁 `forgive_flag_miss`），feats.tres 触发行写 `on: "seal_missed"`。
- **版本**：**v1.1**（2026-10-18 卡片冲突修订批：补设计事实源与标识符形态通则；D1 换代为 `forgive_seal_miss`；契约 3/8 订正；§5/§6 文档同步义务改为 `reports/` 反哺点清单；§10 补前置门。原 v1.0＝2026-10-18 立卡）
- **迭代归属**：迭代 31 第二张卡（与卡①「代码术语刷新批」串行）
- **上游依据**：用户 2026-10-18 逐裁四项——①同调电池**删除**；②完美保险**改归专长**、语义档＝**甲（每战首次封印落空豁免）**；③desc 用 A「本场首次封印落空，不计入完美封印判定」；④寿命域**本批不动**、完美保险按现役 `domain=battle` 落地；配额处置＝**净删**（rare 9→7／总量 104→102）
@@ -19,7 +22,7 @@
3. `feats.tres` 增完美保险专长行，四词表校验通过，效果引擎装载并可派发；
4. 完美排雷判定改为「误标总数 − 豁免数」两账相减式，`_perfect_hit_false` 保持纯净、不被任何效果改写；
5. `TIER_QUOTAS` rare 9→7、总量 104→102，`validate()` 硬断言通过；
6. 批末四闸（冒烟＋单元测试＋场景探针＋改前改后读数对拍）全绿，机械面文档同步完毕。
6. 代码域闸全绿（冒烟＋单元测试＋场景探针＋改前改后读数对拍）＋`reports/` 三份产出物写齐（实现报告／代拍板追认单／反哺点清单）。**文档面（奇物.md 指针销号、entities.yaml 104→102、07 观测项、roadmap 行）不在本条完成定义内**——实现批禁写 `design/` 与根规则文件，一律列进反哺点清单归文档批落笔（v1.1 订正，原句「机械面文档同步完毕」属 2026-10-17 改口径前的旧措辞）。
---
@@ -84,18 +87,18 @@
1. 🔴 **`attune_charges` 账本与 `_seed_attune_charges` 禁删**（`adventure_runner.gd:29/:109/:201/:243/:559-564`）——迭代 11 秘宝基础设施（主动件充能每冒险重置）。本批只删奇物侧写它的入口，不碰账本本体。
2. 🔴 **`_perfect_hit_false` 保持纯净**：任何效果不得改写该值。豁免必须走「自有累加计数 + 判定时相减」，即新增 `_perfect_forgiven` 单向累加，判定取 `effective_miss = _perfect_hit_false - _perfect_forgiven`。**禁止回退式（改别人的值）与拦截式（吞事件）**——两者均已由用户否决。
3. 🔴 **`flag_missed` 事件照常发射**，不得因本件改动改变发射时机或吞并事件，其它订阅方（危险直觉·守等）零感知。
3. 🔴 **`seal_missed` 事件照常发射**（卡① 合回前名 `flag_missed`——见顶部标识符形态通则），不得因本件改动改变发射时机或吞并事件，其它订阅方（危险直觉·守等）零感知。
4. 🔴 **玩家面禁「雷」字**（奇物.md v3.15 命名纪律：插旗＝封印、危险格风味＝地下城陷阱／怪物巢穴）。本批新增的 `feats.tres` 行 desc 与任何 UI 字符串不得含「雷」。
5. 🔴 **四词表封闭**：新增 effect kind 必须同步进 `EFFECT_KINDS` 并在解释器 switch 加分支，否则行校验致命。
6. 🔴 **`domain=battle` 显式写出**：该行将是 `feats.tres` 首例 battle 域（现役 29 行全为 adventure 或不写），须在数据行与代码注释双处留痕，防止后来者误读为缺省。
7. 🔴 **改总量＝重裁**：`TIER_QUOTAS` 总量变动是结构锚。用户已裁「净删」（rare 9→7／总量 104→102），本批不得自行把令牌转给别件来保住总量。
8. 🔴 **本批与迭代 31 卡①串行同迭代**：卡①改玩家面字符串（金币→GP、雷格→危险格），grep 实证与本卡文件集不重叠（卡①不含 `CURIO_KINDS`／`TIER_QUOTAS`／`curio_*` 字段）；双方合回前各 `git merge master`，禁在对方未合回时强行推主区。
8. 🔴 **本批与迭代 31 卡①串行同迭代**（v1.1 订正实证陈述）：卡① 改标识符与玩家面字符串。**字段集不重叠**（卡① 不动 `CURIO_KINDS`／`TIER_QUOTAS`／`curio_*`），但**文件集重叠**——`core/effect_engine.gd`（卡① 改 EVENTS／本卡 T4 加 EFFECT_KINDS＋switch）、`core/settlement/grant_segment.gd`（卡① 改名／本卡 T4 改判定式）、`core/battle_orchestrator.gd`（卡① 改名／本卡 T3 删 `_fx_insurance`）。故**禁两卡并行开 worktree**；本卡必须在卡① 合回 master 后开工，开工前 `git merge master` 取卡① 成果并按顶部通则复核标识符名与行号。
---
## 4. 范围边界
**做**：上列 6 项完成定义内的全部代码与数据表改动、测试更新、机械面文档同步。
**做**：上列 6 项完成定义内的全部代码与数据表改动、测试更新、`reports/` 三份产出物（实现报告／代拍板追认单／反哺点清单）。
**不做**（去向明确）：
@@ -111,14 +114,17 @@
## 5. 关联文档同步面
> **口径（v1.1，2026-10-17 起生效）**：本批禁写 `design/` 整目录与根规则文件，唯一可写目录＝`reports/`。凡标「反哺点」者＝把「哪个文件哪一节、改成什么、依据是什么」写进 `reports/iter31-反哺点-<日期>.md`，由用户裁决后归文档批落笔。v1.0 的「机械面随批」措辞作废（属 2026-10-17 改口径前的旧口径）。
| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 |
|---|---|---|
| `design/gdd/systems/冒险循环/奇物.md` | v3.18 已定稿删件/迁出；本批代码落地后，件表注与迁入登记段中「归独立批」的指针可销号 | **机械面**随批更新（销号一句） |
| `design/registry/entities.yaml:633` | 「104 总量」读数须改为 102（当前注记明写"仍为代码现值，改数随独立代码批同步"） | **机械面**随批更新 |
| `design/gdd/07-体验验证清单.md` | 两件退出后相关观测项注销（文档批已加注，本批确认生效） | **机械面**随批确认 |
| `roadmap.md` | 迭代 31 行＝双卡；当前位目标句容纳两批 | **机械面**随批更新 |
| `game/README.md` | 若载有两件名或配额读数 | **机械面**随批核对 |
| GDD 反哺点 | **零**——设计侧已在 v3.18 定稿，本批无新设计决策需反哺 | 无 |
| `design/gdd/systems/冒险循环/奇物.md` | v3.18 已定稿删件/迁出；本批代码落地后，件表注与迁入登记段中「归独立批」的指针可销号 | **反哺点**·列清单（`design/` 内，本批禁写） |
| `design/registry/entities.yaml:633` | 「104 总量」读数须改为 102（当前注记明写"仍为代码现值，改数随独立代码批同步"）；:254 完美排雷判据句须补「有效误标＝误标数−豁免数」口径 | **反哺点**·列清单（含两处：104→102 读数换代＋判据句补写） |
| `design/gdd/07-体验验证清单.md` | 两件退出后相关观测项注销；本卡新增 R5/R6 目检项（专长卡面文案／三选一池面观感）入册 | **反哺点**·列清单（本批禁写 07；R5/R6 目检项先记 `reports/` 实现报告总清单） |
| `roadmap.md` | 迭代 31 行状态由「待开工」改「已完成」；顶部「当前位」三行换代 | **反哺点**·列清单（根规则文件，本批禁写；第 3 步搬运定义面除外——那是提交既有文件，不是本批撰写） |
| `game/README.md` | 若载有两件名或配额读数 | **本批直改**（文件在 `game/` 内，不属 `design/` 禁写面）——随批核对更新 |
| `design/gdd/06-待办清单.md` | 「凭证件裁削批·代码侧迁移」条目状态推进为已完成 | **反哺点**·列清单（本批禁写；§10 前置门 2 的推进归用户／文档批） |
| GDD 设计结论 | **零新增**——设计侧已在 v3.18 定稿，本批无新设计决策需反哺 | 无（上述五行是既有陈述的换代，不是新设计） |
---
@@ -130,11 +136,11 @@
| **T1 同调电池·表侧删除** | `CURIO_KINDS` 移除 kind；删 `curio_quota_attune_battery_rare`／`curio_value_attune_battery_rare`／`curio_cap_attune_battery` 三字段及分发表三处分支（:138/:159/:176）；同步 schema 头注（:19-20 五件入池表述） | 0.25–0.5d |
| **T2 同调电池·runner 侧删除** | 删 `_battery_pending`、断点回填（:213）、重置（:261）、路由分支（:415-417）、`choose_battery_target`（:598-610）、`battery_pending()`（:615-616）、断点键（:1076）；`feat_vouchers_test.gd` V9-5 断言组整组删 | 0.25–0.5d |
| **T3 完美保险·出池** | `CURIO_KINDS` 移除 kind；删配额／件值／cap 三字段与分发表三处分支；删 runner 侧 `_pending_insurance`、重置、路由分支、战首注入链（:920-923）中该件分量；删 `battle_orchestrator._fx_insurance` 与 `:422` 注入；`feat_vouchers_test.gd` V9-4 断言组整组删 | 0.5–1d |
| **T4 引擎扩签＋两账相减** | `EFFECT_KINDS` 增 `forgive_flag_miss`（D1 已裁）；解释器 switch 加分支；`battle_orchestrator` 增 `_perfect_forgiven`（install 重置同 :471-472）；`grant_segment` 判定改 `effective_miss = _perfect_hit_false - _perfect_forgiven`，删硬编码 if；`flag_missed` 发射位置与时机不动 | 0.5–1d |
| **T5 专长行落表** | `feats.tres` 增完美保险行（规格＝§10 D2，已裁：rarity rare／cap 省略／desc「本场首次封印落空，不计入完美封印判定」／feat_id 取 `perfect_insurance`）；`feat_table` 校验通过；确认 rebuild 装载并在 `_triggers` 出现 | 0.25–0.5d |
| **T4 引擎扩签＋两账相减** | `EFFECT_KINDS` 增 **`forgive_seal_miss`**（v1.1 换代，原 `forgive_flag_miss`）；解释器 switch 加分支；`battle_orchestrator` 增 `_perfect_forgiven`（install 重置同 :471-472）；`grant_segment` 判定改 `effective_miss = _perfect_hit_false - _perfect_forgiven`，删硬编码 if；`seal_missed` 发射位置与时机不动（卡① 合回前该事件名仍为 `flag_missed`） | 0.5–1d |
| **T5 专长行落表** | `feats.tres` 增完美保险行（规格＝§10 D2，已裁：rarity rare／cap 省略／desc「本场首次封印落空，不计入完美封印判定」／feat_id 取 `perfect_insurance`）；**触发行 `on` 取 `"seal_missed"`**（卡① 合回前该名仍为 `flag_missed`）、`kind` 取 `forgive_seal_miss`、`domain=battle` 显式写出；`feat_table` 校验通过；确认 rebuild 装载并在 `_triggers` 出现 | 0.25–0.5d |
| **T6 配额重裁落地** | `TIER_QUOTAS` rare 9→7、总量 104→102；`validate()` 硬断言通过；`adventure.tres` 实例值同步；核对 rare 档剩余品种＝ap／rap／time_sand 三种 | 0.25d |
| **T7 测试补齐** | 新增专长侧验收（见验证闸）；变异验证逐条执行并记录 | 0.5–1d |
| **T8 文档同步闸＋批末四闸** | 轻闸全绿后：机械面文档更新完毕（销号奇物.md「归独立批」指针、entities.yaml 104→102、roadmap 迭代 31 双卡、README 核对）；反哺点逐条列明（本批为零）；跑批末四闸；写实现报告 | 0.25–0.5d |
| **T8 产出物落位卡＋代码域闸** | 轻闸全绿后：`reports/` 三份写齐——实现报告（各 T 卡状态＋改前改后读数对拍＋实机目检总清单含 R5/R6＋变异验证记录表）、代拍板追认单、**反哺点清单**（§5 每条都要有落点：奇物.md 指针销号句、entities.yaml 104→102 与 :254 判据句、07 观测项换代、roadmap 迭代 31 行与「当前位」换代、06 本条状态推进句、术语表 `forgive_seal_miss`／`seal_missed` 换代）；`game/README.md` 属 `game/` 内文件、本批直改核对；跑代码域闸全绿。**禁改 `design/` 与 `roadmap.md`** | 0.25–0.5d |
**合计**：≈2.75–4.75d（超软盒预案：T3/T4 若撞断点兼容问题，先落 T1/T2/T6 的可独立验证部分，T3–T5 转下一批并登记 06）。
@@ -153,7 +159,7 @@
| R2 豁免一次 | 同战两次标错：首次 `effective_miss` 不增、第二次增；跨战后首次标错又豁免一次（domain=battle 每战清零） | 单元：直构引擎＋编排 rig（参照 `smoke_all.gd:6091` 守侧五场景的 rig 法） | 调试接口 |
| R2 计数纯净 | 触发豁免后 `_perfect_hit_false` **值不变**（仍是误标原值）；`_perfect_forgiven` 单向 +1 | 单元：同上 rig，双值对拍断言 | 调试接口 |
| R2 判定正确 | `_perfect_hit_false=2 / _perfect_forgiven=1` → effective 1 → 不完美；`1/1` → 完美成立；`_perfect_hit_true=0` 时不成立 | 单元：真值表断言 | 调试接口 |
| R2 事件不吞 | 触发豁免的同一标错，`flag_missed` 仍被其它订阅方收到（以危险直觉·守的 AP 返还为观测点） | 冒烟：复用既有守侧场景 | 调试接口 |
| R2 事件不吞 | 触发豁免的同一标错，`seal_missed`（卡① 合回前名 `flag_missed`）仍被其它订阅方收到（以危险直觉·守的 AP 返还为观测点） | 冒烟：复用既有守侧场景 | 调试接口 |
| R3 配额锚 | `validate()` 通过；rare 合计 7；总量合计 102；rare 品种集＝{ap, rap, time_sand} | 单元：`adventure_table` validate 断言 | 调试接口 |
| R4 词表合法 | 新 kind 在 `EFFECT_KINDS`；数据行 do.kind 出域即加载致命（反例实证） | 单元：词表成员断言 | 调试接口 |
| R5 玩家面文案 | 新行 desc 不含「雷」；卡面显示正常 | 用户目检（登记 07） | 用户目检 |
@@ -198,8 +204,13 @@
## 10. 待裁点（2026-10-18 已裁毕；开工门＝U0）
- ✅ **D1 效果类型命名**＝`forgive_flag_miss`（用户裁「合动宾惯例的」）。
- ✅ **D1 效果类型命名**＝`forgive_flag_miss`（用户裁「合动宾惯例的」）→ **v1.1 换代为 `forgive_seal_miss`**（2026-10-18 用户补裁）。原裁定管的是命名形状（动词＋宾语，与 EFFECT_KINDS 现役 `add_ticket_rider`／`modify_ticket`／`damage_mult` 同族），不是 flag/seal 之争；卡① 要求 `game/` 内 `flag` 零命中，故新名取 seal 族。
- ✅ **D2 专长行规格**＝`rarity` 取 `rare`／`cap` 省略（承 twin_pick／geologist 惯例）／`desc`＝「本场首次封印落空，不计入完美封印判定」（用户确认，沿用 A 案）。
- ✅ **D3 roadmap 目标句措辞**＝维持现落地的「两卡串行：卡①代码术语刷新批＋卡②凭证件裁削批·代码侧」事实式表述（用户裁「没有问题」）。
**开工门**：用户发开工令（U0）。本卡不等冒记遗留两项（凭证归专长／资源＝转换源判据句）的裁定——那两项不阻塞本卡。
**开工门**：用户发开工令（U0）＋**两项前置门（v1.1 补列，2026-10-18 卡片冲突修订批核出）**——
1. **卡① 已合回 master**（本卡所有 flag_ 旧名要按 seal_ 形态复核，且 T3/T4 与卡① 同改三文件，见契约 8）；
2. **设计事实源已进 HEAD**：`design/gdd/systems/冒险循环/奇物.md` v3.18 当前只存在于主区未提交改动与未合并分支 `curio-prune-20261018`（`HEAD:奇物.md` 无 v3.18），worktree 从 HEAD 检出读不到本卡事实源；同时 06「凭证件裁削批·代码侧迁移」状态列须由「待写卡」推进为「文档设计已闭合（奇物.md v3.18）＋已写卡（本卡路径）＋已编迭代 31」。两处均属 `design/` 落笔，**归用户／文档批，本批禁改**。
本卡不等冒记遗留两项（凭证归专长／资源＝转换源判据句）的裁定——那两项不阻塞本卡。