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

版本：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
```