本项目是专为解决「双通道」药品管理场景下医院药房与零售药店之间处方执行结果不一致问题而设计的轻量级对账协调工具。我们直面医保双通道政策落地中普遍存在的系统割裂、编码不一、时间不同步、责任难追溯等现实堵点，不依赖中间数据库或定制化Web界面，而是以命令行（CLI）为核心交付形态，通过医院HIS药房API与药店ERP API双通道实时采集数据，基于药品本位码映射表统一药品标识，用时间窗口状态机对齐跨系统时间戳，并自动检测处方量与实发量的数量差异、定位可疑断点（如接单时间缺失、时间漂移、编码错配）、生成含会签栏的可打印对账联单与结构化差异报告。全部逻辑由Go语言实现，模块清晰，适配器可插拔，输出格式支持ledger（单张联单）与report（批量汇总），适用于药学部质控、双通道药店合规审计、医保飞行检查前自查等真实工作流。
定位与能力范围
我们不做通用数据集成平台，也不替代医院或药店原有ERP/HIS系统。本项目的边界非常明确：只处理「一张处方从医院开出、到药店发药」这一闭环中的数量一致性校验与归因。它不参与处方审核、不开具药品、不修改库存，只读取、比对、标注、输出。所有判断依据均来自两个源头系统的原始字段，医院端提供处方号、药品名称、处方量、开方时间；药店端提供同一处方号下的实发量、接单时间、发药时间、ERP药品编码。当二者数量不等，或关键时间字段缺失/越界，系统即触发归因逻辑，而非简单标红报错。这种克制的设计，让工具能快速嵌入现有流程：药学部人员可在办公室终端一键跑单条处方复核；信息科可在夜间批处理全量处方生成日报；监管人员可导出带会签栏的PDF联单作为存档凭证。
核心功能机制
本项目五大能力模块彼此解耦，又通过事件总线紧密协同。我们坚持「每个模块只解决一类问题」：
- 双通道适配器
：分别对接医院HIS药房JSON API与药店ERP JSON API，支持字段重命名、空值兜底、HTTP超时重试，不强求两套系统字段名完全一致；
- 药品本位码映射层
：以国家药品本位码为锚点，建立与各药店ERP编码的双向映射表，内置模糊匹配（拼音首字母+规格关键词）与人工标注降级机制，应对编码录入不规范场景；
- 时间窗口状态机
：将「开方→接单→发药」建模为三阶段有限状态机，定义合法时间窗口（如接单必须在开方后2小时内），自动识别时间漂移、逆序、缺失等可疑断点；
- 对账引擎
：核心判断逻辑封装在此，不仅计算「处方量 - 实发量」，更结合断点类型、药品属性（如是否冷链）、操作时段（如夜班）给出归因说明与处置建议；
- 输出生成器
：生成两类产物，对账联单（含处方号、药品名称、处方量、实发量、数量差、对账状态、可疑断点、归因说明、会签栏）与差异报告（汇总总处方数、通过数、差异数、四类差异分布）。
这五层不是堆叠，而是流水线：适配器取数 → 映射层对齐药品 → 状态机校准时间 → 引擎判定差异 → 输出器生成结果。
使用与配置方式
本项目无安装包，无需部署服务，开箱即用。只要本地有Go 1.20+环境，即可直接运行。我们提供两种典型使用路径：
单条处方即时核验
适用于药师日常抽查、争议处方复盘、新药店上线验证。只需指定处方号，启用Mock模式即可模拟全流程：
go run cmd/reconciler/main.go --prescription-id=TEST001 --mock --format=ledger输出为结构化文本，含会签栏（MustSign=true时显示），可直接复制进Word或转PDF归档。
批量处方定时稽查
适用于药学部每日晨会前生成前一日双通道处方执行摘要。输入为JSON数组文件，每项含处方号与可选药店ID：
go run cmd/reconciler/main.go --batch data/sample/batch_input.json --format=report输出为Markdown格式汇总报告，含总处方数、通过率、差异数、四类差异占比（接单时间缺失、数量填报错误、药品编码错误、时间窗口外事件），便于快速定位高频问题环节。
所有参数均可通过--help查看完整说明，无隐藏开关，无配置文件强制依赖。真实环境使用时，仅需替换--mock为实际API地址与认证参数（详见项目文档）。
工程结构与模块职责
目录结构严格遵循关注点分离原则，每一层职责单一且可测试：
目录 | 职责说明 |
|---|---|
cmd/reconciler/ | CLI主入口，解析参数、调度流程、输出结果，零业务逻辑 |
cmd/mock_server/ | 内置Mock API服务器，用于离线验收与教学演示，不依赖外部服务 |
internal/adapter/ | 适配器实现层，含医院药房与药店ERP两个独立适配器，接口契约统一 |
internal/mapper/ | 映射表加载与查询逻辑，支持CSV/JSON映射源，内置缓存与热更新钩子 |
internal/engine/ | 时间窗口状态机定义与事件总线实现，驱动跨系统时序校准 |
internal/reconciler/ | 对账核心算法，含数量比对、断点识别、归因规则引擎（非硬编码，规则可配置化演进） |
internal/output/ | 联单模板渲染（text/template）与报告聚合逻辑，输出格式与样式解耦 |
data/sample/中存放脱敏样例数据，覆盖正常、差异、时间异常三类典型场景，可直接用于验证各分支逻辑。
数据字段与输出解读
理解输出字段含义，是用好本工具的关键。我们不隐藏判断依据，所有结论均可回溯到原始字段：
字段 | 来源系统 | 说明 | 示例 |
|---|---|---|---|
处方号 | 医院HIS | 全局唯一，双端必须一致 | TEST001 |
药品名称 | 医院HIS | 开方时填写的通用名+规格 | 利妥昔单抗注射液（100mg/10ml） |
处方量 | 医院HIS | 医生开具数量，单位由医院定义 | 2 |
实发量 | 药店ERP | 药店实际扫码发出数量 | 1 |
数量差 | 计算得出 | 处方量 - 实发量，>0表示少发，<0表示多发 | 1 |
对账状态 | 引擎判定 | 通过（差=0且无断点）或 | 差异 |
可疑断点 | 状态机输出 | 如 | 接单时间缺失 |
归因说明 | 规则引擎 | 结合断点与业务常识生成建议，如“建议核查药店接单环节是否漏操作” | 接单环节未记录，疑似未完成系统接单 |
会签栏 | 输出器添加 | MustSign=true时显示签字栏，供药师手写确认 | 药师签字：__________ |
批量报告中“四类差异分布”并非主观分类，而是由状态机与引擎联合输出的结构化标签，确保统计口径统一、可审计。
限制与说明
本项目明确不覆盖以下场景，避免用户误用： - 不处理药品价格、医保结算、物流轨迹等非数量维度； - 不支持非JSON协议的老旧ERP系统（需先由对方提供JSON封装层）； - 映射表需人工维护初始版本，模糊匹配仅为兜底，不能替代准确映射； - 时间窗口规则（如“接单须在开方后2小时内”）为默认值，可按地方医保细则在代码中调整，暂不支持运行时配置文件注入； - Mock服务器仅用于演示，真实环境需对接生产API并配置鉴权。
这些限制不是能力短板，而是设计选择：我们优先保障核心对账逻辑的确定性、可追溯性与交付轻便性。复杂度被显式收口，而非隐藏在黑盒配置中。
项目地址：
https://github.com/nexorin9/dual-channel-inventory-reconciler
