ykcheungab
0998009ec3
让状态显示独立于主窗口，保留录制快照注入入口。验证结果和完整门禁限制见 docs/architecture/studio-window-refactor-plan.zh.md。
132 lines
8.1 KiB
Markdown
132 lines
8.1 KiB
Markdown
# Studio 主窗口分步重构计划
|
||
|
||
目的：plan。范围：`apps/studio/src/orisys_studio/app_window.py` 及其直接调用方。
|
||
当前架构由 [Studio 架构](studio-architecture.md) 维护；本文件是唯一实施进度记录。
|
||
|
||
## 目标与约束
|
||
|
||
主窗口保留组件装配、跨功能信号连接、窗口几何及明确的关闭顺序。
|
||
按职责迁移现有实现，不增加产品功能、依赖、线程或全局状态容器。
|
||
会话、回放、布局、显示偏好和记录状态继续由现有控制器持有。
|
||
显示层只读取状态；录制与标定采样继续消费采集线程的数据，不依赖刷新频率。
|
||
|
||
启动、停止、暂停、异常处理、信号顺序及懒加载时机均属于行为保持边界。
|
||
关闭时保留预览关闭、采集回调解绑、分析取消与等待、采集和录制收尾、3D 释放的顺序。
|
||
测试和工具确实使用的旧入口可以暂留，但每一步必须说明保留原因并更新真实调用方。
|
||
不提交、不切换分支；排除已有 Autocal、测试修复文档及工作区归档修改。
|
||
|
||
## 顺序与验收
|
||
|
||
每步都先检查调用方及相关测试，完成后更新本计划和架构文档。
|
||
任务顺序为 S0 → S1 → S2 → S3 → S4 → S5 → S6；每一步均可独立审查。
|
||
|
||
### S0：基线与计划
|
||
|
||
- [x] 记录 HEAD、索引和已有修改，建立独立 scratch 证据目录。
|
||
- [x] 在改动前运行状态显示与主窗口相关测试。
|
||
|
||
基线：2026-10-18，`orisys-app` 的 `main`，HEAD `433b76e`。
|
||
源码为 3,181 行；`StudioMainWindow` 有 212 个方法，含属性访问器。
|
||
原架构文档的 2,309 行及“拆分已完成”属于历史状态。
|
||
|
||
### S1：状态显示
|
||
|
||
- [x] 新建 `status_presenter.py`，接收显示事实与目标控件，不接收整个窗口。
|
||
- [x] 迁移 phase、来源摘要、标定摘要、有效性及录制统计的格式化与显示。
|
||
- [x] 保留 `_record_stats` 注入入口，保证已有截图工具和 UI 检查仍有效。
|
||
|
||
涉及主窗口、新 Presenter 和定向测试。验收：实时视图不显示回放标题；分析结果保持自己的
|
||
传感器身份；未知、无标定、部分轴标定仍可区分；录制关闭中不显示完成，丢失计数完整。
|
||
验证：状态 Presenter 独立测试、`test_ui_smoke`、`test_replay_wiring` 和现有 UI 检查。
|
||
|
||
### S2：界面构建
|
||
|
||
- [ ] 提取 `ui/window_ui.py` 的控件和布局构建，保持控件身份、顺序及 parent。
|
||
- [ ] 单独迁移菜单和 QAction 创建；由窗口显式连接功能操作。
|
||
- [ ] 迁移对应文字与主题更新，保留必要属性兼容入口。
|
||
|
||
依赖 S1。涉及主窗口、UI 模块及实际调用方；面板构建和菜单构建分两批验收。
|
||
验证：`test_ui_elements`、`test_view_layout`、`test_sensor_switch_window`、主题与语言检查。
|
||
3D 仍在原时机创建，启动恢复顺序及保存的布局不变。
|
||
|
||
### S3：实时标定交互
|
||
|
||
- [ ] 提取 `live_calibration.py` 的选择保存、解析、确认及提交请求。
|
||
- [ ] 文件身份和匹配规则复用 `CalibrationService`；对话框通过窄接口访问。
|
||
- [ ] 设备确认、记录版本及采样仍走现有记录通道。
|
||
|
||
依赖 S2。验证：`test_live_calibration_dialog`、`test_calibration_service` 及确认事件测试。
|
||
导出不等于应用，应用请求不等于设备确认，序列号不匹配的处理不变。
|
||
|
||
### S4：分析配置
|
||
|
||
- [ ] 提取 `analysis_setup.py` 的对话框、裸视频工作目录和分析服务构造。
|
||
- [ ] 迁移 reference override 的所有权，保持现有保存和取消语义。
|
||
- [ ] `ReplayController` 继续负责执行、取消、缓存及结果选择，不吸收配置逻辑。
|
||
|
||
依赖 S3 的标定选择接口。验证：`test_bare_video_analysis`、`test_analysis_progress`、
|
||
`test_replay_wiring`；历史录制仍使用自身 chain，取消配置不改变当前结果。
|
||
|
||
### S5：运行协调与预览
|
||
|
||
- [ ] 先提取 `preview_controller.py`，负责设备和预览定时器生命周期。
|
||
- [ ] 再提取 `activity_coordinator.py`，统一按钮和快捷键的运行、暂停、停止规则。
|
||
- [ ] worker 操作通过 `SessionController`；关闭流程继续在窗口显式排列。
|
||
|
||
依赖 S4。两批分别验证 `test_session_controller`、`test_pause_controls`、
|
||
`test_transport_review` 和连接中停止、断开、异常、重复关闭场景。
|
||
普通停止保持非阻塞，退出等待资源结束；预览与采集不能争用相机。
|
||
|
||
### S6：显示入口与兼容桥收尾
|
||
|
||
- [ ] 将 2D/3D 的共同交付协调归入现有 `FrameView`，调用方显式传入显示上下文。
|
||
- [ ] 更新测试和工具为真实控制器接口，删除已无调用方的窗口转发。
|
||
- [ ] 核对依赖方向、无循环、线程归属和文档现状；运行完整门禁。
|
||
|
||
依赖 S5。验证：`test_shared_depth_scale`、`test_scene3d_frame_views`、回放定位与
|
||
显示设置重绘测试。2D/3D 使用同一帧；实时不覆盖回放；重绘不启动新分析。
|
||
结束条件是主窗口只承担约定职责，且所有相关检查通过，不以行数作为唯一标准。
|
||
|
||
## 验证与当前进度
|
||
|
||
解释器使用 `.venv-build/Scripts/python.exe`。定向 pytest 显式使用独立的
|
||
`--basetemp` 和 `-p no:cacheprovider`；日志位于 `.scratch/studio-window-refactor/`。
|
||
每个迁移步骤运行对应检查；可交付批次运行 `tools/gate.ps1 -Task studio-window-refactor`。
|
||
文档使用工作区 `scripts/doc_lint.py` 和 `scripts/doc_count.py`，不扩大基线。
|
||
|
||
2026-10-18：S0 和 S1 已实施。改动前后同一组 `test_ui_smoke` 与
|
||
`test_replay_wiring` 均为 125 passed；新增 Presenter 独立测试为 19 passed。
|
||
主窗口暂为 3,052 行；状态显示已迁出，S2–S6 尚未实施。
|
||
|
||
首次完整门禁：lint、共享层（467 passed、18 skipped、3 deselected）及 UI 检查
|
||
（632 checks、0 failures）通过；Studio 为 548 passed、19 skipped、2 failed。
|
||
失败分别是 `test_adopting_a_box_result_never_flashes_the_overlay_refusal` 的两次绘制，
|
||
以及 `test_the_replay_view_loads_a_recording_and_scrubs_it` 的录制目录缺失。
|
||
|
||
两项在重构前后隔离运行均通过；重构前主窗口的完整顺序对照为 550 passed、19 skipped。
|
||
没有修改回放实现、测试断言或失败基线来消除这些失败；其发生条件尚未确认。
|
||
当前主窗口的最终串行 Studio 复测为 550 passed、19 skipped，与旧主窗口完整对照一致。
|
||
S1 本批检查完成，S2 尚未开始；首次门禁失败报告仍保留，不改写为通过。
|
||
|
||
UI 检查虽然断言通过，日志另有 `asset_rejected: this coordinator has been closed` 的
|
||
异步加载回调异常；其复现条件未确认，S5 的关闭流程验收需要复核。
|
||
|
||
本批使用 Windows、Python 3.10.19 和 offscreen Qt，不能作为真实设备、可见桌面操作
|
||
或硬件 GL 验证。测试反转了标定 fallback 判断，7 项相关用例中 2 项发现错误；
|
||
随后按字节恢复源码。197 个相关源码和测试文件的 SHA-256 在最终收尾比较中完全一致。
|
||
文档门禁无新增问题；架构文档仍保留一项已登记的历史长段落债务，没有扩大基线。
|
||
|
||
实际执行的完整检查如下，工作目录为 `D:\orisys_ws\orisys-app`；独立日志和 XML 留在
|
||
`.scratch/studio-window-refactor/20261018-200221/`，首次门禁汇总位于相邻的
|
||
`gate-20261018T120931Z/summary.md`。这些是本地证据，未纳入版本控制。
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File tools\gate.ps1 -Task studio-window-refactor
|
||
& .\.venv-build\Scripts\python.exe -m pytest apps/studio/tests -m 'not timing' -p no:cacheprovider --basetemp=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261018-200221\pytest-final-studio --junitxml=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261018-200221\final-studio.xml
|
||
```
|
||
|
||
并行任务将 App HEAD 从 `433b76e` 更新至 `cf3e638`，未改动本次主窗口基准；
|
||
相关回放分析修改不属于本批。
|
||
根仓库的计划索引和 inventory 登记被并行任务纳入 `bf44125`，根仓库目前无本批未提交修改。
|
||
本次没有执行提交、暂存或历史改写；产品仓库的五个交付文件保持未暂存。
|