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: 产品文档与设计稿
This commit is contained in:
542
docs/Testing/Coze-API测试文档.md
Normal file
542
docs/Testing/Coze-API测试文档.md
Normal file
@@ -0,0 +1,542 @@
|
||||
# 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 | 初稿 |
|
||||
|
||||
---
|
||||
|
||||
*文档结束*
|
||||
808
docs/Testing/Tool模块-API测试文档.md
Normal file
808
docs/Testing/Tool模块-API测试文档.md
Normal file
@@ -0,0 +1,808 @@
|
||||
# Tool 模块 API 测试文档
|
||||
|
||||
> **版本**：v1.0
|
||||
> **创建日期**：2026-02-08
|
||||
> **基础路径**：`/api/front/tool`
|
||||
> **服务端口**：20822
|
||||
> **认证方式**：需登录（Header: `Authori-zation`）
|
||||
|
||||
---
|
||||
|
||||
## 一、接口总览
|
||||
|
||||
### 1.1 模块分类
|
||||
|
||||
| 模块 | 接口数量 | 说明 |
|
||||
|------|----------|------|
|
||||
| 食谱计算器 | 3 | 营养方案计算与采纳 |
|
||||
| AI营养师 | 4 | AI 对话问答 |
|
||||
| 饮食打卡 | 8 | 打卡记录管理 |
|
||||
| 食物百科 | 4 | 食物查询 |
|
||||
| 营养知识 | 3 | 知识库查询 |
|
||||
| 打卡社区 | 9 | 社区互动 |
|
||||
| 积分系统 | 5 | 积分管理 |
|
||||
| 首页数据 | 4 | 首页聚合数据 |
|
||||
| 食谱管理 | 3 | 食谱收藏 |
|
||||
| 文件上传 | 2 | 图片/语音上传 |
|
||||
|
||||
---
|
||||
|
||||
## 二、认证说明
|
||||
|
||||
所有接口（除特殊标注外）均需要登录认证：
|
||||
|
||||
```bash
|
||||
# Header 示例
|
||||
-H "Authori-zation: eyJhbGciOiJIUzI1NiJ9.xxxxx"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、食谱计算器
|
||||
|
||||
### 3.1 计算营养方案
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `POST /api/front/tool/calculator/calculate` |
|
||||
| Content-Type | `application/json` |
|
||||
| 是否鉴权 | **是** |
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|--------|------|------|------|----------|
|
||||
| `gender` | String | 是 | 性别 | `male` / `female` |
|
||||
| `age` | Integer | 是 | 年龄（岁） | 1 ≤ age ≤ 150 |
|
||||
| `height` | Integer | 是 | 身高（cm） | 50 ≤ height ≤ 250 |
|
||||
| `dialysis` | Boolean | 是 | 是否透析 | true / false |
|
||||
| `dialysisType` | String | 否 | 透析类型 | `hemodialysis` / `peritoneal` |
|
||||
| `dryWeight` | Number | 是 | 干体重（kg） | 20 ≤ dryWeight ≤ 300 |
|
||||
| `creatinine` | Number | 是 | 血肌酐（μmol/L） | 0 < creatinine ≤ 2000 |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-CALC-01: 男性透析患者计算
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"gender": "male",
|
||||
"age": 55,
|
||||
"height": 170,
|
||||
"dialysis": true,
|
||||
"dialysisType": "hemodialysis",
|
||||
"dryWeight": 65.5,
|
||||
"creatinine": 850
|
||||
}'
|
||||
```
|
||||
|
||||
**预期响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 100234,
|
||||
"healthData": {
|
||||
"eGFR": "7.9",
|
||||
"standardWeight": "63.0",
|
||||
"bmi": "22.7",
|
||||
"bmiStatus": "正常",
|
||||
"ckdStage": "透析期"
|
||||
},
|
||||
"nutritionGoals": {
|
||||
"protein": "75.6",
|
||||
"energy": "2205"
|
||||
},
|
||||
"foodList": [
|
||||
{ "number": 1, "name": "谷薯50g", "portion": "5.7" },
|
||||
{ "number": 2, "name": "淀粉100g", "portion": "0.77" },
|
||||
{ "number": 3, "name": "绿叶蔬菜200g", "portion": "1" },
|
||||
{ "number": 4, "name": "瓜果蔬菜200g", "portion": "2" },
|
||||
{ "number": 5, "name": "奶类230g", "portion": "1" },
|
||||
{ "number": 6, "name": "肉蛋类50/60g", "portion": "7" },
|
||||
{ "number": 7, "name": "油脂类10g", "portion": "5.7" }
|
||||
],
|
||||
"mealPlan": {
|
||||
"breakfast": [...],
|
||||
"lunch": [...],
|
||||
"dinner": [...]
|
||||
},
|
||||
"importantTips": [
|
||||
"以上配餐由 AI 生成，仅适用于无其他并发症的单纯尿毒症人群",
|
||||
"透析患者需严格控制水分摄入"
|
||||
],
|
||||
"createdAt": "2026-02-08T10:30:00+08:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### TC-CALC-02: 女性非透析患者计算
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"gender": "female",
|
||||
"age": 48,
|
||||
"height": 160,
|
||||
"dialysis": false,
|
||||
"dryWeight": 52,
|
||||
"creatinine": 180
|
||||
}'
|
||||
```
|
||||
|
||||
##### TC-CALC-03: 参数校验-年龄超出范围
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"gender": "male",
|
||||
"age": 200,
|
||||
"height": 170,
|
||||
"dialysis": false,
|
||||
"dryWeight": 65,
|
||||
"creatinine": 100
|
||||
}'
|
||||
```
|
||||
|
||||
**预期响应**：`code=400, message 包含"年龄"`
|
||||
|
||||
---
|
||||
|
||||
### 3.2 获取计算结果详情
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `GET /api/front/tool/calculator/result/{id}` |
|
||||
| 是否鉴权 | **是** |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-CALC-04: 获取计算结果
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/calculator/result/100234' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
##### TC-CALC-05: 查询不存在的结果
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/calculator/result/999999' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
**预期响应**：`code=404`
|
||||
|
||||
---
|
||||
|
||||
### 3.3 采纳营养计划
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `POST /api/front/tool/calculator/adopt` |
|
||||
| Content-Type | `application/json` |
|
||||
| 是否鉴权 | **是** |
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `resultId` | Long | 是 | 计算结果 ID |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-CALC-06: 采纳营养计划
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/calculator/adopt' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"resultId": 100234
|
||||
}'
|
||||
```
|
||||
|
||||
**预期响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"planId": 56789,
|
||||
"startDate": "2026-02-08",
|
||||
"endDate": "2026-02-14"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### TC-CALC-07: 重复采纳（幂等测试）
|
||||
|
||||
```bash
|
||||
# 同一 resultId 调用两次
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/calculator/adopt' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{"resultId": 100234}'
|
||||
```
|
||||
|
||||
**预期响应**：返回已存在的 planId
|
||||
|
||||
---
|
||||
|
||||
## 四、AI 营养师
|
||||
|
||||
### 4.1 发送消息给 AI 营养师
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `POST /api/front/tool/ai-nutritionist/message` |
|
||||
| Content-Type | `application/json` |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-AI-01: 发送消息
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/ai-nutritionist/message' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"conversationId": "conv_001",
|
||||
"content": "肾病患者可以吃香蕉吗？"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 获取 AI 回复
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `GET /api/front/tool/ai-nutritionist/response/{messageId}` |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-AI-02: 获取回复
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/ai-nutritionist/response/12345' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 获取对话历史
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `GET /api/front/tool/ai-nutritionist/history` |
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `page` | Integer | 否 | 页码，默认 1 |
|
||||
| `limit` | Integer | 否 | 每页数量，默认 20 |
|
||||
| `conversationId` | Long | 否 | 对话 ID |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-AI-03: 获取对话历史
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/ai-nutritionist/history?page=1&limit=20' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 清空对话历史
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-AI-04: 清空对话
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/ai-nutritionist/clear' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"conversationId": "conv_001"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、饮食打卡
|
||||
|
||||
### 5.1 提交打卡记录
|
||||
|
||||
#### 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|------|
|
||||
| 请求路径 | `POST /api/front/tool/checkin/submit` |
|
||||
| Content-Type | `application/json` |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-CHECKIN-01: 提交打卡
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/checkin/submit' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"mealType": "breakfast",
|
||||
"date": "2026-02-08",
|
||||
"foods": [
|
||||
{"name": "牛奶", "amount": "250ml"},
|
||||
{"name": "全麦面包", "amount": "2片"}
|
||||
],
|
||||
"images": ["https://cdn.xxx.com/img1.jpg"],
|
||||
"remark": "早餐清淡"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 获取打卡记录列表
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `page` | Integer | 否 | 页码 |
|
||||
| `limit` | Integer | 否 | 每页数量 |
|
||||
| `date` | String | 否 | 日期筛选 YYYY-MM-DD |
|
||||
| `mealType` | String | 否 | 餐次：breakfast/lunch/dinner |
|
||||
|
||||
#### 测试用例
|
||||
|
||||
##### TC-CHECKIN-02: 获取打卡列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/checkin/list?page=1&limit=10&date=2026-02-08' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.3 获取打卡记录详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/checkin/detail/123' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.4 获取连续打卡统计
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/checkin/streak' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.5 获取打卡日历数据
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/checkin/calendar?yearMonth=2026-02' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.6 获取打卡任务列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/checkin/tasks' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.7 一键复制打卡
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/checkin/copy' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"sourceRecordId": 12345,
|
||||
"targetDate": "2026-02-08",
|
||||
"mealType": "lunch"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.8 一键借鉴打卡
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/checkin/learn' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"sourcePostId": 67890,
|
||||
"targetDate": "2026-02-08",
|
||||
"mealType": "dinner"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、食物百科
|
||||
|
||||
### 6.1 搜索食物
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/food/search?keyword=鸡蛋&category=蛋类&page=1&limit=20' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.2 获取食物列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/food/list?category=肉类&page=1&limit=20' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.3 获取食物详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/food/detail/100' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.4 获取相似食物推荐
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/food/similar/100' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、营养知识
|
||||
|
||||
### 7.1 获取营养知识列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/list?type=article&category=肾病饮食&page=1&limit=10' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7.2 获取营养知识详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/detail/50' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7.3 获取营养素详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/nutrient/蛋白质' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、打卡社区
|
||||
|
||||
### 8.1 获取社区内容列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/community/list?tab=recommend&page=1&limit=10' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.2 获取社区内容详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/community/detail/200' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.3 发布社区内容
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/publish' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"content": "今天的早餐很健康！",
|
||||
"images": ["https://cdn.xxx.com/img1.jpg"],
|
||||
"checkinId": 12345
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.4 点赞/取消点赞
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/like' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"postId": 200,
|
||||
"isLike": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.5 收藏/取消收藏
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/collect' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"postId": 200,
|
||||
"isCollect": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.6 发表评论
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/comment' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"postId": 200,
|
||||
"content": "看起来很不错！",
|
||||
"parentId": null
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.7 获取评论列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/community/comment/list/200?page=1&limit=20' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.8 关注/取消关注用户
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/follow' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"userId": 1001,
|
||||
"isFollow": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.9 分享内容
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/community/share' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"postId": 200
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、积分系统
|
||||
|
||||
### 9.1 获取用户积分信息
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/points/info' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9.2 获取积分规则
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/points/rules' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9.3 获取积分流水
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/points/history?type=earn&page=1&limit=20' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9.4 获取积分兑换列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/points/exchange/list' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9.5 积分兑换
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/points/exchange' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"exchangeId": 10
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、首页数据
|
||||
|
||||
### 10.1 获取首页数据
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/home/data' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10.2 获取推荐食谱列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/home/recipes?limit=6' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10.3 获取推荐营养知识
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/home/knowledge?limit=4' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10.4 获取用户健康档案状态
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/home/health-status' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、食谱管理
|
||||
|
||||
### 11.1 获取食谱列表
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/recipe/list?mealType=breakfast&page=1&limit=10' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11.2 获取食谱详情
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:20822/api/front/tool/recipe/detail/50' \
|
||||
-H "Authori-zation: YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11.3 收藏/取消收藏食谱
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/recipe/favorite' \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-d '{
|
||||
"recipeId": 50,
|
||||
"isFavorite": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十二、文件上传
|
||||
|
||||
### 12.1 上传图片
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/upload/image?type=checkin' \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-F "file=@/path/to/image.jpg"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 12.2 上传语音
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://localhost:20822/api/front/tool/upload/voice' \
|
||||
-H "Authori-zation: YOUR_TOKEN" \
|
||||
-F "file=@/path/to/voice.mp3"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十三、错误码说明
|
||||
|
||||
| code | message | 说明 |
|
||||
|------|---------|------|
|
||||
| 200 | success | 请求成功 |
|
||||
| 400 | 参数校验失败 | 请求参数不符合校验规则 |
|
||||
| 401 / 410000 | 未登录 | Token 缺失 |
|
||||
| 410001 | Token 无效 | Token 格式错误 |
|
||||
| 410002 | 登录过期 | Token 已过期 |
|
||||
| 403 | 无权限 | 访问他人数据 |
|
||||
| 404 | 资源不存在 | 数据不存在 |
|
||||
| 500 | 系统异常 | 服务端内部错误 |
|
||||
|
||||
---
|
||||
|
||||
## 十四、变更记录
|
||||
|
||||
| 版本 | 日期 | 作者 | 变更内容 |
|
||||
|------|------|------|----------|
|
||||
| v1.0 | 2026-02-08 | System | 初稿 |
|
||||
|
||||
---
|
||||
|
||||
*文档结束*
|
||||
Reference in New Issue
Block a user