# 陪练功能基础信息

## 一、功能概述

### 业务场景
考培练系统为轻医美连锁品牌提供AI陪练功能，通过模拟真实客户场景，让学员进行实战对话练习。

### 两种陪练入口

#### 1. 陪练中心（直接模式）
- **URL**: http://localhost:3001/trainee/ai-practice-center
- **流程**: 选择预设场景 → 直接调用Coze开始陪练
- **场景来源**: 数据库中的预设场景（practice_scenes表）

#### 2. 课程中心（课程模式）
- **URL**: http://localhost:3001/trainee/course-center
- **流程**: 点击课程陪练 → Dify提取场景 → Coze开始陪练
- **场景来源**: Dify根据课程内容动态生成

## 二、Coze配置信息

### 认证方式（更新于 2025-11-16）
系统使用 **OAuth认证（JWT + 私钥签名）**，不再使用Personal Access Token (PAT)。

### OAuth配置（后端环境变量）
```bash
# OAuth认证配置
COZE_OAUTH_CLIENT_ID=1114009328887
COZE_OAUTH_PUBLIC_KEY_ID=GGs9pw0BDHx2k9vGGehUyRgKV-PyUWLBncDs-YNNN_I
COZE_OAUTH_PRIVATE_KEY_PATH=/app/secrets/coze_private_key.pem
COZE_PRACTICE_BOT_ID=7560643598174683145

# API配置（关键：必须使用中国区）
COZE_API_BASE=https://api.coze.cn
```

### 私钥文件位置
- **宿主机**: `/root/aiedu/kaopeilian-backend/secrets/coze_private_key.pem`
- **容器内**: `/app/secrets/coze_private_key.pem`
- **权限**: 600（仅所有者可读写）
- **Docker挂载**: `./kaopeilian-backend/secrets:/app/secrets:ro`（只读）

### 重要提示
⚠️ **JWTAuth必须指定 `base_url='https://api.coze.cn'`，否则会使用国际版导致认证失败**

### 官方资源
- **API文档**: https://www.coze.cn/open/docs/developer_guides/chat_v3
- **OAuth文档**: https://www.coze.cn/open/docs/developer_guides/oauth
- **Python SDK**: https://github.com/coze-dev/coze-py
- **SDK版本**: cozepy>=0.19.0

### Bot信息
- **Bot ID**: 7560643598174683145
- **应用ID**: 1114009328887
- **功能**: AI模拟客户陪练，支持多轮对话
- **特性**: 实时流式响应，可自定义场景角色

## 三、Dify配置信息

### API配置
```python
DIFY_API_BASE = "http://dify.ireborn.com.cn/v1"
DIFY_PRACTICE_API_KEY = "app-rYP6LNM4iPmNjIHns12zFeJp"
DIFY_PRACTICE_WORKFLOW_ID = "待确认"  # 需要从Dify创建工作流后获取
```

### 调用示例
```bash
curl -X POST 'http://dify.ireborn.com.cn/v1/workflows/run' \
--header 'Authorization: Bearer app-rYP6LNM4iPmNjIHns12zFeJp' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {
    "course_id": "5"
  },
  "response_mode": "streaming",
  "user": "kaopeilian"
}'
```

### 工作流说明
- **输入参数**: course_id（课程ID）
- **响应模式**: streaming（流式返回）
- **输出格式**: JSON场景数据（包含name、description、background、ai_role、objectives等）

## 四、技术架构

### 核心技术栈
- **前端**: Vue3 + Element Plus
- **后端**: Python + FastAPI
- **数据库**: MySQL 8.0（存储场景数据）
- **AI对话**: Coze Bot（字节跳动）
- **场景提取**: Dify工作流
- **通信协议**: SSE (Server-Sent Events)

### 数据存储策略
- **场景数据**: 存储在MySQL的practice_scenes表
- **对话历史**: 由Coze平台管理，不存储在本地数据库

## 五、规划文档

### 已完成文档
1. ✅ **Coze-API文档.md** - Coze API核心使用方法
2. ✅ **陪练功能技术方案.md** - 完整技术架构和实现方案
3. ✅ **陪练功能API接口规范.md** - 前后端API接口详细规范
4. ✅ **陪练功能数据流程图.md** - 数据流程和时序图
5. ✅ **规范与约定-团队基线.md** - 更新了陪练功能相关规范

### 文档位置
所有规划文档位于：`考培练系统规划/全链路联调/Ai工作流/coze/`

## 六、参考代码

### 可用参考代码位置
- **Coze Python SDK**: `参考代码/coze-py-main/`
  - 示例代码：`examples/chat_stream.py`（流式对话）
  - 示例代码：`examples/chat_simple_audio.py`（音频对话）
  
- **Coze后端参考**: `参考代码/coze-chat-backend/`
  - `main.py` - FastAPI集成示例
  - `auth.py` - Coze认证方式
  - `config.py` - 配置管理
  
- **Coze前端参考**: `参考代码/coze-chat-frontend/`
  - React + TypeScript实现
  - SSE流式对话处理示例

