wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
728d60675f29bab0af51f6cb500f2ebcf20323cc
STM32F4-Base/docs/门禁说明/host-unit-tests.md
T
wandering1 1d39571114 feat(门禁): 第 51 条 nested-comment——把 ARMCC #9-D 的按包含者刷屏拦在提交前 
动机是今天一天复发三次的同一形态：在块注释里写作用域路径，那个 `/*` 被 ARMCC 当第二次注释起点（诊断 9-D），
而且**按包含者数量刷屏、只在重编译那个 TU 时才暴露**——本仓的诱因就是「注释里写 Drivers/BSP/UI/**」。
AGENTS 早就写了这条铁律（写全目录或用尖括号），但它一直是纯口头纪律，所以同一天还是复发三次。

新脚本 scripts/check_nested_comment.py：纯标准库、只读、五状态机（代码 / 行注释 / 块注释 / 字符串 / 字符
字面量），**只有块注释体内的 /* 才算问题**——字符串里的、行注释里的、未闭合判定都不误报。口径上刻意与钩子
的 types: [c] 对齐（403 个 .c/.h 同面），避免「手跑面 ≠ 提交面」这类我们今天就踩过的错位；零第三方依赖是
刻意的，为了让 generated-fresh 那天的解释器假红不长第二遍（实测 .venv 与机器级 C:Python314 两种解释器结论
一致）。

存量口径：全仓实扫**新发 0、存量 2 处**（test/host/common/ch395f_fake.h:7 与 fatfs_fake.h:9，同一形态
「注释里写作用域 test/host/**」）。两份假件头不参与 MCU 构建所以今天不报，一旦被 include 进板端 TU 就会
按包含者刷 9-D——属 test/ 写域，作者**没代改**，而是钉进 BASELINE 走只减不增，**其余零豁免**。

自证有一条必须写清的诚实边界：作者想「拿旧字节回放今天那三处真复发」，实测**做不到**——近 150 个提交里被
改过的 281 份 .c/.h 旧字节**零命中**，因为那三处同类从来没有一处在 HEAD 里留过字节（全靠人工编译后清掉）。
于是改测**形态**（这是能证的部分）：10 项形态电池 10/10，含把已入库的尖括号写法退回星号形态 → 命中 1 处；
另用现存两份真字节做双跑：空基线 → 2 条 [NEW] + exit 1，加基线 → exit 0，证明**基线只决定算不算新的，
不掩盖有没有**。编译器侧原文（run_par.c(267) #9-D）冻结抄进新文档 §2.1——构建日志每次 @build 被覆盖且不入库，
所以文档里刻意没写「最近一次日志里仍有」这种会过期的话。

计数三处同批：AGENTS「共 **51** 个钩子」、门禁索引「51 个 hook → 27 篇 + 1 指针 + 1 外置」、配置声明；并记
文本 grep「 - id:」= 52 的成因（第 65 行被注释掉的 clang-format 候选），收紧行首口径 = 51。作者顺带自打了
一次：在配置注释里复述了那个 grep 字面量 → 文本计数当场虚高 1，已改写并把「配置注释里别复述字面量」写进
README §2 与 AGENTS。

同笔带上 task-28 的裁定句（AGENTS 一只文件里两卡改动天然混在一起，拆开会多两次改写与一次风险）：不补第
23 根 ui-sink 专属钩子——22 根的唯一意义是秒级归因，而 ui_sink 失败面全落在 test-coverage 总闸必跑路径、
失败照样拦；读「这套跑没跑」去看总闸输出，别数钩子。

实测与本笔自查：validate-config = 0；nested-comment --selftest 4/4、--all = 403 / 新发 0 /
存量 2 → exit 0；
doc-links --sections-strict（4 篇）= 0；gen_task_table --check = 0；generated-fresh
PASS（5 处存量走 WARN）；
check_ids --strict exit 0，**不可判定绝对数全程未被本闸吃掉**（作者开工 1,162、写完新闸与新文档仍 1,162；
现 1,156 是队友还清的）；全部改动文件 noBOM / LF / U+FFFD=0。未跑 pre-commit --all-files（只跑本闸）。

**本笔使用 --no-verify 的凭证（唯一允许的两条之一，按 MEMORY 台账例外口径）**：把本批 6 只文件单独
staged 后跑 `pre-commit run --files <这 6 只>` → **13 条 Passed / 1 条 Failed**
唯一失败的是 `mem-budget`
（RAM 92% 阈值，**全树检查**）。本批**零固件源、零 .map 变更**，该红来自其他队友在飞的固件改动造成的 .map
漂移（当前树 Code=231,952 / RW=1,528 / ZI=136,264，在库台账 231,712 / 1,504 / 136,216
差 = run_par setter
与 vol_lock 计数两笔，均未提交）；台账回填由我在树能编后统一 `--write`，不在分支上跑（避免多分支同改受管表）。
gate: only mem-budget pending lead ledger backfill。字节卫生本笔自查：6 只文件均 noBOM / L
F / U+FFFD=0，
新脚本纯 ASCII 输出路径无关，AGENTS 与索引两处计数与配置 YAML 解析口径 51 一致。

另收一条今天反复出现的元教训（Lead 与作者各错过一次、方向相反）：**`pre-commit run` 与 git 钩子不是同一根
探针**——config 处于 modified-unstaged 时只有后者 [ERROR] 拒绝，前者与 validate-config 都 Passed
。它与「stash
只覆盖已跟踪未暂存」「未跟踪文件永不进 stash」同族：手跑的探针不能替真提交的探针作证。
2026-10-27 03:44:18 +08:00

12 KiB
Raw Blame History

主机侧单测（22 个 *-unit-test 钩子）— 同一机制的 22 个实例

一句话：把不依赖硬件的逻辑层拿到 PC 上编译并跑断言（每个模块一个 test/host/<模块>/run_unit_test.py）。 它是"回归最快的两层之一"（静态层 + 逻辑层），但不等于真机正确。

  • 22 个钩子各有一个 files: 白名单（改动被测模块或测试目录才跑）、pass_filenames: false； 远端 CI 只跑 L0 静态门禁 + L0.5 主机侧单测（见 docs/CI/README.md）。

1. 它在查什么（22 个实例）

钩子 被测对象
watchdog-unit-test 看门狗判定状态机 App/util/task_watchdog.c
sys-clock-unit-test 系统时钟换算 App/util/sys_clock.c
cfg-file-unit-test 配置引擎 App/cfg/cfg_file.c
phasor-unit-test 相量层 App/algo/phasor.c + sample_ring.c
adc-input-unit-test ADC 输入层 App/algo/adc_input.c
vol-lock-unit-test 卷锁 App/fs/vol_lock.c
time-sync-unit-test 时间同步 App/sync/time_sync.c
adc-health-unit-test ADC 有效性校验 App/algo/adc_health.c
prot-set-unit-test 保护定值模型 App/algo/prot_set.c
prot-elm-unit-test 保护元件框架 App/algo/prot_elm.c
freq-unit-test 测频 App/algo/freq.c
sha256-unit-test SHA-256 App/util/sha256.c
ftp-auth-unit-test FTP 鉴权状态机 Drivers/BSP/NET/lftpd/lftpd_auth.c
iec104-unit-test IEC104 协议栈（ASDU / 链路 / 端口表）
soe-unit-test SOE 动作记录编解码 App/log/soe_rec.c、soe_store.c
nand-port-unit-test dhara NAND 移植层 Drivers/BSP/GD5F2GQ5UE/nand_ftl.c
adc-cal-unit-test 通道标定层 App/algo/adc_cal.c（2026-10-25 挂闸，下同）
prot-dim-unit-test 量纲回归：标定 → 相量 → 定值 → 判据链的单位与倍率一致性
meas-unit-test L2.5 遥测快照层 App/algo/meas.c（200 ms 双区，104 与 UI 共用上游）
run-par-unit-test 运行参数段 App/algo/run_par.c（遥测死区与系数）
vol-idle-sync-unit-test 卷空闲同步 App/fs/vol_idle_sync.c（空闲窗口内的 f_sync 语义）
ui-data-unit-test UI 数据快照层 Drivers/BSP/UI/ui_data.c 与各页写入方

共同机制：run_unit_test.py 在宿主编译器上编译被测 .c + 该目录的 stub/ 替身，跑断言并汇总 用例数（各模块的 TC-HOST-<模块码> 号段见 docs/编号规范.md）。

各套件的来历与牙齿（迁移自原手册；2026-10-11 至 10-15 分批挂闸）：

套件（登记出处） 规模 为什么非要有
sha256（FTP 鉴权） 13 例 FIPS 180-4 标准向量（空串 / abc / 56 B 补位跨界 / 1 MB）+ hex_eq 非法输入。哈希算错是"正确口令被拒 / 错误口令放行"的静默语义错误，板端只见 530/230 看不出根因
ftp-auth（FTP 鉴权） 36 例 连续 5 败锁定 / 60 s 解锁 / 成功清零 / tick 32 位回绕。板端每验一条要真等 60 s、回绕要跑满 49.7 天；纯函数（tick 由参数注入）就是为了让这些分支能毫秒级穷举
iec104（B4） 82 例 CP56 往返 / APCI 半帧粘帧坏帧 / STARTDT-STOPDT / 总召分片 / COV 死区 / k=12 窗满 / w=8 触发 S / 三个超时定时器 / N(R) 倒退。板端复现要真主站 + 真等待（t1=15 s、窗满要发满 12 帧）
freq（B8） 46 断言 扫频 45~55 Hz 误差 ≤0.02 Hz（实测 0.0101）/ 1% 噪声 ≤0.10 Hz / 启动收敛 ≤40 ms / 阶跃 ≤120 ms。板端无标准源照不出来；定长窗的负序泄漏纹波（0.317 Hz）只有合成扫频能暴露
soe（B9） 32 断言 64 B 定长记录编解码往返 / 截断与坏校验和拒绝 / IV 位 / seq 连续性 / 类型枚举。记录格式是磁盘上的字节级契约，错了要 FTP 下载再解码才看得见
nand-port（dhara 移植层两条硬约束） 149 断言 整页扫描的空闲判定（页首 64 B 全 0xFF 而第 1000 字节有数据等形态）+ 与旧算法对照（旧实现只看页首，同一页答"空闲"）。这类缺陷真机极难复现，发作后只表现为"某次复位后丢数据"
  • 运行器统一用 MSVC cl.exe（远端 CI 的 L0.5 层）；公共骨架是 test/host/common/unit_test_harness.py —— 改动这个骨架会同时触发 22 个钩子 （每个钩子的 files: 都把它写进触发面，这是有意的）。

2. 为什么要它

  • 状态机、编解码、换算这类逻辑，在真机上验证成本极高（要么构造故障、要么等复现）； 在 PC 上毫秒级就能重跑，是"改完敢不敢提交"的第一层信心。
  • 它们已经在真实收口上起过作用：nand-port-unit-test 与 sys-clock-unit-test 的桩里就 注入过 RTC 读失败等错误路径，用来证明失败分支的行为（本次 BSP 错误码契约收编时同步改过这两个 runner 的 include 目录，见 §6 第 4 条）。

3. 触发面

  • 只有改动该被测模块或该测试目录时对应钩子才跑（22 个钩子各管一块，改日志不会触发 22 份编译）。
  • 单独跑：& '.venv\Scripts\python.exe' test/host/<模块>/run_unit_test.py。

4. 报错怎么读

常见两类，处置完全不同：

  1. 断言失败 → 逻辑真的变了/错了：先判断是被测代码错还是期望值该更新；
  2. 编译失败（找不到头文件）→ 多为测试环境滞后：run_unit_test.py 的 include_dirs 是手写清单。今天真实发生：新加 Drivers/BSP/bsp_err.h 后，两个 runner 报"无法打开包括文件 bsp_err.h"，要在两个 runner 里补一行 os.path.join(ROOT, "Drivers", "BSP")。

5. 好处

  • 快（单套件数百毫秒级）、可在无硬件机器上跑、可在远端 CI 上跑（CI 不跑 Keil 构建，单测是唯一 能跑的代码级验证）；
  • 错误路径可注入：真机上很难制造的"RTC 读失败""扇区坏"在这里是一行赋值。

6. 限制与盲区

  1. 宿主编译器 ≠ ARMCC：ARMCC 的警告（#870-D 多字节字符、#1-D 之类）、结构体对齐、 enum 取型、MicroLIB 行为差异，本层一概照不到 → 必须 @build。
  2. 桩就是第二份真相：stub/ 与被测代码依赖的真实头文件不同步时，会出现"单测全绿、真机 行为不同"。桩签名改了而测试没跟着改，编译器未必报错（尤其桩返回宽类型）。
  3. include_dirs 与源文件清单是手写的：新依赖一个目录就会假失败（见 §4 第 2 类），反过来， 漏了某个真实依赖可能让测试编过却少编了一个翻译单元（少测而不自知）。
  4. 专属钩子不是唯一防线，而「没有专属钩子」也不等于「没被跑」。2026-10-26 按 git 历史与实测重新 清点（上一版写「16 个模块有专属钩子、另有 12 套、总闸跑 28 套」——三个数都随 2026-10-25 的 六根新钩子与后续新增套件过期了，正是本目录反复在防的"文档与机器面不同码"）：
    • 22 根专属钩子 = 有独立 files: 触发面、需要秒级归因的那个子集；
    • test/host/ 下带 run_unit_test.py 的套件实测 40 套（42 个目录，除 common 与 __pycache__）⇒ 没有专属钩子的是 18 套：cfg_file_store_mcu、console_log、 ftp_cfg、iec104_serv、lftpd、lftpd_inet、lftpd_io、net_cfg、net_events、 net_listener、net_pending、net_select、net_socket、prot_set_store、soe_store、 sys_log_mcu、task_prof、ui_sink；
    • 这 18 套每次提交都被 test-coverage 总闸真跑：发现规则是 HOST_TEST_DIR.rglob("run_unit_test.py")（与 scripts/ci_local.py 的 L0.5 同一口径）， 退出码语义写死「0 = 全部单测通过且覆盖率相对基线没回退 / 1 = 有单测失败或覆盖率回退」⇒ 失败照样拦提交。差的只是归因粒度（要在总闸输出里认出是哪套）与耗时（40 套全量比单根慢得多）；
    • 要不要给某套补第 23 根，判据现成：pre-commit 4.x 没有 always: true，该模块有没有自己的 files: 触发面决定补了会不会真跑；只为凑数加一根，等于把「快归因面」和「全量把关」两件事混成 一件，还要让钩子计数再改一次；
    • 裁定（2026-10-27，Lead）：这 18 套（含 test/host/ui_sink）不补专属钩子，差异按设计说明记录。 理由不是省事：22 根专属钩子存在的唯一意义是秒级归因；而 ui_sink 改动面小，它的失败面全部 落在 test-coverage 总闸的必跑路径里，坏了照样拦提交。再加一根只是多一个必须「声明数 / 文档数 / 实跑数」三处同源同步的计数点——本仓 2026-10-26 到 27 一天之内就为 40 / 50 / 51 这三个数不同源 返工过两轮。要读「这套跑没跑」，读总闸输出，不要来数钩子。 两个方向的空头账一起堵住： ① 别把没接线的套件算进钩子账（原写「23 个 / 含 ui-sink」正是这么错的；2026-10-27 复核的准数是 22 根 / 40 套 / 18 套无专属钩子）；② 也别把总闸的绿读成「每套都被单独归因过」——它只保证 「全跑过 + 覆盖率没回退」。将来确实要给某套补专属钩子，先过上一条判据，并在同一笔里改 AGENTS 与门禁索引的计数（口径 = YAML 解析条目数，见 docs/门禁说明/README.md §2 首条）。
    • 总闸的触发面是 App/、Drivers/BSP/、test/host/、覆盖率脚本与基线，外加门禁自身 （.pre-commit-config.yaml）——不带上自身就等于谁改坏这根闸的 files: 模式它就再也不跑 （同 lv-conf-sync / bsp-err 的既有做法）。纯 UI/文档改动不触发它，那时确实没有可回归的行为。
  5. 时序与并发不在范围：中断抢占、DMA 完成回调、临界区、真机 tick 抖动都照不到（历史上最贵的 几个坑正是这类，见 docs/问题记录/*_Trap_Records.md）。
  6. 断言写的是"作者当时想到的分支"：行 / 函数覆盖有度量了（test-coverage 总闸出 Cobertura 并守基线台账），但分支覆盖仍无——按用户裁定 2026-10-23 记为已接受缺口， 口径与理由见 docs/测试说明/主机单测覆盖率口径.md §2.1，不是待办。

7. 豁免与基线

  • 没有基线：新增或改动的模块必须自身通过。
  • 用例号段：TC-HOST-<模块码> 以 test/host/<目录>/* 为属主登记处（docs/编号规范.md）； 新增用例要带号，否则 id-check 会按形态/悬空规则处理。

8. 改这套门禁本身（新增一个模块的宿主单测）

  • 新增模块的宿主单测 = 复制一个 runner 模板 + 在 .pre-commit-config.yaml 加一个钩子 + 登记 TC 号段，三件事缺一件就会出现"测试存在但没人跑"或"跑了但无号可引"。
  • 改 include_dirs/源文件清单时，务必确认失败是环境问题而不是逻辑回归（先看是编译错还是断言错）。

9. 变更记录

日期 变更
2026-10-27 裁定入档（task-28）：18 套无专属钩子（含 ui_sink）是设计不是缺口，不补第 23 根；补钩子的判据、两个方向的空头账、「读总闸输出别数钩子」写进 §6 第 4 条。同日复核配置实数 = 解析 51 条 / 专属单测 22 根 / 套件 40 套 / 无专属钩子 18 套，与 AGENTS 那句一致
2026-10-26 数字与机器面对齐（task-18 复核带出）：实例 16 → 22（2026-10-25 由 3528644e / 48bc50e7 / ffd462ef / 8c726986 / 201d7132 / 484d0682 各挂一根，§1 表补齐 6 行）；§6 第 4 条「12 套无专属钩子 / 总闸 28 套」按实测更正为 18 套 / 40 套，并给出「没有专属钩子 ≠ 没被跑」的证据（总闸 rglob 发现规则 + 退出码语义）与补钩子的判据；顺带纠正 AGENTS 的「23 个 / 含 ui-sink」——ui-sink-unit-test 在配置历史里从未存在
2026-10-23 首篇逐项文档（16 个实例清单 + 今天两个 runner 需补 include 目录的实测）
Reference in New Issue View Git Blame Copy Permalink