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

docs(测试说明): 按用途分六个子目录并同步全库引用

Browse Source 
分层：流程与规范/ 单元测试/ 板级测试/ 专项验证/ 测试工具/ 测试数据/，
顶层只留新增的目录导航 README.md（归层判据 + 硬约束 + 本次处置记录）。

- 搬迁 28 个路径：测试数据三个目录 58 个文件为纯改名（R100，内容逐字节不变）
- 全库引用同步 124 个文件：AGENTS / docs 索引 / skills / 门禁注释 / scripts
- 门禁面：scripts/check_test_traceability.py 的 glob 改 rglob
  （分层后不递归扫描＝追溯门禁直接瞎掉）
- scripts/rename_ref.py：收尾的 ℹ 提示在 GBK 代码页抛 UnicodeEncodeError，
  让进程以退出码 1 收场而改写其实已落盘（RC 与真实结果相反）；改为把
  stdout/stderr reconfigure 成 UTF-8，与 check_doc_links.py 等同法
- docs/文档规范.md §1.1 补「子目录文件过多时再分一层」；§3.6 补 rename_ref
  搬整目录的两个实测坑：① 会改写目录内部文件的内容 ② 内部文件的 ../ 出链
  不补层级（本次 23 个被误改的证据文件已按 HEAD 原始字节逐字节还原）
- docs/README.md §6 改为与六个子目录一一对应，并补登原先漏登记的
  「启动日志原子性复验流程」一行
- .cubemx_survival_baseline.json：App/util/task_watchdog.c 的注释路径也随分层更新，
  该文件是存活审计的 watchdog-module 漂移锚点，按脚本自己的提示跑 --write 重建基线
  （实测重建后仅 watchdog-module 一条哈希变化）
- 铁律 4 例外（本次在任务树里改了单写者文件）：AGENTS.md 与
  .pre-commit-config.yaml 只被 rename_ref 改写路径字面量（后者全在注释行），
  任务表块与钩子声明一字未动

