server/聊天功能API测试文档.md

# 聊天对话接口测试文档

## 接口概述

本文档提供了聊天对话系统的所有API接口的详细测试用例，包括请求参数、响应结构和示例数据。

## 统一响应格式

所有接口均采用标准化的JSON响应格式：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1640995200000
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200：成功，400：客户端错误，500：服务器错误） |
| message | String | 响应消息 |
| data | Object | 业务数据 |
| timestamp | Long | 响应时间戳 |

## 参数详细说明

### 核心参数配置说明

在所有聊天接口中，以下四个参数用于配置模型、模板和语音服务，本节详细说明每个参数的可选值范围及其在数据库中对应的具体内容。

#### 1. modelId（模型ID）

**参数说明：** 指定使用的大语言模型配置  
**默认值：** 7  
**数据库表：** `sys_config`  
**筛选条件：** `configType = 'llm'`

**可选值及对应配置：**

| modelId | configName | provider | modelType | 说明 |
|---------|------------|----------|-----------|------|
| 1 | gpt-3.5-turbo | openai | chat | OpenAI GPT-3.5 Turbo模型 |
| 2 | glm-4 | zhipu | chat | 智谱AI GLM-4模型 |
| 3 | spark-lite | xfyun | chat | 讯飞星火认知大模型Lite版 |
| 4 | qwen1.5-7b-chat | qwen | chat | 阿里云通义千问1.5-7B对话模型 |
| 5 | lmstudio-local | lmstudio | chat | LM Studio本地部署模型 |
| 7 | qwen2.5-7b-instruct | qwen | chat | 阿里云通义千问2.5-7B指令模型（默认） |

**使用示例：**
```json
{
  "modelId": 7,  // 使用通义千问2.5-7B指令模型
  "message": "你好"
}
```

#### 2. templateId（模板ID）

**参数说明：** 指定使用的对话模板，定义AI的角色和行为特征  
**默认值：** 6  
**数据库表：** `sys_template`

**可选值及对应配置：**

| templateId | templateName | templateContent（角色描述） |
|------------|--------------|---------------------------|
| 1 | 通用助手 | 你是一个通用的AI助手，能够回答各种问题，提供有用的信息和建议。请保持友好、专业的态度。 |
| 2 | 教育老师 | 你是一位经验丰富的教育工作者，擅长用简单易懂的方式解释复杂概念，善于启发学生思考。 |
| 3 | 专业领域专家 | 你是一位在多个专业领域都有深入研究的专家，能够提供专业、准确的技术建议和解决方案。 |
| 4 | 中英翻译专家 | 你是一位专业的中英文翻译专家，能够准确、流畅地进行中英文互译，注重语言的准确性和文化背景。 |
| 5 | 知心朋友 | 你是一位温暖、善解人意的朋友，善于倾听和理解他人的情感，能够提供情感支持和建议。 |
| 6 | 湾湾小何 | 你是湾湾小何，一个活泼可爱的台湾女孩，说话带有台湾腔调，性格开朗友善，喜欢用台湾的网络用语。 |

**使用示例：**
```json
{
  "templateId": 2,  // 使用教育老师模板
  "message": "请解释一下量子力学的基本概念"
}
```

#### 3. sttConfigId（语音识别配置ID）

**参数说明：** 指定使用的语音转文字（STT）服务配置  
**默认值：** 9  
**数据库表：** `sys_config`  
**筛选条件：** `configType = 'stt'`

**可选值及对应配置：**

| sttConfigId | configName | provider | 说明 |
|-------------|------------|----------|------|
| 6 | 语音识别大模型-字符版 | volcengine | 火山引擎语音识别服务 |
| 9 | qwen3-asr-flash | aliyun | 阿里云通义千问3 ASR闪电版（默认） |

**使用示例：**
```json
{
  "sttConfigId": 9,  // 使用阿里云通义千问3 ASR
  "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
}
```

#### 4. ttsConfigId（语音合成配置ID）

**参数说明：** 指定使用的文字转语音（TTS）服务配置  
**默认值：** 8  
**数据库表：** `sys_config`  
**筛选条件：** `configType = 'tts'`

**可选值及对应配置：**

