整理 App 与 test 目录：按职责分子目录并同步全库引用

2026-09-26 12:51:07 +08:00
parent 39bd06adea
commit 22559365b9
90 changed files with 2650 additions and 2487 deletions
@@ -1,41 +1,24 @@
 # test/ — 测试代码与主机端脚本

-> 测试分两部分：**板端测试套件**（`.c/.h`，编入固件由 testTask 执行）与
-> **主机端脚本**（`.py`，PC 侧驱动板子并判读结果）。
+> 测试分两部分，**物理隔离**在两个子目录：
+> - **`board/`** —— 板端测试套件（`.c/.h`，编入固件由 testTask 执行）
+> - **`host/`** —— 主机端脚本（`.py`，PC 侧驱动板子并判读结果）

-## 板端测试套件（编入固件）
+## 目录结构

-| 文件 | 测试对象 |
-|---|---|
-| `test_config.c/h` | 测试任务配置（启用哪些套件） |
-| `ch395f_test_task.c/h` + `ch395f_test.h` | CH395F 以太网（硬件层 + NET 层） |
-| `gd5f_test_task.c/h` + `gd5f_test.h` | GD5F2GQ5UE SPI NAND 存储 |
-| `sd2506_test_task.c/h` + `sd2506_test.h` | SD2506 RTC |
-| `storage_test_task.c/h` + `storage_test.h` | 存储性能 |
-| `net_test_task.c/h` + `net_latency_test.c/h` | 网络层 / 链路时延 |
-| `nand_ftl_test.c`（如有） | FTL 层 |
-
-## 主机端脚本（PC 侧）
-
-| 脚本 | 作用 |
-|---|---|
-| `run_boot_test.py` | **`@test` 一键闭环**：开串口+清日志 → 烧录 → wait-idle → 校验（退出码 0=PASS） |
-| `verify_log.py` | 日志标记校验（Required/Forbidden 标记） |
-| `ch395f_socket_test.py` | Socket 通信测试 |
-| `ftp_test.py` / `ftp_up_dl_test.py` / `ftp_speed_test.py` | FTP 功能 / 上传下载 / 速度 |
-| `ftp_capture.py` / `ftp_regression.py` | FTP 抓包 / 回归 |
-| `e02_probe.py` | E-02 专项探针 |
-| `latency_peer.py` | 链路时延对端（PC peer） |
-| `time_sync_server.py` | 时间同步推送服务 |
+| 目录 | 内容 | README |
+|---|---|---|
+| `board/` | 板端测试套件（编入 Keil 工程，占 RAM） | [`board/README.md`](board/README.md) |
+| `host/` | PC 端测试/判读脚本（Python） | [`host/README.md`](host/README.md) |

 ## 运行方式

 ```bash
 # @test 一键闭环（推荐）
-& '.venv\Scripts\python.exe' test/run_boot_test.py
+& '.venv\Scripts\python.exe' test/host/run_boot_test.py

 # 单独校验日志
-& '.venv\Scripts\python.exe' test/verify_log.py <日志文件>
+& '.venv\Scripts\python.exe' test/host/verify_log.py <日志文件>
 ```

 退出码约定：`0`=PASS / `1`=FAIL / `2`=采集或烧录错误 / `3`=用法或预检错误。
@@ -43,7 +26,10 @@
 ## ⚠️ 注意

 - 本目录**被 pre-commit 门禁排除**（测试代码不受 C 规范约束）
- 板端套件占用 RAM，启用前先核算预算（见 `docs/内存管理/`）
+- `board/` 套件占用 RAM，启用前先核算预算（见 `docs/内存管理/`）
+- **Keil 工程已同步**：`board/` 下 7 个 `.c` 编入 `MDK-ARM/STM32F4-Demo.uvprojx`，
+  IncludePath 含 `../test/board`；移动文件须同步改工程文件
+- 套件选择开关：`board/test_config.h` 的 `TEST_SUITE_*`（互斥，一次只启用一个）
 - 测试缓冲用**分 Phase 复用静态缓冲**（避免 `L6406E` 溢出）

 ## 相关文档
