Integration Design · pay × jiu

pay 接入 jiu 授权续费 · 对接方案

让 jiu（岩美酒库）门店在应用内购买/续费授权：付款走 pay 收款中枢，付成功后 pay 回调 jiu，jiu 直接给该门店续期。

v1.0 · 2026-07-03 · 方案 B（付款直接续期门店）· server-to-server + 签名 webhook · 待评审

1. 背景与目标

pay 已是独立收款中枢（支付宝电脑网站支付 page.pay + 手机网站支付 wap.pay UA 自适应，已上线验证到账）。jiu 已有完整授权体系（License / LicenseCode / 兑换续期）。目标：把两者接起来——jiu 门店在应用内选套餐付款，付成功后无感自动续期，不再靠线下发兑换码。

2. 现状盘点

pay 现有对外接口

方法/路径	说明
`POST /api/v1/orders`	下单，返回 `pay_url`（UA 自适应 PC 扫码 / 手机拉 App）。当前只收 product_id，无业务标识、无鉴权
`GET /api/v1/orders/:out_trade_no`	查订单状态
`POST /api/v1/notify/{alipay,wechat}`	支付宝/微信异步回调（入账，已实现）

jiu 现有授权模型

模型	关键字段	语义
`License`	ShopID · Type(trial/monthly/annual/lifetime) · Tier · ExpiresAt · MaxDevices · IsActive	门店当前授权状态
`LicenseCode`	Code · DurationDays · Tier · Type · Status(unused/redeemed/void) · RedeemedShopID	兑换券：兑换时把 DurationDays 叠加到门店到期时间；一码一次

现有续期路径：平台生成码 → 用户获得 → 门店兑换。「购买」这步目前是线下/手动——本方案就是把它自动化。

3. 总体架构（方案 B）

用户(jiu 客户端, 已登录, 知道自己 shop) jiu 后端 pay 服务支付宝/微信 │ │ │ │ ①点“购买/续费”选套餐 ───────────────────────►│ │ │ │ ②建 purchase(pending) │ │ │ 调 pay 下单(biz_ref=shop_id, 签名) ───►│ │ │ │◄──── pay_url ────────────│ │ │◄──────────── 返回 pay_url ─────────────────│ │ │ ③打开 pay_url 付款(PC扫码/手机拉App) ───────────────────────────────────────────────────────────►│ │ │ ④收 notify → 入账 ✓ │ │ │◄─ ⑤pay 签名 webhook ─────│ │ │ ⑥验签+幂等 → 给 shop 续期(复用 license) │ │ │ 回 ack ────────────────────────────►│ │ ④'客户端刷新 → 已续期 ✓ │ │ │

为什么是 B：购买发生在已登录门店，jiu 天然知道是哪个 ShopID，付成功直接续期，用户无感，体验最好。

4. 数据模型改动

pay Order 加业务字段新增

字段	类型	说明
`BizSystem`	string(index)	业务来源，如 `jiu`；决定回调哪个 webhook / 用哪个密钥
`BizRef`	string	业务引用，jiu 传（如 `shop_id` 或 jiu purchase_id）；webhook 原样回传
`BizReturnURL`	string(可选)	付完跳回业务自己的页面；空则用 pay 默认结果页

pay Product 加稳定套餐码新增

BizCode（如 annual_standard）：webhook 回传给 jiu，jiu 按稳定码而非数字 product_id 映射权益，避免硬编码耦合。价格权威仍在 pay 套餐表。

pay BizNotifyLog 业务回调日志新增

记录每次向业务系统回调的 URL / payload / 响应 / 重试次数，用于排障与重放。

jiu Purchase 购买记录新增

字段	说明
ShopID · ProductBizCode · Amount	谁买、买什么、多少钱
OutTradeNo	pay 订单号（对账 + 幂等键）
Status(pending/paid/failed) · PaidAt	状态机

5. 接口契约

5.1 pay 下单接口扩展 `POST /api/v1/orders`

请求头带签名（见 §6）。Body 扩展：

{
  "product_id": 3,
  "biz_system": "jiu",
  "biz_ref": "shop_1024",
  "return_url": "https://jiu.51yanmei.com/license/result"   // 可选
}
Headers:
  X-Pay-System: jiu
  X-Pay-Timestamp: 1751520000
  X-Pay-Nonce: 8f3a...
  X-Pay-Sign: base64(HMAC-SHA256(secret, system+timestamp+nonce+body))

pay 校验签名 → 按 product_id 取服务端权威价格建单、存 biz 字段 → 返回 pay_url。

5.2 pay → jiu 业务 webhook（入账后主动推）

pay 在 applyPaid 成功后，按 order 的 biz_system 找到回调配置（URL+secret），POST：

POST {jiu 配置的回调 URL}
Headers: X-Pay-Timestamp, X-Pay-Nonce, X-Pay-Sign (HMAC-SHA256)
Body:
{
  "out_trade_no": "yanmei-20260703...-xxxx",
  "biz_system": "jiu",
  "biz_ref": "shop_1024",
  "product_biz_code": "annual_standard",
  "amount": "268.00",
  "trade_no": "20260703...",       // 支付宝/微信交易号
  "channel": "alipay",
  "paid_at": "2026-07-03T14:36:30+08:00"
}
期望响应：HTTP 200 + {"code":"SUCCESS"}；否则 pay 按退避重试

