# Coze API 集成说明

## 概述

本项目已经优化了 AiChatServiceImpl 的 Coze API 接口实现，确保能够正确调用 Coze 的 v3 API。

## 配置说明

### application.yml 配置

```yaml
emotion:
  coze:
    api:
      token: pat_GCR4qKzqpf90wMCvKsldMrB18KG3QsLDci65bZthssKsbLxu8X70BKYumleDcabO
      base-url: https://api.coze.cn
      chat:
        path: /v3/chat
        talk:
          bot-id: 7523042446285439016
          workflow-id: 7523047462895796287
        summary:
          bot-id: 7529062814150295595
          workflow-id: 7523047462895796287
      timeout: 30000
      retry-count: 3
      retry-delay: 1000
```

### 配置项说明

- `token`: Coze API 的访问令牌，格式为 `pat_` 开头
- `base-url`: Coze API 的基础URL，通常为 `https://api.coze.cn`
- `chat.path`: 聊天API的路径，固定为 `/v3/chat`
- `chat.talk.bot-id`: 对话聊天使用的机器人ID
- `chat.talk.workflow-id`: 对话聊天使用的工作流ID
- `chat.summary.bot-id`: 聊天记录总结使用的机器人ID
- `chat.summary.workflow-id`: 聊天记录总结使用的工作流ID
- `timeout`: API调用超时时间（毫秒）
- `retry-count`: 重试次数
- `retry-delay`: 重试延迟（毫秒）

## API 调用流程

### 1. 发送聊天消息

```java
String response = aiChatService.sendChatMessage(conversationId, message, userId);
```

### 2. 访客聊天

```java
Map<String, Object> response = aiChatService.guestChat(message, clientIp);
```

### 3. 生成对话总结

```java
String summary = aiChatService.generateConversationSummary(conversationId, userId);
```

## 实现特点

### 1. 正确的 API 调用流程

1. **发送聊天请求**: 调用 `/v3/chat` 接口发送消息
2. **获取 chat_id**: 从响应中提取 `chat_id` 和 `conversation_id`
3. **轮询状态**: 使用 `/v3/chat/retrieve` 接口轮询聊天状态
4. **获取消息**: 当状态为 `completed` 时，调用 `/v3/chat/message/list` 获取AI回复

### 2. 请求格式

```json
{
  "bot_id": "7523042446285439016",
  "workflow_id": "7523047462895796287",
  "user_id": "user-123",
  "stream": false,
  "additional_messages": [
    {
      "role": "user",
      "content": "用户消息内容",
      "content_type": "text",
      "type": "question"
    }
  ],
  "parameters": {}
}
```

### 3. 响应处理

- 解析初始响应获取 `chat_id` 和 `conversation_id`
- 轮询聊天状态直到完成（最多30秒，每2秒一次）
- 从消息列表中提取 AI 回复（role=assistant, type=answer）

### 4. 错误处理

- 网络异常处理
- API 错误响应处理
- 超时处理
- 重试机制

## 测试

运行以下命令测试 API 集成：

```bash
mvn test -Dtest=CozeApiTest
```

## 注意事项

1. **API Token**: 确保使用有效的 Coze API token
2. **Bot ID**: 确保 bot_id 和 workflow_id 正确配置
3. **网络连接**: 确保服务器能够访问 `https://api.coze.cn`
4. **超时设置**: 根据实际情况调整超时时间
5. **错误处理**: 生产环境中应该有完善的错误处理和日志记录

## 故障排除

### 1. 检查配置

```bash
# 检查配置是否正确加载
curl -X GET http://localhost:19089/api/ai/health
```

### 2. 查看日志

```bash
# 查看详细的API调用日志
tail -f logs/emotion-single.log | grep -i coze
```

### 3. 常见错误

- **401 Unauthorized**: 检查 API token 是否正确
- **404 Not Found**: 检查 bot_id 是否存在
- **Timeout**: 增加超时时间或检查网络连接
- **Rate Limit**: 检查API调用频率限制