wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity

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

Browse Source 
用户裁定 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。
This commit is contained in:
Wanderingss
2026-10-24 07:50:53 +08:00
parent 2c3939494d
commit 744a1cb086
8 changed files with 55 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.pre-commit-config.yaml
+20
View File
@@ -592,3 +592,23 @@ repos:
language: system
files: ^Drivers/BSP/|^scripts/check_bsp_err\.py$|^\.pre-commit-config\.yaml$
pass_filenames: false
# 8) 主机单测覆盖率总闸（2026-10-24 接线，用户裁定选 FAIL 语义）
# 为什么现在才挂：接线前本文件只有 16 个 *-unit-test 钩子，而仓库已有 28 套主机单测——
# P1 新增的 12 套不在任何提交钩子里。原先"再加一份全量插桩等于同一件事做两遍"
# 这条理由到现在已经**反了**（现状是有一遍没做），所以必须挂；缺口此前如实登记在
# docs/测试说明/主机单测覆盖率口径.md §8。
# 为什么挂这一根而不是补 12 个 per-module 钩子：本钩子跑**全部 28 套**，并且守 §5 的
# 回退台账（某套被删、或某文件的已覆盖行变少 → [REGRESS] 直接红）。这是 per-module
# 钩子做不到的——删掉一套测试，它那根钩子只会因为"没有文件要检查"而静默跳过。
# ⚠ FAIL 语义（用户裁定 2026-10-24）：找不到 mscoverage 时脚本退出码 2 → 本钩子**失败**，
# 不做 skip。理由：skip 等于造一根会静默失效的门禁（与 pre-commit 4.x 移除 always: true
# 是同一类坑）；宁可在没装组件的机器上被挡一次、看清 [ENV] 那行提示，也不要一根假绿的闸。
# 本机与 CI runner 同一台；实测两份 VS 安装都自带该 exe（口径 §7 第 8 条已按实测更正）。
# 口径 / 分母 / 基线 / 盲区详解都在 docs/测试说明/主机单测覆盖率口径.md，本处只留接线事实。
- id: test-coverage
name: 主机单测覆盖率（增量拦截：已覆盖行只增不减）
entry: python scripts/check_test_coverage.py
language: system
files: ^(App/|Drivers/BSP/|test/host/|scripts/check_test_coverage\.py|scripts/test_coverage_baseline\.json)
pass_filenames: false
AGENTS.md
+2 -2
View File
@@ -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` |
docs/代码规范/pre-commit使用说明.md
+3 -3
View File
@@ -63,7 +63,7 @@ git commit
> **2026-10-23 迁移**：原本节 27 个"逐钩子详解"小节，已全部迁往 `docs/门禁说明/`——**每种门禁
> 一篇**，八段固定结构（查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / **限制与盲区** /
> 豁免与基线口径 / 改门禁本身）。39 个 hook 的总览与"三种拦截姿态" → `docs/门禁说明/README.md`。
> 豁免与基线口径 / 改门禁本身）。40 个 hook 的总览与"三种拦截姿态" → `docs/门禁说明/README.md`。
> 搬走的原因：只写"拦了什么"的文档会让人以为绿就是对的，而"什么时候会骗人"必须有归处。
> 同一事实只在一处详述（`docs/文档规范.md` 同此要求），所以本节不再重复逐钩子表格。
@@ -88,7 +88,7 @@ git commit
| 机制 | 口径 |
|---|---|
| **两个阶段** | pre-commit 阶段 38 个钩子 + commit-msg 阶段 `gitlint`；`default_install_hook_types: [pre-commit, commit-msg]` 是显式声明的——换机后 `pre-commit install` 才会带上 commit-msg 钩子 |
| **两个阶段** | pre-commit 阶段 39 个钩子 + commit-msg 阶段 `gitlint`；`default_install_hook_types: [pre-commit, commit-msg]` 是显式声明的——换机后 `pre-commit install` 才会带上 commit-msg 钩子 |
| **stash 陷阱** | pre-commit 跑钩子前会 stash 未暂存改动，钩子看到的是"没有你中间状态"的树。**改代码 + 同时更新基线/受管区的，必须先 `git add` 再跑钩子**，否则会拿到假报警（本仓踩过，`docs/门禁说明/bsp-err.md` §4 记了现场） |
| **`always: true` 已废** | pre-commit 4.x 对 `local` 钩子里这个键**只告警 `Unexpected key(s)` 然后忽略** → "想总是跑"只能把 `files:` 写全（教训 → §5.5） |
| **改写型与只读型的豁免不对称** | YAML 锚点 `&cubemx-generated` 只豁免 `trailing-whitespace` 与 `end-of-file-fixer`；`cppcheck` / `no-mojibake` / `cubemx-survival` / `task-table` / `mem-numbers` **仍覆盖** `Src/`、`Inc/` |
@@ -231,7 +231,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
| 文件 | 位置 | 说明 |
|---|---|---|
| `.pre-commit-config.yaml` | 仓库根 | 钩子配置（**39 个钩子**，2026-10-23 清点）。逐项详解在 `docs/门禁说明/`（索引 `docs/门禁说明/README.md`；主机侧单测 16 个合一篇，含各套件来历；UI 侧另有 `font-charset` 与 `ui-golden` 两篇——后者此前**在旧手册里连小节都没有**，只活在配置注释里，本次补齐） |
| `.pre-commit-config.yaml` | 仓库根 | 钩子配置（**40 个钩子**，2026-10-24 清点：新增 `test-coverage` 覆盖率总闸）。逐项详解在 `docs/门禁说明/`（索引 `docs/门禁说明/README.md`；主机侧单测 16 个合一篇，含各套件来历；UI 侧另有 `font-charset` 与 `ui-golden` 两篇——后者此前**在旧手册里连小节都没有**，只活在配置注释里，本次补齐） |
| `.gitlint` | 仓库根 | gitlint 规则（宽松，兼容中文） |
| `.cubemx_survival_baseline.json` | 仓库根 | CubeMX 易失定制基线（哈希；`--write` 重建） |
| `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 |
docs/测试说明/主机单测覆盖率口径.md
+18 -9
View File
@@ -1,6 +1,6 @@
# 主机单测覆盖率口径（覆盖率脚本 / 基线 / 盲区）
> **状态**：✅ 已落地（脚本 + 基线 + 口径），⏸ 未挂 pre-commit（理由见 §8）；
> **状态**：✅ 已落地，并**已挂 pre-commit**（`test-coverage` 总闸，2026-10-24 接线，缺组件按裁定 FAIL）；
> **分支覆盖**：本机可实测拿到（§2.1 的 gcc/WSL 路），但**用户裁定 2026-10-23 不引入第二条工具链**
> → 本文把它记为**已接受缺口**，不是待办
> **日期**：2026-10-23
@@ -152,8 +152,16 @@
（全量跑时以"模块未跑到"判 REGRESS），子集运行明确降级（§5）。
7. **头文件里的代码归 `.h`。** 统计面含 `.h`（静态内联与被展开的行落在头文件上）；当前 16 套
几乎没触及 `.h`，表里看不到它们——不要以为头文件"天生 100%"。
8. **依赖 VS 的可选组件。** 只有 BuildTools 且没勾"代码覆盖率工具"的机器会退出码 2；
CI runner 与本机同一台（`docs/CI/README.md`），但**换机先跑 `--list` 再跑全量**。
8. **依赖 `Microsoft.CodeCoverage.Console.exe`。** 探测顺序：`DTU_MS_COVERAGE`（设了就必须
有效、**不静默回退**）→ 各 VS 安装根的 `Common7\IDE\Extensions\Microsoft\CodeCoverage.Console\` →
PATH；找不到即退出码 2（**不是 0**）。2026-10-24 起该结果直接红掉 `test-coverage` 钩子（用户裁定
FAIL 语义），并已合成自证：把 `DTU_MS_COVERAGE` 指到一个不存在的文件 → 钩子 Failed、脚本退出码 2、
打印可执行的 `[ENV]` 提示。
⚠ **更正本文旧说法**（原写"只有 BuildTools 且没勾代码覆盖率工具的机器会退出码 2"）：实测本机
Community 18.10 与 BuildTools 18.9 **两份安装都自带**该 exe（mtime 2026-09-15 02:30 / 2026-09-05
16:17，都是各自安装当日，不是后来补勾）→ VS 18 的 BuildTools 默认就带它。真实风险面只剩：没有
VS 只有裸 MSVC 的机器、`DTU_MS_COVERAGE` 指错、以及靠 PATH 兜底的环境。CI runner 与本机同一台
（`docs/CI/README.md`）；**换机仍先跑 `--list` 再跑全量**。
9. **并集口径下"单套百分比"没有意义。** 同一文件被多套触及很常见（`sha256.c` 被 `sha256` 与
`ftp_auth` 都编译），所以对外只报**并集**，单套只报"触及几个文件 / 多少行"。
@@ -161,7 +169,8 @@
**已落地**：脚本、基线台账、口径（本文）、`scripts/ci_local.py --coverage` 一条入口。
**未挂 pre-commit**，三条理由（不是忘了）：
**接线状态：已挂**（2026-10-24，`test-coverage` 落在 `.pre-commit-config.yaml` 第 8 节，用户裁定 **FAIL** 语义）。
接线前的三条理由连同它们的现状一并留档，免得后人重问同一件事：
1. 39 个钩子里已有 16 个主机单测钩子（每套各编译各跑），再加一份"全量插桩"在**当时**确实是同一
件事做两遍，还要多约 25 s；
@@ -171,9 +180,10 @@
全部模块）目前只被 `ci_local.py`（L0.5 自动发现）与 `check_test_coverage.py` 跑到，
**不在提交钩子里**。所以现状不是"重复两遍"，而是**有一遍没做**。
仍未挂，只剩第 2 条那一个原因：必须先定"缺 VS 组件时 skip 还是 FAIL"——那是留给用户裁定的事
（选 skip 等于造一根会静默失效的门禁，与 `always: true 已失效` 那条同类坑）。与其悄悄挂一根
可能假绿的钩子，不如把缺口写在这里。
当时唯一没解的是第 2 条：必须先定"缺 VS 组件时 skip 还是 FAIL"——那是要用户裁定的事（选 skip
等于造一根会静默失效的门禁，与 `always: true 已失效` 同类）。**2026-10-24 用户选 FAIL，本闸已挂**，
缺口关闭。接线时的两个实测数：全闸跑完 **45 s**（28 套；本文别处写的"约 25 s"是只有 16 套时
的值，已过时）；缺组件时钩子 **Failed**、脚本退出码 2 并打印 `[ENV]` 提示（合成自证）。
2. 它依赖 VS 可选组件（§7 第 8 条）。挂之前必须先定"缺组件时 skip 还是 FAIL"——
选 skip 就是一个会静默失效的门禁（与 `AGENTS.md` 里那条 `always: true 已失效、必须靠 files: 覆盖`
是同一类坑）；
@@ -182,8 +192,7 @@
不会假报回退（首版会，已修：并集口径下子集必然变小，所以 `--module` 子集跑跳过全部回退判定）。
真实事件（某次改动真把覆盖行弄少了）仍待观察。
真到接线那天，片段形状如下（这份 YAML 由接线者写进 `.pre-commit-config.yaml`，说明写进
`docs/门禁说明/` 对应那篇，不在本文维护）：
落库的就是下面这份（`.pre-commit-config.yaml` 第 8 节，与文件里逐字一致，只多不少）；`docs/门禁说明/README.md`
```yaml
- repo: local
docs/环境与部署/并行任务工作树方案.md
+1 -1
View File
@@ -397,7 +397,7 @@ docs\内存管理\RAM使用分析与优化方案.md:585 [路径引用] docs/内
| 主题 | 去处 |
|---|---|
| 提交门禁 39 个钩子 | `docs/代码规范/pre-commit使用说明.md` |
| 提交门禁 40 个钩子 | `docs/代码规范/pre-commit使用说明.md` |
| 自动化测试与台架流程 | `docs/测试说明/自动化测试流程.md` |
| 文档写作规范（编码/链接/登记） | `docs/文档规范.md` |
| 工具路径环境变量（换机） | `docs/环境与部署/本地工具路径环境变量方案.md` |
docs/门禁说明/README.md
+3 -2
View File
@@ -1,6 +1,6 @@
# 门禁逐项说明（每种门禁一篇）
> 这一目录回答一个问题：**提交时那 39 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。**
> 这一目录回答一个问题：**提交时那 40 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。**
> 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 /
> **限制与盲区** / 豁免与基线 / 改门禁本身要注意什么。**最后一节是这套文档存在的理由**——
> 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。
@@ -21,7 +21,7 @@
⚠ 增量拦截最容易误会的一点：**绿灯不等于没问题**，只等于"没有比上次更差"。
每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。
## 2. 索引（39 个 hook → 23 篇）
## 2. 索引（40 个 hook → 23 篇 + 1 根在 docs/测试说明/）
| 门禁文档 | 覆盖的 hook id | 一句话它在查什么 | 改了哪类文件才会跑 | 文档 |
|---|---|---|---|---|
@@ -42,6 +42,7 @@
| [`font-charset.md`](font-charset.md) | `font-charset` | UI 用到的汉字是否都在子集字体里（缺字 = 白框） | `Drivers/BSP/UI/**`、字体脚本 | 已写 |
| [`ui-golden.md`](ui-golden.md) | `ui-golden` | UI 像素回归：菜单 8 状态 + 内容页 11 页黄金参考图比对 | UI 源码、模拟器 | 已写 |
| [`host-unit-tests.md`](host-unit-tests.md) | 16 个 `*-unit-test` | 主机侧单测（同一机制 16 个实例）：逻辑层在无硬件的 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` | 别把大文件（日志/镜像/二进制）误提进仓库 | 全部 | 已写 |
docs/门禁说明/gitlint.md
+1 -1
View File
@@ -27,7 +27,7 @@
## 3. 触发面 / 看不见什么
- `git commit`、`--amend`、`-F`、合并生成的提交都会跑；**`--no-verify` 连它和其它 38 个钩子一起跳过**。
- `git commit`、`--amend`、`-F`、合并生成的提交都会跑；**`--no-verify` 连它和其它 39 个钩子一起跳过**。
- 不校验：提交说明与 diff 是否相符、是否真的构建/测试过、是否夹带无关改动、是否该拆成多笔。
## 4. 报错怎么读
docs/门禁说明/host-unit-tests.md
+7 -3
View File
@@ -81,11 +81,15 @@
行为不同"。桩签名改了而测试没跟着改，编译器未必报错（尤其桩返回宽类型）。
3. `include_dirs` 与源文件清单是**手写**的：新依赖一个目录就会假失败（见 §4 第 2 类），反过来，
漏了某个真实依赖可能让测试**编过却少编了一个翻译单元**（少测而不自知）。
4. **没有对应钩子的模块 = 零回归**：本层只覆盖上表 16 个模块；其余逻辑层（含 UI 逻辑、网络
状态机主体）只能靠 `ui-golden`、板级套件与真机 `@test`。
4. **专属钩子不是唯一防线**（2026-10-24 更正，原写"没有对应钩子的模块 = 零回归"，如今不成立）：上表 16
个模块各有专属钩子；仓库另有 12 套（P1 新增）没有专属钩子，改坏了由 `test-coverage` **总闸**兜
住——它跑全部 28 套，并守"已覆盖行只增不减"。总闸的触发面是 `App/`、`Drivers/BSP/`、
`test/host/`、覆盖率脚本与基线；纯文档改动不触发它（那时确实没有可回归的行为）。
5. 时序与并发不在范围：中断抢占、DMA 完成回调、临界区、真机 tick 抖动都照不到（历史上最贵的
几个坑正是这类，见 `docs/问题记录/*_Trap_Records.md`）。
6. 断言写的是"作者当时想到的分支"：分支覆盖是否充分，没有任何度量（无覆盖率统计）。
6. 断言写的是"作者当时想到的分支"：**行 / 函数覆盖有度量了**（`test-coverage` 总闸出
Cobertura 并守基线台账），但**分支覆盖仍无**——按用户裁定 2026-10-23 记为**已接受缺口**，
口径与理由见 `docs/测试说明/主机单测覆盖率口径.md` §2.1，不是待办。
## 7. 豁免与基线