Pangolin 统一支付编排层设计

支付方式无关(provider-agnostic)架构 · client↔控制面协议固定 · 加渠道不改客户端 · 2026-07-09

📋 实现计划:P1 数据层 + 开通重构(7 阶段之一;P2–P7 落地前逐一细化)。本文档是全景蓝图,计划是逐步施工图。

1. 背景与目标

Pangolin 当前没有 App 内支付:用户变 pro 的唯一路径是兑换激活码(POST /v1/redeem),客户端"购买"卡片是 onTap: () {} 空实现。控制面没有订单系统(migration 000001–000021 无 orders/payment 表),只有 codes 激活码履约。这是一块绿地。

目标:

• client(Flutter 四端)与 pangolin 控制面之间的支付协议固定,底层支付平台可插拔。
• 首批接入 加密货币(USDT-TRC20) 与 哪吒聚合支付(支付宝) 两条渠道。
• 未来接 Stripe / 信用卡 / epay 等尽量不改客户端。
• 支付成功 → 自动给用户开通订阅(复用现有订阅/权益模型)。

2. 可行性结论 可行

调研(Stripe next_action 模型 + 多 PSP 编排实践)确认:不同支付平台的交互形态是有限的,而平台是无限的。把形态收敛成客户端认识的 render_type 联合体,即可让客户端 provider 无关。

首批两渠道的形态都落在客户端已有能力上:

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

3. 架构总览

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

4. 数据模型

控制面新增两张表(mysql + sqlite 双套 migration,金额一律 int64 最小单位,禁 float)。

4.1 pay_orders — 业务订单(购买/权益账本)

建单时就把 order_no → user / plan / 天数 落库。回调只能推进已存在的订单、开通其中预先锁定的套餐——回调无法指定"给谁开多久"。这是防回调伪造的纵深。

4.2 pay_attempts — 支付尝试(收款账本)

⚠️ 超时挂在 attempt 上:某 attempt 超时只把它自己置 expired,order 仍 pending → 用户可再建 attempt 换渠道。order.expires_at 是整体购买窗口(较长,如 1h),到点才整单 expired。一笔 order 最多一个 attempt 能成功 —— MarkOrderPaid 只在 order=pending 时原子成立,paid 后续 attempt 全部失效。

4.3 两表分工与创建时机(一对多)

典型:用户买 pro-year 选哪吒 → 建 order + attempt#1(nazha);扫码超时 → attempt#1 expired,order 仍 pending;点「换 crypto」→ order 不变,新建 attempt#2(crypto);链上付款回调 → 按 provider_ref 定位 attempt#2 → 幂等 → order 与 attempt#2 一起置 paid、开通订阅。attempt#1 保留 expired 留痕。一笔 order 最多一个 attempt 成功(MarkOrderPaid 只在 order=pending 原子成立)。用户也可 POST /orders/{no}/cancel 主动取消(pending→canceled),取消单仍在订单列表可见。拆两层:换渠道重试不污染订单状态机 + 订单是开通谁的唯一真相。

4.4 SKU 目录 + 定价 已定

SKU → (plan, 天数, 各币种价格)。哪吒收人民币(支付宝)、crypto 收 USDT,故按币种各定一价(不做实时汇率换算,固定价是产品决策)。首版 SKU 目录作为控制面代码常量(后续可迁 DB)。

USDT 价与 CNY 价均已拍板。金额一律 int64 最小单位存(USDT 微单位 1e-6、CNY 分),哪吒 money 参数按元、2 位小数下发。

5. Provider 适配器接口

每个支付平台实现同一个接口,控制面只依赖接口。三个动作是最小完备集。

type Provider interface {
    Method() MethodInfo   // 元信息:{ID, Name, IconURL, RenderType, Currency, Enabled, Min, Max}
    Create(ctx, o Order) (Session, error)                       // ① 下单→返回渲染指令
    HandleCallback(ctx, r *http.Request) (CallbackResult, error) // ② 验签+解析+归一化
    Query(ctx, providerRef string) (PaymentStatus, *PaidEvent, error) // ③ 主动查单兜底
}

