# 录像和操作员汇总数据契约提案 状态：2026-10-17 已按本契约实现，仅软件验证。属于[实施计划](recording-summary-plan.zh.md)；既有采集字段仍以[单次格式](calibration-data-format.zh.md)及[多点格式](multipoint-data-format.zh.md)为准。本页描述的是当前行为，`formal_conclusion` 仍恒为 false。 ## 文件组织 ```text ___/ session.json stable_means.csv # 多点既有兼容输出 trials/trial-001/ # 单次格式，保持不变 session.json raw_0001.mp4 frames.csv forces.csv reference.csv events.csv sites//repeat-001/ # 多点格式，与 trials 二选一 session.json reference.csv events.csv capture/ session.json raw_0001.mp4 frames.csv forces.csv derived/ review__/ # 既有 review 快照 review.json overview.json # 现有流程有生成时保留 baseline_.png summary__/ 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 验证和证据链接。没有独立验证时明确显示不可用。停止或中止也生成失败摘要；复核变化生成新版本，不改原始数据。