本项目是一个将药品发药数据转化为拟人化叙事的分析系统，专为药房管理者、临床药师和医院信息科设计。它不替代HIS或SPD系统，而是以「药品自述」为切口，把冷冰板的CSV/JSON发药记录（含药品名称、规格、发药数量、领药科室、领药时间）转化为可读性强、问题指向明确的文本洞察。核心机制是调用OpenAI GPT-4o-mini模型生成每种药品的第一人称日记，并同步运行规则驱动的模式检测模块，自动识别高退药率、低效使用等异常线索；交付形态覆盖Web可视化界面、RESTful API服务、命令行报告生成（CLI）三类，便于嵌入日常巡检、质控汇报或系统集成场景。技术栈基于TypeScript + Node.js构建，支持本地部署与Docker容器化，所有AI调用均通过环境变量配置，兼容OpenAI官方API及国内主流大模型代理接口。

定位与能力范围

我们不做全院级数据中台，也不做实时库存预警硬件联动。本项目的边界非常清晰：只处理已有发药数据，只输出两类结果，可读的拟人化文本（日记），和可量化的异常线索（问题检测）。它的价值不在替代传统报表，而在补足报表缺失的“语义层”：当统计表显示“阿莫西林退药率25.5%”，日记会说“我被内科领走100盒，三天后退回25盒，连药盒都没拆封，科室说‘备用太多’”；当报表呈现“呼吸科单日发药频次突增”，日记可能写道“上周五起，我每天被呼吸科领走3次，每次都是整箱，但没人告诉我为什么”。这种拟人化不是修辞游戏，而是结构化提示工程下的可控表达，已内置专业、幽默、温柔三种语气模板，供不同汇报场景切换。

它不采集患者身份、不关联医嘱原文、不对接电子病历，所有输入仅限发药行为本身。这意味着部署零侵入，你不需要动HIS导出逻辑，只要能导出带字段名的CSV或JSON（字段必须包含：药品名称、规格、发药数量、领药科室、领药时间），就能立刻启动分析。

核心功能

本系统围绕「数据→叙事→问题→行动」闭环设计四类能力：

• 数据解析

  严格校验CSV/JSON格式，自动映射字段（如识别“药品名称”“领药科室”等中文列名），拒绝模糊匹配，避免因列名微调导致解析失败

• 拟人化日记生成

  对每种药品调用大模型生成一段固定结构的第一人称叙述，包含使用节奏、流转路径、异常痕迹等要素，支持按需指定语气风格

• 模式检测

  内置退药率阈值（默认15%）、发药频次离群值、科室集中度等规则，不依赖机器学习训练，开箱即用识别高风险药品

• 多端交付

  Web UI提供药品列表页与单药详情页（含日记全文+关键指标卡片）；API支持程序化调用；CLI可批量导出Markdown报告用于邮件分发或归档

这四类能力彼此解耦：你可以只用CLI跑一次日报，不启Web服务；也可以只调用/api/issues接口获取问题清单，跳过全部日记生成；甚至在Mock模式下关闭AI调用，用预置样例验证流程。

使用与配置

无论你是想快速试用，还是准备接入生产环境，都有对应路径：

本地快速启动（适合评估）

npm install
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY
npm run dev

服务启动后访问 http://localhost:3000，上传data/sample-dispense.csv即可看到阿莫西林、头孢克肟等药品的拟人日记和退药问题提示。

命令行批量生成（适合日常运营）

npx ts-node src/cli.ts --file data/sample-dispense.csv --format markdown --output report-202603.md

该命令将生成一份带标题、分节、问题摘要的Markdown文档，可直接粘贴进企业微信或钉钉群，无需二次编辑。

Docker生产部署（适合信息科统一纳管）

docker-compose up -d

配合docker-compose.override.yml挂载./data目录与日志卷，所有配置通过环境变量注入，符合医院IT安全审计要求。

环境变量	必填	典型值	说明
OPENAI_API_KEY	是	sk-xxx	OpenAI密钥或兼容API密钥
OPENAI_MODEL	否	gpt-4o-mini	推荐使用，成本低、响应快
OPENAI_BASE_URL	否	https://your-proxy.com/v1	国产模型需填写此地址
MOCK_MODE	否	true	开发调试时禁用真实AI调用

数据与扩展

输入数据格式决定分析深度。系统仅接受两种格式，且字段命名必须准确：

字段名	类型	是否必填	示例	说明
药品名称	string	是	阿莫西林	作为日记主体与问题归因的唯一标识
规格	string	否	0.5g×24粒	影响批次管理判断，非必需但建议提供
发药数量	number	是	100	用于计算退药率、日均用量等指标
领药科室	string	是	内科	支持科室维度聚合分析（如“外科退药集中”）
领药时间	string	是	2026-03-19T08:30:00	ISO 8601格式，用于识别时间模式

若需扩展能力，项目预留了三个标准入口：
- prompts/ 目录下可修改日记生成模板，调整语气或补充业务规则（如加入医保限制说明）
- src/pattern-analyzer.ts 中可添加新检测规则（如“同一科室连续3天领同药超阈值”）
- src/export.ts 支持新增导出格式（PDF、Excel等），当前已实现Markdown/JSON/TXT

所有扩展不破坏原有接口，API路径与响应结构保持完全兼容。

工程结构与运行保障

项目采用分层架构，各模块职责分明：

模块	文件路径	主要职责
CLI工具	src/cli.ts	提供命令行入口，协调数据解析、日记生成、导出流程
Web服务	src/server.ts	托管Express服务器，路由分发至各API控制器
数据解析	src/data-parser.ts	校验CSV/JSON结构，标准化为内部数据模型
AI服务	src/ai-service.ts	封装OpenAI调用，含重试、缓存、Token统计
模式分析	src/pattern-analyzer.ts	运行确定性规则检测，输出结构化问题清单
报告生成	src/report-generator.ts	整合日记与问题，生成多格式汇总报告

运行保障方面，所有API响应强制遵循统一JSON结构：

{
  "success": true,
  "data": { /* 实际内容 */ },
  "cached": false
}

错误码严格对应HTTP状态：400参数错、404药品未找到、503AI不可用。/api/metrics接口实时暴露各端点调用次数，便于监控高频失败点；/api/health返回版本与时间戳，可接入Zabbix或Prometheus。

限制与说明

我们坦诚说明当前能力边界，避免误用：

• 不支持患者级追溯

  日记不包含患者姓名、ID或诊断，所有分析停留在药品-科室-时间三级粒度

• 不替代人工审核

  高退药率提示需药师结合临床背景判断是否真属浪费，系统仅提供线索

• 缓存策略为内存级

  重启服务后日记需重新生成，如需持久化，可按文档指引挂载数据库扩展

• 中文字段名强依赖

  暂不支持英文列名映射（如drug_name），须确保输入文件使用中文表头

• 无前端权限控制

  Web UI默认开放，生产环境建议前置Nginx加Basic Auth或HTTPS反向代理

常见问题处理方式已在文档中结构化列出，例如：
- 日记生成慢 → 切换gpt-4o-mini模型或启用MOCK_MODE=true快速验证流程
- Docker启动失败 → 检查.env是否漏写OPENAI_API_KEY，或执行docker logs pharmacy-diary定位报错
- 上传CSV报错 → 确认首行是否为中文列名，且无空格、特殊符号，参考data/sample-dispense.csv格式

项目地址：
https://github.com/nexorin9/pharmacy-diary