06-EFT.WP.Core.DataSpec v1.0 | 第2章 模式与字段字典

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

第2章 模式与字段字典

I. 类型系统与基本约束

• 基本标量类型：int32、int64、float32、float64、decimal(p,s)、bool、string、bytes。
• 时间与标识类型：timestamp(UTC)（简称 ts）、date、time、rid、uid、sid、tid、pid。
• 结构化类型：array<T>、vector<T,k>、matrix<T,m,n>、struct{...}、geom{Point|LineString}（需声明 CRS）。
• 量与计量绑定：任一物理量字段以 unit(field_i) 与 dim(field_i) 绑定；unit="1" 表示无量纲。
• 约束基元：nullable(field_i) ∈ {True, False}、default(field_i)、range[min,max]、regex、enum{...}、unique、foreign_key。
• 排序与窗口：时间序列须 ORDER BY ts 非降；窗口以 [t0, t1) 与 Delta_t = t1 - t0 定义。
• 路径一致：路径数据以 gamma(ell) 参量化，ell 单调不减；L_gamma = ( ∫_gamma 1 d ell ) 用于区间校核。

II. 字段词条结构与注册流程

1. 字段词条最小集合：
   name、desc、type、unit、dim、nullable、default、aliases、roles、see。
2. 词条命名规则：使用 snake_case、ASCII、小写；量纲与单位不出现在 name，仅出现在 unit 与 dim。
3. 角色标注：roles ⊆ {key,time,geom,measure,quality,mask,meta,index}。
4. 注册流程（对应 I60）：
   • 使用 register_field(name, type, unit, dim, desc, aliases) 建立词条；
   • register_schema(name, version, fields, constraints, units, pk, idx, see) 组装模式；
   • 以 validate_dataset(schema, ds, strict=True) 校验落盘数据；
   • 以 export_schema(SRef,"yaml") 出版并冻结。

III. 单位与量纲绑定规范

1. 绑定要求：
   • 任一参与方程的字段必须给出 unit(·) 与 dim(·) 并通过 check_dim( y - f(x; theta) )。
   • 只允许仿射单位转换：v_to = a * v_from + b，其中 b ≠ 0 仅用于零点偏移（如 degC ↔ K）。
   • 在规范 t0 = L0 / c_ref 下，被积项 ( n_eff / c_ref ) * d ell 可写作 bar_n_eff * d bar_ell 且视为无量纲，其中 bar_n_eff = n_eff，d bar_ell = d ell / L0。
2. 到达时两口径字段绑定：
   • 常量外提：T_arr = ( 1 / c_ref ) * ( ∫_gamma n_eff d ell )。
   • 一般口径：T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell )。
   • 差异度量：delta_form = | ( 1 / c_ref ) * ( ∫_gamma n_eff d ell ) - ( ∫_gamma ( n_eff / c_ref ) d ell ) |。

IV. 可空性、默认与缺失策略

• 缺失标注：缺失以 m ∈ {0,1} 表示，其中 m=0 为缺失；禁止以哑值替代缺失。
• 默认值：仅用于语义上“可推导或不影响量纲守恒”的字段；默认值需符合 unit 与 dim。
• 插补记录：若进行插补或环境修正，派生字段写作 corr_env(x; RefCond) 并在 manifest 中记录 RefCond = { p_ref, Temp_ref, humidity_ref } 与不确定度 u(·)。

V. 标准字段字典（示例 40 条）

