23 KiB
D1 HUD 与界面框架 设计推演
状态：concluded（未闭合项见文末「开放问题」）· 本文只装"为什么"——
design/gdd/d1-hud-framework.md只收本文的结论。 修订时新增问题节，不删旧节（历史即依据）。
问题 1：为什么 D1 必须作为独立的零玩法状态呈现层系统存在？
广度分析
- 候选 A：不设独立呈现层系统，呈现义务散落在各玩法 GDD——收益：少一份文档；代价：27 项跨系统呈现义务没有单一兑付点，A2 的三事件流没有读者、B1 的流水协议没有呈现面，"自动战斗沦为无聊过场"（game-concept 已识别风险 #1）的防线无人承载。
- 候选 B：呈现层自持部分玩法状态（如本地缓存棋盘、自判合法性）——收益：刷新链路短；代价：与核心双事实源，呈现失真（雾格显影 / 拒绝吞掉 / 格态混淆）直接杀死 P1"我算对了"的感知面。
- 候选 C（采纳）：独立 D1，零玩法状态、零写、零 RNG，只读经成文呈现面、写经组合根。
深度分析
垂直切片两起呈现层崩溃暴露"已定稿 AC 全覆盖 core、呈现层零测试承载"的系统性盲区：① 窗口载荷缺字段直接崩溃（信号参数无运行时类型检查）；② battle_finished 后读已销毁对象。这两起不是偶发 bug，而是"呈现层没有成文契约"的结构性后果——信号载荷 schema、场景级测试、信号时点状态可见性必须升格为系统级硬性要求。
美术侧同理：art-bible §4.6 图标键契约已冻结（键与通道分配定稿、终稿美术归样张批），样张未制作不阻塞 D1 的前提，是呈现层以程序化占位先行并在契约层登记键位映射——这也只有独立系统文档能承载。
综合判断
D1 独立成系统，定位 Layer 4 Presentation、零玩法上游假设。design 件的系统范围、规则 1–4 / 17–20 与 27 项义务台账即本结论的落点。
问题 2：为什么界面只当翻译不当裁判、听消息只走中转、读数走白名单？
广度分析
- 订阅形态候选：呈现层直订 A2/A3 事件（收益：链路短；代价：违反 ADR-0001，呈现层与玩法系统多点耦合，事件语义漂移直接打进视图）vs 只订 B1 步骤流 + runner 信号、其余经组合根转发（采纳）。
- 刷新形态候选：纯事件驱动（代价：旗插拔/移动/AP/RAP/库存等动作零事件外发或零推送，纯事件驱动必然漏刷新）vs 命令式回执双通道（采纳：动作调用一返回，组合根立刻重查只读面刷新界面，不干等通知）。
- 取数形态候选：自由读核心字段（代价：封装破碎、接口漂移不可追踪）vs 成文读数白名单、登记 registry
d1_presentation_surface（采纳）。
深度分析
ADR-0001 明确"信号参数无运行时类型检查"——契约只能靠成文 schema + 消费侧逐字段断言兜底，这是规则 17 十三项载荷表双重用途（实现契约 + 消费断言）的直接成因。battle.md §Events Fired 的"呈现订阅 A2 三事件"表述与 ADR-0001 有措辞差，本系统按 ADR-0001 收窄为"经组合根转发或命令式回执"（冲突清单⑥，battle.md 正文不改动，复检批对齐）。
综合判断
规则 1–4、17、18 即本结论：零玩法数值字面量、零规则逻辑、零核心写调用（唯一发生在组合根）、零 RNG、零直订 A2/A3、禁回读核心生命周期状态。
问题 3：移动路径预览为什么是"合法性指示"而不是穿行动画？
广度分析
- 候选 A：穿行动画轨道——收益：方向感强；代价：移动免费且高频，每次移动都付动画时间税，违反点击摩擦护栏（P4 ≤2 观测假设的承载面）。
- 候选 B（采纳）：悬停即画
compute_move_pathBFS 路径蓝细线点迹（合法性指示）+ 执行时 ≤150ms 短滑。 - 关联候选：点击远格自动"先移动再挖"复合意图——不采纳：移动免费高频，两击的摩擦符合观测假设；留 playtest 验证（A2 评估项留痕）。
深度分析
预览与执行必须同源（同一 compute_move_path，不可达返回空即预览不显示 + 禁止光标），否则"画出来的路"与"走出来的路"可能不一致，合法性指示反而成了谎言。F4 语义序仲裁退为防御性兜底，是因为单意图帧 + stop 终结当帧收集的纪律使生产面造不出会乱序的输入（联合清图让位条款生产面不可达）。
综合判断
规则 7、8 即本结论；短滑时长留痕 playtest 观测（battle.md OQ5），旋钮 = move_slide_ms，若反馈"移动太瞬"再议。
问题 4：棋盘格尺寸为什么是两档定值而不是一条闭式公式？
广度分析
- 候选 A：单一闭式 floor(可用高度 ÷ N)——收益：一处公式；代价：固定边距下无法同时得出 36 与 45 两档（见深度分析）。
- 候选 B（采纳，评审后用户裁决方案 A）：cell(12)=36px、cell(10)=45px 两档定值（battle.md 拍板），公式退为装板期可行性校验器（违例 fail-fast）。
深度分析
反证：cell=36 要求可用高度 ∈ [432,443]、cell=45 要求 ∈ [450,459]——两区间不相交，任何固定 pad 的闭式都无法同时落进两个区间。两档值来源是 battle.md 拍板（"格 36–45px 见方"两端），不是几何推导的产物；因此 F1 的正当形态是界限断言 + 可行性校验，而非闭式导出。
综合判断
design 件 F1 节即本结论：两档定值 + floor(min(D_w − pad_h, D_h − ap_bar_h − pad_v) ÷ N) ≥ cell(N) 且 cell(N) ∈ [30,45] 装板期断言；数字字号 = max(18, ceil(cell × 0.5))。
问题 5：结算明细为什么逐行念账、未生效行为什么不静默、极性为什么按键判？
广度分析
- 明细形态候选：聚合摘要（收益：干净；代价：玩家无法把每一分收益对回自己哪一步扫雷决策，P2 规划延迟兑现的呈现半边断裂）vs 逐行流水 + 每行来源标注（采纳）。
- 未生效行候选：静默吞掉（代价：voided 不提示 = 读感欺骗；零值行被吞 = 兑现不可对账）vs 聚合计数呈现 + 形状冗余（采纳——防逐行惩罚轰炸，且非色相独载）。
- 极性判别候选：按 magnitude 符号（反例：负值增益存在）或按 pool 归属（反例：enemy_output 池两向并存）vs 键级极性表（采纳：attack_up/defense_up/weaken 有利、ambush 有害）。
深度分析
效果行 value 与 pool_value 必须两列分示、禁相加——否则"−130%×2 行 = −260%"的误读必然发生。P2 裁剪判据的最后半米由呈现层走完：行协议 13 类封闭枚举（B1 Core Rule 14）已经把归因字段备齐，呈现层唯一不能做的就是"替玩家省略"。
综合判断
规则 11、12 及其实现参照表即本结论；高光使用规则 = 事件型用独立高光行、属性型强调用行字段标记，庆祝不打在空兑现上（完美排雷首份即零兑付不发高光）。
问题 6：轮末道具窗口为什么在道具栏原地亮起、有库存恒弹？
广度分析
- 候选 A：中央弹窗——代价：打断结算流的视线连续性，与"结算期原地展开明细"的双舞台常驻形态矛盾。
- 候选 B：常驻库存条非模态——代价：窗口锚点的"至多选一件"承诺感消失，选用/跳过不成决策节点。
- 候选 C：仅可用品触发——代价：usable_now 之外的库存信息（未选用件政策注记）失去例行曝光位。
- 候选 D（采纳）：E 区原位激活、MVP 有库存恒弹（battle.md 布局决策 D2）；候选 B/C 归垂直切片留痕（B4 D1 义务②注记）。
深度分析
原位激活的配套纪律来自切片教训：窗口激活期间必须跳过常读条全量重建——全量刷新会冲掉窗口态（entry 36）；空库存直接 skip 不弹窗、窗口标记照常登记（回放输入完整性归 B1），结算零停顿。去饱和 + 金橙色相偏移是 art-bible §2 明度恒定硬规则的合规化实例：锁输入的表达只经色相/饱和，不靠变暗。
综合判断
规则 13 即本结论：原位激活、至多选一件、提交窗口条目位置序（非库存句柄——切片缺陷④契约修正）、跳过恒在、政策注记常驻。
问题 7：零合法板为什么只做诚实提示？
广度分析
- 候选 A：提示（采纳）——B1 上抛非法产物标记 → toast 诚实提示（非模态、不打断）。
- 候选 B：补偿——补偿逻辑归 B1 域外，D1 无权发明玩法补偿。
- 候选 C：确定性回退已知好种子——实现期 ADR 候选（A1 OQ2 关联），不是 MVP 面向玩家的形态。
深度分析
玩家永不卡死已由 A1 验收三分支保证，D1 面对的不是"救场"问题而是"诚实"问题：非法产物到达玩家眼前时，静默是读感欺骗，提示是体验债的诚实兜底（原"玩家不可见遥测域"口径由本条承接闭合）。
综合判断
边界情况表"零合法板"行即本结论：MVP 面向玩家的形态 = 仅提示（B1×3③ / A1 EC5，AC-19 注入腿承载）。
问题 8：体验锚点与美术解耦如何论证？
广度分析
- 参考感受：Into the Breach 的格内信息分层（预告上格——威胁画在格子上）+ 杀戮尖塔的逐卡结算反馈。
- 美术解耦候选：等终稿美术再开工（代价：样张批阻塞整个呈现层）vs 程序化占位先行（采纳：用代码按冻结色板与形状规则直接画出临时图形，终稿到位后原位替换、数据层零改动、零运行时换图）。
深度分析
P1 感知面：规则层的诚实（A2 数字恒真、三源拒绝）必须由呈现层原样送达——任何呈现失真（雾格显影 / 拒绝吞掉 / 格态混淆）= P1 的死亡体验。P2 呈现半边：逐行归因是"这个结果是我哪步扫雷带来的"的唯一兑现形态。P4 容器：挖掘期画面无杂音（能量 2/10，唯一在动 = 悬停呼吸微光）→ 结算期金橙光带逐行横扫（7/10）→ 清图金粒喷泉短促丰收（8/10）→ 失败暮蓝最静一拍（1/10），§2 能量档与明度恒定硬规则由 D1 的转场与反馈系统承载。高光节拍是 P2 爆发兑现节点（创意风险 #2 落点）：完美排雷全屏喝彩 + 标中旗金框行 + H2 金框。
反向护栏：界面绝不替玩家思考（不预判合法点击以外的东西）、绝不静默改判（voided 不提示 = 读感欺骗）、绝不用装饰伪装逻辑差异（art-bible 原则三）——玩家对 D1 的正确感觉是"一块干净的玻璃"：看穿它直接看到棋局与战果，玻璃本身不添乱。占位图同样过硬指标的理由：色板参数域从结构上保证（底足够亮、墨足够深），数字可读性 ≥4.5:1 对程序化占位同样适用；样张定稿 = 砖面形态与色板的冻结闸、终稿资产开工的前置，样张批不阻塞 D1 其余全部验收。
综合判断
design 件设计目的的五条体验承诺、规则 19、规则 22 与 Visual/Audio 执行锚点表即本结论。
附录 A：切片教训三条硬性要求落位表（entry 17——门禁评审核对项，缺项即 blocking）
| # | 硬性要求 | 落位 |
|---|---|---|
| ① | 面向呈现的信号载荷成文 schema | 规则 17（13 项载荷表——A2 三事件/B1 行协议引用 + D1 自有遥测成文 + 零事件外发命令式刷新面成文） |
| ② | 场景级 headless 测试进 AC | AC-19 起场景级硬性块（真实实例化战斗屏场景 + 驱动完整对局 + 断言零脚本错误；载体 = 场景探针，ADR-0004 双载体、gdUnit4 deferred） |
| ③ | 信号时点状态可见性规则 | 规则 18（销毁前捕获 / 载荷自包含 / 禁回读核心生命周期态）+ AC-20 断言 |
附录 B：覆盖矩阵（门禁评审用——编号沿用 design 件现行节名）
| 类别 | 映射 |
|---|---|
| Core Rules | 1–4→AC-19/24/25 · 5→AC-1 · 6→AC-10 · 7→AC-6/7 · 8→AC-6 · 9→AC-4/5 · 10→AC-9 · 11→AC-12/15 · 12→AC-11 · 13→AC-13 · 14→AC-14 · 15→AC-4/11 · 16→AC-8/16/17 · 17→AC-24 · 18→AC-20 · 19→AC-15（键位）/样张引用 · 20→AC-25 · 21→AC-21 · 22→AC-23/26 |
| Formulas | F1→AC-2 · F2→AC-3 |
| Edge Cases | 全表→AC-4/6/8/10/11/13/14/16/17/21/22/23/15（拒绝与 voided→AC-8 及探针负例；零合法板→AC-19 注入腿；双雾区→AC-4/11 腿） |
| 义务台账 | 27 项→design 件「呈现义务台账逐项落位表」逐行 |
| 切片教训 | 3 项→AC-19/20/24 + 规则 17/18 |
附录 C：发现冲突清单（列示待裁决——不改已定稿 GDD 正文与提案）
| # | 冲突 / 待对齐项 | D1 侧处置 |
|---|---|---|
| ① | game-concept 视觉锚原则 1"暗色地牢底色" vs art-bible 明亮底色反转 | 在案（entry 41）——概念侧注记待概念层修订批；D1 全部取色按 art-bible |
| ② | B2 GDD 敌种键 {grub, ambusher} vs 切片 DND 更名 {goblin, bugbear, ogre_chief} | 键位映射表以 GDD 键集为锚（§4.6.4 冻结）；切片更名随 B2/C3 修订批对齐 |
| ③ | B4 GDD 默认根 clear_knife vs 切片供给控制器批 clear_blast + active_inject 池 | 徽章键按 reward_id 冻结、池归属不影响键（§4.6.2 注记）；clear_blast 键并列预留、启用随 B4 修订批 |
| ④ | 极性提案 §3.5 跨文档回写清单全部待实施批（B3 四行→七行、B4 schema 扩列、A2 OQ1 关闭、D1 义务条目正式登记〔未开格类型图标/极性视觉语言/负向文案族〕） | 本 GDD 已按 §4.6 冻结键预留槽位；义务条目登记随提案实施批入 systems-index D1 台账 |
| ⑤ | art-bible §4.6.3"全部未开格呈现类型徽章"（提案 R3）vs B4 Rule 8"未开格身份 MVP 不呈现" | D1 裁决：MVP 格面徽章只在已开格呈现（B4 Rule 8 为现行锁定规则）；未开格预读随极性提案实施批（其机制前提 = cell_type/pool_tag 扩列）随批修订 |
| ⑥ | battle.md §Events Fired"呈现订阅 A2 三事件"表述 vs ADR-0001 订阅纪律（呈现层只订 B1/runner） | 本 GDD 按 ADR-0001 收窄（规则 2）；battle.md 复检批对齐措辞（正文不改动） |
| ⑦ | A3 只读观测量（ap/rap/phase/last_round_end）缺轮内已用刷新次数——刷新按钮"本轮剩 N 次"读数无上游供给 | 接口漂移登记义务（OQ2）：A3 随批补只读观测量；落地前按钮显示退化为"RAP−{rap_refresh_cost 表读值} · 每轮至多 2 次"静态文案 |
| ⑧ | 切片已实现的 B1/B2 呈现面 API 未在 owner GDD 登记契约：B1 面 presentation_snapshot / is_battle_live / stock_count / query_reward_identity / submit_window_selection + settlement_snapshot 信号、B2 面 hero_unit / all_enemies（registry d1_presentation_surface 已成文——owner=D1，切片事实转正） |
OQ3：现行消费以 registry 条目为契约（D1 消费 = 步骤流判定行 + presentation_snapshot()，零阻塞）；回 B1/B2 修订批补登记 API 面（接口漂移） |
附录 D：审计注记（评审元数据，不入 design 正文）
- 复核注记：solo 模式下 creative-director（体验锚点情绪定位——与 battle.md Purpose & Player Need 同源，design 件设计目的为其系统级转写）与 art-director（Visual/Audio 与 art-bible 一致性）未经咨询——生产前人工复核。呈现义务承载依据 =
design/ux/battle.md（APPROVED，§13 台账 27 项经 ux-review 实存验证）+design/art/art-bible.md§1–4。 - 上游状态：A1–B4/B1 + D2 全部 Approved（C3 为 Designed 未经评审——D1 零玩法消费；battle.md APPROVED · art-bible §1–4 定稿）——项目首个零玩法上游假设的表现层系统。
- 归属声明：屏级布局、组件形态、交互细节、动画时长的裁决权威 =
design/ux/battle.md（APPROVED）——本 GDD 引用其裁决不重复论证，只做三件事：① 升格为系统级规则与 AC；② 补齐 spec 之外的系统级契约（信号载荷 schema / 订阅纪律 / 程序化占位 / 命名统一 / 遥测）；③ 逐项落位 27 项门禁义务。 - 命名统一核销 = session-state entry 35（AC-25 grep 断言承载）；读接口白名单转正 = 封装收口批 entry 39/40；敌卡就地更新与窗口态 stomped 教训 = 切片 entry 36。
开放问题
| # | 悬案 | owner | 时机 |
|---|---|---|---|
| 1 | _draw 迁移复议（ADR-0003 Decision 3 的 D1 裁决登记）：MVP 维持 GridContainer + 逐格控件（裁决依据：呈现层程序化占位、样张未定稿、雾纹理/终稿表现力需求未冻结、三探针与现形态耦合〔改造 = 隐藏成本〕）——样张定稿后按表现力需求（biome 色板/雾纹理/动效复杂度）复议二选一；若迁移，Viewport.push_input 端到端探针从加分项变必需项（ADR-0004） |
D1 复议批 | 样张定稿后 |
| 2 | A3 轮内刷新次数读数（接口漂移登记）：刷新按钮"本轮剩 N 次"需要 A3 暴露轮内已用刷新计数（现只读观测量 ap/rap/phase/last_round_end 未含）——A3 修订批补只读观测量 + AC 前言扩列；落地前按钮退化为静态文案"RAP−{rap_refresh_cost 表读值} · 每轮至多 2 次" | A3 | 正式实现接线批 |
| 3 | B1/B2 呈现面 API 契约登记（冲突⑧扩条）：切片已实现的 presentation_snapshot / is_battle_live / stock_count / query_reward_identity / submit_window_selection（B1 面）+ settlement_snapshot 信号 + hero_unit / all_enemies（B2 面）均未在 B1/B2 GDD 登记——registry d1_presentation_surface 为现行契约载体；回 B1/B2 修订批补登记 API 面，独立信号需求随批裁决（接口漂移） |
B1 / B2 | B5 GDD 前 |
| 4 | battle.md 订阅表述对齐（冲突清单⑥）：ADR-0001 订阅纪律（呈现层只订 B1/runner）与 battle.md §Events Fired"A2 三事件呈现订阅"的措辞差——本 GDD 按 ADR-0001 收窄；battle.md 复检批对齐 | battle.md 复检 | 下次 /ux-review |
| 5 | Gamepad 焦点序（battle.md OQ8 继承）：Partial 支持非 MVP——焦点环顺序待 gamepad 批次 | gamepad 批次 | gamepad 批 |
| 6 | 相邻域屏 spec（battle.md OQ9 继承）：design/ux/node-reward.md / design/ux/level-clear.md——本 GDD 只锁出口锚点（节点奖励覆盖层 / 关卡结算屏的完整形态归后续 spec） |
后续 spec | 垂直切片后 |
| 7 | accessibility-requirements.md（battle.md OQ2 继承）：正式分层（文本缩放/色盲模式/按键重映射）待该文档定稿——gate-check Pre-Production 缺口在案 | 该文档定稿批 | 文档定稿 |
| 8 | 键集扩容流程锚定：新 effect_id / reward_id / enemy_id / cell_type 上线 → art-bible §4.6 修订 + SettlementTable effect_pool_map 随批登记（接口漂移双登记——本 GDD AC-15 fail-fast 强制暴露漏登记） | art-bible / D2 修订批 | 键集扩容时 |
| 9 | 极性提案实施批的 D1 义务条目（冲突清单④）：未开格类型图标 / 极性视觉语言 / 负向文案族按提案 §3.5 正式登记入 systems-index D1 台账（本 GDD 已预留键槽位与裁决⑤） | 极性提案实施批 | 提案实施批 |
| 10 | 明细带挖掘期常驻摘要（battle.md OQ6 继承）：常驻（现方案）vs 结算后收起——playtest 观测回看频率后裁决 | playtest 后裁决 | 垂直切片 playtest |
| 11 | D5 教学挂靠（battle.md OQ13 继承）：挖到雷=敌方优势 / 旗挡链 / 首次蓄力提示 / 囤刀闭环——toast 体系为落点候选，D5 GDD 批定 | D5 | D5 GDD 批 |
| 12 | TunePanel 退役时点（battle.md OQ10 继承）：C4 天赋树落位批退役（规则 21 已标注）；Playtest 诊断按钮保留 | C4 | C4 落位批 |
去向映射（零丢失可审计证据）
| 原文章节 / 表 | 落点 |
|---|---|
| 头部块（状态/版本/支柱/层级/一句话） | design 头部块 |
| 头部复核注记 / 上游状态行 | analysis 附录 D |
| 速览表（定位/拥有/不拥有/上游输入/下游输出/硬约束） | design 设计目的 / 系统范围 / 依赖与输出 |
| D1 的存在理由（四条） | analysis 问题 1 |
| 体验锚点表 + 直接承载/参考感受/反向护栏 | design 设计目的（承诺形态）+ analysis 问题 8（论证） |
| 全局流程（呈现刷新链路字符画 + 出口分发表） | design 核心循环 |
| 核心规则归属声明 | analysis 附录 D（权威优先句入 design 依赖与输出引言） |
| 规则 1–4（边界/订阅/读面/写通道） | design「呈现边界与数据通道」 |
| 规则 17 / 18 / 20（载荷 schema / 快照纪律 / 命名统一） | design「呈现边界与数据通道」；切片崩溃机理与 ADR 论证 → analysis 问题 2 |
| 规则 5 / 6 / 21 + 五区布局表 + 敌卡六件套 + 意图线索映射目录 + 战斗屏状态机 | design「战斗屏布局与组件」 |
| 规则 7 / 8 / 9 / 15 + 四种格态 / 光标语义 / hint_id / 拒绝与 voided 映射 | design「挖掘输入与棋盘可读」；穿行动画与复合意图取舍 → analysis 问题 3 |
| 规则 10 / 11 / 12 / 13 + 三张实现参照表 | design「信息与归因呈现」；逐行归因/极性判别/窗口候选论证 → analysis 问题 5、6 |
| 规则 14 / 16 / 19 / 22 + 终局反馈表 + Visual/Audio 锚点表 + 边界情况表 | design「提示·终局反馈·美术与可访问性」；占位解耦论证 → analysis 问题 8 |
| 枚举·ux 遥测行族 | design 规则 17 载荷表 #13（字段与值域在该行展开） |
| 数值结论与推导（F1 / F2 / 显式排除声明） | design「呈现几何与可读性判据」；F1 定值 vs 闭式论证 → analysis 问题 4 |
| 状态（战斗屏状态机 + 不变式） | design「战斗屏布局与组件·战斗屏状态机」 |
| 边界情况表（20 行） | design「提示·终局反馈·美术与可访问性·边界情况」；零合法板三形态选型 → analysis 问题 7 |
| 依赖表 + 索引分层注记 | design 依赖与输出 |
| 呈现义务台账逐项落位表（27 项，活契约） | design 依赖与输出 |
| 意图线索映射目录（B2×4① 成文载体） | design「战斗屏布局与组件」 |
| 切片教训三条硬性要求落位表（审计映射） | analysis 附录 A |
| 发现冲突清单（8 项） | analysis 附录 C（未闭合项同时以 OQ2/3/4/9 入开放问题） |
| Tuning Knobs（8 knob + 非 knob + 性能预算 + 交互 + 调参流程） | design 调参表 |
| Visual/Audio 要求 + Asset Spec 注记 | design「Visual/Audio 执行锚点」 |
| UI 要求（权威 spec / UX Flag / pattern 库 / accessibility / 场景探针） | design 依赖与输出「屏级 spec 与配套文档」 |
| 验收标准（测试口径 + AC-1–26） | design 验收标准（编号不变） |
| 覆盖矩阵（门禁评审用） | analysis 附录 B |
| 开放问题 OQ1–12 | analysis 开放问题（编号不变） |
| 版本历史（v1 / v1.0-lean / v1.1） | design 版本历史（原行全保留，追加 v2 迁移行） |