feat(v2): outbox 退款感知(refund_id 进唯一键)+ 投递门禁放行退款态 + Enqueue 贯通 refundID

internal/model/v2.go

@@ -32,12 +32,24 @@ const (
 type RefundStatus string
 
 const (
-	RefundRequested  RefundStatus = "requested"
-	RefundProcessing RefundStatus = "processing"
-	RefundSucceeded  RefundStatus = "succeeded"
-	RefundFailed     RefundStatus = "failed"
+	RefundRequested     RefundStatus = "requested"
+	RefundProcessing    RefundStatus = "processing"
+	RefundSucceeded     RefundStatus = "succeeded"
+	RefundFailed        RefundStatus = "failed"
+	RefundManualPending RefundStatus = "manual_pending" // crypto 自托管:待运营人工 sweep 退款
 )
 
+// Settled 报告订单是否「已真正收到过钱」(paid 及其后的退款态)。webhook 投递门禁用:
+// 只有已结算订单的 outbox 才放行——payment 事件挡住崩溃窗口里的未付单,refund 事件
+// 则因订单已 paid 过而正常放行(不会因订单转入退款态被卡)。
+func (s OrderStatusV2) Settled() bool {
+	switch s {
+	case OrderPaidV2, OrderRefundingV2, OrderPartRefundedV2, OrderRefundedV2:
+		return true
+	}
+	return false
+}
+
 // ---- 业务订单(购买账本)----
 
 type OrderV2 struct {

internal/model/v2_test.go

@@ -33,3 +33,17 @@ func TestV2Migrate(t *testing.T) {
 		t.Fatalf("got %+v", got)
 	}
 }
+
+func TestOrderStatusSettled(t *testing.T) {
+	settled := []model.OrderStatusV2{model.OrderPaidV2, model.OrderRefundingV2, model.OrderPartRefundedV2, model.OrderRefundedV2}
+	for _, s := range settled {
+		if !s.Settled() {
+			t.Fatalf("%s should be settled", s)
+		}
+	}
+	for _, s := range []model.OrderStatusV2{model.OrderCreatedV2, model.OrderPendingV2, model.OrderCanceledV2, model.OrderExpiredV2} {
+		if s.Settled() {
+			t.Fatalf("%s should NOT be settled", s)
+		}
+	}
+}

internal/model/webhook_delivery.go

@@ -1,11 +1,12 @@
 package model
 
-// WebhookDelivery 是 pay→业务方 webhook 的 outbox(v2)。unique(out_trade_no,event_type)
-// 保证同一订单同一事件只入队一次(幂等);后台 Notifier 扫 Delivered=false 重试兜底。
+// WebhookDelivery 是 pay→业务方 webhook 的 outbox(v2)。unique(out_trade_no,event_type,refund_id)
+// 保证同一订单同一事件(同一退款单)只入队一次(幂等);后台 Notifier 扫 Delivered=false 重试兜底。
 type WebhookDelivery struct {
 	Base
 	OutTradeNo string `gorm:"size:64;not null;uniqueIndex:uq_delivery" json:"out_trade_no"`
 	EventType  string `gorm:"size:32;not null;uniqueIndex:uq_delivery" json:"event_type"`
+	RefundID   string `gorm:"size:64;uniqueIndex:uq_delivery" json:"refund_id,omitempty"` // 退款事件的幂等维度;payment 事件为空
 	BizSystem  string `gorm:"index;size:32" json:"biz_system"`
 	Payload    string `gorm:"type:text" json:"payload"` // 已序列化的领域 JSON(含 event_type)
 	Delivered  bool   `gorm:"index;default:false" json:"delivered"`