08-EFT.WP.Core.Sea v1.0 | 附录E 接口参考（I80）

目录 ／ 文档-技术白皮书 ／ 08-EFT.WP.Core.Sea v1.0

附录E 接口参考（I80）

I. 适用范围与版本

• 本附录定义 I80 接口族之统一口径，覆盖：设备与标定、采样与同步、调理与滤波、频谱与特征、环境修正与不确定度、到达时与路径、质量与漂移、数据落盘与清单。
• 版本标识：api_version = "I80.1.0"；语义化版本，破坏性变更提升主版本。
• 时间基准：内部计算一律以 tau_mono，对外发布用 ts；模型同本卷第3章。
• 变量、公式与单位：一律英文与纯文本；维度守恒用 check_dim(expr) 核验。

II. 通用类型与返回约定

1. 结果封装
   • Result<T> = { ok:bool, data:T|None, error:Error|None, meta:dict }
   • Error = { code:str, message:str, detail:dict|None }，code ∈ {"INVALID_ARG","NOT_FOUND","FAILED_PRECONDITION","OUT_OF_RANGE","ALREADY_EXISTS","CONFLICT","UNAVAILABLE","DEADLINE_EXCEEDED","INTERNAL","NOT_IMPLEMENTED"}
2. 基本引用
   • SnsRef = { sid:str, model:str, serial:str, cal_id:str|None }
   • CalRef = { cal_id:str, sid:str, date:str, coeff:{ "A_gain":float, "B_bias":float, "C_offset":float }, RefCond:dict }
   • SyncRef = { clock_id:str, sync_ref:str, alpha:float, beta:float, u_alpha:float, u_beta:float }（见第3章）
   • FiltRef = { fid:str, kind:str, Hf:dict, f_c:float|None, BW:float|None, group_delay:float|None }（见第4章）
3. 数据与谱对象
   • Trace = { ts:int64[], tau_mono:float[], x:float[], fs:float, window:str|None }
   • PSD = { f:float[], S_xx:float[], method:str, window:str, U_w:float, ENBW_Hz:float, nu_eff:float }（见第5章与附录D）
   • FeatMap = { name:str, values:dict }
   • Manifest = { fmt:str, chan:str, fs:float, blocks:int, compress:str|None, hash:str, RefCond:dict, created_ts:str }
4. 约束字段
   缺失掩码：m ∈ {0,1}；质量分：q_score ∈ [0,1]；漂移：drift:dict（见第9章）。

III. 一般规范与副作用

1. 纯函数与副作用
   • 纯函数：fft、psd、feature_extract、path_integral 不修改入参。
   • 有副作用：register_sensor、configure_sampling、sync_clocks、raise_alert、serialize、export_manifest。
2. 可重现性
   任何随机或数值近似步骤需在 meta.seed 与 meta.eps 中记录；所有输出需回填 RefCond（见第6章）。
3. 线程与实时
   实时路径以 tau_mono 排序；跨设备并发操作需保证 sid 去重与幂等。

IV. I80 1 设备注册与标定

1. register_sensor(model:str, serial:str, meta:dict) -> SnsRef
   • 预置：model != ""，serial != ""。
   • 结果：新建 sid；meta 正规化并存档。
   • 备注：若已存在相同 (model,serial) 返回 ALREADY_EXISTS 或返回已存在 SnsRef（由实现策略决定）。
2. load_calibration(sid:str, cal_id:str) -> CalRef
   • 预置：sid 存在；cal_id 可解析。
   • 结果：返回标定系数与 RefCond。
3. apply_calibration(raw:any, cal:CalRef) -> data
   • 语义：标量线性模型 y = A_gain * x + B_bias + C_offset，或按 cal.model 指定的更高阶模型。
   • 结果：返回带单位的数据及 RefCond 回填。
   • 交叉引用：见本卷第1章与附录B。

V. I80 2 采样与同步

