261 lines
6.3 KiB
Markdown
261 lines
6.3 KiB
Markdown
# 项目代码结构说明
|
||
|
||
## 已创建的文件
|
||
|
||
### 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路由（优先级：高）
|
||
```bash
|
||
app/api/v1/
|
||
├── auth.py # 认证相关API（登录、注册、token刷新）
|
||
├── user.py # 用户管理API
|
||
├── streamer.py # 主播管理API
|
||
├── risk.py # 风险检测API
|
||
└── report.py # 报告管理API
|
||
```
|
||
|
||
### 2. 业务服务层（优先级：高）
|
||
```bash
|
||
app/services/
|
||
├── auth_service.py # 认证服务
|
||
├── user_service.py # 用户服务
|
||
└── ...
|
||
```
|
||
|
||
### 3. 数据库模型（优先级：中）
|
||
```bash
|
||
app/models/
|
||
├── role.py # 角色权限模型
|
||
├── audit.py # 审计相关模型
|
||
├── risk.py # 风险检测模型
|
||
└── report.py # 报告模型
|
||
```
|
||
|
||
### 4. Pydantic模式（优先级：中）
|
||
```bash
|
||
app/schemas/
|
||
├── auth.py # 认证相关模式
|
||
├── streamer.py # 主播相关模式
|
||
├── risk.py # 风险检测模式
|
||
└── report.py # 报告模式
|
||
```
|
||
|
||
### 5. 工具和配置（优先级：低）
|
||
```bash
|
||
app/utils/
|
||
├── logger.py # 日志配置
|
||
├── validators.py # 数据验证器
|
||
└── cache.py # 缓存工具
|
||
|
||
app/core/
|
||
├── celery_app.py # Celery应用配置
|
||
└── security.py # 安全相关配置
|
||
```
|
||
|
||
### 6. 数据库迁移（优先级：中）
|
||
```bash
|
||
alembic/
|
||
├── env.py # 迁移环境配置
|
||
├── script.py.mako # 迁移脚本模板
|
||
└── versions/ # 迁移版本文件
|
||
└── 001_initial_migration.py
|
||
```
|
||
|
||
### 7. 初始化脚本（优先级：低）
|
||
```bash
|
||
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. **初始化数据**
|
||
- 创建管理员用户
|
||
- 初始化基础数据
|
||
|
||
## 快速开始指南
|
||
|
||
### 开发环境
|
||
```bash
|
||
# 1. 安装依赖
|
||
poetry install
|
||
|
||
# 2. 配置环境变量
|
||
cp .env.example .env
|
||
|
||
# 3. 初始化数据库
|
||
poetry run alembic upgrade head
|
||
|
||
# 4. 运行应用
|
||
poetry run uvicorn app.main:app --reload
|
||
```
|
||
|
||
### Docker环境
|
||
```bash
|
||
# 构建并启动所有服务
|
||
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/
|