重构项目结构：迁移到单体架构并优化代码组织

- 删除分布式架构相关文件和配置 - 将backend-distributed重命名为backend保留分布式代码作为参考 - 优化backend-single单体架构实现 - 添加Coze API集成相关文档和测试 - 清理项目根目录的部署脚本和配置文件 - 更新WebSocket和消息服务实现 - 完善认证服务和密码加密功能
2025-07-24 22:16:27 +08:00
parent 847f5126cf
commit ca42a7d9a4
308 changed files with 1263 additions and 13496 deletions
@@ -0,0 +1,139 @@
+# 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. **监控指标**: 添加详细的监控和告警机制