998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
411 lines
12 KiB
Markdown
411 lines
12 KiB
Markdown
## 考培练系统后端（FastAPI）
|
||
|
||
简要说明：本项目为考培练系统的后端服务，基于 FastAPI 开发，配套前端为 Vue3。支持本地开发与测试，默认仅在 localhost 环境运行。
|
||
|
||
### 如何运行（How to Run）
|
||
|
||
1. 进入项目目录：
|
||
```bash
|
||
cd kaopeilian-backend
|
||
```
|
||
|
||
2. 可选：创建并激活虚拟环境（推荐）
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
```
|
||
|
||
3. 安装依赖：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
4. 运行主程序 `main.py`：
|
||
```bash
|
||
python app/main.py
|
||
```
|
||
|
||
可选运行方式（等价）：
|
||
```bash
|
||
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
|
||
```
|
||
|
||
启动后访问接口文档：
|
||
```
|
||
http://localhost:8000/docs
|
||
```
|
||
|
||
> 提示：如需设置数据库连接，请使用本地开发 DSN：`mysql+aiomysql://root:root@localhost:3306/kaopeilian?charset=utf8mb4`，可在 `local_config.py` 或环境变量 `DATABASE_URL` 中覆盖。
|
||
|
||
### 如何测试（How to Test）
|
||
|
||
1. 安装测试依赖（如未安装）：
|
||
```bash
|
||
pip install pytest
|
||
```
|
||
|
||
2. 仅运行 `test_main.py`：
|
||
```bash
|
||
pytest tests/test_main.py
|
||
```
|
||
|
||
（或运行全部测试）
|
||
```bash
|
||
pytest
|
||
```
|
||
|
||
# 考培练系统后端
|
||
|
||
## 项目概述
|
||
|
||
考培练系统是一个革命性的员工能力提升平台，通过集成Coze和Dify双AI平台，实现智能化的培训、考核和陪练功能。
|
||
|
||
## 系统账户
|
||
|
||
系统预置了以下测试账户：
|
||
|
||
| 角色 | 用户名 | 密码 | 权限说明 |
|
||
| ---------- | ---------- | -------------- | ---------------------------- |
|
||
| 超级管理员 | superadmin | Superadmin123! | 系统最高权限，可管理所有功能 |
|
||
| 系统管理员 | admin | Admin123! | 可管理除“系统管理”模块外的全部功能（管理员仪表盘、用户管理、岗位管理、系统日志） |
|
||
| 测试学员 | testuser | TestPass123! | 可学习课程、参加考试和训练 |
|
||
|
||
**注意**：
|
||
|
||
- 这些账户支持两种密码加密方式（bcrypt 和 SHA256）
|
||
- 使用 `create_system_accounts.py` 创建 bcrypt 加密的账户（推荐用于生产环境）
|
||
- 使用 `create_simple_users.py` 创建 SHA256 加密的账户（用于 simple_main.py）
|
||
|
||
## 技术栈
|
||
|
||
- **后端框架**: Python 3.8+ + FastAPI
|
||
- **数据库**: MySQL 8.0 + Redis
|
||
- **ORM**: SQLAlchemy 2.0
|
||
- **AI平台**: Coze（陪练和对话） + Dify（考试和评估）
|
||
- **认证**: JWT
|
||
- **文档转换**: LibreOffice（用于Office文档在线预览）
|
||
- **部署**: Docker
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
kaopeilian-backend/
|
||
├── app/ # 应用主目录
|
||
│ ├── api/ # API路由
|
||
│ │ └── v1/ # API v1版本
|
||
│ │ ├── training.py # 陪练模块API
|
||
│ │ └── ... # 其他模块API
|
||
│ ├── config/ # 配置管理
|
||
│ │ ├── settings.py # 系统配置
|
||
│ │ └── database.py # 数据库配置
|
||
│ ├── core/ # 核心功能
|
||
│ │ ├── deps.py # 依赖注入
|
||
│ │ ├── exceptions.py # 异常定义
|
||
│ │ └── ...
|
||
│ ├── models/ # 数据库模型
|
||
│ │ ├── base.py # 基础模型
|
||
│ │ ├── training.py # 陪练模型
|
||
│ │ └── ...
|
||
│ ├── schemas/ # Pydantic模式
|
||
│ │ ├── base.py # 基础模式
|
||
│ │ ├── training.py # 陪练模式
|
||
│ │ └── ...
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── base_service.py # 基础服务类
|
||
│ │ ├── training_service.py # 陪练服务
|
||
│ │ └── ai/ # AI平台集成
|
||
│ │ ├── coze/ # Coze集成
|
||
│ │ └── dify/ # Dify集成
|
||
│ └── main.py # 应用入口
|
||
├── tests/ # 测试目录
|
||
├── migrations/ # 数据库迁移
|
||
├── requirements.txt # 生产依赖
|
||
├── requirements-dev.txt # 开发依赖
|
||
├── Makefile # 开发命令
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
- Python 3.8+
|
||
- MySQL 8.0
|
||
- Redis
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
# 安装生产依赖
|
||
make install
|
||
|
||
# 或安装开发依赖（包含测试和代码检查工具）
|
||
make install-dev
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
复制环境变量示例文件并修改配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
主要配置项：
|
||
|
||
- 数据库连接：`DATABASE_URL`
|
||
- Redis连接：`REDIS_URL`
|
||
- JWT密钥：`SECRET_KEY`
|
||
- Coze配置：`COZE_API_TOKEN`, `COZE_TRAINING_BOT_ID`
|
||
- Dify配置：`DIFY_API_KEY`
|
||
|
||
### 4. 数据库初始化
|
||
|
||
```bash
|
||
# 运行数据库迁移
|
||
make migrate
|
||
# 数据库结构说明更新
|
||
|
||
- 统一主键：根据当前 ORM 定义，所有表主键均为 `INT AUTO_INCREMENT`。
|
||
- 用户相关引用：`teams.leader_id`、`exams.user_id`、`user_teams.user_id` 统一为 `INT`。
|
||
- 陪练模块：
|
||
- `training_scenes.status` 使用枚举 `DRAFT/ACTIVE/INACTIVE`；
|
||
- `training_sessions.status` 使用枚举 `CREATED/IN_PROGRESS/COMPLETED/CANCELLED/ERROR`；
|
||
- `training_messages.role` 使用 `USER/ASSISTANT/SYSTEM`；`type` 使用 `TEXT/VOICE/SYSTEM`；
|
||
- `training_sessions.user_id` 和 `training_reports.user_id` 为 `INT`（取消 `training_sessions.user_id` 外键）；
|
||
- `training_reports.session_id` 对 `training_sessions.id` 唯一外键保持不变。
|
||
|
||
如需全量初始化，请使用 `scripts/init_database_unified.sql`。
|
||
```
|
||
|
||
### 5. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（自动重载）
|
||
make run
|
||
|
||
# 或直接运行
|
||
python -m app.main
|
||
```
|
||
|
||
服务将在 http://localhost:8000 启动
|
||
|
||
## 数据库连接信息
|
||
|
||
- 公网数据库（当前使用）
|
||
- Host: `120.79.247.16` 或 `aiedu.ireborn.com.cn`
|
||
- Port: `3306`
|
||
- User: `root`
|
||
- Password: `Kaopeilian2025!@#`
|
||
- Database: `kaopeilian`
|
||
- DSN (Python SQLAlchemy): `mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4`
|
||
|
||
- 本地数据库（备用）
|
||
- Host: `127.0.0.1`
|
||
- Port: `3306`
|
||
- User: `root`
|
||
- Password: `root`
|
||
- Database: `kaopeilian`
|
||
- DSN (Python SQLAlchemy): `mysql+aiomysql://root:root@localhost:3306/kaopeilian?charset=utf8mb4`
|
||
|
||
- 配置写入位置
|
||
- 代码内用于本地开发覆盖：`local_config.py` 中的 `os.environ["DATABASE_URL"]`
|
||
- Docker 开发环境：`docker-compose.dev.yml` 中 `backend.environment.DATABASE_URL`
|
||
- 运行时环境变量文件：`.env`（如存在，将被容器挂载）
|
||
|
||
> 提示：开发测试环境仅用于本机 `localhost` 访问，已开启代码自动重载。
|
||
|
||
## 文件管理
|
||
|
||
### 文件存储结构
|
||
- **基础路径**: `/kaopeilian-backend/uploads/`
|
||
- **课程资料**: `uploads/courses/{course_id}/{filename}`
|
||
- **文件命名规则**: `{时间戳}_{8位哈希}.{扩展名}`
|
||
- 示例: `20250922213126_e21775bc.pdf`
|
||
|
||
### 文件上传
|
||
- **上传接口**:
|
||
- 通用上传: `POST /api/v1/upload/file`
|
||
- 课程资料上传: `POST /api/v1/upload/course/{course_id}/materials`
|
||
- **支持格式**: pdf、doc、docx、ppt、pptx、xls、xlsx、txt、md、zip、mp4、mp3、png、jpg、jpeg
|
||
- **大小限制**: 50MB
|
||
- **静态访问路径**: `http://localhost:8000/static/uploads/{相对路径}`
|
||
|
||
### 文件删除策略
|
||
1. **删除资料时**：
|
||
- 软删除数据库记录（标记 `is_deleted=true`）
|
||
- 同步删除物理文件
|
||
- 文件删除失败仅记录日志，不影响业务流程
|
||
|
||
2. **删除课程时**：
|
||
- 软删除课程记录
|
||
- 删除整个课程文件夹 (`uploads/courses/{course_id}/`)
|
||
- 使用 `shutil.rmtree` 递归删除
|
||
- 文件夹删除失败仅记录日志，不影响业务流程
|
||
|
||
### 相关配置
|
||
- **上传路径配置**: `app/core/config.py` 中的 `UPLOAD_PATH` 属性
|
||
- **静态文件服务**: `app/main.py` 中使用 `StaticFiles` 挂载
|
||
- **文件上传模块**: `app/api/v1/upload.py`
|
||
|
||
### 文档预览功能
|
||
|
||
#### 支持的文件格式
|
||
- **直接预览**: PDF、TXT、Markdown (md, mdx)、HTML、CSV、VTT、Properties
|
||
- **转换预览**: Word (doc, docx)、Excel (xls, xlsx) - 通过LibreOffice转换为PDF后预览
|
||
|
||
#### 系统依赖
|
||
- **LibreOffice**: 用于Office文档转换
|
||
- libreoffice-writer: Word文档支持
|
||
- libreoffice-calc: Excel文档支持
|
||
- libreoffice-impress: PowerPoint文档支持（未启用）
|
||
- libreoffice-core: 核心组件
|
||
- **中文字体**: 支持中文文档预览
|
||
- fonts-wqy-zenhei: 文泉驿正黑
|
||
- fonts-wqy-microhei: 文泉驿微米黑
|
||
|
||
#### 预览API
|
||
- 获取预览信息: `GET /api/v1/preview/material/{material_id}`
|
||
- 检查转换服务: `GET /api/v1/preview/check-converter`
|
||
|
||
#### 转换缓存机制
|
||
- 转换后的PDF存储在: `uploads/converted/{course_id}/{material_id}.pdf`
|
||
- 仅在源文件更新时重新转换
|
||
- 转换失败时自动降级为下载模式
|
||
|
||
## API文档
|
||
|
||
启动服务后，可以访问：
|
||
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
|
||
## 开发指南
|
||
|
||
### 代码规范
|
||
|
||
```bash
|
||
# 格式化代码
|
||
make format
|
||
|
||
# 运行代码检查
|
||
make lint
|
||
|
||
# 运行类型检查
|
||
make type-check
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行测试
|
||
make test
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
make test-cov
|
||
```
|
||
|
||
### 模块开发流程
|
||
|
||
1. 在 `app/models/` 创建数据模型
|
||
2. 在 `app/schemas/` 创建Pydantic模式
|
||
3. 在 `app/services/` 实现业务逻辑
|
||
4. 在 `app/api/v1/` 创建API路由
|
||
5. 编写测试用例
|
||
6. 更新API契约文档
|
||
|
||
## 已实现功能
|
||
|
||
### 陪练模块 (Training)
|
||
|
||
- **场景管理**
|
||
|
||
- 获取场景列表（支持分类、状态筛选）
|
||
- 创建/更新/删除场景（管理员权限）
|
||
- 获取场景详情
|
||
- **会话管理**
|
||
|
||
- 开始陪练会话
|
||
- 结束陪练会话
|
||
- 获取会话列表
|
||
- 获取会话详情
|
||
- **消息管理**
|
||
|
||
- 获取会话消息列表
|
||
- 支持文本/语音消息
|
||
- **报告管理**
|
||
|
||
- 生成陪练报告
|
||
- 获取报告列表
|
||
- 获取报告详情
|
||
|
||
## 待实现功能
|
||
|
||
- [ ] 用户认证模块 (Auth)
|
||
- [ ] 用户管理模块 (User)
|
||
- [ ] 课程管理模块 (Course)
|
||
- [ ] 考试模块 (Exam)
|
||
- [ ] 数据分析模块 (Analytics)
|
||
- [ ] 系统管理模块 (Admin)
|
||
- [ ] Coze网关模块
|
||
- [ ] WebSocket实时通信
|
||
|
||
## 部署
|
||
## 常见问题与排错
|
||
|
||
### 1. 登录失败相关
|
||
|
||
- 报错 Unknown column 'users.is_deleted'：请更新数据库，确保 `users` 表包含 `is_deleted` 与 `deleted_at` 字段（参见 `scripts/init_database_unified.sql` 或执行迁移）。
|
||
- 默认账户无法登录：重置默认账户密码哈希或运行 `create_system_accounts.py`。默认账户见上方“系统账户”。
|
||
|
||
### 2. 依赖冲突（httpx 与 cozepy）
|
||
|
||
- `cozepy==0.2.0` 依赖 `httpx<0.25.0`，请将 `requirements.txt` 中 `httpx` 固定为 `0.24.1`，并避免在 `requirements-dev.txt` 再次指定其他版本。
|
||
|
||
### 3. Docker 拉取镜像超时
|
||
|
||
- 可先本地直接运行后端（确保本机 MySQL/Redis 就绪），调通后再处理 Docker 网络问题。
|
||
|
||
|
||
### Docker部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t kaopeilian-backend .
|
||
|
||
# 运行容器
|
||
docker run -d -p 8000:8000 --env-file .env kaopeilian-backend
|
||
```
|
||
|
||
### Docker Compose部署
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
```
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交代码 (`git commit -m 'feat: Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 创建Pull Request
|
||
|
||
### 提交规范
|
||
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式调整
|
||
- `refactor`: 代码重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建过程或辅助工具的变动
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证
|