3.0 KiB
3.0 KiB
屋里咖啡咖啡机对接一期 - 联调与部署说明 (2026-09-18)
1. 角色与外部配置
我方平台 = 厂商文档中的"第三方支付服务商"。需要在屋里咖啡侧完成配置:
| 配置项 | 值 | 说明 |
|---|---|---|
| 支付跳转URL模板 | https://www.pjzhhq.cn/h5/#/pages/pay/coffee-pay?order_no=厂商单号参数 |
用户扫码打开我方H5(前端页面由前端仓库实现) |
| 我方提供的查单地址 | https://www.pjzhhq.cn/api/hard/hard-coffee/wuli/query-order |
文档3.4 queryOrder,POST form表单 |
| 向屋里申请 | 我方调 getOrder/callback/refund 的 appid/appkey(16位) | 录入 third_key_manage bizType=11 |
| 向屋里分配 | 厂商调我方 queryOrder 的 appid/appkey(16位) | 录入 third_key_manage bizType=12 |
2. 密钥与配置
密钥统一在 thirdparty 服务 third_key_manage 表维护（管理端「第三方密钥管理」录入或 SQL，模板见 20260918_hard_coffee_dict_menu.txt 第三节）：
| biz_type | 用途 | app_key | app_secret |
|---|---|---|---|
| 11 屋里咖啡 | 我方调 getOrder/callback/refund | 向屋里申请的 appid | 向屋里申请的 appkey(SHA1签名) |
| 12 屋里咖啡查单 | 厂商调我方 queryOrder 验签 | 我方生成并告知屋里的 appid | 我方生成的 appkey |
密钥为平台级全局唯一（跨租户读取），建议 tenant_id=1；修改后 hardware 侧最多延迟 5 分钟生效（本地缓存）。
Nacos 的 pjcloud-hardware-biz 只保留环境参数：
coffee:
base-url: https://test.wulicoffee.com # 生产切 https://www.wulicoffee.com
timeout-millis: 10000
3. 设备登记(管理端 hard-manager)
- 先执行
db/20260918_add_hard_coffee.sql(两张新表)。 - 管理端添加字典 hard_type=13 咖啡机(见 dict_menu txt 文件)。
- 设备管理新增设备: 类型=咖啡机(13), 设备唯一编号=屋里机器号(machine_name), 绑定商户。
- 未登记的机器扫码会返回"咖啡机未接入平台"。
4. 部署顺序
- 执行 SQL:
db/20260918_add_hard_coffee.sql→ 字典/菜单/third_key_manage 密钥(手工,20260918_hard_coffee_dict_menu.txt)。 - 部署 pjcloud-thirdparty-biz 先于 pjcloud-hardware-biz(hardware 通过新增 Feign /third-key-manage/inner/get-by-biz-type 读密钥)。
- 前端 H5 加 coffee-pay 页面(契约见
20260918_hard_coffee_h5_api.md)。 - 在屋里测试环境发起一笔扫码支付联调,验证: 拉单 → 饭卡支付 → callback → 出餐 → 管理端订单/日志。
5. 运维要点
- 支付结果通知厂商失败: hard_coffee_order.wuli_notify_status=2,补偿任务每60秒重试,上限10次(超过需人工介入,管理端订单列表可见)。
- 退款同步: 管理端售后退款成功后自动按差额通知厂商(refund_sync_amount 记账),补偿任务回看近7天补推缺口。
- 生命周期日志: hard_coffee_log 按订单号/本地订单/设备关联,管理端"咖啡机订单详情"含完整时间线。
- 查单验签: 时间戳窗口±5分钟,appid 必须等于 coffee.query-app-id。