wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity
Files
1b5b2f6b7e3287eb0c9c9836f4fe23583ffb51f1
STM32F4-Base/docs/门禁说明/host-unit-tests.md
T
wandering1 e4d70f9fcb docs(真值): 勘查 13 条文档/代码不一致全部处置（10 改 3 核实）+ 补 3 处 
证据源 = 主树 ci-artifacts/archify/architecture-dtu-overview-20261030-095132/
evidence.md §11。该目录不入库，故把每条的判据与实测源抄进正文，别让证据只活在
一台机器上。处置口径：能改的改成与代码同源，核实后确认文档没问题的明确写「不改」。

判停点与就绪屏障（条 1、条 3）
- AGENTS 原写 `protect_task.c:98` 直接停走判据：`:98` 是 `s_prev_cal_lock` 变量，
  判停点是 `App/task/protect_task.c:268 if (adc_cal_prot_blocked() != 0u)`，
  判定本体在标定层 `adc_cal_prot_blocked()`、protectTask 只是消费者 → 改引用，
  同步 `ui_task.c:240` 页面注释与 `docs/任务规划/数据可信.md` 的同一处行号。
- `SYS_EVT_FTP_READY` 有生产者（`Src/freertos.c:490`，注释自陈预留）无消费者；
  `SYS_EVT_TIMESYNC_READY` 全仓无生产者也无消费者（只有定义与测试桩）。
  AGENTS、`sys_events.h` 位注释、屏障配图（生成器 + 产物）三处从「四个就绪位
  并列」改成「bit0/bit1 在用 + bit2/bit3 预留」，并指向
  `docs/架构设计/项目启动顺序管理.md` §3.2 的逐位对照表。ftpTask 实际等的是
  `NET|STORAGE`（`Src/freertos.c:477-479`，WaitAll|NoClear，100 ms 分片喂狗）。

/log 不是「三本」（条 5）
- `App/log/sys_log_mcu.c` 的 `s_paths[]` = run / selftest / accid / alarm /
  start / oper / yk 七本 64B 定长文本 + `soe.log`（64B 定长二进制）+ `wdev.log`
  （变长取证行，`App/fs/vol_lock` 侧投，不走定长格式）。
  → AGENTS 两处、总览 §2.1 与 §4 的「三本」改成「七本 + SOE（+ wdev 取证行）」。

主机单测 44 套 → 47 套（条 2，两把机器尺互证）
- `scripts/check_test_coverage.py --list` 打印 47 行；`ls -d test/host/*/` = 48 个
  一级目录，唯一没有 `run_unit_test.py` 的是 `common/` ⇒ 47 套。
- 差额三名 = 屏板链路套件：`sb_proto`、`sb_link`（2026-10-29 入库）、
  `sb_led_map`（2026-10-30 入库）。专属钩子仍是 22 根 ⇒ 无专属钩子的从 22 套变 25 套。
- 同步面：AGENTS、`docs/门禁说明/README.md`、`host-unit-tests.md` §6 台账（名单补
  三名）、`docs/代码规范/pre-commit使用说明.md`、`主机单测覆盖率口径.md`（含耗时句）、
  `scripts/README.md`、总览目录树、`.pre-commit-config.yaml` 三处注释、
  `test/host/sys_log_mcu/sys_log_mcu_test.c` 一处注释。
- 带日期戳的历史测量值按纪律冻结不动：28 套、41 套 ~105 s、40 套/18 套那三处。

本仓 LVGL 版本（条 6）
- vendored 版本 = `Lib/lvgl/lv_version.h:9-11` 的 9.3.0；总览两处「LVGL v9.2」与
  `gen_arch_svg.py` 图内文字改 v9.3 并重跑产物（脚本与产物同一笔，`generated-fresh`
  逐字节核）。
- **刻意不动**：`docs/内存管理/RAM使用分析与优化方案.md` 两处「LVGL v9.2 文档」+
  GitHub `release/v9.2` 分支 URL ——那是对外游某分支文档的引用，不是本仓版本声明。

