diff --git a/reports/需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md b/reports/需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md new file mode 100644 index 00000000..3dde9833 --- /dev/null +++ b/reports/需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md @@ -0,0 +1,171 @@ +# 需求卡片:levelmap 装配越界与 BFS 缓存批(视图直读拼文案迁装配+布局重算缓存+绘制字体提取) + +- 版本:**v1.2**(v1.0→一轮「回炉」→v1.1 定案→二轮闭合复检「通过(附一应修)」:契约 3 论据补严→v1.2 定稿,复核记录见 §12) +- 来源:[待办清单](../待办清单.md)「结构审查未立项小件候审」条目之件②(2026-10-25 登记)——**2026-10-26 用户裁「全六件立项」**;本卡收件②独立成卡(结构改动量与审查单元独立)(唯一事实源:工程证据指认=审计报告 §三 其余小件第二条+本卡 §3 行号级实查+grilling 补查〔布局调用链与基线清单〕) +- 归属:`game/presentation/views/level_map_screen.gd`(三段)+ `game/presentation/main_adventure_flow.gd`(l1 拼装迁入——新装配函数)+ `game/tests/golden/`(level 屏基线新增一张+基线表登记) +- 排期:未编入(迭代批卡片;估时 ≈0.75–1 工作日) +- 开工门:U0+复核门过(§12);零待裁点 + +## 0. 前置依赖与并行性 + +- **第〇步核对(2026-10-26 写卡会话)**:来源条目=需求性工程条目(审计行号证据),用户点名立项——放行。 +- 与五小件卡(同条目拆分)同迭代分波:**同触 `main_adventure_flow.gd` 不同函数**(其 p2 confirm 段 :88 vs 本卡 l1 新装配函数)——无冲突;其余文件零交叠。 +- 与 2026-10-25 两批卡零交叠。 +- 呈现输出零变化是硬约束(l1–l3 是结构与性能面重构——**改前建 level 屏 golden 基线、改后对拍**承载,§7 T1 前置步)。 + +## 1. 目标与完成定义 + +**目标**:level_map_screen 三段审计指认落地——l1 视图直读 LevelRunner 拼展示文案迁装配层(架构 §1.3「读核心状态→拼展示文案应集中装配器」唯一越界者清偿);l2 布局 BFS 全量重算缓存(hover/绘制/命中路径不再逐次重算);l3 绘制路径重复取主题字体提取。呈现输出逐像素不变(基线对拍锚)。 + +**改动单元清单**(🔴 契约 1): + +| # | 单元(实查·定案) | 改法 | 依据 | +|---|---|---|---| +| l1 | `_refresh_status`(:326-353)视图直读拼文案——`_runner.level_row/gp/effective_max_hp/hero_hp/run_ledger.bonus/effective_atk/effective_ac` 在视图内拼九段展示文本 | 拼装逻辑迁入**组合根装配函数**:`main_adventure_flow.gd` 新增 `static func level_map_status_payload(runner) -> Dictionary`(产出九段成品:各 label/bonus 行文本+可见位布尔——键名 L1 白名单定);视图改 `func apply_status(payload: Dictionary)` 纯赋值;`_refresh_status` 现调用点(:277 视图内回调处)改为经组合根取 payload 再喂(刷新时点不变:打开本屏/兑付确认回执后);视图保留 `_runner` 引用供交互面(命中/提交)——只清「拼文案」越界 | 审计 ②「§1.3 唯一越界者」;架构分层纪律 | +| l2 | `_layout`(:520-534)全量求值=`_assign_layers`(入口 BFS 分层)+pos 构造;**四处调用点逐次全量重算**::378 `_candidate_at` 内(鼠标每次移动/命中检测)+:408 `press_candidate`+:446 绘制+:536 fit 面——审计指认的 hover 路径即 :362-387 gui_input → :378 → BFS | `_layout` 包缓存层:`var _layout_cache := {"nodes": [], "canvas_size": Vector2.ZERO, "pos": {}}`——命中条件=`nodes` **内容等价**(GDScript Array==逐元素比较——布局是 nodes+canvas 的纯函数,内容等价⇒布局必然等价)且 `canvas.size` 相等;图态换代(节点集内容变)或画布尺寸变即自然失效;四处调用点零改动(缓存收在 `_layout` 内) | 审计 ②;性能债(防扩图后成实感瓶颈);纯函数缓存正确性自证 | +| l3 | 绘制路径字体重复取::502 已是循环内局部变量(需提升到函数首)、:507/:515 两处 `get_theme_default_font()` 内联调用 | 绘制函数首取一次 `var font := get_theme_default_font()`,三处引用改局部 | 审计 ②;零语义差 | +| l4 | golden 基线无 level 屏图(现役基线仅 board_L1/L2/L3+menu_boot 四张——grilling 实查)——逐像素锚缺载体 | **T1 前置步**:改前经 shot_probe 关卡画面帧(`_snap("level")` :138)建 `game/tests/golden/level_map.png` 基线+golden/README 基线表登记(按 render_gate 既有重制口径);改后对拍 changed=0.00% | 撤销证明口径(golden 抓内容观感类);render_gate.sh 基线纪律 | + +**完成定义**: + +1. l4 基线建立在案;l1–l3 落地;呈现逐像素不变(level_map.png 对拍 changed=0.00%+level_map 现役探针绿); +2. l2 缓存生效判据过(wr2);全套闸按本批改动域选档全绿; +3. 撤销证明一条(wr2);三份产出物写齐(T2)。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 工程证据指认=审计报告 §三 其余小件第二条+本卡 §3 实查 | 三段清单 | +| D2 | [architecture](../design/engineering/architecture/architecture.md) §1.3 分层纪律(视图不拼核心态文案) | l1 依据 | +| D3 | [code-conventions](../design/engineering/code-conventions.md) §1(结构与复用) | l2/l3 依据 | +| D4 | [render_gate](../tools/render_gate.sh) 基线纪律(预期面视觉变化=显式重制基线;此处为改前建新基线) | l4 依据 | + +## 3. 现状事实(2026-10-26 写卡会话实查+grilling 补查于 master eb04313b;开工日 T0 复核行号) + +| # | 事实 | 出处 | +|---|---|---| +| L1 | `_refresh_status`(:326-353)视图直读:逐行读 `_runner.level_row/gp/effective_max_hp/hero_hp/run_ledger.bonus/effective_atk/effective_ac` 拼九段文案(atk/ac 加成角标、bonus parts、可见位判据);:277 视图内节点事件回调处自调;注释自认「命令式纪律——组合根打开本屏/兑付确认回执后重查」 | `game/presentation/views/level_map_screen.gd:277/326-353` | +| L2 | `_layout`(:520-534)=`_assign_layers`(入口 BFS 分层,:550 注释「layer=入口 BFS 深度;layout/fit 共享件」)+pos 构造——**纯函数于 (nodes, canvas)**;调用点四处::378(`_candidate_at` 内——gui_input :362-387 hover 每次移动经此)+:408(press_candidate)+:446(绘制)+:536(fit 面)——审计「每次鼠标移动全图 BFS 重算」传导链=hover→_candidate_at→_layout→_assign_layers(grilling 定案) | `game/presentation/views/level_map_screen.gd:362-387/378/408/446/520-536/550` | +| L3 | 绘制路径字体::502 循环内局部变量(作用域限单次迭代)、:507/:515 两处内联调用——三处逐节点/逐帧重复求值 | `game/presentation/views/level_map_screen.gd:502-529` | +| L4 | golden 基线现役四张=board_L1/L2/L3+menu_boot——**无 level 屏图**;shot_probe 有关卡画面帧口 `_snap("level")`(:138);level_map 探针面=screen_flow_probe(含屏切换)/现役套件 T0 定名 | `game/tests/golden/`;`game/probe/shot_probe.gd:138`;`game/probe/screen_flow_probe.gd` | + +## 4. 设计契约(红线,违反 = L3 停机呈报) + +🔴 **契约 1 · 呈现逐像素不变**:l1–l3 落地后 level 屏绘制输出与改前逐像素一致(l4 基线对拍 changed=0.00%)——文案成品、布局坐标、绘制序零变化;l4 基线必须在 l1–l3 改动**之前**建立(时点铁序)。 + +🔴 **契约 2 · 改动面封闭**:只动三段与其迁入点;交互面(命中/提交/press_candidate 探针路径)语义零变化;`_runner` 引用保留(只清拼文案越界)。 + +🔴 **契约 3 · 缓存正确性**:l2 缓存键=(nodes 内容等价, canvas.size);论据链(二轮补严):`_layout` 除 (nodes, canvas) 外另读成员 `_content_size`——其值由 `_fit_canvas`(:290-305)在 open_choices(:276)路径求值、初值 620×240 与下限 620×256 不等,故 `_content_size`=f(nodes) 的派生态——键经该派生链**间接**覆盖;T0 须核对 `_fit_canvas` 求值时点在四调用点首触缓存之前(否则首缓存可能锚在陈旧 _content_size 上——列 T0 必核项+wr2-b 换代用例检点);选路图换代必自然失效;禁另引代次计数等第二失效机制(双键漂移风险)。 + +🔴 **契约 4 · 零行为申报**:本卡无玩家可见行为改动(性能与结构面)——wr1 对拍是验收主锚。 + +🔴 **契约 5 · 禁为机检文本保留无效成员**(req-card 第 13 条,本卡属等价重构类):禁为回避基线建立/对拍而保留旧求值路径或旧拼装(l2/l1 歧路拦截);机检键与本卡契约互斥时停卡呈报。 + +## 5. 范围边界 + +**做**:l1–l4;golden 对拍+探针回归;撤销证明;产出物。 + +**不做**: +- 另五小件(独立卡); +- level_map 屏交互/视觉改版(布局算法/样式零触碰——缓存不改分层结果); +- `_candidate_at` 命中算法重写(线性扫保留——审计未点其本身); +- board 基线四张(既有——本卡不动)。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `待办清单.md` | 来源条目拆注(件②归本卡)+状态推进 | 反哺点 · 列清单(①:拆注核对) | +| [architecture](../design/engineering/architecture/architecture.md) §1.3 | 「唯一越界者」清偿后该条纪律实况注记(预期零改动——纪律文本不变,T0 核) | 反哺点 · 列清单(②:预期零改动注记) | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/presentation/views/level_map_screen.gd` | l2 缓存+l3 字体提取+l1 视图侧纯赋值改写(复用既有·修改) | 非行为改动(呈现零变化)→ wr1 | +| `game/presentation/main_adventure_flow.gd` | l1 拼装迁入(**新增**·装配函数 `level_map_status_payload`) | 非行为改动 → wr1 | +| `game/tests/golden/level_map.png`+README 基线表 | l4 改前建基线(**新增**·基线件) | 非行为改动(基线面)→ wr1 | + +(新增件两件:装配函数与基线图——预检节答「为什么不能复用」。) + +### 接口块 + +- **l1 签名**:`main_adventure_flow.gd` `static func level_map_status_payload(runner: LevelRunner) -> Dictionary`(键:level_label/gp_text/hp_text/hp_bar_redraw/attr_text/bonus_text/bonus_row_visible——九段成品,键名 L1 白名单内定形);视图 `func apply_status(payload: Dictionary) -> void` 纯赋值;:277 调用点改经组合根喂入(组合根持视图引用的既有通道——T0 核 main.gd:83 句柄链)。 +- **l2 缓存**:`_layout` 首部命中判定(`_layout_cache.nodes == nodes and _layout_cache.canvas_size == canvas.size` → 返回缓存 pos;否则全量求值后写缓存)。注意 GDScript Array==为内容比较(迭代 37 d11 语义)——恰合纯函数键需求。 +- **l4 基线建立**:实现批内跑 shot_probe 取关卡画面帧 → `game/tests/golden/level_map.png`+golden/README 基线表登记一行(render_gate 既有口径)。 +- **wr1 对拍**:改后 render 面跑批 level_map.png changed=0.00%。 +- **wr2 判据**:同 nodes 两次 `_layout` 调用第二次命中缓存(命中读数形态:探针/单测可读的计数器或时间差——L1 白名单定形);另加「换代失效」用例(节点集内容变 → 新坐标≠缓存旧值)。 +- **最窄闸**:screen_flow_probe 直跑+golden 对拍;全套闸按本批改动域选档。 + +### 落位与可复用性预检 + +- **装配函数为什么新增**:装配面(main_adventure_flow)无现成同职责函数(grep 实查——level_map 状态拼装唯一直读点即视图内);视图拼装迁出必须有一个装配侧承接件——函数级新增、文件级零新增。 +- **基线图为什么新增**:golden 现役四张无 level 屏(L4)——逐像素锚的载体只能新建(render_gate 既有基线机制复用,仅加一张)。 +- **复用面**:分层/fit 共享件原样复用(缓存包外层);`_snap("level")` 帧口现成。 +- **唯一面**:布局求值唯一入口经缓存层;文案拼装唯一落点装配函数(视图侧 grep `_runner.level_row|effective_atk|run_ledger.bonus` 在视图内拼装语境清零——交互读除外)。 +- **分层**:视图↔装配器职责归位(§1.3);core 零触碰。 + +### T0 事实坐实(≈0.1d) + +- [ ] 复核 L1–L4(重点::277 调用点上下文与组合根喂入通道、L4 探针定名、基线建立流程核对、**契约 3 论据链核对——_fit_canvas 求值时点先于四调用点首触缓存**)。可核查结果:三段定位表+喂入通道判据+_content_size 派生链记录进实现报告素材。 + +### T1 基线建立+三段实装(≈0.5–0.65d) + +- [ ] **前置步(时点铁序)**:l4 基线建立(shot_probe level 帧 → level_map.png+基线表登记)。可核查结果:基线图在案、render 面认卡。 +- [ ] 实装 l3(字体提取)+l2(缓存层)。可核查结果:wr2 命中判据与换代失效用例双绿;对拍 0.00%。 +- [ ] 实装 l1(装配函数+视图纯赋值+喂入通道)。可核查结果:wr1 对拍 0.00%;探针绿;视图侧拼装 grep 清零。 +- [ ] 验证步骤:全套闸按域选档跑一次全绿。 + +### T2 撤销证明+产出物落位卡(≈0.15d,末卡) + +- [ ] 撤销证明一条:回退 l2 缓存 hunk(还原逐次全量)→ wr2 命中判据红(第二次求值未命中)→ 还原复绿。记录进实现报告。 +- [ ] 写齐三份产出物(实现报告〔三段核对表+对拍读数+缓存命中读数+基线建立记录+实机目检总清单——选路屏状态栏/悬停高亮目检一项(登记不阻塞)〕/代拍板追认单/反哺点清单〔§6 逐条落点〕)。 +- [ ] 合并前置:独立验收审计(§8.3)逐行「通过」。 + +**估时合计 ≈0.75–1d**。编排注记:呈现零变化锚在改前基线——**本卡必须与其后任何触 level 屏的批次排先后**(基线时序敏感);与五小件卡同波无冲突(不同函数/文件面)。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 三段重构呈现零变化 | l1 迁装+l2 缓存+l3 字体 | level_map.png 对拍 changed=0.00%〔wr1〕(l4 改前基线)+screen_flow_probe 绿 | 渲染+探针 | render 面真实跑批(level_map 图)+探针真实选路路径 | 等价重构申报:对拍差异非零即红(呈现面以基线为断言载体) | +| wr2 缓存生效与失效正确 | l2 缓存层 | 命中读数〔wr2-a〕+换代失效用例〔wr2-b〕 | 单元/探针 | `_layout` 真实调用路径(hover→_candidate_at 链) | 回退 l2 hunk → wr2-a 红(T2) | +| wr3 产出物 | T2 三份 | 件核〔wr3〕 | — | — | 缺项红 | + +### 8.2 测试削弱申报 + +零(既有断言零改动;新增 wr2 判据两条;wr1 以改前基线对拍承载——golden 逐像素属撤销证明口径的强判据层)。 + +### 8.3 独立验收审计 + +入口=未参与实现的会话或子代理;报告落 `reports/iter-验收审计-<日期>.md`;抽查重点=契约 1(基线建立时点先于改动+对拍读数在案)、契约 3(缓存键设计核对+换代失效用例)、l1 视图侧拼装 grep 清零、基线表登记在案。未过不得合并。 + +## 9. 异常分级 + +- **L1(自救)**:payload 键名;缓存实现细节;wr2 读数形态。 +- **L2(记录继续)**:行号漂移;探针定名变化。 +- **L3(停机呈报)**:对拍非零(契约 1 破——重构引入呈现差);换代后选路图陈旧(契约 3 破——缓存键失效面漏);组合根喂入通道不存在现成形态(需改装配架构——超出预判,呈报后裁);shot_probe level 帧口径与 render 面不兼容(基线建不成)。 + +## 10. 代拍板白名单(超清单必呈报) + +1. payload 键名与 apply_status 形态。 +2. 缓存命中读数实现形态。 +3. wr 断言挂点与消息文本。 +4. 提交切分与 worktree 分支命名。 + +## 11. 待裁点 + +**零待裁点,开工门=U0。** 灰色推导两处(呈报可否决,随 T2 反哺点):①`_candidate_at` 线性扫保留不重写——审计未指认为缺陷(候选 ≤4 无瓶颈),缓存解决的是全图布局重复求值;②缓存键用「内容等价」而非代次计数——布局纯函数性质使内容等价即充分条件,代次计数反引入双源漂移风险。 + +## 12. 自审六查与 grilling 复核记录 + +**自审六查(2026-10-26 写卡会话,v1.0)**:①规格覆盖;②步骤扫描;③类型一致性;④审查焦点——对拍主锚、失效键、装配面预判;⑤篇幅比例;⑥落位预检。 + +**grilling 一轮复核记录(2026-10-26,独立子代理对抗复核,判「回炉」两阻断)**:①阻断一=设计本体留白(l2 失效键「T0 定」、L2 传导链「T0 钉」、l1 迁入面「T0 定位」三项属设计核心非事实复核——违「卡片设计闭合、实现段零裁断」)——v1.1 定案:传导链=hover→_candidate_at(:378)→_layout→_assign_layers BFS+四调用点清单(L2);缓存键=(nodes 内容等价, canvas.size)(契约 3+灰色推导②);迁入面=main_adventure_flow 新函数 `level_map_status_payload`(接口块签名定案);②阻断二=wr1 主锚不存在(golden 现役四张无 level 图、「render 面既有口径」系预设)——v1.1 立 l4 单元:改前经 shot_probe `_snap("level")` 建基线+基线表登记+T1 前置步时点铁序(契约 1);③应修=缺 req-card 第 13 条——立契约 5;④建议=L3 描述不准(:502 已是循环内局部需提升、:507/:515 真内联)——订正;§0「零交叠」不可断言(迁入面未定)——改「同文件不同函数」实况。交叉项:与 10-25 卡 C 的基线时序提醒方向确认(该卡重制 menu_boot 与 level 屏无关,本卡基线自建自足)。 + +**二轮闭合复检(2026-10-26,判「通过(附一应修))**:两阻断核闭合(四调用点 :378/:408/:446/:536 实查全中、缓存键/签名定案、l4 时点铁序+golden 现役四张无 level 图实证);应修=契约 3 论据补严(`_layout` 另读 `_content_size` 成员——经 `_fit_canvas` :290-305 派生于 nodes、键间接覆盖;T0 增「_fit_canvas 求值时点先于首触缓存」必核项);复核实证=l2 返回引用安全(全文件仅 :527 写 pos、四调用点纯读)、nodes 元素 Dictionary 的 Array== 内容比较成立(原地变异亦击穿缓存——键选型正确)。 diff --git a/reports/需求卡片-令牌配额口径清扫批-2026-10-26.md b/reports/需求卡片-令牌配额口径清扫批-2026-10-26.md new file mode 100644 index 00000000..af8e6250 --- /dev/null +++ b/reports/需求卡片-令牌配额口径清扫批-2026-10-26.md @@ -0,0 +1,165 @@ +# 需求卡片:令牌配额口径清扫批(schema/tres 头注口径统一+game 面旧档名清扫) + +- 版本:**v1.2**(v1.0→一轮「回炉」→v1.1→二轮闭合复检「回炉(窄修)」:tres:37 漏枚举+「罕见」另三处待裁定→v1.2 折入定稿,复核记录见 §12) +- 来源:[待办清单](../待办清单.md)「adventure 令牌配额 schema 锚与 tres 现行值不一致+game 面旧档名残留」条目(2026-10-26 登记,状态=待写卡)(唯一事实源:工程证据指认=条目实况+本卡 §3 行号级实查+grilling 补查——**条目核心论断经实查订正**:schema 常量与 tres 实际一致、校验活着且绿;本卡范围=旧口径表述清扫+订正结论落档) +- 归属:`game/data/schemas/adventure_table.gd`(头注口径四处)+ `game/data/tables/adventure.tres`(头注旧口径四处)+ `game/tests/golden/README.md`(旧名一句)+ `game/tests/unit/core/adventure_feats_test.gd`(断言标签文本)+ `game/tests/验证集清单.md`(清单行同步) +- 排期:未编入(迭代批卡片;估时 ≈0.3 工作日) +- 开工门:U0+复核门过(§12);零待裁点 + +## 0. 前置依赖与并行性 + +- **第〇步核对(2026-10-26 写卡会话)**:来源条目=需求性工程条目(证据带 file:line),跳过设计线放行;条目状态=待写卡。 +- 与迭代 37 零文件交叠;与 2026-10-25/26 各批卡零交叠。 +- **条目论断订正**(§3 B5 出结论):「schema 锚与 tres 现行值不一致」不成立——rap_rare/time_sand_rare 的 2/2 是 schema @export 默认值(tres 只显式化 ap_rare=3),逐 kind 求和恰等于常量 7;`validate()` 结构锚校验活着、guard_test 断言绿。真问题=头注旧口径表述残留(schema 四处+tres 四处)+两处旧档名——零数值改动、零行为断言变化(断言条件不动、只改标签文本)。 + +## 1. 目标与完成定义 + +**目标**:令牌配额的全部旧口径表述(rare=3 直映射时代数字+旧三级档名)从 game 面清出,四处头注/两处测试文本与现行唯一事实源(tres 实值+TIER_QUOTAS=70/25/7/0、deck_total 实算 102)对齐;条目登记时的失实论断随卡订正落档。 + +**改动单元清单**(🔴 契约 1): + +| # | 单元(实查·grilling 补查全枚举) | 改法 | 依据 | +|---|---|---|---| +| q1 | `adventure_table.gd` 头注旧口径三处::32「四级直映射 70/25/3/0」(:32-34 整段与现行「稀有 7/总量 102」句并排混写)+:49「70/25/3 零偏离」+:58「总量 98 锚不变」(heal_excellent 行注——三级时代 98) | 三处按现行口径改写(70/25/7/0 与 102;:32-34 段合并为单口径现行句,沿革归 git log);**数值零触碰**(TIER_QUOTAS :37 与 @export 默认 :60-62 逐字不动) | code-conventions 文件头注释纪律;数值单一事实源 | +| q2 | `adventure_table.gd:202` `deck_total()` 头注「结构锚——T2 四级 98 + T4 凭证投放 6 = 104:70+25/9+0」——rare=3 时代口径(70+25+3+0=98)遗留且凭证错算入 deck 总量;实算=102 | 头注按实算改写(deck_total=102=70/25/7/0;凭证投放不走 curio_quota、不进 deck_total);函数体零触碰 | 同上;实算核对 T0 复核 | +| q3 | `adventure.tres` 头注旧口径五处::36「70/25/3/0=98 张」+:37「普通 70/优秀 25/稀有 3/传说 0…旧 70/25/3 直映射改名承袭」(含「稀有 3」旧值与「70/25/3」沿革句——二轮补枚举)+:41「普通 70/稀有 25/罕见 3 = 98 张」(旧三级档名活句)+:45「罕见〔AP 3〕」构成句(:44-45 档位构成段新旧名混写)+:53「70/25/5」 | 五处按现行口径与新四级名改写(:37 改「普通 70/优秀 25/稀有 7/传说 0=头奖位留空」方向、删沿革句——措辞 L1);tres 数值行零触碰 | 档名四级映射(01-核心循环 v1.5);旧名清扫=术语表口径 | +| q4 | 旧档名两处:`golden/README.md:26`「魔法道具 HUD」+`adventure_feats_test.gd:399` 断言标签「池耗后候选恒 ≥2(稀有/罕见档余量……)」(验证集清单 :875 序号 505 冻结同文本;条件表达式 `(draw as Array).size() >= 2` 与档名无关) | README 句改「秘宝(时名魔法道具)」方向;断言标签改新档名(**条件表达式零触碰**)+验证集清单 :875 行同步+`python tools/extract_checks.py --diff` 对账零差异 | 术语表退役词(「魔法道具」2026-09-15/「罕见」2026-09-14);清单同步义务(test-conventions §8.3) | + +**完成定义**: + +1. q1–q4 落地;三条 grep 判据过(§8 wr1)+清单对账零差异; +2. 数值与断言条件零变化(TIER_QUOTAS/三处 @export 默认/tres 数值行/断言表达式逐字不变——wr1 读数对拍);全套闸按本批改动域选档全绿; +3. 撤销证明一条(wr1);三份产出物写齐(T1)——含条目论断订正结论落档。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 工程证据指认=条目实况+本卡 §3 实查(论断订正) | 清扫范围 | +| D2 | [code-conventions](../design/engineering/code-conventions.md) §1(文件头注释纪律:只写现行、禁变更叙事) | q1/q2/q3 改写口径 | +| D3 | [术语表](../design/gdd/术语表.md) 档名与退役词口径 | q3/q4 旧名清扫依据 | +| D4 | [test-conventions](../design/engineering/test-conventions.md) §8.3 | 断言标签改动须同步验证集清单 | + +## 3. 现状事实(2026-10-26 写卡会话实查+grilling 补查于 master eb04313b;开工日 T0 复核行号) + +| # | 事实 | 出处 | +|---|---|---| +| B1 | `TIER_QUOTAS := {"common":70,"excellent":25,"rare":7,"legendary":0}`(:37);rare 实投=ap 3(:60 默认)+rap 2(:61)+时沙 2(:62)=7——常量与逐 kind 求和一致;tres 只显式化 `curio_quota_ap_rare = 3`(:19,与默认同值) | `game/data/schemas/adventure_table.gd:37/60-62`;`game/data/tables/adventure.tres:19` | +| B2 | 校验活着且绿:`validate()` :227-231 按 TIER_QUOTAS 逐档核对 `tier_total`(以载入值求和——含 tres 未显式化的默认值);`table_structure_guard_test.gd:99-100` 断言全绿——条目「不一致」论断不成立的实证(grilling 复核确认求和链闭合) | `game/data/schemas/adventure_table.gd:210-233`;`game/tests/unit/data_config/table_structure_guard_test.gd:99-100` | +| B3 | schema 头注旧口径三处+deck_total 旧口径一处::32「四级直映射 70/25/3/0」/:49「70/25/3 零偏离」/:58「总量 98 锚不变」/:202「T2 四级 98+T4 凭证投放 6=104:70+25+9+0」(deck_total 实算 102) | `game/data/schemas/adventure_table.gd:32/49/58/202` | +| B4b | **「罕见」三处合法保留·显式豁免**(二轮裁定):schema:25-26 档名映射注(「罕见→稀有」——名映射对照载体,删则转换关系丢失);schema:92-93 与 curio_deck.gd:129-130「罕见只在概率不在价格」=奇物四口径契约④**原名引述**(改写即脱离契约原名断链)——grep② 文件面不含它们、非残留 | `game/data/schemas/adventure_table.gd:25-26/92-93`;`game/core/curio_deck.gd:129-130` | +| B4 | tres 头注旧口径五处::36「70/25/3/0=98 张」/:37「稀有 3…旧 70/25/3 直映射」沿革句(二轮 grep① 实跑命中补枚举)/:41「普通 70/稀有 25/罕见 3 = 98 张」/:45「罕见〔AP 3〕」(:44-45 档位构成段新旧名混写)/:53「70/25/5」 | `game/data/tables/adventure.tres:36/37/41/44-45/53` | +| B5 | 旧名残留两处:golden/README.md:26「魔法道具 HUD」(成因记录句内);`adventure_feats_test.gd:399` 断言标签「(稀有/罕见档余量……)」(v1.0 误记 smoke_boot.gd:399——smoke_boot 全文仅 77 行,grilling 订正;验证集清单 :875 序号 505 源址列=399 即此件) | `game/tests/golden/README.md:26`;`game/tests/unit/core/adventure_feats_test.gd:399`;`game/tests/验证集清单.md:875` | +| B6 | 「魔法道具」全仓 game/ 面命中仅 README:26 一处(grep 实查) | grep 实查 | + +## 4. 设计契约(红线,违反 = L3 停机呈报) + +🔴 **契约 1 · 数值与断言条件零变化**:TIER_QUOTAS、三处 @export 默认值、tres 全部数值行、adventure_feats_test:399 的条件表达式——逐字不动;只改注释/头注/README/标签文本与清单行。 + +🔴 **契约 2 · 清单跟上**:q4 断言标签改动后 `tools/extract_checks.py --diff` 对账零差异;禁为免对账保留旧标签。 + +🔴 **契约 3 · 头注只写现行+清扫不漏点**:q1–q3 改写后 schema/tres 头注零旧口径数字与旧档名误用(**§3 B3/B4/B5 清单逐处全清——清单外新发现即 L3 停机呈报**,禁实现段自行扩点;B4b 豁免三处除外);现行口径全库唯一(与 B1 实投一致)。 + +🔴 **契约 4 · 禁为机检文本保留无效成员**(req-card 第 13 条):禁为避免改断言标签/清单行而保留旧档名文本;机检键(清单冻结文本)与契约 1 冲突时停卡呈报。 + +## 5. 范围边界 + +**做**:q1–q4(B3/B4/B5 清单全部十一处:schema 四+tres 五+旧名两);grep 验证;对账;撤销证明;产出物(含论断订正结论)。 + +**不做**: +- TIER_QUOTAS 或配额任何数值调整(provisional 现状不动——归未来数值标定窗口); +- node-reward GDD 文档(v2.9 已按 tres 现行值对齐——零反哺预期,T0 核对注记); +- design/ 面旧词(已由 termsweep-20261026 批清扫);**B4b 三处「罕见」豁免**(档名映射注+契约④原名引述——非误用;GDD 侧若将来改契名,随批同步)。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `待办清单.md` | 来源条目状态推进+论断订正注记(实现报告落档) | 反哺点 · 列清单(①:状态核对注记) | +| [node-reward](../design/gdd/ux/node-reward.md) v2.9 | 文档面已按 tres 现行值对齐——T0 核其与 B1 无冲突后零改动注记 | 反哺点 · 列清单(②:预期零改动注记) | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/data/schemas/adventure_table.gd` | q1(:32/:49/:58)+q2(:202)头注口径(复用既有·修改) | 非行为改动(注释面)→ wr1 | +| `game/data/tables/adventure.tres` | q3(:36/:41/:44-45/:53)头注旧口径(复用既有·修改) | 非行为改动(注释面)→ wr1 | +| `game/tests/golden/README.md` | q4a 旧名一句(复用既有·修改) | 非行为改动(说明文本) | +| `game/tests/unit/core/adventure_feats_test.gd` | q4b 断言标签文本(复用既有·改标签) | 非行为改动(标签文本;条件零触碰)→ wr1 | +| `game/tests/验证集清单.md` | q4b 清单行同步(复用既有·同步) | 非行为改动(清单面)→ wr1 | + +(零新增文件、零新增函数。) + +### 接口块 + +- **wr1 grep 判据**(三条,各零输出):①`grep -n "70/25/3\|70/25/5\|70+25+9\|总量 98" game/data/schemas/adventure_table.gd game/data/tables/adventure.tres`;②`grep -n "罕见" game/data/tables/adventure.tres game/tests/unit/core/adventure_feats_test.gd`;③`grep -n "魔法道具" game/tests/golden/README.md`。 +- **q4 对账命令**:`python tools/extract_checks.py --diff` → 零差异。 +- **数值不变判据**:改前改后 `tier_total` 四档读数(70/25/7/0)与 `deck_total()`(102)对拍一致(table_structure_guard_test 直跑绿即护栏)。 +- **最窄闸**:table_structure_guard_test+adventure_feats_test 单件直跑+对账;全套闸按本批改动域选档。 + +### 落位与可复用性预检 + +- **零新增件**:十处全在既有文件原位改写;清单同步复用 extract_checks 既有工具。 +- **复用面**:现行口径唯一事实源=TIER_QUOTAS 常量+tres 实值(B1)——头注改写只指认它,不引第三处数字。 +- **唯一面**:头注改写后全库配额数字表述唯一(schema/tres/README/清单同口径);「罕见」「魔法道具」在**判据面**(grep②③ 文件集)清零——B4b 豁免三处为合法载体非残留。 +- **分层**:纯文本面;数值/断言条件零触碰。 + +### T0 事实坐实(≈0.05d) + +- [ ] 复核 B1–B6(重点:B3/B4 十处逐行确认无第十一处、B2 求和链复核记录);确认措辞方向。可核查结果:口径核对表进实现报告素材。 + +### T1 清扫实装+对账(≈0.2d) + +- [ ] 实装 q1–q4(十处)。可核查结果:wr1 三条 grep 零输出;对账零差异;两测试单件直跑绿。 +- [ ] 验证步骤:全套闸按域选档跑一次全绿。 + +### T2 撤销证明+产出物落位卡(≈0.05d,末卡) + +- [ ] 撤销证明一条:回退 q3 的 :41 hunk(旧名活句还原)→ wr1 grep② 命中即红 → 还原复绿。记录进实现报告。 +- [ ] 写齐三份产出物(实现报告〔十处口径核对表+论断订正结论+实机目检总清单——零玩家可感项写明理由〕/代拍板追认单/反哺点清单〔§6 逐条落点〕)。 +- [ ] 合并前置:独立验收审计(§8.3)逐行「通过」。 + +**估时合计 ≈0.3d**。编排注记:微件卡;断言标签改动触闸面套件文本——与探针/冒烟改动类他卡同波无冲突。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 十处口径与旧名清扫 | q1–q4 文本改写 | 三条 grep 零输出〔wr1〕+对账零差异+四档读数对拍(70/25/7/0、102) | 静态文本+单元护栏 | grep/extract_checks 真实跑批+两测试单件直跑 | 回退 :41 hunk → grep② 命中即红(T2) | +| wr2 产出物 | T2 三份 | 件核〔wr2〕 | — | — | 缺项红 | + +### 8.2 测试削弱申报 + +零(断言条件零改动;标签文本换代属 q4 申报内改动,清单同步)。 + +### 8.3 独立验收审计 + +入口=未参与实现的会话或子代理;报告落 `reports/iter-验收审计-<日期>.md`;抽查重点=契约 1(数值与条件逐字核对)、契约 3(§3 B3/B4/B5 清单十一处全清、B4b 豁免三处未被顺手改)、对账记录、头注零沿革叙事。未过不得合并。 + +## 9. 异常分级 + +- **L1(自救)**:十处具体措辞。 +- **L2(记录继续)**:行号漂移。 +- **L3(停机呈报)**:T0 发现 deck_total 实算与 102 不符(B3 推导失实——口径问题升数值问题另裁);发现 B3/B4/B5 之外第十一处旧口径/旧名残留;改写被迫触数值行(超契约 1)。 + +## 10. 代拍板白名单(超清单必呈报) + +1. 十处具体措辞(语义=现行口径、旧名清除)。 +2. q4b 新标签文本。 +3. 提交切分与 worktree 分支命名。 + +## 11. 待裁点 + +**零待裁点,开工门=U0。** 灰色推导一处(呈报可否决,随 T2 反哺点):条目「不一致」论断按 §0/§3 订正为「表述口径问题、数值一致」——依据=B1/B2 实查+grilling 求和链复核;若用户坚持将 rap/时沙配额也显式化写进 tres(数值面文件改写),超出本卡文本清扫范围,须另立批。 + +## 12. 自审六查与 grilling 复核记录 + +**自审六查(2026-10-26 写卡会话,v1.0)**:①规格覆盖;②步骤扫描;③类型一致性;④审查焦点——数值零触碰护栏、清单跟上、论断订正落档;⑤篇幅比例;⑥落位预检。 + +**grilling 一轮复核记录(2026-10-26,独立子代理对抗复核,判「回炉」两阻断)**:①阻断一=q4b 断言文件张冠李戴(v1.0 误写 smoke_boot.gd:399——该文件全文 77 行;实址 `adventure_feats_test.gd:399`,清单 :875 序号 505 源址列即证)——v1.1 折入:归属/文件结构图/接口块 grep② 三处订正;②阻断二=清扫枚举不完备(v1.0 只列 :41 一处——tres 实有 :36/:44-45/:53、schema 实有 :49/:58,按 v1.0 判据开工即 L3)——v1.1 折入:q1/q3 范围扩为 schema 三处+tres 四处(B3/B4 全枚举)+grep① 口径串判据重设+契约 3「十处全清」;③应修=deck_total 头注 :202 行号订正——已并入 q2/B3;④复核确认=论断订正成立(求和链闭合、guard_test 绿、deck_total 实算 102)、§11 显式化出口处理正确。 + +**grilling 二轮闭合复检记录(2026-10-26,独立子代理,判「回炉(窄修)」)**:一轮两阻断核闭合;窄修两处+新裂缝——①tres:37 漏枚举(「稀有 3…旧 70/25/3 直映射」沿革句含旧值——grep① 实跑命中,v1.0/v1.1 均未列)→v1.2 入 q3/B4(第五处);②「罕见」game 面另三处未裁定(schema:25-26 映射注/schema:92-93+curio_deck:129-130 契约④原名引述)→v1.2 裁定 B4b 合法保留显式豁免(§5/§7 唯一口径改「判据面清零」);③B3 引文笔误(70+25+9+0)订正;§8.3/契约 3 口径统一为「§3 清单逐处」。 diff --git a/reports/需求卡片-结构小件定点修批-2026-10-26.md b/reports/需求卡片-结构小件定点修批-2026-10-26.md new file mode 100644 index 00000000..95495d0f --- /dev/null +++ b/reports/需求卡片-结构小件定点修批-2026-10-26.md @@ -0,0 +1,186 @@ +# 需求卡片:结构小件定点修批(审计 §三 其余小件五件:死变量/confirm 收口/空判/常驻 flush/fatal 违约回调) + +- 版本:**v1.2**(v1.0→一轮「通过(附四应修+一建议)」→v1.1→二轮闭合复检「通过(附三应修)」→v1.2 定稿,复核记录见 §12) +- 来源:[待办清单](../待办清单.md)「结构审查未立项小件候审」条目(2026-10-25 登记,状态=待裁决)——**2026-10-26 用户裁「全六件立项」**;本卡收五件(①③④⑤⑥,审计原编号),件②(level_map 越界/BFS)独立成卡(结构改动量独立、审查单元分立)(唯一事实源:工程证据指认=审计报告 [§三 其余小件](审计-game代码结构审查-2026-10-24.md) §90-95 逐件行号+本卡 §3 行号级实查〔迭代 37 拆件后行号重定位〕) +- 归属:`game/presentation/main_overlay_flow.gd`+`game/presentation/main.gd`+`game/presentation/row_pacer.gd`(消费一行)+`game/core/board_generator.gd`+`game/core/reward_economy.gd`+`game/core/rng_service.gd`+`game/core/battle_orchestrator.gd`(组装接线两行)+测试面(探针回归+新断言) +- 排期:未编入(迭代批卡片;估时 ≈0.75 工作日) +- 开工门:U0+复核门过(§12);零待裁点 + +## 0. 前置依赖与并行性 + +- **第〇步核对(2026-10-26 写卡会话)**:来源条目=需求性工程条目(审计行号证据),用户 2026-10-26 点名全六件立项——放行。 +- 审计行号基线=2026-10-24(迭代 37 拆件前);本卡 §3 已按现行 master(eb04313b)重定位(①main→main_overlay_flow 拆件迁移、③行号漂移),T0 复核。 +- 与 2026-10-25 两批卡零文件交叠(卡 A 触 battle_orchestrator 的发射点/头注/校验段——本卡 p5 只动组装点 :278/:283 两行接线与两协作件 _fatal,不同面;rng_service p6 与其零叠)。同波无冲突。 +- p5 触结算域(core 件 _fatal 形态)——parity 触面按 MC 纪律:零数值改动=零 MC(_fatal 是违约路径,合法路径零触碰)。 + +## 1. 目标与完成定义 + +**目标**:五件审计定点小件落地——①_ sync_status_entry 死变量与重复四句清除;③settle_batch 两入口显式 null 防护;④row_pacer 会话更替机制化 flush;⑤两 core 协作件 _fatal 的 release 软回退补真中止通道(经 orchestrator 既有封印传导);⑥rng_service open_stream 未知标签补 return+可测违约回调。合法路径行为逐位不变(p2 confirm 收口是唯一行为改动=锁域归位,对照表专行)。 + +**改动单元清单**(🔴 契约 1): + +| # | 单元(实查·现行行号) | 改法 | 依据 | +|---|---|---|---| +| p1 | `main_overlay_flow.gd:107-124` `_sync_status_entry`::111 `var battle_live` 赋值后零消费(死变量)+首组四句 :112-116(:114 置灰注释行夹中)与重复四句 :119-122 逐字相同(:117-118「重复语句在案」注释两句自认) | 删 :111 死变量行+删 :117-122(自认注释两句+重复四句);保留首组与 :123-124 调试角标注释段(非重复组——grilling 订正 v1.0 误圈) | 审计 ①;死代码与重复句清除 | +| p2 | confirm 旁路单口违约:`main_overlay_flow.gd:88` `root.confirm_dialog.open(...)` 与 `main.gd:312/:321` `confirm_dialog.close()` 直开直关——绕过 `_open_modal/_close_modal`(main.gd:282-286 → ModalFlow.open/close 挂起兜底/遮挡记账/开侧同步),违 main.gd 自身头注单口纪律;confirm_dialog.gd:40-41「树序由构建序保证」注释失真 | 三处收口:open 前经 `root._open_modal(root.confirm_dialog)`(ModalFlow.open 承载显示编排,T0 核其与 confirm_dialog.open 设文案的先后序);close 经 `root._close_modal(...)`;:40-41 失真注释随修。**行为改动=confirm 开合进 ModalFlow 栈(输入锁/互斥域归位)**——对照表专行+探针回归 | 审计 ①后半;架构单口纪律 | +| p3 | `main.gd:722/:749` settle_batch 两入口直取 `run_scope.settlement.minesweeper.settle_batch(...)`——前置空判隐式依赖 `_input_locked` 第三例外(锁谓词保证只在局内可达) | 两入口各加显式防护:`if run_scope.settlement == null: return`(零成本双保险——锁谓词异常时不再崩于空引用) | 审计 ③「入口显式 null 防护零成本双保险」 | +| p4 | `row_pacer.gd:11` `_rows` 待播队列住 main 级常驻节点(违架构「局态一律住 RunScope」)——会话更替零残留靠时序约定兜底 | `main.gd:175` `_begin_session` 内加 `_row_pacer.flush()` 一行(:49 现成公开面——机制保证会话更替即清队) | 审计 ④「_begin_session 内 flush 一行变机制保证」 | +| p5 | `board_generator.gd:396-398` 与 `reward_economy.gd:366-368` 两处 `_fatal`=push_error+assert(false)——release 模板剥离 assert 后退化为软回退(无 orchestrator 的 battle_result 封印兜底) | 两件 `_fatal` 各加可注入违约回调:`var fatal_handler: Callable`(缺省 `Callable()`=现行为逐字保持)+`_fatal` 体内 handler 有效则调用;组装点 `battle_orchestrator.gd:278/:283` 各接一行 `fatal_handler = _fatal`(orchestrator 自身 _fatal :1292 已带 battle_result 封印——协作件违约即传导封印=战斗中止,release 真中止成立) | 审计 ⑤「出包前需换真中止(可经宿主注入 fatal 回调)」——经组装层传导,零穿透三层、复用既有封印 | +| p6 | `rng_service.gd:100-103` `open_stream` 未知标签 push_error+assert 后**无 return**——release 剥 assert 后静默继续发号(违随机流纪律) | 补违约通道:`var violation_handler: Callable`(缺省现行为)+未知标签分支 handler 有效则调用+**`return null`**(合法路径零变化;release 下返回 null 使调用方即刻崩=fail-fast 传导);handler 注入使负路径 debug 可测(见 wr6) | 审计 ⑥「补 return 即闭合」+可测性(撤销证明口径) | + +**完成定义**: + +1. p1–p6 落地;合法路径全套闸按域选档全绿; +2. wr 断言绿(p5 封印传导/p6 违约回调两条新断言+p2 锁域回归); +3. 撤销证明三条(p1/p5/p6 各一——§8);三份产出物写齐(T2)。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 工程证据指认=审计报告 §三「其余小件」段(§90-95 逐件)+本卡 §3 实查重定位 | 五件清单与判据 | +| D2 | [architecture](../design/engineering/architecture/architecture.md)「局态一律住 RunScope」+单口纪律 | p2/p4 依据 | +| D3 | [code-conventions](../design/engineering/code-conventions.md) §1(死代码/重复语句)+fail-fast 红线 | p1/p3/p5/p6 依据 | +| D4 | 2026-10-26 用户令「全六件立项」 | 立项凭据 | + +## 3. 现状事实(2026-10-26 写卡会话实查于 master eb04313b——审计 2026-10-24 行号已按拆件后重定位;开工日 T0 复核行号) + +| # | 事实 | 出处 | +|---|---|---| +| S1 | `_sync_status_entry` 现住拆出件::111 死变量 battle_live(赋值零消费);首组四句 :112-116 与重复四句 :119-122 逐字相同(:117-118 注释自认「重复语句在案」;:123-124 调试角标注释独立保留) | `game/presentation/main_overlay_flow.gd:107-124` | +| S2 | confirm 旁路三处:main_overlay_flow.gd:88 open(选档删除确认流)+main.gd:312/:321 close(确认/取消两分支);单口 `_open_modal`→`_modal_flow.open(m)`(挂起兜底/排播排空/遮挡记账/开侧同步——main.gd:282-283 注释);confirm_dialog:open(:36 设文案)/close(:46)/is_open(:50),:40-41 注释「树序由构建序保证」与 ModalFlow 登记序口径不符 | `game/presentation/main_overlay_flow.gd:88`;`game/presentation/main.gd:312/321/282-286`;`game/presentation/views/confirm_dialog.gd:36-50` | +| S3 | settle_batch 两入口::722(棋盘动作批次——treasure 劫持检查后直取)与 :749(stop 批次——:746 有 `_input_locked` 守卫)均无 settlement null 防护 | `game/presentation/main.gd:722/749` | +| S4 | row_pacer 常驻队列 `_rows: Array[Variant]`(:11)+现成公开 `flush()`(:49);`_begin_session`(main.gd:175)现不 flush | `game/presentation/row_pacer.gd:11/49`;`game/presentation/main.gd:175` | +| S5 | 两协作件 `_fatal`=push_error+assert(false) 两行(无兜底——board_generator 实址 :396-398,grilling 订正 v1.0 的 :391-393;reward_economy :366-368 准确);组装点在 orchestrator(:278 `BoardGenerator.new()`、:283 `RewardEconomy.new(db, rng)`);orchestrator 自身 `_fatal`(:1292)=push_error+`battle_result = "fatal_error"` 封印+assert(release 剥 assert 后封印仍在=唯一阻断面) | `game/core/board_generator.gd:396-398`;`game/core/reward_economy.gd:366-368`;`game/core/battle_orchestrator.gd:278/283/1292-1295` | +| S6 | `open_stream` 未知标签分支(:101-103)push_error+assert 后直落 `_master_seed` 检查与发号——无 return;PURPOSE_TAGS 封闭词表(头注 EC12) | `game/core/rng_service.gd:100-112` | + +## 4. 设计契约(红线,违反 = L3 停机呈报) + +🔴 **契约 1 · 改动面封闭**:p1–p6 只动 §1 所列行;合法路径(无违约输入)行为逐位不变——结算、随机发号、排播时序、角标同步零变化;p2 是唯一申报的行为改动(锁域归位)。 + +🔴 **契约 2 · 缺省零变化**:p5/p6 的 handler 缺省(`Callable()`)时两件 `_fatal` 与 `open_stream` 行为逐字等于现状——禁顺手改 push_error 文案与 assert 条件。 + +🔴 **契约 3 · 封印传导不绕**:p5 组装接线后,协作件违约必须经 orchestrator `_fatal` 落 battle_result 封印——禁另立第二中止通道。 + +🔴 **契约 4 · 排播语义不变**:p4 的 flush 只在会话更替时点清队——正常运行期排播节奏零变化(pacing_queue_test 回归)。 + +🔴 **契约 5 · 禁为机检文本保留无效成员**(req-card 第 13 条,本卡属定点重构类):禁为避免断言/清单更新保留死变量或重复句(p1 歧路拦截);机检键与本卡契约互斥时一律停卡呈报。 + +## 5. 范围边界 + +**做**:p1–p6;新断言两条;探针回归;撤销证明;产出物。 + +**不做**: +- 件②level_map 三段(独立卡:[需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md](需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md)); +- orchestrator 自身 `_fatal` 改造(已有封印,审计未点); +- run_all.gd/probe_gate.sh 挂死防护(闸壳件②——工程直改通道,另拆注); +- confirm_dialog 的 open/close 方法本体(收口在调用面,方法语义不动)。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `待办清单.md` | 来源条目(六件候审)状态推进:五件归本卡+件②归独立卡+用户点名记录 | 反哺点 · 列清单(①:状态核对注记) | +| [architecture](../design/engineering/architecture/architecture.md) 模块归属表 | p2/p4 若涉契约表述(单口纪律/RunScope 条款现行表述已覆盖——预期零改动;T0 核) | 反哺点 · 列清单(②:预期零改动注记) | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/presentation/main_overlay_flow.gd` | p1 死变量/重复句删除+p2 open 收口(复用既有·修改) | p1 非行为/p2 **行为改动(锁域)**→ wr2 | +| `game/presentation/main.gd` | p2 close 收口两处+p3 null 防护两处+p4 flush 一行(复用既有·修改) | p2 行为(同行)/p3/p4 非行为(防护/会话边界) | +| `game/presentation/views/confirm_dialog.gd` | p2 注释随修 :40-41(复用既有·修改) | 非行为(注释) | +| `game/presentation/row_pacer.gd` | 零改动(flush :49 现成被消费) | — | +| `game/core/board_generator.gd` | p5 handler 注入面(复用既有·修改) | 非行为(缺省零变化)→ wr5 | +| `game/core/reward_economy.gd` | p5 同上(复用既有·修改) | 非行为 → wr5 | +| `game/core/battle_orchestrator.gd` | p5 组装接线两行(:278/:283 后各一行)(复用既有·修改) | 非行为(接线)→ wr5 | +| `game/core/rng_service.gd` | p6 handler+return(复用既有·修改) | 非行为(缺省零变化)→ wr6 | +| `game/tests/unit/battle_settlement/round_flow_skill_pool_test.gd` | wr5 断言(封印传导)(复用既有·增断言) | 断言面 | +| `game/tests/unit/core/`(rng 现役套件,T0 定名) | wr6 断言(违约回调+返回 null)(复用既有·增断言) | 断言面 | + +(零新增文件、零新增函数——p5/p6 是成员变量+分支段。) + +### 接口块 + +- **p5 形态**(两件同款):`var fatal_handler: Callable = Callable()`(成员声明,注释「违约中止通道——缺省退化 push_error+assert;组装层注入 orchestrator._fatal 经封印真中止」);`_fatal` 体内 assert 前 `if fatal_handler.is_valid(): fatal_handler.call(msg)`。 +- **p5 接线**:orchestrator 组装点 `:278` 后 `_board_generator.fatal_handler = _fatal`、`:283` 后 `_reward_economy.fatal_handler = _fatal`。 +- **p6 形态**:`var violation_handler: Callable = Callable()`;未知标签分支=push_error + `if violation_handler.is_valid(): violation_handler.call(purpose)` + `assert(false, …)`(handler 有效时调用在 assert 前——debug 注入测试面可断言)+ `return null`。 +- **wr5 断言**(round_flow_skill_pool_test 增,V6 装配形态同卡 A):构造 orchestrator → 直调 `_board_generator._fatal("测试违约")` → 断言 `oc.battle_result == "fatal_error"`(封印传导成立);缺省形态断言(新构造件不接线 → 直调 → battle_result 不受影响——契约 2)。 +- **wr6 断言**(rng 现役套件增,T0 定名——rng_service 现役单测所在套件):注入 `violation_handler`(记录型 Callable)→ `open_stream("bogus_purpose")` → 断言 handler 被调(记录位真)且返回值为 null。 +- **wr2 回归**:save_select/confirm 流现役探针(ui_click_probe 选档删除确认段——T0 定位)直跑绿+锁域断言(confirm 开时输入锁生效——若现役断言未覆盖则增一条)。 +- **取用**:无。**最窄闸**:round_flow_skill_pool_test+rng 套件+ui_click_probe 直跑;全套闸按本批改动域选档。 + +### 落位与可复用性预检 + +- **零新增件**:全部为既有件内成员/分支/行级改动;flush/pending_rows 复用 row_pacer 现成公开面。 +- **复用面**:p5 复用 orchestrator 既有 `_fatal` 封印(不造第二中止机制——审计「可经宿主注入」的最小实现);p4 复用 flush();p2 复用 ModalFlow 单口既有编排。 +- **唯一面**:违约通道各件唯一(fatal_handler/violation_handler 各一处、组装接线单点);confirm 开合收口后单口唯一。 +- **分层**:core 件零 UI 依赖不破(Callable 注入非 UI 引用;组装接线在 core 内层间);presentation 收口经既有 ModalFlow。 + +### T0 事实坐实(≈0.1d) + +- [ ] 复核 S1–S6(重点:S2 ModalFlow.open 与 confirm_dialog.open 先后序、wr6 落点套件名、wr2 探针段定位);确认 rng 套件与 pacing 回归面。可核查结果:定位清单进实现报告素材。 + +### T1 定点修五件+断言(≈0.5d) + +- [ ] 实装 p1/p3/p4(删句/防护/flush)+wr4 带夹具断言。可核查结果:grep 死变量与重复组零命中(:123-124 保留段除外);pacing_queue_test 直跑绿;wr4 断言绿。 +- [ ] 实装 p5/p6(handler 面+接线+return)。可核查结果:wr5/wr6 断言绿;缺省形态断言绿(契约 2)。 +- [ ] 实装 p2(confirm 三处收口+注释)。可核查结果:wr2 回归绿;grep `confirm_dialog.open(`/`.close()` 直调仅剩方法定义与收口内调用。 +- [ ] 验证步骤:全套闸按域选档跑一次全绿。 + +### T2 撤销证明+产出物落位卡(≈0.15d,末卡) + +- [ ] 撤销证明三条:①回退 p1 hunk(死变量还原)→ grep battle_live 命中即红(或静态扫描面);②回退 p5 接线两行 → wr5 封印传导断言红(battle_result 不变)→ 还原复绿;③回退 p6 hunk(return 与 handler 还原)→ wr6 断言红(返回非 null)→ 还原复绿。记录进实现报告。 +- [ ] 写齐三份产出物(实现报告〔五件逐件核对表+wr 断言读数+实机目检总清单——选档删除确认流目检一项(p2 锁域归位后行为目检)〕/代拍板追认单/反哺点清单〔§6 逐条落点〕)。 +- [ ] 合并前置:独立验收审计(§8.3)逐行「通过」。 + +**估时合计 ≈0.75d**。编排注记:五件皆小而独立——与件②卡(levelmap)、卡 A 同迭代分波无冲突;p2 有锁域行为面(wr2 回归是合并前置)。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 死代码与重复句清除(p1) | main_overlay_flow.gd:111+:117-122 | grep 判据零命中(:123-124 保留段除外)〔wr1〕+现役角标同步探针绿 | 静态+探针 | grep 真实跑批+ui 探针 | 回退 p1 hunk → grep 命中即红(T2①) | +| wr2 confirm 收口锁域归位(p2) | main_overlay_flow.gd:88+main.gd:312/321 | save_select/confirm 回归探针段〔wr2〕+锁域断言 | 探针 | 选档删除确认真实流(探针驱动) | 回退 p2 hunk → 收口判据 grep 命中即红+锁域断言红 | +| wr3 入口 null 防护(p3) | main.gd:722/749 前置防护 | 防护分支单测/静态判据〔wr3〕(防护态构造经探针锁谓词异常态不可达——静态面+代码评审注记申报) | 静态 | — | 回退 p3 hunk → grep 防护行零命中红 | +| wr4 会话 flush(p4) | main.gd:175 一行 | pacing_queue_test+会话更替断言〔wr4〕(新增:**前置夹具入队若干行再调 begin_session**,断言其后 pending_rows()==0——无夹具则改前改后皆绿钉不住〔grilling 订正〕) | 单元 | _begin_session 真实调用路径+enqueue 真实入队面 | 回退 p4 hunk → 带夹具断言红(残留非零) | +| wr5 fatal 封印传导(p5) | 两件 handler+orchestrator 接线 | wr5 断言两条(传导+缺省)〔wr5〕 | 单元 | V6 装配构造真实编排器路径 | 回退接线 → 传导断言红(T2②) | +| wr6 违约回调与 return(p6) | rng_service handler+return | wr6 断言〔wr6〕(handler 被调+返回 null) | 单元 | open_stream 真实调用路径 | 回退 p6 hunk → 返回值断言红(T2③) | +| wr7 产出物 | T2 三份 | 件核〔wr7〕 | — | — | 缺项红 | + +### 8.2 测试削弱申报 + +零(既有断言零改动;新增断言四条;wr3 防护分支不可达性以静态判据+申报承载——不虚构不可达态的运行期断言)。 + +### 8.3 独立验收审计 + +入口=未参与实现的会话或子代理;报告落 `reports/iter-验收审计-<日期>.md`;抽查重点=契约 1/2(合法路径逐位不变——缺省形态断言在案)、p2 锁域回归读数、p5 接线单点、p6 return 位置(assert 语义保持)。未过不得合并。 + +## 9. 异常分级 + +- **L1(自救)**:p2 收口先后序形态;p5/p6 注释措辞;断言挂点。 +- **L2(记录继续)**:行号漂移;wr6 落点套件名变化。 +- **L3(停机呈报)**:ModalFlow.open 与 confirm_dialog.open 语义冲突(双显示/挂起兜底破坏确认流——收口形态失配停呈);p4 flush 引入排播节奏变化(契约 4 破);p5 接线后协作件违约不落封印(传导断链);发现第三处 `_fatal` 同型软回退(审计清单外);p6 同函数 master_seed<0 分支(:104-106)同款 assert 后无 return——grilling 点名属同病根第二处:**单通道停卡呈报**(不并修——扩点违契约 1 改动面封闭与实现段零裁断;呈报后由用户裁另立或并批)。 + +## 10. 代拍板白名单(超清单必呈报) + +1. p5/p6 成员命名与注释措辞。 +2. wr 断言挂点与消息文本。 +3. p2 收口的先后序实现形态(ModalFlow.open 语义 T0 核后定形)。 +4. 提交切分与 worktree 分支命名。 + +## 11. 待裁点 + +**零待裁点,开工门=U0。** 灰色推导两处(呈报可否决,随 T2 反哺点):①p5 走「组装层传导 orchestrator 封印」而非回调穿透到 presentation——依据=core 件零 UI 依赖红线+复用既有封印零新中止机制;②wr3 防护分支验收用静态判据不造运行期断言——依据=分支在锁谓词正常态不可达,虚构异常态夹具违背「真实入口」口径。 + +## 12. 自审六查与复核记录 + +**自审六查(2026-10-26 写卡会话)**:①规格覆盖——p1–p6→T1/wr1–wr6、撤销/产出物→T2/wr7;②步骤扫描——T1 三步各挂可核查结果;③类型一致性——接口块形态与 S1–S6 实查一致;④审查焦点——缺省零变化(契约 2+缺省断言)、锁域回归(wr2)、封印传导链(契约 3)、排播节奏护栏(契约 4);⑤篇幅比例——零实现体;⑥落位预检——零新增件、复用面(flush/ModalFlow/封印)已答。 + +**grilling 一轮复核记录(2026-10-26,独立子代理对抗复核,判「通过(附四应修+一建议)」)**:①wr4 撤销证明不可执行(无夹具时改前改后皆绿)——v1.1 折入前置夹具断言;②p1 删除边界误圈(:123 调试角标注释非重复组;首组实为 :112-116、重复组 :119-122)——订正;③S5 board_generator _fatal 实址 :396-398——订正;④缺 req-card 第 13 条——立契约 5;⑤建议=p6 同函数 master_seed<0 分支(:104-106)同款 assert 后无 return——L3 点名(二轮收紧为单通道停卡呈报)。复核确认项:S2-S4 行号逐条命中、wr3 静态判据申报诚实、p5 载体成立(round_flow_skill_pool_test 现有装配形态)、handler-before-assert 排序与 headless 实测语义相容。 + +**二轮闭合复检(2026-10-26,判「通过(附三应修))**:四应修核闭合(wr4 夹具/p1 边界/S5 实址/契约 5);残留三处随本轮一并处理——wr1 行与 S5 出处列的旧行号订正、master_seed 条款由「并修或停卡」收紧为单通道「停卡呈报」(并修路线违契约 1 与实现段零裁断)。 diff --git a/reports/需求卡片-结算行缓冲类型错修复批-2026-10-26.md b/reports/需求卡片-结算行缓冲类型错修复批-2026-10-26.md new file mode 100644 index 00000000..bbe73400 --- /dev/null +++ b/reports/需求卡片-结算行缓冲类型错修复批-2026-10-26.md @@ -0,0 +1,143 @@ +# 需求卡片:结算行缓冲类型错修复批(_round_rows TypedArray 运行期错误) + +- 版本:**v1.2**(v1.0→一轮「通过(附两应修)」→v1.1→二轮闭合复检通过(残留两处随轮处理)→v1.2 定稿,复核记录见 §12) +- 来源:[待办清单](../待办清单.md)「闸与探针存量噪声两件——_round_rows 类型错与批上下文挂死」条目之件①(2026-10-25 登记,状态=待写卡·备选)(唯一事实源:工程证据指认=迭代 36 批末闸机观测〔绿跑日志复现运行期 TypedArray 错误〕+本卡 §3 行号级实查) +- 归属:`game/presentation/views/battle_log_view.gd`(类型声明一行)+探针日志断言面 +- 排期:未编入(迭代批卡片;估时 ≈0.25 工作日) +- 开工门:U0+复核门过(§12);零待裁点 + +## 0. 前置依赖与并行性 + +- **第〇步核对(2026-10-26 写卡会话)**:来源条目=需求性工程条目(bug 证据带 file:line),跳过设计线放行。**条目拆注**:条目两件中件①(产品码类型错)=需求改动走本卡;件②(闸壳 per-suite 挂死与进程树回收)改 `tools/` 闸件=**工程改动走直改通道,不属本卡**(§5 不做+条目拆注随本批复核同步登记)。 +- 与迭代 37 零交叠;与 2026-10-25 两批卡零文件交叠(卡 A 触 battle_log_view 仅核验零改动——本卡改 :17 类型声明与其 a5 核验面(match 分支/fallback)无叠)。 + +## 1. 目标与完成定义 + +**目标**:`_round_rows` 缓冲的类型声明与实际承载数据(格式化产物 String)对齐——TypedArray 运行期错误消失,**「上轮摘要」功能随之恢复**(现状 append 全数失败=缓冲恒空=摘要功能已死,G2);这是本卡唯一申报的玩家可见行为恢复,缓冲内容与消费序不变。 + +**改动单元清单**(🔴 契约 1): + +| # | 单元(实查) | 改法 | 依据 | +|---|---|---|---| +| g1 | `battle_log_view.gd:17` `var _round_rows: Array[Dictionary] = []`——而 append 的是 `_format_row` 返回的 String(:96 `append_row` 分支/:126 `_flush_pending_agg` 分支),消费面 :73-76 `for bb in _round_rows:` 把元素当 String 拼 `_summary` | 声明改 `Array[String]`——一行;缓冲语义(「本结算轮行缓冲·上轮摘要构建源」)不变,append 点与消费点零触碰 | 条目件①证据;GDScript TypedArray 运行期类型检查(append 异型即错误行——日志失真断言仍绿的根源) | + +**完成定义**: + +1. g1 落地;ui_click_probe 真实跑批日志零该 TypedArray 错误行(§8 wr1 判据①)+**摘要恢复正向断言绿**(wr1 判据②:结算轮结束后 `_summary.text` 非空); +2. 除申报的摘要恢复外呈现零变化;全套闸按本批改动域选档全绿; +3. 撤销证明一条(wr1);三份产出物写齐(T1)。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 工程证据指认=条目实况(迭代 36 批末闸机观测——绿跑日志复现)+本卡 §3 实查 | 缺陷存在事实 | +| D2 | [code-conventions](../design/engineering/code-conventions.md) §2(类型显式) | 类型声明与承载一致 | + +## 3. 现状事实(2026-10-26 写卡会话实查于 master eb04313b;开工日 T0 复核行号) + +| # | 事实 | 出处 | +|---|---|---| +| G1 | 声明 `Array[Dictionary]`(:17);append 两侧均为 String(:95-96 `var bb := _format_row(row)` → `append(bb)`;:126 `_flush_pending_agg` 同款);消费 :73-76 逐元素当 String 拼接 `_summary.text` 后 `clear()`(:82) | `game/presentation/views/battle_log_view.gd:17/73-82/95-96/126` | +| G2 | 运行期错误在绿跑复现(条目证据):TypedArray append 异型打 SCRIPT ERROR 行——**日志失真但断言仍绿**(断言不查该错误行);错误行进闸批日志即错误扫描噪声源(若闸扫描收紧则成假红) | 条目实况(迭代 36 批末观测) | +| G3 | 复现载体=ui_click_probe(真实冒险路径驱动结算行流经 append_row);battle_log_view 同路径自身复现。**功能已死实证**:append 全数失败 → `_round_rows` 恒空 → `_summary` 构建 :73-74 空即 return——「上轮摘要」自类型错引入以来从未显示 | 条目实况;`game/presentation/views/battle_log_view.gd:73-74` | + +## 4. 设计契约(红线,违反 = L3 停机呈报) + +🔴 **契约 1 · 改动面封闭**:只改 :17 一行类型声明;append/消费/清空/clear 时序零触碰。**行为恢复申报**:修复后上轮摘要从恒空恢复为正常显示=唯一行为面(wr1 正向断言承载);除此之外呈现逐字节不变。 + +🔴 **契约 2 · 缺陷修复不扩面**:不顺手改 `_format_row`/聚合域/摘要构建;发现的第二处类型错另呈报(L3)。 + +## 5. 范围边界 + +**做**:g1;探针日志验证;撤销证明;产出物。 + +**不做**: +- **条目件②(闸壳挂死与进程树回收)**——改 `tools/probe_gate.sh`(per-suite timeout 树杀)与 `game/tests/run_all.gd`(OS.execute 阻塞面超时守护)=工程改动(闸件/测试基建),走直改通道不写卡;随本批在待办清单条目内拆注(件①归本卡、件②留工程直改); +- 聚合域/格式化面任何改动。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `待办清单.md` | 来源条目拆注(件①已写卡·本卡;件②留工程直改)+状态推进 | 反哺点 · 列清单(①:拆注与状态核对) | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/presentation/views/battle_log_view.gd` | g1 类型声明一行(复用既有·修改) | 行为改动(运行期错误消失)→ wr1 | + +(零新增文件、零新增函数。) + +### 接口块 + +- **g1**(:17 原位):`var _round_rows: Array[String] = [] # 本结算轮行缓冲(上轮摘要构建源)`——注释随行保留。 +- **wr1 判据**(两条):①ui_click_probe 直跑(真实冒险路径)输出日志零 `_round_rows` TypedArray 错误行(**限定该错误行**——不扩大到一切 SCRIPT ERROR,防无关错误假红);②摘要恢复正向断言一条(落现役探针/系统测试——T0 定名:结算轮结束后 `log_view._summary.text` 非空),改前该断言必红(缓冲恒空)=撤销证明同源载体。 +- **最窄闸**:ui_click_probe 单件直跑(改前改后日志对照);全套闸按本批改动域选档。 + +### 落位与可复用性预检 + +- **零新增件**:一行类型修正;复现载体复用现役 ui_click_probe。 +- **复用面/唯一面**:缓冲仍单点单职责;无第二处同型缓冲(grep `_round_rows` 全库仅本文件)。 +- **分层**:presentation 视图内部类型面;零跨层。 + +### T0 事实坐实(≈0.05d) + +- [ ] 复核 G1–G3(重点:改前基线日志留存——错误行出现位置与频次记录)。可核查结果:基线日志对照表进实现报告素材。 + +### T1 修复+验证(≈0.15d) + +- [ ] 实装 g1。可核查结果:ui_click_probe 直跑日志零 TypedArray 错误行(与 T0 基线对照);现役断言全绿。 +- [ ] 验证步骤:全套闸按域选档跑一次全绿。 + +### T2 撤销证明+产出物落位卡(≈0.05d,末卡) + +- [ ] 撤销证明一条:回退 g1 hunk(类型还原 Array[Dictionary])→ ui_click_probe 直跑日志复现 TypedArray 错误行即红 → 还原复绿。记录进实现报告。 +- [ ] 写齐三份产出物(实现报告〔基线对照表+实机目检总清单——结算明细带轮摘要目检一项(登记不阻塞)〕/代拍板追认单/反哺点清单〔§6 逐条落点〕)。 +- [ ] 合并前置:独立验收审计(§8.3)逐行「通过」。 + +**估时合计 ≈0.25d**。编排注记:微件卡;与卡 A(明细行收敛)同触 battle_log_view 不同面(类型行 vs 核验面)——同波无冲突。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 缓冲类型对齐·错误消失+摘要恢复 | battle_log_view.gd:17 一行 | ①ui_click_probe 日志零该 TypedArray 错误行〔wr1-a〕(与改前基线对照)+②摘要非空正向断言〔wr1-b〕(T0 定落点) | 探针+日志 | ui_click_probe 真实冒险路径(结算行流经 append_row/聚合两分支) | 回退 g1 hunk → ②断言红(缓冲复恒空)+①错误行复现(T2) | +| wr2 产出物 | T2 三份 | 件核〔wr2〕 | — | — | 缺项红 | + +### 8.2 测试削弱申报 + +零(既有断言零改动;新增正向断言一条〔wr1-b〕——现役断言不查该错误〔G2〕,正因如此新增,非削弱)。 + + + +### 8.3 独立验收审计 + +入口=未参与实现的会话或子代理;报告落 `reports/iter-验收审计-<日期>.md`;抽查重点=改动面封闭(一行核对)、基线对照表在案、除申报的摘要恢复外呈现零变化(现役断言绿读数)。未过不得合并。 + +## 9. 异常分级 + +- **L1(自救)**:无(一行改动零裁量面)。 +- **L2(记录继续)**:行号漂移。 +- **L3(停机呈报)**:类型修正后呈现输出有变(契约 1 破——缓冲语义另有隐患);发现第二处同型 TypedArray 错误。 + +## 10. 代拍板白名单(超清单必呈报) + +1. 提交切分与 worktree 分支命名。 + +## 11. 待裁点 + +**零待裁点,开工门=U0。** 灰色推导一处(呈报可否决):条目件②不并入本卡、走工程直改——依据=改动四类判据(闸件/测试基建不改变游戏行为,禁写卡直改通道);若用户裁两件并批,件②以工程批形态与本卡同 worktree 分批提交(不混入本卡)。 + +## 12. 自审六查与复核记录 + +**自审六查(2026-10-26 写卡会话)**:①规格覆盖——g1→T1/wr1、撤销/产出物→T2/wr2;②步骤扫描;③类型一致性——G1 两侧 append 均 String 实查;④审查焦点——呈现零变化护栏(契约 1)、件②通道拆注(§0/§5);⑤篇幅比例;⑥落位预检——零新增件、唯一缓冲点已答。 + +**grilling 一轮复核记录(2026-10-26,独立子代理对抗复核,判「通过(附两应修)」)**:①「呈现零变化」与修复本质矛盾(现状摘要功能已死——append 全数失败缓冲恒空;修复=玩家可见行为恢复)——v1.1 折入:目标/契约 1/完成定义改「申报内行为恢复」口径+G3 补 :73-74 空即 return 实证+wr1-b 正向断言(改前必红=撤销证明同源);②wr1 判据「零 SCRIPT ERROR 行」过宽——收窄为该 TypedArray 错误行;③复核确认=事实全核实(:17/:95-96/:126/:76-82、全库唯一)、件②拆走工程直改判定正确、撤销证明可执行。 + +**二轮闭合复检(2026-10-26)**:两应修核闭合;§8.3 漏改处与本记录块归位随本轮一并处理。 diff --git a/待办清单.md b/待办清单.md index 1df2f573..83ffe989 100644 --- a/待办清单.md +++ b/待办清单.md @@ -33,11 +33,15 @@ #### 结构审查未立项小件候审(2026-10-25 登记,来源=批次移交) -**实况**:证据=reports/审计-game代码结构审查-2026-10-24.md §三「其余小件」清单(2026-10-24 写卡会话未立项,随迭代 37 批后收尾移交本条)。六件:①level_map 视图直读/BFS;②main 死变量与 confirm 旁路;③settle_batch 空判;④row_pacer 常驻 flush;⑤_fatal assert 剥离;⑥rng_service early-return。逐件论证与行号址见该审计报告 §三(报告留档在册)。是否立项与点名时点待用户裁决;立项者按改动四类走需求改动通道(写卡+编批)。 +**实况**:证据=reports/审计-game代码结构审查-2026-10-24.md §三「其余小件」清单(2026-10-24 写卡会话未立项,随迭代 37 批后收尾移交本条)。六件:①level_map 视图直读/BFS;②main 死变量与 confirm 旁路;③settle_batch 空判;④row_pacer 常驻 flush;⑤_fatal assert 剥离;⑥rng_service early-return。逐件论证与行号址见该审计报告 §三(报告留档在册)。**2026-10-26 用户裁「全六件立项」**——审计原编号②③④⑤⑥五件立「结构小件定点修批」(行号已按迭代 37 拆件后重定位)、原①(level_map 三段)独立立卡;写卡会话实查增补:confirm 三处旁路现行址(main_overlay_flow.gd:88+main.gd:312/321)、p5 走 orchestrator 既有封印传导、p6 增可测违约回调;rng open_stream 同函数 master_seed<0 分支(:104-106)同款病根留 L3 停卡呈报通道。 + +关联文档清单: +- 需求卡片 reports/需求卡片-结构小件定点修批-2026-10-26.md(2026-10-26 v1.2,grilling 两轮复核(一轮附四应修+二轮附三应修均闭合),零待裁点;估时 ≈0.75d) +- 需求卡片 reports/需求卡片-levelmap装配越界与BFS缓存批-2026-10-26.md(2026-10-26 v1.2,grilling 两轮复核(一轮回炉两阻断闭合+二轮附一应修),零待裁点;估时 ≈0.75–1d——呈现零变化锚「改前建 level 屏 golden 基线」) **改动面**:游戏代码 -**状态**:待裁决 +**状态**:已写卡 #### gdstyle 基线陈旧键待人工清理(2026-10-25 登记,来源=批次移交) @@ -576,12 +580,13 @@ #### 闸与探针存量噪声两件——_round_rows 类型错与批上下文挂死(2026-10-25 登记,来源=批次移交) -**实况**:证据=迭代 36 批末闸机观测(非本批引入)。两件存量噪声:①`ui_click_probe` 与 `battle_log_view` 绿跑亦复现 `_round_rows`(Array[Dictionary])append String 的运行期 TypedArray 错误——日志失真但断言仍绿;②`level_shop_economy_test` 在闸批量上下文存在挂死形态(直跑恒绿),`tools/probe_gate.sh` 的 per-suite timeout 只杀 wrapper 不杀引擎子进程,孤儿泄漏会殃及后续全部 Godot 启动(批末四次闸跑批中断的根源,处置=清杀泄漏进程+删重建 `game/.godot`)。两件均登记待后续测试基建批处置。 -- 相关文档:`game/presentation/views/battle_log_view.gd` 与 `game/probe/ui_click_probe.gd`(类型面);`tools/probe_gate.sh`(进程树回收面)——测试基建 +**实况**:证据=迭代 36 批末闸机观测(非本批引入)。两件存量噪声:①`ui_click_probe` 与 `battle_log_view` 绿跑亦复现 `_round_rows`(Array[Dictionary])append String 的运行期 TypedArray 错误——日志失真但断言仍绿;②`level_shop_economy_test` 在闸批量上下文存在挂死形态(直跑恒绿),`tools/probe_gate.sh` 的 per-suite timeout 只杀 wrapper 不杀引擎子进程,孤儿泄漏会殃及后续全部 Godot 启动(批末四次闸跑批中断的根源,处置=清杀泄漏进程+删重建 `game/.godot`)。**2026-10-26 通道拆注(写卡会话裁定)**:件①=游戏产品码缺陷(battle_log_view.gd:17 类型声明错——修复后「上轮摘要」功能恢复)走需求改动通道已写卡;件②=闸壳/测试基建(probe_gate.sh+run_all.gd 挂死防护)按改动四类属**工程改动走直改通道**,本条目降为件②直改登记。 +- 相关文档:件①归 reports/需求卡片-结算行缓冲类型错修复批-2026-10-26.md +- 件②直改落点:tools/probe_gate.sh(per-suite 进程树回收)+game/tests/run_all.gd(OS.execute 阻塞面超时守护)——测试基建直改 **改动面**:游戏代码+工具代码 -**状态**:待写卡(备选) +**状态**:已写卡+待执行 #### 美术资产链路审计两项 P0 — 待用户裁决(2026-10-09 登记,来源=审计发现) @@ -674,7 +679,11 @@ **实况**:文档面旧词清扫批(termsweep-20261026)连带发现。证据四件:①`game/data/schemas/adventure_table.gd` 常量 TIER_QUOTAS={common:70, excellent:25, rare:7, legendary:0}(头注自记「稀有 7、总量 102」系 provisional 投放)与 `game/data/tables/adventure.tres` 现行逐 kind 配额求和(common 70/excellent 25/rare 3〔仅行动点件〕/legendary 0=98 张)不一致——schema 校验是否按该常量核对 tres 总量、provisional 投放是否落表,须核对后统一口径;②同一 tres 头注两段注释新旧口径并存(「稀有 3/98 张」与「稀有 7/102 张」混写);③`game/tests/golden/README.md:26`「魔法道具 HUD」系秘宝旧名;④`game/tests/验证集清单.md:850`「稀有/罕见档」旧档名并写。零行为断言变化,属注释/常量口径/说明文字修订。 - 相关文档:[node-reward](design/gdd/ux/node-reward.md) v2.9(文档面已按 tres 现行值对齐);档名四级映射=`data/schemas/adventure_table.gd` 头注 +- **2026-10-26 写卡会话订正与定稿**:①论断订正——「schema 锚与 tres 不一致」不成立(rap/时沙 rare 默认值 2/2,逐 kind 求和恰等于常量 7;validate 校验活着且绿、guard_test 断言绿;deck_total 实算 102);②真问题=头注旧口径残留(schema 四处+tres 五处——rare=3 直映射时代数字与沿革句)+旧档名两处(golden/README:26「魔法道具」、adventure_feats_test.gd:399「稀有/罕见档」);③「罕见」另三处经裁定合法保留(schema:25-26 档名映射注+schema:92-93 与 curio_deck.gd:129-130 契约④原名引述)。 + +关联文档清单: +- 需求卡片 reports/需求卡片-令牌配额口径清扫批-2026-10-26.md(2026-10-26 v1.2,grilling 两轮复核(一轮回炉两阻断闭合+二轮窄修),零待裁点;估时 ≈0.3d) **改动面**:游戏代码 -**状态**:待写卡 +**状态**:已写卡