ci(gates): 接线 test-coverage 覆盖率总闸（FAIL 语义），并修三处已成假话的门禁文档

用户裁定 2026-10-24：缺 mscoverage 组件时**失败**，不做 skip。于是 P1 之后那个 "钩子只挂 16/28 套"的缺口关闭了。为什么挂这一根而不是补 12 根 per-module 钩子：本闸跑**全部 28 套**，并且守 "已覆盖行只增不减"的基线台账。这是 per-module 钩子结构性做不到的——删掉一套测试，它那根钩子只会因为"没有文件要检查"而静默跳过（Skipped 不等于失败）。实测接线代价：45 s（28 套，含 28 次 MSVC 编译与插桩运行）。 FAIL 语义已按本仓"合成自证"的纪律验证（不是只测绿的那一半）：把 DTU_MS_COVERAGE 指到一个不存在的文件 → 钩子 Failed、脚本退出码 2、并打印可执行的 [ENV] 提示（说明该 exe 装在哪、怎么覆盖）。脚本对显式环境变量刻意 "不做自动探测回退"，所以指错会被点名，而不是悄悄换一份工具跑出另一本账。顺手修掉三条**现在已经不成立**的文档说法（门禁文档最贵的就是骗人）： - 口径 §7 第 8 条：原写"只有 BuildTools 且没勾代码覆盖率工具的机器会退出码 2"。实测本机 Community 18.10 与 BuildTools 18.9 **两份安装都自带**该 exe（mtime 2026-09-15 02:30 / 2026-09-05 16:17，都是各自安装当日，不是后来补勾）→ VS 18 的 BuildTools 默认就带它。真实风险面只剩：裸 MSVC 无 VS 的机器、环境变量指错、以及靠 PATH 兜底的环境。 - 门禁说明 host-unit-tests.md 盲区第 4 条：原写"没有对应钩子的模块 = 零回归"—— 如今 12 套新模块由总闸兜住，这句话已经不成立，改成两种口径并写清触发面。 - 同篇第 6 条：原写"无覆盖率统计"。行/函数覆盖**已有**度量（本闸出 Cobertura 并守基线），仍无的只是分支覆盖——那是用户裁定 2026-10-23 记下的**已接受缺口**，不是待办，改口时把这个区分写清楚。钩子计数同步（新增 1 根 → 声明 40 根 / pre-commit 阶段 39 根 + commit-msg 的 gitlint，已用脚本核对，不是手数）：AGENTS.md（总数、枚举、索引表）、 pre-commit使用说明.md（66 / 91 / 234 三处，含清点日期）、门禁说明 README （正文与索引标题，另加一行索引指向口径文档——23 篇不变，同一事实不在两处维护）、门禁说明 gitlint.md（--no-verify 跳过的"其它 38 个"→39）、并行任务工作树方案。自查：end-of-file-fixer 与 trailing-whitespace 复跑 Passed（首轮 --all-files 只因末行空行红过一次，已按钩子自身规范化）；doc-links --all --sections-strict 通过（178 个文档）；id-check --strict 零台账外新账；8 个改动文件 U+FFFD = 0、无 CRLF。零代码改动，故未跑 @build。未 push。
2026-10-24 07:50:53 +08:00
parent 2c3939494d
commit 744a1cb086
8 changed files with 55 additions and 21 deletions
@@ -90,7 +90,7 @@

 ## 提交门禁（pre-commit）

