feat: 实现卡和设备的套餐系列绑定功能

- 添加 Device 和 IotCard 模型的 SeriesID 字段
- 实现 DeviceService 和 IotCardService 的套餐系列绑定逻辑
- 添加 DeviceStore 和 IotCardStore 的数据库操作方法
- 更新 API 接口和路由支持套餐系列绑定
- 创建数据库迁移脚本（000027_add_series_binding_fields）
- 添加完整的单元测试和集成测试
- 更新 OpenAPI 文档
- 归档 OpenSpec 变更文档

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

internal/service/device/service.go

@@ -19,6 +19,7 @@ type Service struct {
 	iotCardStore               *postgres.IotCardStore
 	shopStore                  *postgres.ShopStore
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore
+	seriesAllocationStore      *postgres.ShopSeriesAllocationStore
 }
 
 func New(
@@ -28,6 +29,7 @@ func New(
 	iotCardStore *postgres.IotCardStore,
 	shopStore *postgres.ShopStore,
 	assetAllocationRecordStore *postgres.AssetAllocationRecordStore,
+	seriesAllocationStore *postgres.ShopSeriesAllocationStore,
 ) *Service {
 	return &Service{
 		db:                         db,
@@ -36,6 +38,7 @@ func New(
 		iotCardStore:               iotCardStore,
 		shopStore:                  shopStore,
 		assetAllocationRecordStore: assetAllocationRecordStore,
+		seriesAllocationStore:      seriesAllocationStore,
 	}
 }
 
@@ -83,6 +86,9 @@ 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
+	}
 
 	devices, total, err := s.deviceStore.List(ctx, opts, filters)
 	if err != nil {
@@ -448,21 +454,24 @@ func (s *Service) extractDeviceIDs(devices []*model.Device) []uint {
 
 func (s *Service) toDeviceResponse(device *model.Device, shopMap map[uint]string, bindingCounts map[uint]int64) *dto.DeviceResponse {
 	resp := &dto.DeviceResponse{
-		ID:             device.ID,
-		DeviceNo:       device.DeviceNo,
-		DeviceName:     device.DeviceName,
-		DeviceModel:    device.DeviceModel,
-		DeviceType:     device.DeviceType,
-		MaxSimSlots:    device.MaxSimSlots,
-		Manufacturer:   device.Manufacturer,
-		BatchNo:        device.BatchNo,
-		ShopID:         device.ShopID,
-		Status:         device.Status,
-		StatusName:     s.getDeviceStatusName(device.Status),
-		BoundCardCount: int(bindingCounts[device.ID]),
-		ActivatedAt:    device.ActivatedAt,
-		CreatedAt:      device.CreatedAt,
-		UpdatedAt:      device.UpdatedAt,
+		ID:                  device.ID,
+		DeviceNo:            device.DeviceNo,
+		DeviceName:          device.DeviceName,
+		DeviceModel:         device.DeviceModel,
+		DeviceType:          device.DeviceType,
+		MaxSimSlots:         device.MaxSimSlots,
+		Manufacturer:        device.Manufacturer,
+		BatchNo:             device.BatchNo,
+		ShopID:              device.ShopID,
+		Status:              device.Status,
+		StatusName:          s.getDeviceStatusName(device.Status),
+		BoundCardCount:      int(bindingCounts[device.ID]),
+		SeriesAllocationID:  device.SeriesAllocationID,
+		FirstCommissionPaid: device.FirstCommissionPaid,
+		AccumulatedRecharge: device.AccumulatedRecharge,
+		ActivatedAt:         device.ActivatedAt,
+		CreatedAt:           device.CreatedAt,
+		UpdatedAt:           device.UpdatedAt,
 	}
 
 	if device.ShopID != nil && *device.ShopID > 0 {
@@ -568,3 +577,105 @@ func (s *Service) buildRecallRecords(devices []*model.Device, successDeviceIDs [
 
 	return records
 }
+
+// BatchSetSeriesBinding 批量设置设备的套餐系列绑定
+func (s *Service) BatchSetSeriesBinding(ctx context.Context, req *dto.BatchSetDeviceSeriesBindngRequest, operatorShopID *uint) (*dto.BatchSetDeviceSeriesBindngResponse, error) {
+	devices, err := s.deviceStore.GetByIDs(ctx, req.DeviceIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(devices) == 0 {
+		return &dto.BatchSetDeviceSeriesBindngResponse{
+			SuccessCount: 0,
+			FailCount:    len(req.DeviceIDs),
+			FailedItems:  s.buildDeviceNotFoundFailedItems(req.DeviceIDs),
+		}, nil
+	}
+
+	deviceMap := make(map[uint]*model.Device)
+	for _, device := range devices {
+		deviceMap[device.ID] = device
+	}
+
+	var seriesAllocation *model.ShopSeriesAllocation
+	if req.SeriesAllocationID > 0 {
+		seriesAllocation, err = s.seriesAllocationStore.GetByID(ctx, req.SeriesAllocationID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return nil, errors.New(errors.CodeNotFound, "套餐系列分配不存在")
+			}
+			return nil, err
+		}
+		if seriesAllocation.Status != 1 {
+			return nil, errors.New(errors.CodeInvalidParam, "套餐系列分配已禁用")
+		}
+	}
+
+	var successDeviceIDs []uint
+	var failedItems []dto.DeviceSeriesBindngFailedItem
+
+	for _, deviceID := range req.DeviceIDs {
+		device, exists := deviceMap[deviceID]
+		if !exists {
+			failedItems = append(failedItems, dto.DeviceSeriesBindngFailedItem{
+				DeviceID: deviceID,
+				DeviceNo: "",
+				Reason:   "设备不存在",
+			})
+			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 {
+			if device.ShopID == nil || *device.ShopID != *operatorShopID {
+				failedItems = append(failedItems, dto.DeviceSeriesBindngFailedItem{
+					DeviceID: device.ID,
+					DeviceNo: device.DeviceNo,
+					Reason:   "无权操作此设备",
+				})
+				continue
+			}
+		}
+
+		successDeviceIDs = append(successDeviceIDs, device.ID)
+	}
+
+	if len(successDeviceIDs) > 0 {
+		var seriesAllocationIDPtr *uint
+		if req.SeriesAllocationID > 0 {
+			seriesAllocationIDPtr = &req.SeriesAllocationID
+		}
+		if err := s.deviceStore.BatchUpdateSeriesAllocation(ctx, successDeviceIDs, seriesAllocationIDPtr); err != nil {
+			return nil, err
+		}
+	}
+
+	return &dto.BatchSetDeviceSeriesBindngResponse{
+		SuccessCount: len(successDeviceIDs),
+		FailCount:    len(failedItems),
+		FailedItems:  failedItems,
+	}, nil
+}
+
+func (s *Service) buildDeviceNotFoundFailedItems(deviceIDs []uint) []dto.DeviceSeriesBindngFailedItem {
+	items := make([]dto.DeviceSeriesBindngFailedItem, len(deviceIDs))
+	for i, id := range deviceIDs {
+		items[i] = dto.DeviceSeriesBindngFailedItem{
+			DeviceID: id,
+			DeviceNo: "",
+			Reason:   "设备不存在",
+		}
+	}
+	return items
+}