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、无行尾空白）。
3.7 KiB
3.7 KiB
test-suite-switch — 别让测试固件被静默提交
一句话：
test/board/test_config.h的TEST_SUITE_*全部注释 = 产品构建；只要有开关是 打开状态，提交的就是测试固件，本门直接拦。
- 配置：
entry: python scripts/check_test_suite.py、pass_filenames: false、files: ^test/board/test_config\.h$。
1. 它在查什么
| 状态 | 判定 |
|---|---|
| 全部注释 | PASS（产品构建） |
| 启用一个或多个 | FAIL，列出套件名与修复方法 |
| 同时启用多个 | FAIL（编译期另有 #error 兜底，两道闸） |
2. 为什么要它
- 真事故（2026-10-01 测试架构评审）：该开关此前没有任何门禁检查，实测已提交的 HEAD 里
TEST_SUITE_CH395F就是开启状态，.map含 34 处 test 代码——躺在分支上的是测试固件， 而它看起来完全正常。纯靠人记得改回去，是迟早会漏的事。
3. 触发面
- 只在
test/board/test_config.h变化时跑（files精确到这一个文件）。 - 测试构建本身是合法的（跑套件回归就是要开），所以放行通道是显式声明：
--allow-test-build或环境变量ALLOW_TEST_BUILD=1；显式放行后仍打印醒目[WARN]横幅。
4. 报错怎么读
测试套件开关=产品构建.......Failed
[FAIL] 启用了 TEST_SUITE_GD5F —— 提交前请全部注释（产品构建）
- 单独跑：
& '.venv\Scripts\python.exe' scripts/check_test_suite.py（--file换目标、--quiet只报失败）。 run_all_suites.py（board-test-suiteskill）会自动改宏、无条件还原，跑完正常情况不会留下开关。
5. 好处
- 把"跑完回归记得还原"从纪律变成判定；
- 与破坏性开关的持久代价配合：
ENABLE_DESTRUCTIVE_TESTS一旦开过又忘了，本门是最后一道提醒。
6. 限制与盲区
- 只看
test_config.h一个文件：如果有人把#define TEST_SUITE_GD5F写进别处（编译器-D参数、uvprojx的预处理定义、某个头文件），本门完全不知道。 - 放行通道
ALLOW_TEST_BUILD=1不记录在提交里——环境变量放行不留痕，所以它适合本地临时 跑，不适合作为常规手段。 - 它不判断"产品构建是否真的没有测试代码"（
test/board/*.c可能仍在工程里，只是被宏关掉）。 ENABLE_DESTRUCTIVE_TESTS的开/关不由本门判定（那是破坏性代价，属 Ask-first 事项， 见docs/测试说明/存储维护与容量恢复.md）。
- 判定实现：先剥掉块注释与行注释再匹配
#define，所以注释掉的开关不会误判；同文件派生出的TEST_SUITE_SELECTED/TEST_SUITE_NAME由白名单排除（它们是开关的推导结果，不是可选项）。 新增派生宏要同时进白名单，否则会被当成"启用了一个套件"（假阳性）。 - 当时论证"此前没有任何门禁"的方式很朴素：
grep TEST_SUITE scripts/*.py零命中。 - 与编译期
#error互斥检查是两道闸：#error只在真构建时暴露，测试固件照样可能被提交， 所以提交期再拦一道。
7. 豁免与基线
- 无基线。唯一的"放行"是显式声明本次就是测试固件；不要用
--no-verify绕过（绕过之后 没有任何痕迹说明你提交了测试构建）。
8. 改这个门禁本身
- 新增套件宏要同时更新判定与互斥名单，否则新宏会被当成"没开"而放过；
- 若改成"允许提交测试构建但要求写进提交说明"，需要先想清楚：那种提交怎么和真实产品构建区分。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-23 | 首篇逐项文档（含"HEAD 里躺着测试固件"的实测背景） |