merge: task/ui-golden-ui-golden-ref 合入 v2-on-ui
任务 ui-golden（1 个提交）经 task-worktree 回收： - chore(ui-golden): 像素黄金参考 ref/*.bin 入库（把门禁改成可移植）
This commit is contained in:
+10
-4
@@ -55,10 +55,15 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
`菜单页面设计.md` §9.5），再更新脚本常量并在本文变更记录登记。**禁止为过门禁盲目改常量**——
|
||||
无法解释的漂移 = 内存回归 bug。
|
||||
|
||||
## 四、黄金参考与目检 PNG（均为本地生成物，不入库）
|
||||
## 四、黄金参考（入库）与目检 PNG（本地产物）
|
||||
|
||||
`simulator/tests/ref/` 下的 `.bin`（像素黄金参考）与 `.png`（目检图）**都不入库**（`.gitignore`）——
|
||||
首次/换机后必须先生成一次：
|
||||
`simulator/tests/ref/*.bin`（像素黄金参考，11 页 × 3200 B）**随仓库入库**；派生的 `.png`
|
||||
目检图仍是本地产物（`.gitignore`）。入库的理由：比对是**逐字节**的，基线不入库时任何新克隆
|
||||
或新工作树跑 `ui-golden` 都必然 FAIL（缺基准），这条门禁就只在"有老副本的机器"上真实存在。
|
||||
可复现性实测（2026-10-22）：两份各自独立构建的 `lvgl_sim`（不同构建目录、相隔 11 天的代码）
|
||||
对同一批 11 个 `.bin` **SHA-256 全部一致** → 渲染是 CPU 侧确定性输出，基线可以进仓库。
|
||||
|
||||
换机后**不需要**再生成基准；只有有意改视觉时才 `--update`（改动会进 `git diff`）：
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update # 生成 ref/*.bin
|
||||
@@ -73,7 +78,7 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
3. **重生成目检 PNG**：`.venv\Scripts\python.exe simulator/tests/regen_ref_png.py`。
|
||||
`.png` 是本地调试产物、**不会**随 `.bin` 自动更新——不重跑则 PNG 仍是旧渲染（缺字/错位，看似"乱码"）。
|
||||
默认 `--scale 6 --invert`（深字白底便于目检）；`--no-invert` = 白字黑底（与设备一致）；
|
||||
4. 无需提交 `ref/`（已 gitignore）。
|
||||
4. **提交 `ref/*.bin` 的改动**（它已入库，等于改基准）：`git diff --stat simulator/tests/ref` 必须
|
||||
|
||||
**误刷保护**：`--update` 会**先跑文本级断言**，断言失败即中止，避免把缺字/错标签的渲染"刷成"新基准。
|
||||
|
||||
@@ -109,3 +114,4 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
| 2026-09-13 | 管线同步：`UI_界面制作流程.md` 移除 HTML 样机阶段（五阶段 → 四阶段 P0~P4），本文定位改为"P2/P3 门禁的可执行版本"；§六 关系描述更新为 P0 规格 → P1 编码 → P2 本文回归 → P3 上机目检 → P4 归档；移除 `tools/ui_mock/` 引用 |
|
||||
| 2026-10-11 | **裁剪 LVGL 死代码（F-1/F-2/F-3）时的门禁记录**：先用**未裁剪**配置 `--update` 生成 11 页黄金参考，再切到裁剪配置重编重跑 → **逐字节全部一致**（菜单 8 状态像素一致），证明裁剪零视觉影响。池水位门禁随之 5440/5520 → **5368/5448**（−72 B；一次性残留仍 80 B，故非泄漏变化，见 §三 水位历史）。顺带揪出并修掉 `Lib/lv_conf.h` 与 `simulator/lv_conf.h` 的**长期漂移**（模拟器早已 I1-only、MCU 端未裁）→ 规则见 `UI_设计架构.md` §1.4 第 10 条，量化见 `../内存管理/RAM使用分析与优化方案.md` §2.6.4 |
|
||||
| 2026-10-15 | **回归改为自洽运行（修 `netcfg_save` 假失败）**：`check_menu_rows.py` / `check_content_pages.py` 一律以**空临时目录当工作目录**跑 `lvgl_sim`（模拟器按 CWD 读写 `sim_config.ini`，残留档会改变页面内容）；`simulator/main.c` 的 `--cfgtest` 加外壳，**无论成败一律删除伪造的 4000 B 配置档**——旧行为连 PASS 路径也会留雷，之后每次 UI 回归的保存行都从 `OK` 变 `ERR`（引擎拒写超长文档，属正确行为）。脚本里"删 `sim_netcfg.bin` 残留"的旧兼容清理随之作废（旧档迁移 2026-10-10 已删），改为**只提示不删除**。修后 11 页 + 往返池水位 5,448 B 全过，**未刷任何黄金参考**；排查口径见 §五 |
|
||||
| 2026-10-22 | **`ref/*.bin` 像素黄金参考改为入库**（撤销 2026-09-10 的"整目录不入库"）：`.gitignore` 由忽略整目录收窄为只忽略 `ref/*.png`。动因是这条门禁不可移植——新克隆/新工作树里基准必然缺失，`ui-golden` 报「缺黄金参考」而不是回归结论；本仓实测两次同类踩坑（并行工作树里第一次跑必失败，只能现场 `--update` 造基准，而"现场造的基准"恰好失去意义）。入库前做了可复现性验证：主树（`ref/` 生成于 2026-10-11）与新工作树各自独立构建 `lvgl_sim`，11 个 `.bin` SHA-256 全部一致。§四 与"何时不该更新"随之改写：`--update` = 改基准，会进 `git diff`，须逐页过目并在提交正文说明 |
|
||||
|
||||
+2
-1
@@ -457,7 +457,7 @@ extern const content_page_def_t ui_page_device_info_desc; /* 描述符（Flash
|
||||
（网口设置 4 态 + 密码页 4 态等）+ 开页-关页往返水位 → 3) Keil 构建 0 错 0 警 → 4) 代码规范检查
|
||||
- **门禁常量**（脚本头部）：`MENU_POOL_BASELINE = 4784 B`、`POOL_AFTER_ROUNDTRIP = 4864 B`
|
||||
- **失败处置**：像素不一致 = 代码 bug（修代码，**禁止**刷参考掩盖）；**有意**改视觉 →
|
||||
先肉眼确认新效果正确，再 `check_content_pages.py --update` 刷参考（`ref/` 为本地生成物、不入库）
|
||||
先肉眼确认新效果正确，再 `check_content_pages.py --update` 刷参考（`ref/*.bin` 已入库，刷了会进 diff，必须一并提交并说明）
|
||||
- 新增页面后同步在 `check_content_pages.py` 增加该页的按键序列、文本断言与参考图
|
||||
|
||||
## 九、变更记录
|
||||
@@ -479,3 +479,4 @@ extern const content_page_def_t ui_page_device_info_desc; /* 描述符（Flash
|
||||
| 2026-09-10 | 网口设置页 MAC 值改常识格式 **`A4:94:B6:12:34:56`**（冒号分隔，17 字符 = 102px）；布局调整 名 x=6→4、值 x=60→54（MAC ink 止于 155，仍在白带 2..157 内）；编辑光标段偏移 MAC 2i→3i |
|
||||
| 2026-09-14 | 运行记录/自检记录动态列表页（`ui_page_runlog` / `ui_page_selftest`）：描述符新增 `count_cb` + `refresh`（开页/翻页时重读条数与内容，每条 2 行 = 时间戳/描述），数据源为 `App/log/sys_log` 引擎的 `/log/run.log`、`/log/selftest.log`；**框架不变量 selectable ⇒ band_h>0**——band_h=0 时选中行恒黑字无白带 → 黑底不可见（首版两页均踩中，改 band_h=13 对齐 AC/DC 约定）；新坑：本 LVGL 版本 `lv_text_get_width` length≠0 时无 NUL 检查，传 -1 越串尾死循环，必须传 strlen（密码页错误提示首版触发，已修并全库排查） |
|
||||
| 2026-09-15 | 网口设置页保存行改**异步交接**（P1-3 跨任务竞态修复，配置引擎属主 = defaultTask）：保存行 ENTER → `net_cfg_save_request()`（置"待保存"标志 + `SYS_EVT_CFG_SAVE` 唤醒属主任务，UI 不再直接触碰 cfg_file 引擎）；写盘与"立即应用"由 defaultTask 的 `net_cfg_save_run()` 执行（成功 → OK 并触发 `SYS_EVT_NET_RECONFIG` 免重启重建；失败 → ERR 不触发应用）；行值改随交接状态 `net_cfg_save_state()` 显示 ENTER/WAIT/OK/ERR（原为页面局部 `s_saved` 同步结果，删除）；无头自检（`--keys`）在注键后同步完成交接保持终态一致；五门禁全绿（像素/文本与改前一致，池水位不变） |
|
||||
| 2026-10-22 | §八 失败处置口径更新：`ref/*.bin` 黄金参考已入库，刷参考会进 `git diff`、必须随改动一并提交并说明理由（详见 `UI_自动化测试流程.md` §四） |
|
||||
|
||||
+3
-1
@@ -119,7 +119,8 @@ sequenceDiagram
|
||||
& '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/RemoDispBus帧格式.svg', write_to='remo.png', scale=2)"
|
||||
```
|
||||
|
||||
> PNG 属**本地派生物、不入库**（与 `simulator/tests/ref/` 的参考图一致，`.gitignore` 已含 `*.png`）。
|
||||
> PNG 属**本地派生物、不入库**（与 `simulator/tests/ref/*.png` 目检图一致，`.gitignore` 已含
|
||||
> `*.png`；注意该目录下作为像素黄金参考的 `.bin` **是入库的**，别顺手一起忽略掉）。
|
||||
|
||||
---
|
||||
|
||||
@@ -140,3 +141,4 @@ sequenceDiagram
|
||||
| 2026-09-11 | 创建：统一图形绘制流程（选型 / SVG 生成器 / Mermaid / 约定 / 检查清单）；新增 `tools/arch_diagram/gen_frame_svg.py`（通用协议帧图）+ `docs/images/RemoDispBus帧格式.svg` |
|
||||
| 2026-09-11 | 新增专门配图目录 `docs/images/`：收拢 `docs/` 根与 `docs/UI设计/images/` 下 5 张 SVG；同步更新 3 个生成器 OUT 路径、4 处文档图片引用、`AGENTS.md` 与 `.gitignore`（PNG 预览规则）；流程沉淀为 `draw-diagram` skill |
|
||||
| 2026-09-11 | 存量 ASCII 框图清理：`STM32F4-Base存储架构说明.md` 两图（存储栈分层 / 物理分区布局）重绘为 SVG（生成器家族新增 `gen_storage_stack_svg.py` / `gen_partition_svg.py`）；`RemoDispBus协议与接收设计说明.md` 删 ASCII 帧图（SVG 帧格式图已在，信息无损失）；`测试说明/CH395F_Test_Guide.md` 4 图（2 组件架构 + 2 会话时序）转 Mermaid |
|
||||
| 2026-10-22 | 澄清 §派生物一句：`simulator/tests/ref/` 下作为像素黄金参考的 `.bin` 已入库，只有派生的 `.png` 目检图仍不入库（原表述把两者混为"参考图不入库"，会诱导后来者把整个目录继续忽略掉） |
|
||||
|
||||
@@ -378,8 +378,8 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
|
||||
### 5.3 黄金参考与字体纪律
|
||||
|
||||
- `simulator/tests/ref/`（`.bin` 参考 + `.png` 目检图）**不入库**：首次 / 换机先 `check_content_pages.py --update` 生成；
|
||||
- `--update` 有**误刷保护**（先跑文本层断言，失败即中止）——**未有意改视觉而 FAIL = bug，修代码，禁止刷参考掩盖**；
|
||||
- `simulator/tests/ref/*.bin`（像素黄金参考）**入库**（2026-10-22 起，新克隆即可跑回归；跨独立构建目录逐字节可复现已实测）；派生的 `.png` 目检图仍不入库；
|
||||
- `--update` 有**误刷保护**（先跑文本层断言，失败即中止）——**未有意改视觉而 FAIL = bug，修代码，禁止刷参考掩盖**；基线入库后刷参考会在 `git diff` 里显形，必须逐页过目并在提交正文说明；
|
||||
- 刷新参考后必须重跑 `regen_ref_png.py` 重生成目检 PNG（否则旧 PNG 看似乱码）；
|
||||
- 门禁常量漂移：先确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新常量 + 在 `UI_自动化测试流程.md` 变更记录登记；
|
||||
- **UI 新增中文文案提交前必须先跑 font-regen**（extract_cn → make_font → diff 检查）：字符集 `ui_cn_chars.txt` 缺字则上机显示空白——**2026-10-15 起该约定已入门禁**（`font-charset` 钩子：源码在用字符 ∉ txt 或 txt ∉ 字体 cmap → 提交 FAIL，详见 `docs/门禁说明/font-charset.md`）。
|
||||
@@ -640,3 +640,4 @@ CI 就静默停摆（2026-10-11 实测 run 16~21 共 12 个 job 零日志）。
|
||||
| 2026-10-01 | §4.2 补 **L0.5 环境要求表**（MSVC `cl.exe` = 装了 VS 即有、与模拟器共用；Windows SDK；纯标准库 Python；缺失时退出码 2 且 pre-commit 钩子拦截）+ "不调 `vcvars64.bat`（`reg.exe` 受限）"原因说明；§4.1 工具清单标注该运行器需 VS。同步更新 `../环境与部署/项目部署环境要求.md`（§2.3 / §2.7 / 第 3、10 步 / 清单 / 下载表 / 速查表） |
|
||||
| 2026-09-15 | §3.4 更新：P1-6 修复落地（基础线程策略）——USER CODE 区冗余 netTask 创建删除 + `net_task_func` 入口 `ENABLE_HW_LAYER_TESTS` 自挂起守卫；"代码事实/设计约束"按修复后现状重写（硬件层模式中断断言恢复安全、NET 层/产品仍按"netTask 恒在轮询"设计）；彻底方案（`.ioc` 移除）经评估未采用。同日构建验证发现两处**存量**测试固件缺陷（与 P1-6 无关，A/B 对照确证）：① `net_test_task.c` `s_rx_buf` 使用先于声明 → NET 层配置自 2026-08（88160a5）起不可编译；② 128KB 静态 RAM 预算溢出（产品镜像 123.6KB，HW 全阶段固件超 8.7KB、NET 固件超 ~28KB）——已立 P1-9/P1-10 跟踪 |
|
||||
| 2026-09-13 | 重写：对齐现测试架构——统一 `test_config.h` 套件（旧版仅描述 CH395F 单套件与 `ch395fTestTask` 旧入口）；新增 @test 自动化闭环、pre-commit 门禁、UI 模拟器五步门禁、主机侧工具约定；新增"测试构建下 netTask"已知问题（旧版"硬件层模式 netTask 不创建"表述与代码不符，改为设计约束并给出重构路径）；修正附录路径（旧版 `docs/测试说明/CH395F_Test_Guide.md` 等已移入 `docs/测试说明/`）；新增双端注册、内存预算、陷阱沉淀要求 |
|
||||
| 2026-10-22 | §5.3 黄金参考纪律更新：`ref/*.bin` 入库（新克隆即可跑 UI 像素回归）、`.png` 仍不入库；补充"刷参考会在 `git diff` 显形，须逐页过目并在提交正文说明" |
|
||||
|
||||
@@ -360,8 +360,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
|
||||
@@ -615,7 +614,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 后重新下载 |
|
||||
@@ -669,3 +668,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` 造基准） |
|
||||
|
||||
Reference in New Issue
Block a user