4.7 KiB

Raw Blame History

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

版本：v1.1
更新时间：2026-09-23
客户端实现：service/mgmt_client.py、service/result_api.py、service/device_status.py、dao/meal_schedule.py

1. 基础地址与认证

https://cpsb.ruimeida.cc/

每次请求 Header：

X-API-Key: dish_a4f7a1287198179fdc6a6571aa14064c2afc6338c6730e2b668ac5be15bdf769

环境变量：DISH_MGMT_API_KEY（务必含 dish_ 前缀）。

2. 获取全部基地信息

GET /api/public/bases

实现：service/mgmt_client.fetch_bases / dao/base_sync.py（启动同步）。

3. 写入菜品识别结果（识别订单）

POST /api/public/recognition-orders

触发：每次识别完成后（report_recognition）。

请求体：

{
  "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. 更新设备状态信息

POST /api/public/devices/status

可用环境变量 DISH_MGMT_DEVICE_STATUS_URL 覆盖完整地址。

触发：后台线程定时上报（默认每 60 秒，DISH_DEVICE_STATUS_INTERVAL）。

请求体：

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

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 获取菜品信息

GET /api/public/dishes

查询参数（可选）：name（模糊）、category（精确；全部 等同不筛选）。

实现：service/mgmt_client.fetch_dishes
环境变量：DISH_MGMT_DISHES_API_URL（默认 {ORIGIN}/api/public/dishes）。

6.2 按菜品名称更新学习状态

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. 常用环境变量

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

4.7 KiB Raw Blame History Unescape Escape