4. 实验室信息管理系统（LIMS）集成

样本追踪系统负责记录“样本在哪里、经历了什么”，LIMS 负责承载“样本的检测项目、结果、审核与报告”。两者若各自为政，就会出现样本位置与检测状态脱节、人工重复录入、报告与原始样本无法对应等问题。集成的目标不是把两个系统合并，而是让样本从接收、入库、分装、检测到留样销毁的每个关键节点，都能在 LIMS 中形成可追溯、可审计、可自动推进的记录。

一、三种对接方式及其适用边界

LIMS 与样本追踪的对接，按耦合程度可分为三类。第一类是文件级对接：追踪系统按约定格式导出 CSV 或 XML，LIMS 定时扫描目录并导入。它实现简单、对网络依赖低，适合样本量小、实时性要求不高的场景，但存在延迟，且文件重复导入或字段错位不易发现。第二类是数据库级对接：通过共享中间表或视图交换数据，追踪系统写入样本状态表，LIMS 触发器或定时任务读取。它比文件方式实时，但两系统表结构强耦合，任一方升级都可能破坏对接。第三类是API 接口对接：以 RESTful 或消息队列方式按事件推送，追踪系统在样本状态变更时调用 LIMS 接口，LIMS 也可反向查询样本位置。它解耦最好、实时性最高，是当前主流方案，但需要处理鉴权、幂等、失败重试与接口版本管理。

选择时可用一个简单判据：若样本状态变化需要立即触发 LIMS 中的检测任务或报告冻结，应选 API；若只是每日汇总核对，文件方式足够；数据库直连仅建议在系统同源、由同一团队维护时使用。

二、数据字段设计：以样本为核心对象

字段设计决定集成能否长期稳定。核心原则是：每个字段有唯一来源系统，避免双向可写造成冲突。通常样本追踪系统是“位置与容器”的权威源，LIMS 是“检测项目与结果”的权威源。以下是一组可直接参考的样本主数据与状态字段示例（示例字段，实际需按实验室流程裁剪）：

字段设计中有三个易错点。其一，时间统一用 ISO 8601 带时区，避免跨系统时区解释不一致。其二，状态枚举必须双方共用同一套码表，例如追踪系统写“in_test”，LIMS 不能只认“testing”。其三，体积、浓度等数值字段要带单位，或约定固定单位（如一律 μL、ng/μL），否则 0.2 与 200 的歧义会直接导致分装错误。

三、API 接口设计要点

以 RESTful 为例，追踪系统在样本状态变更时向 LIMS 推送事件。典型接口如下：

POST /api/v1/samples/events
Authorization: Bearer <token>
Content-Type: application/json

{
  "event_id": "evt-9f2c1a",
  "tracking_uid": "2D-7F3A9C21",
  "sample_id": "BIO-2024-00123",
  "event_type": "aliquot",
  "status": "aliquoted",
  "storage_location": "FZ-A-02-03-14",
  "volume_ul": 180,
  "occurred_at": "2024-06-11T09:20:00+08:00"
}

接口设计需满足四点。第一，幂等性：以 event_id 去重，同一事件重复推送不产生重复记录。第二，鉴权：使用 OAuth2 客户端凭证或短期 JWT，禁止在 URL 中传密钥。第三，失败重试：网络超时返回 5xx 时，追踪系统按指数退避重试，超过阈值进入死信队列并告警。第四，版本管理：URL 中带 /v1/，字段新增保持向后兼容，删除字段需提前公告。LIMS 侧收到事件后，应返回 201 与 LIMS 内部记录号，便于追踪系统回写关联。

四、自动化工作流：从事件到任务

集成真正产生价值的地方，是把样本事件自动转化为 LIMS 中的业务动作。下面这张图展示了一条典型的自动化链路：样本接收后自动建档，分装后自动生成子样本并触发检测任务，检测完成回写状态，剩余体积低于阈值时自动提醒留样或销毁。

工作流落地时，建议把“事件—动作”写成可配置规则，而不是硬编码。例如：当 event_type = aliquot 且 volume_ul < 50 时，LIMS 自动创建“留样评估”任务并通知样本管理员；当 status = completed 时，追踪系统自动把样本位置更新为“待归档”。规则表应包含触发事件、条件表达式、目标动作、通知对象四个字段，便于后续调整。

五、验证与常见故障

集成上线前，至少完成三类验证。第一，字段映射验证：用 20 条覆盖各状态的样本，逐条核对追踪系统与 LIMS 的 sample_id、tracking_uid、status、storage_location 是否一致。第二，幂等与重试验证：同一 event_id 连续推送 3 次，LIMS 应只产生 1 条记录；模拟接口超时，确认重试后数据不重复。第三，边界验证：体积为 0、位置为空、状态码不在码表中的事件，应被拒绝并记录错误日志，而不是静默写入。

常见故障中，最隐蔽的是“状态码表漂移”：追踪系统新增了 “in_transit” 状态，LIMS 未同步，事件被丢弃，样本在 LIMS 中停留在 “stored”。排查方法是定期比对双方码表，并在 API 层对未知状态返回 422 与明确错误信息。其次是时间戳时区问题，若追踪系统用本地时间、LIMS 用 UTC，会导致事件顺序错乱，进而影响“先分装后检测”的逻辑判断。统一使用带时区的 ISO 8601 可从根本上避免。