chore: 归档 OpenSpec 变更 refactor-series-binding-to-series-id

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-02-02 12:21:00 +08:00
parent b47f7b4f46
commit 76b539e867
6 changed files with 762 additions and 2 deletions
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/.openspec.yaml
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-02
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/design.md
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/design.md
@@ -0,0 +1,432 @@
+# Design: refactor-series-binding-to-series-id
+
+## Context
+
+### 当前架构问题
+
+当前系统中，IoT卡和设备通过 `series_allocation_id` 字段绑定到 `ShopSeriesAllocation` 表，形成以下关系链：
+
+```
+IotCard/Device
+  └── series_allocation_id → ShopSeriesAllocation
+                                  ├── shop_id → Shop
+                                  ├── series_id → PackageSeries
+                                  └── 返佣配置（BaseCommissionValue, OneTimeCommission...）
+```
+
+这导致了三层职责混乱：
+1. **资源属性层**（卡/设备的可购买范围）依赖于**权限配置层**（ShopSeriesAllocation）
+2. 每次需要验证套餐是否可购买时，必须先查询 `ShopSeriesAllocation` 获取 `series_id`
+3. 返佣计算和权限验证被强制耦合在一个查询中
+
+### 现有数据结构
+
+**Model 定义**：
+```go
+type IotCard struct {
+    SeriesAllocationID *uint `gorm:"column:series_allocation_id"` // 指向 ShopSeriesAllocation
+}
+
+type Device struct {
+    SeriesAllocationID *uint `gorm:"column:series_allocation_id"`
+}
+
+type ShopSeriesAllocation struct {
+    ShopID              uint   // 被分配的店铺ID
+    SeriesID            uint   // 套餐系列ID
+    BaseCommissionValue int64  // 返佣配置
+    // ... 其他返佣相关字段
+}
+```
+
+**当前业务流程**：
+```
+购买套餐验证：
+card.SeriesAllocationID → ShopSeriesAllocation.SeriesID → 验证 Package.SeriesID
+                        ↓
+                    同时获取返佣配置
+```
+
+### 技术约束
+
+- PostgreSQL 14+，支持字段重命名（`ALTER TABLE ... RENAME COLUMN`）
+- GORM v1.25.x，支持动态字段名
+- 项目禁止外键约束，关联关系在代码层显式维护
+- 开发阶段，无生产数据，可直接修改数据库结构
+
+## Goals / Non-Goals
+
+**Goals:**
+- 将卡/设备的系列绑定从"权限分配"改为"套餐系列"，实现职责分离
+- 优化查询性能，减少购买验证时的数据库查询次数
+- 保持返佣计算逻辑正确性，按需查询 `ShopSeriesAllocation`
+- 统一所有相关代码的字段命名（Model、DTO、Store、Service、测试）
+- 更新 API 文档，明确参数变更
+
+**Non-Goals:**
+- 不修改 `ShopSeriesAllocation` 表结构和返佣计算逻辑
+- 不改变 API 端点路径（仅改变请求/响应字段名）
+- 不引入数据迁移工具或版本控制（直接重命名字段）
+- 不考虑向后兼容性（开发阶段可 BREAKING CHANGE）
+
+## Decisions
+
+### 决策 1：直接重命名数据库字段
+
+**选择**：使用 PostgreSQL 的 `ALTER TABLE ... RENAME COLUMN` 直接重命名字段
+
+**理由**：
+- 开发阶段，无生产数据，无需考虑数据迁移
+- 字段含义保持一致（都是指向某个 ID），只是关联表变了
+- 索引会自动重命名，无需额外处理
+- 简单高效，避免引入复杂的数据迁移逻辑
+
+**替代方案**：
+- ❌ 新增 `series_id` 字段，保留 `series_allocation_id`：增加字段冗余，需要复杂的迁移逻辑
+- ❌ 删除旧字段再创建新字段：会丢失索引，需要手动重建
+
+**实施**：
+```sql
+-- migrations/000XXX_refactor_series_binding_to_series_id.up.sql
+ALTER TABLE tb_iot_card RENAME COLUMN series_allocation_id TO series_id;
+ALTER TABLE tb_device RENAME COLUMN series_allocation_id TO series_id;
+
+COMMENT ON COLUMN tb_iot_card.series_id IS '套餐系列ID(关联PackageSeries)';
+COMMENT ON COLUMN tb_device.series_id IS '套餐系列ID(关联PackageSeries)';
+```
+
+### 决策 2：新增 GetByShopAndSeries 查询方法
+
+**选择**：在 `ShopSeriesAllocationStore` 中新增 `GetByShopAndSeries(shopID, seriesID)` 方法
+
+**理由**：
+- 返佣查询的核心需求是：根据店铺和系列查询分配配置
+- 当前的 `GetByID(allocationID)` 方法不再适用（卡/设备不再存储 `allocation_id`）
+- 该查询有复合索引支持：`(shop_id, series_id)`（需要验证或添加）
+
+**替代方案**：
+- ❌ 在 Service 层手动拼接查询条件：违反分层原则，Store 层应封装所有数据访问逻辑
+- ❌ 继续使用 `GetByID`，在 Service 层先查询获取 ID：增加查询次数，性能倒退
+
+**实施**：
+```go
+// internal/store/postgres/shop_series_allocation_store.go
+func (s *ShopSeriesAllocationStore) GetByShopAndSeries(
+    ctx context.Context,
+    shopID uint,
+    seriesID uint,
+) (*model.ShopSeriesAllocation, error) {
+    var allocation model.ShopSeriesAllocation
+    err := s.db.WithContext(ctx).
+        Where("shop_id = ? AND series_id = ? AND status = ?", shopID, seriesID, 1).
+        First(&allocation).Error
+    if err != nil {
+        return nil, err
+    }
+    return &allocation, nil
+}
+```
+
+**索引验证**：需要检查 `tb_shop_series_allocation` 表是否有 `(shop_id, series_id)` 复合索引，如无则添加：
+```sql
+CREATE INDEX IF NOT EXISTS idx_shop_series_allocation_shop_series 
+    ON tb_shop_series_allocation(shop_id, series_id);
+```
+
+### 决策 3：Service 层逻辑重构策略
+
+**选择**：将验证和返佣查询分离，按需查询
+
+**当前逻辑（错误）**：
+```go
+// ValidateCardPurchase
+allocation := s.seriesAllocationStore.GetByID(card.SeriesAllocationID) // 必须查询
+seriesID := allocation.SeriesID // 获取 series_id
+packages := s.validatePackages(packageIDs, seriesID)
+// allocation 同时用于返佣计算
+```
+
+**重构后逻辑（正确）**：
+```go
+// ValidateCardPurchase
+seriesID := *card.SeriesID // 直接使用，无需查询
+packages := s.validatePackages(packageIDs, seriesID)
+
+// 按需查询返佣配置（仅当需要时）
+var allocation *model.ShopSeriesAllocation
+if card.ShopID != nil && *card.ShopID > 0 {
+    allocation, _ = s.seriesAllocationStore.GetByShopAndSeries(*card.ShopID, seriesID)
+}
+```
+
+**优势**：
+- 购买验证减少一次数据库查询（直接使用 `card.series_id`）
+- 个人客户场景下（`shop_id = NULL`）无需查询 `ShopSeriesAllocation`
+- 返佣查询失败不影响购买流程（`allocation = nil` 表示无返佣）
+
+### 决策 4：权限验证逻辑优化
+
+**选择**：在 `BatchSetSeriesBinding` 中，先验证系列是否存在，再验证操作者权限
+
+**当前逻辑（冗余）**：
+```go
+// 验证分配是否存在
+allocation := s.seriesAllocationStore.GetByID(req.SeriesAllocationID)
+
+// 验证卡是否属于分配的店铺
+if card.ShopID != allocation.ShopID {
+    return errors.New("卡不属于该店铺")
+}
+```
+
+**重构后逻辑**：
+```go
+// 1. 验证系列是否存在
+series := s.packageSeriesStore.GetByID(req.SeriesID)
+if series.Status != 1 {
+    return errors.New("套餐系列已禁用")
+}
+
+// 2. 验证操作者权限（仅代理）
+if operatorShopID != nil {
+    allocation, err := s.seriesAllocationStore.GetByShopAndSeries(*operatorShopID, req.SeriesID)
+    if err != nil || allocation.Status != 1 {
+        return errors.New("您没有权限分配该套餐系列")
+    }
+}
+
+// 3. 验证卡的权限（基于 card.shop_id）
+if operatorShopID != nil && !s.hasPermission(*operatorShopID, card.ShopID) {
+    return errors.New("无权操作该卡")
+}
+```
+
+**优势**：
+- 职责清晰：系列验证、权限验证、资源验证分离
+- 错误提示更准确：区分"系列不存在"、"无权限"、"无权操作该卡"
+- 平台用户（`operatorShopID = nil`）跳过权限检查，直接操作
+
+### 决策 5：测试数据准备策略
+
+**选择**：测试时先创建 `PackageSeries`，再创建 `ShopSeriesAllocation`，最后设置卡/设备的 `series_id`
+
+**数据准备顺序**：
+```go
+// 1. 创建套餐系列
+series := &model.PackageSeries{SeriesCode: "TEST-SERIES", SeriesName: "测试系列", Status: 1}
+db.Create(series)
+
+// 2. 创建店铺系列分配
+allocation := &model.ShopSeriesAllocation{
+    ShopID: shopA.ID,
+    SeriesID: series.ID,
+    BaseCommissionValue: 200, // 20%
+    Status: 1,
+}
+db.Create(allocation)
+
+// 3. 卡/设备直接绑定系列
+card := &model.IotCard{ICCID: "898600...", SeriesID: &series.ID, ShopID: &shopA.ID}
+db.Create(card)
+```
+
+**验证查询**：
+```go
+// 验证返佣配置查询
+allocation, err := seriesAllocationStore.GetByShopAndSeries(shopA.ID, series.ID)
+assert.NoError(t, err)
+assert.Equal(t, int64(200), allocation.BaseCommissionValue)
+```
+
+## Risks / Trade-offs
+
+### 风险 1：遗漏字段名修改导致运行时错误
+
+**风险**：涉及约 150 处代码需要修改，可能遗漏某些地方，导致运行时 `column not found` 错误
+
+**缓解措施**：
+1. 使用 IDE 全局搜索 `SeriesAllocationID` 和 `series_allocation_id`，逐一检查
+2. 运行所有测试，确保覆盖所有代码路径
+3. 分阶段提交：Model → Store → Service → 测试，每个阶段验证编译通过
+
+**检测方式**：
+```bash
+# 搜索所有可能遗漏的引用
+grep -r "SeriesAllocationID" internal/ --include="*.go"
+grep -r "series_allocation_id" internal/ --include="*.go"
+```
+
+### 风险 2：返佣查询失败导致业务中断
+
+**风险**：`GetByShopAndSeries` 查询失败时（如数据不一致），可能导致订单创建或返佣计算失败
+
+**缓解措施**：
+1. 查询失败时区分 `ErrRecordNotFound` 和其他错误
+   - `ErrRecordNotFound`：视为"无返佣配置"，继续业务流程
+   - 其他错误：返回错误，中断流程
+2. 在关键流程（订单创建、充值）中，返佣计算失败不应阻止主流程
+3. 添加日志记录，方便排查数据不一致问题
+
+**实施**：
+```go
+allocation, err := s.seriesAllocationStore.GetByShopAndSeries(shopID, seriesID)
+if err != nil {
+    if err == gorm.ErrRecordNotFound {
+        // 无返佣配置，个人客户或未分配的店铺
+        return nil, nil // 不计算返佣
+    }
+    return nil, err // 其他错误，中断流程
+}
+```
+
+### 风险 3：性能回退（增加查询次数）
+
+**风险**：虽然购买验证减少了一次查询，但返佣计算仍需查询 `ShopSeriesAllocation`，可能增加总查询次数
+
+**实际影响**：
+- 购买验证：减少 1 次查询（`GetByID(allocation_id)`）
+- 返佣计算：增加 1 次条件查询（`GetByShopAndSeries(shop_id, series_id)`）
+- **净影响**：0 查询增加（只是查询方式变了）
+
+**性能优化**：
+1. 确保 `(shop_id, series_id)` 有复合索引
+2. `GetByShopAndSeries` 添加 `status = 1` 条件，利用索引过滤
+3. 个人客户场景下跳过返佣查询，实际减少查询次数
+
+**索引验证**：
+```sql
+-- 检查索引是否存在
+SELECT indexname, indexdef 
+FROM pg_indexes 
+WHERE tablename = 'tb_shop_series_allocation';
+
+-- 如果不存在，添加复合索引
+CREATE INDEX idx_shop_series_allocation_shop_series 
+    ON tb_shop_series_allocation(shop_id, series_id) 
+    WHERE status = 1;
+```
+
+### Trade-off：API Breaking Change
+
+**Trade-off**：修改 API 请求/响应字段名是 BREAKING CHANGE，需要前端同步修改
+
+**决策**：接受此 trade-off，理由如下：
+1. 开发阶段，前后端可同步修改
+2. 字段名更语义化，降低未来维护成本
+3. 避免技术债务积累，现在修复比上线后修复成本低
+
+**前端修改清单**：
+```typescript
+// 修改前
+interface BatchSetCardSeriesBindingRequest {
+  iccids: string[];
+  series_allocation_id: number; // ❌
+}
+
+// 修改后
+interface BatchSetCardSeriesBindingRequest {
+  iccids: string[];
+  series_id: number; // ✅
+}
+```
+
+## Migration Plan
+
+### 实施步骤
+
+**阶段 1：数据库 & Model（基础设施）**
+1. 创建数据库迁移文件 `000XXX_refactor_series_binding_to_series_id.up.sql`
+2. 修改 `internal/model/iot_card.go` 和 `internal/model/device.go`
+3. 修改所有 DTO 文件（6 个结构体）
+4. **验证**：编译通过，无语法错误
+
+**阶段 2：Store 层（数据访问）**
+5. 更新 `IotCardStore` 和 `DeviceStore` 的查询过滤逻辑
+6. 重命名 `BatchUpdateSeriesAllocation` → `BatchUpdateSeriesID`
+7. 重命名 `ListBySeriesAllocationID` → `ListBySeriesID`
+8. 新增 `ShopSeriesAllocationStore.GetByShopAndSeries()`
+9. 新增或完善 `PackageSeriesStore`（如不存在）
+10. **验证**：Store 层测试通过
+
+**阶段 3：Service 层（核心业务）**
+11. 修改 `iot_card/service.go` 的 `BatchSetSeriesBinding`
+12. 修改 `device/service.go` 的 `BatchSetSeriesBinding`
+13. 修改 `purchase_validation/service.go`（关键）
+14. 修改 `commission_calculation/service.go`（关键）
+15. 修改 `recharge/service.go`
+16. 修改 `order/service.go`
+17. **验证**：Service 层测试通过
+
+**阶段 4：Handler & Routes**
+18. 更新路由描述（API 文档）
+19. **验证**：Handler 层无需修改（使用 DTO）
+
+**阶段 5：测试**
+20. 更新 Store 层测试（约 10 个测试用例）
+21. 更新 Service 层测试（约 50 个测试用例）
+22. 更新集成测试（约 40 个测试用例）
+23. **验证**：运行 `go test ./...`，全部通过
+
+**阶段 6：验证 & 清理**
+24. 运行数据库迁移：`migrate up`
+25. 手动测试 API（Postman/curl）
+26. 检查日志，确认无错误
+27. 更新 API 文档（OpenAPI spec）
+28. 清理临时代码和注释
+
+### Rollback 策略
+
+如果在开发阶段发现问题，可以通过以下方式回滚：
+
+**数据库回滚**：
+```sql
+-- migrations/000XXX_refactor_series_binding_to_series_id.down.sql
+ALTER TABLE tb_iot_card RENAME COLUMN series_id TO series_allocation_id;
+ALTER TABLE tb_device RENAME COLUMN series_id TO series_allocation_id;
+
+COMMENT ON COLUMN tb_iot_card.series_allocation_id IS '套餐系列分配ID(关联ShopSeriesAllocation)';
+COMMENT ON COLUMN tb_device.series_allocation_id IS '套餐系列分配ID(关联ShopSeriesAllocation)';
+```
+
+**代码回滚**：
+- 使用 Git 回滚到重构前的 commit
+- 执行 `migrate down` 回滚数据库
+
+## Open Questions
+
+### Q1: tb_shop_series_allocation 表是否有 (shop_id, series_id) 复合索引？
+
+**需要验证**：
+```sql
+SELECT indexname, indexdef 
+FROM pg_indexes 
+WHERE tablename = 'tb_shop_series_allocation'
+  AND indexdef LIKE '%shop_id%'
+  AND indexdef LIKE '%series_id%';
+```
+
+**如果没有，需要添加**：
+```sql
+CREATE INDEX idx_shop_series_allocation_shop_series 
+    ON tb_shop_series_allocation(shop_id, series_id) 
+    WHERE status = 1;
+```
+
+### Q2: PackageSeriesStore 是否已存在？
+
+**需要确认**：是否已有 `internal/store/postgres/package_series_store.go`
+
+**如果不存在，需要创建**：
+- 实现 `GetByID(ctx, id)` 方法
+- 在 `bootstrap/stores.go` 中注册
+- 在 Service 中注入依赖
+
+### Q3: 是否需要在 commission_calculation 中缓存 allocation 查询结果？
+
+**场景**：同一笔订单多次计算返佣时，可能多次查询同一个 `(shop_id, series_id)` 的 allocation
+
+**考虑**：
+- 如果查询频率高，可以在 Service 层缓存查询结果（使用 map）
+- 如果查询频率低，直接查询即可（有索引支持，性能可接受）
+
+**决策**：暂不缓存，保持代码简洁。如果性能测试发现瓶颈，再优化。
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/proposal.md
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/proposal.md
@@ -0,0 +1,84 @@
+# Proposal: refactor-series-binding-to-series-id
+
+## Why
+
+当前系统中，IoT卡和设备通过 `series_allocation_id`（套餐系列分配ID）字段绑定到 `ShopSeriesAllocation` 表，而不是直接绑定到 `PackageSeries`（套餐系列）。这导致了严重的语义混乱和架构问题：
+
+1. **语义错误**：卡/设备应该表达"只能购买某个系列的套餐"，而不是"绑定到某个权限分配"
+2. **职责耦合**：资源属性（可购买的套餐范围）与权限配置（返佣规则）混在一起
+3. **查询冗余**：每次需要 `series_id` 时都要通过 `allocation` 表查询，增加数据库负担
+4. **配置僵化**：修改店铺的返佣配置时，需要重新绑定所有卡/设备
+
+这是一个设计失误，需要在开发阶段彻底重构。正确的设计应该是：卡/设备直接绑定 `series_id`，权限验证和返佣查询时按需通过 `(shop_id, series_id)` 查询 `ShopSeriesAllocation`。
+
+## What Changes
+
+- **数据库结构**：将 `tb_iot_card` 和 `tb_device` 的 `series_allocation_id` 字段重命名为 `series_id`，直接关联到 `tb_package_series`
+- **Model 层**：修改 `IotCard` 和 `Device` 模型，将 `SeriesAllocationID` 字段改为 `SeriesID`
+- **DTO 层**：更新所有相关 DTO，包括查询请求、响应对象、批量设置请求
+- **Store 层**：
+  - 更新查询过滤条件（`series_allocation_id` → `series_id`）
+  - 重命名批量更新方法（`BatchUpdateSeriesAllocation` → `BatchUpdateSeriesID`）
+  - 重命名列表查询方法（`ListBySeriesAllocationID` → `ListBySeriesID`）
+  - **新增** `ShopSeriesAllocationStore.GetByShopAndSeries(shopID, seriesID)` 方法，用于按需查询返佣配置
+  - **新增** `PackageSeriesStore`（如不存在）及其 `GetByID()` 方法
+- **Service 层**：重构核心业务逻辑
+  - `BatchSetSeriesBinding`：验证 `series_id` 是否存在，检查操作者权限（通过 `GetByShopAndSeries` 查询）
+  - `ValidateCardPurchase` / `ValidateDevicePurchase`：直接使用 `card.series_id` 验证套餐，按需查询返佣配置
+  - `CalculateOrderCommission`：根据 `(shop_id, series_id)` 查询返佣配置，而不是通过 `allocation_id`
+  - `CreateRecharge`：同样改为按需查询返佣配置
+- **API 文档**：更新路由描述，说明参数从 `series_allocation_id` 改为 `series_id`
+- **测试**：更新约 100+ 个测试用例，包括单元测试、集成测试、Store 测试
+
+**关键行为变更**：
+- API `/api/admin/iot-cards/series-binding` 和 `/api/admin/devices/series-binding` 的请求参数从 `series_allocation_id` 改为 `series_id`
+- 卡/设备列表的查询参数和响应字段同步改为 `series_id`
+- 内部逻辑从"通过 allocation 获取 series_id"改为"直接使用 series_id，按需查询 allocation"
+
+## Capabilities
+
+### New Capabilities
+<!-- 无新增能力 -->
+
+### Modified Capabilities
+- `card-series-bindng`: 修改 IoT 卡系列绑定的数据模型和验证逻辑，从绑定"分配ID"改为绑定"系列ID"
+- `device-series-bindng`: 修改设备系列绑定的数据模型和验证逻辑，从绑定"分配ID"改为绑定"系列ID"
+
+## Impact
+
+### 影响范围统计
+- **数据库迁移**：2 个迁移文件（新增重命名迁移，修改旧迁移注释）
+- **Model 层**：2 个文件（`internal/model/iot_card.go`, `internal/model/device.go`）
+- **DTO 层**：2 个文件，6 个结构体（`internal/model/dto/iot_card_dto.go`, `internal/model/dto/device_dto.go`）
+- **Store 层**：3 个文件，新增 2 个查询方法（`iot_card_store.go`, `device_store.go`, `shop_series_allocation_store.go`）
+- **Service 层**：6 个文件的核心逻辑重构
+  - `internal/service/iot_card/service.go`
+  - `internal/service/device/service.go`
+  - `internal/service/purchase_validation/service.go`（关键）
+  - `internal/service/commission_calculation/service.go`（关键）
+  - `internal/service/recharge/service.go`
+  - `internal/service/order/service.go`
+- **Handler/Routes 层**：2 个文件的路由描述更新
+- **测试层**：约 10 个文件，100+ 测试用例更新
+
+### 受影响的 API 端点
+- `PATCH /api/admin/iot-cards/series-binding`：请求参数 `series_allocation_id` → `series_id`
+- `PATCH /api/admin/devices/series-binding`：请求参数 `series_allocation_id` → `series_id`
+- `GET /api/admin/iot-cards/standalone`：查询参数和响应字段 `series_allocation_id` → `series_id`
+- `GET /api/admin/devices`：查询参数和响应字段 `series_allocation_id` → `series_id`
+
+### 向后兼容性
+- **BREAKING CHANGE**：API 请求/响应字段名变更，前端需要同步修改
+- **数据迁移**：字段重命名，不需要数据转换（字段含义保持一致，只是重新指向 `PackageSeries.ID`）
+- **业务影响**：开发阶段，无生产数据，可直接重构
+
+### 依赖和约束
+- 依赖现有的 `tb_package_series` 表和 `tb_shop_series_allocation` 表
+- 依赖现有的 `PackageSeries` 模型
+- 需要创建或完善 `PackageSeriesStore`（如不存在）
+- 测试需要创建完整的测试数据链路：`PackageSeries` → `ShopSeriesAllocation` → `IotCard/Device`
+
+### 性能影响
+- **查询优化**：购买验证时减少一次数据库查询（不再需要先查 `ShopSeriesAllocation` 获取 `series_id`）
+- **返佣查询**：增加一次按条件查询 `ShopSeriesAllocation`（`WHERE shop_id = ? AND series_id = ?`），但有索引支持，性能影响可忽略
+- **整体影响**：轻微性能提升（减少了冗余查询）
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/specs/card-series-bindng/spec.md
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/specs/card-series-bindng/spec.md
@@ -0,0 +1,114 @@
+# Delta Spec: card-series-bindng
+
+## MODIFIED Requirements
+
+### Requirement: 批量设置卡的套餐系列
+
+系统 SHALL 允许代理批量为 IoT 卡设置套餐系列。只能设置平台已启用的套餐系列，且代理必须有该系列的权限。
+
+#### Scenario: 成功批量设置
+- **WHEN** 代理提交多个 ICCID 和一个有效的 series_id
+- **THEN** 系统更新这些卡的 series_id 字段
+
+#### Scenario: 系列不存在
+- **WHEN** 代理尝试设置一个不存在的系列 ID
+- **THEN** 系统返回错误 "套餐系列不存在"
+
+#### Scenario: 系列已禁用
+- **WHEN** 代理尝试设置一个已禁用的套餐系列
+- **THEN** 系统返回错误 "套餐系列已禁用"
+
+#### Scenario: 代理无权限设置该系列
+- **WHEN** 代理尝试设置一个未分配给自己店铺的系列
+- **THEN** 系统返回错误 "您没有权限分配该套餐系列"
+
+#### Scenario: ICCID 不存在
+- **WHEN** 提交的 ICCID 中有不存在的卡
+- **THEN** 系统返回错误，列出不存在的 ICCID
+
+#### Scenario: 卡不属于当前店铺
+- **WHEN** 代理尝试设置不属于自己店铺的卡
+- **THEN** 系统返回错误 "无权操作该卡"
+
+---
+
+### Requirement: 清除卡的套餐系列关联
+
+系统 SHALL 允许代理清除卡的套餐系列关联（将 series_id 设为 0）。
+
+#### Scenario: 清除单卡关联
+- **WHEN** 代理将卡的 series_id 设为 0
+- **THEN** 系统清除该卡的套餐系列关联
+
+#### Scenario: 批量清除关联
+- **WHEN** 代理批量提交 ICCID 列表，series_id 为 0
+- **THEN** 系统清除这些卡的套餐系列关联
+
+---
+
+### Requirement: 查询卡的套餐系列信息
+
+系统 SHALL 在卡详情和列表中返回套餐系列关联信息。
+
+#### Scenario: 卡详情包含系列信息
+- **WHEN** 查询卡详情
+- **THEN** 响应包含 series_id、关联的系列名称、佣金状态
+
+#### Scenario: 卡列表支持按系列筛选
+- **WHEN** 代理按 series_id 筛选卡列表
+- **THEN** 系统只返回关联该系列的卡
+
+---
+
+### Requirement: IotCard 模型字段定义
+
+系统 MUST 在 IotCard 模型中包含以下字段：
+- `series_id`：套餐系列 ID（直接关联到 PackageSeries）
+- `first_commission_paid`：一次性佣金是否已发放（默认 false）
+- `accumulated_recharge`：累计充值金额（默认 0）
+
+#### Scenario: 新卡默认值
+- **WHEN** 创建新的 IoT 卡
+- **THEN** series_id 为空，first_commission_paid 为 false，accumulated_recharge 为 0
+
+#### Scenario: 字段在响应中可见
+- **WHEN** 查询卡信息
+- **THEN** 响应包含这三个字段
+
+---
+
+## ADDED Requirements
+
+### Requirement: 购买验证使用 series_id
+
+系统 MUST 在验证卡购买套餐时，直接使用 `card.series_id` 验证套餐是否属于该系列。
+
+#### Scenario: 卡有系列绑定
+- **WHEN** 卡的 series_id 为 5，用户购买 series_id 为 5 的套餐
+- **THEN** 系统允许购买
+
+#### Scenario: 卡未绑定系列
+- **WHEN** 卡的 series_id 为空，用户尝试购买任何套餐
+- **THEN** 系统返回错误 "该卡未关联套餐系列，无法购买套餐"
+
+#### Scenario: 套餐不属于卡的系列
+- **WHEN** 卡的 series_id 为 5，用户购买 series_id 为 8 的套餐
+- **THEN** 系统返回错误 "套餐不在可购买范围内"
+
+---
+
+### Requirement: 返佣查询使用 (shop_id, series_id)
+
+系统 MUST 在计算返佣时，通过 `(shop_id, series_id)` 查询 `ShopSeriesAllocation` 获取返佣配置。
+
+#### Scenario: 店铺有系列权限
+- **WHEN** 卡的 shop_id 为 10，series_id 为 5，且存在 ShopSeriesAllocation(shop_id=10, series_id=5)
+- **THEN** 系统使用该分配记录的返佣配置计算佣金
+
+#### Scenario: 店铺无系列权限
+- **WHEN** 卡的 shop_id 为 10，series_id 为 5，但不存在对应的 ShopSeriesAllocation
+- **THEN** 系统不计算返佣（个人客户场景或未分配系列）
+
+#### Scenario: 个人客户无返佣
+- **WHEN** 卡的 shop_id 为空（个人客户），series_id 为 5
+- **THEN** 系统不查询 ShopSeriesAllocation，不计算返佣
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/specs/device-series-bindng/spec.md
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/specs/device-series-bindng/spec.md
@@ -0,0 +1,128 @@
+# Delta Spec: device-series-bindng
+
+## MODIFIED Requirements
+
+### Requirement: 批量设置设备的套餐系列
+
+系统 SHALL 允许代理批量为设备设置套餐系列。只能设置平台已启用的套餐系列，且代理必须有该系列的权限。
+
+#### Scenario: 成功批量设置
+- **WHEN** 代理提交多个设备 ID 和一个有效的 series_id
+- **THEN** 系统更新这些设备的 series_id 字段
+
+#### Scenario: 系列不存在
+- **WHEN** 代理尝试设置一个不存在的系列 ID
+- **THEN** 系统返回错误 "套餐系列不存在"
+
+#### Scenario: 系列已禁用
+- **WHEN** 代理尝试设置一个已禁用的套餐系列
+- **THEN** 系统返回错误 "套餐系列已禁用"
+
+#### Scenario: 代理无权限设置该系列
+- **WHEN** 代理尝试设置一个未分配给自己店铺的系列
+- **THEN** 系统返回错误 "您没有权限分配该套餐系列"
+
+#### Scenario: 设备不存在
+- **WHEN** 提交的设备 ID 中有不存在的设备
+- **THEN** 系统返回错误，列出不存在的设备 ID
+
+#### Scenario: 设备不属于当前店铺
+- **WHEN** 代理尝试设置不属于自己店铺的设备
+- **THEN** 系统返回错误 "无权操作该设备"
+
+---
+
+### Requirement: 清除设备的套餐系列关联
+
+系统 SHALL 允许代理清除设备的套餐系列关联（将 series_id 设为 0）。
+
+#### Scenario: 清除单设备关联
+- **WHEN** 代理将设备的 series_id 设为 0
+- **THEN** 系统清除该设备的套餐系列关联
+
+#### Scenario: 批量清除关联
+- **WHEN** 代理批量提交设备 ID 列表，series_id 为 0
+- **THEN** 系统清除这些设备的套餐系列关联
+
+---
+
+### Requirement: 查询设备的套餐系列信息
+
+系统 SHALL 在设备详情和列表中返回套餐系列关联信息。
+
+#### Scenario: 设备详情包含系列信息
+- **WHEN** 查询设备详情
+- **THEN** 响应包含 series_id、关联的系列名称、佣金状态
+
+#### Scenario: 设备列表支持按系列筛选
+- **WHEN** 代理按 series_id 筛选设备列表
+- **THEN** 系统只返回关联该系列的设备
+
+---
+
+### Requirement: Device 模型字段定义
+
+系统 MUST 在 Device 模型中包含以下字段：
+- `series_id`：套餐系列 ID（直接关联到 PackageSeries）
+- `first_commission_paid`：一次性佣金是否已发放（默认 false）
+- `accumulated_recharge`：累计充值金额（默认 0）
+
+#### Scenario: 新设备默认值
+- **WHEN** 创建新设备
+- **THEN** series_id 为空，first_commission_paid 为 false，accumulated_recharge 为 0
+
+#### Scenario: 字段在响应中可见
+- **WHEN** 查询设备信息
+- **THEN** 响应包含这三个字段
+
+---
+
+### Requirement: 设备级套餐购买使用 series_id
+
+设备购买套餐时 MUST 使用 `device.series_id` 确定可购买的套餐系列。
+
+#### Scenario: 设备有系列关联
+- **WHEN** 设备的 series_id 为 5，用户购买 series_id 为 5 的套餐
+- **THEN** 系统允许购买
+
+#### Scenario: 设备未绑定系列
+- **WHEN** 设备的 series_id 为空
+- **THEN** 该设备无法购买设备级套餐，系统返回错误 "该设备未关联套餐系列，无法购买套餐"
+
+#### Scenario: 套餐不属于设备的系列
+- **WHEN** 设备的 series_id 为 5，用户购买 series_id 为 8 的套餐
+- **THEN** 系统返回错误 "套餐不在可购买范围内"
+
+---
+
+## ADDED Requirements
+
+### Requirement: 购买验证直接使用 series_id
+
+系统 MUST 在验证设备购买套餐时，直接使用 `device.series_id` 验证套餐是否属于该系列，不再依赖设备下卡的 series_id。
+
+#### Scenario: 设备和卡的系列不同
+- **WHEN** 设备的 series_id 为 5，设备下的卡的 series_id 为 8
+- **THEN** 购买设备级套餐时，系统使用设备的 series_id（5），忽略卡的 series_id
+
+#### Scenario: 设备有系列，卡无系列
+- **WHEN** 设备的 series_id 为 5，设备下的卡的 series_id 为空
+- **THEN** 设备仍然可以购买 series_id 为 5 的设备级套餐
+
+---
+
+### Requirement: 返佣查询使用 (shop_id, series_id)
+
+系统 MUST 在计算返佣时，通过 `(shop_id, series_id)` 查询 `ShopSeriesAllocation` 获取返佣配置。
+
+#### Scenario: 店铺有系列权限
+- **WHEN** 设备的 shop_id 为 10，series_id 为 5，且存在 ShopSeriesAllocation(shop_id=10, series_id=5)
+- **THEN** 系统使用该分配记录的返佣配置计算佣金
+
+#### Scenario: 店铺无系列权限
+- **WHEN** 设备的 shop_id 为 10，series_id 为 5，但不存在对应的 ShopSeriesAllocation
+- **THEN** 系统不计算返佣（个人客户场景或未分配系列）
+
+#### Scenario: 个人客户无返佣
+- **WHEN** 设备的 shop_id 为空（个人客户），series_id 为 5
+- **THEN** 系统不查询 ShopSeriesAllocation，不计算返佣
--- a/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/tasks.md
+++ b/openspec/changes/archive/2026-02-02-refactor-series-binding-to-series-id/tasks.md
@@ -0,0 +1,191 @@
+# Tasks: refactor-series-binding-to-series-id
+
+## 1. 数据库迁移
+
+- [x] 1.1 创建数据库迁移文件 `migrations/000XXX_refactor_series_binding_to_series_id.up.sql`，重命名 `tb_iot_card.series_allocation_id` 为 `series_id`，`tb_device.series_allocation_id` 为 `series_id`，更新字段注释
+- [x] 1.2 创建回滚迁移文件 `migrations/000XXX_refactor_series_binding_to_series_id.down.sql`
+- [x] 1.3 验证索引是否存在：检查 `tb_shop_series_allocation` 是否有 `(shop_id, series_id)` 复合索引，如不存在则添加
+- [x] 1.4 执行迁移：运行 `migrate up`，验证字段重命名成功，无错误
+
+## 2. Model 层修改
+
+- [x] 2.1 修改 `internal/model/iot_card.go`：将 `SeriesAllocationID` 字段重命名为 `SeriesID`，更新 gorm 标签和注释
+- [x] 2.2 修改 `internal/model/device.go`：将 `SeriesAllocationID` 字段重命名为 `SeriesID`，更新 gorm 标签和注释
+- [x] 2.3 验证编译：运行 `go build ./internal/model/...`，确认无编译错误
+
+## 3. DTO 层修改
+
+- [x] 3.1 修改 `internal/model/dto/iot_card_dto.go`：更新 `ListStandaloneIotCardRequest` 的查询参数 `SeriesAllocationID` → `SeriesID`
+- [x] 3.2 修改 `internal/model/dto/iot_card_dto.go`：更新 `StandaloneIotCardResponse` 的响应字段 `SeriesAllocationID` → `SeriesID`
+- [x] 3.3 修改 `internal/model/dto/iot_card_dto.go`：更新 `BatchSetCardSeriesBindngRequest` 的请求字段 `SeriesAllocationID` → `SeriesID`，更新 description 为 "套餐系列ID（0表示清除关联）"
+- [x] 3.4 修改 `internal/model/dto/device_dto.go`：更新 `ListDeviceRequest` 的查询参数 `SeriesAllocationID` → `SeriesID`
+- [x] 3.5 修改 `internal/model/dto/device_dto.go`：更新 `DeviceResponse` 的响应字段 `SeriesAllocationID` → `SeriesID`
+- [x] 3.6 修改 `internal/model/dto/device_dto.go`：更新 `BatchSetDeviceSeriesBindngRequest` 的请求字段 `SeriesAllocationID` → `SeriesID`，更新 description 为 "套餐系列ID（0表示清除关联）"
+- [x] 3.7 验证编译：运行 `go build ./internal/model/dto/...`，确认无编译错误
+
+## 4. Store 层修改
+
+- [x] 4.1 修改 `internal/store/postgres/iot_card_store.go`：更新 `ListStandalone` 方法，将过滤条件 `series_allocation_id` 改为 `series_id`
+- [x] 4.2 修改 `internal/store/postgres/iot_card_store.go`：更新 `Count` 方法，将过滤条件 `series_allocation_id` 改为 `series_id`
+- [x] 4.3 修改 `internal/store/postgres/iot_card_store.go`：重命名方法 `BatchUpdateSeriesAllocation` 为 `BatchUpdateSeriesID`，更新 SQL 字段名
+- [x] 4.4 修改 `internal/store/postgres/iot_card_store.go`：重命名方法 `ListBySeriesAllocationID` 为 `ListBySeriesID`，更新 WHERE 条件
+- [x] 4.5 修改 `internal/store/postgres/device_store.go`：更新 `List` 方法，将过滤条件 `series_allocation_id` 改为 `series_id`
+- [x] 4.6 修改 `internal/store/postgres/device_store.go`：重命名方法 `BatchUpdateSeriesAllocation` 为 `BatchUpdateSeriesID`，更新 SQL 字段名
+- [x] 4.7 修改 `internal/store/postgres/device_store.go`：重命名方法 `ListBySeriesAllocationID` 为 `ListBySeriesID`，更新 WHERE 条件
+- [x] 4.8 修改 `internal/store/postgres/shop_series_allocation_store.go`：新增方法 `GetByShopAndSeries(ctx, shopID, seriesID)`，实现根据店铺和系列查询分配配置
+- [x] 4.9 验证或创建 `internal/store/postgres/package_series_store.go`：如不存在则创建，实现 `GetByID(ctx, id)` 方法
+- [x] 4.10 如果创建了新 Store，在 `internal/bootstrap/stores.go` 中注册 `PackageSeriesStore`
+- [x] 4.11 验证编译：运行 `go build ./internal/store/...`，确认无编译错误
+
+## 5. Service 层修改 - iot_card
+
+- [x] 5.1 修改 `internal/service/iot_card/service.go`：更新 `ListStandalone` 方法，将过滤条件 key `series_allocation_id` 改为 `series_id`
+- [x] 5.2 修改 `internal/service/iot_card/service.go`：更新 `buildStandaloneResponse` 方法，将字段 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 5.3 修改 `internal/service/iot_card/service.go`：重构 `BatchSetSeriesBinding` 方法
+- [x] 5.4 在 `internal/service/iot_card/service.go` 的 `Service` 结构体中添加 `packageSeriesStore` 依赖（如果不存在）
+- [x] 5.5 验证编译：运行 `go build ./internal/service/iot_card/...`，确认无编译错误
+- [x] 5.6 运行 `lsp_diagnostics` 检查 `internal/service/iot_card/service.go`，确认无类型错误
+
+## 6. Service 层修改 - device
+
+- [x] 6.1 修改 `internal/service/device/service.go`：更新 `List` 方法，将过滤条件 key `series_allocation_id` 改为 `series_id`
+- [x] 6.2 修改 `internal/service/device/service.go`：更新 `buildDeviceResponse` 方法，将字段 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 6.3 修改 `internal/service/device/service.go`：重构 `BatchSetSeriesBinding` 方法
+- [x] 6.4 在 `internal/service/device/service.go` 的 `Service` 结构体中添加 `packageSeriesStore` 依赖（如果不存在）
+- [x] 6.5 验证编译：运行 `go build ./internal/service/device/...`，确认无编译错误
+- [x] 6.6 运行 `lsp_diagnostics` 检查 `internal/service/device/service.go`，确认无类型错误
+
+## 7. Service 层修改 - purchase_validation（关键）
+
+- [x] 7.1 修改 `internal/service/purchase_validation/service.go`：重构 `ValidateCardPurchase` 方法
+- [x] 7.2 修改 `internal/service/purchase_validation/service.go`：重构 `ValidateDevicePurchase` 方法
+- [x] 7.3 更新 `ValidateCardPurchase` 和 `ValidateDevicePurchase` 的错误消息，从 "套餐系列分配不存在" 改为 "该卡/设备未关联套餐系列"
+- [x] 7.4 验证编译：运行 `go build ./internal/service/purchase_validation/...`，确认无编译错误
+- [x] 7.5 运行 `lsp_diagnostics` 检查 `internal/service/purchase_validation/service.go`，确认无类型错误
+
+## 8. Service 层修改 - commission_calculation（关键）
+
+- [x] 8.1 修改 `internal/service/commission_calculation/service.go`：重构 `CalculateOrderCommission` 方法
+- [x] 8.2 修改 `internal/service/commission_calculation/service.go`：重构 `CalculateDeviceOrderCommission` 方法（同样的逻辑）
+- [x] 8.3 验证编译：运行 `go build ./internal/service/commission_calculation/...`，确认无编译错误
+- [x] 8.4 运行 `lsp_diagnostics` 检查 `internal/service/commission_calculation/service.go`，确认无类型错误
+
+## 9. Service 层修改 - recharge
+
+- [x] 9.1 修改 `internal/service/recharge/service.go`：重构充值相关方法，将获取 `seriesAllocationID` 的逻辑改为直接使用 `seriesID`
+- [x] 9.2 修改 `internal/service/recharge/service.go`：更新返佣查询逻辑，使用 `GetByShopAndSeries(shopID, seriesID)` 而不是 `GetByID(allocationID)`
+- [x] 9.3 验证编译：运行 `go build ./internal/service/recharge/...`，确认无编译错误
+- [x] 9.4 运行 `lsp_diagnostics` 检查 `internal/service/recharge/service.go`，确认无类型错误
+
+## 10. Service 层修改 - order
+
+- [x] 10.1 检查 `internal/service/order/service.go` 中是否有直接使用 `SeriesAllocationID` 的地方，如有则更新为 `SeriesID`
+- [x] 10.2 验证编译：运行 `go build ./internal/service/order/...`，确认无编译错误
+- [x] 10.3 运行 `lsp_diagnostics` 检查 `internal/service/order/service.go`，确认无类型错误
+
+## 11. Bootstrap 依赖注入
+
+- [x] 11.1 如果创建了 `PackageSeriesStore`，在 `internal/bootstrap/stores.go` 中初始化并添加到 `Stores` 结构体
+- [x] 11.2 在 `internal/bootstrap/services.go` 中，为 `iot_card.Service` 和 `device.Service` 注入 `packageSeriesStore` 依赖
+- [x] 11.3 验证编译：运行 `go build ./internal/bootstrap/...`，确认无编译错误
+
+## 12. Handler & Routes 层
+
+- [x] 12.1 修改 `internal/routes/iot_card.go`：更新 `/series-binding` 路由的 Description，说明参数从 `series_allocation_id` 改为 `series_id`
+- [x] 12.2 修改 `internal/routes/device.go`：更新 `/series-binding` 路由的 Description，说明参数从 `series_allocation_id` 改为 `series_id`
+- [x] 12.3 验证 Handler 层代码：`internal/handler/admin/iot_card.go` 和 `device.go` 无需修改（使用 DTO）
+- [x] 12.4 验证编译：运行 `go build ./internal/routes/... ./internal/handler/...`，确认无编译错误
+
+## 13. Store 层测试更新
+
+- [x] 13.1 修改 `internal/store/postgres/iot_card_store_test.go`：更新所有测试用例，将 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 13.2 修改 `internal/store/postgres/iot_card_store_test.go`：重命名测试函数 `TestIotCardStore_ListBySeriesAllocationID` 为 `TestIotCardStore_ListBySeriesID`
+- [x] 13.3 修改 `internal/store/postgres/iot_card_store_test.go`：更新过滤条件测试，将 `series_allocation_id` 改为 `series_id`
+- [x] 13.4 修改 `internal/store/postgres/device_store_test.go`：更新所有测试用例，将 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 13.5 修改 `internal/store/postgres/device_store_test.go`：重命名测试函数 `TestDeviceStore_ListBySeriesAllocationID` 为 `TestDeviceStore_ListBySeriesID`
+- [x] 13.6 新增测试：在 `shop_series_allocation_store_test.go` 中添加 `TestShopSeriesAllocationStore_GetByShopAndSeries` 测试
+- [x] 13.7 运行 Store 层测试：`source .env.local && go test -v ./internal/store/postgres/...`，确认全部通过
+
+## 14. Service 层测试更新 - iot_card
+
+- [x] 14.1 修改 `internal/service/iot_card/service_test.go`：更新 `TestIotCardService_BatchSetSeriesBinding` 测试
+- [x] 14.2 更新测试数据准备顺序：先 `PackageSeries`，再 `ShopSeriesAllocation`，最后 `IotCard`
+- [x] 14.3 运行 Service 层测试：`source .env.local && go test -v ./internal/service/iot_card/...`，确认全部通过
+
+## 15. Service 层测试更新 - device
+
+- [x] 15.1 修改 `internal/service/device/service_test.go`：更新 `TestDeviceService_BatchSetSeriesBinding` 测试
+- [x] 15.2 更新测试数据准备顺序：先 `PackageSeries`，再 `ShopSeriesAllocation`，最后 `Device`
+- [x] 15.3 运行 Service 层测试：`source .env.local && go test -v ./internal/service/device/...`，确认全部通过
+
+## 16. Service 层测试更新 - purchase_validation
+
+- [x] 16.1 修改 `internal/service/purchase_validation/service_test.go`：更新所有测试用例
+- [x] 16.2 运行 Service 层测试：`source .env.local && go test -v ./internal/service/purchase_validation/...`，确认全部通过
+
+## 17. Service 层测试更新 - commission_calculation
+
+- [x] 17.1 修改 `internal/service/commission_calculation/service_test.go`：更新所有测试用例
+- [x] 17.2 运行 Service 层测试：`source .env.local && go test -v ./internal/service/commission_calculation/...`，确认全部通过
+
+## 18. Service 层测试更新 - recharge & order
+
+- [x] 18.1 修改 `internal/service/recharge/service_test.go`：更新测试用例，将 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 18.2 修改 `internal/service/order/service_test.go`：更新测试用例，将 `SeriesAllocationID` 改为 `SeriesID`
+- [x] 18.3 运行 Service 层测试：`source .env.local && go test -v ./internal/service/recharge/... ./internal/service/order/...`，确认全部通过
+
+## 19. 集成测试更新 - iot_card
+
+- [x] 19.1 修改 `tests/integration/iot_card_test.go`：更新 `TestIotCard_BatchSetSeriesBinding` 测试
+- [x] 19.2 更新所有子测试用例的 JSON 请求体（约 10 个）
+- [x] 19.3 运行集成测试：`source .env.local && cd tests/integration && go test -v -run "TestIotCard_BatchSetSeriesBinding"`，确认全部通过
+
+## 20. 集成测试更新 - device
+
+- [x] 20.1 修改 `tests/integration/device_test.go`：更新 `TestDevice_BatchSetSeriesBinding` 测试
+- [x] 20.2 更新所有子测试用例的 JSON 请求体（约 10 个）
+- [x] 20.3 运行集成测试：`source .env.local && cd tests/integration && go test -v -run "TestDevice_BatchSetSeriesBinding"`，确认全部通过
+
+## 21. 单元测试更新 - commission_calculation
+
+- [x] 21.1 修改 `tests/unit/commission_calculation_service_test.go`：更新所有测试用例
+- [x] 21.2 运行单元测试：`source .env.local && go test -v ./tests/unit/...`，确认全部通过
+
+## 22. 全量测试验证
+
+- [x] 22.1 运行所有测试：`source .env.local && go test -v ./...`，确认全部通过，无遗漏
+- [x] 22.2 运行编译检查：`go build ./...`，确认无编译错误
+- [x] 22.3 使用 grep 搜索遗漏：`grep -r "SeriesAllocationID" internal/ --include="*.go"`，确认无遗漏
+- [x] 22.4 使用 grep 搜索遗漏：`grep -r "series_allocation_id" internal/ --include="*.go"`，确认无遗漏（仅数据库注释除外）
+
+## 23. API 手动测试
+
+- [ ] 23.1 启动本地服务：`go run cmd/api/main.go`
+- [ ] 23.2 测试 IoT 卡系列绑定 API：`PATCH /api/admin/iot-cards/series-binding`，使用 Postman 或 curl 发送请求，验证参数 `series_id` 生效
+- [ ] 23.3 测试设备系列绑定 API：`PATCH /api/admin/devices/series-binding`，使用 Postman 或 curl 发送请求，验证参数 `series_id` 生效
+- [ ] 23.4 测试卡列表查询：`GET /api/admin/iot-cards/standalone?series_id=1`，验证过滤生效
+- [ ] 23.5 测试设备列表查询：`GET /api/admin/devices?series_id=1`，验证过滤生效
+- [ ] 23.6 检查日志：确认无错误日志，SQL 查询使用 `series_id` 而不是 `series_allocation_id`
+
+## 24. API 文档更新
+
+- [x] 24.1 更新 OpenAPI 文档注释：确保路由描述中明确说明参数从 `series_allocation_id` 改为 `series_id`
+- [x] 24.2 重新生成 API 文档：运行 `go run cmd/gendocs/main.go`，生成最新的 OpenAPI spec
+- [x] 24.3 验证生成的文档：检查 `docs/admin-openapi.yaml` 中 `/iot-cards/series-binding` 和 `/devices/series-binding` 的参数定义
+- [x] 24.4 如有前端文档，更新前端接口文档，说明 BREAKING CHANGE
+
+## 25. 清理和最终验证
+
+- [x] 25.1 删除所有临时代码和注释
+- [x] 25.2 运行 `gofmt -w .` 格式化所有代码
+- [x] 25.3 运行 `go mod tidy` 清理依赖
+- [x] 25.4 再次运行全量测试：`source .env.local && go test -v ./...`，确认全部通过
+- [x] 25.5 使用 `git diff` 检查所有改动，确认无遗漏，无多余修改
+- [x] 25.6 更新 CHANGELOG（如有），记录 BREAKING CHANGE
+
+## 26. 提交和归档
+
+- [x] 26.1 提交代码：创建 Git commit，使用中文 commit message："重构: 将卡/设备的套餐系列绑定从分配ID改为系列ID"
+- [ ] 26.2 运行 OpenSpec 归档：`openspec archive refactor-series-binding-to-series-id`
+- [ ] 26.3 验证归档成功：检查 `openspec/changes/archive/` 目录，确认变更已归档
+- [ ] 26.4 清理工作目录：删除 `openspec/changes/refactor-series-binding-to-series-id/`（已归档）