47-PTN Template v1.0 | 第5章 数据规范与管线契约

目录 ／ 文档-技术白皮书 ／ 47-PTN Template v1.0

第5章 数据规范与管线契约

I. 字段表（Field Dictionary）

统一要求：字段名用蛇形命名；内联符号一律使用反引号；凡涉及路径相关量必须显式 gamma(ell) 与测度 d ell；所有数量带单位字段均需在同级或元数据中声明 unit。

1. 核心观测与路径

• record_id｜主键｜string｜全局唯一 ID（ULID/UUIDv4）。
• acq.ts_start｜开始时间｜string（ISO8601，含时区）。
• acq.ts_end｜结束时间｜string（ISO8601，含时区）。
• path.gamma_ell｜路径参数化｜array[number]｜路径坐标离散序列；配对 path.d_ell。
• path.d_ell｜测度步长｜array[number]｜与 gamma(ell) 同长度；单位 m。
• medium.n_eff_profile｜n_eff 序列｜array[number]｜沿路径的有效折射率；无量纲。
• ref.c_ref｜c_ref｜number｜参考传播上限；单位 m/s。
• obs.T_arr｜T_arr｜number｜到达时；单位 s；需记录 delta_form。
• obs.Phi｜Phi｜number｜相位累计；单位 rad；需提供 lambda_ref。
• lambda_ref｜参考波长｜number｜单位 m；与 Phi 成对出现。

2. 仪器与标定

• instrument.id｜设备 ID｜string。
• instrument.mode｜观测模式｜string（枚举：imaging|spectral|timing|mixed）。
• calib.version｜标定版本｜string（SemVer）。
• calib.timestamp｜标定时间｜string（ISO8601）。
• calib.theta｜标定参数｜object（键值对，含单位）。

3. 误差与质量

• uncertainty.obs_T_arr｜u(T_arr)｜number｜标准不确定度；单位 s。
• uncertainty.obs_Phi｜u(Phi)｜number｜单位 rad。
• noise.model｜噪声模型｜string（枚举：gaussian|student|huber|custom）。
• quality.flags｜质量标志｜array[string]（如 geometry_ok，calib_fresh）。
• quality.score_Q｜Q｜number（0–1）。

4. 依赖、引用与版本

• see｜内联引用｜array[string]（例如 "EFT.WP.Core.Equations v1.1:S20-1"）。
• references｜外部引用｜array[string]（发布清单专用）。
• version｜数据对象版本｜string（SemVer）。
• checksum.sha256｜校验和｜string（64 hex）。
• signature｜发布签名｜string（可选，CMS/PGP）。

II. 取值域与单位（Domains, Units & Constraints）

1. 基本约束

• obs.T_arr 与 path.d_ell、medium.n_eff_profile、ref.c_ref 必须同条记录内齐备；n_eff 无量纲，d_ell 为 m，c_ref 为 m/s，T_arr 为 s。
• path.gamma_ell.length = path.d_ell.length = medium.n_eff_profile.length ≥ 2。
• 时间戳统一 ISO8601（例如 2025-09-24T14:08:00Z 或带时区偏移）。

2. 取值域

• ref.c_ref ∈ (2.9e8, 3.1e8)；medium.n_eff_profile[i] ∈ (0.8, 2.5)（工程上限，可按领域覆写）。
• quality.score_Q ∈ [0,1]；noise.model ∈ {gaussian,student,huber,custom}。
• lambda_ref > 0；若 obs.Phi 存在，则 lambda_ref 必填。

3. 缺失与异常

• 数值缺失统一 null（JSON）或省略字段；禁止使用 NaN/Inf 文本。
• 异常点通过 quality.flags 标注，严禁以删除代替标注；剔除规则在分析计划中预注册。

4. 量纲校核

• 所有计算字段需有 unit 元数据或在 see 中指向量纲校核锚点；交付时附 check_dim_report。

III. 质量门与审计轨（Quality Gates & Audit Trail）

1. 质量门（按执行顺序）

• G1｜Schema 校验：字段存在性、类型、必填约束通过。
• G2｜引用合规：see 与 references 均为“卷名 + 版本 + 锚点（P/S/M/I）”，覆盖率 ≥ 90%。
• G3｜路径-测度完整：gamma(ell) 与 d ell 成对，长度≥2，且与 n_eff_profile 同步。
• G4｜量纲闭合：T_arr = ( ∫ ( n_eff / c_ref ) d ell ) 维度为 s；相位累计维度为 rad。
• G5｜标定新鲜度：acq.ts_start - calib.timestamp ≤ τ_calib（由领域规定）。
• G6｜噪声残差门：拟合残差 Q_res 在容许带内；稳健方案需报告等价二阶代理。
• G7｜守恒一致性：ε_flux 满足 O(θ^2)；ΔM ≤ τ_M（若适用）。
• G8｜重复与唯一性：record_id 唯一，checksum.sha256 不重复。

