diff --git a/docs/pay-orchestration-design.html b/docs/pay-orchestration-design.html index 9338619..dce23f7 100644 --- a/docs/pay-orchestration-design.html +++ b/docs/pay-orchestration-design.html @@ -79,20 +79,102 @@

边界(诚实说):客户端改动频率 = 新 render_type 出现频率(极低)+ OS scheme 白名单变化,不是 provider 频率。真正要碰客户端的只有:全新交互形态、拉起 App 的 scheme 白名单(Info.plist/manifest)、信用卡 3DS / Apple·Google Pay 的专有 SDK。

3. 架构总览

-
客户端(只认协议,不认平台) 控制面 :8080 编排层 外部平台 - GET /v1/pay/methods ─────────────▶ 下发启用渠道 [{id,name,icon,render_type}] - POST /v1/pay/orders {sku,method} ─▶ ┌─ Order(业务:谁/买啥/多少钱/开通什么) ← 真相源, order_no 幂等 - ◀── {order_no, session: │ └─ PaymentAttempt(一次尝试:provider/单号/状态) ← 支持换渠道重试 - {render_type,payload}} │ │ - 按 render_type 分发渲染: │ ▼ Provider 注册表 map[method]Provider - redirect → 开浏览器 │ ├─ crypto adapter ──▶ pangolin-pay(已部署) ──▶ TRON 链 - display_details→ 地址+金额卡片 │ ├─ nazha adapter ──▶ nzzf.org /api/pay/create ─▶ 支付宝 - GET /v1/pay/orders/{no} ──────────▶ │ └─ (未来) stripe / epay … 加 adapter,客户端零改 - ◀── {status} 轮询到 paid │ - │ 统一开通管线:验签(adapter)→定位订单→幂等→金额核对→开通订阅(source=pay) - ┌────────────────────────────────────┤◀── POST /v1/webhooks/pay/crypto (pangolin-pay, HMAC) - │ 所有形态最终都收敛到"轮询到 paid" │◀── GET /v1/webhooks/pay/nazha (哪吒, RSA, 注意是 GET) - └────────────────────────────────────┘ 兜底:Query 主动查单(crypto 靠链上轮询;哪吒回调可能被 GFW/CF 吞)
+
+ + + + + + + + + + + + + + + + + + 客户端Flutter 四端 + + 控制面编排层 :8080 + + Provider适配器 + + 外部平台pangolin-pay · 哪吒 + + + GET /v1/pay/methods + + + 启用渠道 [{id,name,render_type}] + + + POST /v1/pay/orders {sku, method} + + + + 落库 Order（谁/买啥/几天）+ Attempt（provider/单号） + + adapter.Create(order) + + + 下单（/order | /pay/create） + + + 地址+金额 | payurl + + + Session{render_type, payload} + + + {order_no, session} + + + + 客户端按 render_type 渲染：redirect→浏览器 / display_details→地址卡 + + 用户付款（链上转账 | 支付宝跳转） + + + 轮询 GET /v1/pay/orders/{no} + + + pending… + + + webhook：/webhooks/pay/crypto(HMAC) | /nazha(RSA·GET) + + + + 验签 → 定位订单 → 幂等 → 金额核对 → 开通订阅（source=pay） + + GET /v1/pay/orders/{no} + + + paid ✓ 已开通 + + + + 兜底：控制面 →(Query 主动查单) 外部平台 —— crypto 靠链上轮询；哪吒回调可能被 GFW/CF 吞 + +

为什么 Order 与 PaymentAttempt 拆两层:同一笔订单,用户可能先扫哪吒超时、再换 crypto 付成功。换渠道 = 新建一个 Attempt,Order 不变。只有一个对象会让"换渠道重试"污染状态机。