# 考培练系统后端项目脚手架结构

## 完整的项目目录结构

```
kaopeilian-backend/
├── app/
│   ├── __init__.py
│   ├── main.py                    # FastAPI 应用入口
│   ├── config/                    # 统一配置管理
│   │   ├── __init__.py
│   │   ├── settings.py            # 系统配置
│   │   ├── database.py            # 数据库配置
│   │   ├── coze_config.py         # Coze平台配置
│   │   └── dify_config.py         # Dify平台配置
│   ├── core/                      # 核心公共模块
│   │   ├── __init__.py
│   │   ├── dependencies.py        # 依赖注入
│   │   ├── security.py            # 认证授权
│   │   ├── exceptions.py          # 统一异常处理
│   │   ├── middleware.py          # 中间件
│   │   └── logger.py              # 日志配置
│   ├── models/                    # 数据库模型（统一）
│   │   ├── __init__.py
│   │   ├── base.py                # 基础模型类
│   │   ├── user.py                # 用户相关模型
│   │   ├── course.py              # 课程相关模型
│   │   ├── exam.py                # 考试相关模型
│   │   ├── training.py            # 陪练相关模型
│   │   └── analytics.py           # 分析相关模型
│   ├── schemas/                   # Pydantic 模式（统一）
│   │   ├── __init__.py
│   │   ├── base.py                # 基础响应模式
│   │   ├── user.py                # 用户相关模式
│   │   ├── course.py              # 课程相关模式
│   │   ├── exam.py                # 考试相关模式
│   │   ├── training.py            # 陪练相关模式
│   │   └── analytics.py           # 分析相关模式
│   ├── services/                  # 业务逻辑服务层
│   │   ├── __init__.py
│   │   ├── base_service.py        # 基础服务类
│   │   ├── user_service.py        # 用户业务逻辑
│   │   ├── course_service.py      # 课程业务逻辑
│   │   ├── exam_service.py        # 考试业务逻辑
│   │   ├── training_service.py    # 陪练业务逻辑
│   │   ├── analytics_service.py   # 分析业务逻辑
│   │   ├── ai/                    # AI平台集成服务
│   │   │   ├── __init__.py
│   │   │   ├── base_ai_service.py # AI服务基类
│   │   │   ├── coze/              # Coze API 集成
│   │   │   │   ├── __init__.py
│   │   │   │   ├── client.py      # Coze客户端封装
│   │   │   │   ├── training.py    # AI陪练功能
│   │   │   │   └── chat.py        # 课程对话功能
│   │   │   └── dify/              # Dify API 集成
│   │   │       ├── __init__.py
│   │   │       ├── client.py      # Dify客户端封装
│   │   │       ├── exam.py        # 动态考试功能
│   │   │       ├── assessment.py  # 能力评估功能
│   │   │       └── recommend.py   # 课程推荐功能
│   │   └── external/              # 外部服务集成
│   │       ├── __init__.py
│   │       ├── sms_service.py     # 短信服务
│   │       └── badge_service.py   # 智能工牌API
│   └── api/                       # API 路由（按模块分离）
│       ├── __init__.py
│       ├── deps.py                # 路由依赖
│       └── v1/                    # API v1版本
│           ├── __init__.py
│           ├── auth.py            # 认证相关
│           ├── users.py           # 用户管理
│           ├── courses.py         # 课程管理
│           ├── exams.py           # 考试模块
│           ├── training.py        # 陪练模块
│           ├── analytics.py       # 数据分析
│           ├── admin.py           # 系统管理
│           └── websocket.py       # WebSocket支持
├── migrations/                    # 数据库迁移
│   └── alembic/                  
│       ├── alembic.ini
│       └── versions/
├── tests/                         # 测试代码
│   ├── __init__.py
│   ├── conftest.py               # 测试配置
│   ├── unit/                     # 单元测试
│   ├── integration/              # 集成测试
│   └── e2e/                      # 端到端测试
├── scripts/                      # 脚本工具
│   ├── init_db.py               # 初始化数据库
│   ├── seed_data.py             # 种子数据
│   └── generate_docs.py         # 生成文档
├── docs/                        # 项目文档
│   ├── api/                     # API文档
│   ├── development/             # 开发文档
│   └── deployment/              # 部署文档
├── requirements/                # 依赖管理
│   ├── base.txt                # 基础依赖
│   ├── dev.txt                 # 开发依赖
│   └── prod.txt                # 生产依赖
├── docker/                      # Docker相关
│   ├── Dockerfile
│   ├── Dockerfile.dev          # 开发环境
│   └── nginx/                  # Nginx配置
├── .env.example                # 环境变量示例
├── .gitignore
├── docker-compose.yml          # 本地开发
├── docker-compose.prod.yml     # 生产环境
├── Makefile                    # 快捷命令
├── README.md                   # 项目说明
└── pyproject.toml             # Python项目配置
```

