wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
a275539c1775d8278af3013402d9aa7289698be2
STM32F4-Base/docs/架构设计/图形绘制流程.md
T
wandering1 a38f862fb9 chore(ui-golden): 像素黄金参考 ref/*.bin 入库（把门禁改成可移植） 
问题：ui-golden 是逐字节比对（check_content_pages.py 里 data == refdata），
而基准 simulator/tests/ref/ 整目录被 .gitignore 忽略、从未入库。后果不是
"少几个文件"，而是这条门禁在任何新克隆 / 新并行工作树里必然报「缺黄金
参考」——只在有老副本的机器上它才是真的回归门禁。本会话已两次实测踩到
（并行工作树里只能现场 --update 造基准，而现场造出来的基准恰好失去意义）。

入库前先证明基线可复现，否则等于把一条天天误报的门禁写进仓库：
- 主树 ref/ 生成于 2026-10-11，其间合入 B6~B9 与 UI 令牌化等多次改动；
  今天用刚重建的 lvgl_sim 重跑 → 11 页 + 开页-关页往返池水位逐字节全过
- 主树与新工作树两份**独立构建**的 lvgl_sim（不同构建目录、不同绝对路径）
  各自生成基准 → 11 个 .bin 的 SHA-256 全部一致
即渲染是 CPU 侧确定性输出，可以当仓库内容。

改动：
- .gitignore：整目录忽略 → 只忽略派生的目检 PNG。另加一条
  !simulator/tests/ref/*.bin 反选——第 115 行的全仓 *.bin 兜底（挡
  sim_netcfg.bin 之类运行产物）会把基线一起挡掉，且反选必须排在它之后
  才生效
- 不引入 LFS：11 x 3200 B = 34.4 KB（160x160 单色打包）。走 LFS 反而新增
  失效面——没拉 LFS 的克隆会拿 pointer 文本去比像素，把"缺基准"换成
  "比不中"。.gitattributes 已有 *.bin binary，check-attr 确认 text unset，
  不会被行尾转换改写
- 基线不会被改写型钩子毁掉：trailing-whitespace / end-of-file-fixer 声明
  types: [text]，位图含 NUL 被判二进制 → 实测 Skipped；索引 blob、磁盘、
  主树参照三方哈希 11/11 一致
- 新增 11 个基线；同步 5 份文档与 3 处脚本口径：缺基准的提示从"首次/换机
  请加 --update"改为"检出不完整 → git checkout -- simulator/tests/ref/ 取回，
  不要用 --update 就地造基准"（旧提示正是自我实现型基准的来源）
- 顺带修掉 simulator/tests/README.md 两处与实现不符的描述：基准写成 PNG
  （实为 .bin）、regen_ref_png.py 写成"重建黄金参考"（它只出目检图，基准
  由 check_content_pages.py --update 刷）
- .pre-commit-config.yaml 只改注释（原文明确断言 ref/ "永远不会进 git
  索引"，已被本改动推翻）；ui-golden 的 files 面覆盖 simulator/tests/，
  基线被改即触发回归，刷参考从此在 git diff 里显形

历史口径按纪律冻结：UI_自动化测试流程 2026-09-10 的"整目录不入库"等 6 处
变更记录行不改写，以新行登记反转。

实测：@build 0 错 0 警（Code=213520，与内存台账一致）；ui-golden Passed；
pre-commit run --all-files = 36 Passed / 0 Failed（RC=0）。
2026-10-22 06:17:00 +08:00

9.2 KiB
Raw Blame History

图形绘制流程（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

三、绘制流程

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 目检图仍不入库（原表述把两者混为"参考图不入库"，会诱导后来者把整个目录继续忽略掉）
Reference in New Issue View Git Blame Copy Permalink