# Autocal 录像复核与汇总实施计划

状态：2026-10-16，待实施。范围：补齐录像可靠性、按事件回放和操作员汇总；不改变运动控制，不部署标定系数。详细字段见[数据契约提案](recording-summary-contract.zh.md)，DeepSeek 执行清单见[任务分工](recording-summary-tasks.zh.md)。本计划补充[原实施计划](implementation-plan.zh.md)，不把草稿描述当作功能验收。

## 现状与问题

调查基线：app `main`、HEAD `2cec3d905b193670e3de5df5f2de6dd4b1e8e3d7`。结论来自源码和样例 CSV，未运行相机、平台或故障复现。工作树已有 `motion/service.py`、`record_diagnostics.py` 和测试计划改动，实施前须重新核对，不能覆盖。

| 证据位置（相对应用源码目录） | 已有能力及缺口 |
|---|---|
| `trial.py: ManualTrial.start/finish/poll` | 已接共享录像器，单 trial 连续录像；异步排空及完整性判断已有模式可复用 |
| `multipoint.py: _start_images/_release_images/_close_repeat` | 已录 `capture/raw_*.mp4`，但停止时未采用 recorder report 判断 repeat 完整性 |
| `multipoint.py: _open_repeat/_start_images` | 后续 repeat 在加入清单前启动录像，随后以 `trials[-1]` 写关联，可能更新前一 repeat |
| `multipoint.py: start` | 会话重新开始未清除待连接 worker，存在旧来源跨会话继承风险；需回归证明 |
| `ui/multipoint_panel.py: _poll` | 当前主要处理保持倒计时，缺少与单 trial 等价的来源／录像失败检查 |
| `multipoint.py: stable_component_rows` | 已有 `stable_means.csv`，采用保持后半段、分量去异常值；帧与力按过滤后的行序关联，须改成明确身份校验 |
| `session_review.py`、`record_overview.py` | 已有保持段复核、FN 拟合及质量统计，复用其审核状态；缺少直接的视频复核入口和统一三分量导出 |

因此首要任务是让现有录像可验证、可发现、可回放，而非再写一套录制器。用户现场的缺录像原因仍待核对实际输出和运行版本；上述静态缺口不能直接证明现场原因。

## 参考样例与设计选择

`D:/orisys_ws/data/dd02-gl` 包含一个 MP4 和两张 CSV。`baseline_load_data.csv` 有 60 行，15 个 UV 点各有 0/1/2/3 N 四档，均为 repeat 1；`sensitivity_values.csv` 有 15 行。只有 11 个不同 site_id，多个来源重复使用编号，不能按 site_id 单独合并。

样例表缺少原始窗口时间、帧索引、配置／映射身份和完整来源文件，不能反推出与该 MP4 的同步关系，也不能证明这些窗口已经人工复核。只借鉴“窗口均值表＋逐点灵敏度表”的操作方式，不把历史样例自动升级为已验证标定。

方案默认录传感器原始输入画面，不录桌面或第二台外部相机；现有 MP4 有损编码不称为无损原始图像。每 trial/repeat 一条逻辑录像，含零载、换档、加载、卸载和恢复；保持段不另建视频。跨测点间的对准等待不承诺录像。

首期保留当前 24 小时分段设置及单 trial 完整性约束，读取端支持已有分段索引。若以后改成短分段，必须同时修改 `ManualTrial.poll()` 的单段限制并验证跨段行为，不能只改录制参数。

保留现有两种采集目录和共享格式，新增可重建的汇总目录；不要移动、删除或复制原始视频来追求目录整洁。旧记录按原样读取，缺视频显示“无录像证据”。

## 数据流和界面

```mermaid
flowchart LR
  A[相机与采集时间] --> B[FingerAcquisitionWorker / SdkPacket]
  B --> C[有界队列 / ExperimentRecorder]
  B --> D[实时预览]
  C --> E[视频 / frames / forces]
  F[人工参考与保持事件] --> G[reference / events / session]
  E --> H[只读身份与完整性检查]
  G --> H
  H --> I[保持段选择与视频回放]
  I --> J[窗口统计与灵敏度]
  J --> K[summary.html / 两份 CSV / summary.json]
```

采集线程只提交数据，不编码、不生成报告。写盘线程负责录像；Qt 线程管理状态和呈现。回放解码、校验和导出在后台执行，通过现有 `ReviewJob` 或专属解码任务返回结果；旧任务结果不得覆盖用户新选的 trial。

采集页展示“未就绪／录制中／收尾中／完整／证据不完整”、实际写入帧数、丢帧、时长和保存位置。开始保持必须等录像就绪；完成按钮进入收尾，不立即报成功。故障通知操作员停止加载并保存未完成证据，不新增自动运动。

记录总览继续作为唯一入口。点选测点、repeat、保持段即可播放对应画面，支持播放／暂停、逐帧、定位起止点；同步显示原始力曲线、实际参考力和有效状态。按帧索引定位，不用播放器秒数推算实际采集时间。采集中可见录像状态，回放首期只开放已收尾的 trial，避免同时读取未封口容器。

结束整场后自动生成候选汇总；人工复核保存后生成新的已复核汇总。操作员默认只看一个报告及两张表，原始目录通过“查看原始证据”展开。报告区分采集完整性、稳定段确认和计算可用性，不输出未经定义的合格／不合格结论。

## 实施与交付顺序

1. 先用两个连续 repeat、连续两个 session、live 后 simulation 证明录像归属和生命周期缺口，并锁定新增契约。
2. 修正现有录像收尾、失败传播和 UI 状态，以合成相机完成两点两次采集闭环。
3. 并行开发只读回放和汇总计算，再串入同一记录总览；禁止跨应用导入 Studio 私有控制器。
4. 增加自动汇总、原子发布和旧记录兼容；最后执行软件回归及独立人工复核。

粗估为 10–15 个工程人日，最多三名实现子代理并行时约 5–8 个工作日；这是排期估计，不是 DeepSeek 运行时承诺，不含设备等待。主代理负责共享文件、接口冻结和集成。

## 验收与停止条件

| 场景 | 必须得到的结果 |
|---|---|
| 两点各两次，含中止重试 | 四次正常试验各指向自己的录像；中止另占身份，不覆盖文件 |
| 断流、写盘失败、编码失败、队列溢出 | 不再报采集完整，仍可打开残存数据；界面不因排空阻塞 |
| 点击一个已确认窗口 | 定位其首／末有效帧，曲线、参考和视频使用同一采集时间及 trial 身份 |
| 两种现有格式与历史缺视频记录 | 可读且保留缺失原因；不伪造帧或稳定性 |
| 汇总重算 | 数值可由输入及窗口选择复算，结果不修改原文件；无有效数据保持空值和原因 |
| 操作员交付 | 一个报告链接能找到全部测点、失败原因、两张 CSV 和原始证据 |

软件完成必须通过任务清单中的测试、文档门禁和无硬件操作演示；相机吞吐、磁盘容量、驱动延迟和视频可解码性另做实机测量。真正加载实验需明确设备、载荷／运动边界和停止条件后执行。

本期不做 FT 同步、自动加载、批量跨 session 合并、历史视频补时间、原始数据清理或算法状态精确重演。录像支持视觉复核，不能保证有状态算法从全新进程逐帧复现。