scottpan/msh-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
msh-system/docs/Testing/Coze-API测试文档.md

543 lines
12 KiB
Markdown
Raw Permalink Normal View History

Initial commit: MSH System\n\n- msh_single_uniapp: Vue 2 + UniApp 前端（微信小程序/H5/App/支付宝小程序）\n- msh_crmeb_22: Spring Boot 2.2 后端（C端API/管理端/业务逻辑）\n- models-integration: AI服务集成（Coze/KieAI/腾讯ASR）\n- docs: 产品文档与设计稿
2026-02-28 05:40:21 +08:00
# Coze API 测试文档
> **版本**：v1.0
> **创建日期**：2026-02-08
> **基础路径**：`/api/front/coze`
> **服务端口**：20822
> **认证方式**：免登录（已加入白名单）
---
## 一、配置信息
### 1.1 当前环境配置
| 配置项 | 值 | 说明 |
|--------|-----|------|
| Base URL | `https://api.coze.cn` | Coze 平台 API 地址 |
| Auth Type | `pat` | Personal Access Token 模式 |
| Default Bot ID | `7591133240535449654` | 食谱计算器 Bot |
| Default User ID | `3243981400446844` | 测试用户 ID |
---
## 二、接口清单
| 序号 | 接口名称 | HTTP方法 | 路径 | 说明 |
|------|----------|----------|------|------|
| 1 | 发起对话 | `POST` | `/chat` | 与 Coze Bot 对话（支持流式/非流式） |
| 2 | 流式对话 | `POST` | `/chat/stream` | SSE 流式对话 |
| 3 | 执行工作流 | `POST` | `/workflow/run` | 触发预定义工作流 |
| 4 | 流式执行工作流 | `POST` | `/workflow/stream` | SSE 流式执行工作流 |
| 5 | 查看对话详情 | `POST` | `/chat/retrieve` | 查询对话状态 |
| 6 | 查看对话消息列表 | `POST` | `/chat/messages/list` | 获取对话消息 |
| 7 | 上传文件 | `POST` | `/file/upload` | 上传文件获取 file_id |
---
## 三、接口详细说明
### 3.1 发起对话
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat` |
| Content-Type | `application/json` |
| 是否鉴权 | **否**（白名单） |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `botId` | String | 是 | Coze Bot ID |
| `userId` | String | 是 | 业务系统用户 ID |
| `stream` | Boolean | 否 | 是否流式返回，默认 false |
| `chatHistory` | Array | 否 | 历史对话上下文 |
| `additionalMessages` | Array | 否 | 当前发送的消息 |
**chatHistory 结构**
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `role` | String | 角色：`user` / `assistant` |
| `content` | String | 消息内容 |
| `contentType` | String | 内容类型：`text` / `object_string` / `card` |
#### 测试用例
##### TC-COZE-01: 基础对话测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "你好，请介绍一下自己"
}
]
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "xxxxx",
"conversationId": "xxxxx",
"botId": "7591133240535449654",
"status": "completed",
"createdAt": 1707350400,
"completedAt": 1707350405
}
}
```
##### TC-COZE-02: 食谱计算器测试（男性透析患者）
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "3243981400446844",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L"
}
]
}'
```
##### TC-COZE-03: 食谱计算器测试（女性非透析患者）
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "3243981400446844",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "请帮我计算营养方案，我的信息如下：性别女，年龄48岁，身高160cm，未透析，体重52kg，血肌酐180μmol/L"
}
]
}'
```
##### TC-COZE-04: 带历史上下文的对话
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"stream": false,
"chatHistory": [
{
"role": "user",
"content": "我是一名55岁的男性透析患者",
"contentType": "text"
},
{
"role": "assistant",
"content": "好的，我了解了您的基本情况。请问您还有其他健康数据需要提供吗？",
"contentType": "text"
}
],
"additionalMessages": [
{
"role": "user",
"content": "我的身高是170cm，体重65.5kg，血肌酐850"
}
]
}'
```
---
### 3.2 流式对话
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |
#### 测试用例
##### TC-COZE-05: 流式对话测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"additionalMessages": [
{
"role": "user",
"content": "请详细介绍一下肾病患者的饮食注意事项"
}
]
}'
```
**预期响应（SSE 格式）**
```
event: message
data: {"event":"conversation.chat.created","chat":{"id":"xxx","conversation_id":"xxx"}}
event: message
data: {"event":"conversation.message.delta","message":{"content":"肾病患者..."}}
event: message
data: {"event":"conversation.message.delta","message":{"content":"需要注意..."}}
event: message
data: {"event":"conversation.chat.completed","chat":{"status":"completed"}}
```
---
### 3.3 执行工作流
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/run` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `workflowId` | String | 是 | 工作流 ID |
| `parameters` | Object | 否 | 工作流输入参数 |
| `isAsync` | Boolean | 否 | 是否异步执行，默认 false |
#### 测试用例
##### TC-COZE-06: 同步执行工作流
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
"workflowId": "1180790412263",
"isAsync": false,
"parameters": {
"gender": "male",
"age": 55,
"height": 170,
"dialysis": true,
"dialysisType": "hemodialysis",
"dryWeight": 65.5,
"creatinine": 850
}
}'
```
##### TC-COZE-07: 异步执行工作流
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
"workflowId": "1180790412263",
"isAsync": true,
"parameters": {
"userId": "test_user_001",
"recordId": 12345
}
}'
```
---
### 3.4 流式执行工作流
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |
#### 测试用例
##### TC-COZE-08: 流式工作流测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"workflowId": "1180790412263",
"parameters": {
"input": "分析用户的饮食记录"
}
}'
```
---
### 3.5 查看对话详情
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/retrieve` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |
#### 测试用例
##### TC-COZE-09: 查询对话详情
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/retrieve' \
-H "Content-Type: application/json" \
-d '{
"conversationId": "7460461142355574825",
"chatId": "7460461142355590000"
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "7460461142355590000",
"conversationId": "7460461142355574825",
"botId": "7591133240535449654",
"status": "completed",
"createdAt": 1707350400,
"completedAt": 1707350410,
"usage": {
"tokenCount": 1500,
"outputCount": 800,
"inputCount": 700
}
}
}
```
---
### 3.6 查看对话消息列表
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/messages/list` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |
#### 测试用例
##### TC-COZE-10: 获取对话消息列表
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/messages/list' \
-H "Content-Type: application/json" \
-d '{
"conversationId": "7460461142355574825",
"chatId": "7460461142355590000"
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": "msg_001",
"role": "user",
"type": "question",
"content": "请帮我计算营养方案",
"contentType": "text",
"createdAt": 1707350400
},
{
"id": "msg_002",
"role": "assistant",
"type": "answer",
"content": "根据您提供的信息，我为您计算了以下营养方案...",
"contentType": "text",
"createdAt": 1707350410
}
]
}
```
---
### 3.7 上传文件
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/file/upload` |
| Content-Type | `multipart/form-data` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `file` | File | 是 | 待上传的文件 |
#### 测试用例
##### TC-COZE-11: 上传图片文件
```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/image.jpg"
```
##### TC-COZE-12: 上传文档文件
```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/document.pdf"
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "file_xxxxx",
"bytes": 102400,
"createdAt": 1707350400,
"fileName": "image.jpg"
}
}
```
---
## 四、错误码说明
| code | message | 说明 |
|------|---------|------|
| 200 | success | 请求成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 认证失败（Token 无效或过期） |
| 404 | Not Found | 资源不存在 |
| 429 | Too Many Requests | 请求频率超限 |
| 500 | Internal Server Error | 服务端内部错误 |
---
## 五、常见问题
### 5.1 Token 过期
当前使用 PAT 模式，Token 有效期 30 天。如遇 401 错误，请检查配置文件中的 `coze.api.token` 是否过期。
### 5.2 Bot ID 无效
确保使用正确的 Bot ID。默认 Bot ID `7591133240535449654` 为食谱计算器专用。
### 5.3 流式接口超时
流式接口默认超时时间为 60 秒。对于长时间运行的对话，请确保客户端保持连接。
---
## 六、Postman 测试集合
可导入以下 JSON 到 Postman 进行测试：
```json
{
"info": {
"name": "Coze API Tests",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "基础对话",
"request": {
"method": "POST",
"header": [{"key": "Content-Type", "value": "application/json"}],
"body": {
"mode": "raw",
"raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"test_user_001\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"你好\"}]}"
},
"url": {"raw": "http://localhost:20822/api/front/coze/chat"}
}
},
{
"name": "食谱计算-男性透析",
"request": {
"method": "POST",
"header": [{"key": "Content-Type", "value": "application/json"}],
"body": {
"mode": "raw",
"raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"3243981400446844\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L\"}]}"
},
"url": {"raw": "http://localhost:20822/api/front/coze/chat"}
}
}
]
}
```
---
## 七、变更记录
| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-02-08 | System | 初稿 |
---
*文档结束*
Reference in New Issue Copy Permalink