feat: 技术债务清理（支付配置动态化、API文档补全、轮询常量提取、废弃代码清理）

internal/service/order/service.go

@@ -18,6 +18,7 @@ import (
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/fuiou"
 	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/payment"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/break/junhong_cmp_fiber/pkg/wechat"
 	"github.com/redis/go-redis/v9"
@@ -48,6 +49,7 @@ type Service struct {
 	packageStore               *postgres.PackageStore
 	wechatConfigService        WechatConfigServiceInterface
 	wechatPayment              wechat.PaymentServiceInterface
+	paymentLoader              payment.PaymentConfigLoader
 	queueClient                *queue.Client
 	logger                     *zap.Logger
 	resumeCallback             packagepkg.ResumeCallback
@@ -73,6 +75,7 @@ func New(
 	packageStore *postgres.PackageStore,
 	wechatConfigService WechatConfigServiceInterface,
 	wechatPayment wechat.PaymentServiceInterface,
+	paymentLoader payment.PaymentConfigLoader,
 	queueClient *queue.Client,
 	logger *zap.Logger,
 	assetIdentifierStore *postgres.AssetIdentifierStore,
@@ -96,6 +99,7 @@ func New(
 		packageStore:               packageStore,
 		wechatConfigService:        wechatConfigService,
 		wechatPayment:              wechatPayment,
+		paymentLoader:              paymentLoader,
 		queueClient:                queueClient,
 		logger:                     logger,
 		assetIdentifierStore:       assetIdentifierStore,
@@ -109,250 +113,6 @@ func (s *Service) SetResumeCallback(callback packagepkg.ResumeCallback) {
 	s.resumeCallback = callback
 }
 
-// CreateLegacy 创建订单（已废弃）
-// Deprecated: 使用 CreateAdminOrder 或 CreateH5Order 替代。保留用于回滚。
-func (s *Service) CreateLegacy(ctx context.Context, req *dto.CreateOrderRequest, buyerType string, buyerID uint) (*dto.OrderResponse, error) {
-	var validationResult *purchase_validation.PurchaseValidationResult
-	var err error
-
-	if req.OrderType == model.OrderTypeSingleCard {
-		if req.IotCardID == nil {
-			return nil, errors.New(errors.CodeInvalidParam, "单卡购买必须指定IoT卡ID")
-		}
-		validationResult, err = s.purchaseValidationService.ValidateCardPurchase(ctx, *req.IotCardID, req.PackageIDs)
-	} else if req.OrderType == model.OrderTypeDevice {
-		if req.DeviceID == nil {
-			return nil, errors.New(errors.CodeInvalidParam, "设备购买必须指定设备ID")
-		}
-		validationResult, err = s.purchaseValidationService.ValidateDevicePurchase(ctx, *req.DeviceID, req.PackageIDs)
-	} else {
-		return nil, errors.New(errors.CodeInvalidParam, "无效的订单类型")
-	}
-
-	if err != nil {
-		return nil, err
-	}
-
-	// 下单阶段校验混买限制：禁止同一订单同时包含正式套餐和加油包
-	if err := validatePackageTypeMixFromPackages(validationResult.Packages); err != nil {
-		return nil, err
-	}
-
-	// 幂等性检查：防止同一买家对同一载体短时间内重复下单
-	carrierType, carrierID := resolveCarrierInfo(req)
-	existingOrderID, err := s.checkOrderIdempotency(ctx, buyerType, buyerID, req.OrderType, carrierType, carrierID, req.PackageIDs)
-	if err != nil {
-		return nil, err
-	}
-	if existingOrderID > 0 {
-		return s.Get(ctx, existingOrderID)
-	}
-	// 获取到分布式锁后，确保无论成功还是失败都释放
-	lockKey := constants.RedisOrderCreateLockKey(carrierType, carrierID)
-	defer s.redis.Del(ctx, lockKey)
-
-	forceRechargeCheck := s.checkForceRechargeRequirement(ctx, validationResult)
-	if forceRechargeCheck.NeedForceRecharge && validationResult.TotalPrice < forceRechargeCheck.ForceRechargeAmount {
-		return nil, errors.New(errors.CodeForceRechargeRequired, "首次购买需满足最低充值要求")
-	}
-
-	userID := middleware.GetUserIDFromContext(ctx)
-
-	// 提取资源所属店铺ID
-	var resourceShopID *uint
-	var seriesID *uint
-	if validationResult.Card != nil {
-		resourceShopID = validationResult.Card.ShopID
-		seriesID = validationResult.Card.SeriesID
-	} else if validationResult.Device != nil {
-		resourceShopID = validationResult.Device.ShopID
-		seriesID = validationResult.Device.SeriesID
-	}
-
-	// 初始化订单字段
-	orderBuyerType := buyerType
-	orderBuyerID := buyerID
-	totalAmount := validationResult.TotalPrice
-	paymentMethod := req.PaymentMethod
-	paymentStatus := model.PaymentStatusPending
-	var paidAt *time.Time
-	now := time.Now()
-	isPurchaseOnBehalf := false
-	var operatorID *uint
-	operatorType := ""
-	var actualPaidAmount *int64
-	purchaseRole := ""
-	var sellerShopID *uint = resourceShopID
-	var sellerCostPrice int64
-
-	// 场景判断：offline（平台代购）、wallet（代理钱包支付）、其他（待支付）
-	if req.PaymentMethod == model.PaymentMethodOffline {
-		// ==== 场景 1：平台代购（offline）====
-		purchaseBuyerID, buyerCostPrice, purchasePaidAt, err := s.resolvePurchaseOnBehalfInfo(ctx, validationResult)
-		if err != nil {
-			return nil, err
-		}
-		orderBuyerType = model.BuyerTypeAgent
-		orderBuyerID = purchaseBuyerID
-		totalAmount = buyerCostPrice
-		paymentMethod = model.PaymentMethodOffline
-		paymentStatus = model.PaymentStatusPaid
-		paidAt = purchasePaidAt
-		isPurchaseOnBehalf = true
-		sellerCostPrice = buyerCostPrice
-
-		// 设置操作者信息（平台代购）
-		operatorID = nil
-		operatorType = constants.OwnerTypePlatform
-		purchaseRole = model.PurchaseRolePurchasedByPlatform
-		actualPaidAmount = nil
-
-	} else if req.PaymentMethod == model.PaymentMethodWallet {
-		// ==== 场景 2：代理钱包支付（wallet）====
-		if buyerType == "" {
-			if resourceShopID == nil {
-				return nil, errors.New(errors.CodeInvalidParam, "不支持的钱包支付场景")
-			}
-			buyerType = model.BuyerTypeAgent
-			buyerID = *resourceShopID
-		}
-
-		// 只有代理账号可以使用钱包支付
-		if buyerType != model.BuyerTypeAgent {
-			return nil, errors.New(errors.CodeInvalidParam, "只有代理账号可以使用钱包支付")
-		}
-		operatorShopID := buyerID
-
-		// 判断资源是否属于操作者
-		if resourceShopID == nil {
-			return nil, errors.New(errors.CodeInternalError, "资源店铺ID为空")
-		}
-
-		// 获取第一个套餐ID用于查询成本价
-		if len(validationResult.Packages) == 0 {
-			return nil, errors.New(errors.CodeInternalError, "套餐列表为空")
-		}
-		firstPackageID := validationResult.Packages[0].ID
-
-		if *resourceShopID == operatorShopID {
-			// ==== 子场景 2.1：代理自购 ====
-			costPrice, err := s.getCostPrice(ctx, operatorShopID, firstPackageID)
-			if err != nil {
-				return nil, err
-			}
-
-			orderBuyerType = model.BuyerTypeAgent
-			orderBuyerID = operatorShopID
-			totalAmount = costPrice
-			paymentMethod = model.PaymentMethodWallet
-			paymentStatus = model.PaymentStatusPaid
-			paidAt = &now
-			isPurchaseOnBehalf = false
-
-			operatorID = &operatorShopID
-			operatorType = "agent"
-			actualPaidAmountVal := costPrice
-			actualPaidAmount = &actualPaidAmountVal
-			purchaseRole = model.PurchaseRoleSelfPurchase
-			sellerCostPrice = costPrice
-
-		} else {
-			// ==== 子场景 2.2：代理代购（给下级购买）====
-			// 获取买家成本价
-			buyerCostPrice, err := s.getCostPrice(ctx, *resourceShopID, firstPackageID)
-			if err != nil {
-				return nil, err
-			}
-
-			// 获取操作者成本价
-			operatorCostPrice, err := s.getCostPrice(ctx, operatorShopID, firstPackageID)
-			if err != nil {
-				return nil, err
-			}
-
-			orderBuyerType = model.BuyerTypeAgent
-			orderBuyerID = *resourceShopID
-			totalAmount = buyerCostPrice
-			paymentMethod = model.PaymentMethodWallet
-			paymentStatus = model.PaymentStatusPaid
-			paidAt = &now
-			isPurchaseOnBehalf = true
-
-			operatorID = &operatorShopID
-			operatorType = "agent"
-			actualPaidAmount = &operatorCostPrice
-			purchaseRole = model.PurchaseRolePurchaseForSubordinate
-			// 代理代购下级时，佣金差额基准应是操作方（代理自己）的成本价，而非下级的成本价
-			// 使用 buyerCostPrice 会导致差额为 0，上级代理无法获得应有佣金
-			sellerCostPrice = operatorCostPrice
-		}
-	}
-
-	order := &model.Order{
-		BaseModel: model.BaseModel{
-			Creator: userID,
-			Updater: userID,
-		},
-		OrderNo:                 s.orderStore.GenerateOrderNo(),
-		OrderType:               req.OrderType,
-		BuyerType:               orderBuyerType,
-		BuyerID:                 orderBuyerID,
-		IotCardID:               req.IotCardID,
-		DeviceID:                req.DeviceID,
-		TotalAmount:             totalAmount,
-		PaymentMethod:           paymentMethod,
-		PaymentStatus:           paymentStatus,
-		PaidAt:                  paidAt,
-		CommissionStatus:        model.CommissionStatusPending,
-		CommissionConfigVersion: 0,
-		SeriesID:                seriesID,
-		SellerShopID:            sellerShopID,
-		SellerCostPrice:         sellerCostPrice,
-		IsPurchaseOnBehalf:      isPurchaseOnBehalf,
-		OperatorID:              operatorID,
-		OperatorType:            operatorType,
-		ActualPaidAmount:        actualPaidAmount,
-		PurchaseRole:            purchaseRole,
-	}
-
-	items := s.buildOrderItems(userID, validationResult.Packages)
-
-	idempotencyKey := buildOrderIdempotencyKey(buyerType, buyerID, req.OrderType, carrierType, carrierID, req.PackageIDs)
-
-	// 根据支付方式选择创建订单的方式
-	if req.PaymentMethod == model.PaymentMethodOffline {
-		// 平台代购：创建订单并立即激活套餐
-		if err := s.createOrderWithActivation(ctx, order, items); err != nil {
-			return nil, err
-		}
-		s.enqueueCommissionCalculation(ctx, order.ID)
-		s.markOrderCreated(ctx, idempotencyKey, order.ID)
-		return s.buildOrderResponse(order, items), nil
-
-	} else if req.PaymentMethod == model.PaymentMethodWallet {
-		// 钱包支付：创建订单、扣款、激活套餐（在事务中完成）
-		if operatorID == nil {
-			return nil, errors.New(errors.CodeInternalError, "钱包支付场景下 operatorID 不能为空")
-		}
-		operatorShopID := *operatorID
-		buyerShopID := orderBuyerID
-
-		if err := s.createOrderWithWalletPayment(ctx, order, items, operatorShopID, buyerShopID); err != nil {
-			return nil, err
-		}
-		s.markOrderCreated(ctx, idempotencyKey, order.ID)
-		return s.buildOrderResponse(order, items), nil
-
-	} else {
-		// 其他支付方式：创建待支付订单
-		if err := s.orderStore.Create(ctx, order, items); err != nil {
-			return nil, err
-		}
-		s.markOrderCreated(ctx, idempotencyKey, order.ID)
-		return s.buildOrderResponse(order, items), nil
-	}
-}
-
 // CreateAdminOrder 后台订单创建（仅支持 wallet/offline，立即扣款或激活）
 // 与 CreateH5Order 的核心区别：后台订单不创建待支付状态，wallet 立即扣款，offline 立即激活
 // POST /api/admin/orders
@@ -2227,6 +1987,7 @@ func (s *Service) buildOrderResponse(order *model.Order, items []*model.OrderIte
 		PaymentVoucherKey:       order.PaymentVoucherKey,
 		IsPurchaseOnBehalf:      order.IsPurchaseOnBehalf,
 		CommissionStatus:        order.CommissionStatus,
+		CommissionStatusName:    constants.GetOrderCommissionStatusName(order.CommissionStatus),
 		CommissionConfigVersion: order.CommissionConfigVersion,
 
 		OperatorID:       order.OperatorID,
@@ -2251,13 +2012,8 @@ func (s *Service) buildOrderResponse(order *model.Order, items []*model.OrderIte
 }
 
 // WechatPayJSAPI 发起微信 JSAPI 支付
-// TODO: 从 payment_config_id 加载配置动态创建 Payment 实例，替代 s.wechatPayment 单例
+// 通过 order.PaymentConfigID 动态加载支付配置，支持多商户场景
 func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID string, buyerType string, buyerID uint) (*dto.WechatPayJSAPIResponse, error) {
-	if s.wechatPayment == nil {
-		s.logger.Error("微信支付服务未配置")
-		return nil, errors.New(errors.CodeWechatPayFailed, "微信支付服务未配置")
-	}
-
 	order, err := s.orderStore.GetByID(ctx, orderID)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
@@ -2274,6 +2030,16 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin
 		return nil, errors.New(errors.CodeInvalidStatus, "订单状态不允许支付")
 	}
 
+	// 按 payment_config_id 动态加载支付配置
+	if order.PaymentConfigID == nil {
+		s.logger.Error("订单缺少支付配置", zap.Uint("order_id", orderID))
+		return nil, errors.New(errors.CodeWechatConfigNotFound, "订单缺少支付配置")
+	}
+	paymentSvc, err := s.paymentLoader.LoadConfig(ctx, *order.PaymentConfigID)
+	if err != nil {
+		return nil, err
+	}
+
 	items, err := s.orderItemStore.ListByOrderIDs(ctx, []uint{orderID})
 	if err != nil {
 		return nil, errors.Wrap(errors.CodeInternalError, err, "查询订单明细失败")
@@ -2283,7 +2049,7 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin
 		description = items[0].PackageName
 	}
 
-	result, err := s.wechatPayment.CreateJSAPIOrder(ctx, order.OrderNo, description, openID, int(order.TotalAmount))
+	result, err := paymentSvc.CreateJSAPIOrder(ctx, order.OrderNo, description, openID, int(order.TotalAmount))
 	if err != nil {
 		s.logger.Error("创建 JSAPI 支付失败",
 			zap.Uint("order_id", orderID),
@@ -2307,13 +2073,8 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin
 }
 
 // WechatPayH5 发起微信 H5 支付
-// TODO: 从 payment_config_id 加载配置动态创建 Payment 实例，替代 s.wechatPayment 单例
+// 通过 order.PaymentConfigID 动态加载支付配置，支持多商户场景
 func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto.WechatH5SceneInfo, buyerType string, buyerID uint) (*dto.WechatPayH5Response, error) {
-	if s.wechatPayment == nil {
-		s.logger.Error("微信支付服务未配置")
-		return nil, errors.New(errors.CodeWechatPayFailed, "微信支付服务未配置")
-	}
-
 	order, err := s.orderStore.GetByID(ctx, orderID)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
@@ -2330,6 +2091,16 @@ func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto.
 		return nil, errors.New(errors.CodeInvalidStatus, "订单状态不允许支付")
 	}
 
+	// 按 payment_config_id 动态加载支付配置
+	if order.PaymentConfigID == nil {
+		s.logger.Error("订单缺少支付配置", zap.Uint("order_id", orderID))
+		return nil, errors.New(errors.CodeWechatConfigNotFound, "订单缺少支付配置")
+	}
+	paymentSvc, err := s.paymentLoader.LoadConfig(ctx, *order.PaymentConfigID)
+	if err != nil {
+		return nil, err
+	}
+
 	items, err := s.orderItemStore.ListByOrderIDs(ctx, []uint{orderID})
 	if err != nil {
 		return nil, errors.Wrap(errors.CodeInternalError, err, "查询订单明细失败")
@@ -2344,7 +2115,7 @@ func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto.
 		H5Type:        sceneInfo.H5Info.Type,
 	}
 
-	result, err := s.wechatPayment.CreateH5Order(ctx, order.OrderNo, description, int(order.TotalAmount), h5SceneInfo)
+	result, err := paymentSvc.CreateH5Order(ctx, order.OrderNo, description, int(order.TotalAmount), h5SceneInfo)
 	if err != nil {
 		s.logger.Error("创建 H5 支付失败",
 			zap.Uint("order_id", orderID),