kushidou/YaoXiang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
YaoXiang/docs/api.md
T
tang1219 ead13f863c 首次提交by MimoCode
2026-06-15 14:50:15 +08:00

20 KiB
Raw Permalink Blame History

API 接口文档

1. 概述

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

1.1 基础信息

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

1.2 通用响应格式

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误响应：

{
  "code": 400,
  "message": "错误信息",
  "detail": "详细错误信息（可选）"
}

1.3 通用状态码

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

2. 认证接口

2.1 用户登录

POST /v1/auth/login

请求体：

{
  "username": "admin",
  "password": "123456"
}

响应：

{
  "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>

响应：

{
  "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

请求体：

{
  "old_password": "123456",
  "new_password": "654321"
}

响应：

{
  "code": 200,
  "message": "密码修改成功"
}

3. 药品管理接口

3.1 获取药品列表

GET /v1/medicines

查询参数：

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

响应：

{
  "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

响应：

{
  "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

请求体：

{
  "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
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "布洛芬",
    ...
  }
}

3.4 更新药品

PUT /v1/medicines/{medicine_id}

请求体：

{
  "name": "布洛芬缓释胶囊",
  "expiry_grace_days": 45
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "布洛芬缓释胶囊",
    ...
  }
}

3.5 删除药品

DELETE /v1/medicines/{medicine_id}

响应：

{
  "code": 200,
  "message": "删除成功"
}

3.6 上传药品图片

POST /v1/medicines/{medicine_id}/images

请求体（multipart/form-data）：

参数 类型 必填 说明
type string 是 图片类型：front/expiry/leaflet
file file 是 图片文件

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "path": "/uploads/medicines/1/front.jpg"
  }
}

4. 批次管理接口

4.1 获取药品的所有批次

GET /v1/medicines/{medicine_id}/batches

响应：

{
  "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

请求体：

{
  "batch_no": "A20240101",
  "production_date": "2024-01-01",
  "expiry_date": "2027-01-01",
  "quantity": 20,
  "location": "药箱A层"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "medicine_id": 1,
    "batch_no": "A20240101",
    ...
  }
}

4.3 更新批次

PUT /v1/batches/{batch_id}

请求体：

{
  "quantity": 15,
  "location": "药箱B层"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 15,
    ...
  }
}

4.4 删除批次

DELETE /v1/batches/{batch_id}

响应：

{
  "code": 200,
  "message": "删除成功"
}

4.5 取药（扣减库存）

POST /v1/batches/{batch_id}/dispense

请求体：

{
  "quantity": 5
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 15,
    ...
  }
}

4.6 入库（增加库存）

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

请求体：

{
  "quantity": 10
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "quantity": 25,
    ...
  }
}

5. 分类管理接口

5.1 获取分类列表

GET /v1/categories

查询参数：

参数 类型 必填 默认值 说明
parent_id integer 否 null 父分类ID
level integer 否 null 分类层级

响应：

{
  "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

请求体：

{
  "name": "维生素",
  "parent_id": 1,
  "level": 2,
  "icon": "vitamin",
  "sort_order": 6
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 11,
    "name": "维生素",
    ...
  }
}

5.3 更新分类

PUT /v1/categories/{category_id}

请求体：

{
  "name": "维生素类",
  "sort_order": 7
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 11,
    "name": "维生素类",
    ...
  }
}

5.4 删除分类

DELETE /v1/categories/{category_id}

响应：

{
  "code": 200,
  "message": "删除成功"
}

6. 搜索接口

6.1 关键词搜索

GET /v1/search

查询参数：

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

响应：

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

6.2 自然语言搜索

POST /v1/search/natural

请求体：

{
  "query": "孩子发烧了，应该吃什么药？"
}

响应：

{
  "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 是 药盒正面照片

响应：

{
  "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 是 生产日期/有效期照片

响应：

{
  "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 是 说明书照片

响应：

{
  "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 每页数量

响应：

{
  "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

响应：

{
  "code": 200,
  "message": "success"
}

8.3 标记所有通知为已读

PUT /v1/notifications/read-all

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "count": 5
  }
}

8.4 删除通知

DELETE /v1/notifications/{notification_id}

响应：

{
  "code": 200,
  "message": "删除成功"
}

8.5 发送测试通知

POST /v1/notifications/test

请求体：

{
  "provider": "serverchan"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "success": true
  }
}

9. 用户管理接口

9.1 获取用户列表

GET /v1/users

响应：

{
  "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

请求体：

{
  "username": "user1",
  "password": "123456",
  "display_name": "用户1",
  "email": "user1@example.com",
  "role": "user",
  "notification_level": "normal"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 2,
    "username": "user1",
    ...
  }
}

9.3 更新用户

PUT /v1/users/{user_id}

请求体：

{
  "display_name": "新名字",
  "role": "readonly",
  "notification_level": "high"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 2,
    "display_name": "新名字",
    ...
  }
}

9.4 删除用户

DELETE /v1/users/{user_id}

响应：

{
  "code": 200,
  "message": "删除成功"
}

9.5 重置用户密码

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

请求体：

{
  "new_password": "654321"
}

响应：

{
  "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 每页数量

响应：

{
  "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

响应：

{
  "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}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "key": "ai_provider",
    "value": "openai",
    "description": "AI 服务提供者"
  }
}

11.3 更新设置

PUT /v1/settings/{key}

请求体：

{
  "value": "gemini"
}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "key": "ai_provider",
    "value": "gemini",
    "description": "AI 服务提供者"
  }
}

11.4 批量更新设置

PUT /v1/settings

请求体：

{
  "settings": [
    {
      "key": "ai_provider",
      "value": "openai"
    },
    {
      "key": "openai_api_key",
      "value": "sk-xxx"
    }
  ]
}

响应：

{
  "code": 200,
  "message": "success"
}

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

12.1 查询库存

GET /v1/external/inventory

查询参数：

参数 类型 必填 默认值 说明
name string 否 null 药品名称
category string 否 null 分类名称

响应：

{
  "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

请求体：

{
  "medicine_name": "布洛芬",
  "quantity": 5
}

响应：

{
  "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}

响应：

{
  "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) 协议暴露以下工具：

{
  "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

请求体：

{
  "tool": "query_inventory",
  "arguments": {
    "medicine_name": "布洛芬"
  }
}

响应：

{
  "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

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "path": "/uploads/images/2024/01/abc123.jpg",
    "url": "http://localhost:8000/uploads/images/2024/01/abc123.jpg"
  }
}
Reference in New Issue View Git Blame Copy Permalink