yl-frontend/api-docs/diet-api.txt

膳食管理模块接口文档
================

基础信息
-------
- 基础路径: /api/v1/diet
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

Meal 膳食对象:
{
  id: number,          // 膳食ID
  time: string,        // 用餐时间
  name: string,        // 膳食名称
  description: string, // 描述
  calories: number,    // 热量(kcal)
  nutrition: {
    protein: number,   // 蛋白质(g)
    carbs: number,     // 碳水化合物(g)
    fat: number        // 脂肪(g)
  },
  status: string,      // 状态(pending/current/done)
  ingredients: [       // 食材列表
    {
      name: string,    // 食材名称
      amount: string   // 用量
    }
  ]
}

NutritionReport 营养报告:
{
  dailyCalories: number,  // 每日热量
  nutrition: {
    protein: number,      // 蛋白质(g)
    carbs: number,        // 碳水化合物(g)
    fat: number          // 脂肪(g)
  },
  suggestions: string[],  // 建议列表
  status: string         // 状态(good/warning/bad)
}

API 接口
-------

1. 获取今日膳食
GET /api/v1/diet/meals/today

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "time": "08:00",
      "name": "营养早餐",
      "description": "牛奶燕麦粥配鸡蛋",
      "calories": 300,
      "nutrition": {
        "protein": 15,
        "carbs": 40,
        "fat": 10
      },
      "status": "done",
      "ingredients": [
        { "name": "燕麦", "amount": "50g" },
        { "name": "牛奶", "amount": "200ml" },
        { "name": "鸡蛋", "amount": "1个" }
      ]
    }
  ]
}

2. 获取营养报告
GET /api/v1/diet/nutrition/report

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "dailyCalories": 1800,
    "nutrition": {
      "protein": 80,
      "carbs": 250,
      "fat": 60
    },
    "suggestions": [
      "可以适当增加优质蛋白的摄入",
      "建议多补充维生素C",
      "注意补充水分"
    ],
    "status": "good"
  }
}

3. 更新用餐状态
PUT /api/v1/diet/meals/{id}/status

请求参数：
{
  "status": "done"  // pending/current/done
}

响应示例：
{
  "code": 200,
  "message": "success"
}

4. 获取膳食计划
GET /api/v1/diet/plans/{date}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "date": "2024-03-20",
    "meals": [],
    "totalCalories": 1800,
    "preferences": ["清淡", "少油"],
    "allergies": ["海鲜"]
  }
}

5. 创建膳食计划
POST /api/v1/diet/plans

请求参数：
{
  "date": "2024-03-21",
  "meals": [],
  "preferences": ["清淡", "少油"],
  "allergies": ["海鲜"]
}

6. 调整膳食
PUT /api/v1/diet/meals/{id}

请求参数：
{
  "name": "新的膳食名称",
  "calories": 350,
  "ingredients": []
}

7. 获取推荐食谱
GET /api/v1/diet/recipes/recommended

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "清蒸鲈鱼",
      "calories": 200,
      "suitable": ["高蛋白", "低脂肪"]
    }
  ]
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 资源不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 日期格式统一使用：YYYY-MM-DD
2. 时间格式统一使用：HH:mm
3. 营养成分单位：
   - 热量：kcal
   - 蛋白质/碳水/脂肪：g
4. 食材用量支持的单位：
   - 重量：g、kg
   - 体积：ml、L
   - 个数：个、只、份
5. 接口调用频率限制：
   - 获取数据接口：10次/分钟
   - 更新数据接口：5次/分钟
6. 数据缓存策略：
   - 今日膳食：5分钟
   - 营养报告：10分钟
   - 推荐食谱：1小时