# Coze API 调用修正说明

## 修正概述

经过对比 Coze API 官方文档，发现并修正了 `AiChatServiceImpl` 中的几个关键问题。

## 主要修正内容

### 1. API 端点修正
**问题**: 使用了错误的 API 端点 `/api/message`
**修正**: 更改为正确的 Coze API v3 端点 `/v3/chat`

```java
// 修正前
String cozeApiUrl = cozeBaseUrl + "/api/message";

// 修正后  
String cozeApiUrl = cozeBaseUrl + "/v3/chat";
```

### 2. 请求体结构优化
**问题**: 请求体缺少必要字段，消息格式不完整
**修正**: 添加了 `auto_save_history` 字段，优化了消息结构

```java
// 修正后的请求体结构
{
    "bot_id": "your-bot-id",
    "workflow_id": "your-workflow-id", // 可选
    "user_id": "user-id",
    "stream": false,
    "auto_save_history": true,        // 新增
    "conversation_id": "conv-id",     // 可选
    "additional_messages": [
        {
            "role": "user",
            "content": "用户消息",
            "content_type": "text"
        }
    ]
}
```

### 3. 响应解析增强
**问题**: 响应解析逻辑可能不匹配实际的 API 响应格式
**修正**: 增强了错误处理和多种响应格式的支持

```java
// 新增错误状态检查
Integer code = responseJson.getInteger("code");
if (code != null && code != 0) {
    String msg = responseJson.getString("msg");
    return "抱歉，AI服务返回错误: " + (msg != null ? msg : "未知错误");
}
```

### 4. 健康检查简化
**问题**: 使用了可能不存在的健康检查端点
**修正**: 简化为配置验证，避免不必要的 API 调用

```java
// 修正后的健康检查
boolean configValid = cozeApiToken != null && !cozeApiToken.trim().isEmpty() &&
        chatBotId != null && !chatBotId.trim().isEmpty() &&
        cozeBaseUrl != null && !cozeBaseUrl.trim().isEmpty();
```

### 5. 代码质量改进
- 添加了常量定义，避免重复字符串
- 统一了聊天和总结请求的构建逻辑
- 改进了错误处理和日志记录

## 配置要求

### 必需配置
```yaml
emotion:
  coze:
    api:
      token: "your-coze-api-token"     # 必需
      base-url: "https://api.coze.cn"  # 必需
      chat:
        talk:
          bot-id: "your-bot-id"        # 必需
```

### 可选配置
```yaml
emotion:
  coze:
    api:
      chat:
        talk:
          workflow-id: "workflow-id"   # 可选
        summary:
          bot-id: "summary-bot-id"     # 可选
          workflow-id: "summary-workflow-id" # 可选
```

## 测试验证

已创建测试类 `AiChatServiceImplTest` 来验证修正的正确性：

1. **API 调用测试**: 验证请求格式和端点
2. **响应解析测试**: 验证正常和错误响应的处理
3. **配置验证测试**: 验证健康检查和服务可用性

## 使用建议

### 1. 配置验证
在启动应用前，确保以下配置正确：
- Coze API token 有效
- Bot ID 正确且已发布到 API
- 网络可以访问 api.coze.cn

### 2. 错误处理
修正后的代码会返回更详细的错误信息：
- API 错误会包含具体的错误码和消息
- 网络错误会有相应的提示
- 配置错误会在健康检查中发现

### 3. 监控建议
- 监控 API 调用的成功率
- 记录响应时间和错误率
- 定期检查 token 的有效性

## 兼容性说明

- 修正后的代码与 Coze API v3 兼容
- 保持了原有的接口签名，不影响调用方
- 增强了错误处理，提高了系统稳定性

## 后续优化建议

1. **流式响应支持**: 实现真正的流式聊天功能
2. **对话历史管理**: 完善对话历史的获取和管理
3. **缓存机制**: 添加适当的缓存来提高性能
4. **限流保护**: 添加 API 调用频率限制
5. **监控指标**: 添加详细的监控和告警机制