| ttsConfigId | configName | provider | 说明 |
|-------------|------------|----------|------|
| 5 | 语音合成大模型-字符版 | volcengine | 火山引擎语音合成服务 |
| 8 | 语音合成服务 | aliyun | 阿里云语音合成服务（默认） |

**使用示例：**
```json
{
  "ttsConfigId": 8,  // 使用阿里云语音合成
  "text": "你好，欢迎使用语音合成服务"
}
```

### 参数组合建议

**推荐配置组合：**

1. **默认配置（推荐）：**
   ```json
   {
     "modelId": 7,        // 通义千问2.5-7B
     "templateId": 6,     // 湾湾小何
     "sttConfigId": 9,    // 阿里云ASR
     "ttsConfigId": 8     // 阿里云TTS
   }
   ```

2. **教育场景配置：**
   ```json
   {
     "modelId": 4,        // 通义千问1.5-7B
     "templateId": 2,     // 教育老师
     "sttConfigId": 9,    // 阿里云ASR
     "ttsConfigId": 8     // 阿里云TTS
   }
   ```

3. **专业咨询配置：**
   ```json
   {
     "modelId": 2,        // 智谱GLM-4
     "templateId": 3,     // 专业领域专家
     "sttConfigId": 9,    // 阿里云ASR
     "ttsConfigId": 8     // 阿里云TTS
   }
   ```

### 注意事项

1. **配置有效性：** 请确保所选择的配置ID在数据库中存在且状态为可用
2. **服务可用性：** 不同的provider可能需要相应的API密钥和服务配置
3. **兼容性：** 建议使用相同provider的STT和TTS服务以获得更好的兼容性
4. **默认值：** 如果不指定参数，系统将使用上述默认值
5. **权限控制：** 某些配置可能需要特定的用户权限才能使用

## 接口列表

### 1. 同步对话接口

**接口路径：** `/api/chat/sync`  
**请求方法：** POST  
**Content-Type：** application/json

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| message | String | 是 | - | 用户消息内容 | "你好，请介绍一下人工智能" |
| sessionId | String | 否 | 自动生成 | 会话ID | "session123" |
| useFunctionCall | Boolean | 否 | false | 是否使用函数调用 | false |
| modelId | Integer | 否 | 7 | 模型ID | 7 |
| templateId | Integer | 否 | 1 | 模板ID | 1 |
| sttConfigId | Integer | 否 | 9 | STT配置ID | 9 |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |

#### 请求示例

```json
{
  "message": "你好，请介绍一下人工智能",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}
```

#### 测试指令

**基础测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请介绍一下人工智能",
    "sessionId": "test_session_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }'
```

**最简测试（仅必填参数）：**
```bash
curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天气怎么样？"
  }'
```

**功能调用测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我查询一下北京的天气",
    "sessionId": "function_test_001",
    "useFunctionCall": true,
    "modelId": 7,
    "templateId": 1
  }'
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "对话成功",
  "data": {
    "response": "人工智能（AI）是计算机科学的一个分支...",
    "sessionId": "session123"
  },
  "timestamp": 1640995200000
}
```

**失败响应：**
```json
{
  "code": 500,
  "message": "系统内部错误: 模型服务不可用",
  "data": null,
  "timestamp": 1640995200000
}
```

### 2. 流式对话接口

**接口路径：** `/api/chat/stream`  
**请求方法：** POST  
**Content-Type：** application/json  
**响应类型：** text/event-stream

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| message | String | 是 | - | 用户消息内容 | "请详细介绍一下人工智能的发展历程" |
| sessionId | String | 否 | 自动生成 | 会话ID | "session123" |
| useFunctionCall | Boolean | 否 | false | 是否使用函数调用 | false |
| modelId | Integer | 否 | 7 | 模型ID | 7 |
| templateId | Integer | 否 | 1 | 模板ID | 1 |
| sttConfigId | Integer | 否 | 9 | STT配置ID | 9 |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |

#### 请求示例

```json
{
  "message": "请详细介绍一下人工智能的发展历程",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}
```

#### 测试指令

**基础流式测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "请详细介绍一下人工智能的发展历程",
    "sessionId": "stream_test_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }' \
  --no-buffer
```

**最简流式测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "写一首关于春天的诗"
  }' \
  --no-buffer
```