• FD.core.uid — type=string, unit="1", dim="1", nullable=False, roles={key}, desc=universal id。
• FD.core.rid — type=string, unit="1", dim="1", nullable=False, roles={key,meta}, desc=record id。
• FD.core.sid — type=string, unit="1", dim="1", nullable=True, roles={key}, desc=site id。
• FD.core.tid — type=string, unit="1", dim="1", nullable=True, roles={key}, desc=trajectory id。
• FD.path.pid — type=string, unit="1", dim="1", nullable=False, roles={key}, desc=path id (= gamma id)。
• FD.time.ts — type=timestamp(UTC), unit="s", dim="[T]", nullable=False, roles={time}, desc=event time。
• FD.time.ts_start — type=timestamp(UTC), unit="s", dim="[T]", nullable=True, roles={time}, desc=window start。
• FD.time.ts_end — type=timestamp(UTC), unit="s", dim="[T]", nullable=True, roles={time}, desc=window end。
• FD.time.delta_t — type=float64, unit="s", dim="[T]", nullable=True, roles={measure}, desc=window width。
• FD.time.fs — type=float64, unit="Hz", dim="[T]^-1", nullable=True, roles={measure}, desc=sample rate。
• FD.geo.lon — type=float64, unit="deg", dim="1", nullable=True, roles={geom}, desc=WGS84 longitude。
• FD.geo.lat — type=float64, unit="deg", dim="1", nullable=True, roles={geom}, desc=WGS84 latitude。
• FD.geo.alt — type=float64, unit="m", dim="[L]", nullable=True, roles={geom}, desc=altitude AMSL。
• FD.cart.x — type=float64, unit="m", dim="[L]", nullable=True, roles={geom}, desc=Cartesian x。
• FD.cart.y — type=float64, unit="m", dim="[L]", nullable=True, roles={geom}, desc=Cartesian y。
• FD.cart.z — type=float64, unit="m", dim="[L]", nullable=True, roles={geom}, desc=Cartesian z。
• FD.geo.crs — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=coordinate reference system。
• FD.path.ell — type=float64, unit="m", dim="[L]", nullable=False, roles={key,measure}, desc=path coordinate。
• FD.path.l_gamma — type=float64, unit="m", dim="[L]", nullable=True, roles={measure}, desc=L_gamma = ( ∫_gamma 1 d ell )。
• FD.optics.n_eff — type=float64, unit="1", dim="1", nullable=True, roles={measure}, desc=effective refractive index。
• FD.optics.c_ref — type=float64, unit="m s^-1", dim="[L][T]^-1", nullable=False, roles={measure,meta}, desc=reference speed。
• FD.arrival.t_arr — type=float64, unit="s", dim="[T]", nullable=True, roles={measure}, desc=arrival time。
• FD.arrival.delta_form — type=float64, unit="s", dim="[T]", nullable=True, roles={quality}, desc=formulation difference。
• FD.env.temp_ref — type=float64, unit="K", dim="[Temp]", nullable=True, roles={meta}, desc=reference temperature。
• FD.env.p_ref — type=float64, unit="Pa", dim="[M][L]^-1[T]^-2", nullable=True, roles={meta}, desc=reference pressure。
• FD.env.humidity_ref — type=float64, unit="1", dim="1", nullable=True, roles={meta}, desc=relative humidity。
• FD.meas.u_x — type=float64, unit="same_as(x)", dim="dim(x)", nullable=True, roles={quality}, desc=standard uncertainty of x。
• FD.meas.U_x — type=float64, unit="same_as(x)", dim="dim(x)", nullable=True, roles={quality}, desc=expanded uncertainty of x。
• FD.quality.m — type=int8, unit="1", dim="1", nullable=False, roles={mask}, desc=missingness mask ∈ {0,1}。
• FD.quality.q_score — type=float32, unit="1", dim="1", nullable=True, roles={quality}, desc=quality score ∈ [0,1]。
• FD.quality.drift — type=float32, unit="1", dim="1", nullable=True, roles={quality}, desc=drift indicator。
• FD.trace.source — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=origin source。
• FD.trace.method — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=process method。
• FD.trace.artifact — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=produced artifact。
• FD.trace.checksum_sha256 — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=hash_sha256(blob)。
• FD.trace.signature — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=signature。
• FD.stats.r — type=float64, unit="same_as(y)", dim="dim(y)", nullable=True, roles={measure}, desc=residual r = y - f(x; theta)。
• FD.stats.r_bar — type=float64, unit="1", dim="1", nullable=True, roles={quality}, desc=normalized residual r_bar = r / sigma。
• FD.stats.w — type=float64, unit="1", dim="1", nullable=True, roles={quality}, desc=weight w。
• FD.stats.chi2 — type=float64, unit="1", dim="1", nullable=True, roles={quality}, desc=chi2 = r^T R r。
• FD.stats.R2 — type=float32, unit="1", dim="1", nullable=True, roles={quality}, desc=coefficient of determination。
• FD.stats.SNR_dB — type=float32, unit="dB", dim="1", nullable=True, roles={quality}, desc=signal-to-noise ratio。
• FD.labels.tag — type=string, unit="1", dim="1", nullable=True, roles={meta}, desc=free-form tag。
• FD.release.schema_version — type=string, unit="1", dim="1", nullable=False, roles={meta}, desc=semantic version。
• FD.release.fmt — type=string, unit="1", dim="1", nullable=False, roles={meta}, desc=serialization format。

