deep-risk/backend/PROJECT_STRUCTURE.md

项目代码结构说明

已创建的文件

1. 配置文件

• ✅ pyproject.toml - Poetry依赖管理配置
• ✅ .env.example - 环境变量示例文件
• ✅ .gitignore - Git忽略文件配置
• ✅ Dockerfile - Docker镜像构建文件
• ✅ docker-compose.yml - Docker Compose编排文件
• ✅ README.md - 项目说明文档

2. 核心应用文件

• ✅ app/main.py - FastAPI应用主入口
• ✅ app/config.py - 配置管理（Pydantic Settings）
• ✅ app/database.py - 数据库配置和会话管理

3. SQLAlchemy模型

• ✅ app/models/__init__.py - 模型模块导出
• ✅ app/models/base.py - 基础模型类（时间戳混入、通用方法）
• ✅ app/models/user.py - 用户相关模型（User, Role, Permission, 日志）
• ✅ app/models/streamer.py - 主播和MCN机构模型

4. Pydantic模式

• ✅ app/schemas/__init__.py - 模式模块导出
• ✅ app/schemas/user.py - 用户相关模式（登录、注册、响应）

5. API路由

• ✅ app/api/__init__.py - API模块导出
• ✅ app/api/v1/__init__.py - V1版本API路由聚合

6. 工具函数

• ✅ app/utils/__init__.py - 工具模块导出
• ✅ app/utils/helpers.py - 辅助函数（密码处理、JWT、验证等）

7. 其他目录

• ✅ app/api/v1/ - API路由目录
• ✅ app/services/ - 业务逻辑层（待创建）
• ✅ app/tests/ - 测试文件目录
• ✅ alembic/ - 数据库迁移目录
• ✅ scripts/ - 脚本文件目录
• ✅ static/ - 静态文件目录
• ✅ templates/ - 模板文件目录

需要继续创建的文件

1. API路由（优先级：高）

app/api/v1/
├── auth.py          # 认证相关API（登录、注册、token刷新）
├── user.py          # 用户管理API
├── streamer.py      # 主播管理API
├── risk.py          # 风险检测API
└── report.py        # 报告管理API

2. 业务服务层（优先级：高）

app/services/
├── auth_service.py  # 认证服务
├── user_service.py  # 用户服务
└── ...

3. 数据库模型（优先级：中）

app/models/
├── role.py          # 角色权限模型
├── audit.py         # 审计相关模型
├── risk.py          # 风险检测模型
└── report.py        # 报告模型

4. Pydantic模式（优先级：中）

app/schemas/
├── auth.py          # 认证相关模式
├── streamer.py      # 主播相关模式
├── risk.py          # 风险检测模式
└── report.py        # 报告模式

5. 工具和配置（优先级：低）

app/utils/
├── logger.py        # 日志配置
├── validators.py    # 数据验证器
└── cache.py         # 缓存工具

app/core/
├── celery_app.py    # Celery应用配置
└── security.py      # 安全相关配置

6. 数据库迁移（优先级：中）

alembic/
├── env.py           # 迁移环境配置
├── script.py.mako   # 迁移脚本模板
└── versions/        # 迁移版本文件
    └── 001_initial_migration.py

7. 初始化脚本（优先级：低）

scripts/
├── init_db.py       # 数据库初始化
├── create_admin.py  # 创建管理员用户
└── seed_data.py     # 初始化数据

技术栈总结

后端技术栈

• 语言: Python 3.11+
• Web框架: FastAPI 0.110+
• ORM: SQLAlchemy 2.x (异步支持)
• 数据库: PostgreSQL 15.x
• 异步驱动: asyncpg
• 数据验证: Pydantic 2.x
• 认证: JWT (python-jose)
• 密码加密: bcrypt (passlib)
• 任务队列: Celery 5.x
• 缓存: Redis 7.x
• 定时任务: APScheduler
• 数据处理: Pandas
• Excel处理: OpenPyXL
• PDF生成: ReportLab
• API文档: FastAPI自动生成 (Swagger + ReDoc)
• 日志: Loguru
• 依赖管理: Poetry
• 代码规范: Black + isort + mypy
• 测试: pytest + pytest-asyncio + httpx
• 容器化: Docker + Docker Compose

核心特性

1. 异步架构

• FastAPI原生支持异步
• SQLAlchemy 2.x异步支持
• asyncpg PostgreSQL异步驱动
• 高并发性能

2. 自动文档

• Swagger UI交互式文档
• ReDoc美观文档
• OpenAPI 3.0规范
• Pydantic自动生成模式文档

3. 类型安全

• Python类型提示
• Pydantic运行时类型检查
• mypy静态类型检查
• 完整的类型系统

4. 数据验证

• Pydantic数据模型验证
• 自定义验证器
• 嵌套对象验证
• 复杂类型验证

5. 安全认证

• JWT Token认证
• 密码bcrypt加密
• RBAC权限控制
• OAuth2.0密码流程

6. 缓存优化

• Redis缓存支持
• 缓存穿透保护
• 缓存雪崩防护
• 分布式缓存

7. 任务队列

• Celery异步任务
• 定时任务调度
• 结果后端
• 任务监控

8. 数据库优化

• SQLAlchemy ORM
• 数据库迁移（Alembic）
• 连接池管理
• 读写分离支持

9. 测试支持

• pytest测试框架
• 异步测试支持
• 覆盖率报告
• 模拟对象支持

10. 容器化

• Dockerfile多阶段构建
• Docker Compose编排
• 健康检查
• 环境隔离

下一步行动

1. 创建API路由文件

   • 认证相关API（auth.py）
   • 用户管理API（user.py）

2. 创建业务服务层

   • 认证服务（auth_service.py）
   • 用户服务（user_service.py）

3. 创建数据库迁移

   • 初始化迁移脚本
   • 创建所有数据表

4. 创建测试文件

   • 测试配置（conftest.py）
   • 单元测试

5. 创建工具文件

   • 日志配置（logger.py）
   • 安全配置（security.py）
   • Celery配置（celery_app.py）

6. 初始化数据

   • 创建管理员用户
   • 初始化基础数据

快速开始指南

开发环境

# 1. 安装依赖
poetry install

# 2. 配置环境变量
cp .env.example .env

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

# 4. 运行应用
poetry run uvicorn app.main:app --reload

Docker环境

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

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

# 停止服务
docker-compose down

文档链接

• FastAPI文档: https://fastapi.tiangolo.com/
• SQLAlchemy文档: https://docs.sqlalchemy.org/
• Pydantic文档: https://docs.pydantic.dev/
• Poetry文档: https://python-poetry.org/docs/
• Docker文档: https://docs.docker.com/