2. 审计轨

• audit.run_id（ULID）、audit.started_at/ended_at（ISO8601）、audit.tools（版本列表）、audit.random_seeds、audit.input_hashes[]、audit.operator。
• 每次运行生成 audit.jsonl，包含参数快照、references[]、version 与质量门通过状态。

IV. 导出与发布（Export & Release）

1. 导出清单（必须包含）

• manifest.yaml：含 dataset_id、version、references[]、see[]、created_at、producer、checksum、licenses（如适用）。
• schema.json：JSON Schema（见下例）。
• check_dim_report.json：量纲校核结果。
• quality_report.json：质量门通过/失败详情与指标。

2. 目录结构（建议）

PTN_EXPORT/

manifest.yaml

data/

observations.parquet

paths.parquet

schema/

schema.json

reports/

check_dim_report.json

quality_report.json

audit.jsonl

README.md

SIGNATURE.asc

3. 文件命名

• dataset_id-version-date.ext（例如 ptn-demo-1.0.0-20250924.parquet）；哈希后缀可追加 +sha.<8>。

4. 发布级别

• internal｜内部流转；public｜对外发布（仅引用 v1.* 稳定线）。

V. 机读契约示例（可直接复用）

A. manifest.yaml

dataset_id: "ptn-demo"

version: "1.0.0"

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

producer: "PTN.Workgroup.Core"

see:

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

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

- "EFT.WP.Core.DataSpec v1.0:TARR"

references:

- "EFT.WP.Core.Terms v1.0:P10-3"

checksum:

algo: "sha256"

value: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

licenses:

- "CC-BY-4.0"

release_tier: "public"

B. schema.json（节选）

{

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

"title": "PTN Data Object v1.0.0",

"type": "object",

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

"properties": {

"record_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$|^[0-9a-fA-F-]{36}$" },

"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", "minimum": 2.9e8, "maximum": 3.1e8 }

}

},

"obs": {

"type": "object",

"properties": {

"T_arr": { "type": "number" },

"Phi": { "type": "number" }

}

},

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

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

"version": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:[-+].*)?$" }

},

"allOf": [

{ "properties": {

"path": { "properties": { "gamma_ell": { "minItems": { "$data": "1/path/d_ell/minItems" } } } }

}

}

]

}

C. pipeline.yaml（处理管线契约）

version: "1.0.0"

pipeline:

- id: step-10-ingest

in: ["raw/*.parquet"]

out: ["stage/ingested.parquet"]

checks: ["G1","G8"]

- id: step-20-calibrate

in: ["stage/ingested.parquet"]

out: ["stage/calibrated.parquet"]

checks: ["G5"]

- id: step-30-arrival

in: ["stage/calibrated.parquet"]

out: ["stage/arrival.parquet"]

compute:

form: "T_arr = ( ∫ ( n_eff / c_ref ) d ell )"

requires: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.c_ref"]

delta_form: "general"

checks: ["G3","G4"]

see:

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

- id: step-40-noisefit

in: ["stage/arrival.parquet"]

out: ["stage/denoised.parquet","reports/noise.json"]

model: "huber"

checks: ["G6"]

- id: step-50-exports

in: ["stage/denoised.parquet"]

out: ["PTN_EXPORT/"]

checks: ["G2","G4","G7"]

audit:

run_id: "01JXYZABCD0EFG7H8JK9MN0PQ"

seeds: [20250924]

tools:

- name: "ptn-cli"

version: "1.4.2"

exports:

must_include: ["manifest.yaml","schema.json","check_dim_report.json","quality_report.json","audit.jsonl"]

D. 计算校核示例（量纲闭合）

Check: T_arr = ∫ ( n_eff / c_ref ) d ell

Dims : [1] / [m·s^-1] * [m] = [s] ✅

VI. 结果导出页面（发布项目信息最小集）

• 项目名称、dataset_id、version、生成时间、生产者。
• 指标概览：记录数、路径平均长度、T_arr 概要统计、Q 分布。
• 质量与校核：质量门通过率、p_dim、Q_res。
• 引用与依赖：see[]、references[] 清单（卷名 + 版本 + 锚点）。
• 获取方式与校验：checksum、SIGNATURE.asc、目录结构与文件大小。