docs(配图): 生成器与产物清单并成一张唯一真值表,挂载列改由实测反推

两张清单各自登记同一批生成器,2026-10-30 实测各漏各的:
`tools/arch_diagram/README.md`「脚本一览」21 行缺 5 个(adc_health 三张、
net_instability、net_pending),`docs/架构设计/图形绘制流程.md` 的三列表 18 行
缺 9 个(多出的还在 `docs/架构设计/图形绘制流程.md` §2.1 另立一张表登记例外面)。
同一条事实两处登记必然漂,现并成一张:

- 唯一真值表 = `tools/arch_diagram/README.md`「产物清单」:按图逐行,32 张入库
  `docs/images/*.svg` 全量(26 个本目录生成器 + refgraph 2 张 + 无生成器的手工
  级联框 2 张),列 = 图 / 生成器 / 这张图答什么 / 顶部数据区(改这里 → 重跑)/
  挂在(`文档:行号`)。
- `docs/架构设计/图形绘制流程.md` §二 的逐脚本表换成指针(只留选型判据与流程),
  §2.1 保留「钩子扫不到的图」的维护口径、去掉与主表重复的表。
- 级联框两张的绘制日期按 `git log --follow` 改对:原写「2026-10-26 手画」与 git 史
  不符,实测 2026-09-08 `891c9ef0` 入库、2026-09-11 `2429955d` 随配图规范收拢进
  `docs/images/`,此后未再改动。
- `docs/门禁说明/generated-fresh.md` §8 旧口径「加生成器 = `GENS` 加一项」对
  `docs-svg` 不实:该条目声明 `dir` + `pattern = gen_*.py`,实跑 `glob.glob` 现扫
  (`scripts/check_generated_fresh.py`:146-150 与 :452)→ 新增生成器自动进扫描面,
  要同批改的是产物清单不是门禁。已拆成「加新类别」与「`docs-svg` 不必登记」两条。