5.3 jiu 购买接口 `POST /api/v1/license/purchase`

鉴权=jiu 自己的登录态（当前用户/门店）。选套餐 → 建 Purchase(pending) → 调 pay §5.1 下单 → 返回 pay_url 给客户端。

5.4 jiu webhook 接收器 `POST /api/v1/pay/callback`

验签：用共享密钥校验 X-Pay-Sign + 时间戳窗口，确认真是 pay 发来的

幂等：按 out_trade_no 查 Purchase，已处理则直接回 SUCCESS

映射：product_biz_code → (duration_days, tier, type)

续期：给该 ShopID 延长授权（复用现有 license 服务：生成 LicenseCode 即兑换，或直接叠加 License.ExpiresAt）

回 ack：HTTP 200 + {"code":"SUCCESS"}；标记 Purchase=paid

6. 安全设计

共享密钥：jiu↔pay 各方向一对 HMAC 密钥，存 Bitwarden（如条目 pay-jiu webhook secret），部署经 rbw 灌环境变量，不落配置/仓库。
签名：HMAC-SHA256 覆盖 system+timestamp+nonce+body，防篡改。
防重放：timestamp 5 分钟窗口 + nonce 去重（拒绝过期/重复请求）。
幂等：两端都按 out_trade_no 唯一处理——pay 可能重发 webhook、jiu 只续一次。
价格权威：pay 按 product_id 取服务端价格，不信任传入金额（延续既有红线）。
传输：全程 HTTPS（jiu.51yanmei.com / pay.51yanmei.com 均已 HTTPS）。

7. 套餐映射

pay 套餐表持有价格（99/268/888/2280），每个套餐挂稳定 biz_code；jiu 侧一张映射表把 biz_code 翻成时长/档位：

pay product	biz_code	价格	jiu 续期（直接叠加 ExpiresAt）
月付·标准	`monthly_standard`	¥299	+30 天, tier=standard, type=monthly
月付·高级	`monthly_pro`	¥599	+30 天, tier=pro, type=monthly
年付·标准	`annual_standard`	¥2999	+365 天, tier=standard, type=annual
年付·高级	`annual_pro`	¥5999	+365 天, tier=pro, type=annual

权益差异（2026-07-03 已定，都是单店）：

档	客户端	仓库	图片分享	AI 商业分析
标准（299/2999）	2	单仓库	千张	—
高级（599/5999）	5	多仓库	万张	免费 AI 周/月度商业数据分析

pay 侧只透传 biz_code，不关心权益细节；权益→License(tier/max_devices/features) 的落地在 jiu 侧，见 jiu 仓 docs/pay支付对接开发指南.html。

8. 失败 / 重试 / 对账

webhook 失败重试：pay 对未收到 SUCCESS ack 的回调按退避重试若干次（如 1m/5m/30m/2h…），记 BizNotifyLog。
兜底查单：jiu 侧对 pending 超时的 Purchase 主动查 pay GET /orders/:out_trade_no 补偿（防 webhook 全丢）。
对账：pay orders 与 jiu purchases 按 out_trade_no 对齐，定期核对金额/状态。
用户已付但续期失败：webhook 重试 + 查单兜底应能自愈；仍失败则告警人工处理（钱已到，不可让用户吃亏）。

9. 分阶段实施计划

阶段 1 · pay 侧：Order 加 biz 字段 + Product 加 biz_code；下单接口收 biz + 签名鉴权；BizNotifyLog。

阶段 2 · pay 侧：入账后业务 webhook 推送 + 退避重试；回调配置（每个 biz_system 的 URL+secret）。

阶段 3 · jiu 侧：Purchase 模型 + 购买接口（调 pay 下单）。

阶段 4 · jiu 侧：webhook 接收器（验签+幂等+映射+续期，复用 license 服务）+ 查单兜底。

阶段 5：jiu 客户端购买/续费 UI；真实 1 分钱端到端联调；对账脚本。

10. 决策（2026-07-03 已定）

#	问题	决策
1	套餐定义	月 ¥299/¥599、年 ¥2999/¥5999（2 档 × 月/年，见 §7）。标准/高级权益差异待定
2	续期实现	直接叠加 `License.ExpiresAt`（不走生成兑换码）
3	biz_ref	jiu 的 `purchase_id`（利对账/多态）
4	付款后	跳回 jiu 结果页（return_url）
5	客户端形态	Web 入口 + App 入口都要；App 用内置 webview 打开 pay_url。付完 return_url 跳回；webview 内拉起支付宝 App 需处理 scheme 唤起/回跳

权益已定（见 §7 表）：标准=2 客户端/单仓库/千图；高级=5 客户端/多仓库/万图/AI 分析。
App webview 注意：应用内 webview 里跳支付宝需 scheme 白名单 / 拦截 alipays:// 唤起 App，付完靠 return_url 回跳 jiu 页面（比 PC 多一层客户端处理，Phase 5 联调）。

相关：支付宝收款页时序与架构 · 上线状态与部署 Runbook