@@ -0,0 +1,40 @@
+# test/board/ — 板端测试套件
+
+> ⚠️ **编入固件**的测试代码（由 testTask 执行）。这些 `.c` 已注册到 Keil 工程
+> `MDK-ARM/STM32F4-Demo.uvprojx`，占用 MCU 的 RAM/Flash。
+
+## 文件一览
+
+| 文件 | 测试对象 / 作用 |
+|---|---|
+| `test_config.c/h` | **测试任务配置**：`TEST_SUITE_*` 套件选择开关（互斥）+ `ENABLE_DESTRUCTIVE_TESTS` |
+| `ch395f_test_task.c/h` + `ch395f_test.h` | CH395F 以太网（硬件层 Phase 1~5 / NET 层 Phase 6~11） |
+| `gd5f_test_task.c/h` + `gd5f_test.h` | GD5F2GQ5UE SPI NAND 存储 |
+| `sd2506_test_task.c/h` + `sd2506_test.h` | SD2506 RTC |
+| `storage_test_task.c/h` + `storage_test.h` | 存储性能 |
+| `net_test_task.c/h` | 网络层测试 |
+| `net_latency_test.c/h` | 链路时延探针（DWT CYCCNT 时基，MCU 专属） |
+
+## ⚠️ 构建约束（`AGENTS.md` 详述）
+
+- **套件互斥**：`test_config.h` 的 `TEST_SUITE_CH395F/STORAGE/GD5F/RTC` 一次只能启用一个
+  （违反则 `#error`）；**全部注释 = 产品构建**
+- **破坏性用例默认关闭**：`ENABLE_DESTRUCTIVE_TESTS`（默认注释）控制写/擦 NAND、格式化、
+  坏块注入。关闭时为**只读模式**（横幅 `mode: READ-ONLY`），可随时在在用设备上跑
+- ⚠️ 实测一轮破坏性 GD5F 运行即让 dhara **多记一个坏块**（容量下降且需全片擦除恢复）——
+  只在产线首启或明确需要时打开
+- CH395F 套件：硬件层与 NET 层模式互斥
+- **总线独占**：CH395F 硬件层模式下 netTask 自挂起，testTask 独占 CH395F
+
+## 添加新测试套件
+
+1. 在 `test_config.h` 加开关（并入互斥 `#error` 检查）
+2. 新建 `<模块>_test_task.c/h`
+3. **注册进 Keil 工程**（`<FilePath>..\test\board\xxx.c</FilePath>`）
+4. 跑回归：`@test`（`test/host/run_boot_test.py`）
+
+## 相关文档
+
+- 测试指南：`docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md`
+- 套件配置：`AGENTS.md`「测试与验证」章
+- 容量恢复：`docs/测试说明/存储维护与容量恢复.md`
@@ -0,0 +1,52 @@
+# test/host/ — 主机端测试脚本
+
+> PC 侧的测试驱动与判读脚本（Python，跑在开发机上，经串口/网络与目标板交互）。
+
+## 文件一览
+
+### 流程与判读
+
+| 脚本 | 作用 |
+|---|---|
+| `run_boot_test.py` | **`@test` 一键闭环**：开串口+清日志 → 烧录 → wait-idle → `verify_log` 校验（退出码 0=PASS） |
+| `verify_log.py` | **日志标记校验**：Required / Forbidden 标记 → PASS / FAIL |
+| `e02_probe.py` | E-02 专项探针（错误码传播审计） |
+
+### 网络 / FTP
+
+| 脚本 | 作用 |
+|---|---|
+| `ch395f_socket_test.py` | Socket 通信测试（回显服务器 / 文件收发） |
+| `ftp_test.py` | FTP 基本功能测试 |
+| `ftp_up_dl_test.py` | FTP 上传下载测试 |
+| `ftp_speed_test.py` | FTP 传输速度测试 |
+| `ftp_capture.py` | FTP 流量抓取 |
+| `ftp_regression.py` | FTP 回归套件 |
+
+### 时间 / 时延
+
+| 脚本 | 作用 |
+|---|---|
+| `latency_peer.py` | 链路时延测试的 PC 对端（peer） |
+| `time_sync_server.py` | 时间同步推送服务（对时源） |
+
+## 运行方式
+
+```bash
+# @test 一键闭环（推荐）
+& '.venv\Scripts\python.exe' test/host/run_boot_test.py
+```
+
+> 串口端口配置在 `.opencode/serial_config.json`（单一配置源，当前 COM6/115200）。
+
+## ⚠️ 注意
+
+- **PYTHONPATH/路径敏感**：脚本按仓库根相对路径读写，**从仓库根执行**
+- 本目录**被 pre-commit 门禁排除**
+- 台架探针族（TCP 复连 / FTP 中止等）在 `MDK-ARM/*.py`，与本目录分工不同
+
+## 相关文档
+
+- `docs/测试说明/自动化测试流程.md` — `@test` 细节与失败模式
+- `docs/测试说明/测试开发标准流程.md` — 测试分层与门禁
+- `docs/测试说明/CH395F_Test_Guide.md`、`FTP_Test_Guide.md`
@@ -12,7 +12,7 @@ net 层当作"刚建立就断开"释放。修复见 net_socket.c handle_disconne
 内容校验；任一环节失败即退出码 1。

 用法：
