# 陪练功能开发文档

## 📚 文档导航

本目录包含考培练系统AI陪练功能的完整开发文档。

---

## 🎯 快速开始

### 新成员必读

1. **⚠️核心差异点速查.md**（5分钟）- 与参考代码的关键不同
2. **基础信息.md**（5分钟）- 功能概述和配置信息
3. **README.md**（本文档）- 文档导航

### 开发人员

**后端开发**：
1. Coze-API文档.md - Coze API使用指南
2. 陪练功能API接口规范.md - 14个API接口定义
3. 陪练分析报告-数据结构与Dify规范.md - Dify工作流规范

**前端开发**：
1. 参考代码分析-Training模块.md - React到Vue3迁移方案
2. 陪练功能API接口规范.md - 前端API调用
3. 陪练功能数据流程图.md - 数据流程

---

## ✅ 完成报告

### 已完成功能

1. **✅陪练中心入口开发完成报告.md** - 预设场景陪练（文本模式）
2. **✅语音陪练功能完成报告.md** - 语音对话功能
3. **✅课程中心陪练入口开发完成报告.md** - 课程场景提取
4. **✅陪练分析报告功能完成报告.md** - AI分析报告

---

## 📖 技术文档

### 核心技术文档

**Coze集成**：
- Coze-API文档.md - Coze WebSocket API完整使用指南
- ⚠️核心差异点速查.md - 场景提示词构建要点

**API规范**：
- 陪练功能API接口规范.md - 14个API接口详细定义
- 陪练分析报告-数据结构与Dify规范.md - Dify工作流输入输出

**数据流程**：
- 陪练功能数据流程图.md - 完整流程图和时序图
- 陪练功能技术方案.md - 技术架构和实现方案

**参考代码**：
- 参考代码分析-Training模块.md - React实现深度解析和Vue3迁移

**基础信息**：
- 基础信息.md - 功能概述、配置信息、参考代码位置

---

## 🎯 核心功能

### 1. 语音陪练对话

- 前端@coze/api直连wss://ws.coze.cn
- 实时语音识别和播放
- 双方字幕实时显示
- 语音/文本模式切换

**技术**：WsChatClient + Agora SDK

### 2. 对话历史保存

- 实时保存到MySQL（practice_dialogues表）
- 会话管理（practice_sessions表）
- 异步保存，不阻塞对话

### 3. AI分析报告

- Dify工作流生成分析
- 5个维度评分
- 6个能力评估
- 对话标注（亮点/金牌话术）
- 改进建议

**Dify API Key**：app-9MWaCEiRegpYGQLov4S9oQjh

### 4. 报告展示

- practice-report.vue页面
- 合并数据库对话+Dify标注
- 雷达图可视化
- 对话筛选功能

### 5. 陪练记录

- practice-records.vue页面
- 列表查询和筛选
- 统计数据展示

---

## 📊 数据库表

### 4张表

1. **practice_scenes** - 陪练场景（5个预设场景）
2. **practice_sessions** - 陪练会话（记录时长、轮次）
3. **practice_dialogues** - 对话记录（逐条保存）
4. **practice_reports** - 分析报告（JSON存储）

---

## 🔌 API接口

### 14个接口

**场景管理**（2个）：
- GET /practice/scenes
- GET /practice/scenes/{id}

**对话管理**（3个）：
- POST /practice/start（SSE）
- POST /practice/interrupt
- POST /practice/conversation/create

**会话管理**（7个）：
- POST /practice/sessions/create
- POST /practice/dialogues/save
- POST /practice/sessions/{id}/end
- POST /practice/sessions/{id}/analyze
- GET /practice/reports/{id}
- GET /practice/sessions/list
- GET /practice/stats

**场景提取**（1个）：
- POST /practice/extract-scene

---

## ⚠️ 关键要点

### 场景提示词（最重要）

考培练系统与参考代码的核心差异：
- **首次消息必须包含完整场景设定**
- 使用Markdown格式组织
- 后续消息只发送用户输入
- 详见：⚠️核心差异点速查.md

### Dify对话标注格式

```json
{
  "dialogue_annotations": [
    {"sequence": 1, "tags": ["金牌话术"], "comment": "..."}
  ]
}
```

**重要**：
- 完整对话来自数据库
- Dify只返回标注（sequence+tags+comment）
- 后端自动合并

### 语音识别技巧

- server_vad模式
- 说完话保持静音500ms
- 环境必须安静

---

## 📝 开发状态

### 已完成（100%）

- ✅ 语音陪练对话
- ✅ 对话历史保存
- ✅ AI分析报告
- ✅ 报告页面展示
- ✅ 陪练记录管理

### 测试通过

- ✅ 语音连接和播放
- ✅ 用户语音识别
- ✅ 对话实时保存
- ✅ Dify分析报告生成
- ✅ 对话标注匹配
- ✅ 报告页面数据展示

---

## 🎓 核心经验

1. **前端直连Coze** - 比后端中转简单高效
2. **使用官方SDK** - @coze/api稳定可靠
3. **对话数据分离** - 数据库存完整对话，Dify只做标注
4. **异步保存策略** - 保存失败不影响对话继续
5. **合理的数据结构** - 两张表分离（会话+对话）便于查询

---

## 📞 技术支持

遇到问题时查阅：
1. **场景不生效** → 核心差异点速查.md
2. **语音无法识别** → Coze-API文档.md（VAD配置）
3. **API对接问题** → 陪练功能API接口规范.md
4. **Dify格式问题** → 陪练分析报告-数据结构与Dify规范.md

---

**文档维护**：考培练系统开发团队  
**最后更新**：2025-10-13  
**版本**：v2.0（完整版）