012-kaopeilian/backend

考培练系统后端（FastAPI）

简要说明：本项目为考培练系统的后端服务，基于 FastAPI 开发，配套前端为 Vue3。支持本地开发与测试，默认仅在 localhost 环境运行。

如何运行（How to Run）

1. 进入项目目录：

cd kaopeilian-backend

2. 可选：创建并激活虚拟环境（推荐）

python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

3. 安装依赖：

pip install -r requirements.txt

4. 运行主程序 main.py：

python app/main.py

可选运行方式（等价）：

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. 安装测试依赖（如未安装）：

pip install pytest

2. 仅运行 test_main.py：

pytest tests/test_main.py

（或运行全部测试）

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. 安装依赖

# 安装生产依赖
make install

# 或安装开发依赖（包含测试和代码检查工具）
make install-dev

3. 配置环境变量

复制环境变量示例文件并修改配置：

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. 数据库初始化

# 运行数据库迁移
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. 启动服务

# 开发模式（自动重载）
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

开发指南

代码规范

# 格式化代码
make format

# 运行代码检查
make lint

# 运行类型检查
make type-check

测试

# 运行测试
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部署

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

# 运行容器
docker run -d -p 8000:8000 --env-file .env kaopeilian-backend

Docker Compose部署

# 启动所有服务
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 许可证