feat(退款分佣): 佣金回溯明细替换全额失效并补齐读侧与导出

用 PRD 2.14 语义整体替换退款佣金「整单全额失效」实现：原佣金保持已发放不变，
回溯事实落在新表 tb_commission_clawback_record 的负数、不可提现明细上。

- 新增成对迁移 000220 建 tb_commission_clawback_record，唯一约束
  (refund_id, original_commission_id) 为权威幂等键，附店铺+时间/原佣金/订单索引。
- 回溯用例（internal/service/refund/clawback.go）：准入仅由退款申请状态、审批异常
  标记与退款方式决定；金额按分整数计算，分母取冻结实收（缺失回落审批尝试）、
  分子原路取渠道成功金额，乘法用 math/big 中间量，舍入差自末条起向前补差；
  终态判据要求订单佣金已离开待计算且不存在 status IN (1,2,99) 的记录。
- 三层幂等：唯一约束兜底、佣金行行锁 + 钱包乐观锁、commission_deducted 仅作投影
  并带 WHERE commission_deducted = false 条件置位；闭合三结果为已回溯、无需回溯、
  审批异常转人工。
- 事务内顺序固定：锁提现申请行 → 锁尝试行 → 解冻冻结 → 置驳回 → 插回溯明细 →
  扣 balance（允许为负）→ 写负数流水 → 审计；删除旧全额失效写入与其两个审计调用点，
  refund.invalidate_commission 仅保留常量与注册供历史审计读取。
- 读侧：佣金明细列表 status 筛选透传，两表 UNION ALL 合并分页并以 source ASC 作
  末位次序键；新增佣金明细详情接口并同步路由与 OpenAPI 装配。
- 导出：新增 commission_record 场景（白名单、exporter 注册、DTO oneof、DataSource
  与列定义），粒度为佣金记录，原佣金与回溯各一行，金额保持分且可为负。
- 新增退款佣金回溯周期补偿任务（@every 1m / MaxRetry(3) / Timeout(10m) /
  Unique(10m)，独立队列），保留启动时补偿扫描，判据与既有实现一致。

Refs: AUG26-012

internal/model/commission.go