- 任一失败即拦截，共 **39 个钩子**（**每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ `docs/门禁说明/README.md` 索引**；通用机制与整体口径 → `docs/代码规范/pre-commit使用说明.md`）：通用 5 + `gitlint` + `cppcheck` / `test-cppcheck` + `no-mojibake` + `coding-standard` + 文档三件套 `doc-links` / `task-table` / `mem-numbers` + `id-check`（**编号门禁**，`docs/编号规范.md` §8 八项校验；**已关闸为【增量拦截】**：只拦 `scripts/id_known_backlog.json` 台账之外的新错误级问题，存量按指纹豁免、台账只减不增；另有一根恒生效的线——可判定比例跌破 `id_registry.json` 基线即失败）+ `lv-conf-sync`（两份 `lv_conf.h` 特性子集一致）+ `cubemx-survival` + 主机侧单测 16 个（`-unit-test` 后缀）+ `test-suite-switch` + `registration-check`（双端注册反向校验 + UI 页面描述符表接线，N-23/U4）+ `mem-budget`（RAM 92% 预算门禁，N-27）+ `font-charset`（UI 字符集差集检查，防缺字白框，U4）+ `ui-golden`（UI 像素回归，菜单 8 状态 + 内容页 11 页黄金参考，U4）+ `layer-deps`（**分层方向**：`Drivers/BSP/**` 不得 include `App/**` 的头；存量 6 条基线只减不增，报告 S-1）+ `bsp-err`（**BSP 错误码与超时命名约定**：公开 API 不得拿 `HAL_StatusTypeDef`/`bool` 当错误通道、`*_TIMEOUT` 宏不得取负值、非 void 须写「返回值：」、**返回错误码的函数不得裸丢弃返回值**（须接住或显式 `(void)`；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 `Drivers/BSP/bsp_err.h`，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；`consume-result` 上线又暴露 37 条存量丢弃 → **现 38 条**），报告 S-5）
+- 任一失败即拦截，共 **40 个钩子**（**每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ `docs/门禁说明/README.md` 索引**；通用机制与整体口径 → `docs/代码规范/pre-commit使用说明.md`）：通用 5 + `gitlint` + `cppcheck` / `test-cppcheck` + `no-mojibake` + `coding-standard` + 文档三件套 `doc-links` / `task-table` / `mem-numbers` + `id-check`（**编号门禁**，`docs/编号规范.md` §8 八项校验；**已关闸为【增量拦截】**：只拦 `scripts/id_known_backlog.json` 台账之外的新错误级问题，存量按指纹豁免、台账只减不增；另有一根恒生效的线——可判定比例跌破 `id_registry.json` 基线即失败）+ `lv-conf-sync`（两份 `lv_conf.h` 特性子集一致）+ `cubemx-survival` + 主机侧单测 16 个（`-unit-test` 后缀）+ `test-coverage`（**覆盖率总闸**：跑全部 28 套并守基线回退；缺 mscoverage 组件时按用户裁定 **FAIL**、不 skip，2026-10-24）+ `test-suite-switch` + `registration-check`（双端注册反向校验 + UI 页面描述符表接线，N-23/U4）+ `mem-budget`（RAM 92% 预算门禁，N-27）+ `font-charset`（UI 字符集差集检查，防缺字白框，U4）+ `ui-golden`（UI 像素回归，菜单 8 状态 + 内容页 11 页黄金参考，U4）+ `layer-deps`（**分层方向**：`Drivers/BSP/**` 不得 include `App/**` 的头；存量 6 条基线只减不增，报告 S-1）+ `bsp-err`（**BSP 错误码与超时命名约定**：公开 API 不得拿 `HAL_StatusTypeDef`/`bool` 当错误通道、`*_TIMEOUT` 宏不得取负值、非 void 须写「返回值：」、**返回错误码的函数不得裸丢弃返回值**（须接住或显式 `(void)`；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 `Drivers/BSP/bsp_err.h`，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；`consume-result` 上线又暴露 37 条存量丢弃 → **现 38 条**），报告 S-5）
 - **范围 = 项目代码**：第三方（`Lib/`、`Middlewares/`、CMSIS、HAL、`lftpd`、`dhara`、`MDK-ARM`）排除；`cppcheck`/`coding-standard` 另排除 `test/`，规范检查再排除 CubeMX 生成的 `Src/`/`Inc/`。**`simulator/` 已纳入全部钩子**（2026-10-11）——生成物只靠 `.gitignore` 挡，**不在 `exclude` 里写目录名**（教训见 `docs/代码规范/pre-commit使用说明.md` §5.5）
 - ⚠ **pre-commit 4.x 已移除 `always: true`**（实测对 `local` 钩子只告警 `Unexpected key(s)` 并跳过）→ 想"总是跑"的钩子**必须让 `files:` 覆盖到所有会触发它的文件**，没有兜底开关
 - **改写型钩子（`trailing-whitespace` + `end-of-file-fixer`）豁免 CubeMX/Keil 生成文件**（配置里 YAML 锚点 `&cubemx-generated`）；⚠ **只读检查不受影响**：`cppcheck` / 乱码 / `cubemx-survival` / `task-table` / `mem-numbers` 仍覆盖 `Src/`、`Inc/`
@@ -173,7 +173,7 @@
 | ADC 采样节拍 / 通道映射 / V0.1 硬件缺陷 | `docs/子系统设计/ADC采样节拍设计说明.md`、`docs/硬件平台/ADC通道映射说明.md` |
 | 存储栈（FatFs / dhara / lftpd / 两条 FatFs 陷阱） | `docs/架构设计/STM32F4-Base存储架构说明.md` |
 | RAM / 栈预算 / 容量台账 | `docs/内存管理/RAM使用分析与优化方案.md`、`内存内容分配策略.md` |
-| **每个提交门禁一篇详解**（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径） | `docs/门禁说明/README.md`（39 个钩子 → 23 篇索引） |
+| **每个提交门禁一篇详解**（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径） | `docs/门禁说明/README.md`（40 个钩子 → 23 篇索引） |
 | 实体编号怎么写 / 前缀总表 / `id-check` 八项校验 | `docs/编号规范.md`（§4 总表、§8 门禁与实测基线） |
 | 提交门禁通用机制（阶段 / stash 陷阱 / 触发面 / 增量拦截三段式） | `docs/代码规范/pre-commit使用说明.md` §2 |
 | 代码规范 V1.0 / cppcheck 口径 | `docs/代码规范/嵌入式C语言代码规范_V1.0.md`、`cppcheck使用说明.md` |