# 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 ``` ### 主要接口 - **认证**: - `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