-    & '.venv\\Scripts\\python.exe' test/ftp_regression.py --host 192.168.1.100
+    & '.venv\\Scripts\\python.exe' test/host/ftp_regression.py --host 192.168.1.100
 """

 import argparse
@@ -31,7 +31,7 @@ import sys
 import threading
 import time

-# --- Protocol constants (mirror test/net_latency_test.c Phase 13 defines) ---
+# --- Protocol constants (mirror test/board/net_latency_test.c Phase 13 defines) ---
 HELLO = b"\x5a\xa5\x58\x01"
 OP_L5_RECV = 0x01
 OP_L5_SEND = 0x02
@@ -19,7 +19,7 @@
  - 烧录带超时（默认 180s；旧版无超时，坏 SWD 连接会永久挂起）

 用法:
-  & '.venv\\Scripts\\python.exe' test/run_boot_test.py
+  & '.venv\\Scripts\\python.exe' test/host/run_boot_test.py
      [--port COM7] [--baud-rate 115200] [--settle-ms 8000] [--max-wait-ms 30000]
      [--flash-cmd MDK-ARM\\download.bat] [--flash-timeout 180]
      [--required "App init OK;Network Init;net init: OK"]
@@ -8,7 +8,7 @@
    板子端在 timeSyncTask 中以 TCP Server 方式监听端口，收到后调用
    sys_clock_set_unix() 更新系统墙钟并写回 SD2506 RTC，使板子时间 == 你电脑的时间。

-协议（板子端实现见 App/time_sync.c 的 time_sync_handle_conn）：
+协议（板子端实现见 App/sync/time_sync.c 的 time_sync_handle_conn）：
    字节 0..3 : 魔术字 "TIME" (0x54 0x49 0x4D 0x45)
    字节 4..7 : 本地 Unix 时间戳，uint32，大端（主机字节序转换后由板子分解）

@@ -5,7 +5,7 @@
 输出结构化判定（格式与旧 PowerShell 版逐字一致，下游文档/习惯不受影响）。

 用法:
-  & '.venv\\Scripts\\python.exe' test/verify_log.py --log-path <file>
+  & '.venv\\Scripts\\python.exe' test/host/verify_log.py --log-path <file>
      [--required 'marker1;marker2']
      [--forbidden 'FAIL;ERROR;HardFault;assert;[ERR]']
      [--show-tail-lines 40]
@@ -15,7 +15,7 @@
  1 = FAIL（缺 Required 或命中 Forbidden）
  2 = ERROR（日志文件不存在/不可读）

-默认 Required 标记对应 STM32F4-Base 启动序列（见 App/app_main.c + App/task/net_task.c），
+默认 Required 标记对应 STM32F4-Base 启动序列（见 App/app/app_main.c + App/task/net_task.c），
 按测试用例覆盖，例如:
  --required 'App init OK;net init: OK;PHY: 100M FULL'
  --forbidden 'FAIL;ERROR;HardFault;assert;[ERR]'