biz-api-cloud-zax/db/20260918_hard_coffee_h5_api.md

咖啡机(屋里咖啡)H5支付页对接契约 - 一期饭卡支付

更新: 2026-09-18。页面已实现(biz_zax_app_cloud src/pages/pay/coffee-pay.vue),本文档保留为接口契约与行为说明。

1. 页面入口与二维码 URL

用户在咖啡机上选择饮品后,机器展示二维码,URL 由屋里咖啡后台配置,指向我方 H5:

https://www.pjzhhq.cn/h5/#/pages/pay/coffee-pay?order_no={厂商订单号}

• order_no: 厂商订单号,19 位数字(测试环境 18 位)。
• 屋里咖啡后台的「支付跳转 URL 模板」按上述地址配置,占位符拼接方式以屋里后台实际支持为准(联调时确认,若模板系统不支持 hash 路由带参需调整为 query 形式)。

2. 页面行为(biz_zax_app_cloud 已实现)

页面路由: /pages/pay/coffee-pay,pages.json 已注册(pages/pay 分包)。

必须登录: 页面 onLoad 检查登录态,未登录 toast 提示后跳转 /pages/root/login(登录后重新扫码进入)。所有支付走登录用户自己的饭卡钱包,无需输卡号。

页面流程:

1. 进入即调拉单接口,展示商品图片/名称/冷热/机器号/金额与支付倒计时(2分钟)。
2. 展示登录用户饭卡余额(钱包类型编码 1)。
3. 点击支付 → 确认弹窗 → 调支付接口 → 页内展示成功结果(支付人/支付后余额/取咖啡提示)。
4. 订单已支付(paid=true)展示已支付态;倒计时归零展示超时态,禁用支付。

3. 接口契约

网关前缀: https://www.pjzhhq.cn/api/hard。响应为统一 R<T> 结构,code != 0 时展示 msg。

3.1 拉取订单信息(匿名可用)

GET /api/hard/hard-coffee/order-info?orderNo={order_no}

字段	类型	说明
orderId	long	本地订单id,支付时回传
orderNo	string	厂商订单号
product / img / isCold	string	产品名/图片链接/1冷0热
price	int	价格(分)
priceYuan	string	价格(元,两位小数),直接展示
machineName	string	机器号
paid	boolean	是否已支付,true 时禁止再次支付
remainSeconds	long	支付剩余秒数(下单起2分钟),超时提示重新发起

3.2 饭卡支付(登录态,扣本人饭卡)

POST /api/hard/hard-coffee/wallet-pay
Content-Type: application/json
Authorization: Bearer {token}

{ "orderId": 1234567890 }

• 需登录(OAuth2),未登录返回 401/424 由移动端拦截器跳登录。
• 扣登录用户饭卡钱包(WalletTypeEnum.EAT),前置校验余额;失败原因见 msg(未开通饭卡/余额不足/订单已超时/订单已支付等)。

响应 data:

字段	类型	说明
orderId	long	本地订单id
orderNo	string	厂商订单号
name	string	支付人姓名
cardNo	string	饭卡卡号
balanceYuan	string	支付后余额(元)

3.3 卡号支付(匿名备用通道,默认不使用)

POST /api/hard/hard-coffee/card-pay     { "orderId": ..., "cardNo": ... }

保留作运维备用(卡号即扣,与消费机刷卡一致),正常流程走 3.2。

4. 注意事项

1. 前端固定 TENANT-ID:1,后端通过机器号自动定位设备租户,多租户无需前端处理。
2. 同一订单支付窗口 2 分钟,过期后在咖啡机重新发起生成新二维码。
3. 防重复提交由后端并发锁保证,前端支付按钮加 loading 即可。
4. 支付出餐由后端回调厂商完成,前端无需轮询(如需兜底可再调 3.1 查看 paid)。