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>

openspec/changes/add-one-time-commission/design.md

@@ -4,7 +4,24 @@ Phase 4 完成了订单和支付流程，现在需要实现佣金计算。当终
 
 **佣金来源**：
 1. **成本价差收入**：每笔订单必触发，售价 - 成本价 = 代理收入
-2. **一次性佣金**：满足触发条件时发放一次，金额从梯度配置获取
+2. **一次性佣金**：满足触发条件时发放一次，每张卡/设备仅发放一次
+3. **周期性梯度返佣**：已在 refactor-shop-package-allocation 中实现，本期不涉及
+
+**一次性佣金的两种类型**：
+- **固定一次性佣金**：充值达标后发放固定金额或比例（如首充≥100元返20元）
+- **梯度一次性佣金**：根据系列销售业绩返不同佣金（如系列销售额≥5000元时首充返15元）
+
+**核心业务逻辑**：
+- **触发条件**：基于单张卡/设备的充值情况（首充或累计充值达标）
+- **返佣金额**：基于该系列分配的累计销售业绩（销量或销售额）选择梯度档位
+- **发放次数**：每张卡/设备仅发放一次（通过 first_commission_paid 标记）
+- **统计来源**：使用 ShopSeriesCommissionStats 查询该系列分配的销售业绩
+
+**与重构的关系**：
+- refactor-shop-package-allocation 已实现 ShopSeriesCommissionStats 统计表（按 allocation_id 统计销售业绩）
+- 一次性佣金复用该统计表，通过 allocation_id 查询该系列分配的累计销量/销售额
+- 需要在 ShopSeriesAllocation 表新增一次性佣金配置字段
+- 需要新增 ShopSeriesOneTimeCommissionTier 表存储梯度配置
 
 **当前 CommissionRecord 模型过于复杂**（包含冻结/解冻字段），需要简化。
 
@@ -127,50 +144,369 @@ func CalculateCostDiffCommission(order *Order) []CommissionRecord {
 }
 ```
 
-### 4. 一次性佣金触发
+### 4. 一次性佣金数据结构
 
-**决策**：两种触发类型，每张卡/设备只触发一次
+**决策**：在 ShopSeriesAllocation 新增配置字段 + 新增梯度表
+
+#### 4.1 ShopSeriesAllocation 新增字段
 
 ```go
