重构: 将卡/设备的套餐系列绑定从分配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
 		}
 	}

internal/service/iot_card/service_test.go

@@ -28,7 +28,8 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 	assetAllocationRecordStore := postgres.NewAssetAllocationRecordStore(tx, rdb)
 	seriesAllocationStore := postgres.NewShopSeriesAllocationStore(tx)
 
-	svc := New(tx, iotCardStore, shopStore, assetAllocationRecordStore, seriesAllocationStore, nil, nil)
+	packageSeriesStore := postgres.NewPackageSeriesStore(tx)
+	svc := New(tx, iotCardStore, shopStore, assetAllocationRecordStore, seriesAllocationStore, packageSeriesStore, nil, nil)
 	ctx := context.Background()
 
 	shop := &model.Shop{
@@ -63,8 +64,8 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("成功设置系列绑定", func(t *testing.T) {
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{prefix + "001", prefix + "002"},
-			SeriesAllocationID: allocation.ID,
+			ICCIDs:   []string{prefix + "001", prefix + "002"},
+			SeriesID: allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -75,15 +76,15 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 		var updatedCards []*model.IotCard
 		require.NoError(t, tx.Where("iccid IN ?", req.ICCIDs).Find(&updatedCards).Error)
 		for _, card := range updatedCards {
-			require.NotNil(t, card.SeriesAllocationID)
-			assert.Equal(t, allocation.ID, *card.SeriesAllocationID)
+			require.NotNil(t, card.SeriesID)
+			assert.Equal(t, allocation.SeriesID, *card.SeriesID)
 		}
 	})
 
 	t.Run("卡不属于套餐系列分配的店铺", func(t *testing.T) {
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{prefix + "003"},
-			SeriesAllocationID: allocation.ID,
+			ICCIDs:   []string{prefix + "003"},
+			SeriesID: allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -95,8 +96,8 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("卡不存在", func(t *testing.T) {
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{"NOTEXIST001"},
-			SeriesAllocationID: allocation.ID,
+			ICCIDs:   []string{"NOTEXIST001"},
+			SeriesID: allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -108,8 +109,8 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("清除系列绑定", func(t *testing.T) {
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{prefix + "001"},
-			SeriesAllocationID: 0,
+			ICCIDs:   []string{prefix + "001"},
+			SeriesID: 0,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -118,14 +119,14 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 
 		var updatedCard model.IotCard
 		require.NoError(t, tx.Where("iccid = ?", prefix+"001").First(&updatedCard).Error)
-		assert.Nil(t, updatedCard.SeriesAllocationID)
+		assert.Nil(t, updatedCard.SeriesID)
 	})
 
 	t.Run("代理用户只能操作自己店铺的卡", func(t *testing.T) {
 		otherShopID := uint(99999)
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{prefix + "002"},
-			SeriesAllocationID: 0,
+			ICCIDs:   []string{prefix + "002"},
+			SeriesID: 0,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, &otherShopID)
@@ -137,8 +138,8 @@ func TestIotCardService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("套餐系列分配不存在", func(t *testing.T) {
 		req := &dto.BatchSetCardSeriesBindngRequest{
-			ICCIDs:             []string{prefix + "002"},
-			SeriesAllocationID: 99999,
+			ICCIDs:   []string{prefix + "002"},
+			SeriesID: 99999,
 		}
 
 		_, err := svc.BatchSetSeriesBinding(ctx, req, nil)