Files

scottpan 14d29d51c0 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

16 KiB

Raw Blame History

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	图片/语音上传

二、认证说明

所有接口（除特殊标注外）均需要登录认证：

# 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: 男性透析患者计算

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
}'

预期响应

{
  "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: 女性非透析患者计算

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: 参数校验-年龄超出范围

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: 获取计算结果

curl -X GET 'http://localhost:20822/api/front/tool/calculator/result/100234' \
-H "Authori-zation: YOUR_TOKEN"

TC-CALC-05: 查询不存在的结果

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: 采纳营养计划

curl -X POST 'http://localhost:20822/api/front/tool/calculator/adopt' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
  "resultId": 100234
}'

预期响应

{
  "code": 200,
  "message": "success",
  "data": {
    "planId": 56789,
    "startDate": "2026-02-08",
    "endDate": "2026-02-14"
  }
}

TC-CALC-07: 重复采纳（幂等测试）

# 同一 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: 发送消息

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: 获取回复

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: 获取对话历史

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: 清空对话

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: 提交打卡

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: 获取打卡列表

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 获取打卡记录详情

curl -X GET 'http://localhost:20822/api/front/tool/checkin/detail/123' \
-H "Authori-zation: YOUR_TOKEN"

5.4 获取连续打卡统计

curl -X GET 'http://localhost:20822/api/front/tool/checkin/streak' \
-H "Authori-zation: YOUR_TOKEN"

5.5 获取打卡日历数据

curl -X GET 'http://localhost:20822/api/front/tool/checkin/calendar?yearMonth=2026-02' \
-H "Authori-zation: YOUR_TOKEN"

5.6 获取打卡任务列表

curl -X GET 'http://localhost:20822/api/front/tool/checkin/tasks' \
-H "Authori-zation: YOUR_TOKEN"

5.7 一键复制打卡

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 一键借鉴打卡

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 搜索食物

curl -X GET 'http://localhost:20822/api/front/tool/food/search?keyword=鸡蛋&category=蛋类&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"

6.2 获取食物列表

curl -X GET 'http://localhost:20822/api/front/tool/food/list?category=肉类&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"

6.3 获取食物详情

curl -X GET 'http://localhost:20822/api/front/tool/food/detail/100' \
-H "Authori-zation: YOUR_TOKEN"

6.4 获取相似食物推荐

curl -X GET 'http://localhost:20822/api/front/tool/food/similar/100' \
-H "Authori-zation: YOUR_TOKEN"

七、营养知识

7.1 获取营养知识列表

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 获取营养知识详情

curl -X GET 'http://localhost:20822/api/front/tool/knowledge/detail/50' \
-H "Authori-zation: YOUR_TOKEN"

7.3 获取营养素详情

curl -X GET 'http://localhost:20822/api/front/tool/knowledge/nutrient/蛋白质' \
-H "Authori-zation: YOUR_TOKEN"

八、打卡社区

8.1 获取社区内容列表

curl -X GET 'http://localhost:20822/api/front/tool/community/list?tab=recommend&page=1&limit=10' \
-H "Authori-zation: YOUR_TOKEN"

8.2 获取社区内容详情

curl -X GET 'http://localhost:20822/api/front/tool/community/detail/200' \
-H "Authori-zation: YOUR_TOKEN"

8.3 发布社区内容

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 点赞/取消点赞

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 收藏/取消收藏

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 发表评论

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 获取评论列表

curl -X GET 'http://localhost:20822/api/front/tool/community/comment/list/200?page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"

8.8 关注/取消关注用户

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 分享内容

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 获取用户积分信息

curl -X GET 'http://localhost:20822/api/front/tool/points/info' \
-H "Authori-zation: YOUR_TOKEN"

9.2 获取积分规则

curl -X GET 'http://localhost:20822/api/front/tool/points/rules' \
-H "Authori-zation: YOUR_TOKEN"

9.3 获取积分流水

curl -X GET 'http://localhost:20822/api/front/tool/points/history?type=earn&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"

9.4 获取积分兑换列表

curl -X GET 'http://localhost:20822/api/front/tool/points/exchange/list' \
-H "Authori-zation: YOUR_TOKEN"

9.5 积分兑换

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 获取首页数据

curl -X GET 'http://localhost:20822/api/front/tool/home/data' \
-H "Authori-zation: YOUR_TOKEN"

10.2 获取推荐食谱列表

curl -X GET 'http://localhost:20822/api/front/tool/home/recipes?limit=6' \
-H "Authori-zation: YOUR_TOKEN"

10.3 获取推荐营养知识

curl -X GET 'http://localhost:20822/api/front/tool/home/knowledge?limit=4' \
-H "Authori-zation: YOUR_TOKEN"

10.4 获取用户健康档案状态

curl -X GET 'http://localhost:20822/api/front/tool/home/health-status' \
-H "Authori-zation: YOUR_TOKEN"

十一、食谱管理

11.1 获取食谱列表

curl -X GET 'http://localhost:20822/api/front/tool/recipe/list?mealType=breakfast&page=1&limit=10' \
-H "Authori-zation: YOUR_TOKEN"

11.2 获取食谱详情

curl -X GET 'http://localhost:20822/api/front/tool/recipe/detail/50' \
-H "Authori-zation: YOUR_TOKEN"

11.3 收藏/取消收藏食谱

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 上传图片

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 上传语音

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

文档结束

16 KiB Raw Blame History Unescape Escape

Tool 模块 API 测试文档

一、接口总览

1.1 模块分类

二、认证说明

三、食谱计算器

3.1 计算营养方案

基础信息

请求参数

测试用例

TC-CALC-01: 男性透析患者计算

TC-CALC-02: 女性非透析患者计算

TC-CALC-03: 参数校验-年龄超出范围

3.2 获取计算结果详情

基础信息

测试用例

TC-CALC-04: 获取计算结果

TC-CALC-05: 查询不存在的结果

3.3 采纳营养计划

基础信息

请求参数

测试用例

TC-CALC-06: 采纳营养计划

TC-CALC-07: 重复采纳（幂等测试）

四、AI 营养师

4.1 发送消息给 AI 营养师

基础信息

测试用例

TC-AI-01: 发送消息

4.2 获取 AI 回复

基础信息

测试用例

TC-AI-02: 获取回复

4.3 获取对话历史

基础信息

请求参数

测试用例

TC-AI-03: 获取对话历史

4.4 清空对话历史

测试用例

TC-AI-04: 清空对话

五、饮食打卡

5.1 提交打卡记录

基础信息

测试用例

TC-CHECKIN-01: 提交打卡

5.2 获取打卡记录列表

请求参数

测试用例

TC-CHECKIN-02: 获取打卡列表

5.3 获取打卡记录详情

5.4 获取连续打卡统计

5.5 获取打卡日历数据

5.6 获取打卡任务列表

5.7 一键复制打卡

5.8 一键借鉴打卡

六、食物百科

6.1 搜索食物

6.2 获取食物列表

6.3 获取食物详情

6.4 获取相似食物推荐

七、营养知识

7.1 获取营养知识列表

7.2 获取营养知识详情

7.3 获取营养素详情

八、打卡社区

8.1 获取社区内容列表

8.2 获取社区内容详情

8.3 发布社区内容

8.4 点赞/取消点赞

8.5 收藏/取消收藏

8.6 发表评论

8.7 获取评论列表

8.8 关注/取消关注用户

8.9 分享内容

九、积分系统

9.1 获取用户积分信息

9.2 获取积分规则

9.3 获取积分流水

9.4 获取积分兑换列表

16 KiB

Raw Blame History