更新一下文档

AGENTS.md

@@ -5,8 +5,10 @@
 ## 构建
 
 - **仅支持 Keil MDK-ARM v5 (ARMCC)**，无其他工具链
-- 命令行编译：`@build`（自动执行 `MDK-ARM/build.bat`）
-- 退出码：0 = 成功 | 1 = 有警告（不通过）| 2+ = 错误，查看 `MDK-ARM/build_log.txt`
+- 命令行编译：`@build`（执行 `MDK-ARM/build.bat`，从仓库根目录用**相对路径**调用）
+- `build.bat` 硬编码 Keil 路径 `C:\Keil_v5\UV4\UV4.exe`（本机已验证存在；换机器需改）
+- 退出码：0 = 0 错误 0 警告 | 1 = 有警告或错误（查看 `MDK-ARM/build_log.txt`）
+- ⚠️ **旧绝对路径陷阱**：仓库曾位于 `D:\Code\DTU 程序\STM32F4-Base`，`.opencode/command/*.md` 与 `test/run_boot_test.ps1` 中若出现该路径一律视为失效，改用仓库相对路径（如 `& "MDK-ARM\build.bat"`）
 
 ## 硬件
 
@@ -16,6 +18,7 @@
 | GD5F2GQ5UE NAND | SPI1 | PE0 CS, PB3 SCK, PB4 MISO, PB5 MOSI, PB8 WP, PE1 HOLD |
 | TPAFE5160 ADC | 并行16位 | PG0-PG15 数据, PD3 RD, PD4 CONVST, PD7 BUSY |
 | USART1 | 串口 | PA9 TX, PA10 RX (115200bps) |
+| RS-485 | UART5 | PC12 TX, PD2 RX, PD0 DE（半双工） |
 | 6x LED | GPIO | PC4, PC5, PB1, PB2, PF11, PF12（低电平点亮） |
 
 MCU: STM32F407ZGTx @ 168MHz (HSE 8MHz → PLL M=4/N=168/P=2，见 `*.ioc`/`stm32f4xx_hal_conf.h`)
