YaoXiang/docs/api.md

# API 接口文档

## 1. 概述

本文档定义了药箱系统的所有 API 接口，包括认证、药品管理、批次管理、分类管理、搜索、通知、AI 识别、用户管理等模块。

### 1.1 基础信息

- **Base URL**: `http://localhost:8000/api`
- **API 版本**: v1
- **认证方式**: Bearer Token (JWT)
- **内容类型**: `application/json`
- **字符编码**: UTF-8

### 1.2 通用响应格式

**成功响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

**错误响应：**
```json
{
  "code": 400,
  "message": "错误信息",
  "detail": "详细错误信息（可选）"
}
```

### 1.3 通用状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 2. 认证接口

### 2.1 用户登录

**POST** `/v1/auth/login`

**请求体：**
```json
{
  "username": "admin",
  "password": "123456"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "admin",
      "display_name": "管理员",
      "role": "admin",
      "notification_level": "normal"
    }
  }
}
```

### 2.2 获取当前用户信息

**GET** `/v1/auth/me`

**请求头：**
```
Authorization: Bearer <token>
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "display_name": "管理员",
    "email": "admin@example.com",
    "role": "admin",
    "notification_level": "normal",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

### 2.3 修改密码

**PUT** `/v1/auth/password`

**请求体：**
```json
{
  "old_password": "123456",
  "new_password": "654321"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "密码修改成功"
}
```

---

## 3. 药品管理接口

### 3.1 获取药品列表

**GET** `/v1/medicines`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| category_id | integer | 否 | null | 分类ID |
| search | string | 否 | null | 搜索关键词 |
| page | integer | 否 | 1 | 页码 |
| page_size | integer | 否 | 20 | 每页数量 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 1,
        "name": "布洛芬",
        "generic_name": "布洛芬缓释胶囊",
        "brand_name": "芬必得",
        "manufacturer": "中美天津史克",
        "specification": "0.3g × 20粒",
        "category_id": 2,
        "total_quantity": 30,
        "nearest_expiry_date": "2027-01-15",
        "batch_count": 2,
        "image_front_path": "/uploads/medicines/1/front.jpg",
        "created_at": "2024-01-01T00:00:00"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}
```

### 3.2 获取药品详情

**GET** `/v1/medicines/{medicine_id}`

**路径参数：**
| 参数 | 类型 | 说明 |
|------|------|------|
| medicine_id | integer | 药品ID |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "布洛芬",
    "generic_name": "布洛芬缓释胶囊",
    "brand_name": "芬必得",
    "manufacturer": "中美天津史克",
    "specification": "0.3g × 20粒",
    "category_id": 2,
    "description": "非甾体抗炎药",
    "indications": "用于缓解轻至中度疼痛，如头痛、关节痛、偏头痛、牙痛、肌肉痛、神经痛、痛经",
    "adult_dose": "口服，一次1粒，一日2次",
    "child_dose": "遵医嘱",
    "contraindications": "对本品及其他非甾体抗炎药过敏者禁用",
    "notes": "请勿空腹服用",
    "expiry_grace_days": 30,
    "image_front_path": "/uploads/medicines/1/front.jpg",
    "image_expiry_path": "/uploads/medicines/1/expiry.jpg",
    "image_leaflet_paths": ["/uploads/medicines/1/leaflet_1.jpg"],
    "created_by": 1,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

### 3.3 创建药品

**POST** `/v1/medicines`

**请求体：**
```json
{
  "name": "布洛芬",
  "generic_name": "布洛芬缓释胶囊",
  "brand_name": "芬必得",
  "manufacturer": "中美天津史克",
  "specification": "0.3g × 20粒",
  "category_id": 2,
  "description": "非甾体抗炎药",
  "indications": "用于缓解轻至中度疼痛",
  "adult_dose": "口服，一次1粒，一日2次",
  "child_dose": "遵医嘱",
  "contraindications": "对本品过敏者禁用",
  "notes": "请勿空腹服用",
  "expiry_grace_days": 30
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "布洛芬",
    ...
  }
}
```

### 3.4 更新药品

**PUT** `/v1/medicines/{medicine_id}`

