STM32F4-Base/docs/架构设计/图形绘制流程.md

图形绘制流程（SVG / Mermaid）

范围：本仓库文档（docs/）里的技术配图——协议帧 / 字节布局、分层架构、依赖 / 就绪屏障、流程 / 时序 / 状态机等。 目标：统一绘图方法与工具链，保证图形精确、可复现、可 diff、可过 pre-commit，并与既有 tools/arch_diagram/ 生成器一致。 沉淀：本流程已沉淀为 draw-diagram skill（.dsh/skills/draw-diagram/SKILL.md）——画图时直接加载该 skill 即可。 产物目录：生成的 .svg 统一放 docs/images/（专门配图目录，产物入库）。

---

一、选型：什么图用什么工具

图形类型	工具	说明
协议帧 / 字节布局（精确比例）	SVG（gen_frame_svg.py）	字段宽须严格 ∝ 字节数 + 逐字段标注 + 偏移标尺
闪存 / 内存分区布局（精确比例）	SVG（gen_partition_svg.py）	帧图生成器的 MB 计量副本（分区宽 ∝ MB 数 + 偏移标尺）
端到端链路鸟瞰（一条数据走到底）	SVG（gen_arch_endtoend_svg.py）	42 框 37 边、长边各占一条独占通道；标签白片必须落在框间通道内，否则被后画的节点吃掉半字 → 判据见 draw-diagram skill §三b
分层架构 / 模块依赖	SVG（gen_arch_svg.py）	多节点跨层依赖，Mermaid 会画成"意大利面"，手工排布更清晰；单层单职责的栈图用其副本 gen_storage_stack_svg.py
就绪屏障 / 生产者-消费者	SVG（gen_barrier_svg.py）	三栏对齐 + 正交连线，避免交叉
流程图 / 时序 / 状态机 / ER	Mermaid（Markdown 内嵌）	拓扑关系类图，节点少、强调连接；渲染器原生支持
UI 界面 / 像素级样机	simulator/ 截图	非本流程范围

为什么"精确布局图"用 SVG，不用 Mermaid / HTML：

维度	SVG	Mermaid	HTML
字段宽 ∝ 字节数	✅ 像素精确定位	❌ 盒子按文本自适应	⚠️ 可但繁琐
连续字节流（无假箭头）	✅ 分段矩形	❌ 自动加有向边	✅
纯文本（可 diff / lint / pre-commit）	✅	✅（代码块）	⚠️
直接是图片（免截图）	✅	⚠️ 需渲染器	❌ 需截图
矢量无损（任意 DPI）	✅	✅（渲染后）	⚠️
依赖	无（浏览器用系统字体渲染）	渲染器	浏览器

结论：要精确像素 / 比例的布局图 → SVG 生成器；只表达拓扑关系的图 → Mermaid。

---

二、既有工具（tools/arch_diagram/）