type Session struct {   // Create 的返回,客户端按 RenderType 分发
    ProviderRef string
    RenderType  string          // redirect / display_details / ...
    Payload     json.RawMessage // 按 RenderType 定 shape
    ExpiresAt   time.Time
}
type PaidEvent struct { OrderNo string; ProviderRef string; AmountMinor int64; Currency string; PaidAt time.Time; TxRef string }
type CallbackResult struct { Handled bool; Event *PaidEvent; AckBody []byte } // AckBody: 哪吒要回 "success"

5.1 crypto adapter(包裹已部署的 pangolin-pay)

pay-server 保持独立进程(持 xpub、看链,最小权限),控制面 crypto adapter 只是它的 HTTP 客户端:

• Create → POST pangolin-pay /order {user_ref=uuid, sku, amount=USDT微单位} → 得地址+精确金额 → render_type=display_details,provider_ref=pay 单号。
• HandleCallback → 需给 pay-server 新增出站 webhook:侦测到 paid → POST 控制面 /v1/webhooks/pay/crypto(HMAC 签名、失败重试)。
• Query → GET pangolin-pay /order/{provider_ref}(链上侦测无 webhook 时兜底)。

5.2 nazha adapter(哪吒聚合支付)

• Create → POST nzzf.org/api/pay/create,参数 pid / type=alipay / out_trade_no=尝试号 / notify_url / return_url / name / money=元 / timestamp / sign / sign_type=RSA,签名 SHA256WithRSA(商户私钥、参数 ASCII 升序拼 k=v&、Base64)→ 得 payurl → render_type=redirect,provider_ref=trade_no。
• HandleCallback → 哪吒以 GET 回调 notify_url,平台公钥 RSA 验签 → trade_status==TRADE_SUCCESS → PaidEvent;响应纯文本 success。
• Query → POST /api/pay/query,status==1 为已支付(回调可能被吞,轮询兜底)。
• 配置:pid + 商户 RSA 私钥 + 平台 RSA 公钥,走 Bitwarden/env。前置:你需在哪吒(Telegram 开户)拿到 pid 与密钥。

6. 客户端契约

6.1 REST 端点(控制面,全部 Bearer)

GET  /v1/pay/methods                 → 200 [{id,name,icon,render_type,currency,enabled,min,max}]
POST /v1/pay/orders {sku, method}    → 201 {order_no, status, session:{render_type,payload,expires_at}}
GET  /v1/pay/orders/{order_no}       → 200 {status, plan, expires_at, session?}
GET  /v1/pay/orders?limit&cursor     → 200 {orders:[{order_no,sku,plan,amount,currency,status,created_at,paid_at}], next} （历史订单含 canceled，用户中心订单页用）
POST /v1/pay/orders/{order_no}/retry {method} → 201 新 attempt/session(Order 不变)
POST /v1/pay/orders/{order_no}/cancel → 200 {status:"canceled"}（仅 pending 可取消；paid/已取消返 409）
--- 平台→控制面(公开,不带 Bearer)---
POST /v1/webhooks/pay/crypto         (pangolin-pay, HMAC 验签)
GET  /v1/webhooks/pay/nazha          (哪吒, RSA 验签, GET)

6.2 render_type 联合体(写死在协议里)

护栏:客户端遇到未知 render_type → 不显示该方法 / 提示"请升级 App"。无论哪种形态,客户端最终都收敛到同一个"轮询 GET /orders/{no} 到 paid"。

6.3 客户端改动:一次 vs 永不

7. 统一开通管线

webhook 与 Query 轮询最终都产出 PaidEvent,走同一条幂等开通逻辑:

7.1 复用并重构现有开通逻辑

开通能力现埋在 codes.Service.applySubscription(server/internal/codes/service.go:235),仅作为 Redeem 事务的一步、且 CreateSubscription 把 source 硬编码 'code'。改动:

• 抽出可复用、可传 source 的开通方法(codes.Redeem 与 pay 管线共用),避免两套开通逻辑漂移。
• subscriptions.source 的 CHECK 枚举现只允许 ('trial','code') → 加 'pay'(migration:sqlite 需表重建、mysql alter,双套)。
• 权益判定(EntitlementForUser)、/me、免费门 无需改——它们只看"最新未过期订阅",source 对它们透明。

8. 哪吒合规风险 务必知情

缓解 = 本架构天生解耦:哪吒只是一个 redirect adapter,将来换成持牌支付宝直连 / Stripe / epay,客户端零改、订单与开通逻辑零改,只换服务端一个 adapter。可"先用它跑量、随时替换",不锁死。crypto(USDT 自托管)作为干净主轨并存。

9. 错误处理与边界

• 回调不可信回跳:浏览器从 return_url 回来时支付结果未必已到,客户端不信任回跳,只认轮询到的 paid。
• webhook 可能丢:crypto 无 webhook(只链上侦测)、哪吒 GET 回调可能被 GFW/CF 吞 → Query 轮询兜底是刚需,不只依赖 webhook。
• 重复回调:UNIQUE(provider, provider_ref) + order granted 标记,已开通再来直接 200。
• 金额不符:crypto 付错金额进 pay 侧 orphan;哪吒金额核对不过则拒绝并告警,不开通。
• attempt 超时 ≠ order 关闭:单个 attempt 到自己的 expires_at 只置该 attempt expired,order 仍 pending,用户可继续换渠道;只有 order 整体窗口到点才整单 expired。
• 只有一个 attempt 能成功:MarkOrderPaid 原子守卫 order=pending,paid 后所有 attempt/retry 失效。
• 用户主动取消:POST /orders/{no}/cancel 仅在 pending 生效(→canceled);已 paid/已取消返 409。canceled 单仍在订单列表可见。取消后若链上迟到付款到账 → 进 orphan 人工处理。
• 订单过期/取消后到账:order 非 pending 则不自动开通,转人工对账(避免迟到付款误开/漏开)。
• 换渠道重试:新建 Attempt,老 Attempt 置 expired,Order 仍 pending。

10. 测试策略

• 控制面:adapter Create/Callback/Query 单测(mock 平台 HTTP);管线幂等(双回调→单开通)、金额不符拒绝、RSA/HMAC 验签通过/失败、开通重构(codes + pay 共用、source 正确)、Order/Attempt 状态机、方法发现。
• pay-server:出站 webhook 投递(签名、重试)单测。
• 客户端:render_type 分发 widget 测试;轮询到 paid;未知 render_type 降级。
• 端到端:两轨各跑一笔小额真链/真单。

11. 首版范围与实施阶段

范围:后端编排层 + crypto & 哪吒两 adapter + 四端 Flutter 统一支付页 + 用户中心订单历史页一次到位。实施在计划里分阶段:

1. 控制面:schema(pay_orders/pay_attempts)+ store + 开通重构 + source=pay migration。
2. Provider 抽象 + 注册表 + crypto adapter + pay-server 出站 webhook。
3. 哪吒 adapter(RSA 签/验、GET 回调、查单)。
4. 客户端 REST(methods/orders/list/retry/webhooks)+ 统一开通管线 + Query 轮询 worker。
5. Flutter 支付页(方法选择器 + render_type 分发 + 轮询)+ 接上购买入口。
6. 用户中心订单历史页(读 GET /v1/pay/orders,新增导航项;return_url 跳此)。
7. 端到端联调(两轨小额)。

12. 待确认清单(评审 gate)

实现计划:P1 数据层 + 开通重构（真相源 docs/superpowers/plans/2026-07-09-pay-orchestration-p1-schema-grant.md）。
相关文档:支付渠道选型总览 · 干净 USDT 方案 · 单地址收款模型 · 加密交易引擎