msh-system/models-integration/docs/coze-integration-prd.md

# Coze API Java 集成产品需求文档 (PRD)
扣子团队版

## 1. 产品概述

### 1.1 产品背景
Coze (扣子) 是一个强大的 AI Agent 开发平台，支持用户快速构建基于大语言模型的各类 Bot 和 Workflow。为了将 Coze 平台构建的智能体能力接入到我们的 Java 后端系统中，实现业务流程自动化和智能对话功能，本项目计划集成 Coze Open API。

### 1.2 产品定位
为内部系统和第三方应用提供统一的 Coze 能力接入网关，屏蔽底层 API 细节，提供标准化的 Java 接口和 RESTful API，支持对话（Chat）、工作流（Workflow）和文件上传等核心功能。

### 1.3 目标用户
- 内部业务系统开发团队
- 需要接入 AI 客服/助手的前端应用
- 自动化任务流程设计者

## 2. 核心功能需求

### 2.1 功能模块概览
| 功能模块 | 描述 | 优先级 | 备注 |
|---------|------|--------|------|
| 鉴权管理 (Auth) | 支持 PAT (个人访问令牌) 和 OAuth JWT 两种模式 | P0 | 初期使用 PAT 快速接入 |
| 智能对话 (Chat) | 与 Coze Bot 进行多轮对话，支持流式 (SSE) / 非流式响应 | P0 | 核心交互能力 |
| 工作流执行 (Workflow) | 调用 Coze 定义的工作流，处理复杂业务逻辑 | P0 | 业务自动化 |
| 文件上传 (File) | 上传图片或文档，用于多模态对话或工作流输入 | P1 | 支持多模态 |
| 语音交互 (Voice) | 文本转语音 (TTS) / 语音转文本 (ASR) | P2 | 依赖 SDK WebSocket 能力 |

### 2.2 API 接口设计

#### 2.2.1 鉴权管理
支持两种鉴权方式，通过配置文件切换：
1.  **PAT (Personal Access Token)**: 适用于内部系统后台调用，长期有效。
2.  **OAuth JWT**: 适用于需要代表不同用户身份调用的场景（高阶需求）。

*参考文档*: [OAuth JWT 授权](https://www.coze.cn/open/docs/developer_guides/oauth_jwt)

#### 2.2.2 智能对话 (Chat)
支持与指定 Bot 进行交互。
- **非流式**: 等待完整回复后返回。
- **流式 (Streaming)**: 使用 Server-Sent Events (SSE) 实时推送 Token，提升用户体验。

**接口地址**: `POST /chat`

**请求参数**:
```json
{
    "bot_id": "730454116184516****", // Coze Bot ID
    "user_id": "user_123",           // 业务系统用户ID
    "query": "帮我写一个 Java 冒泡排序", // 用户输入
    "stream": true,                  // true: 返回 SSE 流; false: 返回 JSON
    "chat_history": [                // (可选) 历史上下文
        {"role": "user", "content": "你好", "content_type": "text"},
        {"role": "assistant", "content": "你好！", "content_type": "text"}
    ]
}
```

**响应示例 (非流式)**:
```json
{
    "code": 200,
    "data": {
        "conversation_id": "737999610479815****",
        "messages": [
            {
                "role": "assistant",
                "type": "answer",
                "content": "当然，这是 Java 冒泡排序的代码...",
                "content_type": "text"
            }
        ],
        "usage": {
            "token_count": 150
        }
    }
}
```

**响应示例 (流式)**:
Content-Type: `text/event-stream`
```
data: {"event":"message", "content":"当然", "is_finish":false}
data: {"event":"message", "content":"，", "is_finish":false}
...
data: {"event":"done", "usage":{...}}
```

#### 2.2.3 工作流执行 (Workflow)
触发 Coze 预定义的工作流。

**接口地址**: `POST /workflow/run`

**请求参数**:
```json
{
    "workflow_id": "73505836754923****",
    "parameters": {
        "input_text": "分析文本",
        "input_image": "https://example.com/img.jpg"
    }
}
```

#### 2.2.4 文件上传
上传文件到 Coze 平台，获取 file_id。

**接口地址**: `POST /file/upload`
**Content-Type**: `multipart/form-data`

**请求参数**:
- `file`: (Binary) 文件内容

## 3. 技术实现规范

### 3.1 项目结构
在 `com.integration.api` 包下扩展 Coze 相关模块：

```
models-integration/
├── src/main/java/com/integration/api/
│   ├── config/
│   │   └── CozeConfig.java           # Coze Client Bean 配置
│   ├── controller/
│   │   └── CozeController.java       # 对外 API 接口 (REST)
│   ├── service/
│   │   ├── CozeService.java          # 业务逻辑接口
│   │   └── impl/
│   │       └── CozeServiceImpl.java  # 调用 Coze SDK 实现
│   ├── dto/
│   │   ├── coze/
│   │       ├── CozeChatRequest.java  # 请求 DTO
│   │       └── CozeBaseResponse.java # 统一响应 DTO
│   └── utils/
│       └── SseEmitterUtil.java       # SSE 推送工具类
```

### 3.2 依赖管理
使用 Coze 官方 Java SDK。

```xml
<dependency>
    <groupId>com.coze</groupId>
    <artifactId>coze-api</artifactId>
    <version>0.4.2</version> <!-- 请检查 Maven Central 获取最新版本 -->
</dependency>
```

### 3.3 配置文件
在 `application.yml` 中配置：

```yaml
coze:
  api:
    base-url: https://api.coze.cn
    token: ${COZE_API_TOKEN}       # 优先使用环境变量
    connect-timeout: 30000
    read-timeout: 60000
```

### 3.4 异常处理
需捕获 SDK 抛出的异常并转换为标准 HTTP 响应：
- `CozeClientException`: 客户端错误 (配置、网络) -> 500
- `CozeServiceException`: 服务端错误 (参数、权限) -> 400/401/429
    - **401**: Token 无效
    - **429**: Rate Limit Exceeded (需实现重试机制)

## 4. 非功能需求

### 4.1 安全性
- Token 不得提交到代码仓库。
- 生产环境建议使用 OAuth JWT 模式以获得更细粒度的权限控制。

### 4.2 性能与稳定性
- **连接池**: 使用 OkHttp 连接池复用连接。
- **流式响应**: Chat 接口必须支持 SSE，避免长轮询等待。
- **超时控制**: 明确设置 ReadTimeout，防止请求挂起。

### 4.3 可观测性
- 记录每次调用的 `conversation_id` 和 `log_id` (SDK 返回)，便于排查问题。
- 监控 Token 消耗量 (Usage)。

## 5. 项目里程碑

### 5.1 第一阶段 (MVP)
- [ ] 引入 Coze SDK (v0.4.2+)。
- [ ] 接入 OAuth JWT 授权流程
- [ ] 实现文件上传接口。
- [ ] 实现 Workflow 接口。
- [ ] 实现基础 Chat 接口 (非流式)。
- [ ] 实现 SSE 流式 Chat 接口。

## 6. 验收标准
1.  Chat 接口能正确响应 Bot 回复。
2.  Workflow 能执行并返回 JSON 结果。
3.  流式请求能通过 SSE 逐步输出内容。
4.  异常情况下能返回友好的错误信息，不暴露堆栈。