51-管线卡 Template v1.0 | 第4章 入站数据与契约（Source/Schema/版本）

目录 ／ 文档-技术白皮书 ／ 51-管线卡 Template v1.0

第4章 入站数据与契约（Source/Schema/版本）

卷名：管线卡 Template v1.0
本节标题：第4章 入站数据与契约（Source/Schema/版本）

I. 目的与范围（Purpose & Scope）

• 统一入站数据源（Source）、**数据契约（Schema/Contract）与版本演进（Versioning/Evolution）**的编制、校验与发布口径，确保跨链路对齐、量纲闭合与可追溯。
• 涉及路径量（到达时/相位）之入站字段，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0 与随附 check_dim_report.json。

II. 数据源定义（Source Definition）

• 来源类型：file/object（分区批文件）、stream（事件/消息队列）、near-rt（共享内存/微批）、api（HTTP/gRPC）。
• 最小元信息：source_id、producer、created_at（ISO-8601）、partition/window、checksum.sha256、signature（可选）。
• 合规前置：上游制品须在 manifest.yaml 内列出 see[]/references[]/version（卷名 + 版本 + 锚点），锚点直指率 ≥ 90%，禁止外链与别名。

III. 入站契约（Inbound Contract / Schema）

1. 与 TARR 对齐：字段命名、单位、量纲与 TARR（数据规范）一致；关键路径字段：
   • path.gamma_ell: array<m>；path.d_ell: array<m>；medium.n_eff_profile: array<1>；
   • ref.c_ref: m/s；（相位类）lambda_ref: m；obs.T_arr: s、obs.Phi: rad（如存在）。
2. 字段规范（最小集合）：
   • 标识：record_id (ULID/UUIDv4)、acq.ts_start/ts_end (ISO-8601)、instrument.id/mode。
   • 质量：quality.flags[]、quality.score_Q (0..1)、uncertainty.*（如可用）。
   • 引用与版本：see[]、references[]、version (SemVer)、checksum。
3. 单位与量纲：所有数值字段附 unit 或在契约中明确；含除号/积分/复合算符的表达必须加括号。
4. 缺失策略：以 null 或缺字段表示缺失；禁止使用文本 NaN/Inf；缺失原因写入 quality.flags。

IV. 模式演进（Schema Evolution）

1. 兼容矩阵：
   • 向后兼容新增（MINOR）：只增字段，旧消费者不破坏；
   • 非兼容变更（MAJOR）：字段语义/单位/量纲改变或删除字段；
   • 修补（PATCH）：默认值/描述修正，不改语义。
2. 版本标注：入站数据包与 schema.json 顶层均携带 version (SemVer)；manifest.yaml 中同步。
3. 迁移策略：MAJOR 改动需提供显式映射/换算（示例：rad = deg * π/180）与回滚方案。

V. 校验流程（Validation Pipeline，Mx-?）

• Schema 校核（G1）：字段存在性/类型/必填；分区/窗口对齐与索引一致。
• 引用合规（G2）：see[]/references[] 满足锚点直指率 ≥ 90%；禁止外链/别名。
• 路径规范（G3）：gamma(ell)/d ell/delta_form 齐备；len(gamma_ell)=len(d_ell)=len(n_eff)≥2，Δell 满足采样约束。
• 量纲闭合（G4）：I70-dim_check 通过；导出 check_dim_report.json；p_dim = 1.0。
• 新鲜度（G5）：clock_state="locked"，|ts_start − calib.timestamp| ≤ τ_calib。
• 覆盖口径（G6）：若含不确定度字段，coverage ∈ {k, alpha, quantile} 且与发布一致。
• 协方差一致（G7）：cov_group 与核参数与误差预算卡第 5 章一致；Σ 正定。
• 唯一性（G8）：record_id 与 checksum 不重复；审计轨迹完备。

VI. 机读契约（Machine-Readable Contracts）
A. schema.json（节选）

