feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
571
docs/规划/后端开发拆分策略/模块分工指南.md
Normal file
571
docs/规划/后端开发拆分策略/模块分工指南.md
Normal file
@@ -0,0 +1,571 @@
|
||||
# 考培练系统后端模块分工指南
|
||||
|
||||
## 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调用示例
|
||||
- 配置文件示例
|
||||
- 常见问题解答
|
||||
|
||||
Reference in New Issue
Block a user