**长文本流式测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "请详细解释量子计算的原理、应用场景和未来发展趋势",
    "sessionId": "long_stream_test_001",
    "modelId": 7,
    "templateId": 1
  }' \
  --no-buffer
```

#### 响应结构

**SSE事件流：**
```
event: start
data: {"sessionId": "session123", "timestamp": 1640995200000}

event: sentence
data: {"content": "人工智能的发展历程可以分为几个重要阶段：", "sessionId": "session123"}

event: sentence
data: {"content": "1. 起源阶段（1940-1956年）...", "sessionId": "session123"}

event: complete
data: {"sessionId": "session123", "totalTokens": 1500, "timestamp": 1640995210000}
```

**错误事件：**
```
event: error
data: 对话失败: 网络连接超时
```

### 3. 文本转语音接口

**接口路径：** `/api/chat/tts`  
**请求方法：** POST  
**Content-Type：** application/json

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| text | String | 是 | - | 要转换的文本 | "你好，欢迎使用语音合成服务" |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |

#### 请求示例

```json
{
  "text": "你好，欢迎使用语音合成服务，这是一个测试文本",
  "ttsConfigId": 8
}
```

#### 测试指令

**基础TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好，欢迎使用语音合成服务，这是一个测试文本",
    "ttsConfigId": 8
  }'
```

**最简TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "今天天气真不错"
  }'
```

**长文本TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "人工智能是计算机科学的一个分支，它企图了解智能的实质，并生产出一种新的能以人类智能相似的方式做出反应的智能机器。该领域的研究包括机器人、语言识别、图像识别、自然语言处理和专家系统等。",
    "ttsConfigId": 8
  }'
```

**保存音频文件测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一个音频文件保存测试",
    "ttsConfigId": 8
  }' | jq -r '.data.audioBase64' | base64 -d > test_audio.wav
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "语音合成成功",
  "data": {
    "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
    "audioPath": "/audio/tts_abc123.mp3",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}
```

**字段说明：**
- `audioBase64`：音频数据的Base64编码，可直接播放或保存为文件。
- `audioPath`：生成的音频文件在服务器上的路径，便于按需下载或复用。
- `timestamp`：生成时间戳，Unix毫秒。

**失败响应：**
```json
{
  "code": 500,
  "message": "系统内部错误: TTS服务不可用",
  "data": null,
  "timestamp": 1640995200000
}
```

### 4. 对话+语音合成接口

**接口路径：** `/api/chat/answer-tts`  
**请求方法：** POST  
**Content-Type：** application/json

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| message | String | 是 | - | 用户消息内容 | "今天天气怎么样？" |
| sessionId | String | 否 | 自动生成 | 会话ID | "session123" |
| useFunctionCall | Boolean | 否 | false | 是否使用函数调用 | false |
| modelId | Integer | 否 | 7 | 模型ID | 7 |
| templateId | Integer | 否 | 1 | 模板ID | 1 |
| sttConfigId | Integer | 否 | 9 | STT配置ID | 9 |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |

#### 请求示例

```json
{
  "message": "今天天气怎么样？",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}
```

#### 测试指令

**基础对话+TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天气怎么样？",
    "sessionId": "answer_tts_test_001",
    "useFunctionCall": false,
    "modelId": 7,
    "templateId": 1,
    "sttConfigId": 9,
    "ttsConfigId": 8
  }'
```

**最简对话+TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请自我介绍一下"
  }'
```

**功能调用+TTS测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我查询一下上海的天气情况",
    "sessionId": "function_tts_test_001",
    "useFunctionCall": true,
    "modelId": 7,
    "templateId": 1,
    "ttsConfigId": 8
  }'
```

**保存对话音频测试：**
```bash
curl -X POST "http://localhost:8080/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请简单介绍一下人工智能",
    "sessionId": "save_audio_test_001",
    "ttsConfigId": 8
  }' | jq -r '.data.audioBase64' | base64 -d > answer_audio.wav
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "对话成功",
  "data": {
    "response": "今天天气晴朗，温度适宜，是个不错的天气。",
    "sessionId": "session123",
    "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
    "audioPath": "/audio/tts_20241215_143022_abc123.wav",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}
```