{

"$schema":"https://json-schema.org/draft/2020-12/schema",

"title":"Inbound v1.0.0",

"type":"object",

"required":["record_id","acq","path","medium","ref","version","see"],

"properties":{

"record_id":{"type":"string"},

"acq":{"type":"object","required":["ts_start","ts_end"],

"properties":{"ts_start":{"type":"string","format":"date-time"},"ts_end":{"type":"string","format":"date-time"}}},

"path":{"type":"object","required":["gamma_ell","d_ell"],

"properties":{"gamma_ell":{"type":"array","items":{"type":"number"},"minItems":2},

"d_ell":{"type":"array","items":{"type":"number"},"minItems":2}}},

"medium":{"type":"object","required":["n_eff_profile"],

"properties":{"n_eff_profile":{"type":"array","items":{"type":"number"},"minItems":2}}},

"ref":{"type":"object","required":["c_ref"],"properties":{"c_ref":{"type":"number"}}},

"see":{"type":"array","items":{"type":"string"},"minItems":1},

"version":{"type":"string"}

}

}

B. contract.yaml（入站契约说明）

version: "1.0.0"

source:

id: "SRC-telemetry-rt"

mode: "streaming" # file|streaming|near-rt|api

schema: "schemas/inbound/schema.json"

units:

c_ref: "m/s"

T_arr: "s"

Phi: "rad"

path:

required: true

delta_form: "general"

quality_gates: ["G1","G2","G3","G4","G5","G6","G7","G8"]

C. manifest.yaml（入站制品清单）

dataset_id: "ptn-ingest-202509"

version: "1.0.0"

created_at: "2025-09-24T16:00:00Z"

producer: "pipeline.ingest"

see:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

checksum: { algo: "sha256", value: "<64-hex>" }

VII. 反例与修正（Anti-Patterns & Fixes）

• 反例：缺 d ell 或未声明 delta_form 的路径数据；修正：补足 gamma/measure/delta_form 并对齐 n_eff 长度。
• 反例：单位以文本 % 表示；修正：单位用 1，并在 notes 中说明“百分比”。
• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号）；修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：引用无版本/锚点；修正：改为 见《EFT.WP.Core.Equations v1.1》Ch.2 S20-1。

VIII. 校验与告警（Validation & Alerts）

• /validate 返回每批/每窗口的 G1–G8 结果与 stops（S1–S5）触发信息；维度闭合以 check_dim_report.json 为准。
• 告警事件：Schema 破坏、锚点直指率不足、p_dim < 1、clock_state != locked、协方差非 PD、路径不一致。
• 审计：audit.jsonl 逐事件记录时间戳、操作者、输入哈希、seed、决策与签名。

IX. 发布与目录结构（Release & Layout）

PTN_EXPORT/

inbound/

contract.yaml

schema.json

data/

*.parquet

reports/

check_dim_report.json

validate_report.json

audit.jsonl

manifest.yaml

SIGNATURE.asc

X. 交叉引用（Cross-References）

• 体系结构与计算图：见第3章；
• 时基、同步与缓冲：见第5章；
• 阶段定义与控制式：见第6章；
• 质量门与监控：见第9章；
• 参数/误差/协议模板：分别见参数注册卡第9章、误差预算卡第5/6/8/9章、实验协议卡第5章。

XI. 执行勾选清单（Checklist）

• contract.yaml / schema.json / manifest.yaml 齐备并一致；see[]/references[] 合规且锚点直指率 ≥ 90%。
• 路径字段显式 gamma(ell)/d ell，delta_form 已记录；len(path) ≥ 2、Δell 合规。
• I70-dim_check 通过、p_dim = 1.0；新鲜度 clock_state="locked"、τ_calib 合规。
• 覆盖口径与 U = k·u_c/分位带一致；cov_group 与误差预算卡一致、Σ 正定。
• /validate 通过 G1–G8，无 S1–S5；入站制品含 checksum 与签名。