VI. 复合类型与结构化字段

• 结构化向量：
  加速度三分量以标量展开：ax, ay, az，而非 vector<float64,3> 落盘；各分量分别声明 unit="m s^-2", dim="[L][T]^-2"。
• 矩阵与雅可比：
  雅可比条目以扁平命名：J_y_xi 表示 ∂y/∂x_i；单位与量纲以 unit(J_y_xi) = unit(y) / unit(x_i)、dim(J_y_xi) = dim(y) * dim(x_i)^-1 绑定。
• 几何类型：
  geom{Point} 字段用于索引与空间查询，但落盘冗余 lon,lat,alt 以便跨系统互操作；CRS 必填。

VII. 契约与验证映射

• 唯一性：unique(pk)、unique(pid, ell)、unique(uid, ts)。
• 单调性：non_decreasing(ts)、non_decreasing(ell)。
• 合法范围：range(lon, -180, 180)、range(lat, -90, 90)、range(q_score, 0, 1)。
• 量纲守恒：check_dim( y - f(x; theta) )。
• 到达时一致性：delta_form ≤ tol_Tarr。
• 缺失一致：m ∈ {0,1} 且 m=0 ⇒ value is NULL。
• 参考条件显式：涉及 corr_env(·; RefCond) 的字段要求 RefCond 存在。

VIII. 索引与排序规范

1. 必备索引：
   • 时间序列：idx(ts) 与复合 idx(uid, ts)。
   • 路径序列：idx(pid, ell)；可选空间索引 idx(lon, lat)。
2. 排序保存：落盘与导出均以主键顺序或 (pid, ell)、(uid, ts) 顺序输出，保证幂等重放。

IX. 到达时数据集的绑定要点

1. 必备字段集：pid、ell、n_eff（若可得）、c_ref、ts（若时变）与几何字段、CRS。
2. 计算与核验：
   • 以选定口径计算 T_arr；
   • 计算 delta_form 并与阈值比较；
   • 以 check_dim 校验 T_arr 的 dim("[T]")；
   • 将 RefCond 与路径测度 d ell 写入 manifest。

X. 模式演进与兼容性策略

1. 版本语义：major 破坏性、minor 向后兼容、patch 文档与元数据修订。
2. 演进规则：
   • 字段重命名：保留旧名于 aliases 至少一个发布周期，并在 diff_datasets 给出映射。
   • 新增字段：默认必须 nullable=True 或具备 default。
   • 删除字段：major+1，并在 import_manifest 提供兼容适配层。

XI. 字段词条模板（文本）

XII. 单位/量纲绑定示例（20 例）

• ts -> unit="s" | dim="[T]"
• ell -> unit="m" | dim="[L]"
• lon -> unit="deg" | dim="1"
• lat -> unit="deg" | dim="1"
• alt -> unit="m" | dim="[L]"
• fs -> unit="Hz" | dim="[T]^-1"
• delta_t -> unit="s" | dim="[T]"
• n_eff -> unit="1" | dim="1"
• c_ref -> unit="m s^-1" | dim="[L][T]^-1"
• t_arr -> unit="s" | dim="[T]"
• l_gamma -> unit="m" | dim="[L]"
• q_score -> unit="1" | dim="1"
• m -> unit="1" | dim="1"
• temp_ref -> unit="K" | dim="[Temp]"
• p_ref -> unit="Pa" | dim="[M][L]^-1[T]^-2"
• r -> unit="same_as(y)" | dim="dim(y)"
• r_bar -> unit="1" | dim="1"
• chi2 -> unit="1" | dim="1"
• SNR_dB -> unit="dB" | dim="1"
• checksum_sha256 -> unit="1" | dim="1"

XIII. 与实现接口（I60-*) 的对照清单

• register_field 与本章词条模板一一对应；
• register_schema 组合 fields、pk、idx、constraints 并固化 units；
• validate_dataset 映射到 VII 的契约集合；
• bind_to_equations 用 see=[Sxx-?, Pxx-?] 追踪绑定；
• enforce_arrival_time_convention 生成并校验 delta_form；
• export_schema、export_manifest 形成可审计发布工件。