tools/arch_diagram/ 下的 26 个生成器共享同一套约定（§3.2），均为纯标准库拼 SVG。逐脚本 / 逐图的 清单不在本文——2026-10-30 起并成一张，落 tools/arch_diagram/README.md「产物清单」：32 张入库 docs/images/*.svg 逐张列出「谁生成它 / 它答什么问题 / 改哪段数据能重跑 / 被哪篇文档内嵌」，本文一度 另立一张三列表，结果两张表各自漏登记（README 漏 5 个、本文漏 9 个，2026-10-30 实测），同一条事实两处 登记必然漂移 → 现只留一处，本文只讲怎么选、怎么画、怎么审。

• 要新增一张精确布局图：先到那张表按主题找最接近的生成器照抄骨架（draw-diagram skill §二）， 落库时同批把行加进那张表（不往本文加）。
• 要挑工具（SVG 还是 Mermaid 还是截图）：看本文 §一 的选型表与维度对比表——那是判据，不是清单， 与逐脚本清单不重复。

2.1 钩子扫不到的图：refgraph 产物与历史手画稿

generated-fresh 的 docs-svg 条目只把 tools/arch_diagram/gen_*.py 拷进临时目录重跑逐字节比对。 本目录生成器不产的那四张图（引用关系图.svg、引用关系图_模块.svg、级联框总览.svg、 级联框几何计算.svg）全都不在这条钩子的扫描面里——改了不会有任何人报警，这就是「42 个节点的旧图 挂在 43 个节点的标题下」能一路活到今天的原因。四张图的产物、出处与挂载逐张列在 **tools/arch_diagram/README.md「产物清单」**末尾两组，本文不再重复登记；只留维护口径：

• refgraph 两张（tools/refgraph/gen_refgraph.py，graphviz，命名不在 gen_*.py 面内）：改了代码引用 就跑 & 'tools\refgraph\gen_refgraph.bat' 重生成，svg 与改动同一笔提交，别只更新 .dot； 口径 → docs/架构设计/引用关系图说明.md。
• 级联框两张：手工 SVG、无生成器（git log --follow 实测 2026-09-08 891c9ef0 入库、2026-09-11 2429955d 随配图规范收拢进 docs/images/，此后未再改动；本文此前写的绘制日期与 git 史不符，已按 git 改）。 只作显示几何示意，不承载菜单树事实——树的结构 / 层级 / 绑页走 docs/images/菜单树总览.svg（有生成器）；坐标公式变了要重算重画，别在 SVG 上描字。

新增精确布局图一律走 tools/arch_diagram/gen_*.py（docs-svg 条目自动发现，不必登记基线）；上面这两组 是这套纪律的例外面，再多一张先说清为什么不能用生成器。

---

三、绘制流程

3.1 精确布局图（协议帧 / 架构 / 依赖）——用生成器

1. 挑脚本：协议帧 → gen_frame_svg.py；分层架构 → gen_arch_svg.py；就绪屏障 → gen_barrier_svg.py。

2. 改数据：编辑脚本顶部数据区。配色沿用既有调色板：

   语义	主色	底色
   蓝	#2563eb	#eff6ff
   青	#0d9488	#f0fdfa
   绿	#16a34a	#f0fdf4
   琥珀	#d97706	#fffbeb
   紫	#7c3aed	#f5f3ff
   灰	#475569	#f1f5f9
   玫红	#e11d48	#fff1f2

3. 重跑（仓库根目录；纯标准库，任意 python3，统一用 .venv 亦可）：

   & '.venv\Scripts\python.exe' tools/arch_diagram/gen_frame_svg.py
   

   成功输出 OK <字节> bytes, canvas <W>x<H> -> <路径>。脚本内置 ElementTree.fromstring 自检——XML 不合法会直接抛错，不会产出坏图。

4. 目检：小图浏览器直接打开 docs/images/*.svg；要留证或回读细节，走本文 §四 的 headless 浏览器截图 （渲染命令只在那一节详述）。确认文字不溢出盒外、框 / 线 / 标签对齐、配色正确。 ≥20 边的大图另跑解析式碰撞审计 → draw-diagram skill §三b（压半格这种问题眼睛看不出来）。

5. 引用：在对应 .md 里用相对路径：根目录下的 md 指向 docs/images/ 下的图（形如 ![帧格式](images/RemoDispBus帧格式.svg)）；docs/UI设计/ 等子目录的 md 则写 ../images/ 前缀的等价写法。

6. 提交：脚本（源）+ 生成的 .svg（产物）一起提交（产物入库，类比生成物 ui_menu_tab.c）。

3.2 SVG 约定（手写 / 新增生成器时遵循）

• 纯标准库：只用 html / os（+ 需要时 math）拼 SVG 字符串；不引第三方库（SVG 由浏览器用系统字体渲染，无需 Pillow / 字体文件）。
• 文本转义：所有文本经 html.escape(s, quote=True)（& < > " ' → 实体），防止破坏 XML。
• 字体：根 <svg font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">（系统字体栈，Win / mac 通用）。
• 文本宽估算（自适应盒宽时）：text_w(s, fs)——CJK / 全角 / 圈码 / 箭头 ≈ 1.0em，其余 ≈ 0.58em（宁大勿小，防溢出）。
• 落盘：open(OUT, "w", encoding="utf-8", newline="\n")（UTF-8 无 BOM + LF，符合仓库编码铁律）。
• 自检：写盘后 xml.etree.ElementTree.fromstring(svg)。
• 产物位置：docs/images/（专门配图目录；引用它的 .md 用相对路径指向）。
• 命名：docs/images/<主题>.svg（可与同名 .md 对应，如 images/RemoDispBus帧格式.svg ↔ RemoDispBus协议与接收设计说明.md §1.2）。

3.3 拓扑类图（流程 / 时序 / 状态机）——用 Mermaid

在 Markdown 里直接写 ```mermaid 代码块（GitHub 与多数渲染器原生渲染，无需生成图片）：

```mermaid
sequenceDiagram
    participant C as 客户端
    participant S as 服务端
    C->>S: LCDMEM 取帧
    S-->>C: 1bpp 位图（3200 B）
```

常用：flowchart（流程 / 框图）、sequenceDiagram（时序）、stateDiagram-v2（状态机）、erDiagram（实体关系）。

⚠️ Mermaid 盒子宽度自适应、会自动连线，只适合"关系"类图；凡需精确像素 / 比例的布局图（协议帧、分层框）一律走 §3.1 的 SVG 生成器。

---

四、SVG → PNG（可选）

默认交付 SVG（矢量、可缩放、可 diff、可过门禁）。需要位图（留证、回读细节、贴进不渲染 SVG 的 查看器）时，用本机实测可用的 headless 浏览器渲染：

# Edge / Chrome 都不在 PATH 上，按全路径调用（本机实测两者都在；换机先核这两个路径在不在，
# Chrome 的那条是 C:\Program Files\Google\Chrome\Application\chrome.exe）。
# --screenshot 必须给绝对 Windows 路径：相对路径报 `Failed to write file …(0x3)` 且 PNG 压根不落盘。
# --window-size 要跟 SVG 画布一致：忘了改会截出大片空白或裁掉底部脚注。
& 'C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe' --headless --disable-gpu `
  --hide-scrollbars --window-size=<W>,<H> --virtual-time-budget=10000 `
  --screenshot="$env:TEMP\preview.png" "file:///<仓库根绝对路径，正斜杠>/docs/images/RemoDispBus帧格式.svg"

别照旧写法装 cairosvg：.venv 里没装（ModuleNotFoundError）、requirements.txt 里也没有， rsvg-convert / inkscape / magick 这台机器上都不存在（2026-10-30 实测）。真要引入是动 requirements.txt 的决定（第三方依赖统一进那里；另注意门禁 entry 的裸 python 不等于 .venv → AGENTS.md「Python 环境」），不是画图这一步的隐含前置。零工具兜底仍是「浏览器双击打开 .svg 用眼看」， 但半格压框这类问题靠眼看不出来。

PNG 属本地派生物、不入库：忽略规则是 .gitignore 里针对目录的三条——docs/images/*.png（:132）、 simulator/shot*.png（:106）、simulator/tests/ref/*.png（:127），不是一条全库 *.png。 另注意 simulator/tests/ref/ 下作为像素黄金参考的 .bin 是入库的，别顺手一起忽略掉。

---

五、检查清单（提交前）

• 生成器输出 OK … bytes（无异常 = XML 合法）。
• 目检（小图浏览器打开；要留证走 §四 的 headless 截图）：文字不溢出、框 / 线 / 标签对齐、配色符合调色板。
• 引用它的 .md 里图片相对路径正确（能显示）。
• 脚本 + 产物 .svg 一并暂存（产物入库）。
• pre-commit run --files <脚本> <svg> <md> 全过（无乱码 / 行尾空白 / 编码 OK）。