feat: 添加订单退款处理的异步任务及相关逻辑

backend/app/jobs/args/order_refund.go

@@ -0,0 +1,45 @@
+package args
+
+import (
+	"quyun/v2/providers/job"
+
+	. "github.com/riverqueue/river"
+	"go.ipao.vip/atom/contracts"
+)
+
+var _ contracts.JobArgs = OrderRefundJob{}
+
+// OrderRefundJob 表示“订单退款处理”的一次性异步任务。
+//
+// 设计说明：
+// - 该任务用于将订单从 refunding 推进到 refunded/failed（由 worker 执行核心退款逻辑）。
+// - 幂等由 River Unique + 业务侧 DB 幂等（ledger idempotency、状态机）共同保证。
+type OrderRefundJob struct {
+	// TenantID 租户ID（用于多租户隔离与唯一性维度）。
+	TenantID int64 `json:"tenant_id" river:"unique"`
+	// OrderID 订单ID（用于唯一性维度）。
+	OrderID int64 `json:"order_id" river:"unique"`
+
+	// OperatorUserID 退款操作人用户ID（租户管理员/系统），用于 worker 在必要时回填审计字段。
+	OperatorUserID int64 `json:"operator_user_id"`
+	// Force 是否强制退款（绕过时间窗）。
+	Force bool `json:"force"`
+	// Reason 退款原因（用于审计；worker 可用于补齐订单字段）。
+	Reason string `json:"reason"`
+}
+
+func (OrderRefundJob) Kind() string { return "order_refund" }
+
+func (a OrderRefundJob) UniqueID() string { return a.Kind() }
+
+func (OrderRefundJob) InsertOpts() InsertOpts {
+	return InsertOpts{
+		Queue:    job.QueueDefault,
+		Priority: job.PriorityDefault,
+		// 失败可重试；由 worker 判断不可重试的场景并 JobCancel。
+		MaxAttempts: 10,
+		UniqueOpts: UniqueOpts{
+			ByArgs: true,
+		},
+	}
+}