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/model/device.go

@@ -25,6 +25,9 @@ type Device struct {
 	DeviceUsername          string     `gorm:"column:device_username;type:varchar(100);comment:设备登录用户名" json:"device_username"`
 	DevicePasswordEncrypted string     `gorm:"column:device_password_encrypted;type:varchar(255);comment:设备登录密码(加密)" json:"device_password_encrypted"`
 	DeviceAPIEndpoint       string     `gorm:"column:device_api_endpoint;type:varchar(500);comment:设备API端点" json:"device_api_endpoint"`
+	SeriesAllocationID      *uint      `gorm:"column:series_allocation_id;index;comment:套餐系列分配ID(关联ShopSeriesAllocation)" json:"series_allocation_id,omitempty"`
+	FirstCommissionPaid     bool       `gorm:"column:first_commission_paid;type:boolean;default:false;comment:一次性佣金是否已发放" json:"first_commission_paid"`
+	AccumulatedRecharge     int64      `gorm:"column:accumulated_recharge;type:bigint;default:0;comment:累计充值金额(分)" json:"accumulated_recharge"`
 }
 
 // TableName 指定表名

internal/model/dto/device_dto.go

@@ -3,36 +3,40 @@ package dto
 import "time"
 
 type ListDeviceRequest struct {
-	Page           int        `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
-	PageSize       int        `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
-	DeviceNo       string     `json:"device_no" query:"device_no" validate:"omitempty,max=100" maxLength:"100" description:"设备号(模糊查询)"`
-	DeviceName     string     `json:"device_name" query:"device_name" validate:"omitempty,max=255" maxLength:"255" description:"设备名称(模糊查询)"`
-	Status         *int       `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
-	ShopID         *uint      `json:"shop_id" query:"shop_id" description:"店铺ID (NULL表示平台库存)"`
-	BatchNo        string     `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
-	DeviceType     string     `json:"device_type" query:"device_type" validate:"omitempty,max=50" maxLength:"50" description:"设备类型"`
-	Manufacturer   string     `json:"manufacturer" query:"manufacturer" validate:"omitempty,max=255" maxLength:"255" description:"制造商(模糊查询)"`
-	CreatedAtStart *time.Time `json:"created_at_start" query:"created_at_start" description:"创建时间起始"`
-	CreatedAtEnd   *time.Time `json:"created_at_end" query:"created_at_end" description:"创建时间结束"`
+	Page               int        `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize           int        `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	DeviceNo           string     `json:"device_no" query:"device_no" validate:"omitempty,max=100" maxLength:"100" description:"设备号(模糊查询)"`
+	DeviceName         string     `json:"device_name" query:"device_name" validate:"omitempty,max=255" maxLength:"255" description:"设备名称(模糊查询)"`
+	Status             *int       `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	ShopID             *uint      `json:"shop_id" query:"shop_id" description:"店铺ID (NULL表示平台库存)"`
+	SeriesAllocationID *uint      `json:"series_allocation_id" query:"series_allocation_id" description:"套餐系列分配ID"`
+	BatchNo            string     `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
+	DeviceType         string     `json:"device_type" query:"device_type" validate:"omitempty,max=50" maxLength:"50" description:"设备类型"`
+	Manufacturer       string     `json:"manufacturer" query:"manufacturer" validate:"omitempty,max=255" maxLength:"255" description:"制造商(模糊查询)"`
+	CreatedAtStart     *time.Time `json:"created_at_start" query:"created_at_start" description:"创建时间起始"`
+	CreatedAtEnd       *time.Time `json:"created_at_end" query:"created_at_end" description:"创建时间结束"`
 }
 
 type DeviceResponse struct {
-	ID             uint       `json:"id" description:"设备ID"`
-	DeviceNo       string     `json:"device_no" description:"设备号"`
-	DeviceName     string     `json:"device_name" description:"设备名称"`
-	DeviceModel    string     `json:"device_model" description:"设备型号"`
-	DeviceType     string     `json:"device_type" description:"设备类型"`
-	MaxSimSlots    int        `json:"max_sim_slots" description:"最大插槽数"`
-	Manufacturer   string     `json:"manufacturer" description:"制造商"`
-	BatchNo        string     `json:"batch_no" description:"批次号"`
-	ShopID         *uint      `json:"shop_id,omitempty" description:"店铺ID"`
-	ShopName       string     `json:"shop_name,omitempty" description:"店铺名称"`
-	Status         int        `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
-	StatusName     string     `json:"status_name" description:"状态名称"`
-	BoundCardCount int        `json:"bound_card_count" description:"已绑定卡数量"`
-	ActivatedAt    *time.Time `json:"activated_at,omitempty" description:"激活时间"`
-	CreatedAt      time.Time  `json:"created_at" description:"创建时间"`
-	UpdatedAt      time.Time  `json:"updated_at" description:"更新时间"`
+	ID                  uint       `json:"id" description:"设备ID"`
+	DeviceNo            string     `json:"device_no" description:"设备号"`
+	DeviceName          string     `json:"device_name" description:"设备名称"`
+	DeviceModel         string     `json:"device_model" description:"设备型号"`
+	DeviceType          string     `json:"device_type" description:"设备类型"`
+	MaxSimSlots         int        `json:"max_sim_slots" description:"最大插槽数"`
+	Manufacturer        string     `json:"manufacturer" description:"制造商"`
+	BatchNo             string     `json:"batch_no" description:"批次号"`
+	ShopID              *uint      `json:"shop_id,omitempty" description:"店铺ID"`
+	ShopName            string     `json:"shop_name,omitempty" description:"店铺名称"`
+	Status              int        `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	StatusName          string     `json:"status_name" description:"状态名称"`
+	BoundCardCount      int        `json:"bound_card_count" description:"已绑定卡数量"`
+	SeriesAllocationID  *uint      `json:"series_allocation_id,omitempty" description:"套餐系列分配ID"`
+	FirstCommissionPaid bool       `json:"first_commission_paid" description:"一次性佣金是否已发放"`
+	AccumulatedRecharge int64      `json:"accumulated_recharge" description:"累计充值金额(分)"`
+	ActivatedAt         *time.Time `json:"activated_at,omitempty" description:"激活时间"`
+	CreatedAt           time.Time  `json:"created_at" description:"创建时间"`
+	UpdatedAt           time.Time  `json:"updated_at" description:"更新时间"`
 }
 
 type ListDeviceResponse struct {
@@ -122,3 +126,23 @@ type RecallDevicesResponse struct {
 	FailCount    int                          `json:"fail_count" description:"失败数量"`
 	FailedItems  []AllocationDeviceFailedItem `json:"failed_items" description:"失败详情列表"`
 }
+
+// BatchSetDeviceSeriesBindngRequest 批量设置设备的套餐系列绑定请求
+type BatchSetDeviceSeriesBindngRequest struct {
+	DeviceIDs          []uint `json:"device_ids" validate:"required,min=1,max=500,dive,required" required:"true" minItems:"1" maxItems:"500" description:"设备ID列表"`
+	SeriesAllocationID uint   `json:"series_allocation_id" validate:"required,min=0" required:"true" minimum:"0" description:"套餐系列分配ID（0表示清除关联）"`
+}
+
+// DeviceSeriesBindngFailedItem 设备系列绑定失败项
+type DeviceSeriesBindngFailedItem struct {
+	DeviceID uint   `json:"device_id" description:"设备ID"`
+	DeviceNo string `json:"device_no" description:"设备号"`
+	Reason   string `json:"reason" description:"失败原因"`
+}
+
+// BatchSetDeviceSeriesBindngResponse 批量设置设备的套餐系列绑定响应
+type BatchSetDeviceSeriesBindngResponse struct {
+	SuccessCount int                            `json:"success_count" description:"成功数量"`
+	FailCount    int                            `json:"fail_count" description:"失败数量"`
+	FailedItems  []DeviceSeriesBindngFailedItem `json:"failed_items" description:"失败详情列表"`
+}

internal/model/dto/iot_card_dto.go

@@ -3,45 +3,49 @@ package dto
 import "time"
 
 type ListStandaloneIotCardRequest struct {
-	Page          int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
-	PageSize      int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
-	Status        *int   `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
-	CarrierID     *uint  `json:"carrier_id" query:"carrier_id" description:"运营商ID"`
-	ShopID        *uint  `json:"shop_id" query:"shop_id" description:"分销商ID"`
-	ICCID         string `json:"iccid" query:"iccid" validate:"omitempty,max=20" maxLength:"20" description:"ICCID(模糊查询)"`
-	MSISDN        string `json:"msisdn" query:"msisdn" validate:"omitempty,max=20" maxLength:"20" description:"卡接入号(模糊查询)"`
-	BatchNo       string `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
-	PackageID     *uint  `json:"package_id" query:"package_id" description:"套餐ID"`
-	IsDistributed *bool  `json:"is_distributed" query:"is_distributed" description:"是否已分销 (true:已分销, false:未分销)"`
-	IsReplaced    *bool  `json:"is_replaced" query:"is_replaced" description:"是否有换卡记录 (true:有换卡记录, false:无换卡记录)"`
-	ICCIDStart    string `json:"iccid_start" query:"iccid_start" validate:"omitempty,max=20" maxLength:"20" description:"ICCID起始号"`
-	ICCIDEnd      string `json:"iccid_end" query:"iccid_end" validate:"omitempty,max=20" maxLength:"20" description:"ICCID结束号"`
+	Page               int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize           int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	Status             *int   `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	CarrierID          *uint  `json:"carrier_id" query:"carrier_id" description:"运营商ID"`
+	ShopID             *uint  `json:"shop_id" query:"shop_id" description:"分销商ID"`
+	SeriesAllocationID *uint  `json:"series_allocation_id" query:"series_allocation_id" description:"套餐系列分配ID"`
+	ICCID              string `json:"iccid" query:"iccid" validate:"omitempty,max=20" maxLength:"20" description:"ICCID(模糊查询)"`
+	MSISDN             string `json:"msisdn" query:"msisdn" validate:"omitempty,max=20" maxLength:"20" description:"卡接入号(模糊查询)"`
+	BatchNo            string `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
+	PackageID          *uint  `json:"package_id" query:"package_id" description:"套餐ID"`
+	IsDistributed      *bool  `json:"is_distributed" query:"is_distributed" description:"是否已分销 (true:已分销, false:未分销)"`
+	IsReplaced         *bool  `json:"is_replaced" query:"is_replaced" description:"是否有换卡记录 (true:有换卡记录, false:无换卡记录)"`
+	ICCIDStart         string `json:"iccid_start" query:"iccid_start" validate:"omitempty,max=20" maxLength:"20" description:"ICCID起始号"`
+	ICCIDEnd           string `json:"iccid_end" query:"iccid_end" validate:"omitempty,max=20" maxLength:"20" description:"ICCID结束号"`
 }
 
 type StandaloneIotCardResponse struct {
-	ID               uint       `json:"id" description:"卡ID"`
-	ICCID            string     `json:"iccid" description:"ICCID"`
-	CardType         string     `json:"card_type" description:"卡类型"`
-	CardCategory     string     `json:"card_category" description:"卡业务类型 (normal:普通卡, industry:行业卡)"`
-	CarrierID        uint       `json:"carrier_id" description:"运营商ID"`
-	CarrierType      string     `json:"carrier_type,omitempty" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
-	CarrierName      string     `json:"carrier_name,omitempty" description:"运营商名称"`
-	IMSI             string     `json:"imsi,omitempty" description:"IMSI"`
-	MSISDN           string     `json:"msisdn,omitempty" description:"卡接入号"`
-	BatchNo          string     `json:"batch_no,omitempty" description:"批次号"`
-	Supplier         string     `json:"supplier,omitempty" description:"供应商"`
-	CostPrice        int64      `json:"cost_price" description:"成本价(分)"`
-	DistributePrice  int64      `json:"distribute_price" description:"分销价(分)"`
-	Status           int        `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
-	ShopID           *uint      `json:"shop_id,omitempty" description:"店铺ID"`
-	ShopName         string     `json:"shop_name,omitempty" description:"店铺名称"`
-	ActivatedAt      *time.Time `json:"activated_at,omitempty" description:"激活时间"`
-	ActivationStatus int        `json:"activation_status" description:"激活状态 (0:未激活, 1:已激活)"`
-	RealNameStatus   int        `json:"real_name_status" description:"实名状态 (0:未实名, 1:已实名)"`
-	NetworkStatus    int        `json:"network_status" description:"网络状态 (0:停机, 1:开机)"`
-	DataUsageMB      int64      `json:"data_usage_mb" description:"累计流量使用(MB)"`
-	CreatedAt        time.Time  `json:"created_at" description:"创建时间"`
-	UpdatedAt        time.Time  `json:"updated_at" description:"更新时间"`
+	ID                  uint       `json:"id" description:"卡ID"`
+	ICCID               string     `json:"iccid" description:"ICCID"`
+	CardType            string     `json:"card_type" description:"卡类型"`
+	CardCategory        string     `json:"card_category" description:"卡业务类型 (normal:普通卡, industry:行业卡)"`
+	CarrierID           uint       `json:"carrier_id" description:"运营商ID"`
+	CarrierType         string     `json:"carrier_type,omitempty" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
+	CarrierName         string     `json:"carrier_name,omitempty" description:"运营商名称"`
+	IMSI                string     `json:"imsi,omitempty" description:"IMSI"`
+	MSISDN              string     `json:"msisdn,omitempty" description:"卡接入号"`
+	BatchNo             string     `json:"batch_no,omitempty" description:"批次号"`
+	Supplier            string     `json:"supplier,omitempty" description:"供应商"`
+	CostPrice           int64      `json:"cost_price" description:"成本价(分)"`
+	DistributePrice     int64      `json:"distribute_price" description:"分销价(分)"`
+	Status              int        `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	ShopID              *uint      `json:"shop_id,omitempty" description:"店铺ID"`
+	ShopName            string     `json:"shop_name,omitempty" description:"店铺名称"`
+	ActivatedAt         *time.Time `json:"activated_at,omitempty" description:"激活时间"`
+	ActivationStatus    int        `json:"activation_status" description:"激活状态 (0:未激活, 1:已激活)"`
+	RealNameStatus      int        `json:"real_name_status" description:"实名状态 (0:未实名, 1:已实名)"`
+	NetworkStatus       int        `json:"network_status" description:"网络状态 (0:停机, 1:开机)"`
+	DataUsageMB         int64      `json:"data_usage_mb" description:"累计流量使用(MB)"`
+	SeriesAllocationID  *uint      `json:"series_allocation_id,omitempty" description:"套餐系列分配ID"`
+	FirstCommissionPaid bool       `json:"first_commission_paid" description:"一次性佣金是否已发放"`
+	AccumulatedRecharge int64      `json:"accumulated_recharge" description:"累计充值金额(分)"`
+	CreatedAt           time.Time  `json:"created_at" description:"创建时间"`
+	UpdatedAt           time.Time  `json:"updated_at" description:"更新时间"`
 }
 
 type ListStandaloneIotCardResponse struct {
@@ -126,3 +130,22 @@ type GetIotCardByICCIDRequest struct {
 type IotCardDetailResponse struct {
 	StandaloneIotCardResponse
 }
+
+// BatchSetCardSeriesBindngRequest 批量设置卡的套餐系列绑定请求
+type BatchSetCardSeriesBindngRequest struct {
+	ICCIDs             []string `json:"iccids" validate:"required,min=1,max=500,dive,required" required:"true" minItems:"1" maxItems:"500" description:"ICCID列表"`
+	SeriesAllocationID uint     `json:"series_allocation_id" validate:"required,min=0" required:"true" minimum:"0" description:"套餐系列分配ID（0表示清除关联）"`
+}
+
+// CardSeriesBindngFailedItem 卡系列绑定失败项
+type CardSeriesBindngFailedItem struct {
+	ICCID  string `json:"iccid" description:"ICCID"`
+	Reason string `json:"reason" description:"失败原因"`
+}
+
+// BatchSetCardSeriesBindngResponse 批量设置卡的套餐系列绑定响应
+type BatchSetCardSeriesBindngResponse struct {
+	SuccessCount int                          `json:"success_count" description:"成功数量"`
+	FailCount    int                          `json:"fail_count" description:"失败数量"`
+	FailedItems  []CardSeriesBindngFailedItem `json:"failed_items" description:"失败详情列表"`
+}

internal/model/iot_card.go

@@ -35,6 +35,9 @@ type IotCard struct {
 	LastDataCheckAt     *time.Time `gorm:"column:last_data_check_at;comment:最后一次流量检查时间" json:"last_data_check_at"`
 	LastRealNameCheckAt *time.Time `gorm:"column:last_real_name_check_at;comment:最后一次实名检查时间" json:"last_real_name_check_at"`
 	LastSyncTime        *time.Time `gorm:"column:last_sync_time;comment:最后一次与Gateway同步时间" json:"last_sync_time"`
+	SeriesAllocationID  *uint      `gorm:"column:series_allocation_id;index;comment:套餐系列分配ID(关联ShopSeriesAllocation)" json:"series_allocation_id,omitempty"`
+	FirstCommissionPaid bool       `gorm:"column:first_commission_paid;type:boolean;default:false;comment:一次性佣金是否已发放" json:"first_commission_paid"`
+	AccumulatedRecharge int64      `gorm:"column:accumulated_recharge;type:bigint;default:0;comment:累计充值金额(分)" json:"accumulated_recharge"`
 }
 
 // TableName 指定表名