基药采购数据分析助手

以《国家基本药物目录（2026 年版）》为只读基线，对你（药师）后期填报/导出的采购与使用数据做可重复的对比分析：自动匹配目录、测算配备率与使用率、排查配备缺口、列出非基药待核项，并产出药学期刊级图表与汇总报告。

不是一次性脚本——而是"基线表 + 录入表 + 匹配字典 + 分析引擎"的可复用数据模型，目录更新只需重跑解析，分析口径保持不变。

一、触发场景

主动分析："帮我分析这份采购数据"、"算一下基药配备率/使用率"、"对比采购药品和基药目录"
达标评价："基药制度落实得怎么样"、"非基药占比多少"、"哪些基药没采购到（缺口）"
目录解析："把 2026 版基药目录 PDF 解析成表格"
演示/培训："跑个示例看看效果"（用于广东省药学会 AI 药学技能培训等场景展示）
关键词：基药配备率、基药使用率、基本药物、采购对比、配备缺口、非基药占比、合理用药点评

二、文件结构与三层数据模型

基药采购数据分析助手/
├── SKILL.md                      # 本说明
├── assets/
│   ├── 基药目录2026基线.csv      # 层1 只读基线表（794 条，已校验）
│   ├── 基药目录2026基线.xlsx     # 同上（Excel 版）
│   ├── 采购数据模板.xlsx          # 层2 录入表模板（含"字段说明"sheet）
│   ├── alias_map.csv             # 层3 别名映射字典模板（商品名→通用名）
│   └── 排除清单.csv             # 院方排除清单（目录有收录但本院不按基药管理）
├── references/
│   └── 数据模型设计.md            # 数据模型、字段字典、指标公式详述
└── scripts/
    ├── parse_catalog.py          # 从 2026 版目录 PDF 重建基线表
    └── analyze_procurement.py    # 分析引擎（匹配+指标+图表+报告）

三层模型（详见 references/数据模型设计.md）：

层1 基线表：目录解析产物，一次性生成、长期复用，分析时只读。字段含 part/top_cat/sub_cat/name_cn/name_en/dosage_spec/is_specialist(△)/is_dup_variant(*)/is_antimicrobial 等。
层2 录入表：每期由药师从 HIS/采购系统导出后映射到固定结构（13 个字段）。
层3 字典：alias_map.csv 把院端"商品名/习惯名"映射到目录"通用名"，解决异构命名。

条目校验：基线已校验 794 条 = 化学药品和生物制品 476 + 中成药 318，与目录声明数一致。

三、工作流

[目录 PDF] --parse_catalog.py--> [基药目录2026基线.csv]  (层1, 只读)
                                                   ▲
[采购/使用明细] --(采购数据模板)--> [录入表] ──┐       │ 规范化匹配键
                                            ├─→ [analyze_procurement.py] ──→ 指标表 + 期刊图表 + 报告
[alias_map.csv] ───────────────────────────┘       ▲
                                                   │
                              [基药目录2026基线.csv] ┘

四、运行命令

依赖（在 WorkBuddy 隔离 Python 环境已装）：pypdf（解析）、pandas、openpyxl、matplotlib。

1) 解析目录 PDF → 基线表（仅在目录更新时跑）

python scripts/parse_catalog.py
# 或自定义路径：
python scripts/parse_catalog.py --pdf "D:/目录.pdf" --outdir "assets"

输出 assets/基药目录2026基线.csv 与 .xlsx，并打印条目数与空名校验。

2) 演示（自动生成示例采购数据并出全套图与报告）

python scripts/analyze_procurement.py --demo --outdir ./基药demo_out

3) 真实分析（你提供采购录入表）

python scripts/analyze_procurement.py --procurement 采购数据.xlsx --outdir ./基药分析结果
# 可选：限定目录范围（如仅化学药+中成药，排除中药饮片）：
--scope-part 1,2
# 可选：提供别名映射字典加速/修正匹配：
--alias assets/alias_map.csv
# 可选：指定院方排除清单（默认读取 assets/排除清单.csv）：
--exclude assets/排除清单.csv

--procurement 支持 .xlsx（read_excel）或 .csv。字段结构见 assets/采购数据模板.xlsx。

五、匹配与指标口径

