chore(ui-golden): 像素黄金参考 ref/*.bin 入库(把门禁改成可移植)

问题:ui-golden 是逐字节比对(check_content_pages.py 里 data == refdata),
而基准 simulator/tests/ref/ 整目录被 .gitignore 忽略、从未入库。后果不是
"少几个文件",而是这条门禁在任何新克隆 / 新并行工作树里必然报「缺黄金
参考」——只在有老副本的机器上它才是真的回归门禁。本会话已两次实测踩到
(并行工作树里只能现场 --update 造基准,而现场造出来的基准恰好失去意义)。

入库前先证明基线可复现,否则等于把一条天天误报的门禁写进仓库:
- 主树 ref/ 生成于 2026-10-11,其间合入 B6~B9 与 UI 令牌化等多次改动;
  今天用刚重建的 lvgl_sim 重跑 → 11 页 + 开页-关页往返池水位逐字节全过
- 主树与新工作树两份**独立构建**的 lvgl_sim(不同构建目录、不同绝对路径)
  各自生成基准 → 11 个 .bin 的 SHA-256 全部一致
即渲染是 CPU 侧确定性输出,可以当仓库内容。

改动:
- .gitignore:整目录忽略 → 只忽略派生的目检 PNG。另加一条
  !simulator/tests/ref/*.bin 反选——第 115 行的全仓 *.bin 兜底(挡
  sim_netcfg.bin 之类运行产物)会把基线一起挡掉,且反选必须排在它之后
  才生效
- 不引入 LFS:11 x 3200 B = 34.4 KB(160x160 单色打包)。走 LFS 反而新增
  失效面——没拉 LFS 的克隆会拿 pointer 文本去比像素,把"缺基准"换成
  "比不中"。.gitattributes 已有 *.bin binary,check-attr 确认 text unset,
  不会被行尾转换改写
- 基线不会被改写型钩子毁掉:trailing-whitespace / end-of-file-fixer 声明
  types: [text],位图含 NUL 被判二进制 → 实测 Skipped;索引 blob、磁盘、
  主树参照三方哈希 11/11 一致
- 新增 11 个基线;同步 5 份文档与 3 处脚本口径:缺基准的提示从"首次/换机
  请加 --update"改为"检出不完整 → git checkout -- simulator/tests/ref/ 取回,
  不要用 --update 就地造基准"(旧提示正是自我实现型基准的来源)
- 顺带修掉 simulator/tests/README.md 两处与实现不符的描述:基准写成 PNG
  (实为 .bin)、regen_ref_png.py 写成"重建黄金参考"(它只出目检图,基准
  由 check_content_pages.py --update 刷)
- .pre-commit-config.yaml 只改注释(原文明确断言 ref/ "永远不会进 git
  索引",已被本改动推翻);ui-golden 的 files 面覆盖 simulator/tests/,
  基线被改即触发回归,刷参考从此在 git diff 里显形

历史口径按纪律冻结:UI_自动化测试流程 2026-09-10 的"整目录不入库"等 6 处
变更记录行不改写,以新行登记反转。

实测:@build 0 错 0 警(Code=213520,与内存台账一致);ui-golden Passed;
pre-commit run --all-files = 36 Passed / 0 Failed(RC=0)。
This commit is contained in:
2026-10-22 06:17:00 +08:00
parent ebe2807ffd
commit a38f862fb9
21 changed files with 52 additions and 23 deletions
@@ -356,8 +356,7 @@ pre-commit run --all-files # 首次全库基线扫描
& "simulator\build_sim.bat" # 模拟器一键构建(自动探测 VS 版本),0 警告
.\simulator\build\Debug\lvgl_sim.exe # 出 160×160 单色菜单画面
& '.venv\Scripts\python.exe' simulator\tests\check_menu_rows.py # PASS
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update # 首次生成参考图
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py # 再跑 → PASS
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py # PASS(基准 ref/*.bin 已入库,无需先生成)
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py selftest # → SELFTEST PASS
& '.venv\Scripts\python.exe' test\host\watchdog\run_unit_test.py # 主机侧单测 → 39/39 PASSED(退出码 0)
pre-commit run --all-files
@@ -613,7 +612,7 @@ $env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话,不动用户级
| `.venv` 不存在 / 脚本 ModuleNotFound | venv 未建(不入库) | 按 §2.4 重建 + `pip install -r requirements.txt` |
| pip 装依赖报 UnicodeDecodeError | `requirements.txt` 含中文注释 | 保持该文件**纯 ASCII**(pip 按 GBK 代码页解码) |
| 字体生成 / 转 PNG 报缺模块 | 误用 PATH 里的 msys64 python | 一律用 `.venv\Scripts\python.exe` |
| 内容页回归 exit 2(参考缺失) | `tests/ref/` 是本地生成物、不入库 | 先 `check_content_pages.py --update` 生成参考,再跑回归 |
| 内容页回归 FAIL「缺黄金参考」 | `ref/*.bin` 已入库 → 缺失 = 检出不完整(被手工删过 / 不完整的 worktree 副本),**不是**"首次运行" | `git checkout -- simulator/tests/ref/` 取回基准;**不要**用 `--update` 就地造基准(那等于把当前渲染固化成基准) |
| 串口采集不到 / 端口占用 | COM 号变化 / 上一进程未释放 | 改 `.serialtest/config.json`;`serial_tool.py ports` 查实际端口,`open` 占用 ≤1s 报 `port busy` |
| 烧录失败 | 下载器未选 / USB 驱动缺失 | Keil `Options for Target → Debug` 选对驱动;安装下载器 USB 驱动 |
| 下载报 Flash 算法 / FLM 文件找不到 | 未安装 `Keil::STM32F4xx_DFP` pack(FLM 来自 pack 目录,不在仓库) | Pack Installer 安装该 pack 后重新下载 |
@@ -666,3 +665,4 @@ $env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话,不动用户级
| 2026-09-13 | 补 STM32CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3(与 .ioc 一致):拓扑图 / §2.2 / 第 2 步 / §2.9 / 搭建清单,常见问题速查增加再生成版本不匹配条目 |
| 2026-09-13 | 新增"Keil 初始化配置(机器侧项,非项目自带)":license / Device Pack(含 FLM 来源解析路径)/ 下载器驱动,并列出项目自带免配置项;§六 速查补 FLM 缺失、license 过期两条 |
| 2026-09-13 | 补 RAM/Flash 链接布局说明:手动 scatter 文件 `STM32F407-Demo.sct`(在仓库)为链接依据(128KB = SRAM1+SRAM2,SRAM3/CCM 未映射),新机器无需重设、勿改 GUI Target 页 |
| 2026-10-22 | 换机自检去掉「首次须 `--update` 生成参考图」一步(`simulator/tests/ref/*.bin` 已入库,检出即带基准);排障表「内容页回归参考缺失」一行改为按"检出不完整"处置(`git checkout -- simulator/tests/ref/`,禁止就地 `--update` 造基准) |