本项目是专为医院信息科、病案科和医疗质量管理部门设计的单病种质量指标计算与报表生成工具。它从病案首页、检验报告（LIS）、长期医嘱（HIS）三类临床业务系统导出的结构化数据出发，按国家单病种质控要求（如急性心肌梗死、脑梗死、心力衰竭）自动完成入组判断、过程指标与结果指标的全链路计算，最终输出符合上报规范的CSV/Excel表格及带交互式图表的HTML可视化报表。核心能力由Python实现的数据读取层、YAML驱动的字段映射引擎、病种定制化指标计算逻辑、Jinja2模板渲染的报表生成层共同构成；对外提供TypeScript/Node.js封装的CLI命令行工具，支持一键运行、病种列表查询、全病种批量处理等实用操作。
定位与能力范围
我们不做通用ETL平台，也不替代HIS或BI系统，而是聚焦在「单病种质控指标落地执行」这个具体断点上：当医院已能导出病案首页、检验结果、长期医嘱三类CSV文件，但每次上报仍需人工核对字段、手写公式、反复粘贴校验时，本工具就成为信息科与质控科之间可复用、可审计、可交接的中间件。
它不连接数据库、不采集实时日志、不改造院内系统，只接受标准格式的离线文件输入；不覆盖临床决策，所有指标逻辑严格对应《国家医疗服务与质量安全报告》中对应病种的质量控制指标定义；不承诺100%覆盖全部病种，当前稳定支持急性心肌梗死（AMI）、脑梗死、心力衰竭三种国家首批重点监测病种，后续扩展只需新增YAML配置文件。
这种边界设定，让我们能把字段映射、时间窗判定、分母分子逻辑、缺失值归因等细节做实，比如“发病24小时内首剂阿司匹林使用率”这类过程指标，会自动识别病案首页中的入院日期、诊断时间，关联医嘱表中的药品名称与开具时间，再按分钟级精度比对是否满足“24小时”窗口，而不是依赖用户手动标注“是否使用”。
核心功能
工具以“数据进—规则跑—报表出”为闭环，所有能力围绕三类交付物组织：
- 上报级结构化数据
：每个病种生成独立子目录，含
report.csv（纯字段+值，无格式）、report.xlsx（含合并单元格、条件格式、表头说明，可直接提交至国家单病种管理平台） - 可视化质控看板
：
report.html包含指标完成率雷达图、分母/分子明细折叠面板、异常数据高亮提示（如某患者“未记录LDL-C值”触发“血脂检测率”扣分项），支持浏览器打开即用，无需部署 - 可追溯计算过程
：
detail/子目录下存放每项指标的原始匹配记录（如“哪些患者被计入‘急诊PCI术前双抗治疗’分母”“哪几条医嘱命中‘阿司匹林’关键词”），供质控员回溯核查
所有功能均通过统一CLI入口调用，无图形界面依赖，适合纳入信息科日常运维脚本或定时任务。
使用与配置
CLI是面向实际工作流设计的：你不需要先学Python或TypeScript，只要会复制粘贴命令、知道自己的CSV文件在哪、了解本院用的是哪几种病种，就能当天跑通。
常用操作有三类：
操作类型 | 命令示例 | 说明 |
|---|---|---|
单病种指定运行 | npx ts-node src/ts/cli.ts --discharge-summary data/sample/discharge_summary_sample.csv --lab-results data/sample/lab_results_sample.csv --medical-orders data/sample/medical_orders_sample.csv --disease-configs config/ --output-dir output/ | 默认按配置目录下首个病种（AMI）执行，适合试点验证 |
查看支持病种 | npx ts-node src/ts/cli.ts --list-diseases | 终端输出： |
批量全病种运行 | npx ts-node src/ts/cli.ts --all-diseases --discharge-summary ... | 一次输入三类数据，自动遍历config/下全部YAML文件，分别生成三个病种的完整报表包 |
病种逻辑完全由YAML文件定义，例如config/disease_ami.yaml中明确声明： - 哪些字段来自病案首页（如admission_date: discharge_summary.入院日期） - 检验项目如何匹配（如ldl_c: ["低密度脂蛋白胆固醇", "LDL-C"]） - 指标计算规则（如aspirin_within_24h: "lab_results.检验项目.contains('肌钙蛋白') and medical_orders.药品名称.str.contains('阿司匹林') and (medical_orders.开具时间 - discharge_summary.入院日期) <= pd.Timedelta('1 day')"）
这意味着：当医院更换LIS系统导致检验报告字段名从ITEM_NAME变成TEST_CODE，你只需修改YAML里的一行映射，无需动Python代码。
工程结构
整个项目采用清晰的职责分离设计，Python负责数据密集型任务，Node.js负责人机交互体验：
src/下Python模块按数据流分层：
readers/专注适配不同导出格式（兼容Excel/CSV/GBK编码/表头偏移）；mapping/将YAML配置编译为运行时字段路由表；calculator/按病种加载指标表达式并安全求值（使用numexpr隔离执行，防注入）；reports/调用pandas ExcelWriter与Jinja2生成多格式输出src/ts/cli.ts作为外壳，解析命令行参数、校验输入路径是否存在、调用Python子进程并捕获结构化日志（如
[INFO] 已加载372份病案首页，跳过12条无诊断编码记录），失败时给出明确修复指引（如“请检查lab_results.csv是否包含‘检验项目’列”）config/与
templates/完全静态，可单独抽离用于跨项目复用；data/sample/提供带注释的示例数据，字段名、时间格式、空值写法均模拟真实HIS导出场景
这种结构让信息科工程师既能直接调用Python模块做深度定制（如接入内部Docker环境），也能让质控员仅用npm命令完成全部操作。
环境与运行
部署极简：仅需Python 3.9+与Node.js 18+两个运行时，无GPU、无服务进程、无后台守护。
安装步骤明确分离：
pip install -r requirements.txtnpm install运行时无需全局安装，npx ts-node确保本地依赖优先；Python侧也支持python -m src.cli直启，规避虚拟环境路径问题。我们测试过Windows（GBK默认编码）、macOS（UTF-8）、CentOS 7（系统Python 2.7需额外装pyenv）三类环境，关键路径处理均加了pathlib.Path标准化与编码自动探测。
日志输出兼顾调试与归档：终端显示精简进度（如[✓] 脑梗死：过程指标计算完成），同时生成output/run.log记录完整上下文（含各数据源行数、字段缺失统计、指标命中详情），符合三级医院信息系统审计要求。
数据与扩展
数据输入遵循最小必要原则：只读取指标计算必需字段，不加载整张宽表。示例数据中discharge_summary_sample.csv仅含12列（如住院号、入院日期、主要诊断ICD编码、出院日期），lab_results_sample.csv仅含5列（检验号、住院号、检验项目、结果值、检验日期），这既降低内存占用，也倒逼医院导出时做字段精简。
扩展新病种只需三步： 1. 在config/下新建disease_hypertension.yaml，按现有格式填写字段映射与指标逻辑 2. 将该文件名加入CLI的--disease-configs指向目录（默认已包含全部YAML） 3. 运行--list-diseases确认识别成功，再执行--all-diseases验证
若需对接非CSV数据源（如SQL Server导出的.xlsx），可在src/readers/下新增一个reader类，重载load()方法，其余计算层与报表层完全无需改动。
限制与说明
本工具明确不解决以下问题，避免预期错位：
不处理非结构化文本：如病程记录、手术记录中的自由描述内容，暂不支持NLP抽取
不校验临床合理性：如“心梗患者未做心电图”属于质控预警范畴，本工具仅按规则计数，不替代医生判断
不替代数据治理：若病案首页中“主要诊断”字段为空或填“待查”，工具会如实标记为“未入组”，但不会反向补全诊断
不提供SaaS服务：无账号体系、无云端存储、无远程调用接口，所有数据停留本地
所有行为逻辑均可在说明文档中逐条对照验证：字段映射关系见config/下各YAML文件；指标公式见对应文件的indicators:区块；HTML模板结构见templates/report_template.html；错误码含义与修复建议见src/logger.py中的ERROR_CODES字典。
项目地址：
https://github.com/nexorin9/single-disease-indicator-extractor
