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_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/）

以下生成器共享同一套约定（§3.2），均为纯标准库拼 SVG：

脚本	产物（入库）	顶部数据区（改这里 → 重跑）
gen_arch_svg.py	docs/images/项目架构总览.svg	LAYERS / ROWS / FOOT
gen_barrier_svg.py	docs/images/就绪屏障.svg	BITS / PRODUCERS / CONSUMERS
gen_frame_svg.py	docs/images/RemoDispBus帧格式.svg	FIELDS / TITLE / SUB / FOOT
gen_storage_stack_svg.py	docs/images/存储栈分层.svg	L_* / ROWS / TITLE / SUB / FOOT
gen_partition_svg.py	docs/images/物理分区布局.svg	FIELDS / TITLE / SUB / FOOT（MB 计量）
gen_net_pending_svg.py	docs/images/Net层阻塞模型.svg	CALLER_STEPS / LOOP_STEPS / PHASES
gen_cfg_arch_svg.py	docs/images/配置文件分层架构.svg	配置引擎分层
gen_net_stack_svg.py	docs/images/BSD网络栈分层.svg	BSD 网络栈分层
gen_memory_svg.py	docs/images/内存布局_*.svg	RAM / FLASH 布局
gen_watchdog_svg.py	docs/images/看门狗心跳模型.svg	TASKS / REQ_BITS / POLL_STEPS / TIMELINE
gen_adc_frontend_svg.py	docs/images/ADC前端电路.svg	SUB1 / NOTE_* 等文案常量 + 面板坐标（电路拓扑固定，网表变了才重画）
gen_adc_code_scale_svg.py	docs/images/ADC码值刻度.svg	PANELS 列表（码范围 / LSB / 实测码标记位置）+ FOOT（换芯片才重画）

---

三、绘制流程

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，确认文字不溢出盒外、框 / 线 / 标签对齐、配色正确。

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 的查看器需要位图时再转 PNG：

• 最简单：浏览器打开 .svg → 截图 / 另存为图片。
• 脚本化：给 .venv 装 cairosvg 后转（scale=2 提高清晰度）：

  & '.venv\Scripts\python.exe' -m pip install cairosvg
  & '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/RemoDispBus帧格式.svg', write_to='remo.png', scale=2)"
  

PNG 属本地派生物、不入库（与 simulator/tests/ref/*.png 目检图一致，.gitignore 已含 *.png；注意该目录下作为像素黄金参考的 .bin 是入库的，别顺手一起忽略掉）。

---

五、检查清单（提交前）

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

---

六、变更记录

日期	变更
2026-09-11	创建：统一图形绘制流程（选型 / SVG 生成器 / Mermaid / 约定 / 检查清单）；新增 tools/arch_diagram/gen_frame_svg.py（通用协议帧图）+ docs/images/RemoDispBus帧格式.svg
2026-09-11	新增专门配图目录 docs/images/：收拢 docs/ 根与 docs/UI设计/images/ 下 5 张 SVG；同步更新 3 个生成器 OUT 路径、4 处文档图片引用、AGENTS.md 与 .gitignore（PNG 预览规则）；流程沉淀为 draw-diagram skill
2026-09-11	存量 ASCII 框图清理：STM32F4-Base存储架构说明.md 两图（存储栈分层 / 物理分区布局）重绘为 SVG（生成器家族新增 gen_storage_stack_svg.py / gen_partition_svg.py）；RemoDispBus协议与接收设计说明.md 删 ASCII 帧图（SVG 帧格式图已在，信息无损失）；测试说明/CH395F_Test_Guide.md 4 图（2 组件架构 + 2 会话时序）转 Mermaid
2026-10-22	澄清 §派生物一句：simulator/tests/ref/ 下作为像素黄金参考的 .bin 已入库，只有派生的 .png 目检图仍不入库（原表述把两者混为"参考图不入库"，会诱导后来者把整个目录继续忽略掉）
2026-10-27	新增 gen_adc_frontend_svg.py → docs/images/ADC前端电路.svg：把 docs/硬件平台/ADC通道映射说明.md §7.1 与 docs/测试说明/ADC前端注入验证流程.md §2 的 ASCII 拓扑图换成 SVG。ASCII 版把滤波支路画成挂在信号节点下的一根竖线，读起来像 2:1 分压——恰是要否掉的结论；SVG 把 ADC7 / ADC7_GND 画成两个节点并加 STM32 侧对照面板。生成器沿用 §3.2 约定（纯标准库 / html.escape / newline="\n" / ElementTree 自检 + 文字溢出预检）；目检用无头 Chrome 截图完成（cairosvg 未装，截图不入库）
2026-10-27	新增 gen_adc_code_scale_svg.py → docs/images/ADC码值刻度.svg：给 docs/测试说明/ADC前端注入验证流程.md §4 的「码」定义配图。两张刻度尺上下对照，标出 11430 码 ≈ 1.744 V（TPAFE）与 1000 码 ≈ 0.806 V（STM32），把"同一整数在两片转换器上代表不同电压"变成可见的，避免台架抄数时混用两套 LSB