[开源] 开源科研生物样本溯源断裂检测系统：面向医院科研科与医务科的自动化时间窗口比对工具

冒泡Se

234人浏览 · 2026-06-11 22:53:00

冒泡Se · 2026-06-11 22:53:00 发布

本项目是专为医院科研生物库设计的溯源断裂检测系统，解决「临床检验使用了科研库样本但未登记」这一类隐蔽性操作漏洞。我们不依赖大模型，而是用规则引擎+集合运算，从 LIS（实验室信息系统）采样时间、生物库出入库操作时间、科研项目样本清单三路数据中，自动识别时间窗口错位、操作缺失、环节脱节等断裂模式，生成可打印、可会签、可归档的检测报告。面向科研科质控员、医务科监管人员、信息科部署工程师，提供 CLI 命令行、HTTP API 和 Web 界面三种使用方式；核心推理由 Golang 编写，保障高并发与确定性，报告生成与通知服务基于 TypeScript/Node.js 构建；支持 CSV/Excel/JSON 多格式输入，输出 HTML、纯文本与 80 列打印机友好的卡片式报告，并可通过企业微信、钉钉定时推送。

定位与能力范围

我们不做样本全生命周期追踪，也不接管 LIS 或生物库的原始业务系统。BioTrace 的边界非常明确：只做「断裂检测」这一件事，当一份科研库样本被带出用于临床检验，但 LIS 里的采样时间不在该样本的出库时间窗口内，或缺少对应出库/归还记录时，系统就把它标为一次溯源断裂。它不修改任何源数据，不替代人工复核，只给出「哪里断了、为什么断、谁该跟进」的结构化结论。

这个「断」不是模糊判断，而是基于三个刚性条件的交集验证： - 样本在科研库中有明确入库记录； - 该样本出现在 LIS 检验记录中（以 sample_id 关联）； - LIS 的 collection_time 不落在该样本「出库时间 + 容差窗口」内（默认 ±30 分钟），且无匹配的出库/归还操作链。

一旦触发，系统自动归因到四个责任环节之一：采样环节（LIS 时间异常早）、登记环节（科研库未录入该样本）、出库环节（有出库需求但无操作记录）、归还环节（长期未归还导致时间漂移）。这种归因不是概率推测，而是基于操作日志是否存在、时间是否闭合的布尔判定。

核心功能模块

所有功能都围绕「检测—归因—报告—触达」闭环展开，不叠加无关能力：

模块	能力说明	是否可关闭
时间窗口比对引擎	对每个 LIS 记录，查找其 sample_id 在生物库记录中的全部出库/归还事件，计算最近一次出库时间与采样时间的偏移量，超容差即标记断裂	可通过配置 `check_time_window: false` 关闭
操作链完整性校验	检查 LIS 中出现的样本，在生物库中是否有对应出库记录，且后续是否有归还记录（防止样本“失踪”）	可通过配置 `check_operation_log: false` 关闭
批量并行处理	CLI 与 API 均默认启用 Goroutine 并行解析与比对，万级样本可在数秒内完成	默认开启，不可关闭（性能基线）
多格式报告生成	同一检测结果可同时输出 HTML（含交互式筛选）、纯文本（适配审计留痕）、卡片式文本（80 列宽，适配热敏打印机）	三者独立开关，如 `--format html,text,card`
卡片排版引擎	自动将多条断裂记录压缩为单页多卡布局，每卡固定 12 行，含样本 ID、患者 ID、断裂类型、建议动作，避免跨页截断	仅卡片模式启用，不可单独关闭

使用与配置方式

你不需要部署整套前端才能开始使用。最轻量路径是 CLI：编译后一条命令即可跑通全流程。API 更适合集成进医院已有质控平台。Web 界面则面向日常抽查与汇报场景。

CLI 使用示例（无需启动服务）：

./biotrace detect \
  --lis data/sample_lis_records.csv \
  --biobank data/sample_biobank_records.csv \
  --project data/sample_project_samples.json \
  --output ./reports \
  --format html,card

API 启动后调用方式（返回检测任务 ID，再轮询获取报告）：

cd api && npm start
curl -X POST http://localhost:3000/api/detect \
  -F "lis=@data/sample_lis_records.csv" \
  -F "biobank=@data/sample_biobank_records.csv" \
  -F "project=@data/sample_project_samples.json"
curl http://localhost:3000/api/report/abc123

