# 屋里咖啡咖啡机对接一期 - 联调与部署说明 (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 只保留环境参数：

```yaml
coffee:
  base-url: https://test.wulicoffee.com   # 生产切 https://www.wulicoffee.com
  timeout-millis: 10000
```

## 3. 设备登记(管理端 hard-manager)

1. 先执行 `db/20260918_add_hard_coffee.sql`(两张新表)。
2. 管理端添加字典 hard_type=13 咖啡机(见 dict_menu txt 文件)。
3. 设备管理新增设备: 类型=咖啡机(13), 设备唯一编号=屋里机器号(machine_name), 绑定商户。
4. 未登记的机器扫码会返回"咖啡机未接入平台"。

## 4. 部署顺序

1. 执行 SQL: `db/20260918_add_hard_coffee.sql` → 字典/菜单/third_key_manage 密钥(手工,`20260918_hard_coffee_dict_menu.txt`)。
2. 部署 **pjcloud-thirdparty-biz 先于 pjcloud-hardware-biz**(hardware 通过新增 Feign /third-key-manage/inner/get-by-biz-type 读密钥)。
3. 前端 H5 加 coffee-pay 页面(契约见 `20260918_hard_coffee_h5_api.md`)。
4. 在屋里测试环境发起一笔扫码支付联调,验证: 拉单 → 饭卡支付 → callback → 出餐 → 管理端订单/日志。

## 5. 运维要点

- 支付结果通知厂商失败: hard_coffee_order.wuli_notify_status=2,补偿任务每60秒重试,上限10次(超过需人工介入,管理端订单列表可见)。
- 退款同步: 管理端售后退款成功后自动按差额通知厂商(refund_sync_amount 记账),补偿任务回看近7天补推缺口。
- 生命周期日志: hard_coffee_log 按订单号/本地订单/设备关联,管理端"咖啡机订单详情"含完整时间线。
- 查单验签: 时间戳窗口±5分钟,appid 必须等于 coffee.query-app-id。