触发口径与栈值（条 4、7、9、10）
- ADC 映射 §1「ADC1 为软件触发」是旧口径：`Src/adc.c:53` 实为
  `ADC_EXTERNALTRIGCONV_T3_TRGO` → 改成 TIM3 TRGO，并补一句「TIM3 与 TPAFE 的
  CONVST 之间没有硬件耦合，仍不构成共同采样触发」，缺陷结论本身不变。
- 同文档 adcTask 栈 512 → 640 words（`Src/freertos.c:159 .stack_size = 640 * 4`）。
- `docs/UI设计/UI_设计架构.md` 的 uiTask 栈「16384 words」是单位错：
  实为 4096 words = 16384 B（`Src/freertos.c:218`），顺手补上行号。
- `App/app/app_main.c:197` 注释「DE = PD0」陈旧：`:198` 实传 `ST_DIR4_*`
  （V0.1 实板 PA15，V0.0 才是 PD0）→ 注释改指 V0.1 网表报告的引脚迁移表。
- 两处已退役编号 `N-18`（ADC 映射、V0.1 网表报告）换成登记簿条目名
  「双转换器无共同采样触发」。

核实后确认「文档没问题」的三条（条 8、12、13）
- 黄金参考「菜单 8 状态 + 内容页 66 张」：`simulator/tests/ref/` 实测 66 个
  `shot_*.bin`，与 `ui-golden` 钩子显示名一致 → 不改。
- `App/task/rs485_task.c` 存在但 `Src/freertos.c` 不创建它（grep 无 rs485）：
  AGENTS 与总览都已写明「尚未接线 / 暂缓」，图侧画成「实现待接线」→ 不改。
- 104 端口 `:2404` 是工厂默认、可经 `/config.ini` `[comm]` 改 → 总览索引表补
  「默认」二字；「uiTask 10 ms 节拍」核实 = `ui_tokens.h:65 UI_TASK_TICK_MS 10` ✓。

并行勘查会话的同族发现（它扫「文档声明数 vs 真值」，逐处独立复验后采纳 3 处）
- `App/protocol/iec104/iec104_link.h` 头注释写「端口：TCP 2404（§1.5 B0 定义）」，
  同文件下方已写「服务端口真源已迁 [comm] 段」= 自相矛盾 → 补「工厂默认」并指回
  [comm] 与「下次重 bind 即生效」。
- `scripts/gen_task_table.py` 的 iec104Task 描述「:2404 监听」→「工厂默认 :2404
  监听」，`--write` 重生成 README 任务表（AGENTS 表无描述列，实测未被改写）。
- `App/log/README.md` 五行写入点行号全漂：事故 181→188、告警 184→191、启动
  176→183（`App/task/protect_task.c`）；操作 `iec104_pts.c` 574/602→582/610、
  `default_task.c` 242→266、`sys_log_mcu.c` 646→682；遥控 573/576/582/586/596/
  598/609 → 581/584/590/594/604/606/617（宿主 `sim_syslog.c:245` 原值正确、未动）。
- **撤销一条**：我早先记的「`docs/算法/继电保护功能复现规划.md:225` 声称记录本已
  有消费者」与原文不符——:225 实为规划表里「动作/SOE 记录 | 复用 `sys_log`」一行，
  属能力复用口径、不是当前态断言 → 不改。教训：**改引用前逐处读现文，别照自己
  上一轮的笔记盲替**（这条比改中的每一处都值钱）。
- 同一批勘查还报了约 12 处「`2404` 缺『工厂默认』限定词」（AGENTS、`App/protocol/
  README.md`、`Src/freertos.c` 注释、5 篇 docs、`test/host` 工具，含一张配图生成器
  要连产物同批重跑）与 `测试开发标准流程.md`「像素层 60 内容页」、
  `.pre-commit-config.yaml` uinav 注释「快检档 18 张黄金参考」（后者写时为真、
  描述的却是钩子现有行为）：**本笔刻意不做**，另开任务空间处理——那批要同时动
  AGENTS.md 与 `.pre-commit-config.yaml` 两处单写者面，与并行会话撞车的代价更高。
