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. **一次性佣金是否支持多级分佣？**
+   - 当前设计：只发放给卡/设备的直接归属店铺
+   - 待确认：是否需要上级代理也获得一次性佣金？如何分配比例？

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

@@ -1,99 +1,144 @@
-## 1. CommissionRecord 模型简化
+## 1. ShopSeriesAllocation 模型更新（一次性佣金配置）
 
-- [ ] 1.1 修改 `internal/model/commission.go`，简化 CommissionRecord 结构
-- [ ] 1.2 删除冻结相关字段（unfrozen_at 等）
-- [ ] 1.3 删除 rule_id、agent_id 字段
-- [ ] 1.4 新增 commission_source 字段（varchar: cost_diff, one_time, tier_bonus）
-- [ ] 1.5 新增 iot_card_id、device_id 字段
-- [ ] 1.6 新增 remark 字段
+- [ ] 1.1 修改 `internal/model/shop_series_allocation.go`，新增一次性佣金配置字段
+- [ ] 1.2 新增 enable_one_time_commission 字段（bool，是否启用）
+- [ ] 1.3 新增 one_time_commission_type 字段（varchar: fixed-固定, tiered-梯度）
+- [ ] 1.4 新增 one_time_commission_trigger 字段（varchar: single_recharge-首充, accumulated_recharge-累计充值）
+- [ ] 1.5 新增 one_time_commission_threshold 字段（bigint，触发阈值分）
+- [ ] 1.6 新增 one_time_commission_mode 字段（varchar: fixed-固定金额, percent-百分比）
+- [ ] 1.7 新增 one_time_commission_value 字段（bigint，返佣值分或千分比）
 
-## 2. 数据库迁移
+## 2. 新增 ShopSeriesOneTimeCommissionTier 模型
 
-- [ ] 2.1 创建迁移文件，修改 tb_commission_record 表结构
-- [ ] 2.2 删除废弃字段
-- [ ] 2.3 添加新字段
-- [ ] 2.4 添加索引（shop_id, order_id, commission_source, iot_card_id, device_id）
-- [ ] 2.5 本地执行迁移验证
+- [ ] 2.1 创建 `internal/model/shop_series_one_time_commission_tier.go`
+- [ ] 2.2 定义 ShopSeriesOneTimeCommissionTier 模型（allocation_id, tier_type, threshold_value, commission_mode, commission_value, status）
+- [ ] 2.3 实现 TableName() 方法返回 "tb_shop_series_one_time_commission_tier"
+- [ ] 2.4 定义梯度类型常量（与 ShopSeriesCommissionTier 保持一致）
 
-## 3. DTO 更新
+## 3. CommissionRecord 模型简化
 
-- [ ] 3.1 更新 `internal/model/dto/commission.go`，调整 CommissionRecordResponse
-- [ ] 3.2 定义 CommissionRecordListRequest（shop_id, commission_source, start_time, end_time, status）
-- [ ] 3.3 定义 CommissionStatsResponse（total_amount, cost_diff_amount, one_time_amount, tier_bonus_amount）
-- [ ] 3.4 定义 DailyCommissionStatsResponse
+- [ ] 3.1 修改 `internal/model/commission.go`，简化 CommissionRecord 结构
+- [ ] 3.2 删除冻结相关字段（unfrozen_at 等）
+- [ ] 3.3 删除 rule_id、agent_id 字段
+- [ ] 3.4 新增 commission_source 字段（varchar: cost_diff, one_time, tier_bonus）
+- [ ] 3.5 新增 iot_card_id、device_id 字段
+- [ ] 3.6 新增 remark 字段
 
-## 4. CommissionRecord Store 更新
+## 4. 数据库迁移
 
-- [ ] 4.1 更新 `internal/store/postgres/commission_record_store.go`，适配新模型
-- [ ] 4.2 更新 Create 方法
-- [ ] 4.3 更新 List 方法支持新筛选条件
-- [ ] 4.4 实现 GetStats 方法（统计总收入和各来源占比）
-- [ ] 4.5 实现 GetDailyStats 方法（每日统计）
+- [ ] 4.1 创建迁移文件，为 tb_shop_series_allocation 添加一次性佣金字段
+- [ ] 4.2 创建 tb_shop_series_one_time_commission_tier 表
+- [ ] 4.3 添加索引（allocation_id, tier_type, threshold_value）
+- [ ] 4.4 修改 tb_commission_record 表结构
+- [ ] 4.5 删除冻结相关字段
+- [ ] 4.6 添加新字段（commission_source, iot_card_id, device_id, remark）
+- [ ] 4.7 添加索引（shop_id, order_id, commission_source, iot_card_id, device_id）
+- [ ] 4.8 本地执行迁移验证
 
-## 5. 佣金计算 Service
+## 5. DTO 更新
 
