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

# 项目部署环境要求

> 版本：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/>串口调试/自动测试]
        U[MSVC (VS2022 生成工具)<br/>主机侧单元测试 cl.exe]
        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.1.1 本地工具路径环境变量（`DTU_*` 系列，新机器必配项见下表）

仓库脚本**不含本机绝对工具路径**：Keil / ST-LINK / pre-commit Python / MSVC / Windows SDK /
Graphviz / Cppcheck 的安装位置差异一律用 `DTU_*` 环境变量表达（完整契约与解析语义见
`docs/环境与部署/本地工具路径环境变量方案.md`）。新机器装完工具后按表配置：

| 变量 | 必需性 | 值的形态 | 使用方 |
|---|---|---|---|
| `DTU_KEIL_UV4` | **必需**（MCU 构建机） | UV4.exe 完整路径 | `keil_build.py`（`@build`） |
| `DTU_STLINK_CLI` | **必需**（用 ST-LINK CLI 的机器；已在 PATH 可不设） | ST-LINK_CLI.exe 完整路径 | `stlink_flash.py`（烧录/复位/回读） |
| `DTU_PRECOMMIT_PYTHON` | 可选（pre-commit 不在 `.venv`/当前解释器时设；CI runner 建议必设） | 装有 pre-commit 的 python.exe 完整路径 | `scripts/ci_local.py`、CI L0/L0.5 |
| `DTU_CPPCHECK` | 可选（开发机入 PATH 即可；无 PATH 的 CI runner 建议设） | cppcheck.exe 完整路径 | pre-commit cppcheck 钩子、CI L0 |
| `DTU_MSVC_CL` | 可选（VS 标准位置时自动探测） | x64 `cl.exe` 完整路径 | 主机侧单测、CI L0.5 |
| `DTU_WINDOWS_KITS_ROOT` | 可选（SDK 标准位置时自动探测） | `Windows Kits\10` 根目录 | 主机侧单测 |
| `DTU_VSWHERE` | 可选（VS 标准位置时由 `%ProgramFiles(x86)%` 自动推导） | vswhere.exe 完整路径 | `simulator/build_sim.ps1` |
| `DTU_GRAPHVIZ_DOT` | 可选（PATH 可发现时不设） | dot.exe 完整路径 | `tools/refgraph` 渲染 |

```powershell
# 用户级设置（无需管理员；★ 设完必须重开终端/IDE 才生效）
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4',   'D:\Tools\Keil\UV4\UV4.exe', 'User')      # 示例路径
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', 'D:\Tools\STLink\ST-LINK_CLI.exe', 'User') # 示例路径
# 其余可选项按实际安装位置补充；验证：$env:DTU_KEIL_UV4 后 Test-Path / 跑对应命令
```

> 统一解析语义：变量**显式设置但无效 → 立即报错**（指出变量名与收到的路径），不静默回退到别的安装；
> 未设置 → 按工具走 PATH / 标准布局自动发现（可选工具允许降级，如 Graphviz 缺失只跳渲染）。
> CI runner 以 **SYSTEM 服务**运行，用户级变量对其不可见——runner 用**机器级**变量注入（见
> `docs/CI/远程CI完整指南.md` §4.1.3）。

### 2.2 MCU 构建工具链（必需）

| 项 | 要求 | 说明 |
|---|---|---|
| Keil MDK-ARM | **v5.x**（须含 ARMCC v5 编译器） | 工程锁定 `uAC6=0`（仅 ARMCC v5，**不支持 armclang**）；仅支持此工具链，无其他工具链 |
| 安装路径 | **任意目录** | `keil_build.py` / `stlink_flash.py` 经 `DTU_*` 环境变量解析工具路径（§2.1.1）；新机器装完后设置 `DTU_KEIL_UV4` / `DTU_STLINK_CLI` 即可，**无需修改仓库脚本** |
| 设备支持 | 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** |
| 命令行构建 | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（即 `@build`） | 退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt` |
| 命令行烧录 | `& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py flash`（即 `@download`） | 烧后 `-Rst -Run`；判据 `Programming Complete` + 回读 `No difference found` |

> ⚠ **版本一致性关键**：.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::STM32F4xx_DFP`（pack 源 https://www.keil.com/pack/ ） | 工程引用的 **Flash 算法 `STM32F4xx_1024.FLM` 就来自此 pack**（.uvoptx 的 `$$Device:STM32F407ZGTx$` 变量解析到 pack 目录 `<Keil安装目录>\PACK\Keil\STM32F4xx_DFP\<ver>\CMSIS\Flash\`，如 `C:\Keil_v5\...`）；**pack 缺失则下载失败**。`Keil::CMSIS` pack **不需要**：核心头文件由仓库 `Drivers/CMSIS/` 提供，`.uvprojx` 只引用 DFP pack（2026-10-02 本机实测：未装 CMSIS pack 构建 0/0 通过；且 keil.com 的 CMSIS pack 直链（5.7.0~6.1.0）均已下架 404，无从安装） |
| 下载器驱动 | 工程已配 **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 侧编译环境（模拟器 + 主机侧单元测试，必需）

