998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
223 lines
5.0 KiB
Markdown
223 lines
5.0 KiB
Markdown
# 陪练功能开发文档
|
||
|
||
## 📚 文档导航
|
||
|
||
本目录包含考培练系统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（完整版）
|