orisys-tech/orisys-app
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

更新 Studio 主窗口重构的 S3 交接计划

Browse Source 
核对已接线阶段与当前回放行为，明确并行标定任务的文件边界。文档门禁通过，本轮未执行代码重构或回归测试。
This commit is contained in:
ykcheungab
2026-10-19 17:23:36 +08:00
parent 9d4563e929
commit 70b4341fd0
1 changed files with 89 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/studio-window-refactor-plan.zh.md
+89 -93
View File
@@ -13,7 +13,7 @@
启动、停止、暂停、异常处理、信号顺序及懒加载时机均属于行为保持边界。
关闭时保留预览关闭、采集回调解绑、分析取消与等待、采集和录制收尾、3D 释放的顺序。
测试和工具确实使用的旧入口可以暂留，但每一步必须说明保留原因并更新真实调用方。
不提交、不切换分支；排除已有 Autocal、测试修复文档及工作区归档修改。
不提交、不切换分支；保留所有已有修改，不将并行功能开发混入重构。
## 顺序与验收
@@ -62,11 +62,12 @@
### S4：分析配置
- [ ] 提取 `analysis_setup.py` 的对话框、裸视频工作目录和分析服务构造。
- [ ] 迁移 reference override 的所有权，保持现有保存和取消语义。
- [ ] 迁移按录制目录保存的完整分析选择，保持接受、取消、重算来源及缓存语义。
- [ ] `ReplayController` 继续负责执行、取消、缓存及结果选择，不吸收配置逻辑。
依赖 S3 的标定选择接口。验证：`test_bare_video_analysis`、`test_analysis_progress`、
`test_replay_wiring`；历史录制仍使用自身 chain，取消配置不改变当前结果。
`test_replay_wiring`、`test_recording_recalibration`；保留录制 chain、标定/设备确认、
显式禁用标定、空载窗口及实际参考帧 ID/时间，取消或失败保留上一完整结果。
### S5：运行协调与预览
@@ -88,106 +89,101 @@
显示设置重绘测试。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`，不扩大基线。
以下是旧批次证据，不是当前 HEAD 的复验。详细原计划快照保存在本轮 scratch 的
`plan-before.md`；原始日志路径若不可用，应注明证据缺失。
### 2026-10-19：S2 接线
| 批次 | 实施与结果 | 原始证据（相对应用仓库） |
|---|---|---|
| S1，2026-10-18 | 状态迁出；前后定向 125 passed，独立 19 passed，最终 Studio 550 passed/19 skipped；首次门禁 Studio 两项失败保留，隔离通过不能解释原因 | `.scratch/studio-window-refactor/20261018-200221/`；`gate-20261018T120931Z/summary.md` |
| S2 准备，2026-10-19 | main a0c13c1；只新增模块及测试，主窗口字节不变；13 passed，lint 通过 | `.scratch/studio-window-refactor/20261019-094111/final.xml` |
| S2 接线，2026-10-19 | main c6c16df；3070→2894 行；10 控件、35 菜单/action 同对象，18 业务回调留窗口；46→49 passed | `.scratch/studio-window-refactor/20261019-095028/` |
以 `main` 的 `c6c16df` 为基准，接入已准备的两个 UI 模块；主窗口从 3,070 行减至
2,894 行。10 个控件和 35 个菜单、action 属性保留同一对象引用；18 处菜单业务回调及
控制器绑定仍在窗口。主题与文字更新委托 UI 模块，reset 目标、pause 状态仍沿用原逻辑。
S2 串行门禁：lint 通过，UI 632 checks/0 failures；shared 461 passed、15 failed、
18 skipped、3 deselected，涉及映射缺失及模型尺寸；Studio 垃圾回收时访问冲突，无 JUnit。
扩展 UI 131 passed/1 failed，为分析停止后的即时状态断言。旧/新窗口隔离均 4 passed；
旧窗口全套对照无进展后中断。不可据此归因。汇总：
`.scratch/studio-window-refactor/gate-20261019T015301Z/`。
FrameView、共享 domain latch 和曲线 store 在控制器接线前绑定，偏好恢复顺序不变。
只改动窗口的构造、菜单构建、菜单勾选、文字和主题刷新五个方法；其余方法的 AST 一致，
最新标定读取、应用和关闭路径未迁移。S3–S6 保持待实施。
S1 首次 shared 467 passed、18 skipped、3 deselected，UI 632/0；另有关闭后的
`asset_rejected` 异步回调，S5 须复核。S1/S2 临时反转条件的回归能发现错误，已恢复源码。
均为 Windows/Python 3.10.19/offscreen；未验证真实设备、可见桌面或硬件 GL。
未放宽断言或基线。S2 的非迁移方法 AST 一致是当时证据，后续功能提交不受其约束。
改动前定向检查为 46 passed；接线后加上三个集成检查为 49 passed。
覆盖控件身份、菜单单次调用、主题与语言刷新、实时与回放的 reset 目标，以及既有布局、
暂停和标定对话框。首次新增断言误将菜单与按钮的不同文案视为相同，已按原契约修正。
串行门禁的 lint 通过，UI 检查为 632 checks、0 failures；共享层为 461 passed、
18 skipped、3 deselected、15 failed，涉及 SDK 映射文件缺失及几何尺寸不一致。
Studio 在垃圾回收期间访问冲突退出，无 JUnit 报告。整套门禁未通过，原因尚未完全确认。
## 当前交接：仅执行 S3
扩展界面检查为 131 passed、1 failed，失败是分析停止后的即时状态断言。
该用例及崩溃所在的三个布局场景，在旧、新主窗口隔离运行均为 4 passed，未复现整套异常。
旧主窗口整套对照长时间无进度后已中断，不能据此判定原因。未修改失败断言或扩大基线。
临时禁用局部主题刷新时，新增测试按预期失败；仅在测试进程注入，源码未改动。
- task_id：`studio-window-refactor`；round：2；updated_at：2026-10-19，Asia/Hong_Kong。
- status：ready；owner：Codex（交出后停止写入）；next_agent：DeepSeek 执行方。
- 用户要求“check existing plan and prepare to handoff to deepseek”；本轮只更新交接。
先前分步重构授权继续有效；转发启动指令后执行 S3，完成交付 review。
S4–S6 留下一轮，不因 S1/S2 结构完成而声称全量验收通过。
环境为 Windows、Python 3.10.19、offscreen Qt；真实设备、可见桌面和硬件 GL 未验证。
文档检查无新增问题，原架构长段落债务仍保留。证据位于
`.scratch/studio-window-refactor/20261019-095028/` 和 `gate-20261019T015301Z/`。
另一个进程的 Autocal 修改含暂存项，全部排除；本批六个文件未暂存，根仓库未修改。
### 基准与输入
| 仓库 | 分支与 HEAD | 起始状态／本轮修改 |
|---|---|---|
| `D:\orisys_ws\orisys-app` | dev；9d4563e9292469e9df500a7acab6d26489810455 | 索引空；finger sensor.json 已有未暂存修改；本轮仅此计划 |
| `D:\orisys_ws` | master；9201914cbe335b6862058212af0bc2614f2b4792 | 场加权计划有其他任务修改；设备包、mph、dragon-q6a 无关未跟踪；本轮不改根仓库 |
当前主窗口 2899 行、213 个方法（含属性访问器）；WindowUi/WindowMenus 已接线，
live_calibration.py/analysis_setup.py 尚不存在。当前源码包含后续回放修复，不能回退旧窗口。
本轮工作目录为应用仓库；解释器 `D:\orisys_ws\orisys-app\.venv-build\Scripts\python.exe`。
源码、配置、测试与依赖声明 SHA256 见
[baseline-sha256.json](../../.scratch/studio-window-refactor/handoff-20261019-171832/baseline-sha256.json)；
本轮计划哈希见同目录 `delivery-sha256.json`，不把哈希写回被哈希文件。
同 checkout 无需补丁；跨 checkout 须提供差异、新文件及上述基准。无须原始视频或硬件。
### 范围、依赖与停止条件
allowed_files：`apps/studio/src/orisys_studio/app_window.py`、新增 `live_calibration.py`，
必要的 `shell_ports.py`；相关实时标定测试及新增单元测试；本计划与 `studio-architecture.md`。
其他阶段、SDK、shared、配置、Autocal 和功能变更均不在本轮范围。
迁移 live choice 的读取/保存、默认路径、解析、导出后选择和确认/提交请求。
复用同一 prefs 与保存入口，避免第二份状态；服务仍负责文件身份和匹配。
注入显式控件、回调或窄接口，不传整个窗口或使用任意属性代理。
先保留实际被 SensorDialog、运行入口、回放配置和测试调用的窗口桥；列出调用者与保留原因。
测试 monkeypatch 的转发仍须生效，不能复制旧实现来满足测试。
采集线程确认继续只写 RecordingCoordinator/SessionController，不操作 Qt；
GUI drain 在原时机执行。导出不应用，请求不当作确认；角色 default/file/none、
缺失文件、序列号检查、提示文字及 worker 请求参数均保持当前行为。
[场加权标定任务](../../../docs/workflow/field-weighted-calibration-plan.zh.md) 当前 working，
涉及 calibration_service.py、video_analysis_dialog.py、replay_controller.py 和 shared。
本轮把它们作为只读依赖；不改接口、不覆盖其工作。若接手时其变化影响提取或验证，
先核对该任务的交接记录与文件所有权，停止交叠部分；不得根据旧哈希恢复它们。
需要修改重叠文件或改变功能时请求决定，独立准备可继续。
默认遵循交接约定的三次失败停止规则；未设时间预算。没有提交、推送或硬件授权。
### 执行与验收
DeepSeek 先运行下方相同测试建立当前基线，再分“选择/解析”和“确认/请求”两批提取。
每批检查调用方与差异、跑相同回归，补窄接口独立测试；完成更新架构现状，运行门禁。
结果应保持旧行为、减少窗口业务逻辑、无循环依赖及新线程。独立验收方复跑关键证据。
历史全量失败不自动豁免；本轮失败记录实际退出码、归因证据与剩余项，不降标准。
```powershell
# 工作目录 D:\orisys_ws\orisys-app；每次替换为唯一 run_id
& ./.venv-build/Scripts/python.exe -m pytest apps/studio/tests/test_live_calibration_dialog.py apps/studio/tests/test_calibration_service.py apps/studio/tests/test_model_calibration_ui.py apps/studio/tests/test_recording_recalibration.py apps/studio/tests/test_bare_video_analysis.py apps/studio/tests/test_window_surfaces.py -p no:cacheprovider --basetemp=.scratch/studio-window-refactor/pytest-<run_id> --junitxml=.scratch/studio-window-refactor/<run_id>.xml
& ./.venv-build/Scripts/python.exe -m pytest apps/studio/tests/test_ui_smoke.py -k calibration -p no:cacheprovider --basetemp=.scratch/studio-window-refactor/pytest-confirm-<run_id>
& ./.venv-build/Scripts/python.exe tools/lint_gate.py
powershell -NoProfile -ExecutionPolicy Bypass -File tools/gate.ps1 -Task studio-window-refactor -LintBase HEAD -Serial
& .\.venv-build\Scripts\python.exe -m pytest apps/studio/tests/test_ui_smoke.py apps/studio/tests/test_ui_elements.py apps/studio/tests/test_sensor_switch_window.py -m 'not timing' -o faulthandler_timeout=60 -p no:cacheprovider --basetemp=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261019-095028\pytest-ui-focused --junitxml=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261019-095028\ui-focused.xml
# 工作目录 D:\orisys_ws
& ./orisys-app/.venv-build/Scripts/python.exe scripts/doc_lint.py --files orisys-app/docs/architecture/studio-window-refactor-plan.zh.md orisys-app/docs/architecture/studio-architecture.md
```
### 2026-10-19：S2 模块准备，接线延期
| 本轮验收项 | 实际命令与结果 | 证据 |
|---|---|---|
| 当前阶段/调用方 | 只读检索与 Python AST 计数；S1/S2 已接线、S3 未实施 | 当前源码及 baseline-sha256.json |
| 文档检查 | `scripts/doc_lint.py --files orisys-app/docs/architecture/studio-window-refactor-plan.zh.md`；退出码 0 | 本轮 scratch/doc-lint.log |
| 文档大小 | `scripts/doc_count.py orisys-app/docs/architecture/studio-window-refactor-plan.zh.md`；预算内 | 本轮 scratch/doc-count.log |
| 代码回归/全量门禁 | 本轮未执行，只整理交接；上方是未来命令 | 不复用历史结果冒充当前通过 |
用户要求避开另一个进程正在修改的标定配置读取和应用路径，本批只新增模块及独立测试，
不编辑 `app_window.py`、现有面板、标定服务、控制器或配置文件。
基准为 `main` 的 `a0c13c1` 加当时工作区修改；读取的主窗口快照留在本批 scratch。
`WindowUi` 创建中央控件、四个面板及布局，提供局部主题和文字更新。
`WindowMenus` 创建 QAction、快捷键、菜单组和勾选初值，提供静态文字及主题/语言勾选同步。
两者均不保存偏好、不绑定业务回调，不启动设备、分析或 3D；真实控件复用现有实现。
当前主窗口仍走原来的构建路径，因此不能宣称 S2 已完成迁移。
未来接线前重新核对并行标定改动，再按顺序替换布局和菜单构建。
共享 domain latch、FrameView、曲线 store、业务信号和初始偏好恢复由窗口显式装配；
第一次呈现前完成绑定。菜单初值先于业务信号连接；reset 的目标文字、pause 状态及操作可用性
仍由现有控制器和窗口同步。兼容属性引用同一批控件，不另造重复面板。
新增 `test_window_surfaces.py` 和现有 `test_studio_binding_purity.py` 为 13 passed，
测试使用临时的空 sensor catalog，不扫描正在修改的真实配置目录。
还核对了 35 个菜单与 action 属性与起始快照一致；临时取消主题组互斥后测试能发现错误，
随后原样恢复。新增文件 lint 通过，文档检查无新增问题；主窗口与起始快照逐字节一致。
本批仅证明模块可独立使用；接线后的主窗口全套回归、真实桌面与设备验证仍待执行。
日志和 XML 位于 `.scratch/studio-window-refactor/20261019-094111/`，最终结果为 `final.xml`。
```powershell
& .\.venv-build\Scripts\python.exe -m pytest apps/studio/tests/test_window_surfaces.py apps/studio/tests/test_studio_binding_purity.py -p no:cacheprovider --basetemp=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261019-094111\pytest-final --junitxml=D:\orisys_ws\orisys-app\.scratch\studio-window-refactor\20261019-094111\final.xml
```
### 2026-10-18：S1 接线与历史验证
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`，根仓库目前无本批未提交修改。
本次没有执行提交、暂存或历史改写；产品仓库的五个交付文件保持未暂存。
轮次摘要：1，S0–S2 实施及历史限制见上；2，核对现状并准备 S3 交接，未改生产代码。
验收者、独立复跑和决定尚未发生。下一步由 DeepSeek 核对现场、将 owner/status 更新为
DeepSeek/working，完成后交 review；验收方决定 done/rework，不能自行宣称接受。
本轮无后台进程；证据保留在 `.scratch/studio-window-refactor/handoff-20261019-171832/`，
检查结束移除任务 .active，不清理日志。缺失 scratch 材料明确标记，不依赖它继续写入。