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

@@ -20,6 +20,8 @@ type Service struct {
 	shopStore                  *postgres.ShopStore
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore
 	seriesAllocationStore      *postgres.ShopSeriesAllocationStore
+	packageSeriesStore         *postgres.PackageSeriesStore
+	shopSeriesAllocationStore  *postgres.ShopSeriesAllocationStore
 }
 
 func New(
@@ -30,6 +32,7 @@ func New(
 	shopStore *postgres.ShopStore,
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore,
 	seriesAllocationStore *postgres.ShopSeriesAllocationStore,
+	packageSeriesStore *postgres.PackageSeriesStore,
 ) *Service {
 	return &Service{
 		db:                         db,
@@ -39,6 +42,8 @@ func New(
 		shopStore:                  shopStore,
 		assetAllocationRecordStore: assetAllocationRecordStore,
 		seriesAllocationStore:      seriesAllocationStore,
+		packageSeriesStore:         packageSeriesStore,
+		shopSeriesAllocationStore:  seriesAllocationStore,
 	}
 }
 
@@ -86,8 +91,8 @@ func (s *Service) List(ctx context.Context, req *dto.ListDeviceRequest) (*dto.Li
 	if req.CreatedAtEnd != nil {
 		filters["created_at_end"] = *req.CreatedAtEnd
 	}
-	if req.SeriesAllocationID != nil {
-		filters["series_allocation_id"] = *req.SeriesAllocationID
+	if req.SeriesID != nil {
+		filters["series_id"] = *req.SeriesID
 	}
 
 	devices, total, err := s.deviceStore.List(ctx, opts, filters)
@@ -466,7 +471,7 @@ func (s *Service) toDeviceResponse(device *model.Device, shopMap map[uint]string
 		Status:              device.Status,
 		StatusName:          s.getDeviceStatusName(device.Status),
 		BoundCardCount:      int(bindingCounts[device.ID]),
-		SeriesAllocationID:  device.SeriesAllocationID,
+		SeriesID:            device.SeriesID,
 		FirstCommissionPaid: device.FirstCommissionPaid,
 		AccumulatedRecharge: device.AccumulatedRecharge,
 		ActivatedAt:         device.ActivatedAt,
@@ -598,17 +603,18 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetDe
 		deviceMap[device.ID] = device
 	}
 
-	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, "套餐系列不存在或已禁用")
 		}
 	}
 
@@ -626,17 +632,23 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetDe
 			continue
 		}
 
