257 lines
6.3 KiB
Markdown
257 lines
6.3 KiB
Markdown
# 菜品识别管理系统第三方接口文档
|
||
|
||
版本：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`。
|