[开源] 出院费用清单医保编码大白话翻译器：面向患者与家属的医疗费用可读化工具
本项目是一个专为出院患者及家属设计的费用清单翻译工具，将医院结算单中晦涩的医保编码（如“0012345678901234”）、专业术语（如“经皮冠状动脉介入治疗术”）和模糊分类（如“其他诊疗费”）实时映射为自然中文说明（如“心脏支架植入手术，含导管、球囊和支架耗材”），并按药品、检查、手术、床位等临床类别自动归类统计。它不依赖医院HIS系统对接，不上传患者数据，全部本地运行；支持JSON/Excel/CSV多格式输入，输出Markdown（适合打印存档）、二维码文本（扫码即看）、JSON（供其他程序调用）三种形态；核心能力由SQLite本地数据库驱动，辅以模糊匹配与LRU缓存保障查得率与响应速度；可选接入LLM生成口语化费用摘要，亦支持纯本地降级处理。我们用TypeScript编写，CLI为主入口，Docker为容器化部署路径，Web单页为轻量查看补充，所有逻辑闭环在用户设备端完成。
定位与能力范围
我们不做费用合规审计，也不替代医保局结算规则解释。我们只解决一个具体问题：当患者拿到一张密密麻麻印着编码、缩写和数字的出院清单时，第一眼能看懂“这笔钱到底花在哪了”。因此，能力边界非常明确：
- 输入必须是结构化费用明细（每条记录含编码、名称、金额、数量、单位、类别字段），不接受扫描图片或PDF；
- 翻译依据是本地SQLite数据库中的医保编码映射表，不联网查询国家库（避免隐私泄露与网络依赖）；
- 所有处理（加载、匹配、统计、格式化）均在本地完成，无后端服务、无用户账户、无数据出域；
- LLM摘要为可选增强模块，启用时仅向用户配置的API端点发送脱敏后的费用分布数据（不含患者身份、病历号、诊断信息），且默认关闭；
- 二维码功能分两类：--format qrtext输出UTF-8编码的纯文本二维码（适配主流扫码App），--qr-output生成PNG图片（供张贴或嵌入报告）。
这个边界决定了它不是给医保科做目录管理的系统，而是给患者带回家、给老人念一遍、给家属转发到家庭群的“费用说明书”。
核心功能
功能 | 说明 | 实际价值 |
|---|---|---|
| 医保编码大白话翻译 | 基于本地SQLite数据库，将医保编码映射为患者能理解的中文描述，例如将“XZ001234”转为“静脉留置针（一次性使用，含敷贴与肝素帽）” | 消除术语黑箱，让患者清楚知道“为什么收这笔钱”，减少医患沟通成本 |
| 多格式输入兼容 | 支持JSON（标准数组结构）、Excel（.xlsx/.xls）、CSV三类常见导出格式，自动识别字段名（code/name/amount/category等） | 无需医院IT配合改造导出模板，护士导出Excel、信息科发JSON、财务给CSV，都能直接用 |
| 费用自动归类统计 | 按临床习惯划分药品、检查、检验、手术、护理、床位、材料、其他八大类，汇总各分类金额及占比 | 一眼看出“药费占多少”“检查花了多少”，辅助家庭财务复盘与后续报销准备 |
| 模糊匹配引擎 | 当编码存在空格、换行、前导零缺失或OCR识别误差时，调用字符串相似度算法（Jaro-Winkler）尝试匹配近似编码 | 解决手工录入错误、旧系统导出格式不规范等现实问题，提升首用匹配成功率 |
| 多通道输出 | Markdown（保留表格与层级，适配微信/邮件/打印）、qrtext（生成可扫码的纯文本链接）、JSON（结构化供二次开发） | 满足不同场景：纸质存档用Markdown，家庭群分享用二维码，医院内部系统集成用JSON |
使用与配置
安装后无需服务器或数据库运维。最简启动只需一条命令：
node dist/index.js data/sample_discharge.json默认输出Markdown到终端，复制粘贴即可阅读。若需保存为文件：
node dist/index.js data/sample_discharge.json --output fee_report.md关键参数按使用频次排序：
---db <path>：指定自定义医保映射库（如./my_hospital_codes.db），默认读取data/insurance_codes.db；
---format <type>：切换输出形态，markdown（默认）、qrtext（生成扫码文本）、json（机器可读）；
---llm-enable：启用LLM摘要（需先配置.env文件填入API密钥与端点）；
---verbose：显示每条编码的匹配过程（命中/未命中/模糊匹配相似度），用于调试映射库覆盖度；
---locale <zh-CN/zh-HK/zh-TW>：适配不同地区中文术语习惯（如“B超”vs“超声波检查”）。
LLM摘要配置流程极简：
1. 复制.env.example为.env；
2. 填写LLM_API_KEY与LLM_ENDPOINT（支持OpenAI兼容接口，如Ollama、AnythingLLM本地部署）；
3. 运行时加--llm-enable，程序将把费用类别分布、最高单项、异常值提示等生成一段口语化总结，例如：“本次住院总费用¥3,280，其中药品占62%（¥2,034），主要为抗生素与止痛药；检查类占21%（¥689），含两次CT与一次核磁；手术类仅占3%（¥98），为常规清创缝合。”
交互模式（无参数运行node dist/index.js）提供菜单式引导，适合首次使用者逐步确认输入路径、输出格式与选项。
数据与扩展
映射库是本项目的核心资产，也是唯一需要定期更新的部分。项目自带sample_codes.db，但实际使用前建议导入最新医保目录：
npm run import-codes该脚本会扫描data/目录下所有Excel/CSV文件，按列名（code, name_zh, description_zh, category）自动入库。你也可以：
- 直接用DB Browser for SQLite等工具编辑insurance_codes.db；
- 将医院信息科提供的Excel医保目录放入data/后重跑导入；
- 在scripts/export_codes.ts基础上定制导出逻辑，同步院内专科编码扩展。
输入数据格式要求明确：JSON必须为对象数组，每个对象至少包含code（医保编码）、name（原名称）、amount（金额）三个字段；Excel/CSV需含同名列（大小写不敏感）。输出Markdown示例中表格列顺序固定：医保编码、原名称、大白话、类别、金额，确保可读性优先。
环境与运行
运行环境精简可控：
-最低要求：Node.js 18+（推荐20.x），无Python或Java依赖；
-数据库：SQLite（via better-sqlite3），单文件、零配置、跨平台；
-Excel处理：xlsx库，支持.xlsx与.xls，不依赖Office软件；
-二维码：qrcode库，纯JS实现，不调用外部服务；
-日志：pino结构化日志，--verbose时输出匹配详情，静默时仅报错。
Docker支持开箱即用：
docker-compose up translator默认处理内置样本；挂载自定义数据只需修改docker-compose.yml中volume配置：
volumes: - ./your_codes.db:/app/data/insurance_codes.db:ro - ./output:/app/outputWeb单页模式（docker-compose --profile web up web）提供浏览器内拖拽上传、即时预览、一键下载Markdown功能，适合非技术人员临时使用。
限制与说明
本项目明确不覆盖以下场景：
- 不解析诊断编码（ICD-10）、疾病分组（DRG/DIP）或病案首页；
- 不校验费用合理性（如“同一药品重复收费”“检查项目超适应症”）；
- 不生成报销凭证或盖章PDF；
- 不支持DICOM、HL7等医疗专有协议；
- LLM摘要不生成诊断结论、不替代医生解释，仅对费用结构作中性描述。
常见问题处理原则统一：
- “未匹配到医保编码”：优先检查编码是否带空格或不可见字符（--verbose可见原始值），其次确认映射库是否已更新；
- “二维码乱码”：务必使用--format qrtext而非--qr-output，后者生成图片需扫码App支持中文渲染；
- “大文件慢”：1000条以内通常<30秒，因内置500条LRU缓存；如需提速，可增大缓存容量或预热常用编码；
- “多语言支持”：--locale仅影响LLM摘要与部分预设文案，医保编码映射内容仍由数据库字段description_zh决定，需自行维护多语种描述。
所有设计决策围绕一个原则：让患者和家属，在离开医院后，第一次打开费用单时，不再需要打电话问护士“这行写的‘XZ001234’到底是什么？”
项目地址：
https://github.com/nexorin9/discharge-cost-translator