wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
737bffc9b59f6b457c81b86695deda54f2dd8442
STM32F4-Base/docs/门禁说明/ui-golden.md
T
wandering1 7099c56c34 chore(ledger): pages 批 1~4 合入后回填凭证/覆盖率并同步黄金参考计数 
task/pages-ui 合入（merge dea7591 + 修复 498cc60）：三页回炉 + SOE 页 +
四查看页 + 遥信 33 行页 + ui_data 三通道 + soe_store 只读 API + 字库与
门禁配套共 12 笔。凭证重盖（Code=224,688 / RW_IRAM1 78,992 B=60.3% /
CCM 87.9%）；覆盖率基线 39/39 套件复算。ui-golden 黄金参考 11→18 页
随批 4 扩容，AGENTS 门禁行/索引行与门禁说明两处、覆盖率口径一处同步；
两篇新详解（bom-guard/setview-check）已由道E 交付、索引去"待补"。
memset 隐式声明一条教训：分支树增量构建"0 警"不覆盖未重编文件，
done 主树全量重编才是终判。
2026-10-25 15:49:42 +08:00

5.0 KiB
Raw Blame History

ui-golden — UI 像素回归（菜单 8 状态 + 内容页 18 页黄金参考）

一句话：改 UI 源码时，把模拟器增量重编 + 两条 golden 回归串成一次提交门禁，像素对不上就拦。 它是包装器：真正的判据在被包装的两条脚本与参考图里。

  • 配置：entry: python scripts/check_ui_golden.py、pass_filenames: false、 files: 覆盖 Drivers/BSP/UI/、App/task/ui_task.(c|h)、模拟器等能改变像素的面。
  • 包装器只做三件事：跑 simulator/build_sim.bat → 跑 simulator/tests/check_menu_rows.py → 跑 simulator/tests/check_content_pages.py，透传输出与退出码。

1. 它在查什么

  • 菜单侧：整棵菜单树的行渲染结果（8 个状态）与参考图逐像素比对；
  • 内容页侧：11 个内容页的渲染结果与参考图比对；
  • 参考图 simulator/tests/ref/*.bin 就是判据本身。

2. 为什么要它（有牙的实测）

  • 两条 golden 脚本早就存在且一直人工跑，但从未进自动门禁——审查报告里自认的这个缺口， 正是"有基线 ≠ 有门禁"的教科书案例。
  • 注入实验（证明它真的会咬人）：给 ui_page_dc.c 的 .top_y 注入 +3 像素位移 → 增量重编 → golden FAIL 并点名 [dc] FAIL 与参考页不一致（1366 px 差异）、退出码 1； 还原后 diff 干净。
  • 形态选型是实测出来的：改一个 UI 源文件后，增量重编 + 两条 golden 合计 2~4 秒 → 才决定 进自动门禁。项目原则写得很清楚：若实测要几分钟，就应改为文档化的人工门禁——一个逼人 --no-verify 的门禁等于没有门禁。

3. 触发面

  • ⚠ pre-commit 4.x 没有 always: true（实测对 local 钩子只告警并跳过）→ 想"总能跑到"， files: 必须穷举所有能改变像素的入口：UI 源码、推流任务、字体生成物、模拟器源码/配置。
  • 包装器有意忽略 pre-commit 传进来的文件名参数：两条 golden 按"整棵树 + 全量参考图"工作， 不接受文件参数（所以它必须 pass_filenames: false）。
  • 依赖本机可构建模拟器（需要 Visual Studio / CMake，见 lvgl-simulator skill）→ 换机第一次跑 可能因为构建环境缺失而 FAIL，那不是 UI 有问题。

4. 报错怎么读

[ui-golden] 增量构建模拟器 ...
[ui-golden] 跑 simulator\tests\check_content_pages.py ...
[dc] FAIL 与参考页不一致（1366 px 差异）
  • 先分清两类失败：构建失败（"模拟器构建失败，无法做像素回归"→ 环境问题，先修构建）与 像素不一致（真改了显示效果）。
  • 确认显示改动是有意的，才允许按 ui-verify skill 的流程更新参考图； 任何时候都不得用刷新基线的方式让钩子变绿。

5. 好处

  • 抓的是"看不出来的错位"：白底白字、palette 头越界、位移 3 像素这类编译与单测都不报、 只有肉眼能发现的问题（两条实证坑见 docs/UI设计/UI_设计架构.md §1.4）。
  • 让"改 UI 不用手点一遍"成为可能，配合 ui-verify skill 是 UI 改动的标准回归路径。

6. 限制与盲区

  1. 参考图即判据：刷新参考图 = 修改判据。评审时必须盯 simulator/tests/ref/ 的 diff； 一旦"顺手更新"，此后所有回归都只在和错的基线比。门禁无法阻止这件事，只能靠评审。
  2. 只覆盖 8 个菜单状态 + 11 个内容页：未列入的状态（密码错误态、超长文本、缺字渲染、 无 SD 卡 / 挂载失败的降级显示）不会有任何回归。
  3. 跑的是模拟器那份配置，不是固件那份 —— 两份 lv_conf.h 漂移时，回归结论不能外推到固件 （所以 lv-conf-sync 是本门有效性的前提）。
  4. 不覆盖真机显示：面板时序、灰度、对比度、SPI 刷屏速率一概不看；像素一致 ≠ 上机正确。
  5. 动态内容（时间戳、日志页、SOE 记录）若被纳入参考图，会因数据变化误报；因此这类页面通常 在稳定数据下生成参考图 —— 数据源一变（例如月份进位）就可能假阳性。
  6. 与 font-charset 互补：那门管"有没有字形"，本门管"像素对不对"；两边都绿仍可能有布局问题 不在黄金参考集内。

7. 豁免与基线

  • 基线 = 参考图二进制；更新流程属 ui-verify skill 的一步，且必须与引起变化的 UI 改动同批提交， 提交说明里写清"为什么像素变了"。

8. 改这个门禁本身

  • 加新页面 / 新状态时，要同时扩参考图集合，否则新页面完全没有回归（不会报错，只是没覆盖）；
  • 触发面 files: 每加一类能改像素的入口就补一行，漏一类 = 那一类改动静默不跑回归。

9. 变更记录

日期 变更
2026-10-23 首篇逐项文档（含 +3 像素注入实验与"有基线 ≠ 有门禁"的缺口来源）
Reference in New Issue View Git Blame Copy Permalink