[开源] 转诊状态追踪器：面向医联体运营的闭环管理CLI工具，自动识别未完成转诊并分级告警

冒泡Se

350人浏览 · 2026-06-11 22:55:31

冒泡Se · 2026-06-11 22:55:31 发布

本项目是专为医联体运营人员设计的轻量级转诊闭环管理工具。它不依赖医院HIS或EMR系统对接，仅通过三类标准CSV文件（referral_records、admission_records、arrival_logs）即可还原转诊全链路状态，严格按 sent→admitted→arrived 三节点建模，内置可配置超时规则与时间容错机制，输出带颜色标记的未闭环清单和完整审计日志。核心能力全部封装在命令行界面（CLI）中，无需部署服务、不设前端页面、不连数据库，开箱即用。技术栈采用 Python 3.10+、Pydantic 做强类型校验、Click 构建交互逻辑，测试覆盖关键路径，适配日常批量导入、快速核查、电话确认归档的典型工作流。

定位与能力范围

我们不做转诊发起、不介入临床决策、不替代院内信息系统，只做一件事：把散落在不同环节的转诊记录“串起来”，并明确回答一个问题，哪些转诊卡在了哪一环？卡了多久？是否超时？

这个“串”的过程不是简单关联ID，而是基于医疗协作真实节奏的状态机建模：
- sent：上级医院开出转诊单，患者尚未入院；
- admitted：下级医院完成入院登记，但患者可能还未实际到达；
- arrived：患者实际抵达并完成接诊准备（如分诊、建档）。

三者构成不可逆的推进链条，任意一环缺失或延迟，即视为流程中断。系统据此生成两类关键交付物：
- unclosed_ledger.csv：结构化未闭环清单，含转诊ID、当前最高状态、各环节时间戳、超时级别（CRITICAL / WARNING）、超时时长；
- audit_logs/{date}.csv：每次运行的完整操作快照，含输入文件哈希值、执行时间、状态分布统计，满足基础审计留痕要求。

它不处理PDF扫描件、不OCR识别手写单、不对接微信小程序，也不做BI看板。它的边界非常清晰：给每天要翻几十份Excel、打电话核对状态的运营同事，省掉手工比对、心算超时、反复导出筛选的时间。

核心功能

系统围绕“状态识别—超时判定—容错适配—结果交付”四步闭环展开，所有能力均服务于医联体日常运营中的确定性动作。

功能模块	说明
三源数据解析	支持同时加载 referral_records（转诊单）、admission_records（入院登记）、arrival_logs（到达日志）三类CSV，字段名与示例数据完全对齐说明文档，无额外映射表或模板转换步骤
状态机引擎	每条转诊ID独立走状态流转：只有前序状态存在且时间早于后序，才允许升级；若admitted时间早于sent，则整条记录直接标为异常并跳过后续判断
超时判定DSL	阈值以JSON配置，非硬编码：sent→admitted 默认72小时，admitted→arrived 默认48小时；支持按业务节奏调整，例如节假日延长、重点专科缩短
时间窗口容错	允许 arrival_log 时间晚于 admission_record 最多48小时，适配EMR系统补录延迟场景，避免因IT同步滞后误报超时
未闭环清单生成	输出CSV含5列：referral_id、current_status、sent_at、admitted_at、arrived_at；超时项按严重程度填入 CRITICAL（双环节均超）或 WARNING（单环节超），方便运营人员优先拨打电话
审计日志	每次`check`命令执行即生成独立审计文件，记录输入文件SHA256、运行时间、各状态数量分布（如 total=30, sent_only=3, admitted_only=1, arrived=24），供复盘与交叉验证

这套设计源于我们反复观察运营日报表发现：真正消耗人力的不是“有没有数据”，而是“数据之间对不上”。比如一张转诊单写了3天前发出，系统里却查不到入院记录，是真没收治？还是入院信息录错了ID？还是还没来得及录入？本项目不做归因，只把“对不上”的事实拎出来，并附上精确到小时的超时计算，让人工确认有据可依。

使用与配置