**字段说明：**
- `response`：LLM模型回复的文本内容
- `sessionId`：会话ID，用于标识上下文
- `audioBase64`：将回复文本合成为语音后的Base64编码，可直接播放
- `audioPath`：合成语音文件在服务器上的路径，便于回放或缓存
- `timestamp`：响应时间戳，Unix毫秒

### 5. 语音对话接口

**接口路径：** `/api/chat/voice-chat`  
**请求方法：** POST  
**Content-Type：** application/json

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| audioData | String | 是 | - | Base64编码的音频数据 | "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..." |
| sessionId | String | 否 | 自动生成 | 会话ID | "session123" |
| useFunctionCall | Boolean | 否 | false | 是否使用函数调用 | false |
| modelId | Integer | 否 | 7 | 模型ID | 7 |
| templateId | Integer | 否 | 1 | 模板ID | 1 |
| sttConfigId | Integer | 否 | 9 | STT配置ID | 9 |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |

#### 请求示例

```json
{
  "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
  "sessionId": "session123",
  "useFunctionCall": false,
  "modelId": 7,
  "templateId": 1,
  "sttConfigId": 9,
  "ttsConfigId": 8
}
```

#### 测试指令

**基础语音对话测试（需要先准备音频文件）：**
```bash
# 1. 先将音频文件转换为Base64
AUDIO_BASE64=$(base64 -w 0 test_audio.wav)

# 2. 发送语音对话请求
curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"voice_chat_test_001\",
    \"useFunctionCall\": false,
    \"modelId\": 7,
    \"templateId\": 1,
    \"sttConfigId\": 9,
    \"ttsConfigId\": 8
  }"
```

**最简语音对话测试：**
```bash
# 使用最少参数进行语音对话
AUDIO_BASE64=$(base64 -w 0 simple_audio.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\"
  }"
```

**功能调用语音对话测试：**
```bash
# 语音询问天气并启用功能调用
AUDIO_BASE64=$(base64 -w 0 weather_question.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"voice_function_test_001\",
    \"useFunctionCall\": true,
    \"modelId\": 7,
    \"templateId\": 1,
    \"sttConfigId\": 9,
    \"ttsConfigId\": 8
  }"
```

**保存语音对话结果：**
```bash
# 进行语音对话并保存返回的音频
AUDIO_BASE64=$(base64 -w 0 input_audio.wav)

curl -X POST "http://localhost:8080/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"save_voice_test_001\",
    \"ttsConfigId\": 8
  }" | jq -r '.data.audioData' | base64 -d > voice_response.wav
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "语音对话成功",
  "data": {
    "sttResult": {
      "text": "今天天气怎么样？",
      "audioFormat": "wav",
      "audioSize": 245760,
      "sttProvider": "qwen3-asr-flash"
    },
    "llmResult": {
      "response": "今天天气晴朗，温度适宜，是个不错的天气。",
      "inputText": "今天天气怎么样？"
    },
    "ttsResult": {
      "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
      "audioPath": "/audio/voice_chat_20241215_143022_abc123.wav",
      "timestamp": 1640995202000
    },
    "sessionId": "session123",
    "timestamp": 1640995202000
  },
  "timestamp": 1640995202000
}
```

**字段说明：**
- `sttResult`：语音识别结果对象
  - `text`：识别出的文本内容
  - `audioFormat`：输入音频格式
  - `audioSize`：输入音频文件大小（字节）
  - `sttProvider`：使用的STT服务提供商
- `llmResult`：大语言模型处理结果对象
  - `response`：LLM模型回复的文本内容
  - `inputText`：输入给LLM的文本（即STT识别结果）
- `ttsResult`：语音合成结果对象
  - `audioBase64`：TTS合成后的音频Base64编码，可直接播放
  - `audioPath`：TTS合成音频文件在服务器上的路径
  - `timestamp`：TTS合成时间戳
- `sessionId`：会话ID，用于标识上下文
- `timestamp`：响应时间戳，Unix毫秒

### 6. 清除会话接口

**接口路径：** `/api/chat/session/{sessionId}`  
**请求方法：** DELETE

#### 路径参数

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| sessionId | String | 是 | 要清除的会话ID | "session123" |

#### 请求示例

```
DELETE /api/chat/session/session123
```

#### 测试指令

**清除指定会话：**
```bash
curl -X DELETE "http://localhost:8080/api/chat/session/session123"
```

