wandering1
e771a8ea21
navtool 合入（3e03375）带进第 49 个钩子 uinav-selftest（快检档，专篇待补、 指针指向 UI_自动化测试流程 §7.3 正文）；门禁 README 索引头 42/25 系批 2 两批钩子未追平，本次一并核账为 49/26+1 指针，主机单测行 16→22（含批 2 六新套）；AGENTS 两处计数与新增括注同步。纯计数与索引，无口径变化。
79 lines
9.3 KiB
Markdown
79 lines
9.3 KiB
Markdown
# 门禁逐项说明（每种门禁一篇）
|
||
|
||
> 这一目录回答一个问题：**提交时那 49 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。**
|
||
> 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 /
|
||
> **限制与盲区** / 豁免与基线 / 改门禁本身要注意什么。**最后一节是这套文档存在的理由**——
|
||
> 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
|
||
|
||
- 配置事实源：`.pre-commit-config.yaml`（39 个 `- id:`，2026-10-23 清点）。
|
||
- 通用机制（两阶段、stash 陷阱、`always` 已废、增量拦截三段式、旧 §2.x 查号表）：
|
||
`docs/代码规范/pre-commit使用说明.md` §2。
|
||
- 快速自查（不等提交）：`& '.venv\Scripts\python.exe' scripts/ci_local.py`（L0 + L0b + L0.5）。
|
||
|
||
## 1. 三种拦截姿态（先分清这个，报错时才知道该干什么）
|
||
|
||
| 姿态 | 含义 | 有哪些 | 失败时该做什么 |
|
||
|---|---|---|---|
|
||
| **改写型** | 不报错，直接改你的文件 | `trailing-whitespace`、`end-of-file-fixer` | 重新 `git add` 被改的文件再提交（它改的是工作区，不是索引） |
|
||
| **硬拦截** | 违反即失败，没有存量豁免 | `cppcheck`、`coding-standard`、`doc-links`、`no-mojibake`、`mem-budget`、`ui-golden`、`font-charset`、`lv-conf-sync`、`task-table`、`mem-numbers`、`registration-check`、`cubemx-survival`、`test-suite-switch`、16 个主机单测、官方 5 个、`gitlint` | 只能改代码或改文档；**不要**找豁免开关 |
|
||
| **增量拦截** | 规则恒生效，但存量钉在基线/台账里，只许减不许增 | `layer-deps`（3 条，2026-10-25 还清 UI 记录 3 条）、`bsp-err`（38 条）、`id-check`（`scripts/id_known_backlog.json` 台账） | 报错先分清是**新增**还是**存量搬家**：`--verbose` 看归类，`--prune` 看已还清 |
|
||
|
||
⚠ 增量拦截最容易误会的一点：**绿灯不等于没问题**，只等于"没有比上次更差"。
|
||
每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
|
||
|
||
## 2. 索引（49 个 hook → 26 篇 + 1 根在 docs/测试说明/）
|
||
|
||
| 门禁文档 | 覆盖的 hook id | 一句话它在查什么 | 改了哪类文件才会跑 | 文档 |
|
||
|---|---|---|---|---|
|
||
| [`bsp-err.md`](bsp-err.md) | `bsp-err` | BSP 的对外 API 面：错误通道类型、超时宏命名、必须写返回值、返回值不得裸丢弃 | `Drivers/BSP/**` 或门禁自身 | 已写 |
|
||
| [`layer-deps.md`](layer-deps.md) | `layer-deps` | 分层方向：`Drivers/BSP/**` 不得 include `App/**` | `Drivers/BSP/**` | 已写 |
|
||
| [`id-check.md`](id-check.md) | `id-check` | 实体编号的八项校验（未登记前缀、裸形、重复定义、孤儿、悬空引用…） | 几乎所有文本文件 | 已写 |
|
||
| [`doc-links.md`](doc-links.md) | `doc-links` | 文档里的路径引用是否存在；`--sections-strict` 另查章节号是否还存在 | 任意 `.md` | 已写 |
|
||
| [`cppcheck.md`](cppcheck.md) | `cppcheck`、`test-cppcheck` | 静态分析（真机侧与 `test/` 侧两套范围与抑制项） | C/H 源文件 | 已写 |
|
||
| [`coding-standard.md`](coding-standard.md) | `coding-standard` | 编码规范 V1.0 的可机械检查子集（命名、头文件保护宏、模块头注释块…） | C/H 源文件 | 已写 |
|
||
| [`no-mojibake.md`](no-mojibake.md) | `no-mojibake` | 禁 `U+FFFD`——中文被按错误编码重解码后不可逆损坏的痕迹 | 全部文本 | 已写 |
|
||
| [`mem-numbers.md`](mem-numbers.md) | `mem-numbers` | 文档里引用的 RAM/Flash 数字与最新 `.map` 报告是否一致（体积档） | `docs/内存管理/**`、相关脚本 | 已写 |
|
||
| [`mem-budget.md`](mem-budget.md) | `mem-budget` | RAM 总量红线：`RW_IRAM1` / `RW_CCM` 超 92% 即拦 | 代码与配置改动 | 已写 |
|
||
| [`task-table.md`](task-table.md) | `task-table` | README/AGENTS 里的任务表是否与 `Src/freertos.c` 一致 | `README.md`、`AGENTS.md`、`Src/freertos.c` | 已写 |
|
||
| [`registration-check.md`](registration-check.md) | `registration-check` | 新 `.c` 是否双端注册（Keil 工程 + 模拟器 CMake）；UI 页面描述符表是否接线 | `.c`、`.uvprojx`、`CMakeLists.txt` | 已写 |
|
||
| [`lv-conf-sync.md`](lv-conf-sync.md) | `lv-conf-sync` | 两份 `lv_conf.h`（MCU / 模拟器）的特性子集是否一致 | 两份 lv_conf 或脚本 | 已写 |
|
||
| [`cubemx-survival.md`](cubemx-survival.md) | `cubemx-survival` | CubeMX 重生成会不会把定制静默抹掉（L3 审计兜底） | `.ioc`、`Src/`、`Inc/` | 已写 |
|
||
| [`test-suite-switch.md`](test-suite-switch.md) | `test-suite-switch` | 板级套件开关必须互斥；全注释 = 产品构建 | `test/board/test_config.h` | 已写 |
|
||
| [`font-charset.md`](font-charset.md) | `font-charset` | UI 用到的汉字是否都在子集字体里（缺字 = 白框） | `Drivers/BSP/UI/**`、字体脚本 | 已写 |
|
||
| [`ui-golden.md`](ui-golden.md) | `ui-golden` | UI 像素回归：菜单 8 状态 + 内容页 18 页黄金参考图比对 | UI 源码、模拟器 | 已写 |
|
||
| [`bom-guard.md`](bom-guard.md) | `bom-guard` | 带 BOM 的文件被编辑工具剥掉 BOM（ARMCC 换解码 → 假语法错） | `Drivers/BSP/UI/**` 等名单内文件 | 已写 |
|
||
| [`setview-check.md`](setview-check.md) | `setview-check` | 定值查看行表与 `prot_set` 枚举序 / `g_prot_set_meta` 上下限是否同一份口径 | `tools/setview_check/**`、`ui_w_setview.*` | 已写 |
|
||
| （专篇待补，档位与限度正文在 [`../UI设计/UI_自动化测试流程.md`](../UI设计/UI_自动化测试流程.md) §7.3） | `uinav-selftest` | 板端 UI 导航器认屏快检（黄金参考帧分类；完整闭环档=合入前/上板前手工跑，快检不互替） | `scripts/board_ui_nav.py`、`simulator/tests/ref/*.bin` | 指针 |
|
||
| [`host-unit-tests.md`](host-unit-tests.md) | 22 个 `*-unit-test` | 主机侧单测（同一机制 22 个实例）：逻辑层在无硬件的 PC 上编译并跑断言 | 各自被测模块与其测试目录 | 已写 |
|
||
| 详解在 [`../测试说明/主机单测覆盖率口径.md`](../测试说明/主机单测覆盖率口径.md)（口径 / 分母 / 基线 / 盲区都在那篇，本目录不重复） | `test-coverage` | **覆盖率总闸**：跑全部 28 套主机单测 + 已覆盖行只增不减的回退台账 | `App/`、`Drivers/BSP/`、`test/host/`、脚本与基线 | 已写（在 `docs/测试说明/`） |
|
||
| [`trailing-whitespace.md`](trailing-whitespace.md) | `trailing-whitespace` | 行尾空白（改写型；CubeMX/Keil 生成文件豁免） | 全部 | 已写 |
|
||
| [`end-of-file-fixer.md`](end-of-file-fixer.md) | `end-of-file-fixer` | 文件末尾必须恰好一个换行（改写型；同豁免） | 全部 | 已写 |
|
||
| [`check-added-large-files.md`](check-added-large-files.md) | `check-added-large-files` | 别把大文件（日志/镜像/二进制）误提进仓库 | 全部 | 已写 |
|
||
| [`check-merge-conflict.md`](check-merge-conflict.md) | `check-merge-conflict` | 别把没解完的冲突标记（`<<<<<<<`）提上去 | 全部 | 已写 |
|
||
| [`check-yaml.md`](check-yaml.md) | `check-yaml` | YAML 语法是否可解析（门禁配置自己坏了会静默不跑） | `.yml`/`.yaml` | 已写 |
|
||
| [`gitlint.md`](gitlint.md) | `gitlint` | 提交信息规则：标题长度、**正文每行 ≤80**、空行要求 | 提交信息（commit-msg 阶段） | 已写 |
|
||
|
||
## 3. 每篇文档的固定八段
|
||
|
||
1. **它在查什么**——逐条判据，能对着代码复核的粒度；
|
||
2. **为什么要它**——它拦下过什么真事，没有它会怎样（没有真事的门禁要老实写"预防性"）；
|
||
3. **触发面**——`files:` / `exclude:` / `pass_filenames` / 阶段，以及**看不见哪些文件**；
|
||
4. **报错怎么读**——样例输出、怎么单独跑、常见"假报警"（含 stash 陷阱）；
|
||
5. **好处**——它把哪件事从"口头约定"变成了机器判定；
|
||
6. **限制与盲区**——什么写法能骗过它、什么错它照不到、判据的启发式在哪里；
|
||
7. **豁免与基线**——白名单形状、在册数量、还债口径（只减不增）；
|
||
8. **改门禁本身**——自测怎么做、改名会波及什么（例如基线键）、为什么不许拿基线洗假阳性。
|
||
|
||
## 4. 现状与下一步
|
||
|
||
- **本目录 23 篇已全部成文**（上表「文档」列 = 覆盖的 hook id，全部可达）。
|
||
- 新增/改动一个门禁时的三步：① 在 `.pre-commit-config.yaml` 落地；② 在本目录**照八段结构
|
||
新增或更新一篇**（"限制与盲区"一节必须写真实判据的限度，不许留空）；③ 在本 README 索引加一行。
|
||
- **收敛已完成（2026-10-23）**：`docs/代码规范/pre-commit使用说明.md` 的原 §2「各钩子规则详解」
|
||
（27 个小节、约 480 行）已删除，本节改为 `docs/代码规范/pre-commit使用说明.md` §2 —— 只留**跨钩子的
|
||
通用机制**（两阶段、stash 陷阱、`always` 已废、改写型与只读型豁免不对称、增量拦截三段式、
|
||
没有 `.map` 即跳过、配置自己坏的验收方式、新增门禁三步）与**旧 §2.N → 新文档 查号表**。
|
||
同一事实只留一处（`docs/文档规范.md` 的要求）。
|
||
- 收敛时按**内容**重指了引用：skill 与 AGENTS 文档表、配置文件头注释、手册自己的文件清单行与 §5.5
|
||
里那句"判定见旧小节 2.8"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。
|