-		if req.SeriesAllocationID > 0 {
-			if device.ShopID == nil || *device.ShopID != seriesAllocation.ShopID {
-				failedItems = append(failedItems, dto.DeviceSeriesBindngFailedItem{
-					DeviceID: device.ID,
-					DeviceNo: device.DeviceNo,
-					Reason:   "设备不属于套餐系列分配的店铺",
-				})
-				continue
+		// 验证操作者权限（仅代理用户）
+		if operatorShopID != nil && req.SeriesID > 0 {
+			allocation, err := s.shopSeriesAllocationStore.GetByShopAndSeries(ctx, *operatorShopID, req.SeriesID)
+			if err != nil {
+				if err == gorm.ErrRecordNotFound || allocation.Status != 1 {
+					failedItems = append(failedItems, dto.DeviceSeriesBindngFailedItem{
+						DeviceID: deviceID,
+						DeviceNo: device.DeviceNo,
+						Reason:   "您没有权限分配该套餐系列",
+					})
+					continue
+				}
+				return nil, err
 			}
 		}
 
+		// 验证设备权限（基于 device.ShopID）
 		if operatorShopID != nil {
 			if device.ShopID == nil || *device.ShopID != *operatorShopID {
 				failedItems = append(failedItems, dto.DeviceSeriesBindngFailedItem{
@@ -652,11 +664,11 @@ func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetDe
 	}
 
 	if len(successDeviceIDs) > 0 {
-		var seriesAllocationIDPtr *uint
-		if req.SeriesAllocationID > 0 {
-			seriesAllocationIDPtr = &req.SeriesAllocationID
+		var seriesIDPtr *uint
+		if req.SeriesID > 0 {
+			seriesIDPtr = &req.SeriesID
 		}
-		if err := s.deviceStore.BatchUpdateSeriesAllocation(ctx, successDeviceIDs, seriesAllocationIDPtr); err != nil {
+		if err := s.deviceStore.BatchUpdateSeriesID(ctx, successDeviceIDs, seriesIDPtr); err != nil {
 			return nil, err
 		}
 	}

internal/service/device/service_test.go

@@ -29,8 +29,9 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 	shopStore := postgres.NewShopStore(tx, rdb)
 	assetAllocationRecordStore := postgres.NewAssetAllocationRecordStore(tx, rdb)
 	seriesAllocationStore := postgres.NewShopSeriesAllocationStore(tx)
+	packageSeriesStore := postgres.NewPackageSeriesStore(tx)
 
-	svc := New(tx, deviceStore, deviceSimBindingStore, iotCardStore, shopStore, assetAllocationRecordStore, seriesAllocationStore)
+	svc := New(tx, deviceStore, deviceSimBindingStore, iotCardStore, shopStore, assetAllocationRecordStore, seriesAllocationStore, packageSeriesStore)
 	ctx := context.Background()
 
 	shop := &model.Shop{
@@ -65,8 +66,8 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("成功设置系列绑定", func(t *testing.T) {
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{devices[0].ID, devices[1].ID},
-			SeriesAllocationID: allocation.ID,
+			DeviceIDs: []uint{devices[0].ID, devices[1].ID},
+			SeriesID:  allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -77,15 +78,15 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 		var updatedDevices []*model.Device
 		require.NoError(t, tx.Where("id IN ?", req.DeviceIDs).Find(&updatedDevices).Error)
 		for _, device := range updatedDevices {
-			require.NotNil(t, device.SeriesAllocationID)
-			assert.Equal(t, allocation.ID, *device.SeriesAllocationID)
+			require.NotNil(t, device.SeriesID)
+			assert.Equal(t, allocation.SeriesID, *device.SeriesID)
 		}
 	})
 
 	t.Run("设备不属于套餐系列分配的店铺", func(t *testing.T) {
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{devices[2].ID},
-			SeriesAllocationID: allocation.ID,
+			DeviceIDs: []uint{devices[2].ID},
+			SeriesID:  allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -97,8 +98,8 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("设备不存在", func(t *testing.T) {
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{99999},
-			SeriesAllocationID: allocation.ID,
+			DeviceIDs: []uint{99999},
+			SeriesID:  allocation.SeriesID,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -110,8 +111,8 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("清除系列绑定", func(t *testing.T) {
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{devices[0].ID},
-			SeriesAllocationID: 0,
+			DeviceIDs: []uint{devices[0].ID},
+			SeriesID:  0,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, nil)
@@ -120,14 +121,14 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 
 		var updatedDevice model.Device
 		require.NoError(t, tx.First(&updatedDevice, devices[0].ID).Error)
-		assert.Nil(t, updatedDevice.SeriesAllocationID)
+		assert.Nil(t, updatedDevice.SeriesID)
 	})
 
 	t.Run("代理用户只能操作自己店铺的设备", func(t *testing.T) {
 		otherShopID := uint(99999)
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{devices[1].ID},
-			SeriesAllocationID: 0,
+			DeviceIDs: []uint{devices[1].ID},
+			SeriesID:  0,
 		}
 
 		resp, err := svc.BatchSetSeriesBinding(ctx, req, &otherShopID)
@@ -139,8 +140,8 @@ func TestDeviceService_BatchSetSeriesBinding(t *testing.T) {
 
 	t.Run("套餐系列分配不存在", func(t *testing.T) {
 		req := &dto.BatchSetDeviceSeriesBindngRequest{
-			DeviceIDs:          []uint{devices[1].ID},
-			SeriesAllocationID: 99999,
+			DeviceIDs: []uint{devices[1].ID},
+			SeriesID:  99999,
 		}
 
 		_, err := svc.BatchSetSeriesBinding(ctx, req, nil)