📚 课程目录第2章实验数据对象建模

2. 实验数据对象建模

实验数据版本管理的第一步不是选工具，而是把“数据对象”本身定义清楚。如果原始数据、中间数据、结果数据、元数据、样本与批次标识在模型层面混在一起，后续的版本号、血缘关系、回滚策略都会失去锚点。本节从建模视角出发，说明这六类对象各自的职责边界、关键字段以及它们之间的引用关系，并给出一套可直接落地的建模方法。

一、为什么必须区分六类对象

实验数据有一个典型特征：同一份数据在不同阶段承担不同角色。例如一台光谱仪输出的原始谱图，经过基线校正后成为中间数据，再经过峰拟合得到浓度值，成为结果数据。如果三者共用同一个标识，就无法回答“这个结果是由哪一版原始数据算出来的”。因此建模的核心目标是：让每一类对象都有稳定的身份、明确的来源和可追溯的引用。

六类对象的职责可以这样理解：原始数据是“不可变的事实记录”，中间数据是“可重算的加工产物”，结果数据是“被解释和交付的结论”，元数据是“描述上述三者的上下文”，样本标识是“物理对象的身份”，批次标识是“一组样本的共同来源”。它们不是并列的六个文件夹，而是围绕一次实验形成的引用网络。

二、原始数据：只追加、不修改

原始数据建模的第一原则是不可变性。仪器直接输出的文件、手工记录的原始表格、图像、音频、日志，一旦入库就应视为只读。建模时需要记录：采集时间、仪器或设备编号、采集参数（如采样率、曝光时间、增益）、文件格式与校验和（如 SHA-256）。校验和是判断“这份原始数据是否被改动过”的最直接依据。

建议原始数据采用“一次写入、多次引用”的存储策略，路径中不包含会变化的业务字段，例如使用 raw/2024/06/18/SPC-001/run-0007.raw 这类按时间与设备组织的结构，而不是把样本名写进路径。样本与原始数据的关联通过元数据表建立，而不是靠文件名猜测。

三、中间数据：可重算、可丢弃

中间数据是处理链的产物，例如去噪后的信号、对齐后的时间序列、特征向量。它的关键属性是可重算性：只要原始数据、处理代码版本和参数确定，中间数据就应当能被重新生成。因此中间数据的建模重点不是“保存得多完整”，而是“记录清楚它是怎么来的”。

每个中间数据对象至少应携带：来源原始数据标识、处理步骤名称、代码提交哈希、参数集合、生成时间。中间数据通常允许被覆盖或清理，但一旦被结果数据引用，就应保留其版本快照，否则结果将无法复现。

四、结果数据：面向解释与交付

结果数据是实验的“结论层”，例如浓度值、合格判定、统计报表、图表。它往往会被写入报告、论文或质量记录，因此建模时需要额外记录：结果版本、审核状态、适用的样本与批次范围、不确定度或置信区间。结果数据一旦发布，应冻结版本，后续修正以新版本形式出现，而不是原地修改。

结果数据与中间数据的区别在于：中间数据可以重算，结果数据一旦被引用就承担了“当时结论”的责任。因此结果数据的版本号建议采用语义化版本，例如 result-v1.2.0，并在元数据中标注变更原因。

五、元数据：把六类对象串起来

元数据不是“附加说明”，而是建模的主干。它至少应覆盖三类信息：描述性元数据（样本名、批次、实验目的）、结构性元数据（字段类型、单位、量纲、缺失值约定）、管理性元数据（创建人、版本、权限、保留期限）。

一个实用的做法是建立统一的元数据表，用 object_id 作为主键，用 object_type 区分 raw/intermediate/result，用 parent_ids 记录上游引用。这样任意一个结果都能沿 parent_ids 回溯到原始数据，形成血缘链。

六、样本与批次标识：物理世界的锚点

样本标识对应物理对象，批次标识对应一组样本的共同来源。建模时建议采用“全局唯一 + 人类可读”的双标识：全局唯一标识（如 UUID 或 SMP-20240618-001）用于系统引用，人类可读名称（如“对照组-3号”）用于沟通。批次则记录制备日期、操作人、环境条件、样本清单。

样本与批次的关系是一对多：一个批次包含多个样本，一个样本只属于一个批次。原始数据、中间数据、结果数据都通过样本标识与批次标识关联，而不是把批次信息重复写入每个文件。

七、建模落地：一张元数据表 + 一条血缘链

把上述六类对象落到工程上，最简可行的方案是一张统一元数据表加一条血缘链。表结构可参考如下字段：

object_id       TEXT PRIMARY KEY   -- 全局唯一
object_type     TEXT               -- raw / intermediate / result
sample_id       TEXT               -- 关联样本
batch_id        TEXT               -- 关联批次
parent_ids      TEXT               -- 上游对象，逗号分隔
code_hash       TEXT               -- 处理代码版本
params_json     TEXT               -- 处理参数
checksum        TEXT               -- 文件校验和
created_at      TIMESTAMP
version         TEXT               -- 语义化版本
status          TEXT               -- draft / reviewed / frozen

以一次光谱实验为例：批次 B-20240618-A 包含样本 SMP-20240618-001，原始数据 raw/run-0007.raw 的校验和为 a3f1…，经基线校正（代码哈希 c9d2…，参数 {"window":51,"poly":3}）生成中间数据，再经峰拟合得到结果 result-v1.2.0。当需要复现时，系统按 parent_ids 逐级回溯，校验每一级 code_hash 与 params_json 是否一致，即可判断结果是否可复现。

建模检查清单：① 原始数据是否只追加、带校验和；② 中间数据是否记录代码哈希与参数；③ 结果数据是否冻结版本并标注审核状态；④ 元数据是否以 object_id 为主键、parent_ids 为血缘；⑤ 样本与批次是否一对多且全局唯一。

常见误区：把批次信息写进文件名、用样本名当主键、中间数据覆盖后不保留快照、结果数据原地修改。这些做法都会在需要回溯时造成断链。

完成对象建模后，版本管理才有明确的“版本主体”：版本号加在对象上，血缘记录在元数据里，回滚针对具体对象而非整个目录。下一阶段的工作，就是在这套模型之上定义版本号规则与生命周期状态。