跳转至

UI/原型改动必须实测 —— 证据三档与四道锁

触发场景:任何改布局(滚动/高度/缩放/间距)、视觉(颜色/层级/字号)或产出原型页(demo/prototype HTML)的任务。 起因:v0.16.61(2026-09-23)任务页滚动条修复只交了「flex 高度链推理 + jsdom 全绿」,Tony 第二天发截图「你自己看」——窗口级粗滚动条还在。jsdom 没有 CSS 引擎,量不出真实溢出;推理写得再漂亮也代替不了一次 --dump-dom。dogfood 一次踩坑 = 一条 rule。

核心问题

jsdom 测试绿 ≠ 实测过。jsdom 不加载 Tailwind、不解析 CSS 变量、没有真实排版引擎——它能验逻辑与契约(钉 className/内联值),量不出布局真相(谁溢出、谁滚动、谁被裁)。同理:审查员的「类名推演」再严密也是 UNVERIFIED,不是证据。

证据三档(什么算实测)

档 手段 适用 不适用
L1 jsdom 单测(vitest) 逻辑/契约/文案断言 ❌ 不算实测(无 CSS 引擎)
L2 真浏览器 harness:tests/layout/*.html + headless Chrome --dump-dom 自扫断言 布局链改动:宽度/高度/缩放/滚动/换行矩阵 纯逻辑改动不需要
L3 真实加载视觉证据:扩展改动 = dist 构建 + chrome://extensions 重载 + 截图;原型/静态页 = chrome --headless --screenshot=out.png --window-size=W,H file://… 视觉级改动(间距/颜色/层级/呼吸感)的最终验收 —

分档规则:改滚动/高度/缩放 → 至少 L2;改颜色/间距/层级 → L3 截图收尾;原型产出 → 一律 L3。L2 的 harness 断言必须写失败形态(如 scrollHeight ≤ clientHeight,而不是「看起来对」)。

四道锁(如何确保不再犯)

  1. 任务书锁:派前端/原型活的任务书必须含「实测交付物」字段——L2 给 harness 命令 + 断言输出,L3 给截图路径。没有实测项的 UI 任务书 = 不合格,写手有权拒收。
  2. 审查锁:审查 UI diff 时必须核实测证据存在且覆盖断言;纯推理结论一律标 UNVERIFIED,不得据此给 GO。
  3. 门禁锁:布局 harness 进 tests/layout/;能套 scan.mjs 宽度循环的注册进 PAGES,套不进的(如高度×缩放矩阵)做自扫式并在头部注释说明原因。收口时 harness 输出贴进 changelog。
  4. 收口锁:changelog 的 UI 条目必须引用实测证据(harness 输出摘要/截图说明)。写了「推理上不会再出」而没证据的条目会被下一把刀打脸——v0.16.61 就是前例。

已有基建(直接复用)

  • tests/layout/scan.mjs + row-layout-harness.html / data-bar-harness.html:宽度矩阵自扫的样板(ISSUE-0177 沉淀)
  • full-layout-harness.html(v0.16.62):缩放×窗高矩阵,断言「无窗口级滚动条 + 各列自持」——就是本条 rule 的起因刀
  • Chrome headless 自带 --screenshot / --dump-dom,零依赖