四级匹配（分子核心对齐，防误并），逐级兜底，详见 references/数据模型设计.md 第四节：

精确：molecule_core(院端名) == 目录 core（去标识/盐型/溶媒/剂型/功能前缀/规格后比较）。
词缀对齐：affix_compatible(院端核心, 目录核心) 为真即判同一分子——仅当差异是公认词缀（盐酸/硫酸氢/枸橼酸等盐型、氯化钠等溶媒、剂型、中成药功能前缀）。例：硫酸氢氯吡格雷 ≡ 氯吡格雷（同一基药）。
别名：查 alias_map，商品名→目录通用名。
模糊待核：difflib 相似度 ≥ 0.85 仅作"待核"建议，绝不自动判为基药，输出人工复核清单。

院方排除清单（目录命中也强制非基药）：assets/排除清单.csv（默认自动加载，亦可用 --exclude 指定）列出"目录有收录、但本院不按基本药物管理"的品种。凡院端品名包含清单中的 keyword，即便通过上面任一级匹配命中目录，也强制判为非基药（match_method=院方排除），不计入基药采购率。这用于体现医院药事委员会的实际管理决策——例如某院将 硫酸氢氯吡格雷（氯吡格雷的硫酸氢盐片剂）与 维生素D滴剂(胶囊型)（自费）排除在基药之外，尽管二者在 2026 版目录中均有收录。清单格式：keyword,reason（keyword 为品名包含匹配的子串，如 硫酸氢氯吡格雷、维生素D滴剂）。

⚠️ 分子区分前缀不剥离：左旋/右旋、氢氯 等会改变分子身份的前缀不视为可剥离词缀。因此 氢氯吡格雷 不会被并入目录的 氯吡格雷（前者不在 2026 版目录，应判为非基药/待核，而非默认成基药）；左氨氯地平 也不会误并入 氨氯地平。任何无法识别的前缀一律保留，确保"相似但不同"的分子不会被错配成基药。

核心指标公式（N=目录品种数，M=匹配到的基药品种数，A_E/A_T=基药/全部金额，Q/P 同理）：

基药配备率（品种）= M / N × 100%
基药使用率（金额/数量/处方）= A_E / A_T、Q_E / Q_T、P_E / P_T × 100%
非基药占比 = 1 − 基药占比
类别配备率 = 按 top_cat 分组重复上式
配备缺口 = 目录中"应配备但未采购"的品种清单
多期趋势 = 各期使用率/配备率环比

方法学提示：配备率反映"有没有"，使用率反映"用了多少"，二者结合评价基药制度落实；金额口径受贵价药影响，宜同时报品种/数量/处方口径；抗菌药物（is_antimicrobial）须单列按专项管理办法评价；"应配备"子集应结合医院功能定位（基层/综合/专科）确定，而非全目录。

六、输出规范（期刊级）

analyze_procurement.py 输出到 --outdir：

基药采购对比分析报告.md：总体指标卡 + 类别维度表 + 多期趋势 + 配备缺口 + 非基药待核清单
基药采购对比分析明细.xlsx：多 sheet（总体指标 / 类别维度 / 多期趋势 / 配备缺口 / 待核）
fig1_金额构成环形图.png：基药 vs 非基药金额构成
fig2_类别配备率条形图.png：各类别基药配备率（品种口径，降序）
fig3_多期趋势折线图.png：配备率 vs 使用率多期趋势（≥2 期时）
fig4_配备缺口分布图.png：未配备基药按类别分布

图表风格：matplotlib dpi=300、中文无乱码（自动探测 msyh/simhei 等）、去 3D、统一配色（基药主蓝 #1E4FA8 vs 非基药灰 #BFBFBF）、必要处加数据标签。

七、注意事项

首次使用建议人工抽检基线 20~30 条（目录 PDF 文本解析，极少数跨行规格/功能前缀已清洗）。
匹配质量取决于录入表"通用名/品名"规范程度；优先填 generic_name 并维护 alias_map，可把自动匹配率提升到 95%+。
模糊匹配只给"待核"建议，不要直接当作基药判定，须人工确认。
目录每年可能调整，更新时重跑 parse_catalog.py，分析口径不变。
分析引擎默认 --catalog 指向 assets/基药目录2026基线.csv，无需手动指定。