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

feat(门禁): 主机单测覆盖率脚本与口径落地（销报告 §4.8 空白 ①）

Browse Source 
落地物：
- scripts/check_test_coverage.py：发现规则与 L0.5 同一条（test/host/**/
  run_unit_test.py），直接 import 各运行器复用其 TestBuild 与
  unit_test_harness._BASE_FLAGS —— 配置零复制，不会漂出第二套口径；
  只算自研生产源码（App/**、Drivers/BSP/**）的行/函数、多套取并集、
  生成物（文件头写"自动生成/请勿手改"）不进分母、分母一律来自插桩
  报告不猜行数；中间物全在 %TEMP%，不新增 .gitignore 规则。
- scripts/test_coverage_baseline.json：增量拦截台账（只拦回退不拦进步，
  与 layer-deps / bsp-err 同姿态）；ci_local.py 加 opt-in --coverage。
- docs/测试说明/主机单测覆盖率口径.md：口径 + 工具链实测 + 九条盲区。
- 报告 §0.1 / §0.4 / §4.8 / §5.5 / §7 改写 + 变更记录 + 去处表。

工具链是实测出来的（换机必读）：Windows 原生侧无任何 gcc/gcov（全盘扫
Program Files*、msys64、scoop、choco、.platformio、LocalAppData = 0 处）；
MSVC 14.51 已砍 /coverage，且只报 D9002 后照常编译成功 = 静默假数据；
CodeCoverage.exe 17.0 三个子命令只打印用法。最终用 mscoverage 18.x
（Microsoft.CodeCoverage.Console.exe）collect -f cobertura 做加载期动态
插桩，并实测它透传子进程退出码 → "插桩运行下仍必须 PASS"可当硬条件。

首登数字：16/16 套插桩下全绿，并集 line=2552/2893（88.2%）、
func=193/207（93.2%）、19 个文件在测、**未触及 125 个生产源文件 /
约 11,839 行**——最后一栏才是这套口径真正照出来的东西。

门禁自证：人为抬高基线后 行/函数/总计 三条回退路径都报 REGRESS 且
退出码 1；--module 子集跑不再假报总计回退（首版会，已修：并集口径下
子集必然变小，全部回退判定只在全量跑时生效）。

GCC 追问的复测结论（口径文档 §2.1 决策记录）：本机 WSL2 Ubuntu 确实有
gcc/gcov 15.2.0，16 套单测在 gcc 下全部编过、用例数与 MSVC 逐个一致，
gcov -b -c 也确实给出分支覆盖（nand_ftl.c 分支至少走过一次 41.40%）；
但换编译器=换分母（sha256.c gcc 105 行 vs MSVC 114 行；adc_input.c 101
vs 120）。**用户裁定：本仓只留 MSVC 一条覆盖率通道**，不建第二条——
多一套工具链就多一套分母、多一本台账、多一个"这台机器到底有没有 WSL/
gcov"的未决项，换来的只有分支这一维。分支覆盖因此**记为已接受缺口**
（不是待办）：绿灯只证明行与函数被测到，补偿判据 = TC 双向追溯 +
用例显式列边界值；§8 写明重开该裁定的前提是先答"两份分母怎么对齐"。

刻意未挂 pre-commit：16 个单测钩子已经跑过同一批测试；依赖 VS 可选
组件（缺组件时 skip 会静默失效、FAIL 会拦换机）；待一个真实回退事件。
YAML 片段与理由写在口径文档 §8。

自查：pre-commit run --files（6 个改动文件）全 Passed；check_doc_links
--all 回到存量 35 处（本分支贡献 0）；check_ids.py --strict PASS；
check_mojibake + BOM/CR/U+FFFD/行尾卫生逐项自查全净。本轮零 .c/.h 改动
（纯 .py/.json/.md），故未跑 @build、未占 build/bench 锁。
This commit is contained in:
Wanderingss
2026-10-23 11:46:13 +08:00
parent 49a257b34c
commit 2bfa09ed15
6 changed files with 1915 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+1
View File
@@ -134,6 +134,7 @@ docs/
| [`相量层单元测试说明.md`](测试说明/相量层单元测试说明.md) | phasor 全周傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换，57 用例 |
| [`卷锁单元测试说明.md`](测试说明/卷锁单元测试说明.md) | vol_lock 创建 / 获取 / 释放契约（**fail-open 不变量**：创建失败仍返回 1 且零阻塞）/ 幂等 / 超时透传，33 断言点 |
| [`时间同步单元测试说明.md`](测试说明/时间同步单元测试说明.md) | time_sync 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（**N-17 的全部逻辑贡献者**），80 断言点 |
| [`主机单测覆盖率口径.md`](测试说明/主机单测覆盖率口径.md) | **跨全部 16 套 L0.5 的覆盖率**：`scripts/check_test_coverage.py` 用法 / 统计面与生成物例外 / 基线增量门禁（只拦回退）/ **为什么本机拿不到分支覆盖** / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML |
**模块测试指南**（动手写测试前先读）
docs/测试说明/主机单测覆盖率口径.md
+200
View File
@@ -0,0 +1,200 @@
# 主机单测覆盖率口径（覆盖率脚本 / 基线 / 盲区）
> **状态**：✅ 已落地（脚本 + 基线 + 口径），⏸ 未挂 pre-commit（理由见 §8）；
> **分支覆盖**：本机可实测拿到（§2.1 的 gcc/WSL 路），但**用户裁定 2026-10-23 不引入第二条工具链**
> → 本文把它记为**已接受缺口**，不是待办
> **日期**：2026-10-23
> **脚本**：[`scripts/check_test_coverage.py`](../../scripts/check_test_coverage.py)（纯标准库）
> **基线台账**：[`scripts/test_coverage_baseline.json`](../../scripts/test_coverage_baseline.json)
> **关联文档**：
> [`测试开发标准流程.md`](测试开发标准流程.md)（L0~L3 分层与门禁决策表）、
> [`../问题记录/项目审查与优化建议报告.md`](../问题记录/项目审查与优化建议报告.md) §4.8（本文关闭它的空白 ①）
> 与 [`../问题记录/项目审查与优化建议报告.md`](../问题记录/项目审查与优化建议报告.md) §5.5 第 5 条的前半、[`../代码规范/pre-commit使用说明.md`](../代码规范/pre-commit使用说明.md)（钩子通用机制）
---
## 1. 一句话口径
**行覆盖 = 至少执行过一次的可执行行 / 被插桩的可执行行**，统计面只算自研生产源码
（`App/**`、`Drivers/BSP/**`），多套单测对同一文件的命中取**并集**；函数覆盖同理按
"至少有一行命中"计。**没有分支覆盖**——本机拿不到（§2），这一点决定了"绿"能说明什么、
不能说明什么（§7）。
## 2. 工具链现实：为什么是 mscoverage，不是 gcov
2026-10-23 本机（VS 2026 / MSVC 14.51）逐项实测，**换机请按同一顺序重探一遍**：
| 候选 | 实测结果 | 结论 |
|---|---|---|
| gcc / gcov / clang / llvm-cov / lcov / gcovr（**Windows 原生侧**） | PATH 上没有；再全盘扫 `Program Files*`、`C:\msys64`、`scoop`、choco、`.platformio`、`%LOCALAPPDATA%\Programs` → **0 处**（OpenCppCoverage 也没有） | Windows 侧走不了 gcov 这条最主流的路（但 WSL 里有，见 §2.1） |
| `cl /coverage`、`cl /fsanitize=coverage` | **MSVC 14.51 已不认**：只报 `warning D9002: 忽略未知选项`，**然后照常编译成功** | ⚠ 最阴的一种：不报错、静默没有插桩 → 覆盖率恒为 0 或假数据，绝不可用 |
| `Team Tools\Dynamic Code Coverage Tools\CodeCoverage.exe`（17.0） | 文件在，但 `collect` / `analyze` / `instrument` **一律只打印"用法: CodeCoverage <command>"** 并返回 -1 | 已 deprecated 且子命令不可用 |
| **`Microsoft.CodeCoverage.Console.exe`**（mscoverage 18.x，随 VS 装在 `Common7\IDE\Extensions\Microsoft\CodeCoverage.Console\`） | `collect -f cobertura` 直接吃 MSVC 原生 exe + PDB，产出标准 Cobertura XML；**子进程退出码原样透传**（实测子进程 `return 3` → `collect` 也返回 3） | ✅ **本脚本用它**（"加载期动态插桩"，不是编译期插桩） |
### 2.1 GCC 到底行不行：能编、能跑、**能出分支覆盖**——结论是**不用**（换编译器就是换分母）
本机 **WSL2 Ubuntu 里有 gcc / gcov 15.2.0**（`wsl -d Ubuntu`，仓库经 `/mnt/d` 可见）。2026-10-23 实测：
| 测项 | 实测结果 |
|---|---|
| 16 套单测用 `gcc -std=c11 -O0 -g --coverage` 编译 | **全部编过、全部 PASS**，用例数与 MSVC 逐个一致（45/103/151/46/36/97/149/57/47/90/13/32/100/82/33/39）——**可移植性不是障碍** |
| `gcov -b -c` | ✅ 行覆盖之外**还给出分支**：`nand_ftl.c` 行 45.49% / 分支至少走过一次 **41.40%（157 支）**；`cfg_file.c` 行 86.72% / 分支 79.69%（512 支）；`sha256.c` 行 97.14% / 分支 82.00%（50 支） |
| 代价一：**分母变了** | 同一文件的"可执行行"两个编译器不同：`App/util/sha256.c` gcc 105 行 vs MSVC 114 行；`nand_ftl.c` 244 vs 253；`adc_input.c` 101 vs 120 → **两套数字两套台账，绝不能混在一张表里比涨跌** |
| 代价二：链接也必须带 `--coverage` | 只给编译加、链接不加 → `undefined reference to __gcov_init`（实测踩过，报错还不指向原因） |
| 代价三：环境不归仓库管 | WSL 是「这台机器装了」，不是「这个仓库保证有」；CI runner 虽是同一台机器，还得先让 WSL 起来，且 `gcov` 在 `/mnt/d`（drvfs）上读写 `.gcda/.gcno` 很慢 → 工作目录要放 WSL 本地 |
**决策记录——默认通道仍是 MSVC + mscoverage，三条理由**：① 与门禁**同一份编译开关**（原样复用
`unit_test_harness._BASE_FLAGS`），台账涨跌直接对应「门禁那份改动」；② 不依赖 WSL 起没起；
③ 零下载、零新依赖、纯标准库解析 Cobertura。**分支覆盖不做第二条通道（用户裁定 2026-10-23，本仓只留 MSVC 一条）**：
多一套工具链就多一套分母、多一本台账、多一个"这台机器到底有没有 WSL/gcov"的未决项，而换来的只有
分支这一维——不值当。代价如实记在 §7 第 1 条：本口径的绿灯**只证明行与函数被测到**。
探测顺序：环境变量 `DTU_MS_COVERAGE`（设了就必须有效，**不静默回退**，与 `DTU_MSVC_CL` 同口径）
→ 各 VS 安装根的 `Common7\IDE\Extensions\Microsoft\CodeCoverage.Console\` → PATH。
找不到即以退出码 2 失败并打印上述现实，**不会**假装通过。
## 3. 怎么跑
```powershell
# 全量：16 套单测逐套"编译（带 PDB）→ 插桩运行 → 解析 Cobertura"，最后并集 + 比基线
& '.venv\Scripts\python.exe' scripts/check_test_coverage.py
# 只跑一套（调试用；子集会跳过"在测文件消失"类回退判定，见 §5）
& '.venv\Scripts\python.exe' scripts/check_test_coverage.py --module sha256
# 刷新基线（改完测试或改完被测源码、确认过数字之后）
& '.venv\Scripts\python.exe' scripts/check_test_coverage.py --update-baseline
# 出报告（默认只打控制台；报告是一次性快照，放临时目录，不入库）
& '.venv\Scripts\python.exe' scripts/check_test_coverage.py --md $env:TEMP/cov.md --json $env:TEMP/cov.json
```
**与 L0.5 同一套发现规则**（`test/host/**/run_unit_test.py`，与 `scripts/ci_local.py` 一致），
并且**不复制任何编译配置**：脚本 import 各模块运行器、直接复用其声明式 `BUILD`（`TestBuild`），
编译开关取 `unit_test_harness._BASE_FLAGS`，只追加 `/Zi /Od` 与 `/link /INCREMENTAL:NO`。
所以"include 目录 / 桩顺序 / 测试单元路径"只有一处定义，覆盖率脚本不会漂成第二套口径。
退出码：`0` 全过且无回退 / `1` 有单测失败或覆盖率回退 / `2` 环境错误（无 cl、无 mscoverage、
编译失败、XML 缺失）/ `3` 用法错误。全量实测约 **25 s**（16 套 × 编译 + 插桩运行）。
中间产物（exe / PDB / Cobertura XML）一律落 `%TEMP%\dtu_test_cov\<模块>\`，**不进仓库**，
所以本脚本不需要新增任何 `.gitignore` 规则。
## 4. 统计面：进什么、不进什么
| | 处理 | 依据 |
|---|---|---|
| `App/**`、`Drivers/BSP/**` 的 `.c`/`.h` | **计入** | 自研生产源码，是唯一有意义的覆盖率对象 |
| `test/host/**`（测试单元自身与 `stub/`） | 不计 | 它们不是被测面；测桩的"覆盖率"是自我安慰 |
| `Lib/`（LVGL / FatFs / dhara）、`Middlewares/`、HAL / CMSIS | 不计 | 第三方；与 `cppcheck` / `coding-standard` 的排除面同口径 |
| Windows SDK / UCRT / MSVC 头 | 不计 | 同上（脚本按"仓库内 + 前缀"双重过滤） |
| **生成物**（文件头 15 行内含"自动生成 / 请勿手改 / DO NOT EDIT"） | **不进分母**，单列打印 | 现有 5 个：`ui_font_cn_12.c`、`ui_menu_tab.c/.h`、`ui_page_registry.c/.h`。给生成表算覆盖率只会稀释数字、照不出问题 |
分母一律取"**插桩报告里出现的行**"，**不做任何静态行数猜测**；`--md` 报告里"有效代码行"
那一列只用于未触及面的体量提示，不参与任何百分比。
## 5. 门禁姿态：只拦回退，不拦进步
台账 = [`scripts/test_coverage_baseline.json`](../../scripts/test_coverage_baseline.json)
（`--update-baseline` 生成，含 `totals` / `modules` / `files` / 未触及清单）。
| 情况 | 判定 | 说明 |
|---|---|---|
| 某文件 `lines_covered` 或 `funcs_covered` 比基线**少** | ❌ **REGRESS**（退出码 1） | 删了用例，或改代码让原来到达的行到不了——这才是要拦的 |
| 总计 `lines_covered` 比基线少 | ❌ REGRESS | 兜住"搬家式下降" |
| 基线里在测的文件本次整个消失（仅全量跑时判） | ❌ REGRESS | 通常是 include 链被删，或那套单测被跳过 |
| 基线里某套单测本次没跑到 / 没通过 | ❌ REGRESS | 覆盖率只在**同一套测试全绿**的前提下可比 |
| 新文件被纳入统计 | 🟡 NOTE | 进步不拦，但确认无误后要 `--update-baseline` 登记 |
| 某文件可执行行数暴涨（>1.3× 基线且 +120 行） | 🟡 NOTE | 百分比会被摊薄，提醒刷基线，免得把"没退"当成退 |
| `--module` 子集运行 | 🟡 NOTE | **跳过全部覆盖率回退判定**（并集必然变小，不是回退）：只保留「单测必须通过」与「新文件登记提示」两项；判回退必须跑全量 |
与 `layer-deps` / `bsp-err` / `id-check` 同属**增量拦截**：**绿灯只等于"没有比上次更差"**。
## 6. 首次实测（2026-10-23，基线首登值）
```
[SUMMARY] coverage: line=2552/2893 (88.2%) func=193/207 (93.2%) suites=16/16 tested_files=19 untested_files=125
```
| 事实 | 数字 |
|---|---|
| 16 套主机单测 | 全部通过（插桩运行下仍 PASS） |
| 被测到的自研生产源文件 | **19 个** / 2,893 可执行行 |
| 行覆盖最低的两个 | `Drivers/BSP/GD5F2GQ5UE/nand_ftl.c` 48.6%（123/253，函数 14/22）、`App/protocol/iec104/iec104_pts.c` 67.2%（117/174，函数 13/17） |
| 行覆盖 95%+ 的文件 | 12 个（多为纯逻辑层：`adc_health` / `sample_ring` / `vol_lock` / `time_sync` / `task_watchdog` …） |
| **从未进过任何主机单测的生产源文件** | **125 个 / 约 11,839 有效代码行**（前五：`net_socket.c` 1,251、`ch395f.c` 801、`lftpd.c` 694、`gd5f2gq5ue.c` 689、`sys_log_mcu.c` 458） |
⚠ 读法：88.2% 是"**被测的那 19 个文件内部**"的比率，**不是全仓覆盖率**。全仓的真相写在
`untested_files` 这一栏（125 个），它比 88% 这个数字有用得多——也是 §7 第三条的由来。
## 7. 限制与盲区（读这篇文档第一眼看这节）
1. **本文这条通道没有分支覆盖。** mscoverage 导出的 Cobertura 里 `branch` 恒为 `False`（实测），
MSVC 又已砍掉 `/coverage`。含义：`if (a && b)` 只走过一侧，这一行也算 100% 覆盖。
→ 报告 §5.5 想要的"覆盖到哪些分支"**没有被本文满足**，被满足的是"哪些行根本没进过"。
分支覆盖本机**能拿到**（§2.1 的 gcc + `gcov -b -c`），但**已裁定不引入第二条工具链** →
它就是本口径的**已知缺口**：绿灯只代表行与函数被测到，`if (a && b)` 的另一半要自己读用例。
补偿判据：TC 双向追溯 + 用例侧显式列边界值（`docs/测试说明/测试开发标准流程.md` §5）；
真到要分支证据那天，先看 §2.1 的三条代价再决定，别顺手装个 `dotnet-coverage` 当第二套口径。
2. **0 分母 ≠ 0%。** 125 个文件从没被任何主机单测编译过，它们**不在**覆盖率里；把"88%"读成
"仓库八成代码被测"是最常见的误读。
3. **桩会重塑被测面。** `nand_port` / `adc_input` / `cfg_file` 等用 `stub/` 顶掉真实 HAL 与日志头，
统计的是"生产 `.c` 在桩环境下可达的行"。真机才走的分支（寄存器超时、DMA 回调、SPI 错误）
在主机侧**永远 0 命中**——它们会拉低百分比，但**不是缺陷**，别为凑覆盖率造假桩。
4. **`/Od` ≠ 真机 `/O1`。** 覆盖率构建只为行映射服务，优化级别与 Keil 产物不同，
不能由它推断真机的可达性或时序。
5. **插桩会改变时序。** 动态插桩让被测程序变慢，对真实 tick/延时敏感的逻辑理论上可能被拖出
不同路径。脚本的处置是**硬要求"插桩运行仍必须 PASS"**（汇总行 + 退出码双校验）——
宁可红，也不给可疑的数字。
6. **只覆盖跑到的进程树。** 一次 `collect` 只看一次运行；没跑到的套件不进分母
（全量跑时以"模块未跑到"判 REGRESS），子集运行明确降级（§5）。
7. **头文件里的代码归 `.h`。** 统计面含 `.h`（静态内联与被展开的行落在头文件上）；当前 16 套
几乎没触及 `.h`，表里看不到它们——不要以为头文件"天生 100%"。
8. **依赖 VS 的可选组件。** 只有 BuildTools 且没勾"代码覆盖率工具"的机器会退出码 2；
CI runner 与本机同一台（`docs/CI/README.md`），但**换机先跑 `--list` 再跑全量**。
9. **并集口径下"单套百分比"没有意义。** 同一文件被多套触及很常见（`sha256.c` 被 `sha256` 与
`ftp_auth` 都编译），所以对外只报**并集**，单套只报"触及几个文件 / 多少行"。
## 8. 接线状态与下一步
**已落地**：脚本、基线台账、口径（本文）、`scripts/ci_local.py --coverage` 一条入口。
**未挂 pre-commit**，三条理由（不是忘了）：
1. 39 个钩子里已有 16 个主机单测钩子（每套各编译各跑），再加一份"全量插桩"是**同一件事做两遍**，
还要多约 25 s；
2. 它依赖 VS 可选组件（§7 第 8 条）。挂之前必须先定"缺组件时 skip 还是 FAIL"——
选 skip 就是一个会静默失效的门禁（与 `AGENTS.md` 里那条 `always: true 已失效、必须靠 files: 覆盖`
是同一类坑）；
3. 基线首登后需要**真实回退事件**才算被验证过。已做的是**合成自证**（人为抬高 `test_coverage_baseline.json`
的三处数字后全量跑）：行 / 函数 / 总计三条回退路径都报 `[REGRESS]` 且退出码 1；`--module` 子集运行
不会假报回退（首版会，已修：并集口径下子集必然变小，所以 `--module` 子集跑跳过全部回退判定）。
真实事件（某次改动真把覆盖行弄少了）仍待观察。
真到接线那天，片段形状如下（这份 YAML 由接线者写进 `.pre-commit-config.yaml`，说明写进
`docs/门禁说明/` 对应那篇，不在本文维护）：
```yaml
- repo: local
hooks:
- 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
```
**下一步（按性价比排序）**：
1. 给 `net_socket.c` / `lftpd.c` / `ch395f.c` 这类"125 个未触及"里最大的几块建主机侧桩——
比把 19 个文件从 88% 推到 95% 值钱得多（覆盖率只照"进没进过"，建桩本身是这个动作里最贵的部分）。
2. **不做**：第二条覆盖率通道（gcc/WSL、`dotnet-coverage`、OpenCppCoverage 三条路都不走，用户裁定
2026-10-23）。要重开这个裁定，前提是能同时给出"两份分母怎么对齐"的答案，否则只是多一本对不上的账。
## 变更记录
| 日期 | 说明 |
|---|---|
| 2026-10-23 | 新建。落地 `scripts/check_test_coverage.py` 与 `scripts/test_coverage_baseline.json`：首次实测 16 套全通过，并集 2552/2893 行（88.2%）、函数 193/207（93.2%），在测 19 文件 / 未触及 125 文件。同步销项 `docs/问题记录/项目审查与优化建议报告.md` §4.8 空白 ①（覆盖率口径）与 §5.5 第 5 条前半、§0.1 / §0.4 / §7 对应行；`malloc(` 正则那条仍开放。**同日补 §2.1**：用户问「为什么不用 GCC」，实测本机 WSL2 Ubuntu 有 gcc/gcov 15.2.0，16 套单测在 gcc 下**全部编过且全绿**、`gcov -b -c` 确实给出分支覆盖（`nand_ftl.c` 分支 41.40%）——但换编译器=换分母（`sha256.c` gcc 105 行 vs MSVC 114 行），故默认通道不变。 |
| 2026-10-23 | **用户裁定：本仓只留 MSVC 一条覆盖率通道**，不建 gcc/WSL 第二条（"后面可能引入更多问题"）。实测数据与三条代价保留在 §2.1 当决策依据，§7 第 1 条把分支覆盖改记为**已接受缺口**，§8 下一步删掉"建通道"并写明重开该裁定的前提（必须先答"两份分母怎么对齐"）。脚本与基线**不受影响**，仍是 `mscoverage` 一条路 |
docs/问题记录/项目审查与优化建议报告.md
+14 -6
View File
@@ -19,7 +19,7 @@
| 文档与治理 | 🟢 良好 | 39 个提交钩子 + 16 套主机单测；工程 md 91 份；`doc-links` 全库 0 问题 | 新增 `编号门禁增量拦截` 与内存快照回填常态化 |
| 内存与 Flash | 🟡 可控但已换位置 | SRAM1 **57.4%**（余 55,808 B）、Flash **22.1%**、**CCM 87.9%（余 7,904 B）** | **红线从 SRAM1 迁到 CCM**（堆 2026-10-11 迁 CCM + 池 40→16 KB 后 SRAM1 已宽松） |
| 可靠性与自恢复 | 🟢 良好 | 4 个 Fault 全采集现场；IWDG 五面 `required_mask`；复位原因与 `[STACK]` 水位常开 | 台架复跑持续 PASS（今日真机 708 ms 起网、无 `[ERR]`/Fault） |
| 测试与验证 | 🟡 半办 | 16 套主机单测 + `ui-golden`/`font-charset` 入门禁；TC 双向追溯 593∶271 交集 265 | **仍无覆盖率**、`coding-standard` **仍无 `malloc` 正则** |
| 测试与验证 | 🟡 半办 | 16 套主机单测 + `ui-golden`/`font-charset` 入门禁；TC 双向追溯 593∶271 交集 265；**覆盖率口径已落地**（`../测试说明/主机单测覆盖率口径.md`：16 套并集 2552/2893 行） | `coding-standard` **仍无 `malloc` 正则**；覆盖率**未挂 pre-commit**（口径文档 §8 三条理由）、**没有分支覆盖** |
| UI 标准化 | 🟢 基本落地 | `ui_tokens.h`（L0 令牌）+ `ui_page_registry.c`（描述符注册表）+ 7 个内容页 + 两枚 UI 钩子 | **U1/U3/U4 从"未做"变为已落地**；U2 只有 `ui_w_records` 一个组件 |
### 0.3 主线建议（2026-10-22）
@@ -67,7 +67,7 @@ B0h 验 `ECC_EN`**——原先那两行的注释自己写着"否则后续 I/O
| 存储/日志 | P2-10 ❌（N-25） | 卷锁现有 5 个使用者（配置原子写 / 日志 / SOE / lftpd_io / defaultTask），容量轮转删除与 UI 读并发仍未全覆盖 | 登记簿 S-5 面（卷锁覆盖面） |
| 仓库 | D-1 ❌（N-29） | jpg 707 个 / 37.3 MB；`docs` 45.3 MB 里芯片手册占 39.5 MB；`.git` **248 MB** | 降采样 / 拆 submodule / LFS 三选一 + 历史重写；已决策暂不做 |
| UI | U2 残余（U 簇） | 组件库只有 `ui_w_records.c/h` 一个；其余仍是页内自绘 | 按产品需求决定要不要继续抽组件 |
| 测试 | 覆盖率 ❌ / `malloc` 门禁 ❌ | 无覆盖率脚本；`check_coding_standard.py` 无 `malloc(` 正则 | 见 §5.5 与 §4.8 |
| 测试 | ~~覆盖率~~ ✅ **2026-10-23 落地** / `malloc` 门禁 ❌ | 覆盖率：`scripts/check_test_coverage.py` + 基线 `scripts/test_coverage_baseline.json`（口径与**盲区**见 `../测试说明/主机单测覆盖率口径.md`）——首登 16 套并集 2552/2893 行（88.2%）、**未触及 125 个生产源文件 / 约 11.8k 行**；`check_coding_standard.py` 仍无 `malloc(` 正则 | 剩 `malloc(` 正则 + 覆盖率挂钩子（先定「缺 VS 组件时 skip 还是 FAIL」）；见 §5.5 与 §4.8 |
| CI | T-7 ❌ | 远程 CI 只跑本机一台 runner，且不跑 `@build` | 保持现状即可；扩机器前重读 `docs/CI/README.md` |
## 1. 审查方法与证据基线
@@ -226,7 +226,7 @@ defaultTask 单属主；原子写经卷锁；旧档迁移已删除。**仍列为
- 主机侧 **16 套**单测（提交门禁实跑）；板级 `test/board/` 19 文件、套件开关互斥受 `test-suite-switch` 管
- TC 双向追溯：代码侧 593 号 / 文档侧 271 号 / 交集 265，差异 13 处（当前仅告警，未升门禁）
- **两处空白**：① 无覆盖率口径；② `check_coding_standard.py` 没有 `malloc(` 正则——"自研禁用 C 库堆"
- **覆盖率口径已落地（2026-10-23）**：`scripts/check_test_coverage.py`（mscoverage 动态插桩 + Cobertura 并集）
这条铁律目前只靠人读 + 模拟器照不出来（MicroLIB C 堆仅 512 B）
- 破坏性套件（`ENABLE_DESTRUCTIVE_TESTS`）有**持久代价**（NAND 坏块记账不可逆），默认关闭是正确设计
@@ -285,8 +285,11 @@ defaultTask 单属主；原子写经卷锁；旧档迁移已删除。**仍列为
2. `check_mem_numbers.py --scan/--write`：文档里的内存数字一律由 `.map` 反查，禁止手填
3. 改栈 / 加大局部变量前后各跑一次 `stack_report.py`（静态 × 真机 `[STACK]`）
4. 子系统配额与 CCM 台账 → `../内存管理/RAM预算台账.md`；趋势 → `scripts/ram_baseline.tsv`
5. **仍未落地的两条补强**：`check_coding_standard.py` 加 `malloc(` 正则（把 C 库堆禁令变成机器拦截）、
覆盖率口径（现在只有"跑过哪些 TC"，没有"覆盖到哪些分支"）
5. **仍未落地的一条补强**：`check_coding_standard.py` 加 `malloc(` 正则（把 C 库堆禁令变成机器拦截）。
另一条「覆盖率口径」✅ **已落地 2026-10-23** → `../测试说明/主机单测覆盖率口径.md`（口径 / 基线 / 盲区
一处写完，此处不复述）。⚠ 它落地的是**行与函数**覆盖，**分支覆盖本机拿不到**（无 gcc，MSVC 14.51
已无 `/coverage`）——「覆盖到哪些分支」这一半**已裁定不补**（不为它引入第二套工具链，见
`../测试说明/主机单测覆盖率口径.md` §2.1），当前补偿 = TC 双向追溯 + 用例显式列边界值
## 6. UI 界面标准化：从方案到已落地
@@ -331,7 +334,7 @@ W6 簇按 U4 → U1 → U3 → U2 的顺序执行完毕（U2 停在"够用即止
|---|---|---|
| ~~W3 预算与内存~~ ⏸ | R-9 ✅ / R-2 后半、R-3、R-4、R-6 暂缓 | 暂缓期间无验收动作，观测照常 |
| W4 结构债 | N-14 ⏸、F-5 🟡、S-1/S-2/S-4/S-5、N-25 | `--strict` 已默认；S-5 契约/门禁已落地并收编三模块，`consume-result` 已把"丢弃返回值"纳入机械检查（基线 19→1→38；剩 GD5F 码集收编、C4 快照、37 条丢弃点、标坏策略） |
| W5 验证常态 | 覆盖率、`malloc` 正则、TC 差异 13 处升门禁 | 逢窗口顺手做 |
| W5 验证常态 | ~~覆盖率~~ ✅ 2026-10-23、`malloc` 正则、TC 差异 13 处升门禁 | 逢窗口顺手做 |
| W6 UI 扩展 | U2 残余、U5 页量 | 随产品需求，不再单列专项 |
| W7 仓库决策 | D-1（N-29） | 已决策暂不处理；对外交付前重评 |
@@ -448,6 +451,10 @@ admin/admin（SHA-256 `pwd_hash`）→ 该脚本**必然登录失败**；它是
| | 数字联动照做：两份 `data/` 快照重跑、`ram_baseline --update/--write`、`check_mem_numbers --write`、FLASH 与
任务栈两张配图重算重生成（逐文本复查越界 = 0）、本文 §1.3/§5.1/§5.4 与部署文档 §3.3 同步；§0.4 的 S-2 行按
「完成即销项」改写、§9 拆出 S-2 行标 ✅。 |
| **2026-10-23** | **执行 §5.5 第 5 条前半：覆盖率口径落地并销项**（§4.8 空白 ①） | 新增 `scripts/check_test_coverage.py`（纯标准库）+ 基线台账 `scripts/test_coverage_baseline.json`。**工具链是实测出来的、不是查到的**：本机 PATH 上 gcc/gcov/clang/llvm-cov/lcov/gcovr **全无**；`cl /coverage`、`/fsanitize=coverage` 在 MSVC 14.51 已被砍——**只报 `warning D9002 忽略未知选项`，然后照常编译成功**（拿它做覆盖率＝静默假数据，比报错更坏）；`Team Tools\Dynamic Code Coverage Tools\CodeCoverage.exe`（17.0）的 `collect`/`analyze`/`instrument` 一律只打印「用法: CodeCoverage <command>」。最终走 **mscoverage（`Microsoft.CodeCoverage.Console.exe` 18.x）`collect -f cobertura`** 的**加载期动态插桩**，并实测它**原样透传子进程退出码**（子进程 `return 3` → `collect` 也返回 3）→ 于是「插桩运行下仍必须 PASS」可以当硬条件用。 |
| | | **口径**：只算 `App/**` 与 `Drivers/BSP/**` 的行/函数、多套单测取**并集**、生成物（文件头写「自动生成 / 请勿手改」）不进分母、分母一律来自插桩报告**不猜行数**；配置零复制——脚本 import 各运行器的 `TestBuild`、开关取 `unit_test_harness._BASE_FLAGS`，只追加 `/Zi /Od` 与 `/link /INCREMENTAL:NO`，发现规则与 L0.5 同一条 `test/host/**/run_unit_test.py`，**不会漂出第二套口径**。 |
| | | **首登数字（2026-10-23）**：16 套全通过，并集 2552/2893 行（88.2%）、193/207 函数（93.2%）、19 个生产文件在测，**未触及 125 个生产源文件 / 约 11,839 行**（`net_socket.c` 1,251 行最大）——最后一栏才是这套口径真正照出来的东西。**门禁自证**：人为抬高基线后，行 / 函数 / 总计三条回退路径都如期报 REGRESS 且退出码 1；`--module` 子集运行不会假报总计回退（首版就会，已修）。**刻意未挂 pre-commit**：三条理由与可直接粘的 YAML 片段写在 `../测试说明/主机单测覆盖率口径.md` §8，接线者照 §8 落地即可。 |
| | | **仍开放**：§5.5 第 5 条的另一半（`check_coding_standard.py` 加 `malloc(` 正则）与**分支覆盖**。分支覆盖**不是拿不到**：同日被用户问住后复测，本机 WSL2 Ubuntu 有 gcc/gcov 15.2.0，16 套单测在 gcc 下**全部编过且全绿**、`gcov -b -c` 出分支数据（`nand_ftl.c` 分支至少走过一次 41.40%）；但换编译器就是换分母（`sha256.c` gcc 105 行 vs MSVC 114 行）→ **用户裁定只保留 MSVC 一条通道**（多一套工具链=多一套分母 +多一本台账 + 多一个"这台机器有没有 WSL"的未决项），分支覆盖**记为已接受缺口**、不是待办。实测表与决策依据见 `../测试说明/主机单测覆盖率口径.md` §2.1。本轮只加 `.py`/`.json`/`.md`，无 `.c/.h` 改动，不重跑 `@build`；文档面动 §0.1 / §0.4 / §4.8 / §5.5 / §7 与 `docs/README.md` 索引各一处。 |
| **2026-10-23** | **术语迁移**：`bsp-err` 的四项检查从 `R1/R2/R3/R4` 改成语义标签 | 用户一句「R4
| | 到底是什么」问出来的。这四个号**是我自己造的**，而 `R1~R8` 在本仓是"专项风险"的裸形编号
| | （`id_registry.json` 已登记那一族，保护规划 `R1~R8`、看门狗 `R1~R7` 的风险表都在用），`R-2`
@@ -657,3 +664,4 @@ USER CODE 区内只留「读 RCC_CSR → 写 RMVF 清除」两句、顺序约束
| **R-9（`LV_MEM_SIZE` 40→16 KB，登记簿 N-27 原 W3 的第一步，2026-10-15 已执行；该簇其余部分同日整簇暂缓）** | 取值依据与再降 8 KB 的前置写在 `Lib/lv_conf.h` 与 `simulator/lv_conf.h` 的池注释；实测水位 → `../内存管理/RAM使用分析与优化方案.md` §2.6.2 与 §阶段 1.1（已执行）；解锁链第 ① 步 ✅（后续步骤暂缓）→ `../内存管理/RAM预算台账.md` §3；池容量口径 → `../UI设计/UI_设计架构.md` §1.2、`../UI设计/UI_界面制作流程.md` C4 |
| **N-12 / N-13**（dhara 移植层 `is_free` 精度 + HAL 越界守卫，登记簿 **N-21**，2026-10-15 已销项） | `../架构设计/STM32F4-Base存储架构说明.md` §5.3（移植层两条硬约束：整页精确的原因链 + 错误码取舍与"为什么不会静默清卷"）+ `Drivers/BSP/GD5F2GQ5UE/nand_ftl.c` 的 `ftl_page_in_range` / `ftl_block_in_range` / `dhara_nand_is_free` 注释 + 主机侧单测 `test/host/nand_port/`（含"旧算法只看页首 64 B"的对照用例，防止将来被改回去） |
| **N-16**（日志读写放大，登记簿 **N-24**，2026-10-15 已销项） | `../子系统设计/运行与自检记录设计说明.md` §4.4（写侧批量合并 + **掉电语义不变**的论证 + 失败回投不丢条目 + 容量轮转只在慢路径）与 §4.5（读侧 8 条窗口 + 写者代数失效 + API 不变）+ `App/log/sys_log_mcu.c` 的 `s_format_rec` / `s_append_rec` / `s_append_many` / `s_read_raw` 注释 |
| **§4.8 空白 ①「无覆盖率口径」+ §5.5 第 5 条前半（2026-10-23 销项；§5.5 后半的 `malloc(` 正则仍开放）** | `../测试说明/主机单测覆盖率口径.md`（口径 / 工具链实测 / 统计面 / 门禁姿态 / **九条限制与盲区** / 未挂钩子的三条理由与待粘 YAML）+ `scripts/check_test_coverage.py`（`--list` / `--module` / `--update-baseline` / `--md` / `--json`）+ 基线台账 `scripts/test_coverage_baseline.json`（首登 2552/2893 行、未触及 125 文件） |