> ⚠ 本节涵盖**两类都要 MSVC 的 PC 侧构建**：① LVGL 模拟器（C++，产物 `lvgl_sim.exe`）；
> ② 主机侧单元测试（C，批量离线编译**真实生产源码**，见 §2.10 与
> `docs/测试说明/看门狗单元测试说明.md`）。两者共用同一套 VS 安装，**无需装两次**。

| 项 | 要求 | 说明 |
|---|---|---|
| CMake | ≥ 3.15 | 本机实测 4.3.0-rc1；**仅模拟器需要**，单元测试不用 CMake |
| 编译器 | **VS2019 / 2022 / 2026 任一**（C++ x64 工作负载） | `build_sim.ps1` 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
| **MSVC C 工具链** | **同上（`cl.exe`）** | **主机侧单元测试的必需项**：`test/host/<模块>/run_unit_test.py` 用 `cl.exe` 离线编译真实源码。**只要装了 VS 就有**（`VC\Tools\MSVC\<ver>\bin\Hostx64\x64\cl.exe`），不额外装东西 |
| Windows SDK | 10.0.19041 及以上 | CMake 配置与 `cl.exe` 编译（`stdio.h` 等）都从这里取；随 VS 工作负载勾选安装 |
| 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）

# 主机侧单元测试（示例：看门狗判定状态机；纯逻辑、零硬件、秒级）
& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py   # 退出码 0=PASS / 1=FAIL / 2=环境错误
```

> 模拟器与 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`、`pre-commit==4.6.2` | 清单 = 仓库根 `requirements.txt`（**必须保持纯 ASCII**：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError）；`pre-commit` 入 `.venv` 后，重建 venv 即可直接跑 L0 门禁（`scripts/ci_local.py` 自动选用） |
| 入库情况 | `.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 串口助手 | `.dsh/skills/serial-assistant/scripts/serial_tool.py`（仓库内置，.venv + pyserial） | 常驻 daemon + 薄 CLI + 全量日志文件；无需单独安装，`pip install -r requirements.txt` 即就绪 |
| 调试串口 | USART1（PA9 TX / PA10 RX），115200 8N1 | **端口单一配置源 `.serialtest/config.json`**（本机 COM6）；换端口只改这个文件 |
| 一键测试 | `.dsh/skills/serial-boot-test/scripts/run_boot_test.py`（即 `@test`，`& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py`） | 开串口 + 清日志 → 烧录 → wait-idle（静默 8s/超时 30s）→ 提取 → 标记校验；默认端口取 `.serialtest/config.json` / 115200，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法错误 |

> 采集 = 端口常开 + daemon 全量日志（`.dsh/skills/serial-assistant/scripts/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，纯标准库） |
| **MSVC `cl.exe`** | **装了 VS 即有（§2.3）** | **`watchdog-unit-test` 钩子必需**：改 `App/util/task_watchdog.*` 或 `test/host/watchdog/**` 时触发，用 `cl.exe` 离线编译真实源码跑单测。**未装 VS 时该钩子报环境错误（退出码 2）→ 拦截提交** |
| 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`。
>
> ⚠ **新增 L0.5 单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"**：
> 只要装了 VS（§2.3）就自动具备，无需额外安装；但**完全未装 VS 的机器在改动看门狗相关文件时会被钩子拦截**。

### 2.8 引用关系图渲染（Graphviz，可选）

| 项 | 要求 | 说明 |
|---|---|---|
| Graphviz | `winget install Graphviz.Graphviz`（本机实测 16.1.0） | `tools/refgraph` 引用关系图生成器的渲染引擎；`dot` 从 **PATH** 查找（winget 安装自动入 PATH）；非标准安装目录用 `DTU_GRAPHVIZ_DOT` 指向 `dot.exe`（§2.1.1） |
| 必需性 | **可选** | 未装时工具自动跳过渲染（仍产出 `.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 不行）
- **安装目录任意**（装完设置 `DTU_KEIL_UV4` = UV4.exe 完整路径，§2.1.1；默认安装位置即可）
- 装完打开 **Pack Installer** → 安装 `Keil::STM32F4xx_DFP`（提供 STM32F407ZGTx 设备 + `STM32F4xx_1024.FLM` Flash 算法；pack 源 https://www.keil.com/pack/ ，Pack Installer 自动拉取）——**必装，否则烧录失败**（FLM 从 pack 目录解析，不在仓库）。`Keil::CMSIS` pack 不需要：核心头文件由仓库 `Drivers/CMSIS/` 提供（`.uvprojx` 只引用 DFP pack；CMSIS pack 已被 keil.com 下架，2026-10-02 实测各版本直链均 404）
- **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**（模拟器工具链 **+ 主机侧单元测试编译器 MSVC**）

