 ykcheungab
|
ccedb9ddd9
|
migrate pyqt5 to pyside6
|
2026-09-21 09:34:56 +08:00 |
|
|
ykcheungab
|
b37c861254
|
文档：刷新架构报告的指标与结论（app_window 拆分已落地）
- What: `docs/architecture/studio-architecture.md` 的数字与结论按当前源码重扫后刷新：
- 分层图/纯文本图：`app_window` 3044 → **2309 行 / fan-out 37**，并新增一层
"②b Studio 控制器"（session_controller 437 / replay_controller 641 / view_layout 398 /
display_prefs 227）；领域服务与共享层的行数一并更新（replay 291、calibration_service 194、
coordinator 619、camera 238、view 757、asset_source 256、gl_backend 870；
shared scene3d 4565 / acquisition 2627 / record 3008 / force 3057 / 基础设施 1507）。
- 边界规则：模块数 89（studio 32 + shared 57）→ **94（studio 37 + shared 57）**，环 0 个不变。
- 指标表：新增 `replay_controller`(641) 与 `session_controller`(437) 两行，并写明
"app_window 的 fan-out 仍是最高（37），因为它本来就是装配器——但规则已经不在它里面"。
- 生产面/验证面：studio 生产 14 655 行、shared 14 764、测试 15 639（shared 7226/334 项 +
studio 8413/310 项）、工具 4046（ui_check 3401）；验证面 19.7k > 生产面 14.7k。
- 评估第 1 条与"一句话结论"改写为：上帝对象已按职责拆开，并**诚实记账**留下的东西——
约 40 个过渡转发（给 tests/`ui_check` 的桥，属过渡层）、仍留在窗口的预览与 2D 渲染
（它们同时属于面板与相机），以及 fan-out 从 36 升到 37 的原因。
- 建议表第 1 条标记为已完成（写清五个去处与新增 41 项控制器单测），新增第 1b 条
"下次改动顺手删掉对应转发"，并补第 7 条"真机与 ARM 验收"（本机无设备/板卡，是当前最大空白）。
- What: `studio-architecture.svg` / `.png` 由 `.repro/make_studio_svg.py` 重新生成：
窗口框改为"2309 行 · 158 方法 · fan-out 37 · 装配 + 信号转发"，右侧四个控制器小框，
面板/服务/共享层/验证面的行数与测试项数同步；底部结论改为"已按职责拆开 + 剩下的胶水"。
顺带修好 `svg_to_png.py` 里写死的 1560×1180（现在读 SVG 自己的尺寸），否则海报加高后会被裁掉。
- Why: 这份报告是"判断组织是否合理"的依据，数字或结论一旦过期就会误导决策；
拆分改变最大的一处正是它第 1 条风险与第 1 条建议，必须同步。
- Verification: 图表脚本重跑无异常（SVG well-formed，PNG 1560×1210 已目视检查）；
同批源码的验证为 pytest 644 passed / 0 failed / 15 skipped（offscreen）、
tools/ui_check.py 587 项 0 失败、.repro/locale_check.py 0 缺失。
- Not in this change: 不改代码；不改 `.repro` 下的扫描脚本口径（仍以扫描输出为准）。
|
2026-09-15 10:02:37 +08:00 |
|
|
ykcheungab
|
8d374e5850
|
refactor(studio): 回放引擎改名 ReplayEngine —— 把「引擎」与「窗口级控制器」的名字分开
- What: `apps/studio/src/orisys_studio/replay.py` 的 `ReplayController` 改名为 `ReplayEngine`
（引用只有 4 处：`app_window.py` 的 import 与构造、`ui_check.py` 的一处 import、模块内定义）；
模块 docstring 写明它为什么叫 engine（只回答"t 时刻是什么"，不知道传输策略、不知道控件），
并指路即将落地的窗口级 `ReplayController`；`app_window.replay` 这个属性名**不动**（36 处使用）。
同步更新两份既有文档里的类名（`apps/studio/docs/shell-lifecycle.md`、`record-channel.md`、
`docs/architecture/studio-architecture.md` 的框图标签）。
- Why: 用户已同意分拆 `app_window.py`，并选定"引擎改名 ReplayEngine + 新类叫 ReplayController"
这一方案（另一方案是让两个名字 `ReplayController`/`ReplayCoordinator` 并存，容易进错门）。
这一步是后续把窗口里那 30 个回放方法搬进 `ReplayController` 的前提：先把名字腾出来，
否则搬迁时无法区分"引擎"与"控制器"。
- Verification: shared+apps 同一次运行 **588 项 0 失败 15 跳过**；`ui_check` 587 项 0 失败；
全仓 `grep ReplayController` 只剩两处有意保留的提及（`replay.py` docstring 里指路、
`app_window.py` 注释里指路），没有悬空引用。
- Not in this change: 不搬运任何方法、不改行为——`app_window.py` 仍是 3043 行；`SessionController`、
`ReplayController`、`ViewLayoutController`、`DisplayPrefsController` 四个模块的搬迁尚未开始
（顺序与契约见 docs/architecture/studio-architecture.md 建议 1）。
|
2026-09-15 08:41:44 +08:00 |
|
|
ykcheungab
|
dd0ee2c71e
|
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 条尚未实施，它们属于下一轮工作，
每条都写了收益、成本与回归门。
|
2026-09-15 08:25:20 +08:00 |
|