验证：check_doc_links.py --sections-strict 覆盖全部 88 个改动 .md 全绿；
check_test_traceability.py 输出与主树逐行一致；196 个文本文件无 BOM、无新增
CR、无 U+FFFD、无行尾空白；陈旧引用面由主树 25 处降到 6 处（无新增断链）。
This commit is contained in:
Wanderingss
2026-10-30 07:06:38 +08:00
parent fea4cc7502
commit f754d59218
209 changed files with 644 additions and 528 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+47 -31
View File
@@ -17,7 +17,7 @@ docs/
├── 子系统设计/ 各功能子系统的设计说明
├── 算法/ 傅氏算法与继电保护算法专题
├── 网络/ BSD Socket API 使用与内部实现
├── 测试说明/ 测试流程、模块测试指南、工具说明
├── 测试说明/ 测试流程与规范 · 单元测试 · 板级测试 · 专项验证 · 测试工具 · 测试数据（六个子目录，导航 `测试说明/README.md`）
├── 代码规范/ 编码规范与静态检查门禁
├── 文档规范.md 本文档体系的规范（命名/链接/门禁/结构）
├── 内存管理/ RAM 预算、分配策略与优化调研
@@ -46,7 +46,7 @@ docs/
| 3 | [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | Event Flags 就绪屏障（取代魔法延时）的任务启动模型 |
| 4 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机/目标板/现场部署的完整环境核对清单 |
| 5 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) → 构建 | 跑通 `@build` / `@test`（见根 `AGENTS.md`） |
| 6 | [`测试开发标准流程.md`](测试说明/测试开发标准流程.md) | 测试分层 静态门禁~保护判据与门禁决策表 |
| 6 | [`测试开发标准流程.md`](测试说明/流程与规范/测试开发标准流程.md) | 测试分层 静态门禁~保护判据与门禁决策表 |
| 7 | [`嵌入式C语言代码规范_V1.0.md`](代码规范/嵌入式C语言代码规范_V1.0.md) | 命名/格式/注释规范（提交门禁强制） |
| 8 | [`项目架构总览.md`](架构设计/项目架构总览.md) → 按需 | 进入具体子系统设计文档 |
@@ -114,50 +114,66 @@ docs/
## 6. 测试说明
**总流程与规范**
> 本目录分六个子目录（**归层判据与本目录文件清单 → [`测试说明/README.md`](测试说明/README.md)**）；
> 下面每个分组与一个子目录一一对应。
**流程与规范/**（测试开发总流程、门禁决策表、测试文档模板）
| 文档 | 内容 |
|---|---|
| [`测试开发标准流程.md`](测试说明/测试开发标准流程.md) | 测试开发总流程：规划→板端套件→主机工具→门禁→沉淀；门禁决策表 |
| [`自动化测试流程.md`](测试说明/自动化测试流程.md) | `@test` 闭环细节：命令 / 串口标记 / 失败模式 |
| [`测试文档模板规范.md`](测试说明/测试文档模板规范.md) | 测试文档模板与命名规则（TM / TC / DP） |
| [`链路延迟测试说明.md`](测试说明/链路延迟测试说明.md) | 网络链路时延分段定义、判定基线、执行流程 |
| [`模拟器差距清单.md`](测试说明/模拟器差距清单.md) | **PC 模拟器 vs 真机差距登记册**（保护判据门禁可信度依据；改动涉及网络/日志/硬件层前必查 §3 决策规则） |
| [`实机测试实施指南.md`](测试说明/实机测试实施指南.md) | **上板（真机）测试执行流程**（按顺序：环境预检 → `@test`+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生；每步含判据/命令/状态）；已完成事项证据去向见 §10 |
| [`ADC前端注入验证流程.md`](测试说明/ADC前端注入验证流程.md) | **ADC 前端与两片转换器的台架注入验证**（已知电压注入验证的执行侧，实测证据 → `docs/硬件平台/ADC通道映射说明.md` §8.1）：注入点清单 / 期望码值表 / 零点·线性·映射·极性·节奏五步（每步自带现场记录表，边做边填）；**不需示波器与信号源**，一块万用表即可 |
| [`测试开发标准流程.md`](测试说明/流程与规范/测试开发标准流程.md) | 测试开发总流程：规划→板端套件→主机工具→门禁→沉淀；门禁决策表 |
| [`自动化测试流程.md`](测试说明/流程与规范/自动化测试流程.md) | `@test` 闭环细节：命令 / 串口标记 / 失败模式 |
| [`测试文档模板规范.md`](测试说明/流程与规范/测试文档模板规范.md) | 测试文档模板与命名规则（TM / TC / DP） |
**主机侧单元测试（主机侧纯逻辑单测）**
**单元测试/**（主机侧纯逻辑单测说明与覆盖率口径）
| 文档 | 内容 |
|---|---|
| [`看门狗单元测试说明.md`](测试说明/看门狗单元测试说明.md) | Task Watchdog 判定状态机（位图 / 掩码 / 节流 / tick 回绕），39 用例 |
| [`系统时钟单元测试说明.md`](测试说明/系统时钟单元测试说明.md) | sys_clock 时间换算 / 星期 Zeller / 30 天惰性再基准化 / RTC 故障降级，100 断言点 |
| [`开机账本单元测试说明.md`](测试说明/开机账本单元测试说明.md) | boot_stats 上电次数四态（不可信 / 首次启用 / 延续 / 电池域掉过电）/ SRAM 记录校验与格式版本 / I2C 失败分支 / 复位原因优先级链，21 断言点 |
| [`配置文件单元测试说明.md`](测试说明/配置文件单元测试说明.md) | cfg_file INI 解析 / 值编解码 / load-save-poll 契约 / 超长守卫，149 断言点（含抓出的外科手术保存死码 P0） |
| [`ADC输入层单元测试说明.md`](测试说明/ADC输入层单元测试说明.md) | adc_input 语义通道映射 / ADC1 顺序扫描（**Rank↔通道判据**）/ poll 契约 / HAL 故障路径，70 用例 |
| [`相量层单元测试说明.md`](测试说明/相量层单元测试说明.md) | phasor 全周傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换，57 用例 |
| [`卷锁单元测试说明.md`](测试说明/卷锁单元测试说明.md) | vol_lock 创建 / 获取 / 释放契约（**fail-open 不变量**：创建失败仍返回 1 且零阻塞）/ 幂等 / 超时透传，33 断言点 |
| [`时间同步单元测试说明.md`](测试说明/时间同步单元测试说明.md) | time_sync 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（探针窗口心跳缺口的全部逻辑贡献者），80 断言点 |
| [`主机单测覆盖率口径.md`](测试说明/主机单测覆盖率口径.md) | **跨全部 16 套 主机侧纯逻辑单测的覆盖率**：`scripts/check_test_coverage.py` 用法 / 统计面与生成物例外 / 基线增量门禁（只拦回退）/ **为什么本机拿不到分支覆盖** / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML |
| [`看门狗单元测试说明.md`](测试说明/单元测试/看门狗单元测试说明.md) | Task Watchdog 判定状态机（位图 / 掩码 / 节流 / tick 回绕），39 用例 |
| [`系统时钟单元测试说明.md`](测试说明/单元测试/系统时钟单元测试说明.md) | sys_clock 时间换算 / 星期 Zeller / 30 天惰性再基准化 / RTC 故障降级，100 断言点 |
| [`开机账本单元测试说明.md`](测试说明/单元测试/开机账本单元测试说明.md) | boot_stats 上电次数四态（不可信 / 首次启用 / 延续 / 电池域掉过电）/ SRAM 记录校验与格式版本 / I2C 失败分支 / 复位原因优先级链，21 断言点 |
| [`配置文件单元测试说明.md`](测试说明/单元测试/配置文件单元测试说明.md) | cfg_file INI 解析 / 值编解码 / load-save-poll 契约 / 超长守卫，149 断言点（含抓出的外科手术保存死码 P0） |
| [`ADC输入层单元测试说明.md`](测试说明/单元测试/ADC输入层单元测试说明.md) | adc_input 语义通道映射 / ADC1 顺序扫描（**Rank↔通道判据**）/ poll 契约 / HAL 故障路径，70 用例 |
| [`相量层单元测试说明.md`](测试说明/单元测试/相量层单元测试说明.md) | phasor 全周傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换，57 用例 |
| [`卷锁单元测试说明.md`](测试说明/单元测试/卷锁单元测试说明.md) | vol_lock 创建 / 获取 / 释放契约（**fail-open 不变量**：创建失败仍返回 1 且零阻塞）/ 幂等 / 超时透传，33 断言点 |
| [`时间同步单元测试说明.md`](测试说明/单元测试/时间同步单元测试说明.md) | time_sync 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（探针窗口心跳缺口的全部逻辑贡献者），80 断言点 |
| [`主机单测覆盖率口径.md`](测试说明/单元测试/主机单测覆盖率口径.md) | **跨全部 16 套 主机侧纯逻辑单测的覆盖率**：`scripts/check_test_coverage.py` 用法 / 统计面与生成物例外 / 基线增量门禁（只拦回退）/ **为什么本机拿不到分支覆盖** / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML |
**模块测试指南**（动手写测试前先读）
**板级测试/**（上板测试：模块测试指南 + 实机实施流程；动手写测试前先读）
| 文档 | 内容 |
|---|---|
| [`CH395F_Test_Guide.md`](测试说明/CH395F_Test_Guide.md) | CH395F 以太网控制器（硬件层 Phase 1~5 / NET 层 Phase 6~11） |
| [`GD5F2GQ5UE_Test_Guide.md`](测试说明/GD5F2GQ5UE_Test_Guide.md) | GD5F2GQ5UE SPI NAND 存储测试 |
| [`SD2506_Test_Guide.md`](测试说明/SD2506_Test_Guide.md) | SD2506 RTC 测试 |
| [`FTP_Test_Guide.md`](测试说明/FTP_Test_Guide.md) | FTP 服务测试 |
| [`CH395F_Test_Guide.md`](测试说明/板级测试/CH395F_Test_Guide.md) | CH395F 以太网控制器（硬件层 Phase 1~5 / NET 层 Phase 6~11） |
| [`GD5F2GQ5UE_Test_Guide.md`](测试说明/板级测试/GD5F2GQ5UE_Test_Guide.md) | GD5F2GQ5UE SPI NAND 存储测试 |
| [`SD2506_Test_Guide.md`](测试说明/板级测试/SD2506_Test_Guide.md) | SD2506 RTC 测试 |
| [`FTP_Test_Guide.md`](测试说明/板级测试/FTP_Test_Guide.md) | FTP 服务测试 |
| [`实机测试实施指南.md`](测试说明/板级测试/实机测试实施指南.md) | **上板（真机）测试执行流程**（按顺序：环境预检 → `@test`+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生；每步含判据/命令/状态）；已完成事项证据去向见 §10 |
**工具与运维**
**专项验证/**（针对一个缺陷或一次复验的台架专项流程；做完即定稿）
| 文档 | 内容 |
|---|---|
| [`串口助手使用指南.md`](测试说明/串口助手使用指南.md) | 串口助手命令用法 / 工作流 / 排障 |
| [`串口助手设计说明.md`](测试说明/串口助手设计说明.md) | 串口助手契约 / daemon 行为 / 陷阱 |
| [`ST-LINK_CLI_复位使用说明.md`](测试说明/ST-LINK_CLI_复位使用说明.md) | 烧录 / 复位 / 回读校验（`ST-LINK_CLI` 完整用法） |
| [`存储维护与容量恢复.md`](测试说明/存储维护与容量恢复.md) | 全片擦除恢复 dhara 坏块记账 / 容量恢复 |
| [`m2_data/README.md`](测试说明/m2_data/README.md) · `m3_data/` | 链路时延测试采集数据（JSON 原始记录） |
| [`ADC前端注入验证流程.md`](测试说明/专项验证/ADC前端注入验证流程.md) | **ADC 前端与两片转换器的台架注入验证**（已知电压注入验证的执行侧，实测证据 → `docs/硬件平台/ADC通道映射说明.md` §8.1）：注入点清单 / 期望码值表 / 零点·线性·映射·极性·节奏五步（每步自带现场记录表，边做边填）；**不需示波器与信号源**，一块万用表即可 |
| [`启动日志原子性复验流程.md`](测试说明/专项验证/启动日志原子性复验流程.md) | **控制台整行独占 / 崩溃遗言原子性**这类**行级完整性**判据的固定动作与口径（`docs/子系统设计/控制台单写者日志设计说明.md` 的验收侧：那边讲怎么修，这边讲怎么证明修好了、以及为什么"标记全中"不等于"日志没坏"） |
| [`链路延迟测试说明.md`](测试说明/专项验证/链路延迟测试说明.md) | 网络链路时延分段定义、判定基线、执行流程 |
| [`模拟器差距清单.md`](测试说明/专项验证/模拟器差距清单.md) | **PC 模拟器 vs 真机差距登记册**（保护判据门禁可信度依据；改动涉及网络/日志/硬件层前必查 §3 决策规则） |
| [`存储维护与容量恢复.md`](测试说明/专项验证/存储维护与容量恢复.md) | 全片擦除恢复 dhara 坏块记账 / 容量恢复 |
**测试工具/**（PC 侧工具用法）
| 文档 | 内容 |
|---|---|
| [`串口助手使用指南.md`](测试说明/测试工具/串口助手使用指南.md) | 串口助手命令用法 / 工作流 / 排障 |
| [`串口助手设计说明.md`](测试说明/测试工具/串口助手设计说明.md) | 串口助手契约 / daemon 行为 / 陷阱 |
| [`ST-LINK_CLI_复位使用说明.md`](测试说明/测试工具/ST-LINK_CLI_复位使用说明.md) | 烧录 / 复位 / 回读校验（`ST-LINK_CLI` 完整用法） |
**测试数据/**（一手证据，**只增不改** → `docs/测试说明/README.md` §4）
| 目录 | 内容 |
|---|---|
| [`boot_log_data/README.md`](测试说明/测试数据/boot_log_data/README.md) | `@test` 产出的**开机串口日志快照**存档（跨构建 `[STACK]` 栈 / 堆水位对照，39 个文件） |
| [`m2_data/README.md`](测试说明/测试数据/m2_data/README.md) | 链路时延 M2 安静档采集数据（JSON + 串口 `[LAT]` 片段，含逐帧尾批明细与方法学约束） |
| `m3_data/` | 链路时延 M3 各档原始 JSON（quiet / stress / pending / 尾批实验；无独立 README，口径见 [`链路延迟测试说明.md`](测试说明/专项验证/链路延迟测试说明.md) 附表） |
> UI 相关测试见 [`UI设计/UI_自动化测试流程.md`](UI设计/UI_自动化测试流程.md)。