**请求体：**
```json
{
  "name": "布洛芬缓释胶囊",
  "expiry_grace_days": 45
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "布洛芬缓释胶囊",
    ...
  }
}
```

### 3.5 删除药品

**DELETE** `/v1/medicines/{medicine_id}`

**响应：**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 3.6 上传药品图片

**POST** `/v1/medicines/{medicine_id}/images`

**请求体（multipart/form-data）：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 是 | 图片类型：front/expiry/leaflet |
| file | file | 是 | 图片文件 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "path": "/uploads/medicines/1/front.jpg"
  }
}
```

---

## 4. 批次管理接口

### 4.1 获取药品的所有批次

**GET** `/v1/medicines/{medicine_id}/batches`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "medicine_id": 1,
      "batch_no": "A20240101",
      "production_date": "2024-01-01",
      "expiry_date": "2027-01-01",
      "quantity": 20,
      "location": "药箱A层",
      "is_expired": false,
      "created_at": "2024-01-01T00:00:00"
    }
  ]
}
```

### 4.2 创建批次

**POST** `/v1/medicines/{medicine_id}/batches`

**请求体：**
```json
{
  "batch_no": "A20240101",
  "production_date": "2024-01-01",
  "expiry_date": "2027-01-01",
  "quantity": 20,
  "location": "药箱A层"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "medicine_id": 1,
    "batch_no": "A20240101",
    ...
  }
}
```

### 4.3 更新批次

**PUT** `/v1/batches/{batch_id}`

**请求体：**
```json
{
  "quantity": 15,
  "location": "药箱B层"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 15,
    ...
  }
}
```

### 4.4 删除批次

**DELETE** `/v1/batches/{batch_id}`

**响应：**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 4.5 取药（扣减库存）

**POST** `/v1/batches/{batch_id}/dispense`

**请求体：**
```json
{
  "quantity": 5
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 15,
    ...
  }
}
```

### 4.6 入库（增加库存）

**POST** `/v1/batches/{batch_id}/add-stock`

**请求体：**
```json
{
  "quantity": 10
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 25,
    ...
  }
}
```

---

## 5. 分类管理接口

### 5.1 获取分类列表

**GET** `/v1/categories`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| parent_id | integer | 否 | null | 父分类ID |
| level | integer | 否 | null | 分类层级 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "药品",
      "parent_id": null,
      "level": 1,
      "icon": "medicine",
      "sort_order": 1,
      "children": [
        {
          "id": 5,
          "name": "感冒药",
          "parent_id": 1,
          "level": 2,
          "icon": null,
          "sort_order": 1
        }
      ]
    }
  ]
}
```

### 5.2 创建分类

**POST** `/v1/categories`

**请求体：**
```json
{
  "name": "维生素",
  "parent_id": 1,
  "level": 2,
  "icon": "vitamin",
  "sort_order": 6
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 11,
    "name": "维生素",
    ...
  }
}
```

### 5.3 更新分类

**PUT** `/v1/categories/{category_id}`

**请求体：**
```json
{
  "name": "维生素类",
  "sort_order": 7
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 11,
    "name": "维生素类",
    ...
  }
}
```

### 5.4 删除分类

**DELETE** `/v1/categories/{category_id}`

**响应：**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

---

## 6. 搜索接口

### 6.1 关键词搜索

**GET** `/v1/search`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| q | string | 是 | - | 搜索关键词 |
| type | string | 否 | name | 搜索类型：name/indications/all |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "布洛芬",
      "generic_name": "布洛芬缓释胶囊",
      "indications": "用于缓解轻至中度疼痛",
      "total_quantity": 30
    }
  ]
}
```

### 6.2 自然语言搜索

**POST** `/v1/search/natural`

**请求体：**
```json
{
  "query": "孩子发烧了，应该吃什么药？"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "medicine_id": 1,
      "name": "布洛芬",
      "reason": "适用于退热，可缓解发热症状",
      "match_score": 0.95
    },
    {
      "medicine_id": 2,
      "name": "对乙酰氨基酚",
      "reason": "适用于儿童退热",
      "match_score": 0.90
    }
  ]
}
```

