793 lines
24 KiB
Markdown
793 lines
24 KiB
Markdown
# 菜品识别管理系统第三方接口文档
|
||
|
||
版本：v1.3
|
||
更新时间：2026-10-13
|
||
|
||
## 1. 接口地址
|
||
|
||
生产环境基础地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/
|
||
```
|
||
|
||
基地和菜品查询接口使用 `GET` 请求；识别结果、无法识别样本和菜品图库样本写入接口使用 `POST` 请求；菜品学习状态和设备状态更新使用 `PATCH` 请求。
|
||
|
||
## 2. 接口认证
|
||
|
||
接口使用独立的 API Key 认证，不使用后台用户登录账号密码。
|
||
|
||
每次请求都必须携带请求头：
|
||
|
||
```http
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
请向系统管理员获取正式 API Key，不要将 API Key 写入前端页面、公开代码仓库或日志中。
|
||
|
||
## 3. 写入菜品识别结果
|
||
|
||
该接口接收一次识别任务的主信息和菜品明细，供第三方识别程序回传结果。接口使用
|
||
`request_id` 做幂等键：同一个 `request_id` 再次提交时会更新主记录，并完整替换该任务的菜品明细，不会产生重复订单。
|
||
|
||
### 请求
|
||
|
||
```http
|
||
POST /api/public/recognition-orders
|
||
Content-Type: application/json
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/recognition-orders
|
||
```
|
||
|
||
### 请求体示例
|
||
|
||
```json
|
||
{
|
||
"request_id": "REQ_20260916_000001",
|
||
"base_name": "上海路基地",
|
||
"device_code": "DEV-0018",
|
||
"capture_time": "2026-09-16 12:34:56",
|
||
"source_image": "https://example.com/images/source.jpg",
|
||
"labeled_image": "https://example.com/images/labeled.jpg",
|
||
"dish_count": 2,
|
||
"dishes": [
|
||
{
|
||
"index": 1,
|
||
"name": "红烧鸡块",
|
||
"score": 0.96,
|
||
"is_unknown": false,
|
||
"suggested_name": null,
|
||
"box": [120, 80, 460, 390],
|
||
"crop_image": "https://example.com/images/crop-1.jpg",
|
||
"text": "识别为红烧鸡块，相似度 0.96"
|
||
},
|
||
{
|
||
"index": 2,
|
||
"name": null,
|
||
"score": 0.42,
|
||
"is_unknown": true,
|
||
"suggested_name": "辣椒炒肉",
|
||
"box": [500, 90, 820, 400],
|
||
"crop_image": "https://example.com/images/crop-2.jpg",
|
||
"text": "低于阈值，建议人工确认"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Body 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `request_id` | string | 是 | 唯一请求号，建议使用 `REQ_` 加毫秒时间戳或业务流水号 |
|
||
| `base_name` | string | 是 | 基地名称，必须与基地信息中的 `name` 完全一致，例如 `上海路基地` |
|
||
| `device_code` | string | 是 | 设备编号，对应设备列表中的设备编号 |
|
||
| `capture_time` | string | 是 | 采集时间，格式为 `YYYY-MM-DD HH:mm:ss`，也支持 ISO 8601 字符串 |
|
||
| `source_image` | string \| null | 否 | 原图路径或 URL；没有时传 `null` 或空字符串 |
|
||
| `labeled_image` | string \| null | 否 | 标注预览图路径或 URL；没有时传 `null` 或空字符串 |
|
||
| `dish_count` | int | 是 | 菜品区域数，必须等于 `dishes.length`，不能小于 0 |
|
||
| `dishes` | array | 是 | 菜品识别明细数组 |
|
||
|
||
### `dishes[]` 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `index` | int | 是 | 从 1 开始的顺序号，与标注预览图中的编号/框对应，任务内不可重复 |
|
||
| `name` | string \| null | 是 | 识别菜名；未知菜品时传 `null` |
|
||
| `score` | number \| null | 否 | 相似度，建议范围为 0～1；未知或没有分数时传 `null` |
|
||
| `is_unknown` | boolean | 是 | 是否未达阈值或未知，未知时为 `true` |
|
||
| `suggested_name` | string \| null | 否 | 未知菜品的近似菜名建议 |
|
||
| `box` | number[4] \| null | 否 | 像素坐标 `[x1, y1, x2, y2]` |
|
||
| `crop_image` | string \| null | 否 | 当前菜品裁剪图路径或 URL |
|
||
| `text` | string \| null | 否 | 可读摘要文本，仅用于调试或展示 |
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
curl -X POST "https://cpsb.ruimeida.cc/api/public/recognition-orders" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
-d @recognition-order.json
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"message": "识别结果已保存",
|
||
"item": {
|
||
"request_id": "REQ_20260916_000001",
|
||
"base_name": "上海路基地",
|
||
"device_code": "DEV-0018",
|
||
"capture_time": "2026-09-16 12:34:56",
|
||
"dish_count": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
### 校验与存储说明
|
||
|
||
1. `base_name` 必须传启用基地的名称，并且需要与基地信息中的 `name` 完全一致；接口会在服务端匹配基地编码保存关联关系。
|
||
2. `device_code` 必须传设备列表中的设备编号。
|
||
3. `dish_count` 必须与明细条数一致；`index` 在同一请求内必须唯一且从 1 开始。
|
||
4. `box` 只能是 4 个数字，顺序为 `[x1, y1, x2, y2]`，单位为原图像素。
|
||
5. 识别原图、标注图和裁剪图由第三方自行保存，接口只保存传入的路径或 URL。
|
||
6. 数据分别保存于 `recognition_orders` 和 `recognition_order_dishes` 两张表，删除或更新主记录时会同步处理明细。
|
||
7. 新版接口使用 `base_name`，不再要求第三方传基地编码；服务端会根据基地名称匹配并保存内部关联关系。历史版本的 `base_id` 仅作兼容处理，不建议新接入继续使用。
|
||
|
||
## 4. 上报无法识别样本
|
||
|
||
第三方识别程序在识别到未知菜品后调用该接口，上报的数据进入后台「数据管理 → 识别数据管理 → 无法识别统计」列表。管理员可在该页面勾选裁剪图、填写菜名后提交手动学习，学习提交会转发到识别端学习接口（`POST /api/client/manual-learn`）。
|
||
|
||
### 请求
|
||
|
||
```http
|
||
POST /api/public/unrecognized-samples
|
||
Content-Type: application/json
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/unrecognized-samples
|
||
```
|
||
|
||
### 请求体示例
|
||
|
||
```json
|
||
{
|
||
"request_id": "REQ_20260916_000002",
|
||
"order_no": "HW26091612341817",
|
||
"base_name": "上海路基地",
|
||
"device_code": "DEV-0018",
|
||
"capture_time": "2026-09-16 12:34:46",
|
||
"image_url": "https://example.com/images/source.jpg",
|
||
"unknown_count": 2,
|
||
"suggested_names": ["梅菜扣肉", "黑米饭"],
|
||
"crops": [
|
||
{
|
||
"index": 1,
|
||
"image_url": "https://example.com/images/crop-1.jpg",
|
||
"suggested_name": "梅菜扣肉",
|
||
"score": 0.62
|
||
},
|
||
{
|
||
"index": 2,
|
||
"image_url": "https://example.com/images/crop-2.jpg",
|
||
"suggested_name": null,
|
||
"score": 0.41
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Body 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `request_id` | string | 否 | 唯一请求号，作为幂等键；传入后同一 `request_id` 重复上报会覆盖主记录并重建明细 |
|
||
| `order_no` | string | 是 | 业务单号，后台无法识别统计与手动学习接口使用 |
|
||
| `base_code` | string | 否 | 基地编码，与 `base_name` 至少传一个；服务端匹配启用基地后保存关联 |
|
||
| `base_name` | string | 否 | 基地名称，需与基地信息中的 `name` 一致；与 `base_code` 同时传入时优先按编码匹配 |
|
||
| `device_code` | string | 是 | 设备编号 |
|
||
| `capture_time` | string | 是 | 采集时间，格式为 `YYYY-MM-DD HH:mm:ss`，也支持 ISO 8601 字符串 |
|
||
| `image_url` | string | 是 | 整盘原图路径或 URL |
|
||
| `unknown_count` | number | 否 | 未知菜品数量；不传或非法时按 `crops.length` 保存 |
|
||
| `suggested_names` | string[] | 否 | 建议菜名列表，在列表页「建议菜名」列展示 |
|
||
| `crops` | array | 否 | 未知菜品裁剪图明细，供后台学习弹框逐盘学习 |
|
||
|
||
### `crops[]` 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `index` | int | 否 | 从 1 开始的顺序号，缺省按数组位置生成；同一样本内不可重复 |
|
||
| `image_url` | string \| null | 否 | 当前未知菜品的裁剪图路径或 URL |
|
||
| `suggested_name` | string \| null | 否 | 近似菜名建议；后台学习弹框会预填到菜名输入框 |
|
||
| `score` | number \| null | 否 | 相似度，范围 0～1；后台学习弹框展示为置信度 |
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
curl -X POST "https://cpsb.ruimeida.cc/api/public/unrecognized-samples" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
-d @unrecognized-sample.json
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"message": "无法识别样本已保存",
|
||
"item": {
|
||
"id": 1,
|
||
"order_no": "HW26091612341817",
|
||
"unknown_count": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
### 校验与存储说明
|
||
|
||
1. `order_no`、`device_code`、`capture_time`、`image_url` 为必填，缺失或格式无效返回 `400`。
|
||
2. `base_code` / `base_name` 传入时服务端会匹配启用状态的基地并保存编码和名称；匹配不到时按传入原值保存，不影响入库。
|
||
3. `score` 超出 0～1、`index` 重复或非法时返回 `400`。
|
||
4. 传 `request_id` 时按幂等处理：重复上报覆盖主记录并完整替换 `crops` 明细；不传 `request_id` 时每次上报都会新增一条样本。
|
||
5. 数据保存于 `unrecognized_samples` 和 `unrecognized_sample_crops` 两张表。
|
||
6. 后台无法识别统计列表支持按时段、日期范围、基地、餐段、学习状态（默认未学习）和关键字筛选；餐段按 `capture_time` 落入系统餐段配置的时间范围判定。
|
||
|
||
## 5. 上报菜品图库样本（近期学习菜品）
|
||
|
||
识别端在学菜完成后调用该接口，把「菜名 ↔ 样本图片」映射上报给管理系统，数据展示在后台「AI 自主学习管理 → 近期学习菜品」页面，详情弹框中展示每个菜品的名称和多张样本图片。
|
||
|
||
### 请求
|
||
|
||
```http
|
||
POST /api/public/dish-gallery/samples
|
||
Content-Type: application/json
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/dish-gallery/samples
|
||
```
|
||
|
||
### 请求体示例（单菜）
|
||
|
||
```json
|
||
{
|
||
"request_id": "REQ_20260916_120001",
|
||
"base_name": "上海路基地",
|
||
"device_code": "DEV-0018",
|
||
"learned_at": "2026-09-16 12:00:01",
|
||
"name": "梅菜扣肉",
|
||
"code": "DISH-001",
|
||
"category": "成品",
|
||
"images": [
|
||
"https://example.com/template/mc/20260916_120001_01.jpg",
|
||
"https://example.com/template/mc/20260916_120001_02.jpg"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 请求体示例（一次报多个菜）
|
||
|
||
```json
|
||
{
|
||
"request_id": "REQ_20260916_120001",
|
||
"base_name": "上海路基地",
|
||
"learned_at": "2026-09-16 12:00:01",
|
||
"dishes": [
|
||
{
|
||
"name": "梅菜扣肉",
|
||
"code": "DISH-001",
|
||
"category": "成品",
|
||
"images": ["https://example.com/template/mc/20260916_120001_01.jpg"]
|
||
},
|
||
{
|
||
"name": "黑米饭",
|
||
"category": "成品",
|
||
"images": ["https://example.com/template/hmf/20260916_120001_02.jpg"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Body 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `request_id` | string | 否 | 请求号，与菜品名称一起作为幂等键；不传时服务端自动生成 |
|
||
| `base_code` | string | 否 | 基地编码，与 `base_name` 至少传一个；服务端匹配启用基地后保存关联 |
|
||
| `base_name` | string | 否 | 基地名称，需与基地信息中的 `name` 一致 |
|
||
| `device_code` | string | 否 | 设备编号 |
|
||
| `learned_at` | string | 是 | 学习完成时间，格式为 `YYYY-MM-DD HH:mm:ss`，也支持 ISO 8601 字符串；兼容 `capture_time` 字段名 |
|
||
| `name` | string | 单菜必填 | 菜品名称（单菜格式） |
|
||
| `code` | string | 否 | 菜品编码（单菜格式） |
|
||
| `category` | string | 否 | 分类，默认 `成品`，建议传 `成品` 或 `配菜` |
|
||
| `images` | string[] | 单菜必填 | 样本图片路径或 URL 数组，至少一张（单菜格式） |
|
||
| `dishes` | array | 多菜必填 | 多菜品格式；与 `name` 同时传入时优先使用 `dishes` |
|
||
|
||
### `dishes[]` 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | string | 是 | 菜品名称 |
|
||
| `code` | string | 否 | 菜品编码 |
|
||
| `category` | string | 否 | 分类，默认 `成品` |
|
||
| `images` | string[] | 是 | 样本图片路径或 URL 数组，至少一张 |
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
curl -X POST "https://cpsb.ruimeida.cc/api/public/dish-gallery/samples" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
-d @dish-gallery-sample.json
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"message": "图库样本已保存",
|
||
"item": {
|
||
"request_id": "REQ_20260916_120001",
|
||
"count": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
### 校验与存储说明
|
||
|
||
1. `learned_at`（或 `capture_time`）缺失或格式无效返回 `400`。
|
||
2. 单菜格式必须同时传 `name` 和非空 `images`；多菜格式每个菜品的 `name` 和 `images` 同样必填，否则返回 `400`。
|
||
3. 幂等键为 `request_id + 菜品名称`：同一组合重复上报时更新样本（图片、分类、学习时间等以最新为准）；上报未携带 `code` 时保留原编码。
|
||
4. 数据保存于 `dish_gallery_samples` 表。
|
||
5. 后台「近期学习菜品」列表按学习时间倒序展示，支持时段、日期范围、基地和关键字筛选；点「详情」按 `request_id` 展示该次学习的全部菜品及多张样本图片。
|
||
|
||
## 6. 后台查询识别结果
|
||
|
||
以下接口用于系统后台的统计列表和详情查询，使用登录用户的 JWT，不使用第三方 API Key。第三方系统如需查询自身回传的数据，建议由业务服务端代理调用，不要把管理员 JWT 暴露给浏览器。
|
||
|
||
### 识别统计列表
|
||
|
||
```http
|
||
GET /api/recognition-stats
|
||
Authorization: Bearer <ACCESS_TOKEN>
|
||
```
|
||
|
||
可选参数：`period`（`today`、`yesterday`、`week`、`month`）、`baseCode`、`keyword`、`startDate`、`endDate`、`page`、`pageSize`。`pageSize` 支持 10、20、50。
|
||
|
||
### 识别结果详情
|
||
|
||
```http
|
||
GET /api/recognition-orders/{request_id}
|
||
Authorization: Bearer <ACCESS_TOKEN>
|
||
```
|
||
|
||
详情返回主记录和 `dishes` 明细，主记录返回 `base_name`、`device_code`，不返回或展示基地编码 `base_id`；明细包含 `index`、`name`、`score`、`is_unknown`、`suggested_name`、`box`、`crop_image`、`text`。
|
||
|
||
## 7. 更新设备状态信息
|
||
|
||
第三方设备程序使用该接口按设备编号更新设备状态、心跳更新时间和菜谱当前日期。接口使用 API Key 认证。
|
||
|
||
### 请求
|
||
|
||
```http
|
||
PATCH /api/public/devices/{device_code}/status
|
||
Content-Type: application/json
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址示例：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/devices/DEV-0018/status
|
||
```
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"status": "在线",
|
||
"updated_at": "2026-09-16 14:30:00",
|
||
"recipe_date": "2026-09-16"
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| 路径 `device_code` | string | 是 | 设备编号，对应设备列表中的设备编号 |
|
||
| `status` | string | 是 | 设备状态，支持 `在线`、`离线`，也支持 `online`、`offline` |
|
||
| `updated_at` | string \| null | 否 | 设备最后更新时间，格式为 `YYYY-MM-DD HH:mm:ss`；不传时使用服务器当前时间 |
|
||
| `recipe_date` | string \| null | 否 | 菜谱当前日期，格式为 `YYYY-MM-DD`；不传时保留原值，传 `null` 或空字符串可清空 |
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
curl -X PATCH "https://cpsb.ruimeida.cc/api/public/devices/DEV-0018/status" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
-d '{"status":"在线","updated_at":"2026-09-16 14:30:00","recipe_date":"2026-09-16"}'
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"message": "设备状态信息已更新",
|
||
"item": {
|
||
"id": 1,
|
||
"code": "DEV-0018",
|
||
"status": 1,
|
||
"status_label": "在线",
|
||
"updated_at": "2026-09-16 14:30:00",
|
||
"recipe_date": "2026-09-16"
|
||
}
|
||
}
|
||
```
|
||
|
||
设备列表查询接口 `GET /api/devices` 返回的字段包括 `status`、`status_label`、`updated_at`、`recipe_date`，其中 `status=1` 表示在线，`status=0` 表示离线。设备状态和时间信息保存于 `devices` 表。
|
||
|
||
## 8. 菜品信息接口
|
||
|
||
菜品接口使用 API Key 认证，返回菜品名称、菜品分类、学习状态、价格等信息。
|
||
|
||
### 8.1 获取菜品信息
|
||
|
||
```http
|
||
GET /api/public/dishes
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/dishes
|
||
```
|
||
|
||
查询参数均为可选，不传参数时返回全部菜品：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | string | 否 | 按菜品名称模糊查询，例如 `鸡` |
|
||
| `category` | string | 否 | 按菜品分类精确查询，例如 `素菜`；传 `全部` 等同于不筛选 |
|
||
|
||
查询全部菜品：
|
||
|
||
```bash
|
||
curl -X GET "https://cpsb.ruimeida.cc/api/public/dishes" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>"
|
||
```
|
||
|
||
按菜品名称和分类查询：
|
||
|
||
```bash
|
||
curl -G "https://cpsb.ruimeida.cc/api/public/dishes" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
--data-urlencode "name=鸡" \
|
||
--data-urlencode "category=大荤"
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"name": "红烧鸡块",
|
||
"code": "DISH-001",
|
||
"category": "大荤",
|
||
"price": 4,
|
||
"status": "已学习",
|
||
"confidence": 96.5,
|
||
"picks": 3809,
|
||
"created_at": "2026-09-16 10:00:00",
|
||
"updated_at": "2026-09-28 09:30:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 8.2 按菜品名称更新学习状态
|
||
|
||
```http
|
||
PATCH /api/public/dishes/learning-status
|
||
Content-Type: application/json
|
||
X-API-Key: <THIRD_PARTY_API_KEY>
|
||
```
|
||
|
||
完整地址：
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/api/public/dishes/learning-status
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"name": "红烧鸡块",
|
||
"status": "已学习"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | string | 是 | 菜品名称，按名称精确匹配 |
|
||
| `status` | string | 是 | 学习状态，只能是 `已学习` 或 `未学习`；也兼容 `learned`、`unlearned` |
|
||
|
||
cURL 示例：
|
||
|
||
```bash
|
||
curl -X PATCH "https://cpsb.ruimeida.cc/api/public/dishes/learning-status" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: <THIRD_PARTY_API_KEY>" \
|
||
-d '{"name":"红烧鸡块","status":"已学习"}'
|
||
```
|
||
|
||
成功返回：
|
||
|
||
```json
|
||
{
|
||
"message": "菜品学习状态已更新",
|
||
"item": {
|
||
"id": 1,
|
||
"name": "红烧鸡块",
|
||
"code": "DISH-001",
|
||
"category": "大荤",
|
||
"price": 4,
|
||
"status": "已学习",
|
||
"confidence": 96.5,
|
||
"picks": 3809,
|
||
"created_at": "2026-09-16 10:00:00",
|
||
"updated_at": "2026-09-28 09:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
菜品名称不存在时返回 `404`；状态不合法或菜品名称为空时返回 `400`。
|
||
|
||
## 9. 获取全部基地信息
|
||
|
||
### 请求
|
||
|
||
```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 | 排序值 |
|
||
|
||
## 10. 获取当天排餐信息
|
||
|
||
### 请求
|
||
|
||
```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 | 菜品在餐段中的顺序 |
|
||
|
||
## 11. HTTP 状态码
|
||
|
||
| 状态码 | 说明 |
|
||
| --- | --- |
|
||
| `200` | 请求成功 |
|
||
| `400` | 请求参数格式错误，例如日期或 `baseId` 格式错误 |
|
||
| `401` | API Key 缺失或错误 |
|
||
| `503` | 服务端尚未配置第三方 API Key |
|
||
| `500` | 服务端内部错误 |
|
||
|
||
错误返回格式：
|
||
|
||
```json
|
||
{
|
||
"message": "第三方接口认证失败"
|
||
}
|
||
```
|
||
|
||
## 12. 对接建议
|
||
|
||
1. 第三方系统应将 API Key 保存在服务端配置中，不要放在浏览器前端代码中。
|
||
2. 建议每次调用排餐接口时传入 `baseName` 或 `baseId`，减少返回数据量。
|
||
3. 排餐接口会返回没有菜品的餐段，第三方系统应将 `dishes: []` 识别为当天该基地该餐段暂无排餐。
|
||
4. 日期不传时按 `Asia/Shanghai` 计算，不要使用第三方服务器的本地时区替代接口返回的 `date`。
|