wandering1
6822726b2c
用户一句"现在门禁都在干什么，我一概不知"引出的收尾。原手册 §2 有 27 个逐钩子小节，只回答 "拦了什么、怎么配"，回答不了"什么时候会骗我"；docs/门禁说明/ 已把逐项详解（含"限制与盲区" 一节）建好，本笔做收敛：同一事实只留一处（docs/文档规范.md 的要求）。 **先搬后删**（否则收敛等于丢事实）：旧 §2 里独有条目逐篇折回，共 18 处插入、15 篇受益。折回的 东西包括：六套主机单测的来历与用例规模（13/36/82/46/32/149 断言，含 nand-port 的"与旧算法 对照"）与"改动公共骨架 unit_test_harness.py 会同时触发 16 个钩子"；UI 页面**两层注册**（构建 注册 vs 框架注册：枚举 + s_defs[] 描述符表）与"豁免不整目录一刀切"；lv-conf-sync 首次落地清掉 26 个 LVGL 9.3 不存在的选项、3 处重复定义、10 项隐式开关显式化，以及 ALLOW_DIFF 端专属白名单 与必须穿过 lv_conf_internal.h 里那层 KCONFIG 包裹；cubemx-survival 的 16 项清单、断言前先剥 C 注释（本仓注释刻意引用历史代码，不剥就恒定误报）、旧手册"自造标记区"建议与看门狗文档实测 教训之间的优先级；id-check 顺带收编 check_test_traceability.py、裸形同字母多义属**显式承认的 盲区**、--update-baseline 只许涨；layer-deps 的注入自证与报错时三条修法（注入回调 / 上层递数据 / 才谈 ALLOW）；coding-standard **nand_ftl.* 也在排除清单**（我先前那篇漏了）；test-suite-switch 的剥注释判定与派生宏白名单；mem-budget 两类软提醒不拦、退出码 2 是解析失败不是通过；doc-links 的排除目录与状态词 ±40 字符距离；task-table 改栈三步；gitlint 报错样例；no-mojibake 的修复路径。 **顺带抓到旧文档两处错**（记进文档，不悄悄改）：一是 check-added-large-files 的阈值旧手册写 "单个文件 > 1MB"，按本机安装的钩子源码实测是 --maxkb 默认 **500**（500 KB）——已更正，并把 "本目录任何默认值都以实测或安装的钩子源码为准"写进 end-of-file-fixer 当反面教材；二是 **ui-golden 在旧手册里连小节都没有**，只活在配置注释里：除了"有基线不等于有门禁"，这是另一种 失踪——有钩子、没文档。 手册 §2 改写为三节：迁移说明 / **旧编号 → 新文档 查号表**（历史引用靠它读，旧号按"冻结历史不 回改"保留）/ **跨钩子通用机制**：两阶段与换机必须重装 hooks 才带 commit-msg、stash 陷阱、 always: true 已废、改写型与只读型豁免不对称、增量拦截三段式且刻意没有 --write、没有 .map 是 "跳过"不是"通过"、改配置的验收是看目标钩子出现在输出里且不是 Skipped、新增门禁三步必须做 注入自证且"限制与盲区"不许留空，另有快速自查入口。手册 707 行 → 273 行。 引用**按内容**重指（只核编号存在与否不够，同号小节会被当本文自引用静默放过）：编号规范、 scripts/README（顺带更正那里过时的 warn-only 说法，早已关闸为增量拦截）、RAM 使用分析与优化 方案、测试开发标准流程、lvgl-simulator skill、AGENTS 文档表（拆成"每门禁一篇详解"与"通用 机制"两行）、.pre-commit-config.yaml 头注释、docs/README.md 描述、手册自身 §5.5 与 §6 的两处 内部引用。另：表格里的裸节号会被 doc-links 判成本文自引用，查号表统一写成不带 § 的形态。 写说明过程又被自家门禁拦一次：gitlint 篇里引用报错样例时写了两个规则号字面量，被判形态不合规 → 改成中文描述，没有往台账里塞 reason 解决。 验证：纯文档与注释改动，不动代码，Program Size 不变，故不跑 @build/@test； check_doc_links --all --sections-strict **171 篇 0 问题**；id-check 增量拦截通过； pre-commit run **RC=0 / 13 项 Passed**；28 个改动文件字节卫生 **0 异常**（无 BOM、无 CR、 无 U+FFFD、均 LF、无行尾空白）。
8.1 KiB
8.1 KiB
门禁逐项说明（每种门禁一篇）
这一目录回答一个问题：提交时那 39 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
- 配置事实源：
.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（6 条）、bsp-err（38 条）、id-check（scripts/id_known_backlog.json 台账） |
报错先分清是新增还是存量搬家：--verbose 看归类，--prune 看已还清 |
⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
2. 索引（39 个 hook → 23 篇）
| 门禁文档 | 覆盖的 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 |
实体编号的八项校验（未登记前缀、裸形、重复定义、孤儿、悬空引用…） | 几乎所有文本文件 | 已写 |
doc-links.md |
doc-links |
文档里的路径引用是否存在；--sections-strict 另查章节号是否还存在 |
任意 .md |
已写 |
cppcheck.md |
cppcheck、test-cppcheck |
静态分析（真机侧与 test/ 侧两套范围与抑制项） |
C/H 源文件 | 已写 |
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 |
已写 |
lv-conf-sync.md |
lv-conf-sync |
两份 lv_conf.h（MCU / 模拟器）的特性子集是否一致 |
两份 lv_conf 或脚本 | 已写 |
cubemx-survival.md |
cubemx-survival |
CubeMX 重生成会不会把定制静默抹掉（L3 审计兜底） | .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 状态 + 内容页 11 页黄金参考图比对 | UI 源码、模拟器 | 已写 |
host-unit-tests.md |
16 个 *-unit-test |
主机侧单测（同一机制 16 个实例）：逻辑层在无硬件的 PC 上编译并跑断言 | 各自被测模块与其测试目录 | 已写 |
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. 每篇文档的固定八段
- 它在查什么——逐条判据，能对着代码复核的粒度；
- 为什么要它——它拦下过什么真事，没有它会怎样（没有真事的门禁要老实写"预防性"）；
- 触发面——
files:/exclude:/pass_filenames/ 阶段，以及看不见哪些文件； - 报错怎么读——样例输出、怎么单独跑、常见"假报警"（含 stash 陷阱）；
- 好处——它把哪件事从"口头约定"变成了机器判定；
- 限制与盲区——什么写法能骗过它、什么错它照不到、判据的启发式在哪里；
- 豁免与基线——白名单形状、在册数量、还债口径（只减不增）；
- 改门禁本身——自测怎么做、改名会波及什么（例如基线键）、为什么不许拿基线洗假阳性。
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"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。