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

分层：流程与规范/ 单元测试/ 板级测试/ 专项验证/ 测试工具/ 测试数据/，顶层只留新增的目录导航 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 处（无新增断链）。
2026-10-30 07:06:38 +08:00
parent fea4cc7502
commit f754d59218
209 changed files with 644 additions and 528 deletions
@@ -70,10 +70,10 @@
 | `nand_port/nand_port_test.c` | 测试单元本体（`#include` 生产源码 + RAM 假芯片；内联一份"只看页首 64 B"的**旧算法对照**，证明断言能咬人） |
 | `nand_port/stub/` | 桩头文件（`gd5f2gq5ue.h` 芯片几何与 SPI 原语声明 / `dbg_log.h` 日志宏计数） |

-> 详见 `docs/测试说明/看门狗单元测试说明.md`、`docs/测试说明/系统时钟单元测试说明.md`、
-> `docs/测试说明/配置文件单元测试说明.md`、`docs/测试说明/ADC输入层单元测试说明.md`、
-> `docs/测试说明/相量层单元测试说明.md`、`docs/测试说明/卷锁单元测试说明.md`、
-> `docs/测试说明/时间同步单元测试说明.md`；
+> 详见 `docs/测试说明/单元测试/看门狗单元测试说明.md`、`docs/测试说明/单元测试/系统时钟单元测试说明.md`、
+> `docs/测试说明/单元测试/配置文件单元测试说明.md`、`docs/测试说明/单元测试/ADC输入层单元测试说明.md`、
+> `docs/测试说明/单元测试/相量层单元测试说明.md`、`docs/测试说明/单元测试/卷锁单元测试说明.md`、
+> `docs/测试说明/单元测试/时间同步单元测试说明.md`；
 > harness 用法见 [`common/README.md`](common/README.md)。
 > 已挂 pre-commit 钩子（各模块同名 `*-unit-test`，共 **22** 个；逐个说明见
 > `docs/代码规范/pre-commit使用说明.md` §2 与 AGENTS.md 门禁条）。
@@ -149,13 +149,13 @@

 ## 相关文档

- `docs/测试说明/自动化测试流程.md` — `@test` 细节与失败模式
- `docs/测试说明/测试开发标准流程.md` — 测试分层与门禁
- `docs/测试说明/看门狗单元测试说明.md` — 主机侧单测（用例 / 平台层 / 扩展方法）
- `docs/测试说明/系统时钟单元测试说明.md` — 系统时钟换算单测（用例 / 桩 / Zeller 缺陷记录）
- `docs/测试说明/配置文件单元测试说明.md` — 配置引擎单测（内存 FS 桩 / 抓出的 P0）
- `docs/测试说明/ADC输入层单元测试说明.md` — ADC 输入层单测（逐 Rank 钉死映射）
- `docs/测试说明/相量层单元测试说明.md` — 相量层单测（傅氏系数 / 双区交换）
- `docs/测试说明/卷锁单元测试说明.md` — 卷锁单测（fail-open 不变量）
- `docs/测试说明/时间同步单元测试说明.md` — 时间同步单测（探针窗口心跳缺口逻辑贡献者）
- `docs/测试说明/CH395F_Test_Guide.md`、`FTP_Test_Guide.md`
+- `docs/测试说明/流程与规范/自动化测试流程.md` — `@test` 细节与失败模式
+- `docs/测试说明/流程与规范/测试开发标准流程.md` — 测试分层与门禁
+- `docs/测试说明/单元测试/看门狗单元测试说明.md` — 主机侧单测（用例 / 平台层 / 扩展方法）
+- `docs/测试说明/单元测试/系统时钟单元测试说明.md` — 系统时钟换算单测（用例 / 桩 / Zeller 缺陷记录）
+- `docs/测试说明/单元测试/配置文件单元测试说明.md` — 配置引擎单测（内存 FS 桩 / 抓出的 P0）
+- `docs/测试说明/单元测试/ADC输入层单元测试说明.md` — ADC 输入层单测（逐 Rank 钉死映射）
+- `docs/测试说明/单元测试/相量层单元测试说明.md` — 相量层单测（傅氏系数 / 双区交换）
+- `docs/测试说明/单元测试/卷锁单元测试说明.md` — 卷锁单测（fail-open 不变量）
+- `docs/测试说明/单元测试/时间同步单元测试说明.md` — 时间同步单测（探针窗口心跳缺口逻辑贡献者）
+- `docs/测试说明/板级测试/CH395F_Test_Guide.md`、`FTP_Test_Guide.md`
@@ -26,7 +26,7 @@
 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

 设计依据：docs/算法/继电保护功能复现规划.md §3.1（采样有效性校验）；
