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

docs(编号): 测试验证层级文档面清号 + 修上一批改名留下的双写与错族疤（27 篇）

Browse Source 
同族第三道（文档面）。上一批只改了 10 篇测试文档，本笔清掉余下 27 篇的层级号，并修
那批机械替换留下的两类疤。

- 层级号改语义名：各单元测试说明的「**门禁层级** | L0.5 层（介于 L0 静态门禁与 L1
  板端套件之间）」→「主机侧纯逻辑单测（介于静态门禁与板端测试套件之间）」；
  「板端（L1）」「L1/L2」「L3 人工」等表头与列值同批改写；测试文档模板规范的模板
  字段同步（它决定以后每篇测试说明怎么写这一栏）。
- 「模拟器回归」旧号（原文标 L3/L2）**不映射**成新语义名，就地写「模拟器回归」：
  它与「主机侧回归」是两回事，硬映射等于造一处新的口径错。
- 修双写疤 17 处（替换串套替换串的产物）：文档道改完 Lead 点名的 8 处后中途失败，
  Lead 接手余下 9 处——测试开发标准流程 7、CI README 1、门禁说明/host-unit-tests 1、
  任务规划/测试与架构专项 1。
- 修**错族替换疤**（比双写更坏：字面改对、意思改错）：ADC输入层单元测试说明与
  相量层单元测试说明的「介于 L0 静态门禁与 语义取数与有效性板端套件之间」——上一批
  把测试层的 L1 换成了采集链层名；本笔随该行改写一并修正。产品需求 §7.4 同类问题
  在上一笔（代码道）修。
- 变更记录历史行按「行内换号、日期与技术事实不动」处理（与「卡」族先例一致），
  换算表与撞族警示在 scripts/archive/id_gate/编号治理历史.md §10 / §10.1。
- 刻意未动：docs/芯片手册（外部手册原文）、UI 菜单层级残留 2 处与采集链旧层名残留
  （已登记 task-12）、test/board 的链路时延段号残留（task-11）。
- 门禁：check_doc_links --all --sections-strict 通过（195 篇、章节引用 3292 处）；
  id-check-new --worktree rc=0（剩 2 处 WARN 是变更记录行里的已停发测试专项号，
  不拦提交，本笔不越族去动它）；112 个改动文件 U+FFFD=0、无 CR、BOM 与 HEAD 一致；
  git diff --check 干净。
