# 药典数据准备操作指南

> 版本：v1.0  
> 适用于：数据录入人员、药典内容整理人员

---

## 一、数据格式

药典数据使用 JSON 格式，每条药品一个对象。**必须严格遵循以下 Schema：**

```json
{
  "drug_id": "H20000001",
  "name": "阿莫西林",
  "name_en": "Amoxicillin",
  "pinyin": "Amoxilin",
  "category": "化学药",
  "subcategory": "β-内酰胺类抗生素",
  "sections": {
    "性状": "...",
    "鉴别": "...",
    "检查": "...",
    "含量测定": "...",
    "类别": "...",
    "贮藏": "...",
    "制剂": "...",
    "用法与用量": "...",
    "禁忌": "...",
    "不良反应": "...",
    "注意事项": "..."
  },
  "source": {
    "version": "2020年版",
    "volume": "二部",
    "page": "567-569"
  }
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `drug_id` | 字符串 | ✅ | 唯一标识。化学药格式 `H` + 8 位数字，中药 `Z` + 8 位数字，生物制品 `S` + 8 位数字 |
| `name` | 字符串 | ✅ | 药品通用名（中文） |
| `name_en` | 字符串 | | 英文名 |
| `pinyin` | 字符串 | | 汉语拼音 |
| `category` | 字符串 | ✅ | **必须为以下值之一**：`化学药` `中药` `生物制品` `辅料` |
| `subcategory` | 字符串 | | 药理分类，如 `β-内酰胺类抗生素` `清热药` `解热镇痛抗炎药` |
| `sections` | 对象 | ✅ | 药品各栏目内容，见下方栏目说明 |
| `source.version` | 字符串 | ✅ | 药典版本，如 `2020年版` |
| `source.volume` | 字符串 | ✅ | 部，如 `一部` `二部` `三部` `四部` |
| `source.page` | 字符串 | ✅ | 页码，如实填写 |

### sections 栏目说明

| 栏目名 | 说明 | 示例 |
|--------|------|------|
| `性状` | 药品的物理形态、颜色、气味、溶解性 | 本品为白色结晶性粉末... |
| `鉴别` | 化学鉴别方法 | (1) 取本品约10mg... |
| `检查` | 质量标准检查项 | 酸度 取本品0.5g... |
| `含量测定` | 有效成分含量测定方法 | 照高效液相色谱法... |
| `类别` | 药品药理类别 | β-内酰胺类抗生素 |
| `贮藏` | 保存条件 | 遮光，密封保存 |
| `制剂` | 该药的制剂类型 | 片剂、胶囊剂、注射剂 |
| `用法与用量` | 给药方式、剂量 | 口服，一次0.5g... |
| `禁忌` | 禁忌症 | 对本品过敏者禁用 |
| `不良反应` | 已知不良反应 | 常见恶心、呕吐... |
| `注意事项` | 使用注意 | 孕妇慎用... |

> **原则**：逐字照搬药典原文，不要改写、不要省略、不要添加个人理解。

---

## 二、文件准备

### 步骤 1：创建 JSON 文件

在 `data-pipeline/data/` 目录下创建 `.json` 文件，数组格式：

```
data-pipeline/
└── data/
    ├── sample_drugs.json      ← 示例数据（已有4条，可参考）
    ├── chem_drugs.json         ← 化学药数据（你创建的）
    ├── tcm_drugs.json          ← 中药数据
    └── biologics.json          ← 生物制品数据
```

### 步骤 2：验证格式

```bash
# 在项目根目录执行
python3 -c "
import json
with open('data-pipeline/data/你的文件.json') as f:
    data = json.load(f)
print(f'共 {len(data)} 条，第1条药品名：{data[0][\"name\"]}')
"
```

### 步骤 3：入库

```bash
# 修改 data-pipeline/ingest.py 中最后几行的文件路径，或直接执行：
source .venv/bin/activate
python3 -c "
import asyncio, json, sys
sys.path.insert(0, 'data-pipeline')
from ingest import ingest_drugs
asyncio.run(ingest_drugs('data-pipeline/data/你的文件.json'))
"
```

---

## 三、数据来源

| 来源 | 方式 | 说明 |
|------|------|------|
| **药典 PDF 拷贝粘贴** | 手动 | 打开药典 PDF，逐个药品复制粘贴到 JSON 模板 |
| **NMPA 官网说明书** | 半自动 | 通过批准文号搜索，复制说明书内容 |
| **结构化表格** | Excel → JSON | 如有 Excel 格式的药品数据表，可写脚本批量转换 |

### 从药典 PDF 录入技巧

1. 用 Adobe Acrobat 或任意 PDF 阅读器打开《中国药典》
2. Ctrl+F 搜索药品名
3. 逐栏目复制到 JSON 模板
4. **特别注意**：化学符号上标下标（如 `C₁₆H₁₈O₉`），建议保留为普通文本 `C16H18O9`

---

## 四、批量导入模板

如果数据量大，可以先填 Excel 再脚本转换。Excel 表头如下：

| drug_id | name | category | subcategory | 性状 | 鉴别 | 检查 | 含量测定 | 类别 | 贮藏 | 制剂 | 用法与用量 | 禁忌 | 不良反应 | 注意事项 | version | volume | page |
|---------|------|----------|-------------|------|------|------|---------|------|------|------|-----------|------|---------|---------|---------|--------|------|

---

## 五、常见问题

**Q: 一个药品的栏目太多，有些没有内容怎么办？**
A: 不填该栏目即可，sections 中只保留有内容的栏目。

**Q: 来源页码怎么写？**
A: 如实写药典原文所在页码。如 `567-569`（跨页），`216`（单页）。

**Q: drug_id 怎么编？**
A: 化学药用批准文号去掉地区码，如国药准字H20000001 → `H20000001`。中药同理。没有批准文号的药品按 `H00000001` 自增编号。

**Q: 入库后怎么更新？**
A: 修改 JSON 文件重新执行入库脚本即可，脚本会 `ON CONFLICT DO UPDATE` 自动覆盖同名 drug_id。