```powershell
winget install Kitware.CMake        # ≥3.15（仅模拟器用；单元测试不用 CMake）
```

- VS 版本不固定：构建入口 `simulator\build_sim.bat` 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可
- **这一个 VS 同时提供两样东西**：① 模拟器的 C++ 工具链 + CMake 生成器；② **主机侧单元测试的 `cl.exe`**（§2.3 / §2.10）——装一次即可，**不需要为单测另装编译器**
- 新装选 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**（**`cl.exe` 编 `stdio.h` 等标准头也依赖此处安装的 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（安装位置任意；入 PATH 或用 DTU_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，解压至任意目录并加入 PATH，或用 `DTU_CPPCHECK` 指向 `cppcheck.exe`）

**第 7 步：Python 串口助手**（串口调试 / 自动测试，仓库内置）

无需单独安装：`.dsh/skills/serial-assistant/` 随仓库提供，依赖 `pyserial`（已入 `requirements.txt`，第 4 步建 `.venv` 时一并安装）。建成后验证：

```powershell
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\serial_tool.py selftest   # → SELFTEST PASS
& '.venv\Scripts\python.exe' .dsh\skills\serial-assistant\scripts\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' .dsh\skills\serial-assistant\scripts\serial_tool.py ports   # 查 COM 号
```

把查到的端口写入 `.serialtest\config.json` 的 `portName`（唯一配置源，换口只改这里）。

**第 10 步：冒烟验证**（全过 = 环境就绪；前置：§2.1.1 的 `DTU_*` 变量已设置——未设时构建脚本会明确报出缺哪个变量及设置方法）

```powershell
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # → 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' .dsh\skills\serial-assistant\scripts\serial_tool.py selftest     # → SELFTEST PASS
& '.venv\Scripts\python.exe' test\host\watchdog\run_unit_test.py            # 主机侧单测 → 39/39 PASSED（退出码 0）
pre-commit run --all-files
```

**搭建清单汇总**（随步骤逐项打勾）：

