# 考培练系统后端模块分工指南

## 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调用示例
   - 配置文件示例
   - 常见问题解答