夜雨聆风在检验医学流程中，一个标本从采集、交接、接收，到最终上机检测，需跨越护理系统、护工系统、LIS 和检测系统四个环节。每个环节的时间戳不仅是操作留痕，更是判断标本质量、追溯流程瓶颈、支撑等级评审的关键证据。但现实中，时间戳缺失、逆序、超时等问题普遍存在，人工排查效率低、口径不统一、难以形成闭环改进依据。
specimen-four-timestamp-ledger 正是为此而生，一款专为检验科与护理部设计的「检验标本四时间戳完整率台账」工具。它不依赖大模型，不生成幻觉，仅基于可验证的时间逻辑与业务阈值，对采集、交接、接收、上机四环节时间戳进行完整性、时序性、时效性三重校验，并输出符合中式管理习惯的 Ledger 式台账，直接服务于质量分析与流程优化。
该项目完全开源，采用 Python 实现，提供 CLI 与 Web 双界面，支持 CSV/Excel/SQL 多源输入，输出含违规明细、统计摘要与环节分析的结构化台账，已在实际医院质量管控场景中落地验证。
核心能力：三类规则驱动的标本时间流稽核
工具以「纯规则引擎」为核心设计理念，所有判断均基于确定性逻辑，无任何概率模型或黑盒推理。其能力覆盖以下三个正交维度：
完整性检测检查采集、交接、接收、上机四个字段是否为空（
None或空字符串），识别MISSING类型违规时序逆序检测对相邻环节时间戳进行大小比较：若
交接时间 < 采集时间、接收时间 < 交接时间或上机时间 < 接收时间，则判定为OUT_OF_ORDER超时阈值检测计算相邻环节时间差（单位：分钟），并与预设阈值比对：
collection_to_handoff（采集→交接）handoff_to_receive（交接→接收）receive_to_analysis（接收→上机） 超出即标记为TIMEOUT
所有违规记录统一归入 Ledger 台账，字段严格对齐临床管理需求：
其中「建议操作」为固定文案，如 补录时间戳、核查交接记录、检查 LIS 接收日志 等，不依赖上下文生成，确保可执行性。
技术实现：轻量、可嵌入、零幻觉
项目采用成熟稳定的 Python 生态栈构建，兼顾开发可维护性与部署简易性：
后端：Flask 提供 Web 接口，Click 构建 CLI 入口 数据处理：pandas 完成清洗与计算，openpyxl 支持 Excel 写入 前端：Bootstrap 实现响应式布局，ECharts 渲染统计图表 配置管理： .env文件集中定义超时阈值，支持运行时覆盖
目录结构清晰分层，各模块职责单一：
src/├── models.py # 标本实体定义与时间字段标准化├── config.py # 默认阈值、常量、环境变量加载├── data_loader.py # 统一入口：CSV/Excel/SQL 表读取与列映射├── specimen_merger.py # 多源数据按标本条码合并（如 LIS 与护理系统分离存储）├── completeness_checker.py # 缺失检测逻辑├── order_checker.py # 逆序检测逻辑├── timeout_checker.py # 超时检测逻辑├── rule_engine.py # 串联三类检查，生成原始违规事件流├── statistics.py # 汇总完整率、各环节违规数、瓶颈排名等指标├── ledger_generator.py # 将违规事件格式化为台账（console/excel/csv）├── cli.py # Click 命令行接口└── webapp.py # Flask Web 应用主模块所有规则逻辑均为函数式实现，无状态、无副作用，便于单元测试与审计。例如 order_checker.py 中核心判断仅为：
def is_out_of_order(collection_time, handoff_time): return handoff_time and collection_time and handoff_time < collection_time快速开始：CLI 与 Web 两种启动路径
安装依赖
pip install -r requirements.txtCLI 使用：面向脚本化与批量分析
基础分析（控制台输出）：
python -m src.cli analyze --input data/mock_specimens.csv --format console带统计摘要的分析：
python -m src.cli analyze --input data/mock_specimens.csv --format console --summary导出 Excel 台账（含多工作表）：
python -m src.cli analyze \ --input data/mock_specimens.csv \ --output data/output_ledger.xlsx \ --format excel \ --summary \ --thresholds collection_to_handoff=30 handoff_to_receive=20 receive_to_analysis=60CLI 参数说明如下：
--input-i | --input data/mock_specimens.csv | |
--output-o | --output output_ledger.xlsx | |
--format-f | console/excel/csv | --format console |
--summary-s | --summary | |
--thresholds | --thresholds collection_to_handoff=45 |
Web 界面：面向日常质量巡查
启动方式：
# Windows.\run_web.ps1# Linux/Mac./run_web.sh服务启动后访问 http://localhost:5000，即可使用图形化界面：
/上传 CSV 或 Excel 文件 /ledger查看可筛选、可排序的违规台账表格 /stats查看完整率趋势、各环节违规分布柱状图、瓶颈环节排名 /export一键导出 Excel 台账（含「违规台账」「统计摘要」「环节分析」三张工作表）
Web 界面不依赖数据库，所有计算在内存中完成，上传即分析，适合单机快速质检。
配置与定制：通过 .env 控制业务语义
超时阈值是临床质控的核心参数，项目支持两种配置方式：
命令行参数动态覆盖（优先级最高） .env文件全局配置（推荐用于生产环境）
在项目根目录创建 .env 文件，内容如下：
COLLECTION_TO_HANDOFF_MINUTES=30HANDOFF_TO_RECEIVE_MINUTES=20RECEIVE_TO_ANALYSIS_MINUTES=60该配置将作为所有分析任务的默认阈值，无需每次命令行指定，也便于团队统一标准。
输出示例：即开即用的质控交付物
Console 输出（精简可读）
=== 检验标本四时间戳完整率台账 ===【统计摘要】总标本数：50完整率：68.0%（34/50）采集缺失：3 交接缺失：2 接收缺失：1 上机缺失：4逆序违规：5 超时违规：8【违规台账】序号 | 患者ID | 标本条码 | 违规类型 | 违规描述 | 涉及环节-----+------------+-------------+--------------+--------------------------------------+----------1 | P001 | SPC20260401 | MISSING | 缺少上机时间戳 | analysis2 | P002 | SPC20260402 | OUT_OF_ORDER | 交接时间早于采集时间（逆序） | collection→handoff3 | P003 | SPC20260403 | TIMEOUT | 采集到交接超45分钟（阈值30分钟） | collection→handoff4 | P004 | SPC20260404 | MISSING | 缺少采集时间戳 | collection5 | P005 | SPC20260405 | OUT_OF_ORDER | 接收时间早于交接时间（逆序） | handoff→receive【瓶颈环节排名】1. 采集环节 - 12起违规（24.0%）2. 上机环节 - 8起违规（16.0%）3. 交接环节 - 6起违规（12.0%）Excel 输出（符合管理规范）
导出的 output_ledger.xlsx 包含三张工作表：
- 违规台账
全量记录，字段同上，支持 Excel 原生筛选与排序 - 统计摘要
各环节完整率、逆序率、超时率数值汇总表 - 环节分析
使用 ECharts 渲染的横向柱状图，直观呈现各环节问题占比
所有输出均遵循《医疗质量管理办法》对过程记录可追溯、可量化、可改进的要求。
适用场景：直击医疗质量管控真实痛点
本工具已明确适配以下典型场景：
检验科日常标本全流程质量监控与月度分析报告生成 护理部对标本采集与交接环节的专项整改支持 等级医院评审与飞行检查前的数据自检与台账准备 LIS、HIS、护理系统间时间戳一致性交叉验证
它不替代系统改造，而是作为独立的质量探针，在不侵入现有系统前提下，提供客观、可复现、可归因的数据稽核能力。
项目地址：https://github.com/nexorin9/specimen-four-timestamp-ledger国内仓库：https://gitee.com/nexorin9/specimen-four-timestamp-ledger欢迎交流使用问题，或提交 issue 反馈实际业务中的时间逻辑扩展需求。
