# 流式聊天 API 文档

## 概述
该 API 提供实时流式聊天功能，支持文本对话和语音合成。API 使用 Server-Sent Events (SSE) 实现流式响应，确保实时性和高效性。

## 基础信息
- 基础URL: `http://your-domain:8080`
- 内容类型: `application/json`
- 响应类型: `text/event-stream` (流式响应)

## API 端点

### 1. 聊天接口
```
POST /chat
```

#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| query | string | 是 | 用户输入的查询文本 |
| response_mode | string | 是 | 响应模式，使用 "streaming" 启用流式响应 |
| user | string | 是 | 用户标识符 |
| conversation_id | string | 否 | 会话ID，首次对话可不传 |

#### 请求示例
```json
{
    "query": "你好，请介绍一下自己",
    "response_mode": "streaming",
    "user": "user123",
    "conversation_id": ""
}
```

#### 响应格式
响应使用 Server-Sent Events (SSE) 格式，每个事件包含以下字段：

| 字段名 | 类型 | 描述 |
|--------|------|------|
| answer | string | 机器人的文本回复 |
| isEnd | boolean | 是否为最后一条消息 |
| conversation_id | string | 会话ID |
| task_id | string | 任务ID |
| audio_data | string | 语音数据（URL或十六进制编码） |

#### 响应示例
```
data: {"answer":"你好！","isEnd":false,"conversation_id":"conv_123","task_id":"task_456","audio_data":"http://example.com/audio.mp3"}
data: {"answer":"我是AI助手","isEnd":false,"conversation_id":"conv_123","task_id":"task_456","audio_data":"http://example.com/audio2.mp3"}
data: {"answer":"","isEnd":true,"conversation_id":"conv_123","task_id":"task_456"}
```

### 2. 停止对话
```
POST /chat-messages/:task_id/stop
```

#### 路径参数
| 参数名 | 类型 | 描述 |
|--------|------|------|
| task_id | string | 要停止的任务ID |

#### 响应示例
```json
{
    "status": "success",
    "message": "Conversation stopped"
}
```

### 3. 删除对话
```
DELETE /conversations/:conversation_id
```

#### 路径参数
| 参数名 | 类型 | 描述 |
|--------|------|------|
| conversation_id | string | 要删除的会话ID |

#### 查询参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| user | string | 是 | 用户标识符 |

#### 响应示例
```json
{
    "status": "success",
    "message": "Conversation deleted"
}
```

## 前端集成示例

### 1. 基本使用
```javascript
async function sendMessage(message) {
    const response = await fetch('/chat', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            query: message,
            response_mode: 'streaming',
            user: 'user123',
            conversation_id: currentConversationId
        })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const { value, done } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const data = JSON.parse(line.slice(6));
                // 处理响应数据
                handleResponse(data);
            }
        }
    }
}
```

### 2. 处理响应数据
```javascript
function handleResponse(data) {
    // 更新会话ID
    if (data.conversation_id) {
        currentConversationId = data.conversation_id;
    }

    // 处理文本回复
    if (data.answer) {
        updateChatMessage(data.answer);
    }

    // 处理语音数据
    if (data.audio_data) {
        playAudio(data.audio_data);
    }
}
```

### 3. 播放音频
```javascript
function playAudio(audioData) {
    // URL格式的音频
    if (audioData.startsWith('http')) {
        const audio = new Audio(audioData);
        audio.play();
    } 
    // 十六进制编码的音频
    else {
        const audioContext = new (window.AudioContext || window.webkitAudioContext)();
        const audioDataArray = new Uint8Array(
            audioData.match(/.{1,2}/g).map(byte => parseInt(byte, 16))
        );
        
        audioContext.decodeAudioData(audioDataArray.buffer, (buffer) => {
            const source = audioContext.createBufferSource();
            source.buffer = buffer;
            source.connect(audioContext.destination);
            source.start(0);
        });
    }
}
```

## 错误处理

### 常见错误码
| 状态码 | 描述 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 500 | 服务器内部错误 |

### 错误响应格式
```json
{
    "error": "错误描述信息"
}
```

## 最佳实践

1. **会话管理**
   - 保存 `conversation_id` 以维持对话上下文
   - 在对话结束时清理资源

2. **错误处理**
   - 实现重试机制
   - 优雅处理网络错误
   - 提供用户友好的错误提示

3. **性能优化**
   - 使用缓冲通道处理流式数据
   - 及时清理不需要的音频资源
   - 实现消息队列避免并发问题

4. **安全性**
   - 验证用户身份
   - 使用 HTTPS
   - 实现请求频率限制

## 注意事项

1. 确保正确处理 SSE 连接的关闭
2. 实现适当的错误重试机制
3. 注意音频资源的及时释放
4. 考虑网络延迟和断线重连
5. 实现适当的加载状态提示