1. configure_sampling(sid:str, fs:float, gain:float|None=None) -> None
   预置：fs > 0；若 fs < 2 * f_max，需在 meta 中声明 H(f) 抗混叠策略（见第2章、第4章）。
2. sync_clocks(sids:list[str], method:str="ptp", ref:str|None=None) -> SyncRef
   • 语义：根据方法估计 alpha（skew）与 beta（offset），模型 ts_i(t) = alpha_i * tau_mono + beta_i。
   • 结果：回填 u_alpha、u_beta。
3. measure_skew_offset(sids:list[str], window:float) -> dict
   • 返回：{ sid: { "alpha":float, "beta":float, "u_alpha":float, "u_beta":float, "J":float } }（J 为抖动估计）。
   • 备注：window >= 10 / fs 为建议下界；见第3章。

VI. I80 3 调理与滤波

1. design_filter(kind:str, params:dict) -> FiltRef
   • kind ∈ {"FIR","IIR","notch","lp","hp","bp","bs"}；params 含 f_c、BW、order、ripple 等。
   • 结果：返回 Hf 采样、group_delay（例如 FIR：(N-1)/(2*fs)）。
2. filter_apply(sig:any, filt:FiltRef) -> any
   • 语义：零相位（离线）可用前后向；实时路径需记录相位特性与群时延补偿。
   • 能量守恒：滤波后 PSD 需在 ENBW_Hz 语境下校核（见附录C、D）。
3. resample(sig:any, fs_target:float, mode:str="polyphase") -> any
   预置：需自动插入抗混叠 H(f)；报告 Delta_f、插值阶次与残余混叠估计。

VII. I80 4 频谱与特征

1. fft(sig:any, window:str="hann") -> complex[]
   输出：X_w[k] 与 meta = { "CG":float, "U_w":float }。
2. psd(sig:any, method:str="welch", seg:int=8, overlap:float=0.5) -> PSD
   • 单侧口径：S_xx[k] = ( 2 / ( fs * N * U_w ) ) * |X_w[k]|^2；端点不乘 2（见附录D）。
   • 返回：nu_eff、ENBW_Hz、window。
3. feature_extract(sig:any, feats:list[str]) -> FeatMap
   • feats ⊂ {"f_centroid","BW_rms","peak_f","gamma_xy2","kurt","skew","THD","SNR"}。
   • 备注：SNR、THD 需说明估计窗与带宽。

VIII. I80 5 环境修正与不确定度

1. apply_env_correction(data:any, ref:dict) -> any
   • 语义：应用 corr_env(x; RefCond)；ref 明确包含 RefCond 与模型标识。
   • 结果：输出含 RefCond 与修正残差统计。
2. propagate_uncertainty(values:dict, model:str) -> dict
   线性传播：u_c^2 = J * cov * J^T；合成不确定度 U = k * u_c，在 meta 中写入 k 与覆盖因子来源（见第6章）。

IX. I80 6 到达时与路径

1. estimate_toa(sig:any, method:str="xcorr") -> float
   • 语义：tau_hat = argmax_tau r_xy[tau]；可选亚样点抛物线细化。
   • 返回：tau_hat（单位 s）与 q_score。
2. path_integral(n_eff:any, gamma:any, c_ref:float) -> float
   • 两口径：
     1. T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
     2. T_arr = ( ∫ ( n_eff / c_ref ) d ell )
   • 结果：返回 T_arr 与 delta_form 报告：
     delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |
3. enforce_arrival_time_convention(trace:any) -> None
   语义：统一 trace 的到达时标注与 tau_mono/ts 对齐；写入审计字段。

X. I80 7 质量、漂移与告警

1. quality_metrics(data:any) -> dict
   返回：{ "q_score":float, "missing_rate":float, "MAD":float, "sigma_robust":float }；sigma_robust = 1.4826 * MAD。
