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: 后台囤货场景

internal/service/package/activation_service.go

@@ -118,19 +118,7 @@ func (s *ActivationService) ActivateByRealname(ctx context.Context, carrierType
 			expiresAt := CalculateExpiryTime(pkg.CalendarType, activatedAt, pkg.DurationMonths, pkg.DurationDays)
 
 			// 计算下次重置时间
-			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 := CalculateNextResetTime(pkg.DataResetCycle, now, billingDay)
+			nextResetAt := CalculateNextResetTime(pkg.DataResetCycle, pkg.CalendarType, now, activatedAt)
 
 			// 更新套餐使用记录
 			updates := map[string]interface{}{
@@ -290,19 +278,7 @@ func (s *ActivationService) activateNextMainPackage(ctx context.Context, tx *gor
 	expiresAt := CalculateExpiryTime(pkg.CalendarType, activatedAt, pkg.DurationMonths, pkg.DurationDays)
 
 	// 计算下次重置时间
-	billingDay := 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
-				}
-			}
-		}
-	}
-	nextResetAt := CalculateNextResetTime(pkg.DataResetCycle, now, billingDay)
+	nextResetAt := CalculateNextResetTime(pkg.DataResetCycle, pkg.CalendarType, now, activatedAt)
 
 	// 更新套餐使用记录
 	updates := map[string]interface{}{

internal/service/package/reset_service.go

@@ -117,43 +117,48 @@ func (s *ResetService) resetMonthlyUsageWithDB(ctx context.Context, db *gorm.DB)
 			return nil
 		}
 
-		// 按套餐分组处理（因为需要区分联通27号 vs 其他1号）
-		for _, pkg := range packages {
-			// 查询运营商信息以确定计费日
-			// 只有单卡套餐才根据运营商判断，设备级套餐统一使用1号计费
-			billingDay := 1
-			if pkg.IotCardID != 0 {
-				var card model.IotCard
-				if err := tx.First(&card, pkg.IotCardID).Error; err == nil {
-					var carrier model.Carrier
-					if err := tx.First(&carrier, card.CarrierID).Error; err == nil {
-						if carrier.CarrierType == "CUCC" {
-							billingDay = 27
-						}
-					}
-				}
+		// 按套餐分组处理（根据套餐周期类型计算下次重置时间）
+		for _, usage := range packages {
+			// 查询套餐信息，获取 calendar_type
+			var pkg model.Package
+			if err := tx.First(&pkg, usage.PackageID).Error; err != nil {
+				s.logger.Error("查询套餐信息失败",
+					zap.Uint("usage_id", usage.ID),
+					zap.Uint("package_id", usage.PackageID),
+					zap.Error(err))
+				continue
 			}
-			// 设备级套餐默认使用1号计费（已在 billingDay := 1 初始化）
 
-			// 计算下次重置时间
-			nextReset := calculateNextMonthlyResetTime(now, billingDay)
+			// 计算下次重置时间（基于套餐周期类型）
+			// 自然月套餐：每月1号重置
+			// 按天套餐：每30天重置
+			activatedAt := usage.ActivatedAt
+			if activatedAt.IsZero() {
+				activatedAt = now // 兜底处理
+			}
+			nextResetAt := CalculateNextResetTime(constants.PackageDataResetMonthly, pkg.CalendarType, now, activatedAt)
+			if nextResetAt == nil {
+				s.logger.Warn("计算下次重置时间失败",
+					zap.Uint("usage_id", usage.ID))
+				continue
+			}
 
 			// 更新套餐
 			updates := map[string]interface{}{
 				"data_usage_mb": 0,
 				"last_reset_at": now,
-				"next_reset_at": nextReset,
+				"next_reset_at": *nextResetAt,
 				"status":        constants.PackageUsageStatusActive, // 重置后恢复为生效中
 			}
 
-			if err := tx.Model(pkg).Updates(updates).Error; err != nil {
+			if err := tx.Model(usage).Updates(updates).Error; err != nil {
 				return errors.Wrap(errors.CodeDatabaseError, err, "重置月流量失败")
 			}
 
 			s.logger.Info("月流量已重置",
-				zap.Uint("usage_id", pkg.ID),
-				zap.Int("billing_day", billingDay),
-				zap.Time("next_reset_at", nextReset))
+				zap.Uint("usage_id", usage.ID),
+				zap.String("calendar_type", pkg.CalendarType),
+				zap.Time("next_reset_at", *nextResetAt))
 		}
 
 		return nil
@@ -217,26 +222,3 @@ func (s *ResetService) resetYearlyUsageWithDB(ctx context.Context, db *gorm.DB)
 	})
 }
 
-// calculateNextMonthlyResetTime 计算下次月重置时间
-func calculateNextMonthlyResetTime(now time.Time, billingDay int) time.Time {
-	currentDay := now.Day()
-	targetMonth := now.Month()
-	targetYear := now.Year()
-
-	// 如果当前日期 >= 计费日，下次重置是下月计费日
-	if currentDay >= billingDay {
-		targetMonth++
-		if targetMonth > 12 {
-			targetMonth = 1
-			targetYear++
-		}
-	}
-
-	// 处理月末天数不足的情况（例如2月没有27日）
-	maxDay := time.Date(targetYear, targetMonth+1, 0, 0, 0, 0, 0, now.Location()).Day()
-	if billingDay > maxDay {
-		billingDay = maxDay
-	}
-
-	return time.Date(targetYear, targetMonth, billingDay, 0, 0, 0, 0, now.Location())
-}

