江苏金斯瑞取餐柜回调联调包

生成日期：2026-05-28 适用项目：江苏金斯瑞智慧营养健康餐厅（zhct_jsr） 接收方：张帅、设备厂商联调工程师基于：issue.md 排查结论

一、问题结论

2026-05-27 订单 260527105928221 取餐柜存餐完成后，手机端订单状态未变更为”已存餐”。

排查结论：取餐柜设备的前置校验/存取回调请求从未到达 zhct_jsr 服务端。

依据： - 服务端 API 日志表 ydy_locker_pickup_api_log 当天无新增记录。 - 阿里云 SLS 日志全天命中 lockerPickup 接口 0 次。 - 订单支付、小票打印、小程序查询链路均正常，证明服务端可用。

最可能原因：取餐柜功能设置中的回调地址配置错误（例如仍指向测试环境、旧域名，或缺少 /api/lockerPickup 路径）。

二、两条正确回调地址

用途	完整地址
存餐前置校验	`https://jsr.yyangpt.cn/api/lockerPickup/verify`
存取餐回调通知	`https://jsr.yyangpt.cn/api/lockerPickup/callback`

重点核查：请确认设备端配置的不是以下任何错误地址： - ❌ http://jsr.yyangpt.cn/...（缺少 HTTPS） - ❌ https://saidi.yyangpt.cn/...（其他客户域名） - ❌ https://zlss.yyangpt.cn/...（其他客户域名） - ❌ https://jsr.yyangpt.cn/lockerPickup/...（缺少 /api 前缀） - ❌ 任何测试环境 IP 或内网地址 - ❌ 任何包含端口号的地址（如 :8080）

三、必传参数速查

3.1 存餐前置校验 — POST `/api/lockerPickup/verify`

参数	类型	必填	说明	示例
`action`	String	✅	固定 `Save`	`Save`
`order`	String	✅	系统订单号	`260527105928221`
`device`	String	✅	设备序列号 / sn	`00060`
`code`	String	否	取餐号	`003`
`user`	String	否	用户 ID	`88`
`sign`	String	否	签名（若设备端关闭了签名则不需要）	—

3.2 存取餐回调通知 — POST `/api/lockerPickup/callback`

参数	类型	必填	说明	示例
`action`	String	✅	`Save` / `TakeByCode` / `Cancel`	`Save`
`order`	String	✅	系统订单号	`260527105928221`
`device`	String	✅	设备序列号 / sn	`00060`
`resultCode`	String	✅	结果码，`0` 或 `200` 表示成功	`200`
`code`	String	否	取餐号	`003`
`user`	String	否	用户 ID	`88`
`cellNo`	String	否	柜门格口编号	`5`
`num`	String	否	格口数量	`1`
`resultMsg`	String	否	结果说明	`存餐成功`
`timestamp`	String	否	厂商时间戳	`1779277312`
`sign`	String	否	签名	—

3.3 action 取值对照

action	含义	用于
`Save`	存餐	前置校验 + 存餐回调
`TakeByCode`	取餐	取餐回调
`Cancel`	撤餐	撤餐回调

四、最小 curl 请求示例

以下示例可直接在取餐柜所在网络环境的终端中执行，验证到服务端的连通性。

4.1 连通性测试（仅验证网络可达）

curl -v -X POST https://jsr.yyangpt.cn/api/lockerPickup/verify \
  -H "Content-Type: application/json" \
  -d '{"action":"Save","order":"260527105928221","device":"00060","code":"003"}'

预期结果： - HTTP 状态码：200 - JSON 响应：{"result":true,"msg":""} 或 {"result":false,"msg":"..."}（只要是 JSON 即证明链路可达）

4.2 存餐回调通知（模拟存餐完成后通知）

curl -v -X POST https://jsr.yyangpt.cn/api/lockerPickup/callback \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Save",
    "order": "260527105928221",
    "code": "003",
    "device": "00060",
    "cellNo": "5",
    "num": "1",
    "resultCode": "200",
    "resultMsg": "存餐成功",
    "timestamp": "1779277312"
  }'