## AI平台集成架构

### Coze平台集成（用于AI陪练和课程对话）
```python
# app/services/ai/coze/client.py
from cozepy import Coze, TokenAuth
from app.config.coze_config import settings

class CozeClient:
    """Coze平台客户端封装"""
    def __init__(self):
        self.client = Coze(
            auth=TokenAuth(settings.COZE_API_TOKEN),
            base_url=settings.COZE_API_BASE
        )
    
    async def create_conversation(self, bot_id: str):
        """创建会话"""
        pass
    
    async def stream_chat(self, bot_id: str, conversation_id: str, message: str):
        """流式对话"""
        pass
```

### Dify平台集成（用于动态考试和能力评估）
```python
# app/services/ai/dify/client.py
import httpx
from app.config.dify_config import settings

class DifyClient:
    """Dify平台客户端封装"""
    def __init__(self):
        self.base_url = settings.DIFY_API_BASE
        self.api_key = settings.DIFY_API_KEY
        self.client = httpx.AsyncClient(
            base_url=self.base_url,
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
    
    async def run_workflow(self, workflow_id: str, inputs: dict):
        """运行Dify工作流"""
        pass
    
    async def query_knowledge_base(self, kb_id: str, query: str):
        """查询知识库"""
        pass
```

## 配置文件示例

### Coze配置（app/config/coze_config.py）
```python
from pydantic import BaseSettings

class CozeSettings(BaseSettings):
    COZE_API_BASE: str = "https://api.coze.cn"
    COZE_WORKSPACE_ID: str
    COZE_API_TOKEN: str
    
    # Bot IDs
    COZE_TRAINING_BOT_ID: str  # AI陪练智能体
    COZE_CHAT_BOT_ID: str      # 课程对话智能体
    
    class Config:
        env_file = ".env"
```

### Dify配置（app/config/dify_config.py）
```python
from pydantic import BaseSettings

class DifySettings(BaseSettings):
    DIFY_API_BASE: str = "https://api.dify.ai/v1"
    DIFY_API_KEY: str
    
    # Workflow IDs
    DIFY_EXAM_WORKFLOW_ID: str        # 动态考试工作流
    DIFY_ASSESSMENT_WORKFLOW_ID: str  # 能力评估工作流
    DIFY_RECOMMEND_WORKFLOW_ID: str   # 课程推荐工作流
    
    class Config:
        env_file = ".env"
```

## 环境变量配置（.env.example）
```bash
# 基础配置
DEBUG=true
LOG_LEVEL=INFO
SECRET_KEY=your-secret-key

# 数据库配置
DATABASE_URL=mysql+aiomysql://user:password@localhost:3306/kaopeilian

# Coze平台配置
COZE_API_BASE=https://api.coze.cn
COZE_WORKSPACE_ID=7474971491470688296
COZE_API_TOKEN=pat_your_token_here
COZE_TRAINING_BOT_ID=7509379008556089379
COZE_CHAT_BOT_ID=7509380917472280617

# Dify平台配置
DIFY_API_BASE=https://api.dify.ai/v1
DIFY_API_KEY=app-your-api-key-here
DIFY_EXAM_WORKFLOW_ID=workflow_exam_id
DIFY_ASSESSMENT_WORKFLOW_ID=workflow_assessment_id
DIFY_RECOMMEND_WORKFLOW_ID=workflow_recommend_id

# Redis配置（用于缓存和会话）
REDIS_URL=redis://localhost:6379/0

# CORS配置
CORS_ORIGINS=["http://localhost:5173", "http://localhost:3000"]
```