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 统一响应格式

{
  "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）格子