-// 触发类型 A：一次性充值 ≥ 阈值
-func CheckOneTimeRecharge(order *Order, threshold int64) bool {
-    return order.TotalAmount >= threshold
-}
-
-// 触发类型 B：累计充值 ≥ 阈值
-func CheckAccumulatedRecharge(card *IotCard, threshold int64) bool {
-    return card.AccumulatedRecharge >= threshold
-}
-
-// 检查并发放一次性佣金
-func TriggerOneTimeCommission(order *Order, card *IotCard) {
-    if card.FirstCommissionPaid {
-        return // 已发放过
-    }
+type ShopSeriesAllocation struct {
+    // ... 现有字段（base_commission, enable_tier_commission 等）
     
-    // 获取配置的触发条件和金额
-    tier := GetCommissionTier(card.SeriesAllocationID)
+    // 🆕 一次性佣金配置
+    EnableOneTimeCommission     bool   `gorm:"column:enable_one_time_commission;default:false;comment:是否启用一次性佣金"`
+    OneTimeCommissionType       string `gorm:"column:one_time_commission_type;type:varchar(20);comment:类型:fixed-固定 tiered-梯度"`
+    OneTimeCommissionTrigger    string `gorm:"column:one_time_commission_trigger;type:varchar(30);comment:触发条件:single_recharge-单次充值 accumulated_recharge-累计充值"`
+    OneTimeCommissionThreshold  int64  `gorm:"column:one_time_commission_threshold;type:bigint;comment:最低阈值(分)"`
     
-    // 检查触发条件
-    triggered := false
-    switch tier.TriggerType {
-    case "one_time_recharge":
-        triggered = CheckOneTimeRecharge(order, tier.ThresholdValue)
-    case "accumulated_recharge":
-        triggered = CheckAccumulatedRecharge(card, tier.ThresholdValue)
-    }
-    
-    if triggered {
-        // 发放佣金
-        CreateCommissionRecord(...)
-        // 标记已发放
-        card.FirstCommissionPaid = true
-        UpdateCard(card)
-    }
+    // 固定一次性佣金配置（type="fixed" 时使用）
+    OneTimeCommissionMode       string `gorm:"column:one_time_commission_mode;type:varchar(20);comment:模式:fixed-固定金额 percent-百分比"`
+    OneTimeCommissionValue      int64  `gorm:"column:one_time_commission_value;type:bigint;comment:佣金金额(分)或比例(千分比)"`
 }
 ```
 
-### 5. 钱包入账
+#### 4.2 新增 ShopSeriesOneTimeCommissionTier 表
+
+```go
+// 梯度一次性佣金配置
+type ShopSeriesOneTimeCommissionTier struct {
+    gorm.Model
+    BaseModel
+    AllocationID        uint   `gorm:"column:allocation_id;not null;index;comment:系列分配ID"`
+    
+    // 梯度判断配置（基于系列销售业绩）
+    TierType            string `gorm:"column:tier_type;type:varchar(20);not null;comment:梯度类型:sales_count-销量 sales_amount-销售额"`
+    ThresholdValue      int64  `gorm:"column:threshold_value;type:bigint;not null;comment:梯度阈值(销量或销售额分)"`
+    
+    // 返佣配置
+    CommissionMode      string `gorm:"column:commission_mode;type:varchar(20);not null;comment:返佣模式:fixed-固定金额 percent-百分比"`
+    CommissionValue     int64  `gorm:"column:commission_value;type:bigint;not null;comment:返佣值(分或千分比)"`
+    
+    Status              int    `gorm:"column:status;type:int;default:1;comment:状态:1-启用 2-停用"`
+}
+
+// TableName 指定表名
+func (ShopSeriesOneTimeCommissionTier) TableName() string {
+    return "tb_shop_series_one_time_commission_tier"
+}
+```
+
+**关键说明**：
+- `TierType`: 梯度判断类型，与 ShopSeriesCommissionTier 的 tier_type 一致（sales_count 或 sales_amount）
+- `ThresholdValue`: 系列销售业绩的阈值（如系列累计销售额≥5000元）
+- 梯度判断使用 ShopSeriesCommissionStats 表中的统计数据（按 allocation_id 查询）
+
+### 5. 一次性佣金触发逻辑
+
+**决策**：两种触发类型 × 两种佣金类型，每张卡/设备只触发一次
+
+#### 5.1 触发条件判断
+
+```go
+// 触发条件 A：单次充值 ≥ 阈值
+func CheckSingleRecharge(order *Order, threshold int64) (bool, int64) {
+    triggered := order.TotalAmount >= threshold
+    return triggered, order.TotalAmount
+}
+
+// 触发条件 B：累计充值 ≥ 阈值
+func CheckAccumulatedRecharge(card *IotCard, order *Order, threshold int64) (bool, int64) {
+    // 先累加当前订单金额
+    newAccumulated := card.AccumulatedRecharge + order.TotalAmount
+    triggered := newAccumulated >= threshold
+    return triggered, newAccumulated
+}
+```
+
+#### 5.2 佣金金额计算
+
+```go
+// 检查并发放一次性佣金（单卡购买场景）
+func TriggerOneTimeCommissionForCard(order *Order, card *IotCard) error {
+    // 1. 检查是否已发放
+    if card.FirstCommissionPaid {
+        return nil
+    }
+    
+    // 2. 获取配置
+    allocation := GetAllocation(card.SeriesAllocationID)
+    if !allocation.EnableOneTimeCommission {
+        return nil
+    }
+    
+    // 3. 检查充值触发条件
+    var rechargeAmount int64
+    switch allocation.OneTimeCommissionTrigger {
+    case "single_recharge":
+        rechargeAmount = order.TotalAmount
+    case "accumulated_recharge":
+        rechargeAmount = card.AccumulatedRecharge + order.TotalAmount
+    }
+    
+    if rechargeAmount < allocation.OneTimeCommissionThreshold {
+        return nil // 充值金额未达标
+    }
+    
+    // 4. 计算佣金金额
+    commissionAmount := calculateOneTimeCommission(allocation, order.TotalAmount)
+    
+    if commissionAmount <= 0 {
+        return nil
+    }
+    
+    // 5. 创建佣金记录
+    record := &CommissionRecord{
+        ShopID:           card.OwnerShopID,
+        OrderID:          order.ID,
+        IotCardID:        card.ID,
+        CommissionSource: "one_time",
+        Amount:           commissionAmount,
+    }
+    CreateCommissionRecord(record)
+    CreditCommission(record)
+    
+    // 6. 标记已发放并更新累计充值
+    card.FirstCommissionPaid = true
+    if allocation.OneTimeCommissionTrigger == "accumulated_recharge" {
+        card.AccumulatedRecharge = rechargeAmount
+    }
+    UpdateCard(card)
+    
+    return nil
+}
+
+// 检查并发放一次性佣金（设备购买场景）
+func TriggerOneTimeCommissionForDevice(order *Order, device *Device) error {
+    // 1. 检查是否已发放
+    if device.FirstCommissionPaid {
+        return nil
+    }
+    
+    // 2. 获取配置
+    allocation := GetAllocation(device.SeriesAllocationID)
+    if !allocation.EnableOneTimeCommission {
+        return nil
+    }
+    
+    // 3. 检查充值触发条件
+    var rechargeAmount int64
+    switch allocation.OneTimeCommissionTrigger {
+    case "single_recharge":
+        rechargeAmount = order.TotalAmount
+    case "accumulated_recharge":
+        rechargeAmount = device.AccumulatedRecharge + order.TotalAmount
+    }
+    
+    if rechargeAmount < allocation.OneTimeCommissionThreshold {
+        return nil
+    }
+    
+    // 4. 计算佣金金额
+    commissionAmount := calculateOneTimeCommission(allocation, order.TotalAmount)
+    
+    if commissionAmount <= 0 {
+        return nil
+    }
+    
+    // 5. 创建佣金记录（注意：设备级购买只发放一次，不按卡数倍增）
+    record := &CommissionRecord{
+        ShopID:           device.OwnerShopID,
+        OrderID:          order.ID,
+        DeviceID:         device.ID,
+        CommissionSource: "one_time",
+        Amount:           commissionAmount,
+    }
+    CreateCommissionRecord(record)
+    CreditCommission(record)
+    
+    // 6. 标记已发放
+    device.FirstCommissionPaid = true
+    if allocation.OneTimeCommissionTrigger == "accumulated_recharge" {
+        device.AccumulatedRecharge = rechargeAmount
+    }
+    UpdateDevice(device)
+    
+    return nil
+}
+
+// 计算一次性佣金金额（固定或梯度）
+func calculateOneTimeCommission(allocation *ShopSeriesAllocation, orderAmount int64) int64 {
+    switch allocation.OneTimeCommissionType {
+    case "fixed":
+        // 固定一次性佣金
+        return calculateFixedCommission(
+            allocation.OneTimeCommissionMode,
+            allocation.OneTimeCommissionValue,
+            orderAmount,
+        )
+        
+    case "tiered":
+        // 梯度一次性佣金 - 基于系列销售业绩选择档位
+        return calculateTieredCommission(allocation.ID, orderAmount)
+    }
+    
+    return 0
+}
+
+// 计算固定佣金金额
+func calculateFixedCommission(mode string, value int64, orderAmount int64) int64 {
+    if mode == "fixed" {
+        return value // 固定金额
+    } else if mode == "percent" {
+        return orderAmount * value / 1000 // 按充值金额的百分比
+    }
+    return 0
+}
+
+// 计算梯度佣金金额（基于系列销售业绩）
+func calculateTieredCommission(allocationID uint, orderAmount int64) int64 {
+    // 1. 获取梯度配置
+    tiers := GetOneTimeCommissionTiers(allocationID)
+    if len(tiers) == 0 {
+        return 0
+    }
+    
+    // 2. 查询该系列分配的销售业绩统计
+    stats, _ := commissionStatsService.GetCurrentStats(ctx, allocationID, "all_time")
+    if stats == nil {
+        return 0
+    }
+    
+    // 3. 找到最高匹配档位
+    var matchedTier *ShopSeriesOneTimeCommissionTier
+    for i := range tiers {
+        // 获取销售业绩值
+        var salesValue int64
+        if tiers[i].TierType == "sales_count" {
+            salesValue = stats.TotalSalesCount
+        } else { // sales_amount
+            salesValue = stats.TotalSalesAmount
+        }
+        
+        // 检查是否达到梯度阈值
+        if salesValue >= tiers[i].ThresholdValue {
+            if matchedTier == nil || tiers[i].ThresholdValue > matchedTier.ThresholdValue {
+                matchedTier = &tiers[i]
+            }
+        }
+    }
+    
+    if matchedTier == nil {
+        return 0
+    }
+    
+    // 4. 计算佣金金额
+    if matchedTier.CommissionMode == "fixed" {
+        return matchedTier.CommissionValue
+    } else if matchedTier.CommissionMode == "percent" {
+        return orderAmount * matchedTier.CommissionValue / 1000
+    }
+    
+    return 0
+}
+```
+
+**关键说明**：
+1. **触发条件**：基于单张卡/设备的充值金额（首充或累计充值）
+2. **梯度判断**：基于该系列分配的销售业绩（从 ShopSeriesCommissionStats 查询）
+3. **设备场景**：设备购买时只发放一次佣金，不按卡数倍增
+4. **统计来源**：使用 `allocationID` 查询该系列分配的累计销量/销售额
+
+#### 5.3 配置示例
+
+**示例 1：固定一次性佣金（首充触发）**
+```json
+{
+  "enable_one_time_commission": true,
+  "one_time_commission_type": "fixed",
+  "one_time_commission_trigger": "single_recharge",
+  "one_time_commission_threshold": 10000,  // 首充≥100元触发
+  "one_time_commission_mode": "fixed",
+  "one_time_commission_value": 2000        // 返20元
+}
+```
+
+**业务效果**：
+- 用户首次充值≥100元时，代理获得20元一次性佣金
+- 该卡/设备后续再充值不再触发
+
+---
+
+**示例 2：梯度一次性佣金（基于销售金额 + 累计充值触发）**
+```json
+{
+  "enable_one_time_commission": true,
+  "one_time_commission_type": "tiered",
+  "one_time_commission_trigger": "accumulated_recharge",
+  "one_time_commission_threshold": 10000,  // 累计充值≥100元才触发
+  "tiers": [
+    {
+      "tier_type": "sales_amount",
+      "threshold": 200000,      // 系列累计销售额≥2000元
+      "mode": "fixed",
+      "value": 1000             // 返10元
+    },
+    {
+      "tier_type": "sales_amount",
+      "threshold": 400000,      // 系列累计销售额≥4000元
+      "mode": "fixed",
+      "value": 1500             // 返15元
+    },
+    {
+      "tier_type": "sales_amount",
+      "threshold": 1000000,     // 系列累计销售额≥10000元
+      "mode": "percent",
+      "value": 100              // 返10%（按充值金额）
+    }
+  ]
+}
+```
+
+**业务效果**：
+- 当该系列分配的累计销售额≥4000元时
+- 用户累计充值≥100元触发一次性佣金
+- 代理获得15元（匹配到第二档梯度）
+- 如果系列销售额后续达到10000元，新用户首充≥100元时，代理获得充值金额的10%
+
+---
+
+**示例 3：梯度一次性佣金（基于销售数量 + 首充触发）**
+```json
+{
+  "enable_one_time_commission": true,
+  "one_time_commission_type": "tiered",
+  "one_time_commission_trigger": "single_recharge",
+  "one_time_commission_threshold": 10000,  // 首充≥100元触发
+  "tiers": [
+    {
+      "tier_type": "sales_count",
+      "threshold": 20,          // 系列累计销量≥20个
+      "mode": "fixed",
+      "value": 1000             // 返10元
+    },
+    {
+      "tier_type": "sales_count",
+      "threshold": 40,          // 系列累计销量≥40个
+      "mode": "fixed",
+      "value": 1500             // 返15元
+    },
+    {
+      "tier_type": "sales_count",
+      "threshold": 120,         // 系列累计销量≥120个
+      "mode": "percent",
+      "value": 200              // 返20%
+    }
+  ]
+}
+```
+
+**业务效果**：
+- 当该系列分配的累计销量≥40个时
+- 用户首充≥100元触发一次性佣金
+- 代理获得15元（匹配到第二档梯度）
+
+### 6. 钱包入账
 
 **决策**：直接入账，无冻结期
 
@@ -198,7 +534,7 @@ func CreditCommission(record *CommissionRecord) error {
 }
 ```
 
-### 6. API 设计
+### 7. API 设计
 
 ```
 # 佣金记录查询
@@ -239,14 +575,18 @@ GET /api/admin/commission-stats/daily          每日佣金统计
 
 ## Open Questions
 
-1. **梯度佣金何时统计？**
-   - 当前设计：本期只做配置，不做实际统计
-   - 待确认：是否需要定时任务统计并发放梯度奖励？
+1. **梯度一次性佣金的档位排序规则？**
+   - 当前设计：选择最高匹配档位（达标档位中阈值最高的）
+   - 待确认：是否正确？是否需要支持阶梯式累加？
 
-2. **累计充值是否包含当前订单？**
-   - 当前设计：先更新累计充值，再检查触发条件
-   - 待确认：是否正确？
+2. **设备级购买如何处理？**
+   - 当前设计：设备购买时使用 Device.SeriesAllocationID 和 Device.FirstCommissionPaid
+   - 待确认：设备下多张卡时，一次性佣金只发一次（按设备），还是按卡数倍增？
 
-3. **一次性佣金发放给谁？**
-   - 当前设计：发放给卡/设备的直接归属店铺
-   - 待确认：是否需要多级分佣？
+3. **累计充值的统计周期？**
+   - 当前设计：永久累计（从卡开始使用至今）
+   - 待确认：是否需要支持按自然年/月重置累计金额？
+
+4. **一次性佣金是否支持多级分佣？**
+   - 当前设计：只发放给卡/设备的直接归属店铺
+   - 待确认：是否需要上级代理也获得一次性佣金？如何分配比例？