**清除测试会话：**
```bash
curl -X DELETE "http://localhost:8080/api/chat/session/test_session_001"
```

**批量清除多个会话：**
```bash
# 清除多个测试会话
for session in test_session_001 test_session_002 test_session_003; do
  curl -X DELETE "http://localhost:8080/api/chat/session/$session"
  echo "已清除会话: $session"
done
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "会话清除成功",
  "data": {
    "sessionId": "session123",
    "timestamp": 1640995200000
  },
  "timestamp": 1640995200000
}
```

### 7. 清除缓存接口

**接口路径：** `/api/chat/cache`  
**请求方法：** DELETE

#### 查询参数

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| sessionId | String | 否 | 指定会话ID（不传则清除所有） | "session123" |

#### 请求示例

```
DELETE /api/chat/cache?sessionId=session123
DELETE /api/chat/cache
```

#### 测试指令

**清除指定会话缓存：**
```bash
curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=session123"
```

**清除所有缓存：**
```bash
curl -X DELETE "http://localhost:8080/api/chat/cache"
```

**清除测试会话缓存：**
```bash
curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=test_session_001"
```

**批量清除多个会话缓存：**
```bash
# 清除多个测试会话的缓存
for session in test_session_001 test_session_002 test_session_003; do
  curl -X DELETE "http://localhost:8080/api/chat/cache?sessionId=$session"
  echo "已清除会话缓存: $session"
done
```

#### 响应结构

**清除指定会话：**
```json
{
  "code": 200,
  "message": "缓存清除成功",
  "data": {
    "sessionId": "session123"
  },
  "timestamp": 1640995200000
}
```

**清除所有会话：**
```json
{
  "code": 200,
  "message": "缓存清除成功",
  "data": {
    "clearedSessions": 15
  },
  "timestamp": 1640995200000
}
```

### 8. 上传音频文件进行语音对话

**接口路径：** `/api/chat/upload-voice-chat`  
**请求方法：** POST  
**Content-Type：** multipart/form-data

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例值 |
|--------|------|------|--------|------|--------|
| audioFile | File | 是 | - | 音频文件 | audio.wav |
| sessionId | String | 否 | 自动生成 | 会话ID | "session123" |
| useFunctionCall | Boolean | 否 | false | 是否使用函数调用 | false |
| modelId | Integer | 否 | 7 | 模型ID | 7 |
| templateId | Integer | 否 | 1 | 模板ID | 1 |
| sttConfigId | Integer | 否 | 9 | STT配置ID | 9 |
| ttsConfigId | Integer | 否 | 8 | TTS配置ID | 8 |
| description | String | 否 | - | 音频描述 | "用户语音输入" |

#### 请求示例

```bash
curl -X POST "http://localhost:8080/api/chat/upload-voice-chat" \
  -F "audioFile=@audio.wav" \
  -F "sessionId=session123" \
  -F "useFunctionCall=false" \
  -F "modelId=7" \
  -F "templateId=1" \
  -F "sttConfigId=9" \
  -F "ttsConfigId=8" \
  -F "description=用户语音输入"
```

#### 响应结构

**成功响应：**
```json
{
  "code": 200,
  "message": "文件上传成功",
  "data": {
    "sttResult": {
      "text": "今天天气怎么样？",
      "audioFormat": "wav",
      "audioSize": 1024000,
      "sttProvider": "qwen3-asr-flash"
    },
    "llmResult": {
      "response": "今天天气晴朗，温度适宜，是个不错的天气。",
      "inputText": "今天天气怎么样？"
    },
    "ttsResult": {
      "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
      "audioPath": "/audio/upload_voice_chat_20241215_143022_abc123.wav",
      "timestamp": 1640995202000
    },
    "sessionId": "session123",
    "originalFileName": "audio.wav",
    "fileSize": 1024000,
    "contentType": "audio/wav",
    "description": "用户语音输入",
    "timestamp": 1640995202000
  },
  "timestamp": 1640995202000
}
```

**字段说明：**
- `sttResult`：语音识别结果对象
  - `text`：识别出的文本内容
  - `audioFormat`：输入音频格式
  - `audioSize`：输入音频文件大小（字节）
  - `sttProvider`：使用的STT服务提供商