-         docs/测试说明/测试开发标准流程.md §4.2（主机侧纯逻辑单测）。
+         docs/测试说明/流程与规范/测试开发标准流程.md §4.2（主机侧纯逻辑单测）。
 创建日期：2026-10-11
 """
 import os
@@ -14,7 +14,7 @@
 *      这些在真机上极难复现（需掉电/坏块）。
 *   3. 不占 MCU 的 RAM。
 *
- * 覆盖点（对应 docs/测试说明/配置文件单元测试说明.md 的 TC-CFG-xxx）：
+ * 覆盖点（对应 docs/测试说明/单元测试/配置文件单元测试说明.md 的 TC-CFG-xxx）：
 *   —— 值类型编解码（s_encode / s_decode 经公开 load/save 间接验证 + 直接白盒）——
 *   TC-CONFIG-001 UINT 1/2/4 字节小端往返（含 0 / 最大值）
 *   TC-CONFIG-002 UINT 非法：空 / 非数字 / 带后缀 / 超范围
@@ -22,7 +22,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

-设计依据：docs/测试说明/配置文件单元测试说明.md（S1-b，原复审项已闭环）；
+设计依据：docs/测试说明/单元测试/配置文件单元测试说明.md（S1-b，原复审项已闭环）；
 创建日期：2026-10-02
 """
 import os
@@ -36,7 +36,7 @@ r"""配置存储后端（cfg_file_store_mcu）的主机侧纯逻辑单元测试

 设计依据：docs/子系统设计/配置文件设计说明.md §6.2（mtime 令牌）、
 docs/架构设计/STM32F4-Base存储架构说明.md §10.1 第 10/11 条、
-docs/测试说明/主机单测覆盖率口径.md §9 P2 第 2 项
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P2 第 2 项
 创建日期：2026-10-24
 """
 import os
@@ -72,7 +72,7 @@ raise SystemExit(run_host_unit_test(TestBuild(name="...", src="...", ...)))

 ## 环境要求

-同主机侧纯逻辑单测通用要求（见 [`../../../docs/测试说明/测试开发标准流程.md`](../../../docs/测试说明/测试开发标准流程.md) §4.2）：
+同主机侧纯逻辑单测通用要求（见 [`../../../docs/测试说明/流程与规范/测试开发标准流程.md`](../../../docs/测试说明/流程与规范/测试开发标准流程.md) §4.2）：
 MSVC `cl.exe`（装了 VS 即有）+ Windows SDK + 纯标准库 Python；**不调 `vcvars64.bat`**
 （内部 `reg.exe` 受限），直接拼环境变量调 `cl.exe`。

@@ -104,7 +104,7 @@ MSVC `cl.exe`（装了 VS 即有）+ Windows SDK + 纯标准库 Python；**不

 - `DTU_HOST_BUILD=<目录>`：改产物根（CI/容器要固定路径时用）。覆盖率侧同源——
  `scripts/check_test_coverage.py` 复用同一个函数，不再用自己那套固定名
-  （旧 `%TEMP%\dtu_test_cov` 的共享名，正是 docs/测试说明/主机单测覆盖率口径.md 里
+  （旧 `%TEMP%\dtu_test_cov` 的共享名，正是 docs/测试说明/单元测试/主机单测覆盖率口径.md 里
  "并行期每人只跑 `--module` 自己模块"那条规避的由来；分家之后该规避不再必要）。
 - `DTU_HOST_BUILD_KEEP=1`：保留本次独占目录不删（要单步调试那个 exe 时用，会打印路径）。

@@ -36,7 +36,7 @@
            summary_marker="=== Task Watchdog Tests:",
        )))

