362 lines
13 KiB
Markdown
362 lines
13 KiB
Markdown
# 菜品识别 API 服务需求文档
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 文档版本 | v1.1 |
|
||
| 日期 | 2026-09-15 |
|
||
| 关联客户端 | Dish_Recognition（海康 / USB 结算机客户端） |
|
||
| 客户端实现参考 | `service/result_api.py` |
|
||
| 总服务器 | `central_server/`（`python start.py` 或 `python -m central_server`） |
|
||
| 状态 | 客户端已实现「先传图再上报」；总服务器可单独部署 |
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
食堂客户端完成「YOLO 检盘 → 特征匹配认菜」后，需将结构化识别结果上报至业务侧 API，供：
|
||
|
||
- 收银 / 结算机展示与记账对接
|
||
- 总部汇总多基地识别数据
|
||
- 未知菜品后续运营处理（可选人工审核）
|
||
|
||
**本期 API 服务范围**：接收图片、落对象存储、返回 URL；再接收识别结果 JSON 并落库。
|
||
**对接拓扑**：工位机只连总库/中心 API；业务系统只连总库，不直连工位。
|
||
**明确不做**：真实支付扣款、会员积分、打印票据（可由下游系统消费本 API 数据实现）。
|
||
|
||
---
|
||
|
||
## 2. 角色与系统边界
|
||
|
||
```
|
||
┌─────────────────┐ 1) 上传图片 ┌──────────────────┐
|
||
│ 工位机客户端 │ ─────────────────────► │ 中心 API / 总库 │
|
||
│ Dish_Recognition│ 2) 上报 JSON(URL) │ 本文档 │
|
||
└────────┬────────┘ └────────┬─────────┘
|
||
│ 模板同步 │
|
||
▼ ▼
|
||
┌─────────────────┐ ┌──────────────────┐
|
||
│ MySQL 总库 │ ◄──── 流水 / URL ───── │ 对象存储 / 静态 │
|
||
│ 模板·基地·记录 │ │ media_store 或 OSS│
|
||
└─────────────────┘ └──────────────────┘
|
||
▲
|
||
│ 只对接总库
|
||
┌──────┴──────┐
|
||
│ 你方业务系统 │
|
||
└─────────────┘
|
||
```
|
||
|
||
| 系统 | 职责 |
|
||
|------|------|
|
||
| 客户端 | 识别、本地 SQLite 缓存；先上传图片再上报 URL |
|
||
| 中心 API | 鉴权、收图、静态访问、校验、结果落库、查询 |
|
||
| MySQL 总库 | 模板权威数据；识别记录可同步写入 |
|
||
| 对象存储 / 静态服务 | 原图 / 标注图 / 裁剪图，对外提供 HTTP URL |
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 识别结果上报（P0 · 必须）
|
||
|
||
| 项 | 要求 |
|
||
|----|------|
|
||
| 接口 | `POST /api/dish/recognize/result` |
|
||
| 触发时机 | 客户端每次选图/拍照识别完成后（异步发送） |
|
||
| 幂等 | 以 `request_id` 为幂等键；重复上报应返回成功且不重复计费/重复插有效流水 |
|
||
| 响应时延 | P99 < 500ms（不含大图上传）；超时客户端按 5s 配置 |
|
||
| 失败策略 | 客户端失败时本地落 mock 文件；服务端应返回明确错误码便于重试 |
|
||
|
||
### 3.2 识别记录查询（P1 · 建议）
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/dish/recognize/records` | 按基地、时间范围分页查询 |
|
||
| `GET /api/dish/recognize/records/{request_id}` | 按请求号查单条详情 |
|
||
|
||
### 3.3 图片资源（P0 · 必须：先上传再上报）
|
||
|
||
工位机本机路径跨机不可用。约定 **方案 A**：
|
||
|
||
1. `POST /api/dish/media/upload` 上传 `source` / `labeled` / `crop`，返回可访问 `url`
|
||
2. `POST /api/dish/recognize/result` 的 `source_image` / `labeled_image` / `dishes[].crop_image` **填 URL**，不再填本地路径
|
||
|
||
本地对象存储：`central_server/data/media/`，由 `python start.py` 提供 `GET /media/...`。
|
||
生产可把同一目录挂到 Nginx / OSS，或把上传接口改写为直传对象存储，**客户端字段不变**。
|
||
|
||
### 3.4 未知菜审核（P2 · 可选）
|
||
|
||
客户端本地有「待学习库」；总部侧可扩展：
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/dish/unknown/pending` | 拉取未知菜列表 |
|
||
| `POST /api/dish/unknown/{id}/approve` | 确认菜名并回写模板策略 |
|
||
| `POST /api/dish/unknown/{id}/reject` | 忽略 |
|
||
|
||
> 客户端 ORM 已有 `PendingApproval` 模型雏形，服务端可与之对齐。
|
||
|
||
### 3.5 健康检查（P0）
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/health` | 存活探测；客户端/网关探活 |
|
||
|
||
---
|
||
|
||
## 4. 接口详细设计
|
||
|
||
### 4.1 上报识别结果
|
||
|
||
**请求**
|
||
|
||
- Method：`POST`
|
||
- Path：`/api/dish/recognize/result`
|
||
- Content-Type：`application/json`
|
||
- Header（建议）：
|
||
|
||
| Header | 必填 | 说明 |
|
||
|--------|------|------|
|
||
| `Authorization` | 建议 | `Bearer <token>` 或基地密钥 |
|
||
| `X-Base-Code` | 可选 | 与 body.`base_id` 一致，便于网关路由 |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
**Body 字段（与客户端 `build_result_payload` 对齐）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `request_id` | string | 是 | 唯一请求号，格式建议 `REQ_{毫秒时间戳}` |
|
||
| `base_id` | string | 是 | 基地编码，如 `BASE_LOCAL_01` |
|
||
| `capture_time` | string | 是 | `YYYY-MM-DD HH:mm:ss` |
|
||
| `source_image` | string | 否 | 原图路径或 URL |
|
||
| `labeled_image` | string | 否 | 标注预览图路径或 URL |
|
||
| `dish_count` | int | 是 | 菜品区域数，应等于 `dishes.length` |
|
||
| `dishes` | array | 是 | 菜品明细，见下表 |
|
||
|
||
**`dishes[]` 元素**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `index` | int | 是 | 从 1 起的序号，与预览图编号/框对应 |
|
||
| `name` | string \| null | 是 | 识别菜名；未知时为 `null` |
|
||
| `score` | number \| null | 否 | 相似度，建议 0~1 |
|
||
| `is_unknown` | bool | 是 | 是否未达阈值 / 未知 |
|
||
| `suggested_name` | string \| null | 否 | 未知时的近似菜名建议 |
|
||
| `box` | number[4] \| null | 否 | `[x1,y1,x2,y2]` 像素坐标 |
|
||
| `crop_image` | string \| null | 否 | 裁剪图路径或 URL |
|
||
| `text` | string \| null | 否 | 可读摘要文本（调试用） |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"request_id": "REQ_1726296161000",
|
||
"base_id": "BASE_LOCAL_01",
|
||
"capture_time": "2026-09-14 14:22:41",
|
||
"source_image": "https://cdn.example.com/cap/xxx.jpg",
|
||
"labeled_image": "https://cdn.example.com/detect/xxx.jpg",
|
||
"dish_count": 2,
|
||
"dishes": [
|
||
{
|
||
"index": 1,
|
||
"name": "土豆丝",
|
||
"score": 0.86,
|
||
"is_unknown": false,
|
||
"suggested_name": null,
|
||
"box": [120, 80, 460, 400],
|
||
"crop_image": "https://cdn.example.com/cutting/1.jpeg",
|
||
"text": "土豆丝 0.860"
|
||
},
|
||
{
|
||
"index": 2,
|
||
"name": null,
|
||
"score": 0.42,
|
||
"is_unknown": true,
|
||
"suggested_name": "炒青菜",
|
||
"box": [500, 90, 820, 410],
|
||
"crop_image": "https://cdn.example.com/cutting/2.jpeg",
|
||
"text": "未知 · 近似 炒青菜"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**成功响应**（建议）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"request_id": "REQ_1726296161000",
|
||
"accepted": true,
|
||
"duplicate": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**（建议）
|
||
|
||
```json
|
||
{
|
||
"code": 40001,
|
||
"message": "dish_count 与 dishes 长度不一致",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
| HTTP | code（示例） | 含义 |
|
||
|------|--------------|------|
|
||
| 200 | 0 | 成功（含幂等重复） |
|
||
| 400 | 40001 | 参数校验失败 |
|
||
| 401 | 40100 | 未授权 |
|
||
| 409 | 40900 | 业务冲突（可选） |
|
||
| 500 | 50000 | 服务内部错误 |
|
||
|
||
---
|
||
|
||
### 4.2 查询识别记录（P1）
|
||
|
||
`GET /api/dish/recognize/records?base_id=BASE_01&from=2026-09-01&to=2026-09-14&page=1&page_size=20`
|
||
|
||
返回字段建议对齐表 `recognition_records`：
|
||
|
||
`request_id`、`base_code`、`capture_time`、`dish_count`、`unknown_count`、`summary`、`source_image`、`labeled_image`、`result_json`
|
||
|
||
---
|
||
|
||
### 4.3 媒体上传（P0）
|
||
|
||
`POST /api/dish/media/upload`
|
||
`Content-Type: multipart/form-data`
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `file` | 是 | 图片文件（jpg/png/bmp/webp，默认上限 12MB） |
|
||
| `type` | 是 | `source` / `labeled` / `crop` |
|
||
| `base_id` | 建议 | 基地编码 |
|
||
| `request_id` | 建议 | 关联某次识别，便于归档 |
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"url": "http://127.0.0.1:9000/media/BASE_LOCAL_01/REQ_1726296161000/source_cap.jpg",
|
||
"path": "BASE_LOCAL_01/REQ_1726296161000/source_cap.jpg",
|
||
"type": "source"
|
||
}
|
||
}
|
||
```
|
||
|
||
静态访问：`GET /media/{base_id}/{request_id}/{filename}`
|
||
|
||
归档规则：`media_store/{base_id}/{request_id}/{type}_{原文件名}`
|
||
|
||
客户端行为（`ResultApiClient`）：
|
||
|
||
1. 生成 `request_id`
|
||
2. **默认**：启动本机 `media_server`（`:9100`），把 YOLO 裁剪图等复制进 `central_server/data/media/`，字段写成
|
||
`http://<局域网IP>:9100/media/{base}/{request_id}/crop_xxx.jpg`
|
||
3. 若显式设置了 `DISH_MEDIA_UPLOAD_URL`，则优先远程上传，失败再回落本机 media server
|
||
4. 再 `POST` 管理系统 `recognition-orders`（或本地 mock）
|
||
|
||
模拟模式不发结果 HTTP，但仍生成本机 media URL。若云端管理系统要拉取图片，本机需公网可达，或设置 `DISH_MEDIA_PUBLIC_BASE` 为可访问前缀（反代/穿透/OSS）。
|
||
|
||
---
|
||
|
||
## 5. 非功能需求
|
||
|
||
| 类别 | 要求 |
|
||
|------|------|
|
||
| 可用性 | 核心上报接口可用性 ≥ 99.5% |
|
||
| 并发 | 单集群支持 ≥ 50 QPS 上报（可按基地数扩展） |
|
||
| 安全 | HTTPS；基地级鉴权；禁止匿名写 |
|
||
| 审计 | 保留原始 JSON ≥ 90 天；可按 `request_id` 追溯 |
|
||
| 日志 | 记录 `request_id`、`base_id`、耗时、HTTP 状态 |
|
||
| 兼容 | 字段向后兼容；新增字段客户端可忽略 |
|
||
|
||
---
|
||
|
||
## 6. 与客户端配置对齐
|
||
|
||
| 环境变量 | 含义 | 默认 |
|
||
|----------|------|------|
|
||
| `DISH_RESULT_API_MOCK` | `1` 写本地 mock，不发 HTTP | `0`（真实上报） |
|
||
| `DISH_RESULT_API_URL` | 真实上报地址 | 管理系统 `…/recognition-orders` |
|
||
| `DISH_MEDIA_UPLOAD_URL` | 远程传图地址；**空则不走远程，用本机 media server** | 空 |
|
||
| `DISH_MEDIA_SERVER_ENABLED` | 是否启本机静态图服务 | `1` |
|
||
| `DISH_MEDIA_SERVER_PORT` | 本机 media 端口 | `9100` |
|
||
| `DISH_MEDIA_PUBLIC_BASE` | 对外可访问的 `/media` 前缀（云端拉图时必配公网） | 自动 `http://<LAN>:9100/media` |
|
||
| `DISH_MEDIA_HOST` | 强制写入 URL 的主机名/IP | 空则自动探测局域网 IP |
|
||
| `DISH_UPLOAD_BEFORE_REPORT` | `1` 先落 URL 再上报 | `1` |
|
||
| `DISH_API_TOKEN` / `DISH_RESULT_API_KEY` | Bearer / X-API-Key | 管理系统 Key |
|
||
| `DISH_RESULT_API_TIMEOUT` | 结果上报超时秒数 | `10` |
|
||
| `DISH_MEDIA_UPLOAD_TIMEOUT` | 远程单张图上传超时 | `20` |
|
||
| `DISH_RESULT_BASE_ID` / `DISH_BASE_CODE` | 上报基地 | `BASE_LOCAL_01` |
|
||
|
||
联调步骤：
|
||
|
||
1. 启动客户端（会自动起 `:9100` media server）
|
||
2. 识别一次，日志应出现 `crop -> http://<LAN>:9100/media/.../crop_….jpg`
|
||
3. 浏览器打开该 URL 应能看到裁剪图；上报 JSON 中 `dishes[].crop_image` 为该 HTTP 路径
|
||
4. 若管理系统在公网：配置 `DISH_MEDIA_PUBLIC_BASE` 为可外网访问的前缀，或设置 `DISH_MEDIA_UPLOAD_URL` 接到 OSS
|
||
|
||
---
|
||
|
||
## 7. 数据落库建议
|
||
|
||
可复用或扩展现有 `recognition_records`：
|
||
|
||
| 列 | 说明 |
|
||
|----|------|
|
||
| `request_id` | 幂等键，唯一索引 |
|
||
| `base_code` / `source_base_id` | 基地 |
|
||
| `capture_time` | 抓拍时间 |
|
||
| `source_image` / `labeled_image` | 建议存 URL |
|
||
| `dish_count` / `unknown_count` | 统计 |
|
||
| `summary` | 菜名摘要 |
|
||
| `result_json` | 完整 dishes JSON |
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
- [x] 合法 payload 上报返回 `code=0`，且库中可查到对应 `request_id`（本地 `api_server`）
|
||
- [x] 相同 `request_id` 重复上报不产生重复有效业务单据
|
||
- [x] `is_unknown=true` 且 `name=null` 可正常入库
|
||
- [x] `dish_count` 与数组长度不一致时返回 4xx
|
||
- [ ] 配置 `DISH_API_TOKEN` 后未鉴权请求被拒绝
|
||
- [ ] 客户端关闭 mock 后真实 HTTP 联调通过（抽样 ≥ 20 次）
|
||
- [x] 图片上传后结果中的 URL 可通过 `GET /media/...` 访问
|
||
|
||
---
|
||
|
||
## 9. 分期建议
|
||
|
||
| 阶段 | 内容 |
|
||
|------|------|
|
||
| MVP | 健康检查 + 图片上传 + 静态访问 + 结果上报 + 幂等落库 |
|
||
| 二期 | 记录查询分页 / 时间筛选；生产 OSS 直传 |
|
||
| 三期 | 未知菜总部审核流 + 统计看板 API |
|
||
|
||
---
|
||
|
||
## 10. 附录：客户端当前行为说明
|
||
|
||
- 默认 **mock**：不发 HTTP；图片复制到 `media_store/`，JSON 写入 `api_mock_results/REQ_*.json`（字段已是 URL）
|
||
- 真实模式：先 `multipart` 上传图片，再 `POST` JSON；失败时仍写一份本地文件便于排错
|
||
- 默认 **异步**上报（不阻塞 UI）；本地 SQLite 仍保存本机路径便于预览
|
||
- 识别同时写入本地 SQLite `recognition_records`；MySQL 可用时客户端也会尝试同步写总库（与 HTTP API 并行，服务端实现时注意职责划分，避免双写冲突）
|
||
|
||
---
|
||
|
||
## 11. 待确认事项（给产品/后端）
|
||
|
||
1. 鉴权方式：已支持可选 `DISH_API_TOKEN`（Bearer / X-Api-Token）；生产是否改 JWT / 签名？
|
||
2. 生产对象存储：继续用本机 `media_store` + Nginx，还是 OSS（接口形态已对齐，只换上传实现）？
|
||
3. 识别结果是否需要回推收银金额（单价是否由服务端维护）？
|
||
|
||
图片必须先上传再上报已冻结为协议。确认其余项后可发 v1.2。
|