Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

6.8 KiB

Raw Permalink Blame History

✅ 陪练功能完整开发报告

完成时间：2025-10-13
完成度：100%
测试状态：✅ 全部通过

🎉 功能总览

完成的5大模块

语音陪练对话 - 实时WebSocket语音交互
对话历史保存 - MySQL数据库持久化
AI分析报告 - Dify智能分析和评分
报告页面展示 - 完整的可视化展示
陪练记录管理 - 历史记录查询和统计

📊 核心功能

1. 语音陪练对话（文本+语音双模式）

文本模式：

SSE流式对话
场景提示词驱动
conversation_id保持上下文

语音模式：

前端@coze/api直连wss://ws.coze.cn
Agora SDK自动处理音频
实时语音识别（VAD）
流式语音播放
双方字幕显示

技术架构：

前端 @coze/api → wss://ws.coze.cn

关键配置：

allowPersonalAccessTokenInBrowser: true
audioMutedDefault: false
playbackVolumeDefault: 1.0

2. 对话历史保存

实时保存策略：

用户语音识别完成→立即保存
AI回复完成→立即保存
异步保存，失败只记录日志
sequence连续递增

数据库表：

practice_sessions（会话元信息）
practice_dialogues（对话详细记录）

3. AI分析报告

Dify工作流：

API Key: app-9MWaCEiRegpYGQLov4S9oQjh
输入: dialogue_history（JSON数组）
输出: 分析结果（dialogue_annotations格式）

分析内容：

综合得分（0-100分）
5个维度打分（开场技巧、需求挖掘、产品介绍、异议处理、成交技巧）
6个能力评估（沟通表达、倾听理解、情绪控制、专业知识、销售技巧、应变能力）
对话标注（sequence+tags+comment）
3-5条改进建议（含具体示例）

对话复盘逻辑：

完整对话（数据库）+ Dify标注（sequence匹配）= 对话复盘

4. 报告页面展示

页面：practice-report.vue

展示内容：

会话信息（日期、时长、轮次）
综合评分圆环图
5个维度进度条
6个能力雷达图
完整对话复盘（标注亮点/金牌话术）
改进建议列表

筛选功能：

全部对话
亮点话术
金牌话术

5. 陪练记录管理

页面：practice-records.vue

功能：

陪练记录列表（分页）
统计数据（总次数、平均分、总时长、本月进步）
关键词搜索
场景类型筛选
时间范围筛选
分数范围筛选

📁 数据库设计

4张表

-- 陪练场景表（5个预设场景）
practice_scenes (id, name, type, difficulty, background, ai_role, objectives, keywords...)

-- 陪练会话表
practice_sessions (session_id, user_id, scene_id, start_time, end_time, duration_seconds, turns, status...)

-- 对话记录表
practice_dialogues (session_id, speaker, content, timestamp, sequence...)

-- 分析报告表
practice_reports (session_id, total_score, score_breakdown, ability_dimensions, dialogue_review, suggestions...)

🔌 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 - 从课程提取场景

🎓 核心技术

前端直连Coze

import { WsChatClient } from '@coze/api/ws-tools'

const client = new WsChatClient({
  token: 'pat_xxx',
  baseWsURL: 'wss://ws.coze.cn',
  allowPersonalAccessTokenInBrowser: true,
  botId: '7560643598174683145'
})

await client.connect()
client.setPlaybackVolume(1)
client.sendTextMessage(scenePrompt)

Dify对话标注

输入：

{
  "inputs": {
    "dialogue_history": "[{\"speaker\":\"user\",\"content\":\"...\"}]"
  }
}

输出：

{
  "dialogue_annotations": [
    {"sequence": 1, "tags": ["金牌话术"], "comment": "开场专业"}
  ]
}

对话合并

# 数据库查询完整对话
dialogues = SELECT * FROM practice_dialogues

# 按sequence匹配Dify标注
for dialogue in dialogues:
    annotation = annotations_map.get(dialogue.sequence)
    dialogue_review.append({
        "content": dialogue.content,  # 来自数据库
        "tags": annotation.tags,  # 来自Dify
        "comment": annotation.comment  # 来自Dify
    })

📈 性能指标

功能	指标
WebSocket连接	<2秒
语音识别	<2秒
对话保存	<100ms
Dify分析	10-15秒
报告查询	<300ms

🎊 开发成果

前端文件（5个）

src/utils/cozeVoiceClient.ts
src/components/VoiceChat.vue
src/components/TextChat.vue
src/views/trainee/practice-report.vue（数据对接）
src/views/trainee/practice-records.vue（数据对接）

后端文件（5个）

app/models/practice.py（4个模型）
app/schemas/practice.py（20个Schema）
app/services/coze_service.py
app/services/dify_practice_service.py
app/api/v1/practice.py（14个接口）

配置文件

package.json - 添加@coze/api依赖
app/core/config.py - Coze和Dify配置

🔑 关键经验

架构选择：前端直连优于后端中转
官方SDK优先：@coze/api比自己实现可靠
数据分离：对话存数据库，Dify做标注
异步保存：不阻塞用户体验
合理设计：两张表分离便于查询

🚀 使用方式

完整流程

1. 陪练中心 → 选择场景 → 开始陪练
   ↓
2. 语音对话（实时保存到数据库）
   ↓
3. 点击"保存并查看分析报告"（Dify分析）
   ↓
4. 查看完整分析报告（5维度+6能力+对话复盘+建议）
   ↓
5. 陪练记录页面（查看历史+统计）

访问地址

陪练中心：http://localhost:3001/trainee/ai-practice-center
陪练记录：http://localhost:3001/trainee/practice-records
分析报告：http://localhost:3001/trainee/practice-report/{sessionId}

⚠️ 重要规范

Dify约束

dialogue_annotations的sequence必须在1到实际对话数范围内
tags只有两种：["亮点话术"]或["金牌话术"]
不要返回不存在的sequence

VAD使用

说完话保持静音500ms
环境安静
说话清晰

开发团队：考培练系统开发组
完成日期：2025-10-13
文档版本：v2.0（最终版）

🎊 陪练功能完整开发圆满完成！

6.8 KiB Raw Permalink Blame History Unescape Escape