### 已有页面
- **陪练中心页面**: `kaopeilian-frontend/src/views/trainee/ai-practice-center.vue`（前端已实现）
- **场景管理页面**: `kaopeilian-frontend/src/views/manager/practice-scene-management.vue`（前端已实现）
- **对话页面**: 待开发（可参考Training模块）

### 核心参考代码（新发现）
- **Training模块**: `参考代码/coze-chat-frontend/src/pages/Training/`
  - `index.tsx` - 主入口（20行）
  - `TextChat.tsx` - 文本对话实现（68行）
  - `VoiceChat.tsx` - 语音对话实现（225行）
  - **`TrainingStore.ts` - 核心状态管理（525行）** ⭐ 重点参考
  
**TrainingStore.ts核心功能**：
- ✅ SSE流式对话处理（使用@ant-design/x的XStream）
- ✅ WebSocket语音对话（使用@coze/api/ws-tools）
- ✅ 消息列表管理（增量更新、删除、重新生成）
- ✅ 对话状态管理（6种状态：未连接、连接中、已连接、聆听、回复中、错误）
- ✅ 文件上传支持
- ✅ 错误处理和重试
- ✅ AbortController中断控制

## 七、开发路线图

### 第一阶段：数据库与基础API（2天）
- [ ] 创建practice_scenes表
- [ ] 插入初始场景数据
- [ ] 实现场景管理API（CRUD）

### 第二阶段：前端管理页面（2天）
- [ ] 场景管理页面开发
- [ ] 表单验证与提交
- [ ] 列表筛选与分页

### 第三阶段：Coze集成（3天）
- [ ] Coze SDK集成
- [ ] 流式对话API实现
- [ ] 陪练对话页面开发

### 第四阶段：Dify集成（2天）
- [ ] Dify场景提取API
- [ ] 课程中心集成

### 第五阶段：联调与优化（2天）
- [ ] 端到端测试
- [ ] 错误处理完善
- [ ] 性能优化

**预计总工期**: 11个工作日

## 八、关键技术点

### ⚠️ 场景提示词构建（核心差异）

**与参考代码的关键不同**：
- **参考代码**：用户直接与Bot对话，无场景概念
- **考培练系统**：首次消息必须包含完整场景设定

**实现方式**：
```python
# 后端：首次消息时构建场景提示词
if is_first:
    scene_prompt = f"""
# 陪练场景设定

## 场景名称
{scene_name}

## 场景背景
{scene_background}

## AI角色要求
{scene_ai_role}

## 练习目标
{chr(10).join(f"{i+1}. {obj}" for i, obj in enumerate(scene_objectives))}

---

现在开始陪练对话。请严格按照上述设定扮演角色。

学员的第一句话：{user_message}
"""
    # 发送完整提示词给Coze
    Message.build_user_question_text(scene_prompt)
else:
    # 后续消息仅发送用户输入
    Message.build_user_question_text(user_message)
```

**为什么这样设计**：
1. 让AI明确理解要扮演的角色
2. 保持对话上下文（使用conversation_id）
3. 后续消息无需重复场景信息
4. 用户界面不显示场景设定文本

### SSE流式通信
```javascript
// 前端处理SSE事件
const response = await fetch('/api/v1/practice/start', {
  method: 'POST',
  body: JSON.stringify({
    scene_name: scene.name,
    scene_background: scene.background,
    scene_ai_role: scene.ai_role,
    scene_objectives: scene.objectives,
    user_message: userInput,
    is_first: true  // 标记首次消息
  })
})

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { value, done } = await reader.read()
  if (done) break
  
  const chunk = decoder.decode(value)
  // 解析 event: xxx\ndata: {...}\n\n 格式
}
```

### Coze流式对话
```python
# 后端调用Coze
from cozepy import Coze, TokenAuth, Message, ChatEventType

stream = coze.chat.stream(
    bot_id=COZE_PRACTICE_BOT_ID,
    user_id=user_id,
    additional_messages=[Message.build_user_question_text(message)],
    conversation_id=conversation_id  # 保持对话上下文
)

for event in stream:
    if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
        # 发送SSE增量事件
        yield f"event: message.delta\ndata: {json.dumps({'content': event.message.content})}\n\n"
```

## 九、注意事项

### 安全性
- Token不要提交到版本控制
- 使用环境变量管理敏感配置
- API调用添加速率限制

### 性能
- SSE连接超时设置为180秒
- 数据库查询使用索引
- 前端消息列表使用虚拟滚动

### 用户体验
- 实现打字效果（message.delta）

如有技术问题，请参考：
1. Coze API文档：`Coze-API文档.md`
2. 技术方案文档：`陪练功能技术方案.md`
3. API接口规范：`陪练功能API接口规范.md`
4. 数据流程图：`陪练功能数据流程图.md`
5. OAuth认证规范：`../../规范与约定-团队基线.md`
6. 完整迁移报告：`/root/aiedu/OAUTH_MIGRATION_SUCCESS.md`

---

**文档版本**: v2.0  
**最后更新**: 2025-11-16  
**维护人**: 考培练系统开发团队  
**重大更新**: OAuth认证迁移完成