---

## 7. AI 识别接口

### 7.1 识别药盒

**POST** `/v1/ai/recognize-medicine`

**请求体（multipart/form-data）：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 药盒正面照片 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "generic_name": "布洛芬缓释胶囊",
    "brand_name": "芬必得",
    "manufacturer": "中美天津史克",
    "specification": "0.3g × 20粒"
  }
}
```

### 7.2 识别日期

**POST** `/v1/ai/recognize-dates`

**请求体（multipart/form-data）：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 生产日期/有效期照片 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "production_date": "2024-08-01",
    "expiry_date": "2027-08-01"
  }
}
```

### 7.3 识别说明书

**POST** `/v1/ai/recognize-leaflet`

**请求体（multipart/form-data）：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 说明书照片 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "indications": "用于缓解轻至中度疼痛，如头痛、关节痛、偏头痛、牙痛、肌肉痛、神经痛、痛经",
    "adult_dose": "口服，一次1粒，一日2次",
    "child_dose": "遵医嘱",
    "contraindications": "对本品及其他非甾体抗炎药过敏者禁用",
    "notes": "请勿空腹服用"
  }
}
```

---

## 8. 通知接口

### 8.1 获取通知列表

**GET** `/v1/notifications`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| is_read | boolean | 否 | null | 是否已读 |
| type | string | 否 | null | 通知类型 |
| page | integer | 否 | 1 | 页码 |
| page_size | integer | 否 | 20 | 每页数量 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 1,
        "type": "expiry_warning",
        "title": "药品过期提醒",
        "content": "布洛芬批次A20240101将在30天内过期",
        "is_read": false,
        "related_id": 1,
        "created_at": "2024-01-01T00:00:00"
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}
```

### 8.2 标记通知为已读

**PUT** `/v1/notifications/{notification_id}/read`

**响应：**
```json
{
  "code": 200,
  "message": "success"
}
```

### 8.3 标记所有通知为已读

**PUT** `/v1/notifications/read-all`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "count": 5
  }
}
```

### 8.4 删除通知

**DELETE** `/v1/notifications/{notification_id}`

**响应：**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 8.5 发送测试通知

**POST** `/v1/notifications/test`

**请求体：**
```json
{
  "provider": "serverchan"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "success": true
  }
}
```

---

## 9. 用户管理接口

### 9.1 获取用户列表

**GET** `/v1/users`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "username": "admin",
      "display_name": "管理员",
      "role": "admin",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00"
    }
  ]
}
```

### 9.2 创建用户

**POST** `/v1/users`

**请求体：**
```json
{
  "username": "user1",
  "password": "123456",
  "display_name": "用户1",
  "email": "user1@example.com",
  "role": "user",
  "notification_level": "normal"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 2,
    "username": "user1",
    ...
  }
}
```

### 9.3 更新用户

**PUT** `/v1/users/{user_id}`

**请求体：**
```json
{
  "display_name": "新名字",
  "role": "readonly",
  "notification_level": "high"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 2,
    "display_name": "新名字",
    ...
  }
}
```

### 9.4 删除用户

**DELETE** `/v1/users/{user_id}`

**响应：**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 9.5 重置用户密码

**POST** `/v1/users/{user_id}/reset-password`

**请求体：**
```json
{
  "new_password": "654321"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success"
}
```

---

## 10. 审计日志接口

### 10.1 获取审计日志列表

**GET** `/v1/audit-logs`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| medicine_id | integer | 否 | null | 药品ID |
| user_id | integer | 否 | null | 用户ID |
| action | string | 否 | null | 操作类型 |
| start_date | string | 否 | null | 开始日期 |
| end_date | string | 否 | null | 结束日期 |
| page | integer | 否 | 1 | 页码 |
| page_size | integer | 否 | 20 | 每页数量 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 1,
        "medicine_id": 1,
        "batch_id": 1,
        "user_id": 1,
        "action": "dispense",
        "quantity_change": -5,
        "quantity_after": 15,
        "remark": null,
        "created_at": "2024-01-01T00:00:00",
        "medicine_name": "布洛芬",
        "user_name": "admin"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}