- 端口生效语义（用户裁定 2026-10-30）：产品基线写「公共地址与端口可配…改后需重启
  生效」，代码 `App/task/iec104_serv.c` 是「ca 改后要重启；port 下次重 bind 才生效」
  ——裁定**按代码语义要改**处理（改了端口应立刻重 bind），属固件行为变更，另开任务
  且需真机验证；`.serialtest/config.json` 写死 `i104: listening on 2404` 必检锚点
  是同题（现场改端口会让串口回归假失败），一并留给那条任务。

自查（任务树内）
- `check_doc_links.py --sections-strict`：12 个改动 .md 逐个 rc=0；
  `check_mermaid.py` 改动 .md 全 rc=0；`check_generated_fresh.py` PASS
  （25 个生成器 / 21 一致 / 4 存量基线）；`check_nested_comment.py --all` PASS
  （449 文件，新发 0、存量 2）；`check_bom_drift.py --all` 99 个名单文件无漂移。
- 编译：`.dsh/skills/keil-build` 退出码 0（0 错误 0 警告），
  Program Size Code=246720 RO=29836 RW=2052 ZI=149708 —— 与本树凭证同码，
  证明这批改的确实只有注释与文档。
- 字节体检：23 个文件无 CR / U+FFFD / 行尾空格 / 缺末行换行；`ui_task.c` 被编辑后
  丢的 3 字节 BOM 已补回（bom-guard 复验通过）；5 处「三连空行」逐文件与
  HEAD 比对确认是存量（Python 生成器的 PEP8 双空行与个别 C 文件原有空行）。
- 一次性工具 `ci-artifacts/fix_docs2.py`：断言式规则表，按文件读一次、在演化文本上
  逐条替换、一次写盘。第一版写成「每条规则各自从启动时快照起算」，同一文件后一条
  把前一条整体覆盖，只有每文件最后一条活下来——靠「改完再全仓复扫旧形态」当场抓到，
  这条判据本身已值得写进流程。
- 待办：`git add` 后需重跑 `ram_baseline.py --update`（体积凭证按 git 索引内容生成，
  未 staged 的文件不在凭证里，`check_size_gate.py --local` 现在因此报红）。
- 未 commit、未 push（AGENTS.md 边界：提交属 Ask first）。
2026-10-30 14:19:35 +08:00

