---
name: ui-verify
description: UI 改动后的回归验证：5 步门禁（模拟器构建、菜单像素回归、内容页黄金参考、Keil 构建、代码规范）。
whenToUse: Drivers/BSP/UI、字体 ui_font_cn_12.c / ui_cn_chars.txt、菜单/内容页被修改的前后（写码前先读「两条实证坑」节），或用户要求"验证 UI / 跑 UI 回归 / UI 改动检查"时。
---

# UI 回归验证

UI 相关改动完成后必须跑完 5 个门禁再提交。完整说明见 `docs/UI设计/UI_自动化测试流程.md`。

## 两条实证坑（写码前先读，模拟器照不出来）

- **I1 绘制缓冲含 8B palette 头**：布局 `[palette 8B][pixel data]`，但 LVGL 容量校验只看 `stride×h` → 只给 `stride×h` 会把末 8 字节写到缓冲外。`ui_port.c` 按 `stride×h + palette` 供给并在 flush 时 `+palette` → `docs/UI设计/UI_设计架构.md` §1.4 第 8 条
- **MCU 端必须显式应用 mono 主题**：`lv_theme_mono_init(disp, true, ...)` + `lv_display_set_theme()` + 对活动屏幕再 `lv_theme_apply()`，否则活动屏仍是默认浅灰而内容恒用白色 → **白底白字整屏纯白**（远端"纯白屏"根因）→ `docs/UI设计/UI_设计架构.md` §1.4 第 9 条

## 步骤（仓库根目录执行，python 一律用 .venv）

```powershell
cmake --build simulator/build --config Debug   # 0) 构建模拟器（须 0 警告）
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py      # 1) 菜单 8 状态像素回归 + 池基线门禁
.venv\Scripts\python.exe simulator/tests/check_content_pages.py  # 2) 内容页黄金参考回归 + 往返池门禁
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # 3) Keil 构建（BUILD_OK，0 错 0 警）
.venv\Scripts\python.exe scripts/check_coding_standard.py        # 4) 代码规范检查（PASS）
```

退出码：0=PASS / 1=断言失败 / 2=环境错误（exe 缺失等，先按 AGENTS.md 重建对应环境再重跑）。

## 失败处置决策

| 现象 | 判定 | 处置 |
|---|---|---|
| 内容页 FAIL，且**有意**改了该页视觉 | 预期变化 | 先肉眼确认新效果正确（窗口模式或 `i1_to_png.py` 出图对照 mockup），再 `.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 刷参考，`git diff` 检查 ref/ 变化后随代码提交 |
| 内容页 FAIL，但**未**有意改视觉 | bug（缺字/几何漂移/样式回归） | 修代码；**禁止**刷参考掩盖 |
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 把新值与它的实测来源写进 `docs/UI设计/UI_自动化测试流程.md` 正文常量表（2026-10-28 起不再记流水，见 `docs/文档规范.md` §5.1） |
| 菜单回归失败 | 结构断言（白带占比/边框/往返一致） | 按脚本打印的未过断言清单逐项修代码，无参考文件可刷 |

## 池水位门禁常量（在脚本头部）

| 常量 | 脚本 | 当前值 | 含义 |
|---|---|---|---|
| `MENU_POOL_BASELINE` | check_menu_rows.py | 5368 B | 菜单根框建完的 LVGL 池 used（x64 模拟器；2026-10-11 随 LVGL 控件裁剪由 4784 上移） |
| `POOL_AFTER_ROUNDTRIP` | check_content_pages.py | 5448 B | 开页-关页往返后 = 基线 + 80 B 一次性残留 |

⚠ 两个常量量的是池的 **`used`**，与 `LV_MEM_SIZE` 总大小**无关** → 改池大小（如 2026-10-15 缩池 40→16 KB）**不该动这两个数**；动了就是页面结构变化或泄漏。

**禁止为过门禁盲目改常量**——无法解释的漂移 = 内存回归 bug。

## 关联注意

- `.venv` 缺失/换机：`& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`（`requirements.txt` 已含 `pre-commit`，重建后静态门禁直接可跑）
- 新增 UI `.c` 文件先走 `new-source-file` skill 双端注册，否则一端静默缺文件
- 改 `ui_menu_tree.txt` 或界面里的中文字符串 → **同一笔**重跑生成器（`tools/menu_gen/gen_menu.py`；字体走 **font-regen** 四步），否则提交门禁 `generated-fresh` 直接拦：它把生成器拷进系统临时目录重跑、与工作区逐字节比对（实证 `0f7b5a87` 改了模板没重跑）→ `docs/门禁说明/generated-fresh.md`
- 字体重生成后全页大面积像素差异属预期：确认字形正确后 `--update` 刷参考
- 涉及新界面/大改时本 skill 是 P3 门禁，完整管线（P0~P5）见 `docs/UI设计/UI_界面制作流程.md`