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

2026-10-17 09:49:51 +08:00
parent 2cec3d905b
commit d7540f52ec
3 changed files with 266 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 录像和操作员汇总数据契约提案
+
+状态：2026-10-16，待实施。属于[实施计划](recording-summary-plan.zh.md)；既有采集字段仍以[单次格式](calibration-data-format.zh.md)及[多点格式](multipoint-data-format.zh.md)为准。以下新增字段、接口和文件名均是提案，不能按已实现能力使用。
+
+## 文件组织
+
+```text
+<model>_<SN>_<UTC>_<uuid>/
+  session.json
+  stable_means.csv                  # 多点既有兼容输出
+  trials/trial-001/                 # 单次格式，保持不变
+    session.json
+    raw_0001.mp4
+    frames.csv
+    forces.csv
+    reference.csv
+    events.csv
+  sites/<site_id>/repeat-001/        # 多点格式，与 trials 二选一
+    session.json
+    reference.csv
+    events.csv
+    capture/
+      session.json
+      raw_0001.mp4
+      frames.csv
+      forces.csv
+  derived/
+    review_<UTC>_<uuid>/            # 既有 review 快照
+      review.json
+      overview.json                # 现有流程有生成时保留
+      baseline_<trial>.png
+    summary_<UTC>_<uuid>/
+      summary.json
+      summary.html
+      baseline_load_data.csv
+      sensitivity_values.csv
+  summary-latest.json              # 最后成功发布的相对路径指针
+```
+
+不建立第二份录像，不改变两种格式的原始目录。新汇总沿用样例文件名，但明确版本化字段；旧 `stable_means.csv` 保留原接口，不将新表悄悄写成旧表。新读取器缺少指针时仍可打开旧会话，绝不通过修改旧 manifest 补造证据。
+
+导出先在唯一临时目录写齐并验证，再发布同盘目录，最后原子替换指针。失败保留旧指针，报告导出失败，不回滚采集状态。指针使用相对路径、summary_id 和内容哈希；并发发布由会话级单一任务串行化，取消后的旧任务不能更新指针。原始文件、历史 review 和已发布 summary 均不覆盖。
+
+## 录像身份、时间和生命周期
+
+逻辑身份使用 `(calibration_session_id, trial_id, capture_session_id, frame_id)`；保持窗口再加 `step_index`。共享 recorder 的整数 session_id 不等于标定 session_id。同试验来源重启不得静默复用 frame_id；中止并新建 trial。重复身份、行数不符或缺关联必须报错／排除，不能退回按行号拼接。
+
+帧和力按采集 session、frame_id 关联；帧提供 `t_host_mono_ns`、UTC、time_basis 及 `segment/segment_frame`。仅同一次实时采集的 `host_camera` 可与保持窗口 `[start,end)` 比较。UTC 只追溯；`host_replay` 不提供原实验同步，`host_fallback` 标未验证。相机内丢帧与写盘丢帧分别记录。
+
+定位窗口时选择范围内首个已入视频的有效帧；无帧就显示缺失，不跳到窗口外假装有证据。播放与曲线按已保存索引关联，可见时间跳跃；媒体 FPS 只影响容器播放，不用于实验时间换算。关闭／切换 trial 释放 decoder；后台结果以请求代次过滤。
+
+```text
+idle → starting → recording → closing → complete
+           └失败──────┴失败/中止───────→ incomplete
+```
+
+先创建当前 trial 清单，再以显式 trial 引用启动 recorder；禁止用 `trials[-1]` 隐式归属。首个可写入帧及 writer 正常后才允许保持确认。启动失败卸载 sink 并结束 writer；每次 start/stop 清理本会话来源引用，simulation 不继承 live worker。
+
+停止时先移除 sink，再异步排空；到终态后校验 report、帧索引和视频可读性，再更新 repeat 和根清单。步骤完成、录像完成分别保存。至少零帧、写入错误、录像／数据丢失、不可解码、来源停止均阻止“证据完整”；相机来源丢帧单列警告，是否影响实验可用性保留待定，不伪造精度阈值。超时保持 closing/incomplete，不复用仍在写入的目录。
+
+建议为多点 manifest 增加 `capture_status`、`capture_reason`、`capture_report`；只增加可选字段，读取器缺省为 unknown。不要把旧的 `images.captured=true` 当成录像验证成功。版本升级仅在旧读取器实际不兼容时实施并加兼容测试。
+
+## 窗口均值表
+
+`baseline_load_data.csv` 每个实际保持尝试一行；重测不可覆盖前次，使用 trial 内 `hold_id` 区分相同 step。关联键为 session_id、trial_id、hold_id；point 标签只用于展示。映射哈希＋UV 校验点身份，缺哈希时保留来源命名空间，不按 UV 猜测跨 session 同一点。
+
+旧格式的 hold_id 由 reference 文件内数据行序号派生，并与该文件哈希共同固定身份；不回写采集文件。人工裁剪保留 hold_id，只改变选择区间。必须保留原始行号再过滤，不能过滤后重新编号。
+
+| 字段组 | 字段与含义 |
+|---|---|
+| 来源 | `schema_version, summary_id, session_id, trial_id, hold_id, site_id, point, repeat_index, step_index, source_file`；路径相对会话根 |
+| 位置 | `U,V,mapping_sha256`；缺位置为空，不补零 |
+| 载荷 | `reference_source,branch,target_load_n,reference_load_n`；实际参考和目标分开，baseline 标准化为 zero |
+| 时间 | `t_start_host_mono_ns,t_end_host_mono_ns,time_basis,window_method,stability_verified` |
+| 样本 | `samples_total,samples_valid,samples_excluded` 及每轴实际参与统计数；单独统计无效、未关联及无视频帧 |
+| 结果 | `FN_mean,FX_mean,FY_mean,FN_std,FX_std,FY_std,unit`；raw 与 N 不混合 |
+| 状态 | `trial_status,capture_status,review_status,eligible,excluded_reason`；不完整也列出，防止静默遗漏 |
+
+默认自动输出候选后半保持窗口，`window_method=hold_second_half_v1`，不自动认为稳定。人工确认后使用现有 selections 的精确区间，`window_method=review_selection_v1`。统计默认有限且有效的原始分量，样本标准差 ddof=1；不足两样本为空。新表不默默继承旧表按轴去异常值；若以后支持过滤，须另给版本、参数和每轴计数。
+
+候选与已确认数据不混合拟合；同一 trial 的被重测废弃保持段列出原因且排除。正式统计只用完整 trial、可比较时间及明确参考的窗口，缺失数值写空单元格／JSON null。
+
+## 灵敏度表与报告
+
+`sensitivity_values.csv` 每点每 trial 每轴每种审核集合一行；纵向结构允许缺轴。含身份、`component,review_status,method,slope_raw_per_N,intercept_raw,R2,rmse_raw,endpoint_raw_per_N,initial_step_raw,reference_min_N,reference_max_N,window_count,status,reason`。导出保持双精度，不沿用旧表六位有效数字作为计算输入。
+
+方法固定为 `raw_on_reference_ols_v1`：以实际参考 N 为 x，原始窗口均值为 y，在同一 trial 内用初始零载和加载窗口等权拟合 `y=a*x+b`。卸载单独展示，不进入该拟合。至少两个不同参考力，否则 unavailable；不跨 trial 混合不同零点。报告按点汇总合格 trial 斜率的均值、样本标准差和数量，不把它冒充新的联合拟合，不平均 R²。
+
+R² 为 `1-SSE/SST`；常量信号 SST=0 时为空并标记 flat_signal，零斜率不反推增益。endpoint 每 trial 用最高加载与初始零载的差除以参考力差；initial_step 为最低正加载均值减初始零载。跨 trial 只汇总这些量的均值及数量，缺配对或分母为零为空；不跨 trial 拼端点。
+
+现有 `_fit()` 是 `N=gain*raw+offset`，其 `1/gain` 与上述正向 OLS 不一般等价。旧审核拟合不更名、不覆盖；新表明确方法，FN/FX/FY 对法向输入的响应不称为三轴力标定。高 R² 不代表物理精度或独立验证。
+
+`summary.json` 保存版本、源文件 SHA256、review 相对路径／selections 哈希、软件版本、生成 UTC、统计方法、单位、缺失原因和全部表格结果；`formal_conclusion=false`。已复核汇总引用既有 review，不复制一套审核状态；自动候选无需预先创建 review。保存时重验输入哈希，变化则拒绝发布。HTML 只呈现同一份对象，转义操作员输入和路径，无外部网络依赖。
+
+报告首屏显示型号／SN、完成与缺失点数、录像完整性、待复核窗口和导出状态；随后是逐点响应、三分量灵敏度、既有重复性／滞后／留一 trial 验证和证据链接。没有独立验证时明确显示不可用。停止或中止也生成失败摘要；复核变化生成新版本，不改原始数据。