refactor: 一次性佣金配置从套餐级别提升到系列级别

主要变更:
- 新增 tb_shop_series_allocation 表，存储系列级别的一次性佣金配置
- ShopPackageAllocation 移除 one_time_commission_amount 字段
- PackageSeries 新增 enable_one_time_commission 字段控制是否启用一次性佣金
- 新增 /api/admin/shop-series-allocations CRUD 接口
- 佣金计算逻辑改为从 ShopSeriesAllocation 获取一次性佣金金额
- 删除废弃的 ShopSeriesOneTimeCommissionTier 模型
- OpenAPI Tag '系列分配' 和 '单套餐分配' 合并为 '套餐分配'

迁移脚本:
- 000042: 重构佣金套餐模型
- 000043: 简化佣金分配
- 000044: 一次性佣金分配重构
- 000045: PackageSeries 添加 enable_one_time_commission 字段

测试:
- 新增验收测试 (shop_series_allocation, commission_calculation)
- 新增流程测试 (one_time_commission_chain)
- 删除过时的单元测试（已被验收测试覆盖）

openspec/changes/archive/2026-02-04-refactor-commission-package-model/tasks.md

@@ -0,0 +1,125 @@
+# 套餐与佣金模型重构任务列表
+
+> **注意**：当前处于开发阶段，无需数据迁移，直接修改表结构和代码。
+
+## 1. 数据库迁移
+
+- [x] 1.1 创建迁移文件：Package 表移除 `price`/`data_type`/`data_amount_mb` 字段，新增 `enable_virtual_data` 字段
+- [x] 1.2 创建迁移文件：ShopPackageAllocation 表新增 `one_time_commission_amount` 字段
+- [x] 1.3 创建迁移文件：IoTCard 表新增 `accumulated_recharge_by_series` 和 `first_recharge_triggered_by_series` 字段（jsonb）
+- [x] 1.4 创建迁移文件：Device 表新增 `accumulated_recharge_by_series` 和 `first_recharge_triggered_by_series` 字段（jsonb）
+- [x] 1.5 创建迁移文件：PackageSeries 表新增 `one_time_commission_config` 字段（jsonb）
+- [x] 1.6 创建迁移文件：ShopSeriesOneTimeCommissionTier 表新增 `stat_scope` 字段
+- [x] 1.7 创建迁移文件：ShopSeriesAllocation 表移除一次性佣金配置字段，新增 `one_time_commission_amount` 字段
+- [x] 1.8 执行迁移并验证
+
+## 2. Model 层更新
+
+- [x] 2.1 更新 Package 模型：移除 `Price`/`DataType`/`DataAmountMB` 字段，新增 `EnableVirtualData` 字段
+- [x] 2.2 更新 ShopPackageAllocation 模型：新增 `OneTimeCommissionAmount` 字段
+- [x] 2.3 更新 IoTCard 模型：新增 `AccumulatedRechargeBySeriesJSON` 和 `FirstRechargeTriggeredBySeriesJSON` 字段
+- [x] 2.4 更新 Device 模型：新增 `AccumulatedRechargeBySeriesJSON` 和 `FirstRechargeTriggeredBySeriesJSON` 字段
+- [x] 2.5 更新 PackageSeries 模型：新增 `OneTimeCommissionConfigJSON` 字段
+- [x] 2.6 创建 OneTimeCommissionConfig 结构体（含 Enable, TriggerType, Threshold, CommissionType, ValidityType 等字段）
+- [x] 2.7 更新 ShopSeriesOneTimeCommissionTier 模型：新增 `StatScope` 字段
+- [x] 2.8 更新 ShopSeriesAllocation 模型：移除一次性佣金配置字段，新增 `OneTimeCommissionAmount` 字段
+- [x] 2.9 为 IoTCard/Device 添加累计充值和首充状态的 getter/setter 辅助方法
+- [x] 2.10 运行 `lsp_diagnostics` 验证 Model 层无编译错误
+
+## 3. DTO 层更新
+
+- [x] 3.1 更新 CreatePackageRequest：移除 `price`/`data_type`/`data_amount_mb`，新增 `enable_virtual_data`
+- [x] 3.2 更新 UpdatePackageRequest：同上调整字段
+- [x] 3.3 更新 PackageResponse：移除废弃字段，新增 `enable_virtual_data`、`one_time_commission_amount`
+- [x] 3.4 更新 CreateShopPackageAllocationRequest：新增 `one_time_commission_amount` 字段
+- [x] 3.5 更新 ShopPackageAllocationResponse：新增 `one_time_commission_amount` 字段
+- [x] 3.6 更新 CreatePackageSeriesRequest：新增 `one_time_commission_config` 嵌套结构
+- [x] 3.7 更新 PackageSeriesResponse：返回一次性佣金规则配置
+- [x] 3.8 简化 CreateShopSeriesAllocationRequest：移除完整一次性佣金配置字段，改为 `one_time_commission_amount`
+- [x] 3.9 简化 ShopSeriesAllocationResponse：移除完整一次性佣金配置字段
+- [x] 3.10 运行 `lsp_diagnostics` 验证 DTO 层无编译错误
+
+## 4. Store 层更新
+
+- [x] 4.1 更新 PackageStore：适配新字段的 CRUD 操作（GORM Save 自动处理）
+- [x] 4.2 更新 ShopPackageAllocationStore：支持 `one_time_commission_amount` 字段（GORM Save 自动处理）
+- [x] 4.3 更新 PackageSeriesStore：支持 `one_time_commission_config` JSON 字段的读写（GORM Save 自动处理）
+- [x] 4.4 更新 ShopSeriesAllocationStore：移除完整一次性佣金配置字段的处理（Model 层已移除字段）
+- [x] 4.5 新增 IoTCardStore 方法：UpdateRechargeTrackingFields
+- [x] 4.6 新增 IoTCardStore 方法：（通过 Model 层 getter/setter 辅助方法实现）
+- [x] 4.7 新增 IoTCardStore 方法：（通过 Model 层 getter/setter 辅助方法实现）
+- [x] 4.8 新增 DeviceStore 方法：UpdateRechargeTrackingFields
+- [x] 4.9 运行 `lsp_diagnostics` 验证 Store 层无编译错误
+
+## 5. Service 层更新 - 套餐管理
+
+- [x] 5.1 更新 PackageService.Create：校验虚流量配置（启用时必填且 ≤ 真流量）
+- [x] 5.2 更新 PackageService.Update：同上校验逻辑
+- [x] 5.3 更新 PackageService.List：根据用户类型返回不同视角的成本价和一次性佣金金额
+- [x] 5.4 新增辅助方法：获取代理的套餐分配关系并填充视角数据
+- [x] 5.5 编写 PackageService 单元测试：虚流量配置校验场景
+- [ ] 5.6 编写 PackageService 单元测试：代理视角套餐列表场景（需要完整测试环境）
+
+## 6. Service 层更新 - 套餐分配
+
+- [x] 6.1 更新 ShopPackageAllocationService.Create：支持设置一次性佣金金额
+- [x] 6.2 新增校验逻辑：一次性佣金金额 ≤ 上级能拿到的金额
+- [x] 6.3 新增校验逻辑：一次性佣金金额 ≥ 0
+- [x] 6.4 更新 ShopPackageAllocationService.Update：支持修改一次性佣金金额
+- [x] 6.5 编写 ShopPackageAllocationService 单元测试：一次性佣金金额校验场景
+
+## 7. Service 层更新 - 系列管理与分配
+
+- [x] 7.1 更新 PackageSeriesService：支持一次性佣金规则配置的 CRUD
+- [x] 7.2 简化 ShopSeriesAllocationService.Create：移除完整一次性佣金配置的处理
+- [x] 7.3 简化 ShopSeriesAllocationService.Update：同上
+- [x] 7.4 更新验证逻辑：从套餐系列获取一次性佣金规则进行校验
+- [ ] 7.5 编写单元测试
+
+## 8. Service 层更新 - 佣金计算
+
+- [x] 8.1 重构一次性佣金触发逻辑：支持按系列追踪首充和累计充值状态
+- [x] 8.2 实现链式分配计算逻辑：沿代理链向上计算各级代理分得的佣金
+- [x] 8.3 更新累计充值逻辑：只有充值操作累计，直接购买不累计
+- [x] 8.4 更新首充判断逻辑：从 `single_recharge` 改为 `first_recharge`
+- [x] 8.5 实现一次性佣金时效检查：过期规则不触发返佣
+- [x] 8.6 更新梯度佣金计算：支持 `stat_scope` 配置
+- [x] 8.7 编写佣金计算 Service 单元测试：链式分配场景
+- [x] 8.8 编写佣金计算 Service 单元测试：首充/累计充值场景
+- [x] 8.9 编写佣金计算 Service 单元测试：梯度升级场景（已实现时效检查测试）
+
+## 9. Service 层更新 - 强充检查
+
+- [x] 9.1 更新首充强充金额计算：max(首充要求, 套餐售价)
+- [x] 9.2 新增累计充值强充金额计算：支持固定/动态两种模式
+- [x] 9.3 更新强充流程：支持累计充值的累计逻辑
+- [ ] 9.4 编写强充检查 Service 单元测试
+
+## 10. Handler 层更新
+
+- [x] 10.1 更新 PackageHandler：适配新 DTO 结构
+- [x] 10.2 更新 PackageSeriesHandler：支持一次性佣金规则配置
+- [x] 10.3 更新 ShopPackageAllocationHandler：支持一次性佣金金额
+- [x] 10.4 更新 ShopSeriesAllocationHandler：简化请求/响应结构
+- [x] 10.5 更新文档生成器 cmd/api/docs.go 和 cmd/gendocs/main.go
+- [x] 10.6 运行 `lsp_diagnostics` 验证 Handler 层无编译错误
+
+## 11. 集成测试
+
+- [ ] 11.1 编写套餐 CRUD 集成测试：验证虚流量配置
+- [ ] 11.2 编写套餐分配集成测试：验证一次性佣金金额
+- [ ] 11.3 编写系列分配集成测试：验证简化后的配置
+- [ ] 11.4 编写代理视角套餐列表集成测试
+- [ ] 11.5 编写一次性佣金触发集成测试：首充场景
+- [ ] 11.6 编写一次性佣金触发集成测试：累计充值场景
+- [ ] 11.7 编写链式佣金分配集成测试
+- [x] 11.8 运行全部测试确保通过
+
+## 12. 验收
+
+- [x] 12.1 运行完整测试套件，确保全部通过
+- [x] 12.2 运行 `go build` 确保编译通过
+- [ ] 12.3 本地环境功能验证：套餐创建/修改流程
+- [ ] 12.4 本地环境功能验证：套餐分配流程
+- [ ] 12.5 本地环境功能验证：一次性佣金触发流程
+- [ ] 12.6 更新 OpenAPI 文档确认变更已反映