deep-risk/backend

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. 环境准备

# 安装Python 3.11+
python --version

# 安装Poetry
curl -sSL https://install.python-poetry.org | python3 -

2. 安装依赖

cd backend
poetry install

3. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息

4. 数据库设置

# 初始化数据库
poetry run alembic upgrade head

# 或者运行初始化脚本
poetry run python scripts/init_db.py

5. 运行应用

# 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 进行类型检查

# 格式化代码
poetry run black .
poetry run isort .

# 类型检查
poetry run mypy .

测试

# 运行所有测试
poetry run pytest

# 运行测试并生成覆盖率报告
poetry run pytest --cov=app --cov-report=html

# 运行特定测试
poetry run pytest app/tests/test_auth.py -v

数据库迁移

# 创建新的迁移
poetry run alembic revision --autogenerate -m "描述"

# 应用迁移
poetry run alembic upgrade head

# 回滚迁移
poetry run alembic downgrade -1

API文档

认证方式

系统使用JWT Token进行认证

1. 首先登录获取token：

   POST /api/v1/auth/login
   {
     "username": "admin",
     "password": "password"
   }
   

2. 在后续请求中携带token：

   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部署

# 构建镜像
docker build -t deeprisk-backend .

# 运行容器
docker run -d -p 8000:8000 --name deeprisk deeprisk-backend

Docker Compose部署

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f web

许可证

MIT License

贡献

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request