SmartPlateCabinet/docs/业务接口对齐文档-开柜门版.md

# 智能餐盘柜（开柜门版）业务接口对齐文档

> 版本：v1.0（2026-08-18）
> 适用设备：会员版智能餐盘柜（开柜门，applicationId `com.sw.platecabinet.member`）
> 用途：供后端对照本设备端实际调用的接口，对齐业务功能与字段

## 1. 通用约定

### 1.1 服务器环境

设备端 BaseUrl 运行时确定，优先级：设备配置接口下发的 `appPackageUrl` > 本地缓存（SP）> 内置默认。

| 环境 | 地址 | 说明 |
| --- | --- | --- |
| 本地 | `http://192.168.10.101:24801` | LOCAL_BASE_URL |
| 测试 | `https://dev.yixiong-tech.com:8081` | TEST_BASE_URL |
| 生产 | `https://platform-api.uat.shuziweidao.com` | PROD_BASE_URL |

### 1.2 请求头（所有请求统一携带）

| Header | 值 | 说明 |
| --- | --- | --- |
| Content-Type | application/json | JSON 请求体 |
| Accept | application/json | — |
| X-Access-Token | 固定 JWT 字符串（当前硬编码） | 设备免登录态 |
| X-DEVICE-CODE | 设备 SN（`GlobalData.deviceId`） | 设备标识 |
| authorization | 固定 key `57ee87183f2a4fa59683ec9ef41c8f5d` | 网关鉴权 |

### 1.3 统一响应格式

```json
{
  "code": "00000",   // 成功固定为 "00000"，其余视为失败
  "msg": "",
  "data": { ... }    // 业务数据，可为 null / 数组
}
```

## 2. 接口总览

本设备端接口分两套体系（两套设备共用同一后端时请都保留）：

