feat(api): 新增V2版本接口支持并集成至网络请求客户端

- 新增 ApiServiceV2 接口，支持人脸缓存、增量数据、设备配置等接口 - ApiClient 中新增 apiServiceV2 对象，复用 Retrofit 实例，调整超时时间至60秒 - DeviceInitActivity 改用 netViewModelV2 进行人脸缓存全量拉取及设备配置读取 - BaseActivity 新增对人脸增量同步接口调用，调用成功后刷新本地识别缓存 - BaseActivity 新增清空本地人脸库功能，异步清理数据库并刷新识别缓存 - FaceApi 增加清空本地人脸库接口，重写数据库操作逻辑 - 升级 lib_face 模块 Room 数据库版本，新增字段以支持多标识人脸实体扩展 - FaceEntity 实体扩展会员编号、用户ID、人脸ID、会员标识、更新时间等字段 - FaceDao 新增按人脸ID查询和删除接口，支持多重人脸数据操作 - 优化网络层 OkHttpClient 配置，简化拦截器写法及日志级别判断 - 升级 lib_face 模块支持 arm64-v8a 架构，增强兼容性 - 规范模块间依赖关系，统一版本管理及包路径声明 - 完善 CLAUDE.md 文档，补充项目架构、模块划分与开发流程说明
2026-08-18 17:14:06 +08:00
parent 5b8db65fa2
commit d53ea8f798
41 changed files with 1786 additions and 258 deletions
@@ -0,0 +1,211 @@
+# 智能餐盘柜（开柜门版）业务接口对齐文档
+
+> 版本：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）格子