Files
STM32F4-Base/tools/arch_diagram/README.md
T
wandering1 045ca7f688 docs(配图): 端到端链路鸟瞰进生成器体系,补大图碰撞审计判据
把 archify 出的交互架构图落回仓内可复现形态,避免 docs/ 里出现「没有生成器的
SVG」:

- 新生成器 tools/arch_diagram/gen_arch_endtoend_svg.py → docs/images/架构总览_
  端到端链路.svg(42 框 / 37 边 / 5 条纵带,线型分数据·命令·屏障心跳三类);
  数据全部内嵌在 .py 里(generated-fresh 只把单个 gen_*.py 拷进临时目录重跑,
  外部 JSON 输入会 rc≠0 假红),SVG 内不含时间戳/commit/绝对路径
- docs/架构设计/项目架构总览.md 新增 §1.3 挂图并写清与 §1 分层图的分工
  (那张答「谁在哪一层」,这张答「一条数据走到底穿过谁」;纵带只是列分组,
  依赖方向仍以 §1.1 表与 layer-deps 门禁为准),版本 v1.2 → v1.3
- 两处生成器清单登记:tools/arch_diagram/README.md 脚本一览、
  docs/架构设计/图形绘制流程.md 的选型表与产物对照表
- draw-diagram skill 新增 §三b(大图碰撞审计判据 + 两条几何纪律)+
  reference/svg-collision-audit.py(拷进 ci-artifacts 用,刻意不进 tools/)

本窗实测(都已写进 skill):42 框 37 边的图缩略目检看着干净,解析式审计一眼
报出 23 条——边标签文字盒压到节点框会被后画的节点白底吃掉半个字(「串行执行」
渲染成「行执行」);根因是同行两框走了「同轴加一段走廊」的通用规则,产出退化
四点折线,把标签落点推到第一半中点。修法:同轴且已对齐直接返回两点线,标签
落点改按总弧长取 50%。

零余量第二遍(用生成器自己的 Box/route/label_at 真值扫,框不膨胀不内缩)又抓到
两处近失:「TRGO 触发」「帧 B 下发」与相邻框只剩 0.7px / 1.5px,缩成「TRGO」
「帧 B」后最紧余量升到 3.5px;同一遍还纠正了审计器自己的错——`hi > y0` 误写成
`hi > x0` 凭空报 3 条穿框,差点重排三条边的走线,所以判据里加了「先验审计器
本身再信 0 条」。

自查:连跑两次产物 sha1 不变;scripts/check_generated_fresh.py rc=0(25 生成器
/ 21 一致 / 4 在只减不增基线内);碰撞审计 rc=0(0 条);生成器无 OVERFLOW;
doc-links --sections-strict 逐篇 rc=0;mermaid-syntax / nested-comment /
skill-size / bom-drift 无新发;改动文件字节体检干净;/keil-build 0 错 0 警。
2026-10-30 15:59:24 +08:00

49 lines
3.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# tools/arch_diagram/ — 架构图 SVG 生成器
> 用 Python 脚本**精确生成**架构类 SVG 图(分层、内存布局、协议帧、屏障等),
> 产物放 `docs/images/`。用于"必须精确布局"的图;拓扑图(流程/时序/状态机)改用 Mermaid。
## 脚本一览
| 脚本 | 产物 | 用途 |
|---|---|---|
| `gen_arch_svg.py` | 架构分层图 | 六层分层结构 |
| `gen_memory_svg.py` | 内存布局图 | RAM / Flash 分区 |
| `gen_storage_stack_svg.py` | 存储栈图 | FTL / dhara / FatFs 三层栈 |
| `gen_net_stack_svg.py` | 网络栈图 | BSD 网络栈分层 |
| `gen_barrier_svg.py` | 就绪屏障图 | Event Flags 屏障模型 |
| `gen_frame_svg.py` | 协议帧格式图 | RemoDispBus 帧结构 |
| `gen_cfg_arch_svg.py` | 配置引擎架构图 | 配置分层与持久化 |
| `gen_partition_svg.py` | 分区图 | 存储分区 |
| `gen_watchdog_svg.py` | 看门狗心跳模型图 | IWDG + 任务心跳位图(置位→判定→喂狗 + 时间轴) |
| `gen_adc_frontend_svg.py` | ADC 前端电路图 | 端子 → 串阻 → 转换节点 → 转换器引脚;含差分负端与 STM32 侧对照 |
| `gen_adc_code_scale_svg.py` | ADC 码值刻度图 | 「码」的直观定义:两片转换器的刻度尺对照(16 位双极性 vs 12 位单极性) |
| `gen_arch_endtoend_svg.py` | 架构总览端到端链路图 | 端到端链路鸟瞰:片外硬件 → 驱动 → 算法 → 任务 → 落点 → 对外/同构端,42 框 37 边 5 条纵带;线型分数据 / 命令 / 屏障心跳三类,长边各占一条独占通道(与 §1 分层图分工:那张答「谁在哪一层」,这张答「一条数据走到底要穿过谁」) |
| `gen_data_trust_ladder_svg.py` | 数据可信台阶图 | 采集数据可信度的五级台阶:现在踩在哪一级、下一级挡什么 |
| `gen_data_trust_dc_ac_svg.py` | ADC 直流标定与交流验证图 | 上排直流注入链、下排信号发生器正弦验证,中间列只有正弦能证的六件事 |
| `gen_wave_record_flow_svg.py` | 故障录波数据流图 | 录波段数据的四个所有者与四条「不许」:谁独占写、谁只能读、标志怎么过界 |
| `gen_menu_tree_svg.py` | 菜单树总览图 | 43 节点的层级 / 绑页 / 密码门鸟瞰;内嵌 `ui_menu_tree.txt` 的节点行并与真值互验,防图与树漂移 |
| `gen_sample_ring_why_svg.py` | 采样环缓冲_为什么需要 | 上游 1 kHz 覆盖写只交最新一帧 vs 下游要 20 点滑窗:缺口 19 点与三个消费者 |
| `gen_sample_ring_layout_svg.py` | 采样环缓冲_环形布局 | 40 格环里哪 20 格是本窗、写指针指「下一格」、回绕与三条设计不变量 |
| `gen_sample_ring_start_svg.py` | 采样环缓冲_窗首下标 | 窗首 = head − n 的圆周走法,与「直接减 / 16 位回绕 / 先加 DEPTH」三种写法对照 |
| `gen_ac_rounds_svg.py` | 交流六轮速查 | 执行手册 §8 六轮总览卡:每轮注什么波形(正弦/方波三角/异相/扫频/削顶/谐波叠加缩略图)、判据一句话、主读数出口 |
| `gen_ac_median_svg.py` | 交流定数取中位数 | 「连取 10 行取中位数」的机理(全周窗滑动 → 读数拍频跳)与操作(中位数 vs 平均 vs 单行对真值)两栏数值示意 |
## 使用方式
```bash
& '.venv\Scripts\python.exe' tools/arch_diagram/gen_memory_svg.py
```
产物统一输出到 `docs/images/`;**脚本与生成的 `.svg` 一并提交**。
## ⚠️ 约定
- 颜色/字体遵循 `docs/架构设计/图形绘制流程.md` 的规范
- 中文用 SVG `<text>` 直接写(需注意字体族声明)
- 改图**改脚本再重跑**,不手改 SVG(保证可复现)
## 相关文档
- `docs/架构设计/图形绘制流程.md` — 配图规范、选型与检查清单