From 266f4e83f3f93f76517b2550ab09f5d1ee225d85 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 9 Jul 2026 22:57:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(pay):=20=E6=9E=B6=E6=9E=84=E6=80=BB?= =?UTF-8?q?=E8=A7=88=E5=AD=97=E7=AC=A6=E7=94=BB=E6=8D=A2=E6=88=90=20SVG=20?= =?UTF-8?q?=E6=97=B6=E5=BA=8F=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 4 参与者 lifeline(客户端/控制面/Provider/外部平台)+ 14 条消息: 实线=请求(cyan)、虚线=返回(grey)、accent=异步(用户付款/webhook)、绿=paid。 含落库/render 分发/开通管线/Query 兜底 说明框。合规范式记入全局记忆 docs-diagrams-use-svg(文档图一律 SVG,禁字符画)。 Co-Authored-By: Claude Opus 4.8 --- docs/pay-orchestration-design.html | 110 +++++++++++++++++++++++++---- 1 file changed, 96 insertions(+), 14 deletions(-) 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 不变。只有一个对象会让"换渠道重试"污染状态机。