- [ ] Windows 10/11 x64 + PowerShell 5.1+
- [ ] Keil MDK-ARM v5.x 已装（任意目录，`DTU_KEIL_UV4` 已设 UV4.exe 完整路径，§2.1.1）+ STM32F4 DFP 包（CMSIS pack 不需要，见 §2.2）
- [ ] STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
- [ ] VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本；**同一 VS 提供主机侧单测所需的 `cl.exe`**，见 §2.3 / §2.10）
- [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH
- [ ] 建 `.venv` 并 `pip install -r requirements.txt`
- [ ] `npm i -g lv_font_conv`
- [ ] 写好 `.serialtest/config.json`（本机 COM 口），`serial_tool selftest` PASS
- [ ] 下载器（ST-Link 等）USB 驱动已装，Keil `Options for Target → Debug` 驱动一致
- [ ] 第 10 步冒烟验证全部通过（含 `test/host/watchdog/run_unit_test.py` → PASSED）
- [ ] （可选）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；安装目录任意（`DTU_KEIL_UV4` 设 UV4.exe 完整路径） |
| STM32F4xx DFP | https://www.keil.com/pack/ | 在 Keil Pack Installer 内装 `Keil::STM32F4xx_DFP`（CMSIS pack 不需要/已下架，见 §2.2） |
| 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 |
| Visual Studio 2022 / 2026 | https://visualstudio.microsoft.com/zh-hans/downloads/ | 任一版本均可（模拟器构建 + 主机侧单测 `cl.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 官网访问受限时可走代理。

### 2.11 CI runner 环境（Gitea Actions，2026-10-01 T-6）

CI 跑 **L0 静态门禁 + L0.5 主机侧单测**（**不含 L1/L2/L3**——需真机 + ST-LINK，只在本地）。
workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测试说明/测试开发标准流程.md`](../测试说明/测试开发标准流程.md) §9。

| 项 | 要求 | 说明 |
|---|---|---|
| Gitea 版本 | ≥ 1.21（实测远程 **1.25.4**） | workflow 置于 `.gitea/workflows/`，兼容 GitHub Actions 语法 |
| Actions 开关 | 实例 `[actions] ENABLED = true` | site admin 配置；未开启则 push 不触发任何 job |
| runner OS | **Windows**（`runs-on: windows`） | labels 须含 `windows`；与开发机同平台，避免脚本语法分叉 |
| runner 软件 | Python 3.x、cppcheck、pre-commit、**MSVC**（VS C++ 工具链 + Windows SDK） | 前三个缺 → `l0-gates` **硬失败**（`::error::`）；MSVC 缺 → `l05-host-unit-tests` **降级跳过并告警**（不硬失败，但等于 L0.5 裸奔）。runner 以 SYSTEM 服务运行，**用户级 PATH/变量不可见**：自动发现失败时用**机器级** `DTU_PRECOMMIT_PYTHON` / `DTU_CPPCHECK` / `DTU_MSVC_CL` 注入（见 `docs/CI/远程CI完整指南.md` §4.1.3） |
| Keil | **不需要** | 刻意不跑 `@build`（需授权）；`.map` 缺失时 `mem-numbers` 钩子自动跳过 |
| `mem-numbers` | 有 `.map` 就跑，无则 `SKIP` | Keil 构建产物 `.map` 已 gitignore；自建带 Keil 的 runner 会照常跑该钩子 |

**runner 就绪前的过渡**：CI 只是"多一道网"，**不能替代本地门禁**。提交前仍须在本地跑：

```powershell
& '.venv\Scripts\python.exe' scripts/ci_local.py    # 与 CI 同一套判定（L0 + L0.5）
```

### 2.12 跨机验证（第二台机器 / 换机验收清单）

验收判据（对应 `本地工具路径环境变量方案.md` 的最终验收）：新电脑只按 §2.1.1 配置本机
`DTU_*` 变量，clone 仓库后**不修改任何 `.bat/.py/.ps1/.yml` 中的本机路径**即可运行开发命令。
工具安装清单同 §2.9 第 1~8 步（**刻意指定与旧机不同的安装目录**，才能真正验证跨路径）；
按下表顺序执行，任一步不达预期即停下排查。

**第 1 步：配置变量 + sanity check**

```powershell
# 用户级（无需管理员）；值填本机实际安装路径
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4',   '<本机 UV4.exe 完整路径>', 'User')
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', '<本机 ST-LINK_CLI.exe 完整路径>', 'User')
# ★ 关闭并重开终端（旧终端持有设置前的环境快照——最常见的"假失败"来源）
# 重开后验证：
Test-Path $env:DTU_KEIL_UV4     # True
Test-Path $env:DTU_STLINK_CLI   # True
```

**第 2 步：验证链**（每步有明确期望；①②③④ 全过 = 该机器验证通过）

| # | 命令 | 期望 | 失败诊断 |
|---|---|---|---|
| ① | `& <任一 python> -m venv .venv` + `& '.venv\Scripts\python.exe' -m pip install -r requirements.txt` | 安装完成且含 pre-commit | pip 报 GBK 解码错 = `requirements.txt` 被污染（该文件必须纯 ASCII，不该发生） |
| ② | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` | `BUILD_OK: 0 errors, 0 warnings`，exit 0 | 报错行**直接指出变量名**（如 `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: ...`）——照报错修值；新机器首次启动 UV4 需 license（90 天评估），缺 Device Pack 则下载失败（构建不受影响） |
| ③ | `& '.venv\Scripts\python.exe' scripts/ci_local.py` | L0 全钩子 Passed + L0.5 单测断言全部通过（当前 278 条），exit 0 | "找不到 MSVC" = VS 未装或装到非标准位置（设 `DTU_MSVC_CL` 可验证覆盖通道） |
| ④ | `& 'tools\refgraph\gen_refgraph.bat'` → `git status` | 重生成后 `docs/images/` **无 diff**（图内容只依赖源码，与本机工具链无关） | 出现 diff = 异常，需查 |
| ⑤ | `& "simulator\build_sim.bat"` | 自动探测 VS → 生成器匹配 → 构建成功（2026-10-02 起模拟器构建可用：配置引擎重构的文件迁移已同步进 `simulator/CMakeLists.txt`） | 报 `Cannot find source file` / `C1083` = CMakeLists 与源码目录再次失步（查文件迁移记录），与 `DTU_*` 变量无关；"未探测到 VS" 见 §2.3 |
| ⑥ | （有 ST-LINK 硬件才执行）`& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py list` | 列出探针 SN | 只跑 `list`，**不烧录不复位**；无硬件跳过不扣分 |

**第 3 步：反向测试**（验证"显式值无效 = 硬报错、不静默回退"语义，约 1 分钟）

```powershell
$env:DTU_KEIL_UV4 = 'D:\NotExist\UV4.exe'   # 仅当前会话，不动用户级值
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
# 期望：BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: D:\NotExist\UV4.exe，exit 2
# 关键判定：没有回退去猜别的 Keil 安装，而是明确报错
# 测完重开终端即恢复（用户级值未动）
```

**通过判定**：①②③④ 全过 = 该机器验证通过（⑤ 的既有 CMake 问题、⑥ 无硬件跳过均不扣分）。
两台不同安装路径的机器都通过 = 环境变量方案的跨机验收闭环（方案阶段 C 出口标准）。

---

## 三、目标板环境（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_cfg.h` 的 `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 内存池 16 KB（静态占用，2026-10-15 由 40 KB 收缩）；FreeRTOS 堆 56 KB（CCM）
- 任务栈预算（words，1 word = 4 B）：

| 任务 | 栈大小 | 优先级 |
|---|---|---|
| defaultTask | 1024 | Normal |
| netTask | 960 | Normal |
| ftpTask | 1024 | Normal |
| testTask | 2048 | BelowNormal |
| uiTask | 4096 | BelowNormal |
| timeSyncTask | 512 | Normal |

> 上表由 `scripts/gen_task_table.py` 同源（唯一来源 `Src/freertos.c` / `.ioc` 的 `FREERTOS.Tasks01`）；
> 2026-10-10 栈整改**未改任何栈值**，靠削调用链达标（详见 `docs/内存管理/RAM使用分析与优化方案.md`）。

> 挖潜方向（未实施）：SRAM3 64 KB / CCM 64 KB 未映射——详见 `docs/内存管理/`。
> 部署侧含义：**不要做任何需要额外 RAM 的固件定制**，新增功能先过内存预算。

### 3.4 下载与调试

| 项 | 说明 |
|---|---|
| 下载方式 | `& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py flash`（ST-LINK_CLI：烧写 + Reset & Run） |
| 下载器 | 工程已配 `UL2CM3` 调试驱动 + `STM32F4xx_1024` Flash 算法；**物理下载器按现场选择**（本机为 ST-Link——不占 COM 口，可与串口调试并存）；新机器在 Keil `Options for Target → Debug → Settings` 选择与硬件一致的驱动 |
| 调试日志 | USART1 115200；抓开机日志必须**先武装采集再复位**（`.dsh/skills/serial-boot-test/scripts/run_boot_test.py --flash-cmd` 已保证顺序） |

### 3.5 功能配置开关

| 开关 | 位置 | 当前值 | 说明 |
|---|---|---|---|
| `APP_NET_ENABLE` / `APP_ADC_ENABLE` / `APP_RS485_ENABLE` | `App/app/app_cfg.h` | 全定义 | **未接线占位，不门控任何代码**（P2-12，2026-10-04 核实）：三个宏全库零消费点，各模块一律编译进产品；"能否裁剪"取决于产品定义（docs/任务规划/README.md §2 阶段 B0），落定后再接入真实门控。**不要把它们当开关** |
| `TEST_SUITE_*` | `test/board/test_config.h` | 全注释（产品构建） | 测试套件**互斥**：一次构建只开一个（CH395F / 存储 / GD5F / RTC）；全注释 = 正常产品固件 |

---

## 四、网络与现场部署

### 4.1 网络参数

| 参数 | 工厂默认 | 修改方式 |
|---|---|---|
| IP | **192.168.1.100**（静态，无 DHCP） | 屏幕 `通讯参数 → 网口设置`（修改密码 `123`）保存后**立即生效**（网络重建约 1~3 s）；或预置 `/config.ini`（INI；旧版 `/cfg/netcfg.bin` **不再读取**——存在则忽略、不迁移，配置回落工厂默认，2026-10-10 起） |
| 子网掩码 | 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]` 帧），
> 任何语言均可实现；单连接模型（同一时刻一个客户端）。

---

## 六、常见环境问题速查

| 现象 | 原因 | 处理 |
|---|---|---|
| `keil_build.py` 报 `DTU_KEIL_UV4` 未设/无效 | `DTU_KEIL_UV4` 未设置或指向错误路径（**设完变量须重开终端**） | 设置/修正 `DTU_KEIL_UV4` 为 UV4.exe 完整路径（§2.1.1），重开终端重试 |
| `stlink_flash.py` 报 `ST-LINK_CLI.exe not found` / `ENV_ERROR: DTU_STLINK_CLI` | `DTU_STLINK_CLI` 未设且不在 PATH，或显式值无效 | 设置 `DTU_STLINK_CLI` 为 ST-LINK_CLI.exe 完整路径，或把其目录加入 PATH；显式值无效时**不会**回退，须修值 |
| 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 文件校验） |
| **`run_unit_test.py` 退出码 2 / 报"找不到 MSVC cl.exe"** | 本机未装 VS（C++ 工作负载） | 按 §2.3 装 VS2019/2022/2026（勾"使用 C++ 的桌面开发"），装完即有 `cl.exe`；**提交看门狗相关改动时该钩子会拦截，必须装** |
| **`run_unit_test.py` 编译报 `C1083: 无法打开包括文件 "stdio.h"`** | VS 未勾选 Windows SDK，或 `cl.exe` 路径异常 | 在 VS Installer 里补勾 **Windows 10/11 SDK**；脚本已按本机 VS/SDK 目录自动拼 `INCLUDE`/`LIB`，无需手动 `vcvars64.bat`（其内部 `reg.exe` 在受限机器上会被安全策略拦截） |
| `.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 号变化 / 上一进程未释放 | 改 `.serialtest/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` |
| **测试分层 / L0.5 主机侧单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩） |
| **CI（Gitea Actions）** | `docs/CI/README.md`（**远程 CI 唯一入口**：服务端 / Runner 部署与保活 / workflow / 排障，**仅本机一台 runner，日常开发不必读**）· `docs/测试说明/测试开发标准流程.md` §9（覆盖边界） |
| 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-10-12 | **远程 CI 文档迁出本目录**：`CI配置指南.md` 与 `Gitea_Runner部署指南.md` 合并为 **`docs/CI/远程CI完整指南.md`**（入口 `docs/CI/README.md`），本文三处引用改指新路径与新章节号（§4.1.3 机器级变量、§7 相关文档登记）。原因：远程 CI 只涉及本机一台 runner，不应与"任何机器都要过"的部署核对清单混在一起 |
| 2026-10-10 | **删除旧档 NCFG 迁移**（升级/迁移口径变更）：旧固件遗留的 `/cfg/netcfg.bin` 不再"首启自动迁移"——旧档若存在则被忽略（不读、不删、不迁移），配置直接回落工厂默认（`/config.ini` `[network]` 段模板）。`net_cfg_legacy.c/h` 与 `cfg_store_legacy_path()` 已移除；携带旧档的设备升级后需经 UI 或 FTP 重新配置网口。§五 现场部署 IP 行同步 |
| 2026-10-02 | **模拟器构建修复**（配置引擎重构遗留）：`simulator/CMakeLists.txt` 的配置文件引擎引用同步到迁移后位置——包含目录 `App/`→`App/cfg/`（`cfg_file.h`/`cfg_file_store.h`）、源文件 `App/cfg_file.c`→`App/cfg/cfg_file.c`、包含目录 `test/`→`test/board/`（`test_config.h`/`net_latency_test.h`）；全量 include 离线核查无其他断链，模拟器全量构建恢复（`--cfgtest` 四场景 PASS，rc=0）。§2.12 验证链 ⑤ 行同步更新 |
| 2026-10-02 | 更正 Device Pack 必装范围：`Keil::CMSIS` pack 不再列为必装项——本工程不依赖它（核心头文件由仓库 `Drivers/CMSIS/` 提供，`.uvprojx` 只引用 DFP pack；2026-10-02 本机实测未装 CMSIS pack 构建 0/0 通过），且其 keil.com 直链（5.7.0~6.1.0）均已下架 404；必装的只有 `Keil::STM32F4xx_DFP`（3.1.1，与 `.uvprojx` PackID 一致）。§2.2 / 第 2 步 / 搭建清单 / §2.10 同步更正 |
| 2026-10-02 | 新增 §2.12「跨机验证（第二台机器 / 换机验收清单）」：变量配置 + sanity check → 六步验证链（含期望结果与失败诊断，含模拟器既有 CMake 问题标注）→ 反向 fail-fast 测试 → 通过判定，作为方案跨机验收的标准操作 |
| 2026-10-02 | **本地工具路径环境变量方案落地**（`本地工具路径环境变量方案.md`）：仓库脚本不再含本机绝对工具路径——10 处调用点（`build/download/reset.bat`、`_build.cmd` 退役、`ci_local.py`、`ci.yml`、`gen_refgraph.py`、`unit_test_harness.py`、`build_sim.ps1`、`make_font.py`）统一改为"`DTU_*` 变量优先 + 自动发现回退"（显式设置但无效 = 硬报错，不静默回退）；新增 §2.1.1 变量清单/设置方法/解析语义；Keil 安装路径、Graphviz、cppcheck、VS/SDK 自动探测、Python 重建示例与速查表同步改为变量口径；`requirements.txt` 增 `pre-commit`（重建 `.venv` 即可直接跑 L0 门禁）；本机已按 §2.1.1 配置用户级 `DTU_KEIL_UV4`/`DTU_STLINK_CLI` 并全链路验证（@build 0/0、ci_local L0+L0.5 全绿、refgraph 重生成、reset 探针识别） |
| 2026-10-02 | 新增 **`Gitea_Runner部署指南.md`**：针对**本机 Gitea 原生部署**（`D:\Docker\Gitea\gitea.exe` + Windows 服务 + `127.0.0.1:3001`）定制的 Runner 端全流程——下载 / `register`（**`--instance` 用回环、`--labels "windows:host"` 必须精确匹配 `runs-on`**）/ `config.yaml` / `daemon install` 常驻 / 软件与 PATH 坑 / MSVC 路径约束 / 内网 action 零依赖改法 / 排障表 / `check_env.ps1` 自检脚本；§七相关文档登记 |
| 2026-10-01 | 新增 **`CI配置指南.md`**（Gitea Actions 配置全流程：服务端 `[actions] ENABLED` / Windows runner 注册（`--labels "windows:host"`）/ runner 软件环境与 PATH / workflow 位置与触发 / 内网拉不到 `actions/checkout` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 |
| 2026-10-01 | **新增 §2.11 CI runner 环境（Gitea Actions，T-6）**：Gitea ≥1.21（实测 1.25.4）+ `[actions] ENABLED` + Windows runner（装 Python/cppcheck/pre-commit/MSVC）；**不需要 Keil**（刻意不跑 `@build`，无 `.map` 时 `mem-numbers` 自动跳过）；补"CI 不能替代本地门禁"与 `scripts/ci_local.py` 过渡命令 |
| 2026-10-01 | **补主机侧单元测试（L0.5）环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 |
| 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 页 |