2. monitor_drift(baseline:any, current:any, fields:list[str]) -> dict
   • 语义：计算窗口均值差与稳健标度：drift_score = | mu_window - mu_ref | / sigma_robust。
   • 返回：按字段列出 drift_score、p_value（若适用）与阈值建议。
3. raise_alert(kind:str, payload:dict) -> None
   kind ∈ {"q_drop","drift","sync_loss","env_out_of_range","storage_fail"}；payload 持久化到 manifest.audit。

XI. I80 8 数据落盘与清单

• serialize(data:any, fmt:str="parquet", compress:str|None=None) -> bytes
  fmt ∈ {"jsonl","csv","parquet","nc","tfrecord"}；返回字节流，meta 写入校验和与块化策略。
• export_manifest(data:any) -> dict
  必填：fmt、chan、fs、blocks、compress、hash、RefCond、api_version、window、ENBW_Hz（若含谱数据）。
• import_manifest(manifest:dict) -> any
  语义：复原管线上下文与 RefCond；FAILED_PRECONDITION 表示缺失必要字段。

XII. 参数与单位统一（核对清单）

• 采样与时间：fs [Hz]，Delta_t [s]，ts [UTC s]，tau_mono [s]。
• 频谱：f [Hz]，S_xx [unit^2/Hz]，ENBW_Hz [Hz]，nu_eff [-]。
• 滤波：f_c [Hz]，BW [Hz]，group_delay [s]。
• 到达时：T_arr [s]，c_ref [m/s]，n_eff [-]，gamma(ell) [m]。
• 质量与统计：q_score [-]，MAD [unit]，sigma_robust [unit]。

XIII. 典型调用序列（可执行指引）

1. 设备与标定
   • sns = register_sensor(model, serial, meta)
   • cal = load_calibration(sns.sid, cal_id)
   • data = apply_calibration(raw, cal)
2. 采样与同步
   • configure_sampling(sns.sid, fs)
   • sync = sync_clocks([sns.sid], "ptp", ref)
   • stats = measure_skew_offset([sns.sid], window)
3. 调理与频谱
   • filt = design_filter("lp", { "f_c": f_c, "order": N })
   • x_f = filter_apply(data, filt)
   • P = psd(x_f, "welch", seg=8, overlap=0.5)
   • feats = feature_extract(x_f, ["f_centroid","BW_rms","SNR"])
4. 环境与不确定度
   • x_corr = apply_env_correction(x_f, RefCond)
   • u = propagate_uncertainty({ "x": x_corr }, "linear")
5. 到达时与路径
   • tau_hat = estimate_toa(x_corr, "xcorr")
   • T = path_integral(n_eff, gamma, c_ref)
   • enforce_arrival_time_convention(trace)
6. 质量与入湖
   • qm = quality_metrics(x_corr)
   • dr = monitor_drift(baseline, x_corr, fields)
   • blob = serialize(x_corr, "parquet", "zstd")
   • mani = export_manifest(x_corr)

XIV. 合规与审计字段（最低集）

• audit = { "api_version":"I80.1.0", "ts_export":ts, "seed":int|None, "RefCond":dict, "window":str, "U_w":float|None, "ENBW_Hz":float|None, "nu_eff":float|None, "alpha":float|None, "beta":float|None, "u_alpha":float|None, "u_beta":float|None }
• 任一函数若涉及 T_arr，必须同时记录 gamma(ell) 描述、d ell 采样策略、c_ref、n_eff 来源与 delta_form。

XV. 退避与性能建议

• 频谱：当 seg > 16 或 overlap > 0.75 时，优先降采样后再估计，以控制 nu_eff 与计算量平衡。
• 滤波：FIR 采用多相或 FFT 卷积；IIR 实时路径需报告相位失真与 tau_g 补偿。
• 同步：抖动主导场景优先加大 window；偏移主导场景优先提升对齐事件密度。

XVI. 跨卷引用样式（固定写法）

XVII. 结束语