ykcheungab
8.5 KiB
录像和操作员汇总数据契约提案
状态：2026-10-17 已按本契约实现，仅软件验证。属于实施计划；既有采集字段仍以单次格式及多点格式为准。本页描述的是当前行为，formal_conclusion 仍恒为 false。
文件组织
<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；后台结果以请求代次过滤。
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 混合不同零点。
sensitivity_summary 按测点、分量和 review_status 分组，分别汇总候选／已确认 trial 斜率的均值与样本标准差，trials 统计唯一 trial_id；不混合两种审核集合、不计算联合拟合或平均 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 验证和证据链接。没有独立验证时明确显示不可用。停止或中止也生成失败摘要；复核变化生成新版本，不改原始数据。