guoyu/log/语音评测模块接口文档.md

# 语音评测模块接口文档

## 概述
语音评测模块用于语文课程的语音跟读和自动评测功能，支持学生录制语音、上传音频、自动评测并记录评测结果。

## 数据库表

### voice_evaluation（语音评测表）
```sql
CREATE TABLE `voice_evaluation` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '评测ID',
  `student_id` bigint NOT NULL COMMENT '学员ID',
  `course_id` bigint DEFAULT NULL COMMENT '课程ID',
  `content` text NOT NULL COMMENT '评测内容（课文或文字）',
  `audio_path` varchar(500) DEFAULT NULL COMMENT '音频文件路径',
  `score` decimal(10,2) DEFAULT NULL COMMENT '评分（总分，0-100）',
  `accuracy` decimal(10,2) DEFAULT NULL COMMENT '准确度（0-100）',
  `fluency` decimal(10,2) DEFAULT NULL COMMENT '流畅度（0-100）',
  `completeness` decimal(10,2) DEFAULT NULL COMMENT '完整度（0-100）',
  `pronunciation` decimal(10,2) DEFAULT NULL COMMENT '发音得分（0-100）',
  `result_detail` text DEFAULT NULL COMMENT '评测详情（JSON格式）',
  `evaluation_time` datetime DEFAULT NULL COMMENT '评测时间',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_student_id` (`student_id`),
  KEY `idx_course_id` (`course_id`),
  KEY `idx_evaluation_time` (`evaluation_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='语音评测表';
```

---

## 后端接口

### 1. 上传音频并进行评测（App端）

**接口URL**: `/study/voiceEvaluation/uploadAndEvaluate`  
**请求方式**: `POST`  
**权限要求**: 学员登录（无需特殊权限）

**请求参数**:
- `file` (MultipartFile, 必填): 音频文件（支持mp3、wav等格式）
- `content` (String, 必填): 评测内容（课文或文字）
- `courseId` (Long, 可选): 课程ID
- `language` (String, 可选): 语言类型，默认"zh-CN"（中文）

**请求示例**:
```javascript
// UniApp端使用uni.uploadFile
uni.uploadFile({
    url: baseURL + '/study/voiceEvaluation/uploadAndEvaluate',
    filePath: recordPath,
    name: 'file',
    formData: {
        content: '评测内容',
        courseId: courseId || '',
        language: 'zh-CN'
    },
    header: {
        'Authorization': 'Bearer ' + token
    }
})
```

**响应示例**:
```json
{
    "code": 200,
    "msg": "评测完成",
    "data": {
        "evaluation": {
            "id": 1,
            "studentId": 100,
            "courseId": 1,
            "content": "评测内容",
            "audioPath": "/upload/voice/xxx.mp3",
            "score": 85.5,
            "accuracy": 90.0,
            "fluency": 85.0,
            "completeness": 88.0,
            "pronunciation": 87.0,
            "resultDetail": "{\"words\":[...]}",
            "evaluationTime": "2025-01-15 10:30:00"
        },
        "audioUrl": "http://localhost:8081/upload/voice/xxx.mp3"
    }
}
```

---

### 2. 获取我的语音评测记录（App端）

**接口URL**: `/study/voiceEvaluation/my-records`  
**请求方式**: `GET`  
**权限要求**: 学员登录

**请求参数**:
- `courseId` (Long, 可选): 课程ID，不传则查询所有记录

**响应示例**:
```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "id": 1,
            "studentId": 100,
            "studentName": "张三",
            "courseId": 1,
            "courseName": "语文课程",
            "content": "评测内容",
            "audioPath": "/upload/voice/xxx.mp3",
            "score": 85.5,
            "accuracy": 90.0,
            "fluency": 85.0,
            "completeness": 88.0,
            "pronunciation": 87.0,
            "evaluationTime": "2025-01-15 10:30:00"
        }
    ]
}
```

---

### 3. 查询语音评测列表（管理后台）

**接口URL**: `/study/voiceEvaluation/list`  
**请求方式**: `GET`  
**权限要求**: `study:voiceEvaluation:list`

**请求参数**:
- `pageNum` (Integer): 页码
- `pageSize` (Integer): 每页数量
- `studentName` (String, 可选): 学员姓名
- `courseName` (String, 可选): 课程名称
- `beginTime` (String, 可选): 开始时间（格式：yyyy-MM-dd）
- `endTime` (String, 可选): 结束时间（格式：yyyy-MM-dd）

**响应示例**:
```json
{
    "code": 200,
    "msg": "操作成功",
    "rows": [
        {
            "id": 1,
            "studentId": 100,
            "studentName": "张三",
            "courseId": 1,
            "courseName": "语文课程",
            "content": "评测内容",
            "score": 85.5,
            "accuracy": 90.0,
            "fluency": 85.0,
            "completeness": 88.0,
            "pronunciation": 87.0,
            "evaluationTime": "2025-01-15 10:30:00"
        }
    ],
    "total": 1
}
```

---

### 4. 获取语音评测详情

**接口URL**: `/study/voiceEvaluation/{id}`  
**请求方式**: `GET`  
**权限要求**: `study:voiceEvaluation:query`

**响应示例**:
```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "studentId": 100,
        "studentName": "张三",
        "courseId": 1,
        "courseName": "语文课程",
        "content": "评测内容",
        "audioPath": "/upload/voice/xxx.mp3",
        "score": 85.5,
        "accuracy": 90.0,
        "fluency": 85.0,
        "completeness": 88.0,
        "pronunciation": 87.0,
        "resultDetail": "{\"words\":[...],\"sentence\":{...}}",
        "evaluationTime": "2025-01-15 10:30:00"
    }
}
```

---

### 5. 删除语音评测

**接口URL**: `/study/voiceEvaluation/{ids}`  
**请求方式**: `DELETE`  
**权限要求**: `study:voiceEvaluation:remove`

**请求参数**:
- `ids` (Long[]): 评测ID数组

**响应示例**:
```json
{
    "code": 200,
    "msg": "操作成功"
}
```

---

### 6. 导出语音评测列表

**接口URL**: `/study/voiceEvaluation/export`  
**请求方式**: `POST`  
**权限要求**: `study:voiceEvaluation:export`

**请求参数**: 同查询列表接口

**响应**: Excel文件下载

---

## 第三方语音服务集成

### 语音服务接口

系统提供了 `IVoiceEvaluationService` 接口，用于集成第三方语音评测服务。

**接口定义**:
```java
public interface IVoiceEvaluationService {
    /**
     * 语音评测
     * @param audioPath 音频文件路径
     * @param content 评测内容
     * @param language 语言类型
     * @return 评测结果
     */
    Map<String, Object> evaluateVoice(String audioPath, String content, String language);
    
    /**
     * 检查服务是否可用
     * @return true-可用，false-不可用
     */
    boolean isAvailable();
}
```

### 支持的第三方服务商

1. **科大讯飞语音评测**
   - 官网：https://www.xfyun.cn/
   - 价格：中等
   - 准确率：高
   - 推荐指数：⭐⭐⭐⭐⭐

2. **百度语音识别**
   - 官网：https://ai.baidu.com/tech/speech/asr
   - 价格：较低
   - 准确率：中等
   - 推荐指数：⭐⭐⭐⭐

3. **腾讯云语音识别**
   - 官网：https://cloud.tencent.com/product/asr
   - 价格：中等
   - 准确率：高
   - 推荐指数：⭐⭐⭐⭐

4. **阿里云语音识别**
   - 官网：https://www.aliyun.com/product/nls
   - 价格：中等
   - 准确率：高
   - 推荐指数：⭐⭐⭐⭐

### 集成步骤

1. **选择服务商**：根据实际需求选择第三方服务商
2. **获取API密钥**：在服务商平台注册并获取API密钥
3. **实现服务类**：实现 `IVoiceEvaluationService` 接口
4. **配置服务**：在配置文件中配置API密钥等信息
5. **替换实现**：将 `VoiceEvaluationServiceImpl` 中的模拟实现替换为真实API调用

### 示例代码（科大讯飞）

```java
@Service
public class XfyunVoiceEvaluationServiceImpl implements IVoiceEvaluationService {
    
    @Value("${voice.xfyun.appid}")
    private String appId;
    
    @Value("${voice.xfyun.apikey}")
    private String apiKey;
    
    @Value("${voice.xfyun.apisecret}")
    private String apiSecret;
    
    @Override
    public Map<String, Object> evaluateVoice(String audioPath, String content, String language) {
        // 1. 读取音频文件
        File audioFile = new File(audioPath);
        byte[] audioData = FileUtils.readFileToByteArray(audioFile);
        
        // 2. 调用科大讯飞API
        XfyunClient client = new XfyunClient(appId, apiKey, apiSecret);
        EvaluationResult result = client.evaluate(audioData, content, language);
        
        // 3. 解析返回结果
        Map<String, Object> evaluationResult = new HashMap<>();
        evaluationResult.put("score", result.getTotalScore());
        evaluationResult.put("accuracy", result.getAccuracy());
        evaluationResult.put("fluency", result.getFluency());
        evaluationResult.put("completeness", result.getCompleteness());
        evaluationResult.put("pronunciation", result.getPronunciation());
        evaluationResult.put("resultDetail", result.getDetailJson());
        
        return evaluationResult;
    }
    
    @Override
    public boolean isAvailable() {
        // 检查API密钥是否配置
        return StringUtils.isNotEmpty(appId) && 
               StringUtils.isNotEmpty(apiKey) && 
               StringUtils.isNotEmpty(apiSecret);
    }
}
```

---

## 前端页面

### UniApp端

**页面路径**: `frontend-uniapp/src/pages/voice/evaluation.vue`

**功能**:
- 设置评测内容
- 语音录制（开始/停止）
- 播放录音
- 上传音频并评测
- 查看评测结果
- 查看历史记录

**使用方式**:
```javascript
// 跳转到语音评测页面
uni.navigateTo({
    url: '/pages/voice/evaluation?courseId=1&courseName=语文课程&content=评测内容'
})
```

### 管理后台

**页面路径**: `ruoyi-ui/src/views/study/voiceEvaluation/index.vue`

**功能**:
- 查询语音评测列表
- 查看评测详情
- 删除评测记录
- 导出评测数据

---

## 使用说明

### 1. 数据库初始化

执行SQL脚本创建表：
```bash
mysql -u root -p ry_study < log/Sql/voice_evaluation_table.sql
```

### 2. 配置第三方服务（可选）

如果需要使用真实的语音评测服务，需要：

1. 在 `application.yml` 中配置API密钥：
```yaml
voice:
  xfyun:
    appid: your_app_id
    apikey: your_api_key
    apisecret: your_api_secret
```

2. 实现 `IVoiceEvaluationService` 接口
3. 替换 `VoiceEvaluationServiceImpl` 中的实现

### 3. 测试

1. **UniApp端测试**：
   - 打开语音评测页面
   - 输入评测内容
   - 录制语音
   - 上传并评测
   - 查看评测结果

2. **管理后台测试**：
   - 登录管理后台
   - 进入"学习系统" -> "语音评测"
   - 查看评测列表
   - 查看评测详情

---

## 注意事项

1. **音频格式**：支持mp3、wav等常见音频格式
2. **文件大小**：建议音频文件不超过10MB
3. **录音时长**：建议录音时长不超过60秒
4. **第三方服务**：当前使用模拟实现，实际使用时需要接入真实的第三方服务
5. **权限控制**：教师只能查看自己班级学员的评测记录（通过数据权限控制）

---

## 更新日志

- 2025-01-XX：创建语音评测模块，实现基础功能
- 待完善：集成第三方语音评测服务