@@ -9,6 +9,7 @@ import (
 // CommissionRecord 佣金记录模型
 // 记录各级代理的佣金入账情况
 // 包含成本价差收入和一次性佣金两种佣金来源
+// 退款佣金回溯不改动本表：原佣金保持已发放，回溯事实见 tb_commission_clawback_record。
 type CommissionRecord struct {
 	gorm.Model
 	BaseModel        `gorm:"embedded"`
@@ -19,7 +20,7 @@ type CommissionRecord struct {
 	CommissionSource string     `gorm:"column:commission_source;type:varchar(20);not null;index;comment:佣金来源 cost_diff-成本价差 one_time-一次性佣金" json:"commission_source"`
 	Amount           int64      `gorm:"column:amount;type:bigint;not null;comment:佣金金额(分)" json:"amount"`
 	BalanceAfter     int64      `gorm:"column:balance_after;type:bigint;default:0;comment:入账后钱包余额（分）" json:"balance_after"`
-	Status           int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-已冻结 2-解冻中 3-已发放 4-已失效 99-待人工修正" json:"status"`
+	Status           int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-已冻结 2-解冻中 3-已发放 4-已失效 5-回溯 99-待人工修正" json:"status"`
 	ReleasedAt       *time.Time `gorm:"column:released_at;comment:入账时间" json:"released_at"`
 	Remark           string     `gorm:"column:remark;type:varchar(500);comment:备注" json:"remark"`
 }

internal/model/commission_clawback.go

@@ -0,0 +1,29 @@
+package model
+
+import "time"
+
+// CommissionClawbackRecord 佣金回溯明细模型。
+// 退款完成后的佣金回溯以负数、不可提现明细独立保存，原佣金记录保持已发放不变。
+// 记录不可变：生成后不更新、不删除；(refund_id, original_commission_id) 是幂等唯一事实。
+type CommissionClawbackRecord struct {
+	ID                   uint   `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	RefundID             uint   `gorm:"column:refund_id;not null" json:"refund_id"`
+	OriginalCommissionID uint   `gorm:"column:original_commission_id;not null" json:"original_commission_id"`
+	OrderID              uint   `gorm:"column:order_id;not null" json:"order_id"`
+	ShopID               uint   `gorm:"column:shop_id;not null" json:"shop_id"`
+	OrderNo              string `gorm:"column:order_no;type:varchar(30);not null;default:''" json:"order_no"`
+	RefundNo             string `gorm:"column:refund_no;type:varchar(50);not null;default:''" json:"refund_no"`
+	CommissionSource     string `gorm:"column:commission_source;type:varchar(20);not null" json:"commission_source"`
+	Amount               int64  `gorm:"column:amount;type:bigint;not null;comment:回溯金额(分)，恒为负数" json:"amount"`
+	BalanceAfter         int64  `gorm:"column:balance_after;type:bigint;not null;default:0;comment:回溯后佣金钱包实际余额（分），允许为负" json:"balance_after"`
+	Withdrawable         bool   `gorm:"column:withdrawable;not null;default:false;comment:是否可提现，回溯明细恒为不可提现" json:"withdrawable"`
+	Status               int    `gorm:"column:status;type:int;not null;default:5;comment:状态 5-回溯" json:"status"`
+	// CreatedAt 与 tb_commission_record.created_at 同为不带时区的本地时间，
+	// 保证两表 UNION ALL 合并分页的统一排序键与时间筛选口径一致。
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamp;not null;autoCreateTime" json:"created_at"`
+}
+
+// TableName 指定表名
+func (CommissionClawbackRecord) TableName() string {
+	return "tb_commission_clawback_record"
+}

internal/model/dto/export_task_dto.go

@@ -4,7 +4,7 @@ import "time"
 
 // CreateExportTaskRequest 创建导出任务请求。
 type CreateExportTaskRequest struct {
-	Scene  string                 `json:"scene" validate:"required,oneof=device iot_card order package agent_wallet_transaction agent_recharge refund exchange" required:"true" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货)"`
+	Scene  string                 `json:"scene" validate:"required,oneof=device iot_card order package agent_wallet_transaction agent_recharge refund exchange commission_record" required:"true" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货, commission_record:佣金明细)"`
 	Format string                 `json:"format" validate:"required,oneof=xlsx csv" required:"true" description:"导出格式 (xlsx:Excel, csv:CSV)"`
 	Query  map[string]interface{} `json:"query,omitempty" description:"导出筛选参数(JSON对象，可选)"`
 }
@@ -22,7 +22,7 @@ type CreateExportTaskResponse struct {
 type ListExportTaskRequest struct {
 	Page      int        `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
 	PageSize  int        `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
-	Scene     string     `json:"scene" query:"scene" validate:"omitempty,oneof=device iot_card order package agent_wallet_transaction agent_recharge refund exchange" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货)"`
+	Scene     string     `json:"scene" query:"scene" validate:"omitempty,oneof=device iot_card order package agent_wallet_transaction agent_recharge refund exchange commission_record" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货, commission_record:佣金明细)"`
 	Status    *int       `json:"status" query:"status" validate:"omitempty,min=1,max=5" minimum:"1" maximum:"5" description:"任务状态 (1:待处理, 2:处理中, 3:已完成, 4:已失败, 5:已取消)"`
 	StartTime *time.Time `json:"start_time" query:"start_time" description:"创建时间起始"`
 	EndTime   *time.Time `json:"end_time" query:"end_time" description:"创建时间结束"`
@@ -33,7 +33,7 @@ type ExportTaskItem struct {
 	ID                  uint       `json:"id" description:"任务ID"`
 	TaskID              uint       `json:"task_id" description:"任务ID"`
 	TaskNo              string     `json:"task_no" description:"任务编号"`
-	Scene               string     `json:"scene" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货)"`
+	Scene               string     `json:"scene" description:"导出场景 (device:设备, iot_card:IoT卡, order:订单, package:套餐, agent_wallet_transaction:代理主钱包流水, agent_recharge:代理充值, refund:退款, exchange:换货, commission_record:佣金明细)"`
 	Format              string     `json:"format" description:"导出格式 (xlsx:Excel, csv:CSV)"`
 	Status              int        `json:"status" description:"任务状态 (1:待处理, 2:处理中, 3:已完成, 4:已失败, 5:已取消)"`
 	StatusName          string     `json:"status_name" description:"任务状态名称（中文）"`

internal/model/dto/shop_commission_dto.go

@@ -148,24 +148,48 @@ type ShopCommissionRecordListReq struct {
 	ICCID            string `json:"iccid" query:"iccid" validate:"omitempty,max=50" maxLength:"50" description:"ICCID（模糊查询）"`
 	VirtualNo        string `json:"virtual_no" query:"virtual_no" validate:"omitempty,max=50" maxLength:"50" description:"设备虚拟号（模糊查询）"`
 	OrderNo          string `json:"order_no" query:"order_no" validate:"omitempty,max=50" maxLength:"50" description:"订单号（模糊查询）"`
+	Status           *int   `json:"status" query:"status" validate:"omitempty,min=1,max=99" minimum:"1" maximum:"99" description:"佣金状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效, 5:回溯, 99:待人工修正)"`
 }
 
-// ShopCommissionRecordItem 代理商佣金明细项
+// ShopCommissionClawbackItem 是一条与原佣金关联的佣金回溯明细。
+type ShopCommissionClawbackItem struct {
+	ID                   uint   `json:"id" description:"回溯明细ID"`
+	OriginalCommissionID uint   `json:"original_commission_id" description:"被回溯的原佣金记录ID"`
+	RefundID             uint   `json:"refund_id" description:"来源退款申请ID"`
+	RefundNo             string `json:"refund_no" description:"来源退款单号"`
+	Amount               int64  `json:"amount" description:"回溯金额（分），恒为负数"`
+	BalanceAfter         int64  `json:"balance_after" description:"回溯后佣金余额（分），可为负数"`
+	Withdrawable         bool   `json:"withdrawable" description:"是否可提现，回溯明细恒为不可提现"`
+	Status               int    `json:"status" description:"状态 (5:回溯)"`
+	StatusName           string `json:"status_name" description:"状态名称"`
+	CreatedAt            string `json:"created_at" description:"生成时间"`
+}
+
+// ShopCommissionRecordItem 代理商佣金明细项。
+// 原佣金与回溯明细合并为同一列表：source 区分来源，回溯行携带原佣金标识、退款单号与不可提现标识。
 type ShopCommissionRecordItem struct {
-	ID               uint   `json:"id" description:"佣金记录ID"`
-	Amount           int64  `json:"amount" description:"佣金金额（分）"`
-	BalanceAfter     int64  `json:"balance_after" description:"入账后佣金余额（分）"`
-	CommissionSource string `json:"commission_source" description:"佣金来源 (cost_diff:成本价差, one_time:一次性佣金, tier_bonus(已废弃):梯度奖励)"`
-	Status           int    `json:"status" description:"状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效)"`
-	StatusName       string `json:"status_name" description:"状态名称"`
-	OrderID          uint   `json:"order_id" description:"订单ID"`
-	OrderNo          string `json:"order_no" description:"订单号"`
-	VirtualNo        string `json:"virtual_no,omitempty" description:"设备虚拟号"`
-	ICCID            string `json:"iccid,omitempty" description:"ICCID"`
-	OrderCreatedAt   string `json:"order_created_at" description:"订单创建时间"`
-	SellerShopID     uint   `json:"seller_shop_id" description:"销售来源店铺ID"`
-	SellerShopName   string `json:"seller_shop_name" description:"销售来源店铺名称"`
-	CreatedAt        string `json:"created_at" description:"佣金入账时间"`
+	Source               string                       `json:"source" description:"记录来源 (original:原佣金, clawback:回溯明细)"`
+	ID                   uint                         `json:"id" description:"记录ID（原佣金ID或回溯明细ID）"`
+	Amount               int64                        `json:"amount" description:"佣金金额（分），回溯明细为负数"`
+	BalanceAfter         int64                        `json:"balance_after" description:"入账后佣金余额（分），回溯行为回溯后余额，可为负数"`
+	CommissionSource     string                       `json:"commission_source" description:"佣金来源 (cost_diff:成本价差, one_time:一次性佣金, tier_bonus(已废弃):梯度奖励)"`
+	Status               int                          `json:"status" description:"状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效, 5:回溯, 99:待人工修正)"`
+	StatusName           string                       `json:"status_name" description:"状态名称"`
+	OrderID              uint                         `json:"order_id" description:"订单ID"`
+	OrderNo              string                       `json:"order_no" description:"订单号"`
+	VirtualNo            string                       `json:"virtual_no,omitempty" description:"设备虚拟号"`
+	ICCID                string                       `json:"iccid,omitempty" description:"ICCID"`
+	OrderCreatedAt       string                       `json:"order_created_at" description:"订单创建时间"`
+	SellerShopID         uint                         `json:"seller_shop_id" description:"销售来源店铺ID"`
+	SellerShopName       string                       `json:"seller_shop_name" description:"销售来源店铺名称"`
+	ReleasedAt           string                       `json:"released_at,omitempty" description:"佣金入账时间，回溯明细为空"`
+	CreatedAt            string                       `json:"created_at" description:"佣金入账或回溯明细生成时间"`
+	OriginalCommissionID uint                         `json:"original_commission_id,omitempty" description:"被回溯的原佣金记录ID，仅回溯明细返回"`
+	RefundID             uint                         `json:"refund_id,omitempty" description:"来源退款申请ID，仅回溯明细返回"`
+	RefundNo             string                       `json:"refund_no,omitempty" description:"来源退款单号，仅回溯明细返回"`
+	Withdrawable         *bool                        `json:"withdrawable,omitempty" description:"是否可提现，仅回溯明细返回且恒为不可提现"`
+	ClawbackRecords      []ShopCommissionClawbackItem `json:"clawback_records,omitempty" description:"该原佣金已生成的全部回溯明细，仅原佣金返回"`
+	ClawbackTotalAmount  int64                        `json:"clawback_total_amount,omitempty" description:"该原佣金累计回溯金额（分，负值），仅原佣金返回"`
 }
 
 // ShopCommissionRecordPageResult 代理商佣金明细分页响应
@@ -176,6 +200,22 @@ type ShopCommissionRecordPageResult struct {
 	Size  int                        `json:"size" description:"每页数量"`
 }
 
+// ShopCommissionRecordDetailReq 代理商佣金明细详情请求
+type ShopCommissionRecordDetailReq struct {
+	ShopID uint   `json:"-" params:"shop_id" path:"shop_id" validate:"required" description:"店铺ID"`
+	ID     uint   `json:"-" params:"id" path:"id" validate:"required" description:"记录ID"`
+	Source string `json:"source" query:"source" validate:"omitempty,oneof=original clawback" description:"记录来源 (original:原佣金, clawback:回溯明细，默认原佣金)"`
+}
+
+// ShopCommissionRecordDetailResp 代理商佣金明细详情响应。
+// 原佣金详情返回其全部回溯明细；回溯明细详情返回关联的原佣金与来源退款单。
+type ShopCommissionRecordDetailResp struct {
+	Source             string                       `json:"source" description:"记录来源 (original:原佣金, clawback:回溯明细)"`
+	Record             ShopCommissionRecordItem     `json:"record" description:"主体记录"`
+	OriginalCommission *ShopCommissionRecordItem    `json:"original_commission,omitempty" description:"回溯明细关联的原佣金记录，仅回溯明细详情返回"`
+	ClawbackRecords    []ShopCommissionClawbackItem `json:"clawback_records,omitempty" description:"该原佣金已生成的全部回溯明细，仅原佣金详情返回"`
+}
+
 // ========================================
 // 路由参数 DTO
 // ========================================