-设计依据：docs/测试说明/测试开发标准流程.md §4.2
+设计依据：docs/测试说明/流程与规范/测试开发标准流程.md §4.2
 创建日期：2026-10-01
 """

@@ -141,9 +141,9 @@ class TestBuild:
 # 套件**就会互相覆盖，而最坏的不是编不过：A 树编译完，B 树把同名 exe 又盖一遍，
 # A 树随后执行的是 **B 树编出来的二进制**——两棵树的 summary_marker 一模一样，
 # harness 分辨不出来，于是拿着别人的运行结果给自己下结论（比红更难查）。
-# 覆盖率侧同源：%TEMP%\dtu_test_cov 也是固定共享名（docs/测试说明/主机单测覆盖率
-# 口径.md 里"并行期每人只跑 --module 自己模块"就是为绕开它写的规避；本处修好后
-# 那条规避不再必要）。
+# 覆盖率侧同源：%TEMP%\dtu_test_cov 也是固定共享名（口径文档
+# docs/测试说明/单元测试/主机单测覆盖率口径.md：其中"并行期每人只跑 --module 自己模块"
+# 就是为绕开它写的规避；本处修好后那条规避不再必要）。
 #
 # 口径：**按工作树分家**。产物根 = %TEMP%\dtu_host\<仓库根路径哈希>\，跨树天然不撞，
 # 同一棵树内仍复用同一份目录（33 套的编译缓存没必要白白重编）。**不用锁**——锁会把
@@ -1282,9 +1282,10 @@ static void tc_check_then_act(void)
 * 这是本套唯一能把"两个生产者并发时，写进 DR 的字节流里不得出现另一条行的字节"
 * 做成必然失败断言的把手：修复后是**非阻塞**设计，永远不会调 vTaskDelay，所以既有的
 * con_delay_hook 在这条路径上根本不会被触发（拿它当注入点会静默地什么都测不到）。
- * 台架一手证据：docs/测试说明/boot_log_data/20261026_prod_console_interleave_evidence.txt
+ * 台架一手证据：docs/测试说明/测试数据/boot_log_data/20261026_prod_console_interleave_evidence.txt
 * —— PROT 行内多出 [ 2 0 三字节，紧接其后的 NAND_FTL 行恰好缺这三个字节的行首。 */
-/* 台架 16:37 那次被插字的原文行（boot_log_data/20261026_prod_console_interleave_evidence.txt
+/* 台架 16:37 那次被插字的原文行（证据文件同上：
+ * docs/测试说明/测试数据/boot_log_data/ 那份 interleave 证据的
 * OCCURRENCE 1 去掉三个外来字节之后的样子）。M 族拿它当"真实行长与真实前缀"的样本，
 * 免得用例自己造一个不像现场的理想行。 */
 static const char s_prot_line[] =
@@ -38,7 +38,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/子系统设计/控制台单写者日志设计说明.md、docs/测试说明/主机单测覆盖率口径.md §9「P2 落地」清单第 3 条
+设计依据：docs/子系统设计/控制台单写者日志设计说明.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9「P2 落地」清单第 3 条
 创建日期：2026-10-24
 """
 import os
@@ -22,7 +22,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