internal/service/package/utils.go

@@ -40,10 +40,11 @@ func CalculateExpiryTime(calendarType string, activatedAt time.Time, durationMon
 
 // CalculateNextResetTime 计算下次流量重置时间
 // dataResetCycle: 流量重置周期（daily/monthly/yearly/none）
+// calendarType: 套餐周期类型（natural_month/by_day），影响月重置逻辑
 // currentTime: 当前时间
-// billingDay: 计费日（月重置时使用，联通=27，其他=1）
+// activatedAt: 套餐激活时间（按天套餐月重置时使用）
 // 返回：下次重置时间（00:00:00）
-func CalculateNextResetTime(dataResetCycle string, currentTime time.Time, billingDay int) *time.Time {
+func CalculateNextResetTime(dataResetCycle, calendarType string, currentTime, activatedAt time.Time) *time.Time {
 	if dataResetCycle == constants.PackageDataResetNone {
 		// 不重置
 		return nil
@@ -63,46 +64,49 @@ func CalculateNextResetTime(dataResetCycle string, currentTime time.Time, billin
 		)
 
 	case constants.PackageDataResetMonthly:
-		// 月重置：下月 billingDay 号 00:00:00
-		year := currentTime.Year()
-		month := currentTime.Month()
+		if calendarType == constants.PackageCalendarTypeNaturalMonth {
+			// 自然月套餐：每月1号 00:00:00 重置
+			year := currentTime.Year()
+			month := currentTime.Month()
 
-		// 检查 billingDay 是否为当前月的最后一天（月末计费的特殊情况）
-		currentMonthLastDay := time.Date(year, month+1, 0, 0, 0, 0, 0, currentTime.Location()).Day()
-		isBillingDayMonthEnd := billingDay >= currentMonthLastDay
-
-		// 如果当前日期 >= billingDay，则重置时间为下个月的 billingDay
-		// 否则，重置时间为本月的 billingDay
-		// 特殊情况：如果 billingDay 是月末，并且当前日期已接近月末，则跳到下个月
-		shouldUseNextMonth := currentTime.Day() >= billingDay || (isBillingDayMonthEnd && currentTime.Day() >= currentMonthLastDay-1)
-
-		if shouldUseNextMonth {
-			// 下个月
-			month++
-			if month > 12 {
-				month = 1
-				year++
+			// 如果当前日期 >= 1号（即已过重置点），则下次重置为下个月1号
+			if currentTime.Day() >= 1 {
+				month++
+				if month > 12 {
+					month = 1
+					year++
+				}
 			}
-		}
 
-		// 计算目标月份的最后一天（处理月末情况）
-		lastDayOfMonth := time.Date(year, month+1, 0, 0, 0, 0, 0, currentTime.Location()).Day()
-		resetDay := billingDay
-		if billingDay > lastDayOfMonth {
-			// 如果 billingDay 超过该月天数，使用月末
-			resetDay = lastDayOfMonth
-		}
+			nextResetTime = time.Date(year, month, 1, 0, 0, 0, 0, currentTime.Location())
+		} else {
+			// 按天套餐：从激活日期开始，每30天重置一次
+			// 计算从激活到现在经过了多少个30天周期
+			daysSinceActivation := int(currentTime.Sub(activatedAt).Hours() / 24)
+			cyclesPassed := daysSinceActivation / 30
 
-		nextResetTime = time.Date(year, month, resetDay, 0, 0, 0, 0, currentTime.Location())
+			// 下次重置时间 = 激活时间 + (已过周期数+1) * 30天
+			nextResetTime = activatedAt.AddDate(0, 0, (cyclesPassed+1)*30)
+			nextResetTime = time.Date(
+				nextResetTime.Year(),
+				nextResetTime.Month(),
+				nextResetTime.Day(),
+				0, 0, 0, 0,
+				nextResetTime.Location(),
+			)
+		}
 
 	case constants.PackageDataResetYearly:
-		// 年重置：明年 1 月 1 日 00:00:00
-		nextResetTime = time.Date(
-			currentTime.Year()+1,
-			1, 1,
-			0, 0, 0, 0,
-			currentTime.Location(),
-		)
+		// 年重置：每年1月1日 00:00:00
+		year := currentTime.Year()
+
+		// 如果当前日期已经过了1月1日，则使用明年
+		jan1ThisYear := time.Date(year, 1, 1, 0, 0, 0, 0, currentTime.Location())
+		if currentTime.After(jan1ThisYear) || currentTime.Equal(jan1ThisYear) {
+			year++
+		}
+
+		nextResetTime = time.Date(year, 1, 1, 0, 0, 0, 0, currentTime.Location())
 
 	default:
 		return nil