重构: 将卡/设备的套餐系列绑定从分配ID改为系列ID

- 数据库: 重命名 series_allocation_id → series_id
- Model: IotCard 和 Device 字段重命名
- DTO: 所有请求/响应字段统一为 series_id
- Store: 方法重命名，新增 GetByShopAndSeries 查询
- Service: 业务逻辑优化，系列验证和权限验证分离
- 测试: 更新所有测试用例，新增 shop_series_allocation_store_test.go
- 文档: 更新 API 文档说明参数变更

BREAKING CHANGE: API 参数从 series_allocation_id 改为 series_id

internal/service/iot_card/service.go

@@ -20,6 +20,7 @@ type Service struct {
 	shopStore                  *postgres.ShopStore
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore
 	seriesAllocationStore      *postgres.ShopSeriesAllocationStore
+	packageSeriesStore         *postgres.PackageSeriesStore
 	gatewayClient              *gateway.Client
 	logger                     *zap.Logger
 }
@@ -30,6 +31,7 @@ func New(
 	shopStore *postgres.ShopStore,
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore,
 	seriesAllocationStore *postgres.ShopSeriesAllocationStore,
+	packageSeriesStore *postgres.PackageSeriesStore,
 	gatewayClient *gateway.Client,
 	logger *zap.Logger,
 ) *Service {
@@ -39,6 +41,7 @@ func New(
 		shopStore:                  shopStore,
 		assetAllocationRecordStore: assetAllocationRecordStore,
 		seriesAllocationStore:      seriesAllocationStore,
+		packageSeriesStore:         packageSeriesStore,
 		gatewayClient:              gatewayClient,
 		logger:                     logger,
 	}
@@ -93,8 +96,8 @@ func (s *Service) ListStandalone(ctx context.Context, req *dto.ListStandaloneIot
 	if req.IsReplaced != nil {
 		filters["is_replaced"] = *req.IsReplaced
 	}
-	if req.SeriesAllocationID != nil {
-		filters["series_allocation_id"] = *req.SeriesAllocationID
+	if req.SeriesID != nil {
+		filters["series_id"] = *req.SeriesID
 	}
 
 	cards, total, err := s.iotCardStore.ListStandalone(ctx, opts, filters)
@@ -187,7 +190,7 @@ func (s *Service) toStandaloneResponse(card *model.IotCard, shopMap map[uint]str
 		RealNameStatus:      card.RealNameStatus,
 		NetworkStatus:       card.NetworkStatus,
 		DataUsageMB:         card.DataUsageMB,
-		SeriesAllocationID:  card.SeriesAllocationID,
+		SeriesID:            card.SeriesID,
 		FirstCommissionPaid: card.FirstCommissionPaid,
 		AccumulatedRecharge: card.AccumulatedRecharge,
 		CreatedAt:           card.CreatedAt,
@@ -571,17 +574,18 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetCa
 		cardMap[card.ICCID] = card
 	}
 
-	var seriesAllocation *model.ShopSeriesAllocation
-	if req.SeriesAllocationID > 0 {
-		seriesAllocation, err = s.seriesAllocationStore.GetByID(ctx, req.SeriesAllocationID)
+	// 验证系列存在（仅当 SeriesID > 0 时）
+	var packageSeries *model.PackageSeries
+	if req.SeriesID > 0 {
+		packageSeries, err = s.packageSeriesStore.GetByID(ctx, req.SeriesID)
 		if err != nil {
 			if err == gorm.ErrRecordNotFound {
-				return nil, errors.New(errors.CodeNotFound, "套餐系列分配不存在")
+				return nil, errors.New(errors.CodeNotFound, "套餐系列不存在或已禁用")
 			}
 			return nil, err
 		}
-		if seriesAllocation.Status != 1 {
-			return nil, errors.New(errors.CodeInvalidParam, "套餐系列分配已禁用")
+		if packageSeries.Status != 1 {
+			return nil, errors.New(errors.CodeInvalidParam, "套餐系列不存在或已禁用")
 		}
 	}
 
@@ -598,16 +602,22 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetCa
 			continue
 		}
 
-		if req.SeriesAllocationID > 0 {
-			if card.ShopID == nil || *card.ShopID != seriesAllocation.ShopID {
-				failedItems = append(failedItems, dto.CardSeriesBindngFailedItem{
-					ICCID:  iccid,
-					Reason: "卡不属于套餐系列分配的店铺",
-				})
-				continue
+		// 验证操作者权限（仅代理用户）
+		if operatorShopID != nil && req.SeriesID > 0 {
+			allocation, err := s.seriesAllocationStore.GetByShopAndSeries(ctx, *operatorShopID, req.SeriesID)
+			if err != nil {
+				if err == gorm.ErrRecordNotFound || allocation.Status != 1 {
+					failedItems = append(failedItems, dto.CardSeriesBindngFailedItem{
+						ICCID:  iccid,
+						Reason: "您没有权限分配该套餐系列",
+					})
+					continue
+				}
+				return nil, err
 			}
 		}
 
+		// 验证卡权限（基于 card.ShopID）
 		if operatorShopID != nil {
 			if card.ShopID == nil || *card.ShopID != *operatorShopID {
 				failedItems = append(failedItems, dto.CardSeriesBindngFailedItem{
@@ -622,11 +632,11 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetCa
 	}
 
 	if len(successCardIDs) > 0 {
-		var seriesAllocationIDPtr *uint
-		if req.SeriesAllocationID > 0 {
-			seriesAllocationIDPtr = &req.SeriesAllocationID
+		var seriesIDPtr *uint
+		if req.SeriesID > 0 {
+			seriesIDPtr = &req.SeriesID
 		}
-		if err := s.iotCardStore.BatchUpdateSeriesAllocation(ctx, successCardIDs, seriesAllocationIDPtr); err != nil {
+		if err := s.iotCardStore.BatchUpdateSeriesID(ctx, successCardIDs, seriesIDPtr); err != nil {
 			return nil, err
 		}
 	}