wandering1
6ffbb7d5b5
§8 开头插「六轮速查卡」：3x2 面板，每轮注入信号缩略图数据驱动
（正弦 / 同峰值方波三角 / UA·UN 异相 / 扫频 / 负半周钉 0 / 谐波叠
加），一卡给接法、判据一句话、主读数出口，先立轮廓再进执行卡。
§8.5 插「为什么连取 10 行取中位数」概念图：左栏机理（定宽 20 拍
窗逐窗滑动 → 读数拍频跳），右栏操作（中位数 / 平均 / 真值三线
错位对照 + 毛刺行标注）——取数口径 4e4d597e 刚定，此图补原理。
§8.3 / §8.5 各加一张 Mermaid：接线拓扑（端接高阻、万用表并接、
单点共地、STM32 五路仅削顶轮支线）；单轮执行主干（采集链与偏差
两级决策、分诊虚线回环，汇于关输出填表）。
新增生成器 gen_ac_rounds_svg.py / gen_ac_median_svg.py（纯标准库、
OVERFLOW 预检归零、generated-fresh 自动在册），README 补两行台账。
验证：两产物连跑两次 sha1 不变；check_generated_fresh rc=0 无
DIFF / NEW、漂移基线不增；mermaid-syntax 2 围栏新发 0；headless
Chrome 截图回读三轮，修掉两类只有渲染才暴露的真错（正文 x 在卡
循环外算导致第 2、3 列叠进第 1 列；三角波闭式值域 −2..4 画越界
尖峰）。六文件 BOM / CR / U+FFFD 均零。
注：当前 check_doc_links --all 报 27 处，全属并发会话在改的产品
需求三份文档，与本笔无关、未触碰。
48 lines
3.3 KiB
Markdown
48 lines
3.3 KiB
Markdown
# 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_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` — 配图规范、选型与检查清单
|