文档体系重组与 D-7 一致性门禁落地，清理芯片手册孤儿图片

- D-6 目录规范化：docs 根目录散落文档归入 UI设计/子系统设计/架构设计/审查记录/
  环境与部署/网络 等子目录，去掉目录名空格，重命名 嵌入式C语言代码规范_V1.0.md
- D-7 三档一致性门禁：新增 scripts/check_doc_links.py（链接存在性）、
  scripts/gen_task_table.py（FreeRTOS 任务表数值）、scripts/check_mem_numbers.py
  （内存/Flash 体积），均支持 --check/--write/--diff，pre-commit 钩子同步注册
- D-5 文档索引：新建 docs/README.md，新建 docs/文档规范.md 约束目录命名与链接写法
- D-1 芯片手册瘦身：删除 1069 张无引用孤儿图片（77.06 MB），
  docs/芯片手册 120 MB → 41 MB，已引用图片零断链
- 同步 C 源码注释中的文档路径引用（D-6 重组后），构建 0 错误 0 警告

docs/环境与部署/项目部署环境要求.md

@@ -0,0 +1,544 @@
+# 项目部署环境要求
+
+> 版本：v1.0　日期：2026-09-13
+> 适用工程：STM32F4-Base（STM32F407ZGTx + CH395F 以太网 / LVGL UI / FreeRTOS）
+> 用途：新机器搭建、环境交接、现场部署时的**一站式环境核对清单**——开发机软件环境、
+> 目标板硬件与资源预算、网络/服务现场部署、远端客户端环境、验收步骤与常见环境问题。
+> 文中所有版本/参数/数值均取自仓库内配置或本机实测（`AGENTS.md`、`MDK-ARM/*.bat`、
+> `simulator/README.md`、`docs/内存管理/`、`docs/子系统设计/网络配置说明.md`、`docs/测试说明/` 等），
+> 换机器时以仓库文件为准逐项核对。
+
+---
+
+## 一、环境总览
+
+本项目涉及三类环境，部署前按 §二~§五 逐一核对：
+
+```mermaid
+flowchart LR
+    subgraph DEV["① 开发机（Windows PC）"]
+        K[Keil MDK-ARM v5<br/>MCU 编译/烧录]
+        X[STM32CubeMX 6.17.0<br/>外设配置/代码再生成]
+        S[CMake + VS2019/2026<br/>LVGL PC 模拟器]
+        P[Python .venv<br/>字体/回归脚本]
+        T[Python 串口助手 serial_tool<br/>串口调试/自动测试]
+        G[Graphviz<br/>引用关系图渲染（可选）]
+    end
+    subgraph TGT["② 目标板（DTU 硬件）"]
+        M[STM32F407ZGTx @168MHz<br/>1MB Flash / 192KB SRAM]
+        H[CH395F / GD5F2GQ5UE<br/>TPAFE5160 / RS-485 / LED×6]
+    end
+    subgraph RMT["③ 远端客户端（PC/浏览器）"]
+        C[DTU-RemoteLCD<br/>或任意 TCP 客户端]
+    end
+
+    DEV -- "USB：下载器（ST-Link 等）" --> TGT
+    DEV -- "USB 串口 USART1<br/>COMx @115200 调试日志" --> TGT
+    TGT -- "以太网（CH395F）<br/>FTP:21 / 对时:8888 / 显示:7003" --> RMT
+```
+
+| 环境 | 角色 | 必需性 |
+|---|---|---|
+| ① 开发机 | MCU 编译/烧录、UI 模拟器、脚本工具链 | 开发/测试必需 |
+| ② 目标板 | 运行固件的 DTU 硬件 | 上机必需 |
+| ③ 远端客户端 | 远程看图/按键、对时推送、FTP 文件操作 | 现场使用必需 |
+
+---
+
+## 二、开发机环境（Windows）
+
+### 2.1 操作系统与基础
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| 系统 | Windows 10/11 x64 | 全部工具链均为 Windows 形态（Keil / VS / SDL / COM 口）；本机实测 Win11 |
+| 终端 | PowerShell 5.1+ | 构建/测试脚本均为 `.bat` / `.ps1` |
+| 版本控制 | git | 提交受 pre-commit 钩子门禁（§2.7） |
+| 磁盘 | ≥10 GB 空闲 | Keil 工程 + VS 模拟器 `build/` + 工具链 |
+
+### 2.2 MCU 构建工具链（必需）
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| Keil MDK-ARM | **v5.x**（须含 ARMCC v5 编译器） | 工程锁定 `uAC6=0`（仅 ARMCC v5，**不支持 armclang**）；仅支持此工具链，无其他工具链 |
+| 安装路径 | `C:\Keil_v5\` | `MDK-ARM/build.bat`、`download.bat` 硬编码 `C:\Keil_v5\UV4\UV4.exe`；**换机器须装到同路径，或修改两个 bat 的 `UV4=` 行** |
+| 设备支持 | STM32F407ZGTx + CMSIS Flash 算法 | 工程引用 `STM32F4xx_1024.FLM`（1MB 片内 Flash，0x08000000），由 CMSIS STM32F4 设备包提供 |
+| STM32CubeMX | **6.17.0**（工程 `STM32F407-Demo.ioc` 记录的版本） | 修改外设/引脚/时钟配置并再生成 CubeMX 文件；固件包须 **STM32Cube FW_F4 V1.28.3** |
+| 命令行构建 | `& "MDK-ARM\build.bat"`（即 `@build`） | 退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt` |
+| 命令行烧录 | `& "MDK-ARM\download.bat"`（即 `@download`） | flash + Reset & Run；日志出现 `Application running` 判成功 |
+
+> ⚠ **版本一致性关键**：.ioc 记录 `MxCube.Version=6.17.0` + `FirmwarePackage=STM32Cube FW_F4 V1.28.3`，
+> 再生成代码必须用此组合——用更新版本的 CubeMX 会把仓库内 HAL 驱动升级、产生大量无关 diff（见 §六 速查）。
+> 自定义代码只写 `USER CODE BEGIN/END` 区域内（再生成时保留，`KeepUserCode=true`），**勿手改生成文件的非 USER CODE 区域**。
+
+**Keil 初始化配置（机器侧项，非项目自带）**：
+
+| 项 | 配置方法 | 说明 |
+|---|---|---|
+| License | 首次启动 UV4 自动生成 **90 天评估 license**；长期使用需购买正式 license | license 绑定机器、不在仓库；`Options for Target → License` 查看/输入 |
+| Device Pack | **Pack Installer** 安装 `Keil::CMSIS`、`Keil::STM32F4xx_DFP`（pack 源 https://www.keil.com/pack/ ） | 工程引用的 **Flash 算法 `STM32F4xx_1024.FLM` 就来自此 pack**（.uvoptx 的 `$$Device:STM32F407ZGTx$` 变量解析到 pack 目录 `C:\Keil_v5\PACK\Keil\STM32F4xx_DFP\<ver>\CMSIS\Flash\`）；**pack 缺失则下载失败** |
+| 下载器驱动 | 工程已配 **UL2CM3** 调试驱动 + Flash 算法参数（.uvoptx 自带，调试时钟 10 MHz） | 物理下载器（ST-Link 等）需装 USB 驱动（见第 8 步）；现场换其他下载器在 Keil `Options for Target → Debug → Settings` 切换 |
+
+> **项目自带、新机器无需重配**（随仓库同步）：编译器与目标选项（`.uvprojx`：ARMCC v5 / 设备 STM32F407ZGTx / Cortex-M4+FPU）、
+> 调试与下载参数（`.uvoptx`）、Run-Time Environment（`MDK-ARM/RTE/`）、启动文件 `startup_stm32f407xx.s`、构建/下载 bat、
+> **RAM/Flash 链接布局（见下）**。
+
+**RAM / Flash 链接布局（项目自带，自动同步，新机器无需在 Keil 里重设）**：
+
+- 链接器使用**手动 scatter 文件** `MDK-ARM/STM32F407-Demo/STM32F407-Demo.sct`（在仓库，`.uvprojx` 已启用 `useFile=1`）：
+  - `ER_IROM1` 0x08000000，1 MB（代码 + 只读数据）
+  - `RW_IRAM1` 0x20000000，**128 KB**（SRAM1 112K + SRAM2 16K 连续；SRAM3/CCM 故意未映射——克隆芯片可能无 SRAM3）
+- Keil `Options for Target → Target` 页显示的片上内存来自 `.uvprojx` 的 `<Cpu>` 行（IRAM 112 KB / IRAM2 16 KB / IROM 1 MB，同样在仓库）+ Device Pack
+- ⚠ 新机器**不要在 GUI 里重填 RAM 区**，也**勿改 Target 页**（会回写共享的 `.uvprojx` 影响他人）；确需调整内存布局（如日后启用 SRAM3/CCM）时修改 `.sct` 并提交
+
+### 2.3 PC 模拟器环境（UI 开发/回归必需）
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| CMake | ≥ 3.15 | 本机实测 4.3.0-rc1 |
+| 编译器 | **VS2019 / 2022 / 2026 任一**（C++ x64 工作负载） | `build_sim.ps1` 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
+| Windows SDK | 10.0.19041 及以上 | CMake 配置时自动选用已装版本 |
+| SDL2 | 2.32.10（预编译，无需系统安装） | **不在仓库**（`simulator/SDL2/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见**第 3 步** |
+| 产物 | `simulator/build/Debug/lvgl_sim.exe` | `build/` 为生成物（gitignore），可整体删除重建 |
+
+```powershell
+& "simulator\build_sim.bat"                          # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑）
+.\simulator\build\Debug\lvgl_sim.exe                 # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）
+```
+
+> 模拟器与 MCU **共用 UI 源码**（`Drivers/BSP/UI/`），无硬件业务（网络推流除外，Winsock 版）。
+> 详见 `simulator/README.md`、`docs/UI设计/LVGL模拟器部署与使用说明.md`。
+
+### 2.4 Python 环境（脚本工具链）
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| 统一入口 | **仓库 `.venv\Scripts\python.exe`** | 一切依赖第三方库的脚本（字体生成、截图转 PNG、RemoDispBus 回归）都用它 |
+| 解释器版本 | Python ≥ 3.10（任意发行版） | 种子解释器仅用于建 venv 一次；本机为 3.12.4 |
+| 依赖 | `fonttools==4.51.0`、`pillow==10.3.0`、`pyserial==3.5` | 清单 = 仓库根 `requirements.txt`（**必须保持纯 ASCII**：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError） |
+| 入库情况 | `.venv/` 已 gitignore | **换机/首次必须重建** |
+
+```powershell
+# 重建（<种子python> 换成本机任一 python ≥3.10）
+& <种子python> -m venv .venv
+& '.venv\Scripts\python.exe' -m pip install -r requirements.txt
+```
+
+> ⚠ PATH 里默认 `python` 可能是 msys64 的（无第三方库）——**禁止**用它跑字体生成 / Pillow 脚本；
+> 纯标准库脚本（UI 回归测试、`extract_cn.py`）任意 python3 均可。
+
+### 2.5 中文字体生成依赖
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| Node.js + npm | 任意近期版本 | 一次性：`npm i -g lv_font_conv`（字体位图转换） |
+| fontTools | 仓库 `.venv`（§2.4） | `make_font.py` 依赖 |
+
+```powershell
+python tools/font_gen/extract_cn.py                        # 任意 python3：扫 UI 源码 → ui_cn_chars.txt
+& '.venv\Scripts\python.exe' tools/font_gen/make_font.py   # 宋体 12px 1bpp + 字符集 → ui_font_cn_12.c
+```
+
+> 任何 UI 文案新增汉字后必须走此流程（缺字 = 屏幕空白块），详见 `docs/UI设计/UI_中文字体生成与配置.md`。
+
+### 2.6 串口调试 / 自动化测试工具
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| Python 串口助手 | `tools/serial_tool/serial_tool.py`（仓库内置，.venv + pyserial） | 常驻 daemon + 薄 CLI + 全量日志文件；无需单独安装，`pip install -r requirements.txt` 即就绪 |
+| 调试串口 | USART1（PA9 TX / PA10 RX），115200 8N1 | **端口单一配置源 `.opencode/serial_config.json`**（本机 COM6）；换端口只改这个文件 |
+| 一键测试 | `test\run_boot_test.py`（即 `@test`，`& '.venv\Scripts\python.exe' test/run_boot_test.py`） | 开串口 + 清日志 → 烧录 → wait-idle（静默 8s/超时 30s）→ 提取 → 标记校验；默认端口取 `serial_config.json` / 115200，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法错误 |
+
+> 采集 = 端口常开 + daemon 全量日志（`tools/serial_tool/state/serial.log`），无采集窗口/first-byte/EOF 重试仪式。
+> 命令契约与陷阱见 `docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md`。
+
+### 2.7 代码审查钩子（pre-commit）
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| pre-commit | 已安装并 `pre-commit install` | 提交门禁（pre-commit + commit-msg 两类钩子） |
+| cppcheck | 在 PATH 中 | 本地钩子直接调 `cppcheck --enable=warning,performance,portability,style`（`language: system`） |
+| python | 在 PATH 中 | 本地钩子调 `scripts/check_mojibake.py`（U+FFFD 乱码）、`scripts/check_coding_standard.py`（规范 V1.0，纯标准库） |
+| gitlint | 随 pre-commit 自动拉取 | commit message 格式（宽松规则，兼容中文标题） |
+
+> 检查范围仅项目自有代码；`Lib/`、`Middlewares/`、`Drivers/BSP/UI`、`lftpd`、`dhara`、`test/` 等被排除。
+> 全库扫描：`pre-commit run --all-files`。详见 `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`。
+
+### 2.8 引用关系图渲染（Graphviz，可选）
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| Graphviz | `winget install Graphviz.Graphviz`（本机实测 16.1.0） | `tools/refgraph` 引用关系图生成器的渲染引擎；`dot` 在 `C:\Program Files\Graphviz\bin\`，工具自动定位，**无需配置 PATH** |
+| 必需性 | **可选** | 未装时工具自动跳过渲染（仍产出 `.dot`/`.json`，装好后重跑即出图）；不影响编译/测试/审查门禁 |
+| 产物 | `docs/images/引用关系图.*` | 文件级 + 模块级 `.svg`/`.dot`/`.json`（随工具提交入库）；PNG 仅本地预览（`docs/images/*.png` 已 gitignore） |
+
+```powershell
+winget install Graphviz.Graphviz
+& 'tools\refgraph\gen_refgraph.bat'    # → docs/images/引用关系图.*（.dot/.svg/.png/.json）+ 生成报告
+```
+
+> 图例、语义（文本层引用/未解析归外部）、更新流程与已知限制见 `docs/架构设计/引用关系图说明.md`。
+> Keil 工程包含路径解析自 `MDK-ARM/*.uvprojx`（自动跟随）；模拟器包含路径变化需同步脚本 `SIM_INCLUDE_DIRS`。
+
+### 2.9 开发机一次性搭建（分步安装命令）
+
+以下命令在 PowerShell 中直接执行（新机器从零搭建，全程约 1~2 小时），逐步对照文末清单打勾。
+
+**第 1 步：git**
+
+```powershell
+winget install Git.Git
+```
+
+> 手动下载：https://git-scm.com/download/win （Git for Windows）
+
+**第 2 步：Keil MDK-ARM v5 + STM32CubeMX**（GUI 安装，无命令行方式）
+
+- 下载页：<https://www.keil.com/arm/mdk.htm>（MDK-ARM v5.x；90 天评估 license 可先开发；必须含 **ARMCC v5** 编译器——工程锁 `uAC6=0`，armclang 不行）
+- **安装目录设为 `C:\Keil_v5`**（`build.bat` / `download.bat` 的 `UV4=` 行硬编码该路径；装别处就改这两个 bat）
+- 装完打开 **Pack Installer** → 安装 `Keil::CMSIS` 和 `Keil::STM32F4xx_DFP`（提供 STM32F407ZGTx 设备 + `STM32F4xx_1024.FLM` Flash 算法；pack 源 https://www.keil.com/pack/ ，Pack Installer 自动拉取）——**必装，否则烧录失败**（FLM 从 pack 目录解析，不在仓库）
+- **License**：首次启动 UV4 自动生成 90 天评估 license（长期使用需购买正式 license；license 绑定机器、不在仓库）
+- **STM32CubeMX 6.17.0**：下载页 https://www.st.com/en/tools/stm32cubemx.html （直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe ）
+  - 用途：打开仓库 `STM32F407-Demo.ioc` → 改外设/引脚/时钟 → 生成代码（仅重写 CubeMX 区域，**USER CODE 区域保留**）
+  - 固件包须 **STM32Cube FW_F4 V1.28.3**（与仓库 HAL 驱动一致；若未随附，在 CubeMX `帮助 → 管理` 下载对应包）
+  - ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，**勿随意用最新版**
+
+**第 3 步：VS（2019/2022/2026 任一）+ CMake**（模拟器工具链）
+
+```powershell
+winget install Kitware.CMake        # ≥3.15
+```
+
+- VS 版本不固定：构建入口 `simulator\build_sim.bat` 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可
+- 新装选 VS2019 的注意：Community 已下架主站，从**存档页**下载：<https://visualstudio.microsoft.com/zh-hans/vs/archives/>（直链：<https://aka.ms/vs/16/release/vs_community.exe>）；装 VS2022/VS2026 走主站下载
+  - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾对应 **Windows 10/11 SDK**
+- **SDL2 无需系统安装**（用预编译 SDK），但**不在仓库**——`simulator/SDL2/` 被 gitignore，`git clone` 后本地没有；目录不存在时按下面步骤补一次
+
+  **补 SDL2 SDK（仅当 `simulator/SDL2/` 缺失）**
+
+  ```powershell
+  # 1) 下载官方 2.32.10 VC 预编译包（GitHub Releases，约 7 MB）
+  New-Item -ItemType Directory -Force simulator\SDL2 | Out-Null
+  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+  Invoke-WebRequest -Uri "https://github.com/libsdl-org/SDL/releases/download/release-2.32.10/SDL2-devel-2.32.10-VC.zip" `
+      -OutFile simulator\SDL2\SDL2-devel-2.32.10-VC.zip -UseBasicParsing
+
+  # 2) 解压到 simulator/SDL2/；顶层目录名须为 SDL2-2.32.10
+  #    （若解压出 SDL2-devel-2.32.10/，改名为 SDL2-2.32.10/）
+  Expand-Archive simulator\SDL2\SDL2-devel-2.32.10-VC.zip -DestinationPath simulator\SDL2 -Force
+
+  # 3) 头文件复制到 include/SDL2/ 子目录（必做：LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
+  $inc = "simulator\SDL2\SDL2-2.32.10\include"
+  New-Item -ItemType Directory -Path "$inc\SDL2" -Force | Out-Null
+  Copy-Item "$inc\*.h" "$inc\SDL2\"
+
+  # 4) 校验 5 个必备文件（全 True = 就绪），然后删 zip
+  foreach ($f in @("include\SDL.h", "include\SDL2\SDL.h", "lib\x64\SDL2.lib",
+                   "lib\x64\SDL2main.lib", "lib\x64\SDL2.dll")) {
+      "{0} : {1}" -f $f, (Test-Path "simulator\SDL2\SDL2-2.32.10\$f")
+  }
+  Remove-Item simulator\SDL2\SDL2-devel-2.32.10-VC.zip
+  ```
+
+  目标目录结构：
+
+  ```
+  simulator/SDL2/SDL2-2.32.10/
+  ├── include/            ← SDL.h 及各头文件
+  │   └── SDL2/           ← 头文件副本（第 3 步；缺它编译报 C1083: cannot open include file "SDL2/SDL.h"）
+  └── lib/x64/            ← SDL2.lib / SDL2main.lib / SDL2.dll（构建与运行均从此取）
+  ```
+
+  > 内网机器连不上 GitHub：在任一台有网的机器下载 zip（release 页：<https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10>）拷过去，再走上面第 2~4 步。
+
+**第 4 步：Python**（`.venv` 脚本工具链）
+
+```powershell
+winget install Python.Python.3.12   # 或任一 ≥3.10；手动：https://www.python.org/downloads/windows/
+# 仓库根目录建 venv（种子解释器用刚装的 python 即可）
+python -m venv .venv
+& '.venv\Scripts\python.exe' -m pip install -r requirements.txt
+```
+
+> `python` 不可用时改用完整路径 `& "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe" -m venv .venv`。
+> `requirements.txt` 必须保持**纯 ASCII**；之后一切依赖第三方库的脚本只用 `.venv\Scripts\python.exe`。
+
+**第 5 步：Node.js + 字体工具**
+
+```powershell
+winget install OpenJS.NodeJS.LTS     # 手动：https://nodejs.org/ （选 LTS）
+npm i -g lv_font_conv                # 手动：https://www.npmjs.com/package/lv_font_conv
+```
+
+**第 6 步：pre-commit + cppcheck**（提交门禁）
+
+```powershell
+winget install astral-sh.uv
+uv tool install pre-commit
+winget install cppcheck             # 2.21.0 → C:\Program Files\Cppcheck
+# ★ 重开终端（PATH 才生效），然后：
+pre-commit install
+pre-commit run --all-files          # 首次全库基线扫描
+```
+
+> 手动下载：uv → https://astral.sh/uv/ （一行安装 `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`）· pre-commit → https://pre-commit.com/ · cppcheck 2.21.0 → https://github.com/CppQA/cppcheck/releases （2.21.0 tag 的 Windows x64 zip，解压至 `C:\Program Files\Cppcheck` 并加入 PATH）
+
+**第 7 步：Python 串口助手**（串口调试 / 自动测试，仓库内置）
+
+无需单独安装：`tools/serial_tool/` 随仓库提供，依赖 `pyserial`（已入 `requirements.txt`，第 4 步建 `.venv` 时一并安装）。建成后验证：
+
+```powershell
+& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py selftest   # → SELFTEST PASS
+& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py ports      # 枚举 COM 口
+```
+
+**第 8 步：下载器驱动**（ST-Link）
+
+- ST 官网下载 **STM32CubeProgrammer** 运行一次（自动安装 ST-Link USB 驱动）：https://www.st.com/en/development-tools/stm32cubeprog.html
+- 仅需要 ST-Link V2 驱动时：https://www.st.com/en/development-tools/stm321025.html （`ST-LinkV2-USB-Driver` 包）
+- Keil `Options for Target → Debug` 确认驱动与实物一致（工程已配 UL2CM3 框架）
+
+**第 9 步：串口配置**
+
+```powershell
+& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py ports   # 查 COM 号
+```
+
+把查到的端口写入 `.opencode\serial_config.json` 的 `portName`（唯一配置源，换口只改这里）。
+
+**第 10 步：冒烟验证**（全过 = 环境就绪）
+
+```powershell
+& "MDK-ARM\build.bat"                                            # → BUILD_OK: 0 errors, 0 warnings
+& "simulator\build_sim.bat"                                      # 模拟器一键构建（自动探测 VS 版本），0 警告
+.\simulator\build\Debug\lvgl_sim.exe                             # 出 160×160 单色菜单画面
+& '.venv\Scripts\python.exe' simulator\tests\check_menu_rows.py           # PASS
+& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update  # 首次生成参考图
+& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py       # 再跑 → PASS
+& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py selftest     # → SELFTEST PASS
+pre-commit run --all-files
+```
+
+**搭建清单汇总**（随步骤逐项打勾）：
+
+- [ ] Windows 10/11 x64 + PowerShell 5.1+
+- [ ] Keil MDK-ARM v5.x 装到 `C:\Keil_v5\`（或已同步修改两个 bat）+ CMSIS / STM32F4 DFP 包
+- [ ] STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
+- [ ] VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本）
+- [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH
+- [ ] 建 `.venv` 并 `pip install -r requirements.txt`
+- [ ] `npm i -g lv_font_conv`
+- [ ] 写好 `.opencode/serial_config.json`（本机 COM 口），`serial_tool selftest` PASS
+- [ ] 下载器（ST-Link 等）USB 驱动已装，Keil `Options for Target → Debug` 驱动一致
+- [ ] 第 10 步冒烟验证全部通过
+- [ ] （可选）Graphviz 已装（引用关系图渲染：`winget install Graphviz.Graphviz`，见 §2.8）
+
+### 2.10 手动下载来源速查
+
+§2.9 中需下载组件的官方下载地址汇总（正文的 winget / 命令行方式优先；网络受限时按本表手动下载）：
+
+| 组件 | 官方下载页 | 版本 / 说明 |
+|---|---|---|
+| Git for Windows | https://git-scm.com/download/win | 最新稳定版 |
+| Keil MDK-ARM | https://www.keil.com/arm/mdk.htm | v5.x，须含 ARMCC v5；安装目录 `C:\Keil_v5` |
+| CMSIS / STM32F4xx DFP | https://www.keil.com/pack/ | 在 Keil Pack Installer 内装 `Keil::CMSIS`、`Keil::STM32F4xx_DFP` |
+| STM32CubeMX | https://www.st.com/en/tools/stm32cubemx.html | 6.17.0（与 .ioc 一致）；直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe |
+| STM32Cube FW_F4（固件包） | https://www.st.com/en/embedded-software/stm32cube-f4.html | V1.28.3（与仓库 HAL 驱动一致） |
+| Visual Studio 2019 | https://visualstudio.microsoft.com/zh-hans/vs/archives/ | 直链：https://aka.ms/vs/16/release/vs_community.exe |
+| CMake | https://cmake.org/download/ | ≥ 3.15 |
+| Python | https://www.python.org/downloads/windows/ | ≥ 3.10，推荐 3.12 |
+| Node.js | https://nodejs.org/ | LTS |
+| lv_font_conv | https://www.npmjs.com/package/lv_font_conv | 一般 `npm i -g lv_font_conv` |
+| uv | https://astral.sh/uv/ | `powershell -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
+| pre-commit | https://pre-commit.com/ | 一般 `uv tool install pre-commit` |
+| cppcheck | https://github.com/CppQA/cppcheck/releases | 2.21.0 的 Windows x64 zip（`cppcheck-2.21.0-windows-x64.zip` 形式），解压入 PATH |
+| STM32CubeProgrammer | https://www.st.com/en/development-tools/stm32cubeprog.html | 含 ST-Link USB 驱动 |
+| ST-Link V2 驱动 | https://www.st.com/en/development-tools/stm321025.html | `ST-LinkV2-USB-Driver` 包 |
+| SDL2（仅仓库预编译库缺失时） | https://github.com/libsdl-org/SDL/releases | 2.32.10，一般不需要 |
+| Graphviz | https://graphviz.org/download/ | 一般 `winget install Graphviz.Graphviz`；未装时引用关系图工具跳过渲染（§2.8），不阻塞其他工具链 |
+
+> 获取渠道优先级：① `winget`（自动校验、免手动）→ ② 上表官方页 → ③ 网络受限时自行选可信镜像；
+> Keil / ST 官网访问受限时可走代理。
+
+---
+
+## 三、目标板环境（DTU 硬件）
+
+### 3.1 主芯片
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| MCU | STM32F407ZGTx | Cortex-M4（双精度 FPU / TrustZone），LQFP144 |
+| 主频 | 168 MHz | HSE 8 MHz → PLL M=4 / N=168 / P=2（`Inc/stm32f4xx_hal_conf.h`） |
+| Flash | 1 MB（0x08000000） | 片内 |
+| SRAM | 192 KB（128 KB 主 + 64 KB CCM） | 当前仅用主 SRAM 128 KB；SRAM3/CCM 未映射（§3.3） |
+| RTOS | FreeRTOS V10.3.1（CMSIS-RTOS V2） | HAL 时基 TIM7，tick = 1 ms；NVIC 4 位抢占，外设中断优先级 ≥5 |
+
+### 3.2 外设硬件要求（引脚级）
+
+| 外设 | 接口 | 引脚 | 备注 |
+|---|---|---|---|
+| CH395F 以太网 | SPI2 | PB12 CS / PB13 SCK / PB14 SDO / PB15 SDI | PHY 强制 100M 全双工；SPI 分频系数必须为 8（PCB 设计约束，速度受限） |
+| GD5F2GQ5UE NAND（2 Gbit） | SPI1 | PE0 CS / PB3 SCK / PB4 MISO / PB5 MOSI / PB8 WP / PE1 HOLD | FatFS（FAT32）+ dhara FTL；上电无卷自动 `f_mkfs` |
+| TPAFE5160 ADC | 并行 16 位 | PG0~PG15 数据 / PD3 RD / PD4 CONVST / PD7 BUSY | `APP_ADC_ENABLE` 开关 |
+| USART1（调试串口） | UART | PA9 TX / PA10 RX | 115200 8N1；printf 日志 + `@test` 采集通道 |
+| UART5（RS-485） | UART | PC12 TX / PD2 RX / PD0 DE | 半双工；`APP_RS485_ENABLE` 开关 |
+| 状态 LED ×6 | GPIO | PC4 / PC5 / PB1 / PB2 / PF11 / PF12 | **低电平点亮** |
+
+### 3.3 资源预算（部署红线）
+
+实测（2026-09-11 快照口径，现汇总于 `docs/内存管理/RAM使用分析与优化方案.md`）：
+
+| 资源 | 已用 | 总量 | 利用率 | 余量 | 红线说明 |
+|---|---|---|---|---|---|
+| Flash | 232,000 B（226.6 KB） | 1 MB | 22.1% | ~798 KB | 充裕 |
+| 主 SRAM（静态区+堆） | 125,104 B（122.2 KB） | 128 KB | **95.4%** | **5.8 KB** | **极度紧张**：新增任何静态缓冲/任务栈前必须先核算 RAM 余量 |
+
+- LVGL 内存池 40 KB（静态占用）；FreeRTOS 堆 48 KB
+- 任务栈预算（words，1 word = 4 B）：
+
+| 任务 | 栈大小 | 优先级 |
+|---|---|---|
+| defaultTask | 2048 | Normal |
+| netTask | 4096 | Normal |
+| ftpTask | 4096 | Normal |
+| testTask | 4096 | BelowNormal |
+| uiTask | 16384 | BelowNormal |
+| timeSyncTask | 2048 | Normal |
+
+> 挖潜方向（未实施）：SRAM3 64 KB / CCM 64 KB 未映射——详见 `docs/内存管理/`。
+> 部署侧含义：**不要做任何需要额外 RAM 的固件定制**，新增功能先过内存预算。
+
+### 3.4 下载与调试
+
+| 项 | 说明 |
+|---|---|
+| 下载方式 | `& "MDK-ARM\download.bat"`（Keil 命令行：烧写 + Reset & Run） |
+| 下载器 | 工程已配 `UL2CM3` 调试驱动 + `STM32F4xx_1024` Flash 算法；**物理下载器按现场选择**（本机为 ST-Link——不占 COM 口，可与串口调试并存）；新机器在 Keil `Options for Target → Debug → Settings` 选择与硬件一致的驱动 |
+| 调试日志 | USART1 115200；抓开机日志必须**先武装采集再复位**（`test/run_boot_test.py --flash-cmd` 已保证顺序） |
+
+### 3.5 功能配置开关
+
+| 开关 | 位置 | 当前值 | 说明 |
+|---|---|---|---|
+| `APP_NET_ENABLE` | `App/app_cfg.h` | 开 | 网络（CH395F + 全部 TCP 服务） |
+| `APP_ADC_ENABLE` | 同上 | 开 | TPAFE5160 采样 |
+| `APP_RS485_ENABLE` | 同上 | 开 | RS-485 通信 |
+| `TEST_SUITE_*` | `test/test_config.h` | 全注释（产品构建） | 测试套件**互斥**：一次构建只开一个（CH395F / 存储 / GD5F / RTC）；全注释 = 正常产品固件 |
+
+---
+
+## 四、网络与现场部署
+
+### 4.1 网络参数
+
+| 参数 | 工厂默认 | 修改方式 |
+|---|---|---|
+| IP | **192.168.1.100**（静态，无 DHCP） | 屏幕 `通讯参数 → 网口设置`（修改密码 `123`）保存后**立即生效**（网络重建约 1~3 s）；或预置 `/config.ini`（INI；旧版 `/cfg/netcfg.bin` 首启自动迁移） |
+| 子网掩码 | 255.255.255.0（/24） | 同上 |
+| 默认网关 | 192.168.1.1 | 同上 |
+| MAC | 全零 = 芯片内置 MAC | 同上（全零是"使用芯片内置 MAC"的哨兵，不是"MAC 为 0"） |
+| PHY | 强制 100M 全双工 | 固件固定，不可配 |
+
+- 配置持久化：NAND 上通用配置文件 `/config.ini`（INI `[network]` 段；缺失/损坏回退工厂默认并重建模板，不带崩网络）
+- 立即生效机制：保存 → netTask 重建网络 → 代次号递增 → 三个 TCP 服务自动重建监听（**既有连接会断开**，属预期）
+
+### 4.2 服务端口（现场连通性核对）
+
+| 服务 | 协议/端口 | 用途 | 核对方法 |
+|---|---|---|---|
+| 远程显示（RemoDispBus） | TCP **7003** | 远端看图（160×160 1bpp，3200 B/帧，客户端 LCDMEM 拉取）+ 远端导航按键 | DTU-RemoteLCD 或任意 TCP 客户端连 7003 收帧 |
+| 墙钟对时 | TCP **8888** | PC 主动推送时间到设备 | 对时推送后核对设备时间 / 日志时间戳 |
+| FTP | TCP **21** | 文件上传/下载（根目录 `/`，NAND 存储） | 任意 FTP 客户端列目录/读写 |
+
+> 现场组网要求：设备与客户端**同网段**（默认 .100/24、网关 .1）；跨网段部署先按 §4.1 改 IP 再上线。
+
+### 4.3 存储与运行时
+
+- 文件系统：FatFS（FAT32）挂 NAND；**上电无卷自动格式化**（`f_mkfs`）；格式化会清除卷上全部文件（含网口配置 `/config.ini`）
+- RTC：SD2506 芯片（驱动 `Drivers/BSP/SD2506/`）提供墙钟基准与日志时间戳；首次使用建议先经 8888 对时
+- 启动时序：`app_main_init`（存储 → 时钟 → RS485 → NAND → ADC → 启动转换）→ 就绪屏障（STORAGE / NET / FTP / TIMESYNC 事件）→ 六任务运行；详见 `docs/架构设计/项目启动顺序管理.md`、`docs/架构设计/项目架构总览.md`
+
+### 4.4 现场验收清单
+
+| # | 项目 | 方法 | 通过标准 |
+|---|---|---|---|
+| 1 | 上电自启动 | 断电上电 + 串口采集 | `@test` PASS：Required `App init OK;Network Init;net init: OK;PHY: 100M FULL`，无 `FAIL/ERROR/HardFault` |
+| 2 | 网络连通 | PC ping 192.168.1.100 | 通（PHY 100M FULL） |
+| 3 | 远程显示 | DTU-RemoteLCD 连 7003 | 出图（160×160 1bpp）+ 远端菜单导航可用 |
+| 4 | FTP | FTP 客户端连 :21 | 列目录 / 读写 `/` 下文件 |
+| 5 | UI 功能 | 屏幕 / 远端操作 | 菜单 7 项导航、内容页、密码（查看 `000` / 修改 `123`）、网口设置保存后立即生效 |
+| 6 | 对时 | PC 推送 8888 | 设备墙钟更新、日志时间戳正确 |
+| 7 | 掉电保持 | 写文件 / 改网口配置 → 重启 | 数据仍在（`/config.ini` 按新值生效） |
+| 8 | LED 状态 | 目检 | 6 路 LED 随系统状态变化（低电平点亮） |
+
+---
+
+## 五、远端客户端环境
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| 操作系统 | 任意（Windows / Linux / macOS，有浏览器或 Python 即可） | 与设备同网段 |
+| 远程显示客户端 | **DTU-RemoteLCD**（独立项目：Flask + WebSocket 参考实现）或任意符合 RemoDispBus 协议的 TCP 客户端 | 连设备 **TCP 7003**；协议见 `docs/UI设计/RemoDispBus协议与接收设计说明.md` |
+| 对时工具 | 任意可 TCP 推送的工具/脚本 | 向设备 **8888** 推送 |
+| FTP 客户端 | 任意（资源管理器 / FileZilla 等） | 设备端 lftpd，端口 21 |
+| 浏览器 | Chrome / Edge | 查看参考客户端 Web 页；开发期浏览文档 SVG 图 |
+
+> 客户端侧**无强制版本依赖**——协议是纯 TCP 字节流（`[TAG][CMD][LEN][DATA][CRC]` 帧），
+> 任何语言均可实现；单连接模型（同一时刻一个客户端）。
+
+---
+
+## 六、常见环境问题速查
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| `build.bat` 找不到 UV4 / 闪退 | Keil 未装在 `C:\Keil_v5\` | 装到该路径，或改 `build.bat` / `download.bat` 的 `UV4=` 行 |
+| Keil 编译报编译器不识别 | 新装 MDK 只有 armclang | 工程锁 `uAC6=0`，必须用带 **ARMCC v5** 的 MDK v5.x |
+| CubeMX 再生成后出现大量 diff / 新告警 | 用了比工程记录更新的 CubeMX / 固件包版本 | 用 git 还原生成文件，按 **.ioc 记录的 CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3** 重新生成 |
+| CMake 配置失败：找不到生成器 | 本机 VS 大版本与生成器不匹配 | 统一走 `simulator\build_sim.bat`（自动探测 VS 版本选生成器）；手动 cmake 时 `-G` 号须与本机 VS 一致（16=2019 / 17=2022 / 18=2026） |
+| 模拟器构建报 `SDL2/SDL.h` 找不到 | `simulator/SDL2/` SDK 缺失（不入库）或头文件副本没做 | 按第 3 步"补 SDL2 SDK"完整走一遍（下载 → 解压 → 头文件复制到 `include/SDL2/` → 5 文件校验） |
+| `.venv` 不存在 / 脚本 ModuleNotFound | venv 未建（不入库） | 按 §2.4 重建 + `pip install -r requirements.txt` |
+| pip 装依赖报 UnicodeDecodeError | `requirements.txt` 含中文注释 | 保持该文件**纯 ASCII**（pip 按 GBK 代码页解码） |
+| 字体生成 / 转 PNG 报缺模块 | 误用 PATH 里的 msys64 python | 一律用 `.venv\Scripts\python.exe` |
+| 内容页回归 exit 2（参考缺失） | `tests/ref/` 是本地生成物、不入库 | 先 `check_content_pages.py --update` 生成参考，再跑回归 |
+| 串口采集不到 / 端口占用 | COM 号变化 / 上一进程未释放 | 改 `.opencode/serial_config.json`；`serial_tool.py ports` 查实际端口，`open` 占用 ≤1s 报 `port busy` |
+| 烧录失败 | 下载器未选 / USB 驱动缺失 | Keil `Options for Target → Debug` 选对驱动；安装下载器 USB 驱动 |
+| 下载报 Flash 算法 / FLM 文件找不到 | 未安装 `Keil::STM32F4xx_DFP` pack（FLM 来自 pack 目录，不在仓库） | Pack Installer 安装该 pack 后重新下载 |
+| UV4 启动弹 license 窗口 / 无法编译 | 90 天评估 license 过期或未激活 | `Options for Target → License` 查看/输入；长期使用购买正式 license |
+| 提交被钩子拦截 | cppcheck / 规范 / 乱码 / gitlint 任一失败 | 按 pre-commit 输出逐项修复；**禁止** `--no-verify` 跳过门禁 |
+| 改代码后"没生效" | 新 `.c` 漏双端注册 / 模拟器缓存 | 走 `new-source-file` 双端注册流程；`cmake --build` 增量或删 `simulator/build/` 重建 |
+
+---
+
+## 七、相关文档
+
+| 主题 | 文档 |
+|---|---|
+| 项目全景架构 | `docs/架构设计/项目架构总览.md` |
+| 启动顺序 / 就绪屏障 | `docs/架构设计/项目启动顺序管理.md` |
+| 内存预算详析 / 优化方案 / 栈观测 | `docs/内存管理/RAM使用分析与优化方案.md`（主文档）· `docs/内存管理/内存内容分配策略.md`（区域与 DMA 规则） |
+| 网口配置 / 生效链路 | `docs/子系统设计/网络配置说明.md` |
+| 远程显示协议 | `docs/UI设计/RemoDispBus协议与接收设计说明.md` |
+| LVGL 模拟器部署 | `docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` |
+| 串口调试 / 自动化测试 | `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md` |
+| pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` |
+| 引用关系图（文件引用） | `docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8） |
+| 各模块测试指南 | `docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` |
+| 已知硬件陷阱 | `docs/问题记录/CH395F_Trap_Records.md` 等 |
+
+---
+
+## 变更记录
+
+| 日期 | 变更 |
+|---|---|
+| 2026-09-21 | 更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"**随仓库提供**/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正 |
+| 2026-09-21 | 模拟器构建改为自适应：新增 `simulator/build_sim.bat/.ps1`（vswhere 自动探测本机 VS 大版本 → 生成器 16=2019 / 17=2022 / 18=2026；`build/` 生成器不符自动删除重建，删除带重试抗文件锁）；VS 版本不再固定，2019/2022/2026 兼容：总览图、§2.3、第 3 步、第 10 步冒烟、搭建清单、速查表同步更新 |
+| 2026-09-16 | 补 Graphviz（引用关系图渲染，可选）：新增 §2.8，原 §2.8/§2.9 顺延为 §2.9/§2.10（章节内步骤号不变）；总览图、搭建清单、§2.10 下载表、相关文档各补一项 |
+| 2026-09-13 | 初版：汇总开发机（Keil / VS2019+SDL2 / Python venv / 字体 / 串口工具 / pre-commit）、目标板（引脚 / 资源预算 / 下载 / 功能开关）、网络现场部署（默认参数 / 端口 / 验收清单）、远端客户端四类环境要求，附一次性搭建清单（含分步安装命令与冒烟验证）与常见环境问题速查 |
+| 2026-09-13 | §2.8 各组件补手动下载网址；新增 §2.9 手动下载来源速查表 |
+| 2026-09-15 | 串口调试/自动测试工具由 serial-mcp-server 切换为仓库内置 Python 串口助手（serial_tool，.venv + pyserial，免安装）：§2.4 依赖清单、§2.6、§2.8 第 7/9/10 步、搭建清单、§2.9 下载表（去 Rust/serial-mcp-server）、速查表、相关文档同步 |
+| 2026-09-13 | 补 STM32CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3（与 .ioc 一致）：拓扑图 / §2.2 / 第 2 步 / §2.9 / 搭建清单，常见问题速查增加再生成版本不匹配条目 |
+| 2026-09-13 | 新增"Keil 初始化配置（机器侧项，非项目自带）"：license / Device Pack（含 FLM 来源解析路径）/ 下载器驱动，并列出项目自带免配置项；§六 速查补 FLM 缺失、license 过期两条 |
+| 2026-09-13 | 补 RAM/Flash 链接布局说明：手动 scatter 文件 `STM32F407-Demo.sct`（在仓库）为链接依据（128KB = SRAM1+SRAM2，SRAM3/CCM 未映射），新机器无需重设、勿改 GUI Target 页 |