```

---

## 11. 系统设置接口

### 11.1 获取所有设置

**GET** `/v1/settings`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "key": "ai_provider",
      "value": "openai",
      "description": "AI 服务提供者"
    },
    {
      "key": "expiry_warning_days",
      "value": "90,30,7",
      "description": "到期提醒天数"
    }
  ]
}
```

### 11.2 获取单个设置

**GET** `/v1/settings/{key}`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "key": "ai_provider",
    "value": "openai",
    "description": "AI 服务提供者"
  }
}
```

### 11.3 更新设置

**PUT** `/v1/settings/{key}`

**请求体：**
```json
{
  "value": "gemini"
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "key": "ai_provider",
    "value": "gemini",
    "description": "AI 服务提供者"
  }
}
```

### 11.4 批量更新设置

**PUT** `/v1/settings`

**请求体：**
```json
{
  "settings": [
    {
      "key": "ai_provider",
      "value": "openai"
    },
    {
      "key": "openai_api_key",
      "value": "sk-xxx"
    }
  ]
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success"
}
```

---

## 12. 外部 API（供插件/MCP调用）

### 12.1 查询库存

**GET** `/v1/external/inventory`

**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| name | string | 否 | null | 药品名称 |
| category | string | 否 | null | 分类名称 |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "medicine_id": 1,
      "name": "布洛芬",
      "total_quantity": 30,
      "batches": [
        {
          "batch_id": 1,
          "batch_no": "A20240101",
          "quantity": 20,
          "expiry_date": "2027-01-01"
        }
      ]
    }
  ]
}
```

### 12.2 取药

**POST** `/v1/external/dispense`

**请求体：**
```json
{
  "medicine_name": "布洛芬",
  "quantity": 5
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "medicine_id": 1,
    "batch_id": 1,
    "dispensed_quantity": 5,
    "remaining_quantity": 25
  }
}
```

### 12.3 查询药品详情

**GET** `/v1/external/medicine/{medicine_name}`

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "medicine_id": 1,
    "name": "布洛芬",
    "generic_name": "布洛芬缓释胶囊",
    "indications": "用于缓解轻至中度疼痛",
    "adult_dose": "口服，一次1粒，一日2次",
    "contraindications": "对本品过敏者禁用",
    "total_quantity": 30
  }
}
```

---

## 13. MCP 协议支持

### 13.1 MCP 工具定义

系统支持通过 MCP (Model Context Protocol) 协议暴露以下工具：

```json
{
  "tools": [
    {
      "name": "query_inventory",
      "description": "查询家庭药品库存",
      "inputSchema": {
        "type": "object",
        "properties": {
          "medicine_name": {
            "type": "string",
            "description": "药品名称（可选）"
          }
        }
      }
    },
    {
      "name": "dispense_medicine",
      "description": "取药操作",
      "inputSchema": {
        "type": "object",
        "properties": {
          "medicine_name": {
            "type": "string",
            "description": "药品名称"
          },
          "quantity": {
            "type": "integer",
            "description": "取药数量"
          }
        },
        "required": ["medicine_name", "quantity"]
      }
    },
    {
      "name": "get_medicine_info",
      "description": "获取药品详细信息",
      "inputSchema": {
        "type": "object",
        "properties": {
          "medicine_name": {
            "type": "string",
            "description": "药品名称"
          }
        },
        "required": ["medicine_name"]
      }
    }
  ]
}
```

### 13.2 MCP 工具调用

**POST** `/v1/mcp/call`

**请求体：**
```json
{
  "tool": "query_inventory",
  "arguments": {
    "medicine_name": "布洛芬"
  }
}
```

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "找到布洛芬，当前库存30粒，最近过期批次将在2027年1月过期。"
      }
    ]
  }
}
```

---

## 14. 文件上传接口

### 14.1 上传图片

**POST** `/v1/upload/image`

**请求体（multipart/form-data）：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 图片文件 |
| category | string | 否 | 图片分类：medicine/leaflet/other |

**响应：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "path": "/uploads/images/2024/01/abc123.jpg",
    "url": "http://localhost:8000/uploads/images/2024/01/abc123.jpg"
  }
}
```