SmartPlateCabinet/餐盘柜-API文档.md

餐盘柜设备端 API 文档

更新时间：2026-09-09 ｜ 服务：platform-nutrition（端口 24810）

一、通用约定

1. 路径与鉴权

• 所有接口路径前缀为 /nutrition，在 Nacos 白名单 /nutrition/neglect/** 下，无需登录 token
• 设备上下文统一靠请求头 X-DEVICE-CODE 解析（值为终端管理的设备编码），请求体无需传 deviceCode

2. 统一响应结构

{ "code": "00000", "msg": "操作成功", "data": { }, "total": 0 }

字段	类型	说明
code	string	00000 成功；99999 等为失败
msg	string	失败时直接展示给设备端（业务异常中文提示）
data	object/array	业务数据
total	int	分页接口返回总条数，非分页为 0

3. 数据类型说明

• 所有 id（Long）序列化为字符串，防止精度丢失
• 金额为 BigDecimal，按原样输出（不转科学计数法）
• 时间格式 yyyy-MM-dd HH:mm:ss，日期 yyyy-MM-dd

4. 收费模式 chargeType

值	含义	price
1	按餐计费	有值（元/份）
2	称重计费	null
3	免费	null

---

二、接口明细

1. 获取设备绑定用户列表

GET /nutrition/neglect/sideboard/app/getYxMemberRefPlateByEquipmentCode

返回当前设备（按 X-DEVICE-CODE）全部格子，按格子序号升序。

返回 data：数组

字段	类型	说明
id	string	绑定记录id（解绑时使用）
equipmentId	string	设备id（nut_terminal.id）
equipmentName	string	设备名称
equipmentCode	string	设备编码
equipmentBoxCode	string	格子编号（1..N）
faceId	string	绑定用户id（=nut_user.id），空格子为 null
plateNumber	string	餐盘号，空格子为 null
orderNo	int	格子排序号
name	string	用户姓名（未绑定为 null）
phone	string	用户手机号（未绑定为 null）
faceUrl	string	预留，人脸头像
mealTime	string	就餐时间（预留）
openTime	string	最近开柜绑定时间
updateTime	string	更新时间
eatCount	int	预留

示例

{
  "code": "00000", "msg": "操作成功", "total": 0,
  "data": [
    { "id": "1948000001", "equipmentId": "1001", "equipmentName": "1号餐盘柜",
      "equipmentCode": "DEV-PLATE-CABINET-01", "equipmentBoxCode": "1",
      "faceId": "10001", "plateNumber": "PLATE-001", "orderNo": 1,
      "name": "张三", "phone": "138****0001", "faceUrl": null,
      "mealTime": null, "openTime": "2026-09-04 11:20:00",
      "updateTime": "2026-09-04 11:20:00", "eatCount": 0 }
  ]
}

---

2. 餐盘绑定

POST /nutrition/neglect/sideboard/app/plateBinding

入参（JSON 请求体）

字段	类型	必填	说明
equipmentBoxCode	string	是	目标格子编号
faceId	long	是	用户id（用户搜索接口返回的 faceId）
plateNumber	string	是	餐盘号
equipmentId / equipmentCode	-	否	兼容旧项目的冗余字段，后端以请求头为准

{ "equipmentBoxCode": "1", "faceId": 10001, "plateNumber": "PLATE-001" }

处理规则

1. 目标格子已绑定用户 → 报错「当前柜子已绑定用户」
2. 餐盘号已被其他用户绑定 → 报错「当前柜子已绑定用户」
3. 用户不存在或不是会员（is_vip≠1）→ 报错「用户查询失败」
4. 用户已绑定其他格子 → 自动释放旧格子并重建空格
5. 成功返回 Result<Void>，同时记录开柜时间

---

3. 餐盘解绑

POST /nutrition/neglect/sideboard/app/plateUnbind

⚠️ 与旧项目不同：参数在 JSON 请求体，不是 QueryString

入参（JSON 请求体）

字段	类型	必填	说明
id	long	是	绑定记录id（列表接口返回的 id）

{ "id": 1948000001 }

错误：记录不存在 → 「绑定记录不存在」。成功后原格子重建为空格。

---

4. 用户信息模糊搜索

POST /nutrition/neglect/common/app/getUserInfoByNameOrPhone

按姓名或手机号模糊搜索会员（仅 is_vip=1 且状态正常），不按食堂过滤。

入参（JSON 请求体）

字段	类型	必填	说明
name	string	否	姓名模糊
phone	string	否	手机号模糊（name/phone 至少一个）
pageNum	int	否	默认 1
pageSize	int	否	默认 10，最大 500

返回 data：数组（total 为总条数）

字段	类型	说明
id	string	用户id
faceId	string	同 id（键名对齐旧项目）
name	string	姓名
phone	string	手机号

{
  "code": "00000", "msg": "操作成功", "total": 1,
  "data": [ { "id": "10001", "faceId": "10001", "name": "张三", "phone": "13800000001" } ]
}

---

5. 通过餐盘号获取信息

GET /nutrition/neglect/sideboard/app/getMemberRefPlateByPlateNumber?plateNumber=PLATE-001

用户刷餐盘取餐时调用；cardBalance 为真实账户余额：余额 > 0 可开柜，负数提示用户充值。

返回 data

字段	类型	说明
equipmentId	string	设备id
equipmentName	string	设备名称
equipmentCode	string	设备编码
id	string	绑定记录id
equipmentBoxCode	string	格子编号
updateTime	string	更新时间
plateNumber	string	餐盘号
faceId	string	绑定用户id，未绑定为 null
name	string	用户姓名，未绑定为 null
phone	string	用户手机号，未绑定为 null
cardBalance	number	账户真实余额（元）；未绑定/无账户为 null

错误：餐盘号为空 → 「餐盘号不能为空」；查无绑定 → 「未找到餐盘绑定信息」

{
  "code": "00000", "msg": "操作成功", "total": 0,
  "data": {
    "equipmentId": "1001", "equipmentName": "1号餐盘柜", "equipmentCode": "DEV-PLATE-CABINET-01",
    "id": "1948000001", "equipmentBoxCode": "1", "updateTime": "2026-09-04 11:20:00",
    "plateNumber": "PLATE-001", "faceId": "10001", "name": "张三", "phone": "13800000001",
    "cardBalance": 25.50
  }
}

---

6. 通过用户ID获取信息

GET /nutrition/neglect/sideboard/app/getMemberRefPlateByUserId?userId=10001

人脸识别匹配到 userId 后调用；查询当前设备上该用户绑定的餐盘/格子，cardBalance 为真实账户余额：余额 > 0 可开柜，负数提示用户充值。

返回 data（字段同「通过餐盘号获取信息」）

字段	类型	说明
equipmentId	string	设备id
equipmentName	string	设备名称
equipmentCode	string	设备编码
id	string	绑定记录id
equipmentBoxCode	string	格子编号
updateTime	string	更新时间
plateNumber	string	餐盘号
faceId	string	绑定用户id
name	string	用户姓名
phone	string	用户手机号
cardBalance	number	账户真实余额（元）

错误：用户ID为空 → 「用户ID不能为空」；查无绑定 → 「未找到用户绑定信息」

{
  "code": "00000", "msg": "操作成功", "total": 0,
  "data": {
    "equipmentId": "1001", "equipmentName": "1号餐盘柜", "equipmentCode": "DEV-PLATE-CABINET-01",
    "id": "1948000001", "equipmentBoxCode": "1", "updateTime": "2026-09-04 11:20:00",
    "plateNumber": "PLATE-001", "faceId": "10001", "name": "张三", "phone": "13800000001",
    "cardBalance": 25.50
  }
}

---

7. 获取扣费规则

GET /nutrition/neglect/sideboard/app/getChargeRuleByEquipmentCode

键名对齐旧项目 getRegionRuleByEquipmentCode。按「终端绑定餐线 → 今天星期 × 当前时段餐次」查询收费模式矩阵（nut_canteen_line_charge）。

返回 data

字段	类型	说明
chargeType	int	1按餐计费 / 2称重计费 / 3免费
price	number	仅 chargeType=1 时有值（元/份）

规则

• 终端未绑定餐线 / 餐线停用 / 当日当餐未配置 → 默认返回 chargeType=2（称重计费）
• 餐次时段：早餐 06:00-10:00 / 午餐 10:00-14:00 / 加餐 14:00-16:00 / 晚餐 16:00-20:00（全局统一）
• 按餐计费的扣费由后端定时任务完成：该餐次取餐结束（最后一条取餐记录 15 分钟后）统一按份扣余额，硬件无需在取盘时扣款，仅需按 cardBalance > 0 判断是否开柜
• 余额不足会扣成负数（后续充值回补），负余额即提示充值

{ "code": "00000", "msg": "操作成功", "total": 0, "data": { "chargeType": 1, "price": 15.00 } }

---

三、错误响应示例

{ "code": "99999", "msg": "当前柜子已绑定用户", "data": null, "total": 0 }

业务校验失败的 msg 为中文提示，可直接在设备端展示；参数校验失败（缺必填字段）返回 PARAM_ERROR。