msh-system/docs/Testing/Tool模块-API测试文档.md

# 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 | 初稿 |

---

*文档结束*