258 lines
5.8 KiB
Markdown
258 lines
5.8 KiB
Markdown
# DeepRisk Backend - 税务风控审查系统后端
|
||
|
||
基于 Python + FastAPI + PostgreSQL 构建的后端服务
|
||
|
||
## 技术栈
|
||
|
||
- **Web框架**: FastAPI 0.110+
|
||
- **数据库**: PostgreSQL 15.x + SQLAlchemy 2.x
|
||
- **异步驱动**: asyncpg
|
||
- **数据验证**: Pydantic 2.x
|
||
- **任务队列**: Celery
|
||
- **缓存**: Redis
|
||
- **API文档**: Swagger UI + ReDoc
|
||
- **依赖管理**: Poetry
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── app/ # 应用主目录
|
||
│ ├── api/ # API路由
|
||
│ │ └── v1/ # API版本1
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth.py # 认证相关API
|
||
│ │ ├── user.py # 用户管理API
|
||
│ │ └── ...
|
||
│ ├── models/ # SQLAlchemy模型
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base.py # 基础模型
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── streamer.py # 主播信息模型
|
||
│ │ └── ...
|
||
│ ├── schemas/ # Pydantic模式
|
||
│ │ ├── __init__.py
|
||
│ │ ├── user.py # 用户相关模式
|
||
│ │ └── ...
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth_service.py # 认证服务
|
||
│ │ └── ...
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── __init__.py
|
||
│ │ ├── helpers.py # 辅助函数
|
||
│ │ └── ...
|
||
│ ├── tests/ # 测试
|
||
│ │ ├── __init__.py
|
||
│ │ ├── conftest.py # pytest配置
|
||
│ │ └── ...
|
||
│ ├── main.py # FastAPI应用入口
|
||
│ ├── config.py # 配置管理
|
||
│ └── database.py # 数据库配置
|
||
├── alembic/ # 数据库迁移
|
||
│ ├── versions/ # 迁移版本
|
||
│ ├── env.py # 迁移环境配置
|
||
│ └── script.py.mako # 迁移脚本模板
|
||
├── scripts/ # 脚本文件
|
||
│ ├── init_db.py # 初始化数据库
|
||
│ └── ...
|
||
├── static/ # 静态文件
|
||
│ ├── uploads/ # 上传文件
|
||
│ └── reports/ # 报告文件
|
||
├── templates/ # 模板文件
|
||
├── pyproject.toml # Poetry配置
|
||
├── .env.example # 环境变量示例
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
```bash
|
||
# 安装Python 3.11+
|
||
python --version
|
||
|
||
# 安装Poetry
|
||
curl -sSL https://install.python-poetry.org | python3 -
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
cd backend
|
||
poetry install
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，配置数据库连接等信息
|
||
```
|
||
|
||
### 4. 数据库设置
|
||
|
||
```bash
|
||
# 初始化数据库
|
||
poetry run alembic upgrade head
|
||
|
||
# 或者运行初始化脚本
|
||
poetry run python scripts/init_db.py
|
||
```
|
||
|
||
### 5. 运行应用
|
||
|
||
```bash
|
||
# windows 开发模式
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
|
||
# mac 激活虚拟环境
|
||
cd backend
|
||
source venv/bin/activate
|
||
|
||
# 启动应用
|
||
uvicorn app.main:app --reload
|
||
|
||
# 退出虚拟环境
|
||
deactivate
|
||
|
||
# 生产模式
|
||
poetry run gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
|
||
```
|
||
|
||
### 6. 访问API文档
|
||
|
||
- Swagger UI: http://localhost:8000/api/v1/docs
|
||
- ReDoc: http://localhost:8000/api/v1/redoc
|
||
|
||
## 开发指南
|
||
|
||
### 代码规范
|
||
|
||
- 遵循 PEP 8 代码规范
|
||
- 使用 Black 格式化代码
|
||
- 使用 isort 排序导入
|
||
- 使用 mypy 进行类型检查
|
||
|
||
```bash
|
||
# 格式化代码
|
||
poetry run black .
|
||
poetry run isort .
|
||
|
||
# 类型检查
|
||
poetry run mypy .
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
poetry run pytest
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
poetry run pytest --cov=app --cov-report=html
|
||
|
||
# 运行特定测试
|
||
poetry run pytest app/tests/test_auth.py -v
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 创建新的迁移
|
||
poetry run alembic revision --autogenerate -m "描述"
|
||
|
||
# 应用迁移
|
||
poetry run alembic upgrade head
|
||
|
||
# 回滚迁移
|
||
poetry run alembic downgrade -1
|
||
```
|
||
|
||
## API文档
|
||
|
||
### 认证方式
|
||
|
||
系统使用JWT Token进行认证
|
||
|
||
1. 首先登录获取token：
|
||
```http
|
||
POST /api/v1/auth/login
|
||
{
|
||
"username": "admin",
|
||
"password": "password"
|
||
}
|
||
```
|
||
|
||
2. 在后续请求中携带token：
|
||
```http
|
||
Authorization: Bearer <your-token>
|
||
```
|
||
|
||
### 主要接口
|
||
|
||
- **认证**:
|
||
- `POST /api/v1/auth/login` - 用户登录
|
||
- `POST /api/v1/auth/refresh` - 刷新token
|
||
- `POST /api/v1/auth/logout` - 退出登录
|
||
|
||
- **用户管理**:
|
||
- `GET /api/v1/users` - 获取用户列表
|
||
- `POST /api/v1/users` - 创建用户
|
||
- `GET /api/v1/users/{id}` - 获取用户详情
|
||
- `PUT /api/v1/users/{id}` - 更新用户
|
||
- `DELETE /api/v1/users/{id}` - 删除用户
|
||
|
||
- **主播管理**:
|
||
- `GET /api/v1/streamers` - 获取主播列表
|
||
- `POST /api/v1/streamers` - 创建主播
|
||
- `GET /api/v1/streamers/{id}` - 获取主播详情
|
||
|
||
## 性能优化
|
||
|
||
- 使用异步编程提升并发性能
|
||
- 数据库查询优化（索引、分页）
|
||
- Redis缓存热点数据
|
||
- Celery异步处理耗时任务
|
||
|
||
## 监控与日志
|
||
|
||
- 使用Loguru进行日志管理
|
||
- 支持结构化日志输出
|
||
- 集成Sentry进行错误监控（可选）
|
||
|
||
## 部署
|
||
|
||
### Docker部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t deeprisk-backend .
|
||
|
||
# 运行容器
|
||
docker run -d -p 8000:8000 --name deeprisk deeprisk-backend
|
||
```
|
||
|
||
### Docker Compose部署
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f web
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 贡献
|
||
|
||
1. Fork 项目
|
||
2. 创建特性分支
|
||
3. 提交更改
|
||
4. 推送到分支
|
||
5. 创建Pull Request
|