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
@@ -40,6 +40,6 @@

 ## 相关文档

- 测试指南：`docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md`
+- 测试指南：`docs/测试说明/板级测试/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md`
 - 套件配置：`AGENTS.md`「测试与验证」章
- 容量恢复：`docs/测试说明/存储维护与容量恢复.md`
+- 容量恢复：`docs/测试说明/专项验证/存储维护与容量恢复.md`
@@ -26,7 +26,7 @@
 * Phase 12 | 硬件层   | 独立运行：SPI 字节命令 / DMA 时延基线（SPI_CMD/SPI_DMA，无需 PC）
 * Phase 13 | NET 层   | testTask：芯片 + 队列时延（CHUNK_WAIT~FRAME_RT/LOGTAX，需 PC peer，独立运行）
 * Phase 14 | NET 层   | testTask：生产路径时延（PROD_CYCLE~UI_LOOP + 模拟器 A/B，需 PC peer）〔M3 规划〕
- * 时延分段定义/判定基线/执行流程：docs/测试说明/链路延迟测试说明.md
+ * 时延分段定义/判定基线/执行流程：docs/测试说明/专项验证/链路延迟测试说明.md
 */

 #ifndef CH395F_TEST_H
@@ -42,7 +42,7 @@ extern "C" {
 /*
 * 阶段使能开关（取消注释即启用对应阶段）
 *
- * 构建模式互斥（详见 docs/测试说明/CH395F_Test_Guide.md「构建模式与执行顺序」）：
+ * 构建模式互斥（详见 docs/测试说明/板级测试/CH395F_Test_Guide.md「构建模式与执行顺序」）：
 *   硬件层模式（阶段 1~5）：netTask 入口自挂起（创建但不运行），testTask 独占 CH395F
 *   NET 层模式 （阶段 6~11）：完整网络栈，netTask 轮询 + testTask 监听循环
 *
@@ -66,10 +66,10 @@ extern "C" {
 * 连接无效，E11 实证）；勿与 Phase 6/9/10/13 混选（recv 互抢数据）。
 * ⚠ 说明写在**上一行**而不是挂在 #define 行尾：见本节末尾的"开关行注释规范" */
 #define ENABLE_PHASE11_TESTS    /* [网] KeepAlive 超时断开（判据见 CH395F_Test_Guide） */
-/* ---- 链路时延基线（M1；分段/阈值见 docs/测试说明/链路延迟测试说明.md）---- */
+/* ---- 链路时延基线（M1；分段/阈值见 docs/测试说明/专项验证/链路延迟测试说明.md）---- */
 //#define ENABLE_PHASE12_TESTS     /* [硬] SPI 字节命令 / DMA 时延基线（SPI_CMD/SPI_DMA，无需 PC）—— M1 已完成，基线见说明文档 §6.1 */
-//#define ENABLE_PHASE15_TESTS     /* [硬] 自愈驱动原语：状态回读一致性/cmd_done/sock_reset 状态机跑通/链路缓存（无需 PC）——TC 详见 docs/测试说明/CH395F_Test_Guide.md 阶段 15；台架 21/21 PASS */
-/* ---- 链路时延（M2/M3；分段/阈值见 docs/测试说明/链路延迟测试说明.md）---- */
+//#define ENABLE_PHASE15_TESTS     /* [硬] 自愈驱动原语：状态回读一致性/cmd_done/sock_reset 状态机跑通/链路缓存（无需 PC）——TC 详见 docs/测试说明/板级测试/CH395F_Test_Guide.md 阶段 15；台架 21/21 PASS */
+/* ---- 链路时延（M2/M3；分段/阈值见 docs/测试说明/专项验证/链路延迟测试说明.md）---- */
 //#define ENABLE_PHASE13_TESTS     /* [网] 芯片 + 队列时延（CHUNK_WAIT~FRAME_RT/LOGTAX，需 PC peer）—— M2 已完成，基线见说明文档 §6.2 */
 /* [网] 生产路径时延（PROD_CYCLE~UI_LOOP + 模拟器 Δ）—— M3，需 peer --mode remo（:7003）；
 * 与 Phase 11 共存安全：peer 缺席时有 LAT_P14_TIMEOUT_MS 整体超时，自动 done，
@@ -90,7 +90,7 @@ static void phase1_run(void) {
     * 通过：函数返回 CH395F_ERR_SUCCESS（0x00）= SPI 回显取反匹配。
     * 失败：返回 CH395F_STATUS_NOT_DETECTED（0xFF）= SPI 通信异常或芯片未响应。
     *
-     * 用例号：TC-NET-101（docs/测试说明/CH395F_Test_Guide.md §2 阶段 1「SPI 命令路径
+     * 用例号：TC-NET-101（docs/测试说明/板级测试/CH395F_Test_Guide.md §2 阶段 1「SPI 命令路径
     *          完整性」——该条目的各步就是本函数按序执行的九个测试项，项号见各项标注）。
     */
    {
@@ -187,7 +187,7 @@ static void phase1_run(void) {
     * 失败：第二次读非 0x0000（测试期间出现新事件）。
     *
     * 用例号：本项即原 TC-NET-102（全局中断状态一致性）。该条目在 2026-08-22
-     *          文档重构时被删、而 docs/测试说明/CH395F_Test_Guide.md 附录 B 的
+     *          文档重构时被删、而 docs/测试说明/板级测试/CH395F_Test_Guide.md 附录 B 的
     *          汇总行遗留至今，故在此把号挂回实现体。
     */
    {
@@ -2,7 +2,7 @@
 * 模块名称：GD5F2GQ5UE Driver Test Suite
 * 模块功能：GD5F2GQ5UE SPI NAND Flash 驱动测试入口，按阶段组织测试用例，
 *          覆盖 gd5f2gq5ue.c 全部公开/私有函数，并延伸到 FTL（nand_ftl）与
- *          FatFS diskio。详见 docs/测试说明/GD5F2GQ5UE_Test_Guide.md。
+ *          FatFS diskio。详见 docs/测试说明/板级测试/GD5F2GQ5UE_Test_Guide.md。
 * 适用平台：STM32F4 系列（GD5F2GQ5UE SPI NAND）
 * 作者：王建锋
 * 创建日期：2026-08-26
@@ -3,7 +3,7 @@
 * 模块功能：DWT CYCCNT 微秒时基 + 采样统计（min/med/p95/max/尖峰）+ [LAT]
 *          机器可读报告与 verdict；Phase 12（M1）：SPI 字节命令 / DMA 时延
 *          基线（SPI_CMD/SPI_DMA，硬件层模式，无需 PC）。分段定义与判定基线见
- *          docs/测试说明/链路延迟测试说明.md。
+ *          docs/测试说明/专项验证/链路延迟测试说明.md。
 * 适用平台：STM32F4 系列（CH395F）
 * 作者：王建锋
 * 创建日期：2026-09-22
@@ -5,7 +5,7 @@
 *          Phase 12（硬件层，M1）：SPI 字节命令 / DMA 时延基线（SPI_CMD/SPI_DMA，无需 PC）；
 *          Phase 13/14（NET 层，M2/M3 规划）：芯片发送握手 / 队列往返 /
 *          生产路径时延。分段定义、判定基线与执行流程见
- *          docs/测试说明/链路延迟测试说明.md。
+ *          docs/测试说明/专项验证/链路延迟测试说明.md。
 * 适用平台：STM32F4 系列（CH395F）
 * 作者：王建锋
 * 创建日期：2026-09-22
@@ -494,7 +494,7 @@ static int32_t phase8_verify(uint8_t *buf, uint32_t size, uint32_t offset) {
 #endif

 /* 用例号：TC-NET-801（SEND 方向）与 TC-NET-802（RECV 方向）——两向由
- *          PHASE8_DIRECTION 编译期切换，定义见 docs/测试说明/CH395F_Test_Guide.md
+ *          PHASE8_DIRECTION 编译期切换，定义见 docs/测试说明/板级测试/CH395F_Test_Guide.md
 *          阶段 8（本函数体从未改过名，只是一直没挂上号，2026-10-21 核对补注）。 */
 static void phase8_run(int32_t sockfd) {
 #if PHASE8_DIRECTION == PHASE8_DIR_RECV
@@ -610,7 +610,7 @@ static void phase8_run(int32_t sockfd) {
 * 通过：select 检测到数据并成功回显。
 * 失败：select 未检测到数据或回显失败。
 * 用例号：TC-NET-901（单 Socket 就绪检测）与 TC-NET-902（超时返回 0），
- *          定义见 docs/测试说明/CH395F_Test_Guide.md 阶段 9——本测试一直在，
+ *          定义见 docs/测试说明/板级测试/CH395F_Test_Guide.md 阶段 9——本测试一直在，
 *          只是从未挂上这两个号（2026-10-21 核对补注）。
 * =================================================================== */

@@ -811,7 +811,7 @@ static void phase10_run(int32_t sockfd) {
 * 通过：从连接建立到 recv 返回 0 的间隔落在 10s~120s 有界窗
 *          （芯片定时语义与手册公式 75s 不符，实测判死 18~31s——
 *          见《网络自愈架构设计》§5.2 E11 与 phase11_run 内判据注释）。
- * 用例号：TC-NET-1101（docs/测试说明/CH395F_Test_Guide.md 阶段 11 KeepAlive 触发断开）。
+ * 用例号：TC-NET-1101（docs/测试说明/板级测试/CH395F_Test_Guide.md 阶段 11 KeepAlive 触发断开）。
 * =================================================================== */

 #ifdef ENABLE_PHASE11_TESTS
@@ -229,7 +229,7 @@ void sd2506_test_run(void)
     *      不再出现"Phase 2 显示的是含 Phase 1 的累计值"这种易误读输出；
     *   2) 末尾输出套件级 `=== RTC Tests: N/M PASSED (failed=0) ===` 汇总行——
     *      它是 run_all_suites.py --require-suite-summary 的判定标记
-     *      （见 test_common.h / docs/测试说明/测试开发标准流程.md §3.2）。 */
+     *      （见 test_common.h / docs/测试说明/流程与规范/测试开发标准流程.md §3.2）。 */
    uint16_t suite_total  = 0U;
    uint16_t suite_passed = 0U;
    uint16_t suite_failed = 0U;
@@ -6,7 +6,7 @@
 *
 *           设计取舍：**统计变量仍按套件独立**（各套件持有自己的 `g_xxx_stats`），
 *           公共宏只提供"内核"，由各套件用一行宏把它绑定到自己的统计变量。
- *           理由见 docs/测试说明/测试开发标准流程.md §3.2：
+ *           理由见 docs/测试说明/流程与规范/测试开发标准流程.md §3.2：
 *             - 统计变量独立 = 防跨套件串数（历史约定，不能破）；
 *             - 内核共用    = 报告行格式/字段一处维护，改一次即全生效。
 *
@@ -26,7 +26,7 @@ extern "C" {
 * ⚠️ 默认必须是**产品构建**（全部注释）——pre-commit 钩子 `test-suite-switch` 会拦截
 * 未显式放行的测试构建（`--allow-test-build` / `ALLOW_TEST_BUILD=1`）。
 * 跑套件回归时取消注释所需套件；跑完务必改回、或直接用 `test/run_all_suites.py`
- * （自动改宏 + 结束后无条件还原）。详见 docs/测试说明/测试开发标准流程.md §3.1/§3.6。 */
+ * （自动改宏 + 结束后无条件还原）。详见 docs/测试说明/流程与规范/测试开发标准流程.md §3.1/§3.6。 */
 //#define TEST_SUITE_CH395F
 //#define TEST_SUITE_STORAGE
 //#define TEST_SUITE_GD5F
@@ -54,7 +54,7 @@ extern "C" {
 * 创建"的旧疑点不成立（实测 RTC 套件正常执行；RTC 已计入下方析取，故 RTC 构建下本
 * 标记亦置位、testTask 正常保留）。
 * 4 个套件（含 RTC）在此补齐：若将来再引入"测试构建下 defaultTask 空闲"等分支而复用
- * 本标记，可避免重演"漏 RTC"的隐患。详见 docs/测试说明/实机测试实施指南.md §8.3。 */
+ * 本标记，可避免重演"漏 RTC"的隐患。详见 docs/测试说明/板级测试/实机测试实施指南.md §8.3。 */
 #if defined(TEST_SUITE_CH395F) || defined(TEST_SUITE_STORAGE) || defined(TEST_SUITE_GD5F) || defined(TEST_SUITE_RTC)
 #define TEST_SUITE_SELECTED
 #endif