@@ -23,22 +26,30 @@ MCU: STM32F407ZGTx @ 168MHz (HSE 8MHz → PLL M=4/N=168/P=2，见 `*.ioc`/`stm32
 ## 架构
 
 ```
-Src/main.c → 外设初始化 → app_main_init → gd5f2gq5ue_init → tpafe5160_init
-  → osKernelInitialize → MX_FREERTOS_Init → osKernelStart
-  → [FreeRTOS tasks: defaultTask, netTask, ftpTask]
+Src/main.c → CubeMX 外设初始化 → app_main_init → osKernelStart
+  → [FreeRTOS tasks: defaultTask, netTask, ftpTask, testTask, uiTask, timeSyncTask]
 ```
 
-- **defaultTask**：FTL + FatFS 初始化测试（开机一次性）
-- **netTask**：`net_init()` → `net_poll()` + `net_process_messages()` 每 10ms
-- **ftpTask**：`lftpd_start("/", 21, &ftp)` 延迟 7s 后启动
+- **app_main_init 顺序**（时间子系统优先，使后续日志带时间戳）：`sd2506_init` → `sys_clock_init`（墙钟基准）→ `rs485_init` → `gd5f2gq5ue_init` → `tpafe5160_init` → SD2506 诊断 → `tpafe5160_start_conv_irq`
+- **就绪屏障**（`App/sys_events.h` Event Flags，取代魔法延时/全局轮询）：`SYS_EVT_NET_READY`(bit0, netTask 置位) / `SYS_EVT_STORAGE_READY`(bit1, defaultTask 置位) / `SYS_EVT_FTP_READY`(bit2) / `SYS_EVT_TIMESYNC_READY`(bit3)；消费者用 `osEventFlagsWait` 阻塞等待
+- **defaultTask**：FatFS 挂载（`f_mount` forced，无卷自动 `f_mkfs` FAT32）→ 置 `SYS_EVT_STORAGE_READY` → LED 闪烁循环
+- **netTask**：延时 2s → `net_stack_bring_up()`（net_init + MAC + PHY 强制 100M 全双工 + 等链路 ≤3s）→ 置 `SYS_EVT_NET_READY` → 循环 `net_poll()` + `net_process_messages()` + `osDelay(1)`（tick=1ms）
+- **ftpTask**：`osEventFlagsWait(NET_READY | STORAGE_READY, WaitAll)` 后 `lftpd_start("/", 21, &ftp)`（已无 7s 魔法延时）
+- **testTask**：测试套件入口（`test/test_config.h` 选择；产品构建下空转）
+- **uiTask**：等 `SYS_EVT_NET_READY` 后 `ui_port_init` → `ui_menu_init` → 启动 UI net sink
+- **timeSyncTask**：TCP 墙钟时间同步（PC 推送）
+- 功能编译开关：`App/app_cfg.h`（`APP_NET_ENABLE` / `APP_ADC_ENABLE` / `APP_RS485_ENABLE`）
 
 ### 任务栈
 
-| Task | 栈大小 |
-|---|---|
-| defaultTask | 2048 |
-| netTask | 4096 |
-| ftpTask | 4096 |
+| Task | 栈大小(words) | 优先级 |
+|---|---|---|
+| defaultTask | 2048 | Normal |
+| netTask | 4096 | Normal |
+| ftpTask | 4096 | Normal |
+| testTask | 4096 | BelowNormal |
+| uiTask | 16384 | BelowNormal |
+| timeSyncTask | 2048 | Normal |
 
 ## CH395F 设计原则
 
@@ -47,32 +58,45 @@ Src/main.c → 外设初始化 → app_main_init → gd5f2gq5ue_init → tpafe51
 
 ## NET 网络层
 
-- `net_socket.h/c` — BSD Socket API，多连接模式下 Socket 0 监听、Socket 1~7 数据
+- `net_socket.h/c` — BSD Socket API；**单连接模式**（`ch395f_set_fun_para(0x09)`：多 Socket + TCP Server 单连接 + 手动关闭），连接停留在 Socket 0
 - `net_select.h/c` — select/poll I/O 多路复用
 - 线程安全通过消息队列（`netMsgQueue`）实现，所有 CH395F 操作在 netTask 中串行处理
-- 网络初始化顺序（多连接）：`ch395f_set_fun_para(0x02)` → `ch395f_init()` → 配置 Socket 1~7（缓冲区+端口+协议，不 OPEN）→ 配置 Socket 0（TCP LISTEN）
+- `net_init` 顺序：check_exist → reset → `set_fun_para(0x09)` → MSS/重传/KeepAlive → IP → `ch395f_init()` → Socket 0~7 缓冲分配 → ping 使能
+- 静态 IP 192.168.1.100/24（gw 192.168.1.1），PHY 强制 100M 全双工
 - **新文件需手动添加到 Keil MDK 工程**才能编译
 
+## 测试构建模式
+
+- `test/test_config.h`：`TEST_SUITE_CH395F` / `TEST_SUITE_STORAGE` / `TEST_SUITE_GD5F` / `TEST_SUITE_RTC` **互斥**（一次构建只能启用一个，`#error`）；全部注释 = 正常产品构建
+- CH395F 套件沿用 `test/ch395f_test.h` 阶段宏：硬件层 Phase 1~5 与 NET 层 Phase 6~11 **互斥**（`#error`）；硬件层模式下 netTask 不创建，testTask 独占 CH395F
+- 各模块测试指南见 `docs/测试说明/`（CH395F / GD5F / SD2506 / FTP）
+
 ## 关键文件
 
 | 路径 | 说明 |
 |---|---|
 | `Src/main.c` | 入口，CubeMX 生成 + USER CODE 区域 |
 | `Src/freertos.c` | FreeRTOS task 创建，CubeMX 生成 + USER CODE 区域 |
+| `App/app_main.c` | 应用初始化流程编排 |
+| `App/sys_events.h` | 系统就绪事件（Event Flags 就绪屏障） |
+| `App/app_cfg.h` | 功能模块编译开关 |
 | `App/task/net_task.c` | netTask 主循环（网络初始化 + 轮询） |
-| `Drivers/BSP/NET/` | BSD Socket API 网络抽象层 |
+| `test/test_config.h` | 测试套件选择（互斥开关） |
+| `Drivers/BSP/NET/` | BSD Socket API 网络抽象层 + lftpd |
 | `Drivers/BSP/CH395F/` | CH395F SPI 驱动 |
 | `Drivers/BSP/GD5F2GQ5UE/` | NAND Flash 驱动 + dhara FTL + FatFS diskio |
 | `Drivers/BSP/TPAFE5160/` | ADC 并行接口驱动 |
 | `Drivers/BSP/SD2506/` | RTC 驱动 |
 | `Drivers/BSP/RS485/` | RS-485 通信（UART5 + PD0 DE） |
+| `Drivers/BSP/UI/` | LVGL UI 组件（与 PC 模拟器共用源码） |
 
 ## 驱动关键点
 
 详见 `docs/` 目录：
-- `CH395F_Trap_Records.md` — CH395F 已知陷阱
-- `GD5F2GQ5UE_Trap_Records.md` — GD5F2GQ5UE 已知陷阱
-- `CH395F_Test_Guide.md` — 网络测试说明
+- `docs/问题记录/CH395F_Trap_Records.md` — CH395F 已知陷阱
+- `docs/问题记录/GD5F2GQ5UE_Trap_Records.md` — GD5F2GQ5UE 已知陷阱
+- `docs/问题记录/SD2506_Trap_Records.md` — SD2506 RTC 已知陷阱
+- `docs/测试说明/CH395F_Test_Guide.md` — 网络测试说明（含构建模式与执行顺序）
 
 ## 串口调试（serial-mcp-server MCP/CLI）
 
@@ -85,20 +109,43 @@ Src/main.c → 外设初始化 → app_main_init → gd5f2gq5ue_init → tpafe51
 
 改完代码后运行 **`@test`** 可自动执行完整闭环：**构建验证 → 串口捕获武装（serial-mcp-server 采集窗口）→ 烧录（`MDK-ARM/download.bat`，下载后 Reset & Run）→ 解析捕获 JSON → `test/verify_log.ps1` 标记校验 → PASS/FAIL 判定并迭代**。
 
-- **推荐一键命令**：`test/run_boot_test.ps1` = 采集（含 EOF 重试）→ 烧录 → 提取日志 → verify 全流程，退出码 0=PASS/1=FAIL/2=错误
+- **推荐一键命令**：`test/run_boot_test.ps1` = 采集（含 EOF 重试）→ 烧录 → 提取日志 → verify 全流程，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=日志文件错误
 - 判定标准：`@test` 内部先 `@build`（0 错误 0 警告），再 `@download`（退出码 0），日志用 `verify_log.ps1` 校验（默认 Required：`App init OK`/`Network Init`/`net init: OK`；Forbidden：`FAIL`/`ERROR`/`HardFault`）
 - **采集必须在烧录前武装**（采集进程先打开 COM 等 first-byte，烧录触发复位后才抓得到开机日志）；`run_boot_test.ps1` 的 `-FlashCmd` 分支已保证顺序
 - 每次按模块定制标记（网络/存储/RTC/ADC/RS485）见 `docs/测试说明/自动化测试流程.md`
-- UI（`App/task/ui_task.c`）当前无 DBG 打印，无法从串口自动验证；如需 UI 回归，先在固件加 `UI port init: OK` / `UI menu init: OK` 打印再纳入 Required
+- UI 已有 DBG 打印（`UI port init: OK` / `UI menu init: OK` / `UI net sink: started`），可用 `-Required "UI port init: OK;UI menu init: OK"` 自动回归 UI 初始化；屏幕内容仍需人工目检
+
+## 代码规范与 pre-commit
+
+- **提交被 pre-commit 钩子门禁**，任一失败即拦截：cppcheck 静态分析（warning/performance/portability/style）+ 代码规范机械检查 + U+FFFD 乱码检查 + gitlint commit message
+- 代码规范 V1.0（`docs/代码规范/嵌入式C语言代码规范（V1.0）.md`）：命名小写下划线（`g_`/`s_`/`p_`/`a_` 前缀）、头文件保护宏 `XXX_H`、常量在右、文件头模块注释块等；可机械校验项由 `scripts/check_coding_standard.py` 强制
+- 检查范围仅项目自有代码；第三方（`Lib/`、`Middlewares/`、CMSIS/HAL、`lftpd`、`Drivers/BSP/UI`、`test/`）被排除
+- 新机器启用：`pre-commit install`；全库扫描：`pre-commit run --all-files`
+- 详见 `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`
+
+## LVGL PC 模拟器
+
+`simulator/`（CMake + SDL2 2.32.10 预编译库）可在 PC 上开发调试 UI，**与 MCU 端共用 UI 源码**（`Drivers/BSP/UI/ui_menu.c`、`ui_font_cn_12.c`），无需烧录：
+
+```powershell
+cd simulator
+cmake -B build -G "Visual Studio 16 2019" -A x64
+cmake --build build --config Debug
+# 运行 simulator\build\Debug\lvgl_sim.exe
+```
+
+- 详见 `docs/UI 设计/LVGL模拟器部署与使用说明.md`
+- 中文字体：`ui_cn_chars.txt`（字符集）+ `tools/font_gen/` 生成 `Drivers/BSP/UI/ui_font_cn_12.c`，见 `docs/UI 设计/UI_中文字体生成与配置.md`
 
 ## 注意
 
 - `Inc/` 和 `Src/` 中 CubeMX 生成的文件带有 `USER CODE BEGIN`/`END` 标记，自定义代码写在这些区域之间
 - `Drivers/BSP/` 下的驱动文件为纯手工代码，不受 CubeMX 保护
 - CH395F 每次 SPI 事务需用 `ch395f_spi_begin()` / `ch395f_spi_end()` 包裹
--  CH395F SPI PCB设计问题，现在分频系数必须为 8，速度相对较低
-- FreeRTOS V10.3.1 via CMSIS-RTOS V2，HAL 时基用 TIM7（非 SysTick）
+- CH395F SPI PCB 设计问题，分频系数必须为 8，速度相对较低
+- FreeRTOS V10.3.1 via CMSIS-RTOS V2，HAL 时基用 TIM7（非 SysTick），tick = 1ms
 - NVIC 优先级分组 4 位，外设中断优先级 ≥ 5（`configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY`）
+- **内存预算紧张**：任务栈目前普遍偏大（见 `待处理内容.md`），新增任务/缓冲/栈前必须先核算 RAM 余量
 
 ## 源码编辑与编码安全（铁律）
 
@@ -106,6 +153,6 @@ Src/main.c → 外设初始化 → app_main_init → gd5f2gq5ue_init → tpafe51
 
 - **绝不用 `Get-Content` / `Set-Content` / `cmd` 文本重写含中文的源码文件**。这类"整文件重写"会按系统默认编码重新解码再写回，多字节中文必被 `U+FFFD` 替换且不可逆。
 - **改代码只用 Edit 工具**（精确子串替换，不重新编解码整个文件，安全）；批量替换用 Edit 的 `replaceAll`。
-- 必须脚本级替换时，使用显式且一致的编码（如 Python `open(p, encoding="utf-8")` 同编码回写），并先确认工程编码（Keil 工程常用 GBK）——但**最稳的是别碰**，只用 Edit / git。
+- 必须脚本级替换时，使用显式且一致的编码（**本工程源码为 UTF-8 无 BOM**，如 Python `open(p, encoding="utf-8")` 同编码回写）——但**最稳的是别碰**，只用 Edit / git。
 - **发现乱码先别急着 `git checkout`**：`git checkout` 会丢弃所有未提交工作，使损失扩大。先评估能否用 Edit 仅改坏掉的那几行。
 - 验证是否真损坏用字节级检查（统计 `EF BF BD` 出现次数），不要依赖终端/Read 渲染判断。