13 KiB
Raw Blame History

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

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

  • 22 个钩子各有一个 files: 白名单（改动被测模块或测试目录才跑）、pass_filenames: false； 远端 CI 只跑 静态门禁 + 主机侧纯逻辑单测（见 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 测频与遥测快照层 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 的 主机侧纯逻辑单测层）；公共骨架是 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 行为差异，本层一概照不到 → 必须 /keil-build。
  2. 桩就是第二份真相：stub/ 与被测代码依赖的真实头文件不同步时，会出现"单测全绿、真机 行为不同"。桩签名改了而测试没跟着改，编译器未必报错（尤其桩返回宽类型）。
  3. include_dirs 与源文件清单是手写的：新依赖一个目录就会假失败（见 §4 第 2 类），反过来， 漏了某个真实依赖可能让测试编过却少编了一个翻译单元（少测而不自知）。
  4. 专属钩子不是唯一防线，而「没有专属钩子」也不等于「没被跑」。2026-10-26 按 git 历史与实测重新 清点（2026-10-28 复点、2026-10-29 录波三套入库后再复点：下列数字已按复点值更新；上一版写「16 个模块有专属钩子、另有 12 套、总闸跑 28 套」——三个数都随 2026-10-25 的 六根新钩子与后续新增套件过期了，正是本目录反复在防的"文档与机器面不同码"）：
    • 22 根专属钩子 = 有独立 files: 触发面、需要秒级归因的那个子集；
    • test/host/ 下带 run_unit_test.py 的套件实测 47 套（48 个目录，除 common 与 __pycache__；两个数分别来自 check_test_coverage.py --list（47 行）与 ls -d test/host/*/（48 个目录），2026-10-30 复点） ⇒ 没有专属钩子的是 25 套：boot_stats、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、sb_led_map、sb_link、sb_proto、soe_store、 sys_log_mcu、task_prof、ui_sink、wave_ring、wave_store、wave_trig（末三套 2026-10-29 随 故障录波入库，屏板三套（sb_proto/sb_link 2026-10-29、sb_led_map 2026-10-30）随屏板链路入库，同一条 Lead 裁定不补专属钩子；25 = 47 套 − 22 根专属钩子，逐点数与两处机器源互证）；
    • 这 22 套每次 CI 与 scripts/ci_local.py 都由 test-coverage 总闸真跑（该钩子带 stages: [manual]： git commit 阶段不跑它，这一根与 cppcheck / test-cppcheck 同属 CI 与 ci_local.py 的 manual 段）； 发现规则是 HOST_TEST_DIR.rglob("run_unit_test.py")（与 scripts/ci_local.py 的主机侧纯逻辑单测同一口径）， 退出码语义写死「0 = 全部单测通过且覆盖率相对基线没回退 / 1 = 有单测失败或覆盖率回退」⇒ 失败照样拦（CI 与 ci_local.py 的 manual 段）。差的只是归因粒度（要在总闸输出里认出是哪套）与耗时（47 套全量比单根慢得多）；
    • 要不要给某套补第 23 根，判据现成：pre-commit 4.x 没有 always: true，该模块有没有自己的 files: 触发面决定补了会不会真跑；只为凑数加一根，等于把「快归因面」和「全量把关」两件事混成 一件，还要让钩子计数再改一次；
    • 裁定（2026-10-27，Lead）：这批无专属钩子套件（裁定当时 18 套，2026-10-28 为 19 套，2026-10-29 现值 22 套；含 test/host/ui_sink 与新增的 wave_ring / wave_store / wave_trig）不补专属钩子，差异按设计说明记录。 理由不是省事：22 根专属钩子存在的唯一意义是秒级归因；而 ui_sink 改动面小，它的失败面全部 落在 test-coverage 总闸的必跑路径里，坏了照样在 CI / ci_local.py 拦下。再加一根只是多一个必须「声明数 / 文档数 / 实跑数」三处同源同步的计数点——本仓 2026-10-26 到 27 一天之内就为 40 / 50 / 51 这三个数不同源 返工过两轮。要读「这套跑没跑」，读总闸输出，不要来数钩子。 两个方向的空头账一起堵住： ① 别把没接线的套件算进钩子账（原写「23 个 / 含 ui-sink」正是这么错的；2026-10-27 复核的准数是 22 根 / 40 套 / 18 套无专属钩子（三个数都是当时值）——第 41 套 boot_stats 当日 11:29 才入库，此后两数当时是 41 / 19，现值 47 / 25 以本条上面的实测行为准）；② 也别把总闸的绿读成「每套都被单独归因过」——它只保证 「全跑过 + 覆盖率没回退」。将来确实要给某套补专属钩子，先过上一条判据，并在同一笔里改 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 §4.1）； 该号段 2026-10-27 起停发新号（用户裁定「批次三，不坐」）：新增用例不配号，写语义化测试函数名， 现存号只读、不清、不复用。追溯器只双向比对已有集合，不会因为新用例没号而报错——别把它当"要带号"。 当时的机器口径（2026-10-27 落地，如今只剩留痕）：scripts/archive/id_gate/id_registry.json 37 个 TC 类族登记 frozen: true、34 个子族游标冻结在当日存量最高号， 当年在号段上再加新号 = id-check 校验 5 错误级；无专属子族的模块码落在主族 TC（游标仍为空）。两道编号门禁已退役（2026-10-28 / 29），这些校验都不再跑，那一面如今只由规范与评审兜住 → docs/编号规范.md §4.1 末框与 scripts/archive/id_gate/编号治理历史.md §9.1 末段。

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

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