feat(pay-v2): P8 Task2 PaidEvent.Kind + SubscriptionProvider + Stripe 订阅 Checkout/取消

internal/provider/provider.go

@@ -71,6 +71,22 @@ type CallbackInput struct {
 	Query   map[string]string
 }
 
+// EventKind — PaidEvent 的语义判别器(P8,设计 §5)。零值 EventPayment 是既有一次性/首期
+// 支付语义(P3 三渠道全落此),新增枚举全为 additive,不改变任何既有调用点的行为。
+type EventKind string
+
+const (
+	EventPayment              EventKind = "" // 默认:一次性/首期支付(向后兼容)
+	EventSubscriptionRenewal  EventKind = "subscription_renewal"
+	EventSubscriptionPastDue  EventKind = "subscription_past_due"
+	EventSubscriptionCanceled EventKind = "subscription_canceled"
+	EventChargeback           EventKind = "chargeback"
+)
+
+// RecurringKindGatewayScheduled — Capabilities.RecurringKind 取值之一:续费由渠道网关自身
+// 调度驱动(如 Stripe invoice.paid),pay 不主动发起 Charge(区别于 token_offsession)。
+const RecurringKindGatewayScheduled = "gateway_scheduled"
+
 // PaidEvent — verify_callback / query 的统一产出(设计 §4.1 → {order_ref,status,paid_amount})。
 type PaidEvent struct {
 	ProviderRef     string
@@ -79,6 +95,14 @@ type PaidEvent struct {
 	PaidCurrency    string
 	Raw             string
 	PaidAt          *time.Time // 渠道报的支付时间;nil 则 settle 用收到时间,对账时两边时间才对得上
+
+	// 以下均可选(P8,零值=旧行为):
+	Kind               EventKind // 事件语义判别器,零值=既有一次性支付
+	SubscriptionRef    string    // 渠道订阅号(checkout.completed 诞生 / invoice / deleted 反查)
+	InvoiceRef         string    // 续费期次唯一号(renewal attempt 的 provider_ref)
+	DisputeRef         string    // 拒付号
+	ProviderPaymentRef string    // 拒付关联的 PaymentIntent id
+	OutTradeNo         string    // 拒付解析出的原单号(可空)
 }
 
 // QueryRequest — Provider.Query 入参:尝试的完整上下文快照,不是裸 provider_ref。
@@ -125,6 +149,16 @@ type RecurringProvider interface {
 	CancelAgreement(ctx context.Context, agreementRef string) error
 }
 
+// SubscriptionProvider — 可选:渠道网关自身调度续费(RecurringKindGatewayScheduled,如
+// Stripe Checkout mode=subscription)的 Provider 额外实现。与 RecurringProvider(pay 主动
+// Charge 的 token_offsession 类)不同:订阅号在用户完成收银台支付后才诞生,续费由渠道
+// webhook(invoice.paid)驱动,pay 只负责建单与取消。
+type SubscriptionProvider interface {
+	Provider
+	CreateSubscriptionCheckout(ctx context.Context, req CreateRequest) (*Session, error)
+	CancelSubscription(ctx context.Context, providerSubRef string) error
+}
+
 // Registry — 方法名 → Provider(设计 §2 Provider adapter 注册表)。启动期注册,运行期只读。
 type Registry struct{ providers map[string]Provider }