This commit is contained in:
Wanderingss
2026-10-28 17:56:21 +08:00
parent 04997e48aa
commit 83011abb16
27 changed files with 111 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/环境与部署/项目部署环境要求.md
+12 -12
View File
@@ -67,9 +67,9 @@ Graphviz / Cppcheck 的安装位置差异一律用 `DTU_*` 环境变量表达（
|---|---|---|---|
| `DTU_KEIL_UV4` | **必需**（MCU 构建机） | UV4.exe 完整路径 | `keil_build.py`（`@build`） |
| `DTU_STLINK_CLI` | **必需**（用 ST-LINK CLI 的机器；已在 PATH 可不设） | ST-LINK_CLI.exe 完整路径 | `stlink_flash.py`（烧录/复位/回读） |
| `DTU_PRECOMMIT_PYTHON` | 可选（pre-commit 不在 `.venv`/当前解释器时设；CI runner 建议必设） | 装有 pre-commit 的 python.exe 完整路径 | `scripts/ci_local.py`、CI L0/L0.5 |
| `DTU_CPPCHECK` | 可选（开发机入 PATH 即可；无 PATH 的 CI runner 建议设） | cppcheck.exe 完整路径 | pre-commit cppcheck 钩子、CI L0 |
| `DTU_MSVC_CL` | 可选（VS 标准位置时自动探测） | x64 `cl.exe` 完整路径 | 主机侧单测、CI L0.5 |
| `DTU_PRECOMMIT_PYTHON` | 可选（pre-commit 不在 `.venv`/当前解释器时设；CI runner 建议必设） | 装有 pre-commit 的 python.exe 完整路径 | `scripts/ci_local.py`、CI 静态门禁 / 主机侧纯逻辑单测 |
| `DTU_CPPCHECK` | 可选（开发机入 PATH 即可；无 PATH 的 CI runner 建议设） | cppcheck.exe 完整路径 | pre-commit cppcheck 钩子、CI 静态门禁 |
| `DTU_MSVC_CL` | 可选（VS 标准位置时自动探测） | x64 `cl.exe` 完整路径 | 主机侧纯逻辑单测（本地与 CI） |
| `DTU_WINDOWS_KITS_ROOT` | 可选（SDK 标准位置时自动探测） | `Windows Kits\10` 根目录 | 主机侧单测 |
| `DTU_VSWHERE` | 可选（VS 标准位置时由 `%ProgramFiles(x86)%` 自动推导） | vswhere.exe 完整路径 | `simulator/build_sim.ps1` |
| `DTU_GRAPHVIZ_DOT` | 可选（PATH 可发现时不设） | dot.exe 完整路径 | `tools/refgraph` 渲染 |
@@ -157,7 +157,7 @@ Graphviz / Cppcheck 的安装位置差异一律用 `DTU_*` 环境变量表达（
|---|---|---|
| 统一入口 | **仓库 `.venv\Scripts\python.exe`** | 一切依赖第三方库的脚本（字体生成、截图转 PNG、RemoDispBus 回归）都用它 |
| 解释器版本 | Python ≥ 3.10（任意发行版） | 种子解释器仅用于建 venv 一次；本机为 3.12.4 |
| 依赖 | `fonttools==4.51.0`、`pillow==10.3.0`、`pyserial==3.5`、`pre-commit==4.6.2` | 清单 = 仓库根 `requirements.txt`（**必须保持纯 ASCII**：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError）；`pre-commit` 入 `.venv` 后，重建 venv 即可直接跑 L0 门禁（`scripts/ci_local.py` 自动选用） |
| 依赖 | `fonttools==4.51.0`、`pillow==10.3.0`、`pyserial==3.5`、`pre-commit==4.6.2` | 清单 = 仓库根 `requirements.txt`（**必须保持纯 ASCII**：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError）；`pre-commit` 入 `.venv` 后，重建 venv 即可直接跑静态门禁（`scripts/ci_local.py` 自动选用） |
| 入库情况 | `.venv/` 已 gitignore | **换机/首次必须重建** |
```powershell
@@ -207,7 +207,7 @@ python tools/font_gen/extract_cn.py # 任意 python3：
> 检查范围仅项目自有代码；`Lib/`、`Middlewares/`、`Drivers/BSP/UI`、`lftpd`、`dhara`、`test/` 等被排除。
> 全库扫描：`pre-commit run --all-files`。详见 `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`。
>
> ⚠ **新增 L0.5 单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"**：
> ⚠ **新增主机侧纯逻辑单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"**：
> 只要装了 VS（§2.3）就自动具备，无需额外安装；但**完全未装 VS 的机器在改动看门狗相关文件时会被钩子拦截**。
### 2.8 引用关系图渲染（Graphviz，可选）
@@ -410,7 +410,7 @@ pre-commit run --all-files
### 2.11 CI runner 环境（Gitea Actions，2026-10-01 起）
CI 跑 **L0 静态门禁 + L0.5 主机侧单测**（**不含 L1/L2/L3**——需真机 + ST-LINK，只在本地）。
CI 跑 **静态门禁 + 主机侧纯逻辑单测**（**不含板端测试套件 / 主机侧回归 / 人工目检**——需真机 + ST-LINK，只在本地）。
workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测试说明/测试开发标准流程.md`](../测试说明/测试开发标准流程.md) §9。
| 项 | 要求 | 说明 |
@@ -418,14 +418,14 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测
| Gitea 版本 | ≥ 1.21（实测远程 **1.25.4**） | workflow 置于 `.gitea/workflows/`，兼容 GitHub Actions 语法 |
| Actions 开关 | 实例 `[actions] ENABLED = true` | site admin 配置；未开启则 push 不触发任何 job |
| runner OS | **Windows**（`runs-on: windows`） | labels 须含 `windows`；与开发机同平台，避免脚本语法分叉 |
| runner 软件 | Python 3.x、cppcheck、pre-commit、**MSVC**（VS C++ 工具链 + Windows SDK） | 前三个缺 → `l0-gates` **硬失败**（`::error::`）；MSVC 缺 → `l05-host-unit-tests` **降级跳过并告警**（不硬失败，但等于 L0.5 裸奔）。runner 以 SYSTEM 服务运行，**用户级 PATH/变量不可见**：自动发现失败时用**机器级** `DTU_PRECOMMIT_PYTHON` / `DTU_CPPCHECK` / `DTU_MSVC_CL` 注入（见 `docs/CI/远程CI完整指南.md` §4.1.3） |
| runner 软件 | Python 3.x、cppcheck、pre-commit、**MSVC**（VS C++ 工具链 + Windows SDK） | 前三个缺 → `static-gates` **硬失败**（`::error::`）；MSVC 缺 → `host-unit-tests` **降级跳过并告警**（不硬失败，但等于主机侧纯逻辑单测裸奔）。runner 以 SYSTEM 服务运行，**用户级 PATH/变量不可见**：自动发现失败时用**机器级** `DTU_PRECOMMIT_PYTHON` / `DTU_CPPCHECK` / `DTU_MSVC_CL` 注入（见 `docs/CI/远程CI完整指南.md` §4.1.3） |
| Keil | **不需要** | 刻意不跑 `@build`（需授权）；`.map` 缺失时 `mem-numbers` 钩子自动跳过 |
| `mem-numbers` | 有 `.map` 就跑，无则 `SKIP` | Keil 构建产物 `.map` 已 gitignore；自建带 Keil 的 runner 会照常跑该钩子 |
**runner 就绪前的过渡**：CI 只是"多一道网"，**不能替代本地门禁**。提交前仍须在本地跑：
```powershell
& '.venv\Scripts\python.exe' scripts/ci_local.py # 与 CI 同一套判定（L0 + L0.5）
& '.venv\Scripts\python.exe' scripts/ci_local.py # 与 CI 同一套判定（静态门禁 + 主机侧纯逻辑单测）
```
### 2.12 跨机验证（第二台机器 / 换机验收清单）
@@ -453,7 +453,7 @@ Test-Path $env:DTU_STLINK_CLI # True
|---|---|---|---|
| ① | `& <任一 python> -m venv .venv` + `& '.venv\Scripts\python.exe' -m pip install -r requirements.txt` | 安装完成且含 pre-commit | pip 报 GBK 解码错 = `requirements.txt` 被污染（该文件必须纯 ASCII，不该发生） |
| ② | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` | `BUILD_OK: 0 errors, 0 warnings`，exit 0 | 报错行**直接指出变量名**（如 `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: ...`）——照报错修值；新机器首次启动 UV4 需 license（90 天评估），缺 Device Pack 则下载失败（构建不受影响） |
| ③ | `& '.venv\Scripts\python.exe' scripts/ci_local.py` | L0 全钩子 Passed + L0.5 单测断言全部通过（当前 278 条），exit 0 | "找不到 MSVC" = VS 未装或装到非标准位置（设 `DTU_MSVC_CL` 可验证覆盖通道） |
| ③ | `& '.venv\Scripts\python.exe' scripts/ci_local.py` | 静态门禁全钩子 Passed + 主机侧纯逻辑单测断言全部通过（当前 278 条），exit 0 | "找不到 MSVC" = VS 未装或装到非标准位置（设 `DTU_MSVC_CL` 可验证覆盖通道） |
| ④ | `& 'tools\refgraph\gen_refgraph.bat'` → `git status` | 重生成后 `docs/images/` **无 diff**（图内容只依赖源码，与本机工具链无关） | 出现 diff = 异常，需查 |
| ⑤ | `& "simulator\build_sim.bat"` | 自动探测 VS → 生成器匹配 → 构建成功（2026-10-02 起模拟器构建可用：配置引擎重构的文件迁移已同步进 `simulator/CMakeLists.txt`） | 报 `Cannot find source file` / `C1083` = CMakeLists 与源码目录再次失步（查文件迁移记录），与 `DTU_*` 变量无关；"未探测到 VS" 见 §2.3 |
| ⑥ | （有 ST-LINK 硬件才执行）`& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py list` | 列出探针 SN | 只跑 `list`，**不烧录不复位**；无硬件跳过不扣分 |
@@ -640,7 +640,7 @@ $env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话，不动用户级
| 远程显示协议 | `docs/UI设计/RemoDispBus协议与接收设计说明.md` |
| LVGL 模拟器部署 | `docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` |
| 串口调试 / 自动化测试 | `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md` |
| **测试分层 / L0.5 主机侧单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩） |
| **测试分层 / 主机侧纯逻辑单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（主机侧纯逻辑单测范式：MSVC 离线编译 + 平台桩） |
| **CI（Gitea Actions）** | `docs/CI/README.md`（**远程 CI 唯一入口**：服务端 / Runner 部署与保活 / workflow / 排障，**仅本机一台 runner，日常开发不必读**）· `docs/测试说明/测试开发标准流程.md` §9（覆盖边界） |
| pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` |
| 引用关系图（文件引用） | `docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8） |
@@ -660,11 +660,11 @@ $env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe' # 仅当前会话，不动用户级
| 2026-10-02 | **模拟器构建修复**（配置引擎重构遗留）：`simulator/CMakeLists.txt` 的配置文件引擎引用同步到迁移后位置——包含目录 `App/`→`App/cfg/`（`cfg_file.h`/`cfg_file_store.h`）、源文件 `App/cfg_file.c`→`App/cfg/cfg_file.c`、包含目录 `test/`→`test/board/`（`test_config.h`/`net_latency_test.h`）；全量 include 离线核查无其他断链，模拟器全量构建恢复（`--cfgtest` 四场景 PASS，rc=0）。§2.12 验证链 ⑤ 行同步更新 |
| 2026-10-02 | 更正 Device Pack 必装范围：`Keil::CMSIS` pack 不再列为必装项——本工程不依赖它（核心头文件由仓库 `Drivers/CMSIS/` 提供，`.uvprojx` 只引用 DFP pack；2026-10-02 本机实测未装 CMSIS pack 构建 0/0 通过），且其 keil.com 直链（5.7.0~6.1.0）均已下架 404；必装的只有 `Keil::STM32F4xx_DFP`（3.1.1，与 `.uvprojx` PackID 一致）。§2.2 / 第 2 步 / 搭建清单 / §2.10 同步更正 |
| 2026-10-02 | 新增 §2.12「跨机验证（第二台机器 / 换机验收清单）」：变量配置 + sanity check → 六步验证链（含期望结果与失败诊断，含模拟器既有 CMake 问题标注）→ 反向 fail-fast 测试 → 通过判定，作为方案跨机验收的标准操作 |
| 2026-10-02 | **本地工具路径环境变量方案落地**（`本地工具路径环境变量方案.md`）：仓库脚本不再含本机绝对工具路径——10 处调用点（`build/download/reset.bat`、`_build.cmd` 退役、`ci_local.py`、`ci.yml`、`gen_refgraph.py`、`unit_test_harness.py`、`build_sim.ps1`、`make_font.py`）统一改为"`DTU_*` 变量优先 + 自动发现回退"（显式设置但无效 = 硬报错，不静默回退）；新增 §2.1.1 变量清单/设置方法/解析语义；Keil 安装路径、Graphviz、cppcheck、VS/SDK 自动探测、Python 重建示例与速查表同步改为变量口径；`requirements.txt` 增 `pre-commit`（重建 `.venv` 即可直接跑 L0 门禁）；本机已按 §2.1.1 配置用户级 `DTU_KEIL_UV4`/`DTU_STLINK_CLI` 并全链路验证（@build 0/0、ci_local L0+L0.5 全绿、refgraph 重生成、reset 探针识别） |
| 2026-10-02 | **本地工具路径环境变量方案落地**（`本地工具路径环境变量方案.md`）：仓库脚本不再含本机绝对工具路径——10 处调用点（`build/download/reset.bat`、`_build.cmd` 退役、`ci_local.py`、`ci.yml`、`gen_refgraph.py`、`unit_test_harness.py`、`build_sim.ps1`、`make_font.py`）统一改为"`DTU_*` 变量优先 + 自动发现回退"（显式设置但无效 = 硬报错，不静默回退）；新增 §2.1.1 变量清单/设置方法/解析语义；Keil 安装路径、Graphviz、cppcheck、VS/SDK 自动探测、Python 重建示例与速查表同步改为变量口径；`requirements.txt` 增 `pre-commit`（重建 `.venv` 即可直接跑静态门禁）；本机已按 §2.1.1 配置用户级 `DTU_KEIL_UV4`/`DTU_STLINK_CLI` 并全链路验证（@build 0/0、ci_local 静态门禁+主机侧纯逻辑单测全绿、refgraph 重生成、reset 探针识别） |
| 2026-10-02 | 新增 **`Gitea_Runner部署指南.md`**：针对**本机 Gitea 原生部署**（`D:\Docker\Gitea\gitea.exe` + Windows 服务 + `127.0.0.1:3001`）定制的 Runner 端全流程——下载 / `register`（**`--instance` 用回环、`--labels "windows:host"` 必须精确匹配 `runs-on`**）/ `config.yaml` / `daemon install` 常驻 / 软件与 PATH 坑 / MSVC 路径约束 / 内网 action 零依赖改法 / 排障表 / `check_env.ps1` 自检脚本；§七相关文档登记 |
| 2026-10-01 | 新增 **`CI配置指南.md`**（Gitea Actions 配置全流程：服务端 `[actions] ENABLED` / Windows runner 注册（`--labels "windows:host"`）/ runner 软件环境与 PATH / workflow 位置与触发 / 内网拉不到 `actions/checkout` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 |
| 2026-10-01 | **新增 §2.11 CI runner 环境（Gitea Actions，T-6）**：Gitea ≥1.21（实测 1.25.4）+ `[actions] ENABLED` + Windows runner（装 Python/cppcheck/pre-commit/MSVC）；**不需要 Keil**（刻意不跑 `@build`，无 `.map` 时 `mem-numbers` 自动跳过）；补"CI 不能替代本地门禁"与 `scripts/ci_local.py` 过渡命令 |
| 2026-10-01 | **补主机侧单元测试（L0.5）环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 |
| 2026-10-01 | **补主机侧单元测试环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 |
| 2026-09-21 | 更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"**随仓库提供**/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正 |
| 2026-09-21 | 模拟器构建改为自适应：新增 `simulator/build_sim.bat/.ps1`（vswhere 自动探测本机 VS 大版本 → 生成器 16=2019 / 17=2022 / 18=2026；`build/` 生成器不符自动删除重建，删除带重试抗文件锁）；VS 版本不再固定，2019/2022/2026 兼容：总览图、§2.3、第 3 步、第 10 步冒烟、搭建清单、速查表同步更新 |
| 2026-09-16 | 补 Graphviz（引用关系图渲染，可选）：新增 §2.8，原 §2.8/§2.9 顺延为 §2.9/§2.10（章节内步骤号不变）；总览图、搭建清单、§2.10 下载表、相关文档各补一项 |