| 体系 | 用途 | 状态 |
| --- | --- | --- |
| V2（/nutrition/neglect/**） | 人脸体系：设备配置、人脸全量/增量同步、人脸采集、取餐上报 | **当前启用** |
| V1（/terminal/neglect/**） | 开柜门业务：登录、餐盘绑定/解绑、会员搜索、扫描枪查询 | **当前启用** |
| V1 旧人脸接口（faceFeature 系列） | 旧人脸同步 | **已停用**（被 V2 替代，可下线） |

## 3. V2 人脸体系接口（当前启用）

### 3.1 获取设备配置

- **GET** `/nutrition/neglect/pickup/device/config`
- 无参数
- 调用时机：设备启动（DeviceInitActivity），人脸缓存同步之前

响应 `data`（DeviceConfigV2）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appPackageUrl | String | 业务服务器 BASE URL（下发后全局生效） |
| canteenName | String | 食堂名称 |
| canteenId | String | 食堂 ID |
| arcsoftAppId | String | 虹软 SDK AppID（设备激活用） |
| arcsoftSdkKey | String | 虹软 SDK Key |
| arcsoftActiveKey | String | 虹软 SDK 激活码 |
| clientServerIp | String | MQTT 客户端服务器 IP |
| zhstServerIp | String | 智慧食堂服务器 IP（MQTT 端口） |

### 3.2 获取人脸缓存（全量，分页）

- **POST** `/nutrition/neglect/common/face/page`
- 请求体：`{ "pageNum": 1, "pageSize": 100 }`（pageSize 固定 100，客户端自动递归翻页直到不足一页）
- 调用时机：设备首次启动（本地标记 isFirstGetFace）时全量拉取，拉取成功后清空本地人脸库重建

响应 `data`：`UserFaceModelV2` 数组：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| userFaceId | String | 人脸记录唯一 ID（增量删除/判重的关键） |
| userId | String | 用户 ID |
| faceFeature / faceFeatureStr / faceFeatureString | String | 人脸特征 Base64（三字段取第一个非空） |
| faceUpdateTimestamp | Long | 人脸更新时间戳（毫秒） |
| cardNo | String | 会员编号 |
| member | Boolean | 是否会员 |
| faceDeleted | Boolean | 删除标识（增量接口用） |
| personType | String | 人员类型 |

### 3.3 获取人脸增量数据

- **POST** `/nutrition/neglect/common/face/increment`
- 请求体：`{ "pageNum": 1, "pageSize": 100, "timestamp": 1723900000000 }`（timestamp 为上次同步的最大 faceUpdateTimestamp）
- 调用时机：登录页每 5 分钟定时任务（人脸库非空时）
- 客户端处理：`faceDeleted=true` 按 `userFaceId` 删单条；否则按 `userFaceId` 判重后插入；同步完成后保存最大时间戳（只升不降）
- 响应：同 3.2 的 `UserFaceModelV2` 数组

### 3.4 上传人脸照片（预留，本版本未启用）

- **POST** `/nutrition/neglect/upload`（multipart/form-data，字段名 `file`）
- 响应 `data`：图片 URL（String）

### 3.5 新增人脸数据（预留，本版本未启用）

- **POST** `/nutrition/neglect/user/add-by-face`
- 请求体：`{ "url": "<图片URL>", "featureChar": "<特征Base64>" }`
- 响应 `data`：`UserFaceModelV2`（含服务端生成的 userFaceId / userId）

### 3.6 取餐盘时刻上报（预留，本版本未启用）

- **POST** `/nutrition/neglect/pickup/plate-pickup`
- 请求体：`{ "id": <用户id> }`
- 响应 `data`：主单 recordNo（String）
- 说明：吐盘机 5.0 在识别成功出盘后调用；开柜门版暂未启用，后端可先行保留

## 4. V1 开柜门业务接口（当前启用）

> 基础路径 `/terminal/neglect`，本设备核心业务流。

### 4.1 登录（获取餐盘用户信息）

- **POST** `/terminal/neglect/sideboard/app/getPlateBoxUserInfo`
- 请求体（LoginParam）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| equipmentId | Int | 设备 ID |
| faceId | String | 会员人脸 ID（人脸识别登录时传） |
| phone | String | 手机号（密码登录时传） |
| password | String | 密码（密码登录时传） |

- 调用时机：人脸识别成功（相似度 ≥ 0.8，3 秒防抖）/ 手机号密码登录

响应 `data`（EquipmentUserInfo）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | Long | 绑定记录主键（解绑时使用） |
| equipmentId | String | 设备 ID |
| equipmentCode | String | 设备编号 |
| equipmentBoxCode | String | 柜门/格子编号（**非空即执行开柜门**，转 Int 后下发串口） |
| faceId | String | 会员人脸 ID（非 null 表示已绑定餐盘） |
| plateNumber | String | 餐盘编号 |
| equipmentName | String | 设备名称 |
| orderNo | String | 订单号 |
| updateTime | String | 更新时间 |
| name / phone / faceUrl | String | 会员基础信息 |
| mealTime / mealTimeInterval | String | 就餐时段 |
| openTime / openTimeInterval | String | 开柜时段 |
| eatCount | Int | 就餐次数 |
| cardBalance | Double | 卡余额（≤0 弹余额不足提示并拦截） |

### 4.2 查询设备下的绑定列表

- **GET** `/terminal/neglect/sideboard/app/getYxMemberRefPlateByEquipmentCode`（设备编号走 `X-DEVICE-CODE` 头）
- 调用时机：管理员登录且未绑定格子时，取可绑定的空格子
- 响应 `data`：EquipmentUserInfo 数组

### 4.3 餐盘绑定

- **POST** `/terminal/neglect/sideboard/app/plateBinding`
- 请求体（BindParam）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| equipmentId | String | 设备 ID |
| equipmentCode | String | 设备编号 |
| equipmentBoxCode | String | 格子编号 |
| memberId | String | 会员 ID |
| faceId | String | 会员人脸 ID |
| plateNumber | String | 餐盘编号 |

- 响应 `data`：EquipmentUserInfo

### 4.4 餐盘解绑

- **POST** `/terminal/neglect/sideboard/app/plateUnbind`（form-urlencoded）
- 参数：`id`（Long，绑定记录主键）
- 响应 `data`：无

### 4.5 会员模糊搜索

- **POST** `/terminal/neglect/common/app/getUserInfoByNameOrPhone`
- 请求体：`{ "pageNum": 0, "pageSize": 0, "name": "张", "phone": "138..." }`
- 响应 `data`（Member 数组）：`id`、`faceId`、`name`、`phone`
- 调用时机：管理界面按姓名/手机号搜索会员

### 4.6 按餐盘号查询（扫描枪）

- **GET** `/terminal/neglect/sideboard/app/getMemberRefPlateByPlateNumber?plateNumber=xxx`
- 响应 `data`：EquipmentUserInfo
- 调用时机：扫描枪扫餐盘码

## 5. 已停用的 V1 旧接口（可下线）

以下接口在本次人脸体系切换（V2）后**设备端已无调用**，后端对齐时可安排下线：

| 接口 | 路径 |
| --- | --- |
| 旧人脸缓存（V1） | POST `/terminal/neglect/common/app/faceFeature/list` |
| 旧人脸增量（V1） | POST `/terminal/neglect/common/app/faceFeature/increment/list` |
| 旧设备配置（V1） | GET `/terminal/neglect/common/app/getYxEquipmentByEquipmentCode` |

## 6. 设备端业务主流程（供对照）

1. 启动 → 拉取设备配置（V2 3.1，注入虹软激活参数、BaseUrl）
2. 首次启动全量拉取人脸（V2 3.2，分页递归重建本地库）
3. 进入人脸识别登录页，每 5 分钟增量同步（V2 3.3）
4. 人脸识别成功（阈值 0.8）→ 登录接口（V1 4.1）查会员与绑定信息
5. 已绑格子（equipmentBoxCode 非空）→ 串口开柜门 → 跳转结果页
6. 余额不足（cardBalance ≤ 0）→ 弹窗拦截
7. 管理员路径：搜索会员（4.5）/ 扫描枪（4.6）→ 绑定（4.3）/ 解绑（4.4）格子