Dish_Recognition/docs/第三方接口文档_mgmt.md

菜品识别管理系统第三方接口文档

版本：v1.0
更新时间：2026-09-16

1. 接口地址

生产环境基础地址：

https://cpsb.ruimeida.cc/

所有接口均使用 GET 请求，不需要请求体。

2. 接口认证

接口使用独立的 API Key 认证，不使用后台用户登录账号密码。

每次请求都必须携带请求头：

X-API-Key: dish_a4f7a1287198179fdc6a6571aa14064c2afc6338c6730e2b668ac5be15bdf769

请向系统管理员获取正式 API Key，不要将 API Key 写入前端页面、公开代码仓库或日志中。

3. 获取全部基地信息

请求

GET /api/public/bases

完整地址：

https://cpsb.ruimeida.cc/api/public/bases

cURL 示例

curl -X GET "https://cpsb.ruimeida.cc/api/public/bases" \
  -H "X-API-Key: <THIRD_PARTY_API_KEY>"

返回示例

{
  "items": [
    {
      "id": 1364,
      "branchName": "安仁街分部",
      "name": "上海路基地",
      "code": "上海路基地-1788059884828-e55vu",
      "province": "",
      "city": "",
      "district": "",
      "address": "",
      "contact": "",
      "phone": "",
      "longitude": null,
      "latitude": null,
      "description": "",
      "status": 1,
      "sortOrder": 0
    }
  ]
}

字段说明

字段	类型	说明
id	number	基地 ID，可用于排餐查询的 baseId 参数
branchName	string	分部名称
name	string	基地名称，可用于排餐查询的 baseName 参数
code	string	基地编码，可用于排餐查询的 baseCode 参数
province / city / district	string	所属地区
address	string	详细地址
contact	string	联系人
phone	string	联系电话
longitude / latitude	number | null	经纬度
description	string	基地备注
status	number	1 启用，0 禁用
sortOrder	number	排序值

4. 获取当天排餐信息

请求

GET /api/public/meal-schedules/today

兼容地址：

GET /api/meal-schedules/today

接口默认返回中国时区（Asia/Shanghai）当天的数据，并包含所有基地、早餐、中餐和晚餐。

查询参数

所有查询参数均为可选：

参数	类型	说明
date	string	指定日期，格式为 YYYY-MM-DD；不传时使用中国时区当天日期
baseName	string	按基地名称精确查询，推荐使用；中文需要进行 URL 编码
baseId	number	按基地 ID 查询
baseCode	string	按基地编码精确查询

基地筛选参数只需要传一个。如果同时传多个参数，优先级为：baseId > baseCode > baseName。

调用示例

查询当天所有基地：

curl -X GET "https://cpsb.ruimeida.cc/api/public/meal-schedules/today" \
  -H "X-API-Key: <THIRD_PARTY_API_KEY>"

按基地名称查询：

curl -G "https://cpsb.ruimeida.cc/api/public/meal-schedules/today" \
  -H "X-API-Key: <THIRD_PARTY_API_KEY>" \
  --data-urlencode "baseName=上海路基地"

查询指定日期和基地：

curl -G "https://cpsb.ruimeida.cc/api/public/meal-schedules/today" \
  -H "X-API-Key: <THIRD_PARTY_API_KEY>" \
  --data-urlencode "date=2026-09-16" \
  --data-urlencode "baseName=上海路基地"

返回示例

{
  "date": "2026-09-16",
  "timezone": "Asia/Shanghai",
  "mealPeriods": [
    {
      "id": 1,
      "name": "早餐",
      "startTime": "07:00",
      "endTime": "09:00"
    },
    {
      "id": 2,
      "name": "中餐",
      "startTime": "11:30",
      "endTime": "13:30"
    },
    {
      "id": 3,
      "name": "晚餐",
      "startTime": "17:30",
      "endTime": "19:00"
    }
  ],
  "bases": [
    {
      "id": 1364,
      "code": "上海路基地-1788059884828-e55vu",
      "name": "上海路基地",
      "branchName": "安仁街分部",
      "status": 1,
      "meals": [
        {
          "mealPeriodId": 1,
          "mealPeriodName": "早餐",
          "startTime": "07:00",
          "endTime": "09:00",
          "dishes": []
        },
        {
          "mealPeriodId": 2,
          "mealPeriodName": "中餐",
          "startTime": "11:30",
          "endTime": "13:30",
          "dishes": [
            {
              "name": "米粉蒸肉",
              "price": 4,
              "learningStatus": "未学习",
              "sortOrder": 0
            }
          ]
        },
        {
          "mealPeriodId": 3,
          "mealPeriodName": "晚餐",
          "startTime": "17:30",
          "endTime": "19:00",
          "dishes": []
        }
      ]
    }
  ]
}

排餐字段说明

字段	类型	说明
date	string	查询日期
timezone	string	日期使用的时区
mealPeriods	array	当天配置的餐段列表
bases	array	基地列表
bases[].meals	array	当前基地的各餐段；没有菜品时仍返回该餐段
meals[].mealPeriodId	number	餐段 ID
meals[].mealPeriodName	string	餐段名称
meals[].startTime / endTime	string	餐段开始、结束时间，格式为 HH:mm
meals[].dishes	array	当前基地当前餐段的菜品
dishes[].name	string	菜品名称
dishes[].price	number	菜品价格
dishes[].learningStatus	string	已学习 或 未学习
dishes[].sortOrder	number	菜品在餐段中的顺序

5. HTTP 状态码

状态码	说明
200	请求成功
400	请求参数格式错误，例如日期或 baseId 格式错误
401	API Key 缺失或错误
503	服务端尚未配置第三方 API Key
500	服务端内部错误

错误返回格式：

{
  "message": "第三方接口认证失败"
}

6. 对接建议

1. 第三方系统应将 API Key 保存在服务端配置中，不要放在浏览器前端代码中。
2. 建议每次调用排餐接口时传入 baseName 或 baseId，减少返回数据量。
3. 排餐接口会返回没有菜品的餐段，第三方系统应将 dishes: [] 识别为当天该基地该餐段暂无排餐。
4. 日期不传时按 Asia/Shanghai 计算，不要使用第三方服务器的本地时区替代接口返回的 date。