541 lines
15 KiB
Markdown
541 lines
15 KiB
Markdown
# 药箱后端开发文档
|
||
|
||
## 1. 项目概述
|
||
|
||
药箱（YaoXiang）是一个家庭药品与应急物资管理系统，后端采用 FastAPI 框架，提供 RESTful API 服务。
|
||
|
||
## 2. 技术栈
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Python | 3.11+ | 运行环境 |
|
||
| FastAPI | 0.104.1 | Web 框架 |
|
||
| SQLAlchemy | 2.0.23 | ORM 框架 |
|
||
| Alembic | 1.13.0 | 数据库迁移 |
|
||
| SQLite | - | 数据库 |
|
||
| Pydantic | 2.5.2 | 数据验证 |
|
||
| python-jose | 3.3.0 | JWT 认证 |
|
||
| passlib | 1.7.4 | 密码加密 |
|
||
| OpenAI | 1.6.1 | AI 服务 |
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── app/ # 主应用目录
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI 应用入口
|
||
│ ├── config.py # 配置管理
|
||
│ ├── database.py # 数据库连接
|
||
│ │
|
||
│ ├── api/ # API 路由层
|
||
│ │ ├── router.py # 路由汇总
|
||
│ │ └── v1/ # API 版本 1
|
||
│ │ ├── auth.py # 认证接口
|
||
│ │ ├── medicines.py # 药品管理接口
|
||
│ │ ├── batches.py # 批次管理接口
|
||
│ │ ├── categories.py # 分类管理接口
|
||
│ │ ├── search.py # 搜索接口
|
||
│ │ ├── notifications.py # 通知接口
|
||
│ │ ├── ai.py # AI 识别接口
|
||
│ │ ├── users.py # 用户管理接口
|
||
│ │ └── settings.py # 系统设置接口
|
||
│ │
|
||
│ ├── models/ # SQLAlchemy 数据模型
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── medicine.py # 药品模型
|
||
│ │ ├── batch.py # 批次模型
|
||
│ │ ├── category.py # 分类模型
|
||
│ │ ├── audit_log.py # 审计日志模型
|
||
│ │ ├── notification.py # 通知模型
|
||
│ │ └── setting.py # 设置模型
|
||
│ │
|
||
│ ├── schemas/ # Pydantic 数据模式
|
||
│ │ ├── user.py
|
||
│ │ ├── medicine.py
|
||
│ │ ├── batch.py
|
||
│ │ ├── category.py
|
||
│ │ └── auth.py
|
||
│ │
|
||
│ ├── services/ # 业务服务层
|
||
│ │ ├── auth.py # 认证服务
|
||
│ │ ├── user.py # 用户服务
|
||
│ │ ├── medicine.py # 药品服务
|
||
│ │ ├── batch.py # 批次服务
|
||
│ │ ├── category.py # 分类服务
|
||
│ │ ├── audit.py # 审计日志服务
|
||
│ │ └── notification.py # 通知服务
|
||
│ │
|
||
│ ├── repositories/ # 数据访问层
|
||
│ │ ├── user.py
|
||
│ │ ├── medicine.py
|
||
│ │ ├── batch.py
|
||
│ │ ├── category.py
|
||
│ │ ├── audit_log.py
|
||
│ │ └── notification.py
|
||
│ │
|
||
│ ├── ai/ # AI Provider 模块
|
||
│ │ ├── base.py # 抽象基类
|
||
│ │ ├── openai_provider.py # OpenAI 实现
|
||
│ │ └── manager.py # Provider 管理器
|
||
│ │
|
||
│ ├── notifications/ # 通知系统
|
||
│ │ ├── base.py # 抽象基类
|
||
│ │ ├── serverchan.py # Server酱
|
||
│ │ ├── pushplus.py # PushPlus
|
||
│ │ └── manager.py # 通知管理器
|
||
│ │
|
||
│ ├── storage/ # 文件存储
|
||
│ │ ├── base.py # 抽象基类
|
||
│ │ ├── local.py # 本地存储
|
||
│ │ └── manager.py # 存储管理器
|
||
│ │
|
||
│ ├── core/ # 核心功能
|
||
│ │ ├── security.py # 安全工具 (JWT, 密码)
|
||
│ │ ├── deps.py # 依赖注入
|
||
│ │ └── exceptions.py # 异常处理
|
||
│ │
|
||
│ └── tasks/ # 异步任务
|
||
│ └── expiry_check.py # 到期检查任务
|
||
│
|
||
├── tests/ # 测试目录
|
||
├── data/ # 数据目录
|
||
├── requirements.txt # Python 依赖
|
||
├── .env.example # 环境变量示例
|
||
└── .env # 环境变量配置
|
||
```
|
||
|
||
## 4. 快速开始
|
||
|
||
### 4.1 环境准备
|
||
|
||
```bash
|
||
# 进入后端目录
|
||
cd backend
|
||
|
||
# 创建虚拟环境 (可选)
|
||
python -m venv venv
|
||
venv\Scripts\activate # Windows
|
||
# source venv/bin/activate # Linux/Mac
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4.2 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量示例文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，配置必要的参数
|
||
```
|
||
|
||
### 4.3 启动服务
|
||
|
||
```bash
|
||
# 开发模式启动
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 生产模式启动
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||
```
|
||
|
||
### 4.4 访问 API 文档
|
||
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
- 健康检查: http://localhost:8000/health
|
||
|
||
## 5. 配置说明
|
||
|
||
### 5.1 环境变量配置
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| DATABASE_URL | sqlite+aiosqlite:///./data/yaoxiang.db | 数据库连接字符串 |
|
||
| JWT_SECRET_KEY | your-secret-key-change-in-production | JWT 密钥 |
|
||
| JWT_ALGORITHM | HS256 | JWT 算法 |
|
||
| JWT_EXPIRATION_HOURS | 24 | JWT 过期时间(小时) |
|
||
| AI_PROVIDER | openai | AI 服务提供者 |
|
||
| OPENAI_API_KEY | - | OpenAI API Key |
|
||
| OPENAI_MODEL | gpt-4o | OpenAI 模型 |
|
||
| UPLOAD_DIR | ./data/uploads | 文件上传目录 |
|
||
| CORS_ORIGINS | http://localhost:5173 | CORS 允许的源 |
|
||
|
||
### 5.2 AI Provider 配置
|
||
|
||
支持的 AI Provider：
|
||
- **openai**: OpenAI GPT-4o
|
||
- **gemini**: Google Gemini
|
||
- **claude**: Anthropic Claude
|
||
- **deepseek**: DeepSeek
|
||
- **ollama**: 本地 Ollama
|
||
|
||
## 6. 数据库设计
|
||
|
||
### 6.1 数据表
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| users | 用户表 |
|
||
| categories | 分类表 |
|
||
| medicines | 药品表 |
|
||
| batches | 批次表 |
|
||
| audit_logs | 审计日志表 |
|
||
| notifications | 通知表 |
|
||
| settings | 系统设置表 |
|
||
|
||
### 6.2 核心表结构
|
||
|
||
#### users 表
|
||
```sql
|
||
CREATE TABLE users (
|
||
id INTEGER PRIMARY KEY,
|
||
username VARCHAR(50) UNIQUE NOT NULL,
|
||
password_hash VARCHAR(255) NOT NULL,
|
||
role VARCHAR(20) DEFAULT 'user',
|
||
display_name VARCHAR(100),
|
||
email VARCHAR(100),
|
||
notification_level VARCHAR(20) DEFAULT 'normal',
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
created_at TIMESTAMP,
|
||
updated_at TIMESTAMP
|
||
);
|
||
```
|
||
|
||
#### medicines 表
|
||
```sql
|
||
CREATE TABLE medicines (
|
||
id INTEGER PRIMARY KEY,
|
||
name VARCHAR(200) NOT NULL,
|
||
generic_name VARCHAR(200),
|
||
brand_name VARCHAR(200),
|
||
manufacturer VARCHAR(200),
|
||
specification VARCHAR(200),
|
||
category_id INTEGER REFERENCES categories(id),
|
||
indications TEXT,
|
||
adult_dose TEXT,
|
||
child_dose TEXT,
|
||
contraindications TEXT,
|
||
notes TEXT,
|
||
image_front_path VARCHAR(500),
|
||
image_expiry_path VARCHAR(500),
|
||
image_leaflet_paths JSON,
|
||
expiry_grace_days INTEGER DEFAULT 0,
|
||
created_by INTEGER REFERENCES users(id),
|
||
created_at TIMESTAMP,
|
||
updated_at TIMESTAMP
|
||
);
|
||
```
|
||
|
||
#### batches 表
|
||
```sql
|
||
CREATE TABLE batches (
|
||
id INTEGER PRIMARY KEY,
|
||
medicine_id INTEGER REFERENCES medicines(id),
|
||
batch_no VARCHAR(100),
|
||
production_date DATE,
|
||
expiry_date DATE NOT NULL,
|
||
quantity INTEGER DEFAULT 0,
|
||
location VARCHAR(200),
|
||
is_expired BOOLEAN DEFAULT FALSE,
|
||
created_at TIMESTAMP,
|
||
updated_at TIMESTAMP
|
||
);
|
||
```
|
||
|
||
## 7. API 接口
|
||
|
||
### 7.1 认证接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/auth/login | 用户登录 |
|
||
| GET | /api/v1/auth/me | 获取当前用户信息 |
|
||
| PUT | /api/v1/auth/password | 修改密码 |
|
||
|
||
### 7.2 药品管理接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/medicines | 获取药品列表 | 登录用户 |
|
||
| GET | /api/v1/medicines/{id} | 获取药品详情 | 登录用户 |
|
||
| POST | /api/v1/medicines | 创建药品 | admin/user |
|
||
| PUT | /api/v1/medicines/{id} | 更新药品 | admin/user |
|
||
| DELETE | /api/v1/medicines/{id} | 删除药品 | admin |
|
||
|
||
### 7.3 批次管理接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/batches/medicine/{medicine_id} | 获取药品的所有批次 | 登录用户 |
|
||
| GET | /api/v1/batches/{id} | 获取批次详情 | 登录用户 |
|
||
| POST | /api/v1/batches/medicine/{medicine_id} | 创建批次 | admin/user |
|
||
| PUT | /api/v1/batches/{id} | 更新批次 | admin/user |
|
||
| DELETE | /api/v1/batches/{id} | 删除批次 | admin |
|
||
| POST | /api/v1/batches/{id}/dispense | 取药 | admin/user |
|
||
| POST | /api/v1/batches/{id}/add-stock | 入库 | admin/user |
|
||
|
||
### 7.4 分类管理接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/categories | 获取分类列表 | 登录用户 |
|
||
| GET | /api/v1/categories/tree | 获取分类树 | 登录用户 |
|
||
| GET | /api/v1/categories/{id} | 获取分类详情 | 登录用户 |
|
||
| POST | /api/v1/categories | 创建分类 | admin |
|
||
| PUT | /api/v1/categories/{id} | 更新分类 | admin |
|
||
| DELETE | /api/v1/categories/{id} | 删除分类 | admin |
|
||
|
||
### 7.5 搜索接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/v1/search?q=关键词 | 关键词搜索 |
|
||
| POST | /api/v1/search/natural | 自然语言搜索 |
|
||
|
||
### 7.6 AI 识别接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| POST | /api/v1/ai/recognize-medicine | 识别药盒 | admin/user |
|
||
| POST | /api/v1/ai/recognize-dates | 识别日期 | admin/user |
|
||
| POST | /api/v1/ai/recognize-leaflet | 识别说明书 | admin/user |
|
||
|
||
### 7.7 用户管理接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/users | 获取用户列表 | admin |
|
||
| GET | /api/v1/users/{id} | 获取用户详情 | admin |
|
||
| POST | /api/v1/users | 创建用户 | admin |
|
||
| PUT | /api/v1/users/{id} | 更新用户 | admin |
|
||
| DELETE | /api/v1/users/{id} | 删除用户 | admin |
|
||
| POST | /api/v1/users/{id}/reset-password | 重置密码 | admin |
|
||
|
||
### 7.8 通知接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/v1/notifications | 获取通知列表 |
|
||
| PUT | /api/v1/notifications/{id}/read | 标记为已读 |
|
||
| PUT | /api/v1/notifications/read-all | 全部标记为已读 |
|
||
| DELETE | /api/v1/notifications/{id} | 删除通知 |
|
||
|
||
### 7.9 系统设置接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/settings | 获取所有设置 | admin |
|
||
| GET | /api/v1/settings/{key} | 获取单个设置 | admin |
|
||
| PUT | /api/v1/settings/{key} | 更新设置 | admin |
|
||
|
||
## 8. 开发指南
|
||
|
||
### 8.1 添加新的 API 接口
|
||
|
||
1. 在 `app/api/v1/` 目录下创建或修改路由文件
|
||
2. 定义请求和响应的 Pydantic 模式
|
||
3. 实现业务逻辑（服务层）
|
||
4. 在 `app/api/router.py` 中注册路由
|
||
|
||
示例：
|
||
```python
|
||
# app/api/v1/example.py
|
||
from fastapi import APIRouter, Depends
|
||
from app.core.deps import get_current_user
|
||
|
||
router = APIRouter()
|
||
|
||
@router.get("/")
|
||
async def list_examples(current_user = Depends(get_current_user)):
|
||
return {"message": "success"}
|
||
```
|
||
|
||
### 8.2 添加新的数据模型
|
||
|
||
1. 在 `app/models/` 目录下创建模型文件
|
||
2. 继承 `Base` 类
|
||
3. 定义表名和字段
|
||
4. 在 `app/models/__init__.py` 中导入
|
||
|
||
```python
|
||
# app/models/example.py
|
||
from sqlalchemy import Column, Integer, String
|
||
from app.database import Base
|
||
|
||
class Example(Base):
|
||
__tablename__ = "examples"
|
||
|
||
id = Column(Integer, primary_key=True, index=True)
|
||
name = Column(String(100), nullable=False)
|
||
```
|
||
|
||
### 8.3 添加新的服务
|
||
|
||
1. 在 `app/services/` 目录下创建服务文件
|
||
2. 实现业务逻辑
|
||
3. 使用 Repository 进行数据访问
|
||
|
||
```python
|
||
# app/services/example.py
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
from app.repositories.example import ExampleRepository
|
||
|
||
class ExampleService:
|
||
def __init__(self, db: AsyncSession):
|
||
self.db = db
|
||
self.repo = ExampleRepository(db)
|
||
|
||
async def get_example(self, example_id: int):
|
||
return await self.repo.get_by_id(example_id)
|
||
```
|
||
|
||
### 8.4 添加新的 AI Provider
|
||
|
||
1. 在 `app/ai/` 目录下创建 Provider 文件
|
||
2. 继承 `VisionProvider` 或 `TextProvider`
|
||
3. 实现抽象方法
|
||
4. 在 `app/ai/manager.py` 中注册
|
||
|
||
```python
|
||
# app/ai/custom_provider.py
|
||
from app.ai.base import VisionProvider, VisionResult
|
||
|
||
class CustomVisionProvider(VisionProvider):
|
||
async def recognize_medicine(self, image_bytes: bytes) -> VisionResult:
|
||
# 实现识别逻辑
|
||
return VisionResult(generic_name="药品名称")
|
||
|
||
async def recognize_dates(self, image_bytes: bytes):
|
||
# 实现日期识别
|
||
pass
|
||
```
|
||
|
||
### 8.5 添加新的通知 Provider
|
||
|
||
1. 在 `app/notifications/` 目录下创建 Provider 文件
|
||
2. 继承 `NotificationProvider`
|
||
3. 实现 `send` 和 `validate_config` 方法
|
||
|
||
```python
|
||
# app/notifications/custom.py
|
||
from app.notifications.base import NotificationProvider
|
||
|
||
class CustomNotificationProvider(NotificationProvider):
|
||
def __init__(self):
|
||
self.config = "your-config"
|
||
|
||
def validate_config(self) -> bool:
|
||
return bool(self.config)
|
||
|
||
async def send(self, title: str, content: str) -> bool:
|
||
# 实现发送逻辑
|
||
return True
|
||
```
|
||
|
||
## 9. 测试
|
||
|
||
### 9.1 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_auth.py
|
||
|
||
# 运行带详细输出的测试
|
||
pytest -v
|
||
```
|
||
|
||
### 9.2 编写测试
|
||
|
||
```python
|
||
# tests/test_example.py
|
||
import pytest
|
||
from httpx import AsyncClient
|
||
|
||
@pytest.mark.asyncio
|
||
async def test_health_check(client: AsyncClient):
|
||
response = await client.get("/health")
|
||
assert response.status_code == 200
|
||
assert response.json()["status"] == "healthy"
|
||
```
|
||
|
||
## 10. 部署
|
||
|
||
### 10.1 Docker 部署
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM python:3.11-slim
|
||
|
||
WORKDIR /app
|
||
|
||
COPY requirements.txt .
|
||
RUN pip install --no-cache-dir -r requirements.txt
|
||
|
||
COPY . .
|
||
|
||
EXPOSE 8000
|
||
|
||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||
```
|
||
|
||
### 10.2 生产环境配置
|
||
|
||
```bash
|
||
# 设置环境变量
|
||
export DATABASE_URL=sqlite+aiosqlite:///./data/yaoxiang.db
|
||
export JWT_SECRET_KEY=your-production-secret-key
|
||
export DEBUG=false
|
||
|
||
# 启动服务
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||
```
|
||
|
||
## 11. 常见问题
|
||
|
||
### 11.1 数据库初始化失败
|
||
|
||
检查 `data/` 目录是否存在，确保有写入权限。
|
||
|
||
### 11.2 AI 服务连接失败
|
||
|
||
检查 `.env` 文件中的 API Key 配置是否正确。
|
||
|
||
### 11.3 文件上传失败
|
||
|
||
检查 `UPLOAD_DIR` 配置的目录是否存在，确保有写入权限。
|
||
|
||
## 12. 扩展开发
|
||
|
||
### 12.1 添加新的通知渠道
|
||
|
||
参考 `app/notifications/serverchan.py` 实现新的通知 Provider。
|
||
|
||
### 12.2 添加新的 AI 能力
|
||
|
||
1. 扩展 `app/ai/base.py` 中的抽象基类
|
||
2. 实现新的 Provider
|
||
3. 在 `app/ai/manager.py` 中注册
|
||
|
||
### 12.3 添加新的定时任务
|
||
|
||
使用 APScheduler 添加定时任务：
|
||
|
||
```python
|
||
from apscheduler.schedulers.asyncio import AsyncIOScheduler
|
||
|
||
scheduler = AsyncIOScheduler()
|
||
|
||
async def my_task():
|
||
# 任务逻辑
|
||
pass
|
||
|
||
scheduler.add_job(my_task, 'cron', hour=9, minute=0)
|
||
scheduler.start()
|
||
```
|