STM32F4-Base/docs/门禁说明/README.md

门禁逐项说明（每种门禁一篇）

本目录逐项说明各门禁：声明的 51 个钩子到底在干什么、拦谁、放谁、什么时候会骗人——其中 3 根慢钩子带 stages: [manual]，一次 git commit 只实跑 48 根（口径见下条）。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。

• 配置事实源：.pre-commit-config.yaml。钩子数的唯一口径 = YAML 解析后的 hook 条目数，不是文件里的文本行数。 自查（打印声明数；加/删一条钩子后，这个数要与 AGENTS.md 的「共 N 个钩子」、本目录 §2 标题同时对齐）： & '.venv\Scripts\python.exe' -c "import yaml; d=yaml.safe_load(open('.pre-commit-config.yaml', encoding='utf-8')); print(sum(len(r['hooks']) for r in d['repos']))" → 51（2026-10-26：49 → 50 加 generated-fresh；2026-10-27：50 → 51 加 nested-comment； 2026-10-28：51 → 52 加 id-check-new、随即 52 → 51 摘掉 id-check（退役全库语料审计））。 ⚠ 别用 grep -c 去数配置里的声明行：该文件里有一条注释掉的候选钩子（clang-format，第 65 行）， 文本 grep 会多算 1 = 52——「声明 52 / 文档 51 / 实跑 51」这种三个数不同源的争执就是这么来的。真要 grep， 用锚定行首缩进的模式（它天然跳过以 # 开头的注释行）2026-10-28 实测直接得 51，与 YAML 口径一致； 会多算 1 = 52 的是不锚定行首、按子串匹配声明行的写法（那条被注释掉的候选也被它算进去）。 ⚠ 反过来的坑也真踩过（2026-10-27）：在配置注释里复述那个 grep 字面量，会让文本 grep 再虚高 1—— 数数只认 YAML 解析，注释与文档里都别写出那个字面量（docs/门禁说明/nested-comment.md §8 记了现场）。 实跑侧口径：scripts/ci_local.py 的静态门禁汇总行 [SUMMARY] …: pre-commit hooks -- passed=A failed=B skipped=C（方括号里那一段是层级名，脚本输出与文档层的语义名正分头迁移 → 抓这行按 passed= 字段匹配，别把层级名前缀写死进字面量，否则会 grep 不到而误判「没有实跑数」）， A+B+C = commit 阶段的钩子数（47 = 51 − 3 根 stages: [manual] − gitlint），再加 gitlint 1 条（它的 commit-msg 阶段声明写在上游仓库自带的钩子清单里，本配置文件里查不到，见 scripts/ci_local.py 文件头） → 47 + 1 = 48 = 一次 git commit 实跑的钩子数；再加 3 根 manual 阶段的慢钩子才是声明数 51，三数同源。 枚举自查（不执行任何钩子，SKIP 列全部 id）：SKIP=<全部 id> -m pre_commit run --all-files --hook-stage commit 输出 47 行、--hook-stage manual 输出 50 行（47 常规 + 3 慢的）。
• 三根慢钩子在 manual 阶段：cppcheck、test-cppcheck、test-coverage 带 stages: [manual] → git commit 阶段不跑（实测三根合计约 165 s，占一次带代码提交耗时的约三分之二），只在远端 CI 的「手动阶段门禁」步 （.gitea/workflows/ci.yml，逐根 --hook-stage manual）与 scripts/ci_local.py 的 manual 段里跑。 本地手工复跑：& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual <hook-id> （一次只能给一个 id，多 id 实测报 unrecognized arguments）。声明数仍是 51，变的是「提交期实跑几根」。
• 通用机制（三个阶段 = pre-commit / commit-msg / manual、stash 陷阱、always 已废、增量拦截三段式、旧 §2.x 查号表）： docs/代码规范/pre-commit使用说明.md §2。
• 快速自查（不等提交）：& '.venv\Scripts\python.exe' scripts/ci_local.py（静态段 47 根 + manual 段三根 + 提交信息门禁 + 体积门禁 + 主机侧纯逻辑单测；manual 段默认跑）。

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、22 个主机单测、官方 5 个、gitlint	只能改代码或改文档；不要找豁免开关
增量拦截	规则恒生效，但存量钉在基线/台账里，只许减不许增	layer-deps（3 条，2026-10-25 还清 UI 记录 3 条）、bsp-err（38 条）、generated-fresh（5 处 docs/images/ 配图存量，脚本内 BASELINE）、nested-comment（2 处主机侧假件头，test/host/common/，脚本内 BASELINE）	报错先分清是新增还是存量搬家：--verbose 看归类，--prune 看已还清
只查新增	只看本次改动的增量，没有存量基线，也没有台账	id-check-new	改成语义短语，或把设备名/协议名登记进脚本白名单（行内 [编号豁免] 是最后手段）

⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。

2. 索引（51 个 hook → 28 篇，其中 1 篇是已退役门禁的留档 + 1 根只有本表指针（专篇待补）+ 1 根详解在 docs/测试说明/）

带 stages: [manual] 的三根（cppcheck / test-cppcheck / test-coverage）提交期不跑，只在远端 CI 的 「手动阶段门禁」步与 scripts/ci_local.py 的 manual 段跑；下表对应两行的「文档」列已标注。

门禁文档	覆盖的 hook id	一句话它在查什么	改了哪类文件才会跑	文档
bsp-err.md	bsp-err	BSP 的对外 API 面：错误通道类型、超时宏命名、必须写返回值、返回值不得裸丢弃	Drivers/BSP/** 或门禁自身	已写
layer-deps.md	layer-deps	分层方向：Drivers/BSP/** 不得 include App/**	Drivers/BSP/**	已写
id-check.md	~id-check	已退役（2026-10-28）：全库语料的八项校验，留档备查；现行编号门禁见下一行	在时有：几乎所有文本文件	已写（退役留档）
id-check-new.md	id-check-new	只查新增行有没有新造编号（零语料前缀白名单，已停发族只告警）	任意 md/c/h/py/yaml/txt	已写
doc-links.md	doc-links	文档里的路径引用是否存在；--sections-strict 另查章节号是否还存在	任意 .md	已写
cppcheck.md	cppcheck、test-cppcheck	静态分析（真机侧与 test/ 侧两套范围与抑制项）	C/H 源文件	已写（stages: [manual]）
coding-standard.md	coding-standard	编码规范 V1.0 的可机械检查子集（命名、头文件保护宏、模块头注释块…）	C/H 源文件	已写
no-mojibake.md	no-mojibake	禁 U+FFFD——中文被按错误编码重解码后不可逆损坏的痕迹	全部文本	已写
mem-numbers.md	mem-numbers	文档里引用的 RAM/Flash 数字与最新 .map 报告是否一致（体积档）	docs/内存管理/**、相关脚本	已写
mem-budget.md	mem-budget	RAM 总量红线：RW_IRAM1 / RW_CCM 超 92% 即拦	代码与配置改动	已写
task-table.md	task-table	README/AGENTS 里的任务表是否与 Src/freertos.c 一致	README.md、AGENTS.md、Src/freertos.c	已写
registration-check.md	registration-check	新 .c 是否双端注册（Keil 工程 + 模拟器 CMake）；UI 页面描述符表是否接线	.c、.uvprojx、CMakeLists.txt	已写
nested-comment.md	nested-comment	块注释体内再出现 /*（ARMCC 9-D 嵌套注释；诱因是注释里写路径通配）	全仓 .c/.h（第三方与生成物除外）	已写
generated-fresh.md	generated-fresh	生成器幂等性：把生成器重跑到系统临时目录，与工作区逐字节必须一致（不一致 = 生成物比生成器旧）	tools/**、UI 源码、ui_menu_tree.txt、ui_cn_chars.txt、docs/images/*.svg、两份注册表	已写
lv-conf-sync.md	lv-conf-sync	两份 lv_conf.h（MCU / 模拟器）的特性子集是否一致	两份 lv_conf 或脚本	已写
cubemx-survival.md	cubemx-survival	CubeMX 重生成会不会把定制静默抹掉（人工目检审计兜底）	.ioc、Src/、Inc/	已写
test-suite-switch.md	test-suite-switch	板级套件开关必须互斥；全注释 = 产品构建	test/board/test_config.h	已写
font-charset.md	font-charset	UI 用到的汉字是否都在子集字体里（缺字 = 白框）	Drivers/BSP/UI/**、字体脚本	已写
ui-golden.md	ui-golden	UI 像素回归：菜单 8 状态 + 内容页 66 张黄金参考图比对	UI 源码、模拟器	已写
bom-guard.md	bom-guard	带 BOM 的文件被编辑工具剥掉 BOM（ARMCC 换解码 → 假语法错）	Drivers/BSP/UI/** 等名单内文件	已写
setview-check.md	setview-check	定值查看行表与 prot_set 枚举序 / g_prot_set_meta 上下限是否同一份口径	tools/setview_check/**、ui_w_setview.*	已写
（专篇待补，档位与限度正文在 ../UI设计/UI_自动化测试流程.md §7.3）	uinav-selftest	板端 UI 导航器认屏快检（黄金参考帧分类；完整闭环档=合入前/上板前手工跑，快检不互替）	scripts/board_ui_nav.py、simulator/tests/ref/*.bin	指针
host-unit-tests.md	22 个 *-unit-test	主机侧单测（同一机制 22 个实例）：逻辑层在无硬件的 PC 上编译并跑断言	各自被测模块与其测试目录	已写
详解在 ../测试说明/主机单测覆盖率口径.md（口径 / 分母 / 基线 / 盲区都在那篇，本目录不重复）	test-coverage	覆盖率总闸：跑全部 41 套主机单测 + 已覆盖行只增不减的回退台账	App/、Drivers/BSP/、test/host/、脚本与基线	已写（在 docs/测试说明/；stages: [manual]）
trailing-whitespace.md	trailing-whitespace	行尾空白（改写型；CubeMX/Keil 生成文件豁免）	全部	已写
end-of-file-fixer.md	end-of-file-fixer	文件末尾必须恰好一个换行（改写型；同豁免）	全部	已写
check-added-large-files.md	check-added-large-files	别把大文件（日志/镜像/二进制）误提进仓库	全部	已写
check-merge-conflict.md	check-merge-conflict	别把没解完的冲突标记（<<<<<<<）提上去	全部	已写
check-yaml.md	check-yaml	YAML 语法是否可解析（门禁配置自己坏了会静默不跑）	.yml/.yaml	已写
gitlint.md	gitlint	提交信息规则：标题长度、正文每行 ≤80、空行要求	提交信息（commit-msg 阶段）	已写

3. 每篇文档的固定八段

1. 它在查什么——逐条判据，能对着代码复核的粒度；
2. 为什么要它——它拦下过什么真事，没有它会怎样（没有真事的门禁要老实写"预防性"）；
3. 触发面——files: / exclude: / pass_filenames / 阶段，以及看不见哪些文件；
4. 报错怎么读——样例输出、怎么单独跑、常见"假报警"（含 stash 陷阱）；
5. 好处——它把哪件事从"口头约定"变成了机器判定；
6. 限制与盲区——什么写法能骗过它、什么错它照不到、判据的启发式在哪里；
7. 豁免与基线——白名单形状、在册数量、还债口径（只减不增）；
8. 改门禁本身——自测怎么做、改名会波及什么（例如基线键）、为什么不许拿基线洗假阳性。

4. 现状与下一步

• 本目录 28 篇已全部成文（2026-10-27 实测当时 27 篇；2026-10-28 复核：docs/门禁说明/ 下除 README 外 28 篇，与上表「文档」列 一一对应——「有页无行」与「有行无页」两个差集都是空集；一行覆盖多个 hook 的行（cppcheck+test-cppcheck、 22 个 *-unit-test）按行内列举计。上一句写「23 篇」是存量误差：2026-10-25 连加 bom-guard / setview-check / uinav-selftest 三根、本轮加 generated-fresh 都没同步它（本轮前实有 25 篇）。 加钩子时的三步见下一行，第 ③ 步的计数与本目录 §2 标题、AGENTS.md 的钩子数必须同一笔改。
• 新增/改动一个门禁时的三步：① 在 .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"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。