998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
572 lines
17 KiB
Markdown
572 lines
17 KiB
Markdown
# 考培练系统后端模块分工指南
|
||
|
||
## 1. 模块划分总览
|
||
|
||
### 核心业务模块
|
||
| 模块名称 | Agent代号 | 负责范围 | 依赖模块 |
|
||
|---------|----------|---------|----------|
|
||
| 认证授权模块 | Agent-Auth | 登录、注册、权限管理、Token管理 | - |
|
||
| 用户管理模块 | Agent-User | 用户CRUD、个人信息、团队管理 | Auth |
|
||
| 课程管理模块 | Agent-Course | 课程CRUD、资料管理、成长路径 | Auth, User |
|
||
| 考试模块 | Agent-Exam | 动态考试、成绩管理、错题分析 | Auth, User, Dify |
|
||
| AI陪练模块 | Agent-Training | 陪练场景、实时对话、陪练记录 | Auth, User, Coze |
|
||
| 数据分析模块 | Agent-Analytics | 统计分析、数据可视化、报表生成 | Auth, User, Exam, Training |
|
||
| 系统管理模块 | Agent-Admin | 系统配置、日志管理、岗位管理 | Auth, User |
|
||
|
||
### AI集成模块
|
||
| 模块名称 | Agent代号 | 负责范围 | 对接平台 |
|
||
|---------|----------|---------|----------|
|
||
| Coze集成服务 | Agent-Coze | Coze API封装、会话管理、消息处理 | Coze平台 |
|
||
| Dify集成服务 | Agent-Dify | Dify工作流调用、知识库查询 | Dify平台 |
|
||
|
||
## 2. 详细模块说明
|
||
|
||
### 2.1 Agent-Auth（认证授权模块）
|
||
|
||
**负责人**: 子Agent-1
|
||
|
||
**主要职责**:
|
||
- 用户登录/登出
|
||
- 用户注册
|
||
- JWT Token生成与验证
|
||
- 权限检查中间件
|
||
- 密码重置功能
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── core/
|
||
│ ├── security.py # JWT处理、密码加密
|
||
│ └── dependencies.py # 认证依赖注入
|
||
├── models/
|
||
│ └── user.py # User模型（仅认证相关字段）
|
||
├── schemas/
|
||
│ └── auth.py # 认证相关的Pydantic模型
|
||
├── services/
|
||
│ └── auth_service.py # 认证业务逻辑
|
||
└── api/v1/
|
||
└── auth.py # 认证相关API路由
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
POST /api/v1/auth/login # 用户登录
|
||
POST /api/v1/auth/register # 用户注册
|
||
POST /api/v1/auth/logout # 用户登出
|
||
POST /api/v1/auth/refresh # 刷新Token
|
||
POST /api/v1/auth/reset-password # 重置密码
|
||
```
|
||
|
||
**与其他模块的接口**:
|
||
```python
|
||
# 提供给其他模块的依赖注入
|
||
from app.api.deps import get_current_user, require_admin
|
||
|
||
@router.get("/protected")
|
||
async def protected_route(current_user: User = Depends(get_current_user)):
|
||
return {"user": current_user}
|
||
```
|
||
|
||
### 2.2 Agent-User（用户管理模块）
|
||
|
||
**负责人**: 子Agent-2
|
||
|
||
**主要职责**:
|
||
- 用户信息CRUD
|
||
- 个人资料管理
|
||
- 团队/部门管理
|
||
- 用户角色分配
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── models/
|
||
│ ├── user.py # User模型（完整）
|
||
│ └── team.py # Team/Department模型
|
||
├── schemas/
|
||
│ ├── user.py # 用户相关Schema
|
||
│ └── team.py # 团队相关Schema
|
||
├── services/
|
||
│ ├── user_service.py # 用户业务逻辑
|
||
│ └── team_service.py # 团队业务逻辑
|
||
└── api/v1/
|
||
└── users.py # 用户管理API
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
GET /api/v1/users # 获取用户列表
|
||
GET /api/v1/users/{id} # 获取用户详情
|
||
PUT /api/v1/users/{id} # 更新用户信息
|
||
DELETE /api/v1/users/{id} # 删除用户
|
||
GET /api/v1/users/me # 获取当前用户信息
|
||
PUT /api/v1/users/me # 更新当前用户信息
|
||
|
||
GET /api/v1/teams # 获取团队列表
|
||
POST /api/v1/teams # 创建团队
|
||
PUT /api/v1/teams/{id} # 更新团队
|
||
POST /api/v1/teams/{id}/members # 添加团队成员
|
||
```
|
||
|
||
### 2.3 Agent-Course（课程管理模块）
|
||
|
||
**负责人**: 子Agent-3
|
||
|
||
**主要职责**:
|
||
- 课程CRUD操作
|
||
- 课程资料管理
|
||
- 知识点管理
|
||
- 成长路径配置
|
||
- 课程分配
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── models/
|
||
│ ├── course.py # Course模型
|
||
│ ├── material.py # 课程资料模型
|
||
│ └── growth_path.py # 成长路径模型
|
||
├── schemas/
|
||
│ ├── course.py # 课程相关Schema
|
||
│ └── growth_path.py # 成长路径Schema
|
||
├── services/
|
||
│ ├── course_service.py # 课程业务逻辑
|
||
│ └── growth_path_service.py # 成长路径逻辑
|
||
└── api/v1/
|
||
└── courses.py # 课程管理API
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
# 课程管理
|
||
GET /api/v1/courses # 获取课程列表
|
||
POST /api/v1/courses # 创建课程
|
||
GET /api/v1/courses/{id} # 获取课程详情
|
||
PUT /api/v1/courses/{id} # 更新课程
|
||
DELETE /api/v1/courses/{id} # 删除课程
|
||
|
||
# 课程资料
|
||
POST /api/v1/courses/{id}/materials # 上传资料
|
||
GET /api/v1/courses/{id}/materials # 获取资料列表
|
||
DELETE /api/v1/courses/{id}/materials/{material_id} # 删除资料
|
||
|
||
# 成长路径
|
||
GET /api/v1/growth-paths # 获取成长路径列表
|
||
POST /api/v1/growth-paths # 创建成长路径
|
||
PUT /api/v1/growth-paths/{id} # 更新成长路径
|
||
```
|
||
|
||
### 2.4 Agent-Exam（考试模块）
|
||
|
||
**负责人**: 子Agent-4
|
||
|
||
**主要职责**:
|
||
- 动态生成考题（调用Dify）
|
||
- 考试流程管理
|
||
- 成绩计算与存储
|
||
- 错题本管理
|
||
- 考试报告生成
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── models/
|
||
│ ├── exam.py # Exam模型
|
||
│ ├── question.py # Question模型
|
||
│ └── exam_record.py # 考试记录模型
|
||
├── schemas/
|
||
│ ├── exam.py # 考试相关Schema
|
||
│ └── question.py # 题目相关Schema
|
||
├── services/
|
||
│ ├── exam_service.py # 考试业务逻辑
|
||
│ └── question_service.py # 题目业务逻辑
|
||
└── api/v1/
|
||
└── exams.py # 考试相关API
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
# 考试管理
|
||
POST /api/v1/exams/start # 开始考试
|
||
POST /api/v1/exams/submit # 提交答案
|
||
GET /api/v1/exams/{id} # 获取考试详情
|
||
GET /api/v1/exams/records # 获取考试记录
|
||
|
||
# 成绩查询
|
||
GET /api/v1/scores # 获取成绩列表
|
||
GET /api/v1/scores/{id} # 获取成绩详情
|
||
GET /api/v1/scores/statistics # 成绩统计
|
||
|
||
# 错题管理
|
||
GET /api/v1/mistakes # 获取错题列表
|
||
POST /api/v1/mistakes/practice # 错题重练
|
||
```
|
||
|
||
### 2.5 Agent-Training（AI陪练模块）
|
||
|
||
**负责人**: 子Agent-5
|
||
|
||
**主要职责**:
|
||
- 陪练场景管理
|
||
- WebSocket实时对话
|
||
- 语音处理（TTS/ASR）
|
||
- 陪练记录管理
|
||
- 陪练报告生成
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── models/
|
||
│ ├── training_scene.py # 陪练场景模型
|
||
│ ├── training_record.py # 陪练记录模型
|
||
│ └── training_plan.py # 陪练计划模型
|
||
├── schemas/
|
||
│ ├── training.py # 陪练相关Schema
|
||
│ └── training_plan.py # 计划相关Schema
|
||
├── services/
|
||
│ ├── training_service.py # 陪练业务逻辑
|
||
│ └── training_plan_service.py # 计划业务逻辑
|
||
└── api/v1/
|
||
├── training.py # 陪练相关API
|
||
└── websocket.py # WebSocket处理
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
# 陪练场景管理
|
||
GET /api/v1/training-scenes # 获取场景列表
|
||
POST /api/v1/training-scenes # 创建场景
|
||
PUT /api/v1/training-scenes/{id} # 更新场景
|
||
|
||
# 陪练计划
|
||
GET /api/v1/training-plans # 获取计划列表
|
||
POST /api/v1/training-plans # 创建计划
|
||
POST /api/v1/training-plans/{id}/assign # 分配计划
|
||
|
||
# 陪练会话
|
||
WS /ws/v1/training/{scene_id} # WebSocket陪练
|
||
POST /api/v1/training/start # 开始陪练
|
||
POST /api/v1/training/end # 结束陪练
|
||
|
||
# 陪练记录
|
||
GET /api/v1/training-records # 获取记录列表
|
||
GET /api/v1/training-records/{id} # 获取记录详情
|
||
```
|
||
|
||
### 2.6 Agent-Analytics（数据分析模块）
|
||
|
||
**负责人**: 子Agent-6
|
||
|
||
**主要职责**:
|
||
- 学习数据统计
|
||
- 考试成绩分析
|
||
- 陪练效果分析
|
||
- 能力评估报告
|
||
- 数据可视化
|
||
|
||
**核心文件**:
|
||
```
|
||
app/
|
||
├── schemas/
|
||
│ └── analytics.py # 分析相关Schema
|
||
├── services/
|
||
│ ├── analytics_service.py # 分析业务逻辑
|
||
│ └── report_service.py # 报告生成逻辑
|
||
└── api/v1/
|
||
└── analytics.py # 分析相关API
|
||
```
|
||
|
||
**API接口**:
|
||
```
|
||
# 整体统计
|
||
GET /api/v1/analytics/overview # 总览数据
|
||
GET /api/v1/analytics/trends # 趋势分析
|
||
|
||
# 学员分析
|
||
GET /api/v1/analytics/users/{id}/ability # 能力雷达图
|
||
GET /api/v1/analytics/users/{id}/progress # 学习进度
|
||
GET /api/v1/analytics/users/{id}/report # 个人报告
|
||
|
||
# 团队分析
|
||
GET /api/v1/analytics/teams/{id}/overview # 团队概况
|
||
GET /api/v1/analytics/teams/{id}/ranking # 团队排名
|
||
```
|
||
|
||
### 2.7 Agent-Coze（Coze集成服务）
|
||
|
||
**负责人**: 子Agent-7
|
||
|
||
**主要职责**:
|
||
- Coze API客户端封装
|
||
- 会话管理
|
||
- 消息流处理
|
||
- 错误重试机制
|
||
- 响应数据转换
|
||
|
||
**核心文件**:
|
||
```
|
||
app/services/ai/coze/
|
||
├── __init__.py
|
||
├── client.py # Coze客户端
|
||
├── training.py # 陪练相关功能
|
||
├── chat.py # 对话相关功能
|
||
├── models.py # Coze数据模型
|
||
└── exceptions.py # Coze异常处理
|
||
```
|
||
|
||
**提供的服务接口**:
|
||
```python
|
||
class CozeService:
|
||
async def create_training_session(self, bot_id: str, user_id: int)
|
||
async def send_message(self, session_id: str, content: str)
|
||
async def stream_chat(self, session_id: str, content: str)
|
||
async def end_session(self, session_id: str)
|
||
async def get_evaluation_report(self, session_id: str)
|
||
```
|
||
|
||
**对外API（统一网关，供前端与第三方服务解耦）**:
|
||
```
|
||
# 课程对话（与课程对话页 /trainee/chat-course 使用）
|
||
POST /api/v1/course-chat/sessions # 创建课程对话会话（入参：course_id，可选：bot_id 覆盖）
|
||
POST /api/v1/course-chat/messages # 发送消息（入参：session_id, content, stream?bool）
|
||
WS /ws/v1/course-chat/{session_id} # 可选：流式对话通道（文本/事件流）
|
||
|
||
# 陪练语音会话（AI陪练会话页 /trainee/ai-practice 使用）
|
||
POST /api/v1/training/sessions # 创建陪练会话（入参：scene_id 或 bot_id，user_context 可选）
|
||
POST /api/v1/training/sessions/{id}/end # 结束陪练会话
|
||
WS /ws/v1/training/{session_id} # 语音/文本实时通话（沿用现有 coze-chat-backend 接口形式）
|
||
|
||
# 配置（统一环境变量）
|
||
# COZE_TRAINING_BOT_ID （陪练用Bot）
|
||
# COZE_CHAT_BOT_ID （课程对话用Bot）
|
||
```
|
||
|
||
> 说明：以上为网关层标准，内部由 `Agent-Coze` 适配既有 `coze-chat-backend` 能力（接口形同，仅切换 bot_id）。
|
||
|
||
### 2.8 Agent-Dify（Dify集成服务）
|
||
|
||
**负责人**: 子Agent-8
|
||
|
||
**主要职责**:
|
||
- Dify API客户端封装
|
||
- 工作流调用
|
||
- 知识库查询
|
||
- 能力评估
|
||
- 课程推荐
|
||
|
||
**核心文件**:
|
||
```
|
||
app/services/ai/dify/
|
||
├── __init__.py
|
||
├── client.py # Dify客户端
|
||
├── exam.py # 考试相关功能
|
||
├── assessment.py # 评估相关功能
|
||
├── recommend.py # 推荐相关功能
|
||
├── models.py # Dify数据模型
|
||
└── exceptions.py # Dify异常处理
|
||
```
|
||
|
||
**提供的服务接口**:
|
||
```python
|
||
class DifyService:
|
||
async def generate_exam_questions(self, course_id: int, count: int)
|
||
async def evaluate_ability(self, user_id: int, audio_data: bytes)
|
||
async def recommend_courses(self, user_id: int, weak_points: List[str])
|
||
async def query_knowledge_base(self, query: str)
|
||
```
|
||
|
||
**对外API（统一网关，供前端与第三方服务解耦）**:
|
||
```
|
||
# 动态考试（与 /exam/practice、/trainee/score-report 匹配）
|
||
POST /api/v1/exams/start # 启动动态考卷生成（入参：course_id, count，可选：difficulty/tags）
|
||
POST /api/v1/exams/submit # 提交答案
|
||
GET /api/v1/exams/{id} # 获取考试详情/题目
|
||
GET /api/v1/exams/records # 获取考试记录
|
||
|
||
# 知识拆解（课程资料上传后触发/手动重分析，供课程中心与知识点管理）
|
||
POST /api/v1/knowledge/decompose # 文档/媒体知识拆解（入参：course_id, file_url 或 material_id）
|
||
GET /api/v1/courses/{id}/knowledge-points # 获取课程知识点清单
|
||
|
||
# 能力评估与推荐（用于成长路径/个性化推荐）
|
||
POST /api/v1/assessment/ability # 上传音频或引用外部音频记录，返回能力弱项标签
|
||
POST /api/v1/recommend/courses # 根据弱项标签返回推荐课程
|
||
```
|
||
|
||
> 说明：网关层对接既有 `ExamsSystem` 与 `Dify` 工作流，保持前端稳定接口。
|
||
|
||
## 3. 模块间协作规则
|
||
|
||
### 3.1 依赖关系原则
|
||
1. **单向依赖**: 模块间只能单向依赖，避免循环依赖
|
||
2. **接口隔离**: 通过定义清晰的接口进行通信
|
||
3. **最小依赖**: 只依赖必要的模块，减少耦合
|
||
|
||
### 3.2 数据共享机制
|
||
```python
|
||
# app/core/context.py
|
||
from dataclasses import dataclass
|
||
from typing import Dict, Any
|
||
|
||
@dataclass
|
||
class SharedContext:
|
||
"""模块间共享的上下文信息"""
|
||
user_info: Dict[str, Any]
|
||
request_id: str
|
||
trace_id: str
|
||
|
||
# 在请求中传递上下文
|
||
async def some_api_handler(
|
||
request: Request,
|
||
current_user: User = Depends(get_current_user)
|
||
):
|
||
context = SharedContext(
|
||
user_info={"id": current_user.id, "role": current_user.role},
|
||
request_id=request.state.request_id,
|
||
trace_id=request.state.trace_id
|
||
)
|
||
# 传递给服务层
|
||
result = await service.process(context, data)
|
||
```
|
||
|
||
### 3.3 事件通知机制
|
||
```python
|
||
# app/core/events.py
|
||
from enum import Enum
|
||
from typing import Any, Dict
|
||
|
||
class EventType(Enum):
|
||
USER_CREATED = "user.created"
|
||
COURSE_COMPLETED = "course.completed"
|
||
EXAM_FINISHED = "exam.finished"
|
||
TRAINING_COMPLETED = "training.completed"
|
||
|
||
class EventBus:
|
||
"""简单的事件总线实现"""
|
||
def __init__(self):
|
||
self._handlers = {}
|
||
|
||
def subscribe(self, event_type: EventType, handler):
|
||
if event_type not in self._handlers:
|
||
self._handlers[event_type] = []
|
||
self._handlers[event_type].append(handler)
|
||
|
||
async def publish(self, event_type: EventType, data: Dict[str, Any]):
|
||
if event_type in self._handlers:
|
||
for handler in self._handlers[event_type]:
|
||
await handler(data)
|
||
|
||
# 使用示例
|
||
event_bus = EventBus()
|
||
|
||
# 在用户模块中发布事件
|
||
await event_bus.publish(EventType.USER_CREATED, {"user_id": user.id})
|
||
|
||
# 在分析模块中订阅事件
|
||
async def handle_user_created(data: Dict[str, Any]):
|
||
user_id = data["user_id"]
|
||
# 初始化用户的分析数据
|
||
await analytics_service.init_user_analytics(user_id)
|
||
|
||
event_bus.subscribe(EventType.USER_CREATED, handle_user_created)
|
||
```
|
||
|
||
## 4. 开发时序安排
|
||
|
||
### 第一批次（基础模块）
|
||
1. **Agent-Auth**: 最先开发，其他模块都依赖认证
|
||
2. **Agent-User**: 紧随其后，提供用户基础数据
|
||
|
||
### 第二批次（AI集成）
|
||
3. **Agent-Coze**: 为陪练模块提供支持
|
||
4. **Agent-Dify**: 为考试模块提供支持
|
||
|
||
### 第三批次（业务模块）
|
||
5. **Agent-Course**: 课程管理功能
|
||
6. **Agent-Exam**: 考试功能（依赖Dify）
|
||
7. **Agent-Training**: 陪练功能（依赖Coze）
|
||
|
||
### 第四批次（高级功能）
|
||
8. **Agent-Analytics**: 数据分析（依赖其他业务模块的数据）
|
||
9. **Agent-Admin**: 系统管理功能
|
||
|
||
## 5. 接口文档规范
|
||
|
||
每个模块必须提供完整的接口文档，格式如下：
|
||
|
||
```yaml
|
||
# api_docs/auth.yaml
|
||
openapi: 3.0.0
|
||
info:
|
||
title: 认证授权模块API
|
||
version: 1.0.0
|
||
|
||
paths:
|
||
/api/v1/auth/login:
|
||
post:
|
||
summary: 用户登录
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
username:
|
||
type: string
|
||
description: 用户名或邮箱
|
||
password:
|
||
type: string
|
||
description: 密码
|
||
required:
|
||
- username
|
||
- password
|
||
responses:
|
||
200:
|
||
description: 登录成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type: integer
|
||
example: 200
|
||
message:
|
||
type: string
|
||
example: success
|
||
data:
|
||
type: object
|
||
properties:
|
||
access_token:
|
||
type: string
|
||
refresh_token:
|
||
type: string
|
||
user:
|
||
$ref: '#/components/schemas/User'
|
||
```
|
||
|
||
## 6. 模块交付标准
|
||
|
||
每个模块完成时必须包含：
|
||
|
||
1. **源代码**
|
||
- 符合编码规范
|
||
- 包含完整的类型注解
|
||
- 有充分的注释
|
||
|
||
2. **测试代码**
|
||
- 单元测试覆盖率 > 80%
|
||
- 包含集成测试用例
|
||
- 测试数据准备脚本
|
||
|
||
3. **文档**
|
||
- API接口文档（OpenAPI格式）
|
||
- 模块设计文档
|
||
- 部署配置说明
|
||
|
||
4. **示例**
|
||
- API调用示例
|
||
- 配置文件示例
|
||
- 常见问题解答
|
||
|