首次提交by MimoCode
This commit is contained in:
tang1219
@@ -0,0 +1,540 @@
|
||||
# 药箱后端开发文档
|
||||
|
||||
## 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()
|
||||
```
|
||||
Reference in New Issue
Block a user