设备端阶段营养报告接口文档

生成日期：2026-06-16；目标项目：zhctproject/ai_api；接口分类：设备端 / AI运动营养师 / 阶段营养报告

请求方式POST/terminal/analysis.weekNew/weekNew

认证方式不需要 token；人员标识 uuid 放在 Body

响应格式{ "code": 0, "message": "success", "data": {...} }

成功码code = 0

一、接口说明

该接口供设备端按人员 UUID 查询指定日期范围内的阶段营养报告。响应体 data 的业务结构与用户端接口 /api/analysis.weekNew/weekNew 返回体中的 data 保持一致。

接口不要求传 token，只通过 body 中的人员 UUID 与日期范围查询报告数据。人员 UUID 与日期字段同级放在 body 中。

二、请求契约

请求地址

POST /terminal/analysis.weekNew/weekNew

Header

字段	必填	说明	示例
`Content-Type`	是	请求体格式。	`application/json`

Body

字段	类型	必填	说明	示例
`uuid`	string	是	智慧餐厅人员 UUID，用于定位 AI 运动营养师人员。	`staff-uuid-demo`
`start_date`	string	是	查询开始日期，格式 `YYYY-MM-DD`。	`2026-06-15`
`end_date`	string	是	查询结束日期，格式 `YYYY-MM-DD`。	`2026-06-21`

请求示例

{
  "uuid": "staff-uuid-demo",
  "start_date": "2026-06-15",
  "end_date": "2026-06-21"
}

三、响应契约

字段	类型	说明
`code`	integer	设备端统一业务码。成功返回 `0`。
`message`	string	提示信息。成功返回 `success`。
`data`	object	阶段营养报告数据，与用户端接口返回体的 `data` 结构一致。

成功响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "repast": {
      "repast": {
        "morning": 1,
        "noon": 1,
        "night": 0,
        "extra": 0
      },
      "hint": "想要提醒你的是注重早餐摄入和必要的加餐。缺餐会导致当天能量摄入不足!"
    },
    "dietary_habit": {
      "hun_su_zhou": {
        "西红柿炒鸡蛋0001": {
          "num": 1,
          "name": "西红柿炒鸡蛋0001",
          "category_two": 7,
          "file_path": "",
          "dishes_id": 4901
        }
      },
      "staple_fruits": {
        "山西到喜爱面": {
          "num": 1,
          "name": "山西到喜爱面",
          "category_two": 4,
          "file_path": "",
          "dishes_id": 4902
        }
      },
      "cook_method": {
        "煮": "green",
        "炒": "green"
      },
      "ratio": 100
    },
    "meal_construction": {
      "ingredient_num": 10,
      "ratio": 99,
      "msg": "棒棒哒！"
    },
    "pyramid": {
      "坚果": {
        "intake_num": 0,
        "message": "坚果摄入次数偏少，距离推荐还差5次，建议增加摄入",
        "color": "rgba(238, 102, 88, 1)"
      },
      "蛋制品": {
        "intake_num": 1,
        "message": "您一周仅摄入1次蛋，次数严重偏低，<span style='color: rgba(238, 102, 88, 1)'>建议保证一天一个蛋</span>",
        "color": "transparent transparent rgba(238, 102, 88, 1) rgba(238, 102, 88, 1)"
      }
    },
    "diff_time": 22
  }
}

四、data 字段说明

字段	类型	说明
`repast`	object	就餐情况，包含早/中/晚/加餐次数与提醒文案。
`dietary_habit`	object	饮食喜好，包含荤素汤、主食水果、烹调方式和推荐烹调方式占比。
`meal_construction`	object	膳食结构，包含食材数量、排名比例和提示语。
`pyramid`	object	膳食宝塔摄入情况，按坚果、奶制品、豆制品、畜禽水产、蛋制品、蔬菜、水果、谷物、薯类/全谷物分组。
`diff_time`	integer	人员创建时间到查询结束日期的周数差。

五、异常响应

场景	响应示例	说明
缺少 `uuid/start_date/end_date`	`{ "code": 400, "message": "缺少必要参数", "data": [] }`	三个 body 字段任意缺失或为空时返回。
人员不存在或未绑定 AI 用户	`{ "code": 500, "message": "人员不存在", "data": [] }`	无法通过智慧餐厅人员 UUID 映射到 AI 运动营养师人员时返回。

六、测试矩阵

用例	请求数据	期望结果
成功查询	合法 `uuid` + 合法日期范围	`code=0`，`data` 包含阶段报告五个一级字段。
缺少人员 UUID	不传 `uuid`	`code=400`，提示缺少必要参数。
缺少日期	不传 `start_date` 或 `end_date`	`code=400`，提示缺少必要参数。
人员未绑定	传不存在或未绑定 AI 用户的 `uuid`	返回错误码，`message=人员不存在`。
空报告数据	人员合法但日期范围内无就餐记录	`code=0`，各业务模块返回空数组或 0 值结构。

当前接口只读取报告数据，不写入订单、消费、设备控制或支付数据。若后续需要把该接口纳入 Apifox 自动化测试，应使用测试环境人员 UUID，避免读取生产敏感人员数据。