From 2bed82471dd4edd420bfd991c0020e0adfcd4691 Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Wed, 16 Sep 2026 08:40:55 +0800
Subject: [PATCH] =?UTF-8?q?=E9=83=A8=E7=BD=B2=E7=8E=AF=E5=A2=83=E6=96=87?=
=?UTF-8?q?=E6=A1=A3=E8=A1=A5=20Graphviz=EF=BC=9A=E6=96=B0=E5=A2=9E=20?=
=?UTF-8?q?=C2=A72.8=20=E5=BC=95=E7=94=A8=E5=85=B3=E7=B3=BB=E5=9B=BE?=
=?UTF-8?q?=E6=B8=B2=E6=9F=93=EF=BC=88=E5=8F=AF=E9=80=89=EF=BC=89=EF=BC=8C?=
=?UTF-8?q?=E5=8E=9F=20=C2=A72.8/=C2=A72.9=20=E9=A1=BA=E5=BB=B6=EF=BC=8C?=
=?UTF-8?q?=E5=90=8C=E6=AD=A5=E4=B8=8B=E8=BD=BD=E8=A1=A8/=E6=B8=85?=
=?UTF-8?q?=E5=8D=95/=E7=9B=B8=E5=85=B3=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/项目部署环境要求.md | 27 ++++++++++++++++++++++++---
1 file changed, 24 insertions(+), 3 deletions(-)
diff --git a/docs/项目部署环境要求.md b/docs/项目部署环境要求.md
index aa34470c..f1997dd8 100644
--- a/docs/项目部署环境要求.md
+++ b/docs/项目部署环境要求.md
@@ -22,6 +22,7 @@ flowchart LR
S[CMake + VS2019
LVGL PC 模拟器]
P[Python .venv
字体/回归脚本]
T[Python 串口助手 serial_tool
串口调试/自动测试]
+ G[Graphviz
引用关系图渲染（可选）]
end
subgraph TGT["② 目标板（DTU 硬件）"]
M[STM32F407ZGTx @168MHz
1MB Flash / 192KB SRAM]
@@ -165,7 +166,23 @@ python tools/font_gen/extract_cn.py # 任意 python3：
> 检查范围仅项目自有代码；`Lib/`、`Middlewares/`、`Drivers/BSP/UI`、`lftpd`、`dhara`、`test/` 等被排除。
> 全库扫描：`pre-commit run --all-files`。详见 `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`。
-### 2.8 开发机一次性搭建（分步安装命令）
+### 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 小时），逐步对照文末清单打勾。
@@ -280,10 +297,11 @@ pre-commit run --all-files
- [ ] 写好 `.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.9 手动下载来源速查
+### 2.10 手动下载来源速查
-§2.8 中需下载组件的官方下载地址汇总（正文的 winget / 命令行方式优先；网络受限时按本表手动下载）：
+§2.9 中需下载组件的官方下载地址汇总（正文的 winget / 命令行方式优先；网络受限时按本表手动下载）：
| 组件 | 官方下载页 | 版本 / 说明 |
|---|---|---|
@@ -303,6 +321,7 @@ pre-commit run --all-files
| 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 官网访问受限时可走代理。
@@ -470,6 +489,7 @@ pre-commit run --all-files
| 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` 等 |
@@ -479,6 +499,7 @@ pre-commit run --all-files
| 日期 | 变更 |
|---|---|
+| 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）、速查表、相关文档同步 |