wandering1
dc44c1e54e
用户诉求原话："现在门禁都在干什么，我一概不知。" 原有文档回答"有哪些钩子、怎么配"，回答不了 "这一条到底在拦什么、什么时候会骗我"。本目录按**每种门禁一篇**补齐 23 篇（39 个 hook id 全覆盖： 16 个主机单测是同机制 16 实例合一篇；cppcheck 与 test-cppcheck 是同工具两套范围合一篇）， 文件名用 hook id，与提交输出里的名字一致、可 grep。 八段固定结构：查什么 / 为什么要它（拦下过什么真事）/ 触发面 / 报错怎么读 / 好处 / **限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。最后一节是这批文档存在的理由—— 只看"拦了什么"的文档会让人以为绿就是对的；本仓三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、 id-check 台账 640 处）的绿灯含义只是"没比上次更差"。README 另立"三种拦截姿态"一节：改写型 / 硬拦截 / 增量拦截，分清才知道报错时该改代码还是该还基线。 有实证的地方全部带数字，没实证的地方直接写"预防性、未记录到实际拦截案例"（不编故事）： · cppcheck：把 simulator/ 纳入受检后立刻揪出 sim_syslog.c 真实空指针；test/ 曾有 s_rx_buf 使用先于声明；**并记入两条实测负结果**——它对 14 处丢弃 HAL_SPI_* 返回值与"未初始化局部量 进 P_FAIL 判定"一条不报（这正是 consume-result 的由来）。 · lv-conf-sync：漂移导致 64,576 B 死代码入库（旧镜像的 23.5%），且 golden 跑的是模拟器那份配置。 · cubemx-survival：2026-09-29 一次重生成覆盖 4 处定制（P0×1+P1×2+P2×1），且不报编译错。 · registration-check：rs485_task.c、lftpd_log.c 两处都没注册 = 从不参与编译的死代码；第四类 "页面描述了但没接进 s_defs[] 表"编译链接全过，前三类完全照不出。 · test-suite-switch：实测已提交的 HEAD 里 TEST_SUITE_CH395F 就是开着的，.map 含 34 处 test 代码。 · task-table：2026-09 两张表都比源码落后一大截（写 2048/4096/…/16384，实际 1024…512）。 · mem-numbers：2026-09-26 复核，文档写 82,048 B / 62.6%，实际 87,040 B / 66.4%；Flash 写 249,432 / 23.8%，实际 261,932 / 25.0%。 · ui-golden：注入 .top_y +3 像素 → golden FAIL 点名"1366 px 差异"、退出码 1；并把"有基线 ≠ 有门禁"与"逼人 --no-verify 的门禁等于没有门禁"两条选型依据写进去。 · check-yaml：本仓已移除的 always 键只告警 Unexpected key(s) 然后忽略——配置"看起来生效其实没 生效"而本门全绿，所以验收方式是实跑看目标钩子是 Passed 还是 Skipped。 · no-mojibake：types: [c] 只管 C/H，**文档侧乱码无人管**——覆盖面与需求错配定性写进限制一节。 盲区写法示例（每篇都要求写真实限度，不留空）：layer-deps 只查直接 include、按 basename 匹配、 不查是否真的用到；font-charset 管不到运行期拼出来的字符串与配置文件里的字；host-unit-tests 用宿主 编译器、桩是第二份真相、include_dirs 手写、没有对应钩子的模块等于零回归；mem-budget 的 92% 是管理 阈值不是安全余量、.map 缺失即"通过式跳过"；registration-check 不看条件编译与注册指向是否正确； coding-standard 的 CODE-RULE-17 在无配对头时跳过、规则编号 14 作废不回收。 写文档过程自己被自家门禁拦了两轮，都按规矩改而不是绕过： ① doc-links 拦下我自己——我在解释"写 §数字 而没紧邻文档名会被判成本文自引用"这段话里，正好 就犯了这个写法（两处），另有一处示例输出未标记；改成正例写法 + [示例] 标记。 ② id-check 拦下 7 类新账：示例报错行里的号、档号引用未紧邻文档名、说明"裸形不合规"时自己写了 裸形。全部改成平实描述或补文档名、给样例加 [示例]，没有一条是往台账里塞 reason 解决的。 这两次本身已写进相关篇目的"限制/变更记录"，是这套文档最实在的注脚。 同步：手册 pre-commit使用说明.md 的 §2 顶部加指针（逐项详解已迁往本目录；两处收敛为"通用机制 + 总览 + 指针"排在 docs/门禁说明/README.md §4 的下一步，并注明收敛要按内容重指既有引用——只核编号 存在与否不够）；README 索引 23 行状态全部置为已写、文档列改为可达链接。 验证：纯文档，不动代码与构建产物；check_doc_links --all --sections-strict **171 篇 0 问题** （新目录 24 个文件的内部链接与跨文档引用都纳入判定）；id-check --strict 增量拦截通过；本次受影响 文件 pre-commit run **RC=0**；24 个文件字节卫生 0 异常（无 BOM、无 CR、无 U+FFFD、均有尾换行）。
5.0 KiB
5.0 KiB
ui-golden — UI 像素回归（菜单 8 状态 + 内容页 11 页黄金参考）
一句话：改 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-simulatorskill）→ 换机第一次跑 可能因为构建环境缺失而 FAIL，那不是 UI 有问题。
4. 报错怎么读
[ui-golden] 增量构建模拟器 ...
[ui-golden] 跑 simulator\tests\check_content_pages.py ...
[dc] FAIL 与参考页不一致（1366 px 差异）
- 先分清两类失败：构建失败（"模拟器构建失败，无法做像素回归"→ 环境问题，先修构建）与 像素不一致（真改了显示效果）。
- 确认显示改动是有意的，才允许按
ui-verifyskill 的流程更新参考图； 任何时候都不得用刷新基线的方式让钩子变绿。
5. 好处
- 抓的是"看不出来的错位"：白底白字、palette 头越界、位移 3 像素这类编译与单测都不报、
只有肉眼能发现的问题（两条实证坑见
docs/UI设计/UI_设计架构.md§1.4）。 - 让"改 UI 不用手点一遍"成为可能，配合
ui-verifyskill 是 UI 改动的标准回归路径。
6. 限制与盲区
- 参考图即判据：刷新参考图 = 修改判据。评审时必须盯
simulator/tests/ref/的 diff； 一旦"顺手更新"，此后所有回归都只在和错的基线比。门禁无法阻止这件事，只能靠评审。 - 只覆盖 8 个菜单状态 + 11 个内容页：未列入的状态（密码错误态、超长文本、缺字渲染、 无 SD 卡 / 挂载失败的降级显示）不会有任何回归。
- 跑的是模拟器那份配置，不是固件那份 —— 两份
lv_conf.h漂移时，回归结论不能外推到固件 （所以lv-conf-sync是本门有效性的前提）。 - 不覆盖真机显示：面板时序、灰度、对比度、SPI 刷屏速率一概不看；像素一致 ≠ 上机正确。
- 动态内容（时间戳、日志页、SOE 记录）若被纳入参考图，会因数据变化误报；因此这类页面通常 在稳定数据下生成参考图 —— 数据源一变（例如月份进位）就可能假阳性。
- 与
font-charset互补：那门管"有没有字形"，本门管"像素对不对"；两边都绿仍可能有布局问题 不在黄金参考集内。
7. 豁免与基线
- 基线 = 参考图二进制；更新流程属
ui-verifyskill 的一步，且必须与引起变化的 UI 改动同批提交， 提交说明里写清"为什么像素变了"。
8. 改这个门禁本身
- 加新页面 / 新状态时，要同时扩参考图集合，否则新页面完全没有回归（不会报错，只是没覆盖）；
- 触发面
files:每加一类能改像素的入口就补一行，漏一类 = 那一类改动静默不跑回归。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-23 | 首篇逐项文档（含 +3 像素注入实验与"有基线 ≠ 有门禁"的缺口来源） |