pay v2 · P2 收款管线 + Provider 抽象 + webhook v2 (阅读版)

Task 1 · Provider 抽象接口 + render_type + PaidEvent + 注册表

文件 internal/provider/provider.go。核心契约,P3 所有渠道 adapter 依赖它:

type Provider interface {
  Method() string
  Capabilities() Capabilities
  Create(ctx, CreateRequest) (*Session, error)
  VerifyCallback(ctx, CallbackInput) (*PaidEvent, error)
  Query(ctx, QueryRequest) (*PaidEvent, error)  // D4-A2:带尝试上下文快照,非裸 ref
}
// 可选子接口:RefundingProvider(P4)、RecurringProvider(P8)
type Session      struct { ProviderRef string; RenderType string; Payload map[string]any; ExpiresAt *time.Time }
type PaidEvent    struct { ProviderRef string; Status PaidStatus; PaidAmountMinor int64; PaidCurrency, Raw string; PaidAt *time.Time }
type QueryRequest struct { ProviderRef, OutTradeNo, AccountID string; AmountMinor int64; Currency string; CreatedAt time.Time; ExpiresAt *time.Time }

6 个 render_type 常量 + PaidPending/Succeeded/Failed;Registry(Register/Get/Methods + ErrUnknownMethod)。

Task 2 · fake provider(测试用)

internal/provider/fake/fake.go —— 实现 Provider,Method()=="fake"、render=crypto_address;带 SetQueryResult 测试 seam。P2 用它端到端验管线,不接真渠道。

Task 3 · OrderStore 扩展(查询)

internal/store/order_query.go:GetOrder / AttemptByProviderRef / ListAttemptsByStatus / ExpirePendingAttempts + 哨兵错误。为管线定位订单/尝试用。

Task 4 · 一次性收款管线 gateway

internal/gateway/gateway.go:CreateOrder(选 provider→create→落 Order+Attempt→返回 {order_no, session:{render_type,payload}})/ GetOrder / RetryOrder / CancelOrder。接口 ProductResolver.Resolve(sku)(取权威价/币种/subject/bizCode)、WebhookEnqueuer.Enqueue(...)。

Task 5 · 统一入账/开通管线 settle

internal/gateway/settle.go:Settle(ctx, *PaidEvent) = 归一 → 定位(provider_ref→attempt→order)→ 币种/金额核对 → 先幂等入队 payment.succeeded,再复用 P1 MarkAttemptPaid 幂等翻转(D4-A1 崩溃安全顺序:不变量「paid ⇒ outbox 行存在」,入队失败返回 SettleFailed 不翻转、渠道重投自愈)。HandleCallback(webhook 入口)、SyncPendingAttempts(query 兜底)都汇入这条。SettleResult:ignored/not_found/amount_mismatch/duplicate/processed/failed。paid_at 优先用渠道报的 PaidAt(D4-A3)。

Task 6 · webhook v2 outbox + Notifier

model.WebhookDelivery(uniqueIndex(out_trade_no,event_type) 幂等)+ store.WebhookStore(Enqueue/ListUndelivered/MarkDelivered/MarkFailed)+ webhook.Notifier(DeliverPending/Start,HMAC 头 X-Pay-System/Event/Timestamp/Nonce/Sign,失败重试)。event_type 从 payment.succeeded 起。投递门禁(D4-A1 另一半):发前确认订单已付,防把"未付单"通知出去。

Task 7 · HTTP /api/v2 接线

router.SetupV2 挂 POST /api/v2/orders、GET /api/v2/orders/:no、.../retry、.../cancel、POST /api/v2/callback/:method(D3:与旧版统一 /api 前缀;POST /api/v1/orders 被旧契约占用无法共存,P3 渠道迁入后删除整组 /api/v1 收口为一套);main.go 装配 provider 注册表 + gateway + notifier(含投递门禁闭包),AutoMigrate 加 WebhookDelivery。