- `llmResult`：大语言模型处理结果对象
  - `response`：LLM模型回复的文本内容
  - `inputText`：输入给LLM的文本（即STT识别结果）
- `ttsResult`：语音合成结果对象
  - `audioBase64`：TTS合成后的音频Base64编码，可直接播放
  - `audioPath`：TTS合成音频文件在服务器上的路径
  - `timestamp`：TTS合成时间戳
- `sessionId`：会话ID，用于标识上下文
- `originalFileName`：用户上传的原始文件名
- `fileSize`：用户上传文件的大小（字节）
- `contentType`：上传文件的MIME类型
- `description`：音频描述信息
- `timestamp`：响应时间戳，Unix毫秒

**文件验证失败：**
```json
{
  "code": 400,
  "message": "参数验证失败: 不支持的音频格式",
  "data": null,
  "timestamp": 1640995200000
}
```

**文件上传异常：**
```json
{
  "code": 400,
  "message": "文件上传失败: 文件大小超过限制",
  "data": null,
  "timestamp": 1640995200000
}
```

## 错误码说明

| 错误码 | 说明 | 常见原因 |
|--------|------|----------|
| 200 | 成功 | 请求处理成功 |
| 400 | 客户端错误 | 参数验证失败、文件格式不支持等 |
| 500 | 服务器错误 | 系统内部错误、服务不可用等 |

## 常见错误消息

| 错误消息 | 说明 | 解决方案 |
|----------|------|----------|
| 消息内容不能为空 | message参数为空 | 检查请求参数 |
| 文本内容不能为空 | text参数为空 | 检查请求参数 |
| 音频数据不能为空 | audioData参数为空 | 检查音频数据 |
| 音频文件不能为空 | 上传的文件为空 | 检查上传文件 |
| 音频文件大小不能超过50MB | 文件过大 | 压缩音频文件 |
| 音频文件大小不能小于1KB | 文件过小 | 检查文件完整性 |
| 不支持的音频格式 | 文件格式不支持 | 使用支持的格式（wav、mp3、m4a、flac、ogg、aac、wma、amr） |
| 无效的音频文件头 | 文件头格式错误 | 检查文件是否损坏或格式正确 |
| 文件上传失败 | 文件保存异常 | 检查服务器存储空间和权限 |
| 系统未配置任何LLM模型 | 模型配置缺失 | 联系管理员配置模型 |
| 会话不存在 | 指定的会话ID不存在 | 检查会话ID或创建新会话 |

## 测试建议

1. **参数验证测试：** 测试必填参数缺失、参数类型错误等场景
2. **边界值测试：** 测试文件大小限制、文本长度限制等
3. **异常场景测试：** 测试网络异常、服务不可用等情况
4. **并发测试：** 测试多用户同时访问的性能表现
5. **安全测试：** 测试恶意文件上传、SQL注入等安全问题

## 完整测试流程示例

### 基础功能测试流程

```bash
#!/bin/bash
# 聊天功能API完整测试脚本

BASE_URL="http://localhost:8080"
SESSION_ID="complete_test_$(date +%s)"

echo "=== 聊天功能API完整测试 ==="
echo "测试会话ID: $SESSION_ID"
echo "服务器地址: $BASE_URL"
echo ""

# 1. 同步对话测试
echo "1. 测试同步对话接口..."
curl -X POST "$BASE_URL/api/chat/sync" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"你好，请简单介绍一下自己\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 2. TTS测试
echo "2. 测试TTS接口..."
curl -X POST "$BASE_URL/api/chat/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一个TTS测试，语音合成功能正常工作"
  }' | jq '.'
echo ""

# 3. 对话+TTS测试
echo "3. 测试对话+TTS接口..."
curl -X POST "$BASE_URL/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"请用一句话总结人工智能的作用\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 4. 流式对话测试
echo "4. 测试流式对话接口..."
curl -X POST "$BASE_URL/api/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d "{
    \"message\": \"请简单介绍一下机器学习\",
    \"sessionId\": \"$SESSION_ID\"
  }" \
  --no-buffer | head -20
echo ""

# 5. 清除会话测试
echo "5. 测试清除会话接口..."
curl -X DELETE "$BASE_URL/api/chat/session/$SESSION_ID" | jq '.'
echo ""

# 6. 清除缓存测试
echo "6. 测试清除缓存接口..."
curl -X DELETE "$BASE_URL/api/chat/cache" | jq '.'
echo ""

echo "=== 测试完成 ==="
```

