docs(architecture): Studio 架构图与可维护性评估（按源码实际 import 关系生成）

- What:
  1. `docs/architecture/studio-architecture.md`：分层视图（Mermaid + 纯文本版）、运行时/线程视图、
     二维/三维显示子系统视图、边界规则与证据表、指标表（模块行数 × 扇出、稳定核心 fan-in、验证面规模）、
     可维护性评估（5 条优点 / 7 条风险，逐条带证据）、6 条建议（按性价比排序）。
  2. `docs/architecture/studio-architecture.svg`（浏览器直接打开）与同名 `.png`（由 SVG 经 QtSvg 栅格化，
     给没有 SVG 渲染器的场景）：分层海报，层间流动用箭头表示，跨模块关系写在框内。
  3. 数据来源（在 `.repro/`，可重跑）：`studio_arch_scan.py` 扫 89 个模块的 import 图并给出 fan-in/fan-out
     与**模块级环**；`studio_arch_imports.py` 分别统计"import 时就拉 Qt/GL/SDK"与"函数内惰性 import"，
     并在**新解释器**里逐个验证"导入 X 是否会拉进 PyQt5/OpenGL/SDK"；`make_studio_svg.py`/`svg_to_png.py`
     生成图。原始数据 `studio_arch.json`、`studio_arch_imports.json`。
- Why: 用户要看架构图来判断"软件组织是否合理、是否容易维护"。因此所有框与数字都从源码实际 import 关系
  生成，而不是画一个理想分层：报告里同时给出**成立**的边界规则（无环、共享层 import 时不依赖 Qt/GL、
  三维调度与相机无 Qt 可脱离 GUI 测试）与**不成立**的一条（`force/calibration_io` 在 import 时 import
  orisys，于是力相关单测必须装 SDK），以及最贵的单点 `app_window.py`（3044 行 / 158 方法 / fan-out 36）。
- Verification:
  · 扫描结果：89 个模块（studio 32 + shared 57）模块级**环 0 个**；import 时拉 PyQt5 的 21 个模块**全部**
  在 `orisys_studio.*`；OpenGL 只在 `gl_backend`/`widget` 函数内惰性加载；新解释器验证
  `scene3d.contracts/composer`、`acquisition.arrows/sinks`、`record.playback`、`theme`、
  `studio.scene3d.coordinator/camera` 均为"干净"（不含 PyQt5/OpenGL/SDK），而 `force.history` 会拉进 SDK。
  · 规模：studio src 13 376 行（三维 4 326）、shared 14 820 行（三维 4 576 / 记录 2 673 / 力 2 645 /
  采集 2 343）、测试 11 633 行、工具 5 272 行；`scene3d.contracts` fan-in 22 为全仓最高。
  · 图的自检：SVG 由 `ET.parse` 验证为良构 XML，并栅格化成 PNG 后逐版目视检查过（第一版箭头穿框，已改为
  层间箭头 + 框内关系文字）。
- Not in this change: 不改任何产品代码；建议 1（拆 `app_window`）等 6 条尚未实施，它们属于下一轮工作，
  每条都写了收益、成本与回归门。

This commit is contained in:

ykcheungab

2026-09-15 08:25:20 +08:00

parent cf45e654e1

commit dd0ee2c71e

3 changed files with 421 additions and 0 deletions

docs/architecture/studio-architecture.png

BIN

View File

Binary file not shown.

After

Width: | Height: | Size: 267 KiB