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/store/postgres/device_store.go

@@ -106,6 +106,9 @@ func (s *DeviceStore) List(ctx context.Context, opts *store.QueryOptions, filter
 	if createdAtEnd, ok := filters["created_at_end"].(time.Time); ok && !createdAtEnd.IsZero() {
 		query = query.Where("created_at <= ?", createdAtEnd)
 	}
+	if seriesAllocationID, ok := filters["series_allocation_id"].(uint); ok && seriesAllocationID > 0 {
+		query = query.Where("series_allocation_id = ?", seriesAllocationID)
+	}
 
 	if err := query.Count(&total).Error; err != nil {
 		return nil, 0, err
@@ -181,3 +184,22 @@ func (s *DeviceStore) GetByDeviceNos(ctx context.Context, deviceNos []string) ([
 	}
 	return devices, nil
 }
+
+// BatchUpdateSeriesAllocation 批量更新设备的套餐系列分配
+func (s *DeviceStore) BatchUpdateSeriesAllocation(ctx context.Context, deviceIDs []uint, seriesAllocationID *uint) error {
+	if len(deviceIDs) == 0 {
+		return nil
+	}
+	return s.db.WithContext(ctx).Model(&model.Device{}).
+		Where("id IN ?", deviceIDs).
+		Update("series_allocation_id", seriesAllocationID).Error
+}
+
+// ListBySeriesAllocationID 根据套餐系列分配ID查询设备列表
+func (s *DeviceStore) ListBySeriesAllocationID(ctx context.Context, seriesAllocationID uint) ([]*model.Device, error) {
+	var devices []*model.Device
+	if err := s.db.WithContext(ctx).Where("series_allocation_id = ?", seriesAllocationID).Find(&devices).Error; err != nil {
+		return nil, err
+	}
+	return devices, nil
+}

internal/store/postgres/device_store_test.go

@@ -0,0 +1,119 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/tests/testutils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func uniqueDeviceNoPrefix() string {
+	return fmt.Sprintf("D%d", time.Now().UnixNano()%1000000000)
+}
+
+func TestDeviceStore_BatchUpdateSeriesAllocation(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewDeviceStore(tx, rdb)
+	ctx := context.Background()
+
+	prefix := uniqueDeviceNoPrefix()
+	devices := []*model.Device{
+		{DeviceNo: prefix + "001", DeviceName: "测试设备1", Status: 1},
+		{DeviceNo: prefix + "002", DeviceName: "测试设备2", Status: 1},
+	}
+	require.NoError(t, s.CreateBatch(ctx, devices))
+
+	t.Run("设置系列分配ID", func(t *testing.T) {
+		seriesAllocationID := uint(100)
+		deviceIDs := []uint{devices[0].ID, devices[1].ID}
+
+		err := s.BatchUpdateSeriesAllocation(ctx, deviceIDs, &seriesAllocationID)
+		require.NoError(t, err)
+
+		var updatedDevices []*model.Device
+		require.NoError(t, tx.Where("id IN ?", deviceIDs).Find(&updatedDevices).Error)
+		for _, device := range updatedDevices {
+			require.NotNil(t, device.SeriesAllocationID)
+			assert.Equal(t, seriesAllocationID, *device.SeriesAllocationID)
+		}
+	})
+
+	t.Run("清除系列分配ID", func(t *testing.T) {
+		deviceIDs := []uint{devices[0].ID}
+
+		err := s.BatchUpdateSeriesAllocation(ctx, deviceIDs, nil)
+		require.NoError(t, err)
+
+		var updatedDevice model.Device
+		require.NoError(t, tx.First(&updatedDevice, devices[0].ID).Error)
+		assert.Nil(t, updatedDevice.SeriesAllocationID)
+	})
+
+	t.Run("空列表不报错", func(t *testing.T) {
+		err := s.BatchUpdateSeriesAllocation(ctx, []uint{}, nil)
+		require.NoError(t, err)
+	})
+}
+
+func TestDeviceStore_ListBySeriesAllocationID(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewDeviceStore(tx, rdb)
+	ctx := context.Background()
+
+	prefix := uniqueDeviceNoPrefix()
+	seriesAllocationID := uint(200)
+	devices := []*model.Device{
+		{DeviceNo: prefix + "001", DeviceName: "测试设备1", Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{DeviceNo: prefix + "002", DeviceName: "测试设备2", Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{DeviceNo: prefix + "003", DeviceName: "测试设备3", Status: 1, SeriesAllocationID: nil},
+	}
+	require.NoError(t, s.CreateBatch(ctx, devices))
+
+	result, err := s.ListBySeriesAllocationID(ctx, seriesAllocationID)
+	require.NoError(t, err)
+	assert.Len(t, result, 2)
+	for _, device := range result {
+		assert.Equal(t, seriesAllocationID, *device.SeriesAllocationID)
+	}
+}
+
+func TestDeviceStore_List_SeriesAllocationFilter(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewDeviceStore(tx, rdb)
+	ctx := context.Background()
+
+	prefix := uniqueDeviceNoPrefix()
+	seriesAllocationID := uint(300)
+	devices := []*model.Device{
+		{DeviceNo: prefix + "001", DeviceName: "测试设备1", Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{DeviceNo: prefix + "002", DeviceName: "测试设备2", Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{DeviceNo: prefix + "003", DeviceName: "测试设备3", Status: 1, SeriesAllocationID: nil},
+	}
+	require.NoError(t, s.CreateBatch(ctx, devices))
+
+	filters := map[string]interface{}{
+		"series_allocation_id": seriesAllocationID,
+		"device_no":            prefix,
+	}
+	result, total, err := s.List(ctx, nil, filters)
+	require.NoError(t, err)
+	assert.Equal(t, int64(2), total)
+	assert.Len(t, result, 2)
+	for _, device := range result {
+		assert.Equal(t, seriesAllocationID, *device.SeriesAllocationID)
+	}
+}

internal/store/postgres/iot_card_store.go

@@ -147,6 +147,9 @@ func (s *IotCardStore) List(ctx context.Context, opts *store.QueryOptions, filte
 	if iccidEnd, ok := filters["iccid_end"].(string); ok && iccidEnd != "" {
 		query = query.Where("iccid <= ?", iccidEnd)
 	}
+	if seriesAllocationID, ok := filters["series_allocation_id"].(uint); ok && seriesAllocationID > 0 {
+		query = query.Where("series_allocation_id = ?", seriesAllocationID)
+	}
 
 	// 统计总数
 	if err := query.Count(&total).Error; err != nil {
@@ -239,6 +242,9 @@ func (s *IotCardStore) ListStandalone(ctx context.Context, opts *store.QueryOpti
 					Where("deleted_at IS NULL"))
 		}
 	}
+	if seriesAllocationID, ok := filters["series_allocation_id"].(uint); ok && seriesAllocationID > 0 {
+		query = query.Where("series_allocation_id = ?", seriesAllocationID)
+	}
 
 	if err := query.Count(&total).Error; err != nil {
 		return nil, 0, err
@@ -374,3 +380,24 @@ func (s *IotCardStore) GetByIDsWithEnterpriseFilter(ctx context.Context, cardIDs
 	}
 	return cards, nil
 }
+
+// BatchUpdateSeriesAllocation 批量更新卡的套餐系列分配
+// 用于批量设置或清除卡与套餐系列的关联关系
+func (s *IotCardStore) BatchUpdateSeriesAllocation(ctx context.Context, cardIDs []uint, seriesAllocationID *uint) error {
+	if len(cardIDs) == 0 {
+		return nil
+	}
+	return s.db.WithContext(ctx).Model(&model.IotCard{}).
+		Where("id IN ?", cardIDs).
+		Update("series_allocation_id", seriesAllocationID).Error
+}
+
+// ListBySeriesAllocationID 根据套餐系列分配ID查询卡列表
+// 用于查询某个套餐系列分配下的所有卡
+func (s *IotCardStore) ListBySeriesAllocationID(ctx context.Context, seriesAllocationID uint) ([]*model.IotCard, error) {
+	var cards []*model.IotCard
+	if err := s.db.WithContext(ctx).Where("series_allocation_id = ?", seriesAllocationID).Find(&cards).Error; err != nil {
+		return nil, err
+	}
+	return cards, nil
+}

internal/store/postgres/iot_card_store_test.go

@@ -425,3 +425,103 @@ func TestIotCardStore_GetBoundCardIDs(t *testing.T) {
 		assert.Nil(t, result)
 	})
 }
+
+func TestIotCardStore_BatchUpdateSeriesAllocation(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	cards := []*model.IotCard{
+		{ICCID: "89860012345678910001", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "89860012345678910002", CardType: "data_card", CarrierID: 1, Status: 1},
+	}
+	require.NoError(t, s.CreateBatch(ctx, cards))
+
+	t.Run("设置系列分配ID", func(t *testing.T) {
+		seriesAllocationID := uint(100)
+		cardIDs := []uint{cards[0].ID, cards[1].ID}
+
+		err := s.BatchUpdateSeriesAllocation(ctx, cardIDs, &seriesAllocationID)
+		require.NoError(t, err)
+
+		var updatedCards []*model.IotCard
+		require.NoError(t, tx.Where("id IN ?", cardIDs).Find(&updatedCards).Error)
+		for _, card := range updatedCards {
+			require.NotNil(t, card.SeriesAllocationID)
+			assert.Equal(t, seriesAllocationID, *card.SeriesAllocationID)
+		}
+	})
+
+	t.Run("清除系列分配ID", func(t *testing.T) {
+		cardIDs := []uint{cards[0].ID}
+
+		err := s.BatchUpdateSeriesAllocation(ctx, cardIDs, nil)
+		require.NoError(t, err)
+
+		var updatedCard model.IotCard
+		require.NoError(t, tx.First(&updatedCard, cards[0].ID).Error)
+		assert.Nil(t, updatedCard.SeriesAllocationID)
+	})
+
+	t.Run("空列表不报错", func(t *testing.T) {
+		err := s.BatchUpdateSeriesAllocation(ctx, []uint{}, nil)
+		require.NoError(t, err)
+	})
+}
+
+func TestIotCardStore_ListBySeriesAllocationID(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	seriesAllocationID := uint(200)
+	cards := []*model.IotCard{
+		{ICCID: "89860012345678911001", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{ICCID: "89860012345678911002", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{ICCID: "89860012345678911003", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: nil},
+	}
+	require.NoError(t, s.CreateBatch(ctx, cards))
+
+	result, err := s.ListBySeriesAllocationID(ctx, seriesAllocationID)
+	require.NoError(t, err)
+	assert.Len(t, result, 2)
+	for _, card := range result {
+		assert.Equal(t, seriesAllocationID, *card.SeriesAllocationID)
+	}
+}
+
+func TestIotCardStore_ListStandalone_SeriesAllocationFilter(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	prefix := uniqueICCIDPrefix()
+	seriesAllocationID := uint(300)
+	cards := []*model.IotCard{
+		{ICCID: prefix + "S001", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{ICCID: prefix + "S002", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: &seriesAllocationID},
+		{ICCID: prefix + "S003", CardType: "data_card", CarrierID: 1, Status: 1, SeriesAllocationID: nil},
+	}
+	require.NoError(t, s.CreateBatch(ctx, cards))
+
+	filters := map[string]interface{}{
+		"series_allocation_id": seriesAllocationID,
+		"iccid":                prefix,
+	}
+	result, total, err := s.ListStandalone(ctx, nil, filters)
+	require.NoError(t, err)
+	assert.Equal(t, int64(2), total)
+	assert.Len(t, result, 2)
+	for _, card := range result {
+		assert.Equal(t, seriesAllocationID, *card.SeriesAllocationID)
+	}
+}