188 lines
4.7 KiB
Markdown
188 lines
4.7 KiB
Markdown
# 菜品识别管理系统第三方接口文档
|
||
|
||
版本：v1.1
|
||
更新时间：2026-09-23
|
||
客户端实现：`service/mgmt_client.py`、`service/result_api.py`、`service/device_status.py`、`dao/meal_schedule.py`
|
||
|
||
## 1. 基础地址与认证
|
||
|
||
```text
|
||
https://cpsb.ruimeida.cc/
|
||
```
|
||
|
||
每次请求 Header：
|
||
|
||
```http
|
||
X-API-Key: dish_a4f7a1287198179fdc6a6571aa14064c2afc6338c6730e2b668ac5be15bdf769
|
||
```
|
||
|
||
环境变量：`DISH_MGMT_API_KEY`（务必含 `dish_` 前缀）。
|
||
|
||
---
|
||
|
||
## 2. 获取全部基地信息
|
||
|
||
```http
|
||
GET /api/public/bases
|
||
```
|
||
|
||
实现：`service/mgmt_client.fetch_bases` / `dao/base_sync.py`（启动同步）。
|
||
|
||
---
|
||
|
||
## 3. 写入菜品识别结果（识别订单）
|
||
|
||
```http
|
||
POST /api/public/recognition-orders
|
||
```
|
||
|
||
触发：每次识别完成后（`report_recognition`）。
|
||
|
||
请求体：
|
||
|
||
```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": "低于阈值，建议人工确认"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
实现：`service/result_api.py` → `ResultApiClient.send`。
|
||
|
||
---
|
||
|
||
## 4. 更新设备状态信息
|
||
|
||
```http
|
||
POST /api/public/devices/status
|
||
```
|
||
|
||
可用环境变量 `DISH_MGMT_DEVICE_STATUS_URL` 覆盖完整地址。
|
||
|
||
触发：后台线程定时上报（默认每 60 秒，`DISH_DEVICE_STATUS_INTERVAL`）。
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"deviceCode": "BASE_LOCAL_01",
|
||
"deviceName": "本地基地",
|
||
"baseCode": "BASE_LOCAL_01",
|
||
"baseName": "上海路基地",
|
||
"status": 1,
|
||
"online": true,
|
||
"ip": "192.168.1.10",
|
||
"appVersion": "1.0.0",
|
||
"reportedAt": "2026-09-23 16:00:00"
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `deviceCode` | 设备编码（默认 `DISH_DEVICE_CODE` / `DISH_BASE_CODE`） |
|
||
| `deviceName` | 设备名称 |
|
||
| `baseCode` / `baseName` | 所属基地 |
|
||
| `status` | `1` 在线启用 |
|
||
| `online` | 是否在线 |
|
||
| `ip` | 本机 IP |
|
||
| `appVersion` | 客户端版本 |
|
||
| `reportedAt` | 上报时间 |
|
||
|
||
实现：`service/device_status.DeviceStatusReporter`。
|
||
|
||
> 说明：若服务端路径或字段与上表不一致，用环境变量改 URL，或改 `build_device_status_payload`。
|
||
|
||
---
|
||
|
||
## 5. 获取当天排餐信息
|
||
|
||
```http
|
||
GET /api/public/meal-schedules/today?baseName=上海路基地
|
||
```
|
||
|
||
兼容：`GET /api/meal-schedules/today`
|
||
|
||
查询参数（可选，筛选优先级 `baseId` > `baseCode` > `baseName`）：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `date` | `YYYY-MM-DD`，默认中国时区当天 |
|
||
| `baseName` | 基地名称（推荐） |
|
||
| `baseId` | 基地 ID |
|
||
| `baseCode` | 基地编码 |
|
||
|
||
触发：程序启动时拉取一次（`DISH_MGMT_MEAL_ON_START=1`），结果缓存在本地文件，**界面不展示**。
|
||
|
||
比对规则：识别到的**已识别菜名**若不在当天排餐菜名集合中 → 写入待学习库（`reason=不在今日排餐`），人工确认是否识错。当天无排餐数据时跳过比对。
|
||
|
||
实现：`dao/meal_schedule.py` + `dao/schedule_check.py`。
|
||
|
||
---
|
||
|
||
## 6. 菜品信息
|
||
|
||
### 6.1 获取菜品信息
|
||
|
||
```http
|
||
GET /api/public/dishes
|
||
```
|
||
|
||
查询参数（可选）：`name`（模糊）、`category`（精确；`全部` 等同不筛选）。
|
||
|
||
实现：`service/mgmt_client.fetch_dishes`
|
||
环境变量：`DISH_MGMT_DISHES_API_URL`（默认 `{ORIGIN}/api/public/dishes`）。
|
||
|
||
### 6.2 按菜品名称更新学习状态
|
||
|
||
```http
|
||
PATCH /api/public/dishes/learning-status
|
||
```
|
||
|
||
请求体：`{"name":"红烧鸡块","status":"已学习"}`（`status` 仅 `已学习` / `未学习`，兼容 `learned` / `unlearned`）。
|
||
|
||
实现：`service/mgmt_client.patch_dish_learning_status` / `notify_dish_learned`
|
||
触发：本地添加模板 / 批量导入成功后，后台自动上报 `已学习`（失败只打日志，不影响学菜）。
|
||
环境变量：`DISH_MGMT_DISH_LEARNING_STATUS_URL`。
|
||
|
||
---
|
||
|
||
## 7. 常用环境变量
|
||
|
||
```bash
|
||
set DISH_MGMT_API_KEY=dish_a4f7a1287198179fdc6a6571aa14064c2afc6338c6730e2b668ac5be15bdf769
|
||
set DISH_BASE_NAME=上海路基地
|
||
set DISH_BASE_CODE=上海路基地-1788059884828-e55vu
|
||
set DISH_DEVICE_CODE=SETTLE_01
|
||
set DISH_DEVICE_NAME=一号结算机
|
||
set DISH_DEVICE_STATUS_INTERVAL=60
|
||
set DISH_RESULT_API_MOCK=0
|
||
set DISH_MGMT_MEAL_ON_START=1
|
||
```
|