012-kaopeilian/docs/规划/后端开发拆分策略/模块分工指南.md

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

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  # 重置密码

与其他模块的接口:

# 提供给其他模块的依赖注入
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异常处理

提供的服务接口:

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异常处理

提供的服务接口:

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 数据共享机制

# 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 事件通知机制

# 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. 接口文档规范

每个模块必须提供完整的接口文档，格式如下：

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