预期结果： - HTTP 状态码：200 - JSON 响应：{"result":true,"msg":""} - 服务端 ydy_locker_pickup_api_log 表新增一条记录 - 手机端订单状态从”未存餐”变更为”已存餐”

4.3 取餐回调通知（模拟取餐完成后通知）

curl -v -X POST https://jsr.yyangpt.cn/api/lockerPickup/callback \
  -H "Content-Type: application/json" \
  -d '{
    "action": "TakeByCode",
    "order": "260527105928221",
    "code": "003",
    "device": "00060",
    "cellNo": "5",
    "num": "1",
    "resultCode": "200",
    "resultMsg": "取餐成功",
    "timestamp": "1779277381"
  }'

五、厂商必须回传的 HTTP 日志字段

请设备厂商提供 2026-05-27 订单 260527105928221 存餐动作的 HTTP 请求日志，每条至少包含：

字段	说明	示例
请求时间	存餐动作发起的精确时间（含秒）	`2026-05-27 10:01:XX`
请求 URL	实际发出的完整 URL（含协议和路径）	`https://jsr.yyangpt.cn/api/lockerPickup/callback`
请求方法	HTTP 方法	`POST`
请求头 Content-Type	内容类型	`application/json`
请求体	实际发出的完整 JSON body	`{"action":"Save","order":"260527105928221",...}`
HTTP 状态码	服务端返回的状态码	`200` / `404` / `502` / 无响应
响应体	服务端返回的完整响应内容	`{"result":true,"msg":""}`
失败原因	若请求未成功，记录错误信息	`超时` / `DNS 解析失败` / `TLS 握手失败` / `连接拒绝`
DNS 解析结果	域名解析到的 IP 地址	`101.200.165.56`

六、现场连通性检查步骤

在取餐柜所在网络环境中逐项验证（可用同一网络下的笔记本或调试终端）：

步骤 1：验证 DNS 解析

nslookup jsr.yyangpt.cn
# 或
dig jsr.yyangpt.cn

预期：应解析到有效的公网 IPv4 地址（例如 101.200.165.56）。

步骤 2：验证 HTTPS 端口可达

curl -v --connect-timeout 10 https://jsr.yyangpt.cn/ 2>&1 | head -30

预期：TLS 握手成功，返回 HTTP 响应（状态码不限，只要能建立连接即可）。

步骤 3：验证前置校验接口

curl -v --connect-timeout 10 -X POST https://jsr.yyangpt.cn/api/lockerPickup/verify \
  -H "Content-Type: application/json" \
  -d '{"action":"Save","order":"260527105928221","device":"00060","code":"003"}'

预期：HTTP 200，JSON 响应包含 "result" 字段。

步骤 4：模拟存餐回调通知

curl -v --connect-timeout 10 -X POST https://jsr.yyangpt.cn/api/lockerPickup/callback \
  -H "Content-Type: application/json" \
  -d '{"action":"Save","order":"260527105928221","code":"003","device":"00060","cellNo":"5","num":"1","resultCode":"200","resultMsg":"存餐成功","timestamp":"1779277312"}'

预期：HTTP 200，{"result":true,"msg":""}。回调成功后，服务端 ydy_locker_pickup_api_log 表会新增一条记录，手机端订单状态变为”已存餐”。

步骤 5：核对设备端功能设置

在取餐柜屏幕管理后台检查以下配置项：

配置项	期望值
前置校验地址	`https://jsr.yyangpt.cn/api/lockerPickup/verify`
存取回调地址	`https://jsr.yyangpt.cn/api/lockerPickup/callback`
存取餐自定义格式	`作为订单号`
签名开关	关（当前系统暂不校验 sign）

七、联调验证通过标准

以下三项全部满足即为联调通过：

✅ 取餐柜完成存餐后，厂商日志中看到 HTTP 200 响应，响应体为 {"result":true,"msg":""}。
✅ 服务端数据库 ydy_locker_pickup_api_log 新增一条回调记录。
✅ 手机端（小程序）打开对应订单详情，取餐状态显示为「已存餐」。

八、联系方式

联调过程中如遇问题，请联系：

张帅（项目实施）
研发（后端接口问题）