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

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

## 1. 接口地址

生产环境基础地址：

```text
https://cpsb.ruimeida.cc/
```

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

## 2. 接口认证

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

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

```http
X-API-Key: dish_a4f7a1287198179fdc6a6571aa14064c2afc6338c6730e2b668ac5be15bdf769
```

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

## 3. 获取全部基地信息

### 请求

```http
GET /api/public/bases
```

完整地址：

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

### cURL 示例

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

### 返回示例

```json
{
  "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. 获取当天排餐信息

### 请求

```http
GET /api/public/meal-schedules/today
```

兼容地址：

```http
GET /api/meal-schedules/today
```

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

### 查询参数

所有查询参数均为可选：

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

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

### 调用示例

查询当天所有基地：

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

按基地名称查询：

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

查询指定日期和基地：

```bash
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=上海路基地"
```

### 返回示例

```json
{
  "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` | 服务端内部错误 |

错误返回格式：

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

## 6. 对接建议

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