- 「挂在」列由扫描 `![]()` 反推,并跳过 ``` 围栏与行内反引号里的示例写法——
  `docs/文档规范.md`:83、`draw-diagram` SKILL.md:155、本文档 §3.1 第 5 步
  那三处是教学示例、不是真挂载,先前手写表时误计进去过。
- 三张零内嵌图(`内存布局_RAM.svg`、`引用关系图.svg`、`引用关系图_模块.svg`)
  在表里明写「零内嵌」并给出被文字提到的位置。

`draw-diagram` skill 的落库义务同批改指:§二第 6 步与验证清单都指向「产物清单」,
并写明「全仓只此一张逐脚本清单」,避免下一个人再另起第二张。

自查:`check_doc_links.py --sections-strict` 三篇 rc=0;`check_generated_fresh.py`
PASS(26 生成器 / 22 一致 / 4 存量基线);`check_skill_size.py` 17 个 SKILL.md ok;
`check_mermaid.py --all` 31 文件 62 围栏新发 0;`check_bom_drift.py --all` 99 文件
无漂移;产物清单核对器(一次性,不入库)重写挂载列后复跑归零、再跑幂等。
纯文档与 skill 文案,未改任何生成器与代码,未 commit。
This commit is contained in:
2026-10-30 16:54:53 +08:00
parent 002e66d928
commit f48208f1c5
4 changed files with 99 additions and 59 deletions
+21 -28
View File
@@ -36,41 +36,34 @@
## 二、既有工具(`tools/arch_diagram/`)
以下生成器共享同一套约定(§3.2),均为**纯标准库**拼 SVG:
`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 实测),同一条事实两处
登记必然漂移 → 现只留一处,本文只讲**怎么选、怎么画、怎么审**。
| 脚本 | 产物(入库) | 顶部数据区(改这里 → 重跑) |
|---|---|---|
| `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_arch_endtoend_svg.py` | `docs/images/架构总览_端到端链路.svg` | `NODES`(id / 列 / 行 / 标题 / 副题)+ `EDGES`(出入框方位与 f / g / my / gx 旋钮)+ `BANDS` 纵带;三条独占通道 `CHAN_B` / `CHAN_78` / `CHAN_SLOTS` 与走廊 `GUT_C4C5` 落在几何区 |
| `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`(换芯片才重画) |
| `gen_data_trust_ladder_svg.py` | `docs/images/数据可信台阶.svg` | `STEPS` 五级台阶(状态 / 问题 / 依据)+ `BAND_LABEL_1` / `GATE_LABEL` / `FOOTNOTE`(台阶状态变了才重画) |
| `gen_data_trust_dc_ac_svg.py` | `docs/images/ADC直流标定与交流验证.svg` | `BOXES_A` / `BOXES_B` 两条泳道 + `CHIPS` 六件事 + `NOTES` 红线与"证不到"清单 |
| `gen_wave_record_flow_svg.py` | `docs/images/故障录波数据流.svg` | `CHAIN` 主链四段 + `EDGE` 跨边界标签 + `TRAPS` 三条陷阱 + `FORBID` 四条红线(所有权、段形态或红线变了才重画) |
| `gen_menu_tree_svg.py` | `docs/images/菜单树总览.svg` | **内嵌 `NODE_SRC`**(= `ui_menu_tree.txt` 的 43 行节点)+ 版面常量;仓库里跑会与真值逐行互验,不一致 exit 1(临时目录里读不到真值 → 用内嵌表,输出逐字节一致) |
- 要新增一张精确布局图:先到那张表按主题找最接近的生成器**照抄骨架**(`draw-diagram` skill §二),
落库时**同批把行加进那张表**(不往本文加)。
- 要挑工具(SVG 还是 Mermaid 还是截图):看本文 §一 的选型表与维度对比表——那是**判据**,不是清单,
与逐脚本清单不重复。
### 2.1 钩子扫不到的图:refgraph 产物与历史手画稿
`generated-fresh` 的 `docs-svg` 条目只把 `tools/arch_diagram/gen_*.py` 拷进临时目录重跑逐字节比对。
上表没列到的 `docs/images/*.svg` 就是下面这几张,**它们全都不在这条钩子的扫描面里**——改了不会有任何
人报警,这就是「42 个节点的旧图挂在 43 个节点的标题下」能一路活到今天的原因。
**本目录生成器不产的那四张图**(`引用关系图.svg`、`引用关系图_模块.svg`、`级联框总览.svg`、
`级联框几何计算.svg`)**全都不在这条钩子的扫描面里**——改了不会有任何人报警,这就是「42 个节点的旧图
挂在 43 个节点的标题下」能一路活到今天的原因。四张图的产物、出处与挂载逐张列在
**`tools/arch_diagram/README.md`「产物清单」**末尾两组,本文不再重复登记;只留维护口径:
| 图 | 谁画的 | 用在哪 | 维护口径 |
|---|---|---|---|
| `docs/images/引用关系图.svg`、`docs/images/引用关系图_模块.svg` | `tools/refgraph/gen_refgraph.py`(graphviz,不在 `gen_*.py` 命名面里) | `docs/架构设计/引用关系图说明.md` 的产品 | 改了代码引用就跑 `tools\refgraph\gen_refgraph.bat` 重生成,**svg 与改动同一笔提交**,别只更新 `.dot`;口径 → `docs/架构设计/引用关系图说明.md` |
| `docs/images/级联框总览.svg` | 2026-10-26 手画 | `docs/UI设计/菜单页面设计.md` §4.1(级联框显示几何:根框 + 整定子框) | 只作**显示几何示意**,不承载菜单树事实;树的结构 / 层级 / 绑页 → `docs/images/菜单树总览.svg`(有生成器) |
| `docs/images/级联框几何计算.svg` | 同上 | `docs/UI设计/菜单页面设计.md` §5.3(逐框坐标推导) | 同上;坐标公式变了要重算重画,别在 SVG 上描字 |
- **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` 条目自动发现,**不必登记基线**);上面这几张
新增精确布局图一律走 `tools/arch_diagram/gen_*.py`(`docs-svg` 条目自动发现,**不必登记基线**);上面这两组
是这套纪律的**例外面**,再多一张先说清为什么不能用生成器。
---