本项目是专为医院药房、社区药房及医药流通环节设计的轻量级库存风控 CLI 工具。它不依赖数据库或 Web 后台也不要求部署服务器而是通过「消耗速度快/中/慢」与「剩余效期近/中/远」两个业务可解释维度构建 3×3 交叉矩阵对每种组合分别计算断货风险与报损风险输出带严重度排序的预警清单和补货建议。核心能力包括多格式数据加载CSV/Excel/JSON、自动分类器训练、双预警引擎触发、HTML 可视化报告生成以及全链路配置化从分位数阈值、效期天数定义到安全库存天数、报损比例红线均可按药房实际运营节奏调整。运行于 Node.js 环境采用 ES Module 架构命令行交互使用 commander.js终端输出支持 chalk 彩色高亮Excel 解析依赖 xlsx 库所有逻辑无外部 API 依赖本地即可闭环运行。定位与能力范围我们不做通用 ERP 插件也不做 SaaS 订阅服务。这套系统只解决药房日常最痛的两件事一边怕断货被临床催一边怕近效期药品过期报废。传统做法靠人工翻表、凭经验划重点但人眼难同时盯住「哪些药卖得快却快过期」「哪些药卖得慢但库存还堆着」这正是交叉风险的盲区。我们把问题拆成两个可量化的轴横轴是消耗速度基于历史日均用量按分位数自动划分快/中/慢三档纵轴是效期等级按剩余天数硬性切分为近/中/远三档再在每个格子内独立评估「还能撑几天」和「效期内能不能卖完」。结果不是笼统打个标签而是输出两类清单断货预警按够用天数≤7天/8–14天分级、报损预警按效期内预计消耗比例30%/30%–60%分级并附带交叉矩阵热力图一眼锁定「快消耗近效期」这类高优先级干预项或「慢消耗近效期」这类需紧急促销/调拨的红灯单元。核心功能系统以 CLI 为唯一交互界面所有能力围绕「数据输入→风险识别→结果交付」三步闭环展开不引入图形界面或后台服务降低使用门槛与维护成本多格式数据加载库存、消耗、效期三类数据支持 CSV、Excel.xlsx/.xls、JSON 任意组合混用无需预清洗字段名自动映射标准字段如drug_id、quantity、date、expiry_date消耗速度自动分类基于 consumption 文件中各药品 30 天内总消耗量计算日均值后按全局分位数切分默认 P25/P75输出每品规归属「快/中/慢」档位避免主观定性效期等级自动评估解析 expiry 文件中的expiry_date与当前日期比对按配置阈值默认 ≤30 天为近效期31–90 天为中效期归类兼容不同药监效期标注习惯双风险交叉矩阵生成 3 行消耗速度× 3 列效期等级表格每个单元格显示该组合下药品数量、平均剩余天数、平均效期内消耗完成率并用颜色区分风险密度双预警引擎并行触发断货预警依据「当前库存 ÷ 日均消耗量」推算够用天数与配置的安全阈值比对报损预警依据「效期内预计消耗量 ÷ 总库存」计算完成率与报损比例阈值比对两者独立计算、独立排序、独立导出多格式报告交付支持json默认适合下游程序解析、csv适配 Excel 二次分析、html含交互式矩阵图、预警清单折叠面板、响应式布局手机端可读三种输出格式。使用与配置所有操作通过node bin/cli.js启动分三个主子命令职责清晰不重叠命令用途典型场景load-data验证三类数据文件可读性、字段完整性、日期格式合规性并输出标准化 JSON 结构预览新接入药房系统前校验数据质量排查expiry_date格式错乱或quantity为空等常见问题detect运行完整风险模型终端实时输出彩色预警列表红色高危黄色中危含药品 ID、名称、当前库存、日均消耗、剩余天数、效期完成率、风险类型与等级每日晨会快速扫一遍高风险项决定当日补货/促销/调拨优先级report生成结构化报告文件支持--format html/csv/json和--output自定义路径向科室负责人提交周度库存风控简报或存档备查全局参数统一控制输入源与输出行为关键参数如下参数缩写说明默认值--inventory path-i库存数据文件路径必须无默认报错--consumption path-c消耗记录文件路径必须无默认报错--expiry path-e效期数据文件路径必须无默认报错--config path—自定义配置目录路径config/内置默认--format format-f输出格式csv、json或htmljson--output path-o输出文件路径不设则输出至终端stdout例如生成一份 HTML 报告供移动端查看node bin/cli.js report \ --inventory data/inventory-sample.csv \ --consumption data/consumption-sample.csv \ --expiry data/expiry-sample.csv \ --format html \ --output report.html数据与扩展系统不绑定任何特定 HIS 或药房系统字段仅约定最小可用字段集便于对接各类数据源数据类型必需字段示例说明库存inventorydrug_id,name,quantity,unitquantity为当前在库数量unit用于展示如“盒”“瓶”消耗consumptiondrug_id,date,quantitydate为消耗发生日期支持多条同品规跨日记录效期expirydrug_id,expiry_dateexpiry_date支持YYYY-MM-DD或YYYY/MM/DD格式配置完全外置全部位于config/目录下分为两类 JSON 文件classifier-config.json控制分类逻辑{consumptionSpeed: { quantiles: { fast: 0.75, medium: 0.25 } },expiryThresholds: { near: 30, medium: 90 }}detector-config.json控制预警红线{stockoutThresholds: { high: 7, medium: 14 },expiryThresholds: { high: 0.3, medium: 0.6 }}所有阈值均可按药房实际补货周期、药品单价、仓储条件动态调整。例如基层药房补货周期为 14 天则应将stockoutThresholds.high改为14若管理高价肿瘤药则可将expiryThresholds.high从0.3收紧至0.15提前介入。环境与运行零依赖安装仅需 Node.js ≥18.0。安装命令极简npm install运行时无需编译或打包直接执行 CLI 主入口。环境变量可通过.env文件预设常用路径避免每次重复输入长路径变量说明默认值INVENTORY_PATH库存文件路径data/inventory-sample.csvCONSUMPTION_PATH消耗文件路径data/consumption-sample.csvEXPIRY_PATH效期文件路径data/expiry-sample.csvOUTPUT_FORMAT默认输出格式jsonLOG_LEVEL日志级别info复制模板启用cp .env.example .env修改.env后后续命令可省略全部--inventory等参数直接运行node bin/cli.js detect node bin/cli.js report --format html --output daily-warning.html限制与说明本系统明确划定能力边界它不替代进销存系统不处理采购订单生成不对接电子处方不提供用户权限管理。它的价值在于「把已有数据变成可行动的风险信号」。因此我们不对原始数据质量负责若消耗记录缺失某药品 30 天数据则其消耗速度无法分类若效期字段为空或格式错误则整行被跳过。所有数据校验逻辑在load-data阶段透明输出不静默容错。输出中的百分比如“效期内消耗完成率 28%”仅为模型推算值用于横向比较风险程度不构成财务报损依据实际报损仍需结合实物盘点与院内审批流程。HTML 报告在手机 Safari、Chrome 中经实测可正常展开折叠、滑动矩阵表格字体与间距适配小屏阅读无需缩放即可看清药品 ID 与数字。项目地址https://github.com/nexorin9/drug-expiry-warning