-设计依据：docs/子系统设计/网络配置说明.md §3.4、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：docs/子系统设计/网络配置说明.md §3.4、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -28,7 +28,7 @@
 退出码：0=PASS / 1=测试失败 / 2=环境错误。

 设计依据：docs/子系统设计/*104* 设计文档、AGENTS.md 模块约定（单连接 socket 断开语义、
-错误码经任务通知值回传）、docs/测试说明/主机单测覆盖率口径.md §9
+错误码经任务通知值回传）、docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-23
 """
 import os
@@ -3,7 +3,7 @@

 Server-driven protocol: the MCU (testTask, port 8080) sends one operation
 byte; the peer executes the corresponding traffic pattern. See
-docs/测试说明/链路延迟测试说明.md §4.5 for the full protocol spec.
+docs/测试说明/专项验证/链路延迟测试说明.md §4.5 for the full protocol spec.

 Ops (MCU -> peer):
  0x01  QUEUE_RT recv flood   : peer sends 50 x 100B (5ms apart)
@@ -29,8 +29,8 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/测试说明/FTP_Test_Guide.md、docs/子系统设计/网络配置说明.md §3.4、
-docs/测试说明/主机单测覆盖率口径.md §9
+设计依据：docs/测试说明/板级测试/FTP_Test_Guide.md、docs/子系统设计/网络配置说明.md §3.4、
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-23
 """
 import os
@@ -25,8 +25,8 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/子系统设计/网络配置说明.md §3.4、docs/测试说明/FTP_Test_Guide.md、
-docs/测试说明/主机单测覆盖率口径.md §9
+设计依据：docs/子系统设计/网络配置说明.md §3.4、docs/测试说明/板级测试/FTP_Test_Guide.md、
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-23
 """
 import os
@@ -26,7 +26,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/内存管理/RAM使用分析与优化方案.md §4.2.1、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：docs/内存管理/RAM使用分析与优化方案.md §4.2.1、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -28,7 +28,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

-设计依据：docs/子系统设计/网络配置说明.md、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：docs/子系统设计/网络配置说明.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -31,7 +31,7 @@
 退出码：0=PASS / 1=测试失败 / 2=环境错误。

 设计依据：docs/网络/网络自愈架构设计.md §4.10、docs/网络/Net层阻塞模型架构设计.md、
-docs/测试说明/主机单测覆盖率口径.md §9
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-23
 """
 import os
@@ -31,7 +31,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/网络/网络自愈架构设计.md §4.10、docs/测试说明/主机单测覆盖率口径.md §9（假 CH395F 实施规格）
+设计依据：docs/网络/网络自愈架构设计.md §4.10、docs/测试说明/单元测试/主机单测覆盖率口径.md §9（假 CH395F 实施规格）
 创建日期：2026-10-23
 """
 import os
@@ -30,7 +30,7 @@
 退出码：0=PASS / 1=测试失败 / 2=环境错误。

 设计依据：AGENTS.md 模块约定（错误码经任务通知值回传）、
-docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/主机单测覆盖率口径.md §9
+docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-23
 """
 import os
@@ -25,7 +25,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -49,7 +49,7 @@

 退出码：0=PASS / 1=测试失败（含常量闸不过）/ 2=环境错误。

-设计依据：docs/网络/网络自愈架构设计.md §4.10、docs/测试说明/主机单测覆盖率口径.md §9
+设计依据：docs/网络/网络自愈架构设计.md §4.10、docs/测试说明/单元测试/主机单测覆盖率口径.md §9
 创建日期：2026-10-24
 """
 import os
@@ -28,7 +28,7 @@

 设计依据：docs/算法/继电保护功能复现规划.md §3.2（全周傅氏系数表 等）；
         docs/算法/傅氏算法详解.md §2.3（系数口径）；
-         docs/测试说明/测试开发标准流程.md §4.2（主机侧纯逻辑单测）。
+         docs/测试说明/流程与规范/测试开发标准流程.md §4.2（主机侧纯逻辑单测）。
 创建日期：2026-10-10
 """
 import os
@@ -21,7 +21,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：App/cfg/prot_set_store.h 的返回码表、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：App/cfg/prot_set_store.h 的返回码表、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -39,7 +39,7 @@ r"""SOE 落盘胶水层（soe_store）的主机侧纯逻辑单元测试运行器

 设计依据：docs/架构设计/STM32F4-Base存储架构说明.md §10.1 第 10/11 条、
 docs/算法/继电保护功能复现规划.md §3.4（SOE 记录 / 动作记录，B9）、
-docs/测试说明/主机单测覆盖率口径.md §9 P2 第 2 项
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P2 第 2 项
 创建日期：2026-10-24
 """
 import os
@@ -24,7 +24,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

-设计依据：docs/测试说明/系统时钟单元测试说明.md（S1-a，原复审项已闭环）；
+设计依据：docs/测试说明/单元测试/系统时钟单元测试说明.md（S1-a，原复审项已闭环）；
 创建日期：2026-10-02
 """
 import os
@@ -13,7 +13,7 @@
 *           断言，见 tc_000；
 *         - 其余用例用 sys_clock_set(unix, NULL) 建立确定基准（无 RTC 副作用）。
 *
- * 覆盖点（对应 docs/测试说明/系统时钟单元测试说明.md 的 TC-CLK-xxx）：
+ * 覆盖点（对应 docs/测试说明/单元测试/系统时钟单元测试说明.md 的 TC-CLK-xxx）：
 *   TC-SYSCLK-000 未初始化：sys_clock_get / get_time / get_str 的无效语义
 *   TC-SYSCLK-001 init 正常：RTC 合法 → 返回 0，基准 = 换算 Unix 秒
 *   TC-SYSCLK-002 init 闰年换算：2024-02-29 / 2000-02-29（世纪闰）/ 2/29→3/1 间隔
@@ -46,7 +46,7 @@ r"""运行/自检记录落盘后端（sys_log_mcu）的主机侧纯逻辑单元

 设计依据：docs/子系统设计/运行与自检记录设计说明.md §4.4/§4.5/§5.3、
 docs/架构设计/STM32F4-Base存储架构说明.md §10.1 第 10/11 条、
-docs/测试说明/主机单测覆盖率口径.md §9 P2 第 2 项
+docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P2 第 2 项
 创建日期：2026-10-24
 """
 import os
@@ -23,7 +23,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误。

-设计依据：App/util/task_prof.h、docs/测试说明/主机单测覆盖率口径.md §9 P1
+设计依据：App/util/task_prof.h、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 P1
 创建日期：2026-10-23
 """
 import os
@@ -22,7 +22,7 @@

 退出码：0=PASS / 1=测试失败 / 2=环境错误（找不到编译器 / 编译失败 / 无汇总行）。

-设计依据：docs/测试说明/看门狗单元测试说明.md
+设计依据：docs/测试说明/单元测试/看门狗单元测试说明.md
 创建日期：2026-10-01
 """
 import os
@@ -10,7 +10,7 @@
 *       TASK_WATCHDOG_UNIT_TEST 守卫的测试专用复位，MCU 构建零开销）
 *       把模块静态态恢复到"刚上电"。
 *
- * 覆盖点（对应 docs/测试说明/看门狗单元测试说明.md 的 TC-WD-xxx）：
+ * 覆盖点（对应 docs/测试说明/单元测试/看门狗单元测试说明.md 的 TC-WD-xxx）：
 *   TC-WATCHDOG-001 未启动时 poll 不做任何判定（也不喂狗）
 *   TC-WATCHDOG-002 节流：< 100ms 的 poll 直接返回
 *   TC-WATCHDOG-003 全员到位置位 → 喂狗一次，且位图取走清零