仪器结果传入 LIMS：字段映射、幂等与异常重试怎么设计
把仪器结果写入 LIMS，看起来像一次普通 API 调用。真正困难的是：如何保证重复消息不会生成重复结果，字段错误不会静默进入正式记录，网络恢复后数据仍能按正确顺序处理。
本文给出一套与具体厂商无关的设计思路。文中的名称均为示例字段，不代表现有产品接口。
## 1. 先确定业务主键
不要只用可编辑的样品名称关联结果。更稳妥的消息至少包含：
```json
{
"message_id": "唯一消息标识",
"sample_id": "样品唯一标识",
"test_id": "检测任务标识",
"instrument_id": "仪器标识",
"method_version": "方法版本",
"completed_at": "完成时间"
}
```
`message_id` 用于接口幂等，`sample_id + test_id` 用于业务匹配。两类标识不要混为一谈。
## 2. 字段映射表要能直接验收
| 业务含义 | 来源字段示例 | LIMS 字段示例 | 校验规则 |
|---|---|---|---|
| 任务标识 | sequence_item_id | test_id | 必填且任务存在 |
| 结果值 | calculated_result | result_value | 数值、精度正确 |
| 单位 | unit | result_unit | 命中字典或受控换算 |
| 数据文件 | data_file_id | raw_data_ref | 可定位且不可混淆 |
| 方法 | method_name/version | method_code/version | 版本一致 |
| 状态 | run_status | result_status | 只允许定义的状态转换 |
字段表应额外记录长度、字符集、时区、空值策略和错误代码。只写“名称对应名称”通常不够。
## 3. 幂等不是简单去重
接收方可以在事务中先查询 `message_id`：
```text
begin transaction
if message_id already succeeded:
return previous success response
validate task, unit, status and payload
write result and audit record
mark message_id succeeded
commit
```
如果同一 `message_id` 的内容发生变化，不应直接覆盖。可以拒绝并记录冲突，要求发送方生成新的受控消息。
## 4. 区分可重试与不可重试错误
- 网络超时、临时服务不可用：进入延迟重试；
- 字段缺失、单位未知、任务不存在：进入人工处理队列；
- 重复成功消息：返回原处理结果；
- 已作废任务收到新结果：拒绝并留下异常记录；
- 结果已批准后发生更改：进入受控更正流程。
建议采用有限次数的指数退避，并设置死信或异常队列。无限重试会掩盖数据质量问题。
## 5. 日志要回答四个问题
1. 谁或哪个系统发送了消息？
2. 什么时候发送、接收和处理？
3. 处理前后状态是什么？
4. 失败原因和后续动作是什么？
接口日志不等于完整审计追踪。结果更正、重新计算、复核和作废仍需要在业务系统中保留相应记录。
## 6. 验收不要只测正常路径
至少覆盖重复发送、断网恢复、字段缺失、单位错误、任务作废、时间格式错误、乱序到达和部分成功。每个用例都应有输入、预期响应、数据库结果和日志证据。
FDA 数据完整性问答提供了数据完整性控制背景：https://www.fda.gov/regulatory-information/search-fda-guidance-documents/data-integrity-and-compliance-drug-cgmp-questions-and-answers
21 CFR Part 11 原文：https://www.ecfr.gov/current/title-21/chapter-I/subchapter-A/part-11
以上资料访问日期：2026-07-27。本文是架构中立的工程草稿，不代表任何产品接口已经实现，也不构成法规适用性结论。
## 官网首发来源
技术审核和官网首发完成满 24 小时后，可在平台规则允许时保留一个来源链接：https://labinforsoft.cn/pages/news/480.html?utm_source=csdn&utm_medium=technical&utm_campaign=202607_lims_geo&utm_content=csdn-instrument-lims-mapping