关键配置项均集中于 config.yaml，常见调整如下： | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | tolerance_minutes | integer | 30 | 时间窗口容差，单位分钟，适用于采样与出库存在物流延迟的场景 | | rules.check_time_window | boolean | true | 控制是否启用时间比对（设为 false 可专注查操作缺失） | | notify.webhook_url | string | "" | 企业微信或钉钉的卡片推送地址，留空则不推送 | | notify.push_schedule | string | "daily" | 可选 "daily" 或 "per-shift"（按白班/夜班推送） |

工程结构与技术选型依据

我们坚持「推理归推理，呈现归呈现」的分层原则。Golang 承担全部核心计算：时间解析、区间交集、集合差集、归因逻辑，因其静态编译、无 GC 毛刺、并发模型天然适配批量比对任务；TypeScript/Node.js 负责 API 路由、文件上传解析、模板渲染与通知封装，发挥其生态成熟、JSON 处理高效、前端同构优势；React 前端仅作为可选视图层，不参与任何业务逻辑。

整个结构清晰映射职责： - src/：Golang 引擎，含 engine/（主推理）、data/（CSV/Excel/JSON 解析器）、report/（模板驱动的 HTML/text/card 渲染）； - api/：Express 服务，暴露 /api/detect 与 /api/report/:id，调用 src 编译出的 biotrace 二进制或直接调用 Go CGO 封装（生产环境推荐前者）； - web/：纯静态 React 应用，通过 API 与后端通信，无服务端渲染需求； - templates/：所有报告模板存放处，HTML 使用 EJS，卡片使用纯文本占位符，便于医院按需定制样式。

不引入数据库、不依赖 Redis、不强制使用 Kubernetes，Docker Compose 即可一键拉起完整服务栈，也支持仅运行 CLI 进行离线检测。

数据接入规范

三类输入数据必须严格遵循字段定义，否则无法建立关联。我们不提供字段映射界面，所有映射关系在代码中硬编码，确保逻辑透明、审计可溯。

LIS 检验记录（必需字段）： | 字段名 | 类型 | 是否必填 | 说明 | |--------|------|----------|------| | sample_id | string | 是 | 与生物库记录、科研项目记录完全一致的样本唯一标识 | | collection_time | datetime | 是 | ISO 8601 格式（如 2024-03-15T09:22:17+08:00），用于时间窗口比对 |

生物库入出库记录（必需字段）： | 字段名 | 类型 | 是否必填 | 说明 | |--------|------|----------|------| | sample_id | string | 是 | 同上，用于跨表关联 | | operation_type | enum | 是 | 仅接受 入库、出库、归还 三种值，大小写敏感 | | operation_time | datetime | 是 | 同样 ISO 8601 格式，用于构建时间窗口 |

科研项目关联表（JSON 格式，必需字段）：

{
  "project_id": "PRJ001",
  "samples": [
    {
      "sample_id": "SAMPLE001",
      "patient_id": "P001"
    }
  ]
}

其中 sample_id 是唯一关联键，patient_id 用于报告中展示患者维度统计。

部署与运行环境

最小可行运行环境仅需一台 2 核 4GB 内存的 Linux 服务器（或 Docker Desktop 本地开发）。无特殊依赖：

组件	版本要求	说明
Go	≥1.21	编译 `src/` 所需
Node.js	≥18.17	运行 `api/` 与 `web/` 所需
Docker	≥24.0	`docker-compose up -d` 启动全栈
浏览器	Chrome/Firefox/Edge 最新版	Web 界面兼容性保障

Docker 部署只需两步：

git clone https://github.com/cca/biotrace.git
cd biotrace && docker-compose up -d

服务启动后，API 监听 :3000，Web 界面监听 :8080，CLI 二进制位于 src/biotrace，开箱即用。

限制与说明

我们明确不覆盖以下场景，避免用户误用： - 不处理样本编号不一致问题（如 LIS 写 SAMP-001，生物库写 SAMPLE001），需前置清洗； - 不支持跨时区自动转换，所有时间字段必须统一为本地时区（如东八区）并显式标注 +08:00； - 不校验样本内容一致性（如 LIS 检验的是血液，但科研库登记为组织），仅校验流程时间与操作链； - 报告中「建议行动」为通用话术（如“请核查出库登记记录”），不生成个性化整改方案； - 企业微信/钉钉推送依赖外部 webhook，不内置消息重试或失败告警（需配合 Prometheus + Alertmanager）。

所有字段定义、错误码含义、归因逻辑细则，详见项目文档中的《数据格式说明》与《归因规则手册》，不在此重复罗列。

项目地址：
https://github.com/cca/biotrace