-- [ ] 5.1 创建 `internal/service/commission_calculation/service.go`
-- [ ] 5.2 实现 CalculateCommission 主方法（协调整体计算流程）
-- [ ] 5.3 实现 CalculateCostDiffCommission 方法（遍历代理层级计算成本价差）
-- [ ] 5.4 实现 CheckAndTriggerOneTimeCommission 方法（检查一次性佣金触发条件）
-- [ ] 5.5 实现 CreditCommission 方法（佣金入账到钱包）
-- [ ] 5.6 实现 UpdateAccumulatedRecharge 方法（更新累计充值金额）
+- [ ] 5.1 更新 `internal/model/dto/shop_series_allocation.go`，新增一次性佣金配置 DTO
+- [ ] 5.2 定义 OneTimeCommissionConfig（type, trigger, threshold, mode, value）
+- [ ] 5.3 定义 OneTimeCommissionTierEntry（tier_type, threshold, mode, value）
+- [ ] 5.4 更新 CreateShopSeriesAllocationRequest，支持一次性佣金配置
+- [ ] 5.5 更新 ShopSeriesAllocationResponse，包含一次性佣金配置信息
+- [ ] 5.6 更新 `internal/model/dto/commission.go`，调整 CommissionRecordResponse
+- [ ] 5.7 定义 CommissionRecordListRequest（shop_id, commission_source, start_time, end_time, status）
+- [ ] 5.8 定义 CommissionStatsResponse（total_amount, cost_diff_amount, one_time_amount, tier_bonus_amount）
+- [ ] 5.9 定义 DailyCommissionStatsResponse
 
-## 6. 异步任务
+## 6. ShopSeriesOneTimeCommissionTier Store 创建
 
-- [ ] 6.1 创建 `internal/task/commission_calculation.go`，定义佣金计算任务类型
-- [ ] 6.2 实现任务处理函数 HandleCommissionCalculation
-- [ ] 6.3 在 OrderService.WalletPay 中添加任务发送逻辑
-- [ ] 6.4 在支付回调处理中添加任务发送逻辑
-- [ ] 6.5 在 Worker 中注册任务处理器
+- [ ] 6.1 创建 `internal/store/postgres/shop_series_one_time_commission_tier_store.go`
+- [ ] 6.2 实现 Create 方法
+- [ ] 6.3 实现 BatchCreate 方法（批量创建梯度档位）
+- [ ] 6.4 实现 ListByAllocationID 方法（查询某个分配的所有梯度）
+- [ ] 6.5 实现 DeleteByAllocationID 方法（删除某个分配的所有梯度）
+- [ ] 6.6 实现 Update 方法
 
-## 7. 佣金查询 Service
+## 7. CommissionRecord Store 更新
 
-- [ ] 7.1 更新 `internal/service/my_commission/service.go`，适配新模型
-- [ ] 7.2 实现 List 方法
-- [ ] 7.3 实现 Get 方法
-- [ ] 7.4 实现 GetStats 方法
-- [ ] 7.5 实现 GetDailyStats 方法
+- [ ] 7.1 更新 `internal/store/postgres/commission_record_store.go`，适配新模型
+- [ ] 7.2 更新 Create 方法
+- [ ] 7.3 更新 List 方法支持新筛选条件
+- [ ] 7.4 实现 GetStats 方法（统计总收入和各来源占比）
+- [ ] 7.5 实现 GetDailyStats 方法（每日统计）
 
-## 8. Handler 更新
+## 8. 佣金计算 Service
 
-- [ ] 8.1 更新 `internal/handler/admin/my_commission.go`，适配新接口
-- [ ] 8.2 实现 List 接口
-- [ ] 8.3 实现 Get 接口
-- [ ] 8.4 实现 GetStats 接口
-- [ ] 8.5 实现 GetDailyStats 接口
+- [ ] 8.1 创建 `internal/service/commission_calculation/service.go`
+- [ ] 8.2 实现 CalculateCommission 主方法（协调整体计算流程）
+- [ ] 8.3 实现 CalculateCostDiffCommission 方法（遍历代理层级计算成本价差）
+- [ ] 8.4 实现 TriggerOneTimeCommissionForCard 方法（单卡购买场景）
+- [ ] 8.5 实现 TriggerOneTimeCommissionForDevice 方法（设备购买场景）
+- [ ] 8.6 实现 calculateOneTimeCommission 辅助方法（固定或梯度佣金计算）
+- [ ] 8.7 实现 calculateFixedCommission 方法（固定佣金计算）
+- [ ] 8.8 实现 calculateTieredCommission 方法（梯度佣金计算，查询 ShopSeriesCommissionStats）
+- [ ] 8.9 实现 CreditCommission 方法（佣金入账到钱包）
 
-## 9. Bootstrap 注册
+## 9. 异步任务
 
