# SSE工具类使用指南

## 概述

SSE (Server-Sent Events) 工具类提供了通用的流式响应处理功能，支持实时数据流处理、回调机制和错误处理。

## 主要功能

### 1. 基础SSE请求 - `createSSERequest()`

最灵活的底层API，支持完全自定义配置。

```javascript
import { createSSERequest } from '@/utils/sse.js'

const response = await createSSERequest({
  url: 'https://api.example.com/stream',
  method: 'POST',
  data: { message: '你好' },
  headers: { 'Custom-Header': 'value' },
  onChunk: (chunk) => {
    console.log('接收到数据:', chunk.content)
    console.log('累积内容:', chunk.totalContent)
  },
  onComplete: (result) => {
    console.log('流式响应完成:', result.data)
  },
  onError: (error) => {
    console.error('发生错误:', error)
  },
  doneMarker: '[DONE]' // 自定义结束标记
})
```

### 2. 默认配置SSE请求 - `createDefaultSSERequest()`

带有默认配置的便捷API。

```javascript
import { createDefaultSSERequest } from '@/utils/sse.js'

const response = await createDefaultSSERequest(
  '/api/chat/stream', // API端点
  { message: '你好' }, // 请求数据
  {
    onChunk: (chunk) => {
      // 处理数据块
      updateUI(chunk.content)
    },
    onComplete: (result) => {
      // 处理完成
      console.log('完成:', result.data.message)
    }
  }
)
```

### 3. 宠物助手专用SSE - `createPetAssistantSSE()`

专门为宠物助手功能设计的API。

```javascript
import { createPetAssistantSSE } from '@/utils/sse.js'

const response = await createPetAssistantSSE(
  {
    message: '我的宠物生病了怎么办？',
    temperature: 0.7,
    maxTokens: 1000
  },
  {
    onChunk: (chunk) => {
      // 实时更新AI回复
      aiMessage.content = chunk.totalContent
      scrollToBottom()
    },
    onComplete: (result) => {
      // 更新元数据
      aiMessage.isSensitive = result.data.isSensitive
      aiMessage.tokenCount = result.data.tokenCount
    }
  }
)
```

### 4. 可取消的SSE请求 - `createCancellableSSE()`

支持取消操作的SSE请求。

```javascript
import { createCancellableSSE, SSE_STATUS } from '@/utils/sse.js'

const { promise, cancel, getStatus } = createCancellableSSE({
  url: '/api/stream',
  data: { message: '长时间处理的请求' },
  onChunk: (chunk) => {
    console.log('状态:', getStatus()) // 'streaming'
    updateContent(chunk.content)
  }
})

// 5秒后取消请求
setTimeout(() => {
  if (getStatus() === SSE_STATUS.STREAMING) {
    cancel()
    console.log('请求已取消')
  }
}, 5000)

try {
  const result = await promise
  console.log('请求完成:', result)
} catch (error) {
  console.log('请求被取消或失败:', error)
}
```

## 回调函数参数

### onChunk(chunk)
- `chunk.content` - 当前数据块内容
- `chunk.totalContent` - 累积的完整内容
- `chunk.chunk` - 原始解析的数据对象

### onComplete(result)
- `result.data.message` - 完整的响应消息
- `result.data.isSensitive` - 是否包含敏感内容
- `result.data.tokenCount` - 使用的token数量
- `result.data.responseTime` - 响应时间

### onError(error)
- 网络错误、解析错误或其他异常

## 状态枚举

```javascript
import { SSE_STATUS } from '@/utils/sse.js'

SSE_STATUS.PENDING    // 等待中
SSE_STATUS.STREAMING  // 流式传输中
SSE_STATUS.COMPLETED  // 已完成
SSE_STATUS.ERROR      // 发生错误
SSE_STATUS.CANCELLED  // 已取消
```

## 在Vue组件中使用

```javascript
// 在组件中导入
import { createPetAssistantSSE } from '@/utils/sse.js'

export default {
  methods: {
    async sendMessage() {
      // 创建消息对象
      const aiMessage = {
        type: 'ai',
        content: '',
        time: this.getCurrentTime()
      }
      this.messageList.push(aiMessage)
      
      // 发起SSE请求
      try {
        const result = await createPetAssistantSSE(
          { message: this.inputMessage },
          {
            onChunk: (chunk) => {
              // 实时更新内容
              aiMessage.content = chunk.totalContent
              this.$nextTick(() => {
                this.scrollToBottom()
              })
            },
            onComplete: (result) => {
              // 更新元数据
              Object.assign(aiMessage, result.data)
            },
            onError: (error) => {
              console.error('SSE失败:', error)
              // 可以在这里实现降级处理
            }
          }
        )
      } catch (error) {
        // 处理异常
        this.handleError(error)
      }
    }
  }
}
```

## 注意事项

1. **自动认证**: 工具类会自动添加Authorization头部
2. **错误处理**: 建议同时实现onError回调和try-catch
3. **内存管理**: 长时间的流式响应注意内存使用
4. **网络状态**: 考虑网络中断的情况
5. **降级处理**: SSE失败时可以降级到普通API请求

## 扩展使用

可以基于基础API创建更多专用函数：

```javascript
// 创建客服聊天SSE
export function createCustomerServiceSSE(data, callbacks) {
  return createDefaultSSERequest('/api/customer/stream', data, callbacks)
}

// 创建代码生成SSE
export function createCodeGenerationSSE(data, callbacks) {
  return createDefaultSSERequest('/api/code/generate', data, callbacks)
}
```