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
2026-09-14 13:40:34 +08:00
parent 67893617fe
commit 1aa4eacee2
30 changed files with 1867 additions and 399 deletions
--- a/internal/service/shop_commission/service.go
+++ b/internal/service/shop_commission/service.go
@@ -248,6 +248,7 @@ func (s *Service) buildShopHierarchyPath(ctx context.Context, shop *model.Shop)

 // ListShopCommissionRecords 查询代理商佣金明细
 // GET /shops/:id/commission-records
+// 原佣金与回溯明细按同一分页与排序口径合并返回，筛选与数据范围在合并前各自应用。
 func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, req *dto.ShopCommissionRecordListReq) (*dto.ShopCommissionRecordPageResult, error) {
 	// 越权校验：平台人员可查所有，代理只能查自己和下级
 	if err := middleware.CanManageShop(ctx, shopID); err != nil {
@@ -262,7 +263,6 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 	opts := &store.QueryOptions{
 		Page:     req.Page,
 		PageSize: req.PageSize,
-		OrderBy:  "created_at DESC",
 	}
 	if opts.Page == 0 {
 		opts.Page = 1
@@ -270,6 +270,9 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 	if opts.PageSize == 0 {
 		opts.PageSize = constants.DefaultPageSize
 	}
+	if opts.PageSize > constants.MaxPageSize {
+		opts.PageSize = constants.MaxPageSize
+	}

 	filters := &postgres.CommissionRecordListFilters{
 		ShopID:           shopID,
@@ -277,56 +280,39 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 		ICCID:            req.ICCID,
 		DeviceNo:         req.VirtualNo,
 		OrderNo:          req.OrderNo,
+		Status:           req.Status,
 	}

-	records, total, err := s.commissionRecordStore.ListByShopID(ctx, opts, filters)
+	rows, total, err := s.commissionRecordStore.ListLedgerByShopID(ctx, opts, filters)
 	if err != nil {
 		return nil, errors.Wrap(errors.CodeInternalError, err, "查询佣金明细失败")
 	}

-	sellerShopIDs := make([]uint, 0)
-	for _, r := range records {
-		if r.SellerShopID != nil && *r.SellerShopID > 0 {
-			sellerShopIDs = append(sellerShopIDs, *r.SellerShopID)
+	originalIDs := make([]uint, 0, len(rows))
+	for _, row := range rows {
+		if row.Source == postgres.CommissionLedgerSourceOriginal {
+			originalIDs = append(originalIDs, row.ID)
 		}
 	}
+	summaries, err := s.commissionRecordStore.ListClawbackSummaries(ctx, originalIDs)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询佣金回溯摘要失败")
+	}

-	shopNameMap := make(map[uint]string)
-	if len(sellerShopIDs) > 0 {
-		shops, err := s.shopStore.GetByIDs(ctx, sellerShopIDs)
-		if err == nil {
-			for _, sh := range shops {
-				shopNameMap[sh.ID] = sh.ShopName
+	shopNameMap, err := s.sellerShopNames(ctx, rows)
+	if err != nil {
+		return nil, err
+	}
+
+	items := make([]dto.ShopCommissionRecordItem, 0, len(rows))
+	for _, row := range rows {
+		item := buildShopCommissionRecordItem(row, shopNameMap)
+		if row.Source == postgres.CommissionLedgerSourceOriginal {
+			item.ClawbackRecords = buildClawbackItems(summaries[row.ID])
+			for _, clawback := range item.ClawbackRecords {
+				item.ClawbackTotalAmount += clawback.Amount
 			}
 		}
-	}
-
-	items := make([]dto.ShopCommissionRecordItem, 0, len(records))
-	for _, r := range records {
-		var orderCreatedAt string
-		if r.OrderCreatedAt != nil {
-			orderCreatedAt = r.OrderCreatedAt.Format("2006-01-02 15:04:05")
-		}
-		var sellerShopID uint
-		if r.SellerShopID != nil {
-			sellerShopID = *r.SellerShopID
-		}
-		item := dto.ShopCommissionRecordItem{
-			ID:               r.ID,
-			Amount:           r.Amount,
-			BalanceAfter:     r.BalanceAfter,
-			CommissionSource: r.CommissionSource,
-			Status:           r.Status,
-			StatusName:       constants.GetCommissionRecordStatusName(r.Status),
-			OrderID:          r.OrderID,
-			OrderNo:          r.OrderNo,
-			VirtualNo:        r.VirtualNo,
-			ICCID:            r.ICCID,
-			OrderCreatedAt:   orderCreatedAt,
-			SellerShopID:     sellerShopID,
-			SellerShopName:   shopNameMap[sellerShopID],
-			CreatedAt:        r.CreatedAt.Format("2006-01-02 15:04:05"),
-		}
 		items = append(items, item)
 	}

@@ -338,6 +324,150 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 	}, nil
 }

+// GetShopCommissionRecord 查询单条佣金明细详情
+// GET /shops/:shop_id/commission-records/:id
+// source 区分原佣金与回溯明细；越权与不存在返回同一结果，不泄露存在性。
+func (s *Service) GetShopCommissionRecord(ctx context.Context, req *dto.ShopCommissionRecordDetailReq) (*dto.ShopCommissionRecordDetailResp, error) {
+	if err := middleware.CanManageShop(ctx, req.ShopID); err != nil {
+		return nil, errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
+	}
+	if _, err := s.shopStore.GetByID(ctx, req.ShopID); err != nil {
+		return nil, errors.New(errors.CodeShopNotFound, "店铺不存在")
+	}
+	source := req.Source
+	if source == "" {
+		source = postgres.CommissionLedgerSourceOriginal
+	}
+
+	row, err := s.commissionRecordStore.GetLedgerRowByID(ctx, source, req.ID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "佣金明细不存在")
+		}
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询佣金明细详情失败")
+	}
+	// 记录必须属于请求路径中的店铺，避免借已知 ID 跨店铺枚举。
+	if row.ShopID != req.ShopID {
+		return nil, errors.New(errors.CodeNotFound, "佣金明细不存在")
+	}
+
+	rows := []*postgres.CommissionLedgerRow{row}
+	shopNameMap, err := s.sellerShopNames(ctx, rows)
+	if err != nil {
+		return nil, err
+	}
+	resp := &dto.ShopCommissionRecordDetailResp{
+		Source: source,
+		Record: buildShopCommissionRecordItem(row, shopNameMap),
+	}
+
+	if source == postgres.CommissionLedgerSourceClawback {
+		if row.OriginalCommissionID != nil {
+			original, err := s.commissionRecordStore.GetLedgerRowByID(ctx, postgres.CommissionLedgerSourceOriginal, *row.OriginalCommissionID)
+			if err == nil {
+				originalItem := buildShopCommissionRecordItem(original, shopNameMap)
+				resp.OriginalCommission = &originalItem
+			} else if err != gorm.ErrRecordNotFound {
+				return nil, errors.Wrap(errors.CodeInternalError, err, "查询回溯明细关联原佣金失败")
+			}
+		}
+		return resp, nil
+	}
+
+	summaries, err := s.commissionRecordStore.ListClawbackSummaries(ctx, []uint{row.ID})
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询佣金回溯摘要失败")
+	}
+	resp.ClawbackRecords = buildClawbackItems(summaries[row.ID])
+	return resp, nil
+}
+
+// sellerShopNames 批量解析合并行涉及的销售来源店铺名称。
+func (s *Service) sellerShopNames(ctx context.Context, rows []*postgres.CommissionLedgerRow) (map[uint]string, error) {
+	sellerShopIDs := make([]uint, 0, len(rows))
+	for _, row := range rows {
+		if row.SellerShopID != nil && *row.SellerShopID > 0 {
+			sellerShopIDs = append(sellerShopIDs, *row.SellerShopID)
+		}
+	}
+	shopNameMap := make(map[uint]string)
+	if len(sellerShopIDs) == 0 {
+		return shopNameMap, nil
+	}
+	shops, err := s.shopStore.GetByIDs(ctx, sellerShopIDs)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询销售来源店铺失败")
+	}
+	for _, shop := range shops {
+		shopNameMap[shop.ID] = shop.ShopName
+	}
+	return shopNameMap, nil
+}
+
+// buildShopCommissionRecordItem 把合并行投影为统一明细项。
+func buildShopCommissionRecordItem(row *postgres.CommissionLedgerRow, shopNameMap map[uint]string) dto.ShopCommissionRecordItem {
+	var orderCreatedAt string
+	if row.OrderCreatedAt != nil {
+		orderCreatedAt = row.OrderCreatedAt.Format("2006-01-02 15:04:05")
+	}
+	var sellerShopID uint
+	if row.SellerShopID != nil {
+		sellerShopID = *row.SellerShopID
+	}
+	item := dto.ShopCommissionRecordItem{
+		Source:           row.Source,
+		ID:               row.ID,
+		Amount:           row.Amount,
+		BalanceAfter:     row.BalanceAfter,
+		CommissionSource: row.CommissionSource,
+		Status:           row.Status,
+		StatusName:       constants.GetCommissionRecordStatusName(row.Status),
+		OrderID:          row.OrderID,
+		OrderNo:          row.OrderNo,
+		VirtualNo:        row.VirtualNo,
+		ICCID:            row.ICCID,
+		OrderCreatedAt:   orderCreatedAt,
+		SellerShopID:     sellerShopID,
+		SellerShopName:   shopNameMap[sellerShopID],
+		CreatedAt:        row.CreatedAt.Format("2006-01-02 15:04:05"),
+	}
+	if row.ReleasedAt != nil {
+		item.ReleasedAt = row.ReleasedAt.Format("2006-01-02 15:04:05")
+	}
+	if row.OriginalCommissionID != nil {
+		item.OriginalCommissionID = *row.OriginalCommissionID
+	}
+	if row.RefundID != nil {
+		item.RefundID = *row.RefundID
+	}
+	item.RefundNo = row.RefundNo
+	item.Withdrawable = row.Withdrawable
+	return item
+}
+
+// buildClawbackItems 把回溯摘要投影为明细项。
+func buildClawbackItems(summaries []postgres.CommissionClawbackSummary) []dto.ShopCommissionClawbackItem {
+	if len(summaries) == 0 {
+		return nil
+	}
+	items := make([]dto.ShopCommissionClawbackItem, 0, len(summaries))
+	for _, summary := range summaries {
+		items = append(items, dto.ShopCommissionClawbackItem{
+			ID:                   summary.ID,
+			OriginalCommissionID: summary.OriginalCommissionID,
+			RefundID:             summary.RefundID,
+			RefundNo:             summary.RefundNo,
+			Amount:               summary.Amount,
+			BalanceAfter:         summary.BalanceAfter,
+			Withdrawable:         summary.Withdrawable,
+			Status:               summary.Status,
+			StatusName:           constants.GetCommissionRecordStatusName(summary.Status),
+			CreatedAt:            summary.CreatedAt.Format("2006-01-02 15:04:05"),
+		})
+	}
+	return items
+}
+
 // GetStats 获取佣金统计
 // GET /shops/:id/commission-stats
 func (s *Service) GetStats(ctx context.Context, shopID uint, req *dto.CommissionStatsRequest) (*dto.CommissionStatsResponse, error) {