### 语音功能测试流程

```bash
#!/bin/bash
# 语音功能测试脚本（需要准备测试音频文件）

BASE_URL="http://localhost:8080"
SESSION_ID="voice_test_$(date +%s)"
AUDIO_FILE="test_audio.wav"  # 需要准备的测试音频文件

echo "=== 语音功能测试 ==="
echo "测试会话ID: $SESSION_ID"
echo "音频文件: $AUDIO_FILE"
echo ""

# 检查音频文件是否存在
if [ ! -f "$AUDIO_FILE" ]; then
  echo "错误: 音频文件 $AUDIO_FILE 不存在"
  echo "请准备一个测试音频文件（支持格式：wav、mp3、m4a、flac、ogg、aac、wma、amr）"
  exit 1
fi

# 1. 语音对话测试（Base64方式）
echo "1. 测试语音对话接口（Base64方式）..."
AUDIO_BASE64=$(base64 -w 0 "$AUDIO_FILE")
curl -X POST "$BASE_URL/api/chat/voice-chat" \
  -H "Content-Type: application/json" \
  -d "{
    \"audioData\": \"$AUDIO_BASE64\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq '.'
echo ""

# 2. 上传音频文件测试
echo "2. 测试上传音频文件接口..."
curl -X POST "$BASE_URL/api/chat/upload-voice-chat" \
  -F "audioFile=@$AUDIO_FILE" \
  -F "sessionId=$SESSION_ID" \
  -F "description=语音功能测试" | jq '.'
echo ""

# 3. 保存返回的音频
echo "3. 测试保存返回音频..."
curl -X POST "$BASE_URL/api/chat/answer-tts" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"这是一个音频保存测试\",
    \"sessionId\": \"$SESSION_ID\"
  }" | jq -r '.data.audioBase64' | base64 -d > "response_audio_$SESSION_ID.wav"
echo "音频已保存为: response_audio_$SESSION_ID.wav"
echo ""

echo "=== 语音功能测试完成 ==="
```

### 快速健康检查脚本

```bash
#!/bin/bash
# API健康检查脚本

BASE_URL="http://localhost:8080"

echo "=== API健康检查 ==="

# 检查各个接口的基本可用性
endpoints=(
  "POST /api/chat/sync"
  "POST /api/chat/stream" 
  "POST /api/chat/tts"
  "POST /api/chat/answer-tts"
  "POST /api/chat/voice-chat"
  "POST /api/chat/upload-voice-chat"
  "DELETE /api/chat/cache"
)

for endpoint in "${endpoints[@]}"; do
  method=$(echo $endpoint | cut -d' ' -f1)
  path=$(echo $endpoint | cut -d' ' -f2)
  
  echo -n "检查 $endpoint ... "
  
  if [ "$method" = "POST" ]; then
    response=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL$path" \
      -H "Content-Type: application/json" \
      -d '{"message":"health check"}' 2>/dev/null)
  else
    response=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "$BASE_URL$path" 2>/dev/null)
  fi
  
  if [ "$response" = "200" ] || [ "$response" = "400" ]; then
    echo "✓ 可用 (HTTP $response)"
  else
    echo "✗ 不可用 (HTTP $response)"
  fi
done

echo "=== 健康检查完成 ==="
```

## 注意事项

1. 所有接口都支持跨域访问（CORS）
2. 音频文件支持格式：wav、mp3、m4a、flac、ogg、aac、wma、amr
3. 音频文件大小限制：最大50MB，最小1KB
4. 会话ID如果不提供，系统会自动生成
5. 流式接口需要支持SSE（Server-Sent Events）
6. 所有时间戳均为Unix时间戳（毫秒）
7. TTS相关响应统一包含`audioBase64`与`audioPath`两个字段，前者便于直接播放，后者便于文件管理与复用
8. 测试脚本需要安装`jq`工具用于JSON格式化：`sudo apt-get install jq`
9. 语音功能测试需要准备相应格式的音频文件
10. 建议在测试环境中运行完整测试流程，避免影响生产数据