-- [ ] 9.1 在 services.go 中注册 CommissionCalculationService
-- [ ] 9.2 确认 MyCommissionService 注册正确
+- [ ] 9.1 创建 `internal/task/commission_calculation.go`，定义佣金计算任务类型
+- [ ] 9.2 实现任务处理函数 HandleCommissionCalculation
+- [ ] 9.3 在 OrderService.WalletPay 中添加任务发送逻辑
+- [ ] 9.4 在支付回调处理中添加任务发送逻辑
+- [ ] 9.5 在 Worker 中注册任务处理器
 
-## 10. 路由更新
+## 10. 佣金查询 Service
 
-- [ ] 10.1 确认 `/api/admin/my-commission/records` 路由
-- [ ] 10.2 添加 `/api/admin/my-commission/stats` 路由
-- [ ] 10.3 添加 `/api/admin/my-commission/daily-stats` 路由
+- [ ] 10.1 更新 `internal/service/my_commission/service.go`，适配新模型
+- [ ] 10.2 实现 List 方法
+- [ ] 10.3 实现 Get 方法
+- [ ] 10.4 实现 GetStats 方法
+- [ ] 10.5 实现 GetDailyStats 方法
 
-## 11. 文档生成器更新
+## 11. Handler 更新
 
-- [ ] 11.1 更新 docs.go 和 gendocs/main.go
-- [ ] 11.2 执行文档生成验证
+- [ ] 11.1 更新 `internal/handler/admin/my_commission.go`，适配新接口
+- [ ] 11.2 实现 List 接口
+- [ ] 11.3 实现 Get 接口
+- [ ] 11.4 实现 GetStats 接口
+- [ ] 11.5 实现 GetDailyStats 接口
 
-## 12. 测试
+## 12. Bootstrap 注册
 
-- [ ] 12.1 CommissionRecordStore 单元测试
-- [ ] 12.2 CommissionCalculationService 单元测试（覆盖成本价差计算）
-- [ ] 12.3 一次性佣金触发逻辑测试（覆盖各种触发条件）
-- [ ] 12.4 佣金入账事务测试
-- [ ] 12.5 异步任务测试
-- [ ] 12.6 佣金统计 API 集成测试
-- [ ] 12.7 执行 `go test ./...` 确认通过
+- [ ] 12.1 在 stores.go 中注册 ShopSeriesOneTimeCommissionTierStore
+- [ ] 12.2 在 services.go 中注册 CommissionCalculationService
+- [ ] 12.3 确认 MyCommissionService 注册正确
 
-## 13. 最终验证
+## 13. 路由更新
 
-- [ ] 13.1 执行 `go build ./...` 确认编译通过
-- [ ] 13.2 启动服务，创建订单并支付
-- [ ] 13.3 验证佣金记录正确创建
-- [ ] 13.4 验证钱包余额正确增加
-- [ ] 13.5 验证一次性佣金触发逻辑
-- [ ] 13.6 验证佣金统计数据正确
+- [ ] 13.1 确认 `/api/admin/my-commission/records` 路由
+- [ ] 13.2 添加 `/api/admin/my-commission/stats` 路由
+- [ ] 13.3 添加 `/api/admin/my-commission/daily-stats` 路由
+
+## 14. 文档生成器更新
+
+- [ ] 14.1 更新 docs.go 和 gendocs/main.go
+- [ ] 14.2 执行文档生成验证
+
+## 15. 测试
+
+- [ ] 15.1 ShopSeriesOneTimeCommissionTierStore 单元测试
+- [ ] 15.2 CommissionRecordStore 单元测试
+- [ ] 15.3 CommissionCalculationService 单元测试（覆盖成本价差计算）
+- [ ] 15.4 固定一次性佣金触发测试（单卡和设备场景）
+- [ ] 15.5 梯度一次性佣金触发测试（基于销售业绩选择档位）
+- [ ] 15.6 首充和累计充值触发条件测试
+- [ ] 15.7 佣金入账事务测试
+- [ ] 15.8 异步任务测试
+- [ ] 15.9 佣金统计 API 集成测试
+- [ ] 15.10 执行 `go test ./...` 确认通过
+
+## 16. 最终验证
+
+- [ ] 16.1 执行 `go build ./...` 确认编译通过
+- [ ] 16.2 启动服务，配置固定一次性佣金并测试
+- [ ] 16.3 配置梯度一次性佣金并测试
+- [ ] 16.4 验证单卡购买场景的一次性佣金
+- [ ] 16.5 验证设备购买场景的一次性佣金（不按卡数倍增）
+- [ ] 16.6 验证梯度匹配逻辑（基于销售业绩统计）
+- [ ] 16.7 验证首充和累计充值触发条件
+- [ ] 16.8 验证 first_commission_paid 标记（防止重复发放）
+- [ ] 16.9 验证钱包余额正确增加
+- [ ] 16.10 验证佣金统计数据正确