feat: 套餐系统升级 - Worker 重构、流量重置、文档与规范更新

- 重构 Worker 启动流程，引入 bootstrap 模块统一管理依赖注入
- 实现套餐流量重置服务（日/月/年周期重置）
- 新增套餐激活排队、加油包绑定、囤货待实名激活逻辑
- 新增订单创建幂等性防重（Redis 业务键 + 分布式锁）
- 更新 AGENTS.md/CLAUDE.md：新增注释规范、幂等性规范，移除测试要求
- 添加套餐系统升级完整文档（API文档、使用指南、功能总结、运维指南）
- 归档 OpenSpec package-system-upgrade 变更，同步 specs 到主目录
- 新增 queue types 抽象和 Redis 常量定义

internal/service/order/service.go

@@ -2,6 +2,10 @@ package order
 
 import (
 	"context"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
 	"time"
 
 	"github.com/break/junhong_cmp_fiber/internal/model"
@@ -16,12 +20,14 @@ import (
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/break/junhong_cmp_fiber/pkg/wechat"
 	"github.com/bytedance/sonic"
+	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 
 type Service struct {
 	db                         *gorm.DB
+	redis                      *redis.Client
 	orderStore                 *postgres.OrderStore
 	orderItemStore             *postgres.OrderItemStore
 	walletStore                *postgres.WalletStore
@@ -40,6 +46,7 @@ type Service struct {
 
 func New(
 	db *gorm.DB,
+	redisClient *redis.Client,
 	orderStore *postgres.OrderStore,
 	orderItemStore *postgres.OrderItemStore,
 	walletStore *postgres.WalletStore,
@@ -57,6 +64,7 @@ func New(
 ) *Service {
 	return &Service{
 		db:                         db,
+		redis:                      redisClient,
 		orderStore:                 orderStore,
 		orderItemStore:             orderItemStore,
 		walletStore:                walletStore,
@@ -96,6 +104,24 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateOrderRequest, buyer
 		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, "首次购买需满足最低充值要求")
@@ -170,11 +196,14 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateOrderRequest, buyer
 
 	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
 	}
 
@@ -182,6 +211,7 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateOrderRequest, buyer
 		return nil, err
 	}
 
+	s.markOrderCreated(ctx, idempotencyKey, order.ID)
 	return s.buildOrderResponse(order, items), nil
 }
 
@@ -591,9 +621,9 @@ func (s *Service) validatePackageTypeMix(tx *gorm.DB, items []*model.OrderItem)
 			return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐信息失败")
 		}
 
-		if pkg.PackageType == "formal" {
+		if pkg.PackageType == constants.PackageTypeFormal {
 			hasFormal = true
-		} else if pkg.PackageType == "addon" {
+		} else if pkg.PackageType == constants.PackageTypeAddon {
 			hasAddon = true
 		}
 
@@ -605,6 +635,114 @@ func (s *Service) validatePackageTypeMix(tx *gorm.DB, items []*model.OrderItem)
 	return nil
 }
 
+// validatePackageTypeMixFromPackages 基于已加载的套餐列表检查混买限制（无需 DB 查询）
+func validatePackageTypeMixFromPackages(packages []*model.Package) error {
+	hasFormal := false
+	hasAddon := false
+
+	for _, pkg := range packages {
+		if pkg.PackageType == constants.PackageTypeFormal {
+			hasFormal = true
+		} else if pkg.PackageType == constants.PackageTypeAddon {
+			hasAddon = true
+		}
+
+		if hasFormal && hasAddon {
+			return errors.New(errors.CodeInvalidParam, "不允许在同一订单中同时购买正式套餐和加油包")
+		}
+	}
+
+	return nil
+}
+
+// resolveCarrierInfo 从请求中提取载体类型和ID
+func resolveCarrierInfo(req *dto.CreateOrderRequest) (carrierType string, carrierID uint) {
+	if req.OrderType == model.OrderTypeSingleCard && req.IotCardID != nil {
+		return "iot_card", *req.IotCardID
+	}
+	if req.OrderType == model.OrderTypeDevice && req.DeviceID != nil {
+		return "device", *req.DeviceID
+	}
+	return "", 0
+}
+
+// buildOrderIdempotencyKey 生成订单创建的幂等性业务键
+// 格式: {buyer_type}:{buyer_id}:{order_type}:{carrier_type}:{carrier_id}:{sorted_package_ids}
+func buildOrderIdempotencyKey(buyerType string, buyerID uint, orderType string, carrierType string, carrierID uint, packageIDs []uint) string {
+	sortedIDs := make([]uint, len(packageIDs))
+	copy(sortedIDs, packageIDs)
+	sort.Slice(sortedIDs, func(i, j int) bool { return sortedIDs[i] < sortedIDs[j] })
+
+	idStrs := make([]string, len(sortedIDs))
+	for i, id := range sortedIDs {
+		idStrs[i] = strconv.FormatUint(uint64(id), 10)
+	}
+
+	return fmt.Sprintf("%s:%d:%s:%s:%d:%s",
+		buyerType, buyerID, orderType, carrierType, carrierID, strings.Join(idStrs, ","))
+}
+
+const (
+	orderIdempotencyTTL = 3 * time.Minute
+	orderCreateLockTTL  = 10 * time.Second
+)
+
+// checkOrderIdempotency 检查订单是否已创建（Redis SETNX + 分布式锁）
+// 返回已存在的 orderID（>0 表示重复请求），或 0 表示可以创续创建
+func (s *Service) checkOrderIdempotency(ctx context.Context, buyerType string, buyerID uint, orderType string, carrierType string, carrierID uint, packageIDs []uint) (uint, error) {
+	idempotencyKey := buildOrderIdempotencyKey(buyerType, buyerID, orderType, carrierType, carrierID, packageIDs)
+	redisKey := constants.RedisOrderIdempotencyKey(idempotencyKey)
+
+	// 第 1 层：Redis 快速检测，如果 key 已存在说明已创建或正在创建
+	val, err := s.redis.Get(ctx, redisKey).Result()
+	if err == nil && val != "" {
+		orderID, _ := strconv.ParseUint(val, 10, 64)
+		if orderID > 0 {
+			s.logger.Info("订单幂等性命中，返回已有订单",
+				zap.Uint("order_id", uint(orderID)),
+				zap.String("idempotency_key", idempotencyKey))
+			return uint(orderID), nil
+		}
+	}
+
+	// 第 2 层：分布式锁，防止并发创建
+	lockKey := constants.RedisOrderCreateLockKey(carrierType, carrierID)
+	locked, err := s.redis.SetNX(ctx, lockKey, time.Now().String(), orderCreateLockTTL).Result()
+	if err != nil {
+		s.logger.Warn("获取订单创建分布式锁失败，继续执行",
+			zap.Error(err),
+			zap.String("lock_key", lockKey))
+		return 0, nil
+	}
+	if !locked {
+		return 0, errors.New(errors.CodeTooManyRequests, "订单正在创建中，请勿重复提交")
+	}
+
+	// 第 3 层：加锁后二次检测，防止锁等待期间已被处理
+	val, err = s.redis.Get(ctx, redisKey).Result()
+	if err == nil && val != "" {
+		orderID, _ := strconv.ParseUint(val, 10, 64)
+		if orderID > 0 {
+			s.logger.Info("订单幂等性二次检测命中",
+				zap.Uint("order_id", uint(orderID)),
+				zap.String("idempotency_key", idempotencyKey))
+			return uint(orderID), nil
+		}
+	}
+
+	return 0, nil
+}
+
+// markOrderCreated 订单创建成功后标记 Redis 并释放分布式锁
+func (s *Service) markOrderCreated(ctx context.Context, idempotencyKey string, orderID uint) {
+	redisKey := constants.RedisOrderIdempotencyKey(idempotencyKey)
+	if err := s.redis.Set(ctx, redisKey, strconv.FormatUint(uint64(orderID), 10), orderIdempotencyTTL).Err(); err != nil {
+		s.logger.Warn("设置订单幂等性标记失败",
+			zap.Error(err),
+			zap.Uint("order_id", orderID))
+	}
+}
+
 // activateMainPackage 任务 8.2-8.4: 主套餐激活逻辑
 func (s *Service) activateMainPackage(ctx context.Context, tx *gorm.DB, order *model.Order, pkg *model.Package, carrierType string, carrierID uint, now time.Time) error {
 	// 检查是否有生效中主套餐
@@ -642,22 +780,8 @@ func (s *Service) activateMainPackage(ctx context.Context, tx *gorm.DB, order *m
 		activatedAt = now
 		// 使用工具函数计算过期时间
 		expiresAt = packagepkg.CalculateExpiryTime(pkg.CalendarType, activatedAt, pkg.DurationMonths, pkg.DurationDays)
-		// 计算下次重置时间
-		// TODO: 从运营商表读取 billing_day（任务 1.5 待实现）
-		// 暂时使用默认值：联通=27，其他=1
-		billingDay := 1 // 默认1号计费
-		if carrierType == "iot_card" {
-			var card model.IotCard
-			if err := tx.First(&card, carrierID).Error; err == nil {
-				var carrier model.Carrier
-				if err := tx.First(&carrier, card.CarrierID).Error; err == nil {
-					if carrier.CarrierType == "CUCC" {
-						billingDay = 27 // 联通27号计费
-					}
-				}
-			}
-		}
-		nextResetAt = packagepkg.CalculateNextResetTime(pkg.DataResetCycle, now, billingDay)
+		// 计算下次重置时间（基于套餐周期类型）
+		nextResetAt = packagepkg.CalculateNextResetTime(pkg.DataResetCycle, pkg.CalendarType, now, activatedAt)
 	}
 
 	// 任务 8.9: 后台囤货场景