整个使用流程就三步：放好数据、运行命令、取结果。没有安装服务、没有账号密码、不产生后台进程。

数据准备

将三类CSV文件统一放入data/sample/目录（可自定义路径），确保字段名与说明文档一致：
- referral_records.csv 必含：referral_id, sent_at（ISO格式时间字符串）
- admission_records.csv 必含：referral_id, admitted_at
- arrival_logs.csv 必含：referral_id, arrived_at

字段缺失会触发Pydantic校验失败并明确提示第几行缺哪个字段，不静默跳过。

运行主命令

检查当前转诊状态，输出未闭环清单与审计日志：

python -m src.cli check --input-dir data/sample/ --output-dir output/

该命令会：
- 自动读取input-dir下全部CSV；
- 按referral_id关联三表；
- 计算每条记录的当前状态与超时情况；
- 写入output/unclosed_ledger.csv与output/audit_logs/20240615.csv（日期按运行日生成）。

查看历史审计

如需回溯某次运行上下文，直接调用审计子命令：

python -m src.cli audit --output-dir output/

它会列出output/audit_logs/下所有已生成的审计文件，并打印最近一次的摘要统计，包括本次共处理多少条转诊、各状态分布数量、最长超时时长等，不重新解析原始数据。

查看与修改配置

默认超时规则与时间容差均存于JSON配置文件，可通过命令直观查看：

python -m src.cli config

输出类似：

Timeout thresholds:
  sent → admitted: 72 hours
  admitted → arrived: 48 hours
Time tolerance:
  arrival_log may be up to 48 hours later than admitted_at

如需调整，直接编辑config/timeout_config.json与config/time_tolerance.json，无需改代码。

工程结构

项目采用扁平清晰的模块划分，所有逻辑收敛于src/目录下，无隐藏依赖或动态插件：

src/cli.py
：Click驱动的命令入口，仅暴露check/audit/config三个子命令；
src/core/
：核心业务逻辑，含状态机实现、超时计算、容错判断；
src/models/
：Pydantic模型定义，强制校验输入字段类型与格式；
src/io/
：文件读写与哈希计算，审计日志生成在此；
config/
：纯JSON配置，无Python脚本，运维可直接修改；
tests/
：pytest覆盖状态流转、边界时间、空文件、字段缺失等关键case。

这种结构意味着：你看到的每一行命令，背后都对应一个明确定义的函数；你修改的每一个JSON，都会实时影响下次运行结果；你拿到的每一份unclosed_ledger.csv，其字段含义与生成逻辑，在代码里都有唯一出处。

环境与运行

本项目对运行环境要求极简，仅需标准Python环境，无GPU、无Docker、无额外服务依赖。

依赖项	版本要求	说明
Python	3.10+	低版本不支持Pydantic v2的严格类型推导
Pydantic	>=2.0	用于CSV行级结构校验与错误定位
Click	>=8.0	提供标准化CLI参数解析与帮助文本
pytest	用于本地验证	不作为运行时依赖，安装时可选

安装只需一行：

pip install -r requirements.txt

验证是否就绪，可运行：

python -m src.cli --help

将显示完整命令树与参数说明。所有操作均在本地完成，输入文件不上传、不联网、不调用外部API，符合基层单位对数据不出域的基本合规要求。

数据与扩展

当前支持的数据形态是固定字段的CSV，这是医联体运营中最常交接的格式，无需IT介入、业务人员可直接导出、Excel可开箱编辑。我们刻意回避了数据库连接、API拉取、Excel多Sheet解析等复杂路径，因为实践中90%的“待追踪清单”就是邮件附件里的三个CSV。

未来如需扩展，也严格遵循同一原则：
- 若新增状态节点（如discharged），只需在状态机构造中加入新阶段、补充对应CSV解析逻辑、更新超时配置项；
- 若需支持其他时间格式（如2024/06/15 09:30），在src/models.py中扩展时间解析器即可，不影响主流程；
- 若需导出PDF报告，可在src/io.py中新增导出函数，不改动核心状态机。

所有扩展点都限定在src/目录内，不引入新框架、不改变CLI契约、不增加用户学习成本。