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

套餐与佣金模型重构任务列表

注意：当前处于开发阶段，无需数据迁移，直接修改表结构和代码。

1. 数据库迁移

• 1.1 创建迁移文件：Package 表移除 price/data_type/data_amount_mb 字段，新增 enable_virtual_data 字段
• 1.2 创建迁移文件：ShopPackageAllocation 表新增 one_time_commission_amount 字段
• 1.3 创建迁移文件：IoTCard 表新增 accumulated_recharge_by_series 和 first_recharge_triggered_by_series 字段（jsonb）
• 1.4 创建迁移文件：Device 表新增 accumulated_recharge_by_series 和 first_recharge_triggered_by_series 字段（jsonb）
• 1.5 创建迁移文件：PackageSeries 表新增 one_time_commission_config 字段（jsonb）
• 1.6 创建迁移文件：ShopSeriesOneTimeCommissionTier 表新增 stat_scope 字段
• 1.7 创建迁移文件：ShopSeriesAllocation 表移除一次性佣金配置字段，新增 one_time_commission_amount 字段
• 1.8 执行迁移并验证

2. Model 层更新

• 2.1 更新 Package 模型：移除 Price/DataType/DataAmountMB 字段，新增 EnableVirtualData 字段
• 2.2 更新 ShopPackageAllocation 模型：新增 OneTimeCommissionAmount 字段
• 2.3 更新 IoTCard 模型：新增 AccumulatedRechargeBySeriesJSON 和 FirstRechargeTriggeredBySeriesJSON 字段
• 2.4 更新 Device 模型：新增 AccumulatedRechargeBySeriesJSON 和 FirstRechargeTriggeredBySeriesJSON 字段
• 2.5 更新 PackageSeries 模型：新增 OneTimeCommissionConfigJSON 字段
• 2.6 创建 OneTimeCommissionConfig 结构体（含 Enable, TriggerType, Threshold, CommissionType, ValidityType 等字段）
• 2.7 更新 ShopSeriesOneTimeCommissionTier 模型：新增 StatScope 字段
• 2.8 更新 ShopSeriesAllocation 模型：移除一次性佣金配置字段，新增 OneTimeCommissionAmount 字段
• 2.9 为 IoTCard/Device 添加累计充值和首充状态的 getter/setter 辅助方法
• 2.10 运行 lsp_diagnostics 验证 Model 层无编译错误

3. DTO 层更新

• 3.1 更新 CreatePackageRequest：移除 price/data_type/data_amount_mb，新增 enable_virtual_data
• 3.2 更新 UpdatePackageRequest：同上调整字段
• 3.3 更新 PackageResponse：移除废弃字段，新增 enable_virtual_data、one_time_commission_amount
• 3.4 更新 CreateShopPackageAllocationRequest：新增 one_time_commission_amount 字段
• 3.5 更新 ShopPackageAllocationResponse：新增 one_time_commission_amount 字段
• 3.6 更新 CreatePackageSeriesRequest：新增 one_time_commission_config 嵌套结构
• 3.7 更新 PackageSeriesResponse：返回一次性佣金规则配置
• 3.8 简化 CreateShopSeriesAllocationRequest：移除完整一次性佣金配置字段，改为 one_time_commission_amount
• 3.9 简化 ShopSeriesAllocationResponse：移除完整一次性佣金配置字段
• 3.10 运行 lsp_diagnostics 验证 DTO 层无编译错误

4. Store 层更新

• 4.1 更新 PackageStore：适配新字段的 CRUD 操作（GORM Save 自动处理）
• 4.2 更新 ShopPackageAllocationStore：支持 one_time_commission_amount 字段（GORM Save 自动处理）
• 4.3 更新 PackageSeriesStore：支持 one_time_commission_config JSON 字段的读写（GORM Save 自动处理）
• 4.4 更新 ShopSeriesAllocationStore：移除完整一次性佣金配置字段的处理（Model 层已移除字段）
• 4.5 新增 IoTCardStore 方法：UpdateRechargeTrackingFields
• 4.6 新增 IoTCardStore 方法：（通过 Model 层 getter/setter 辅助方法实现）
• 4.7 新增 IoTCardStore 方法：（通过 Model 层 getter/setter 辅助方法实现）
• 4.8 新增 DeviceStore 方法：UpdateRechargeTrackingFields
• 4.9 运行 lsp_diagnostics 验证 Store 层无编译错误

5. Service 层更新 - 套餐管理

• 5.1 更新 PackageService.Create：校验虚流量配置（启用时必填且 ≤ 真流量）
• 5.2 更新 PackageService.Update：同上校验逻辑
• 5.3 更新 PackageService.List：根据用户类型返回不同视角的成本价和一次性佣金金额
• 5.4 新增辅助方法：获取代理的套餐分配关系并填充视角数据
• 5.5 编写 PackageService 单元测试：虚流量配置校验场景
• 5.6 编写 PackageService 单元测试：代理视角套餐列表场景（需要完整测试环境）

6. Service 层更新 - 套餐分配

• 6.1 更新 ShopPackageAllocationService.Create：支持设置一次性佣金金额
• 6.2 新增校验逻辑：一次性佣金金额 ≤ 上级能拿到的金额
• 6.3 新增校验逻辑：一次性佣金金额 ≥ 0
• 6.4 更新 ShopPackageAllocationService.Update：支持修改一次性佣金金额
• 6.5 编写 ShopPackageAllocationService 单元测试：一次性佣金金额校验场景

7. Service 层更新 - 系列管理与分配

• 7.1 更新 PackageSeriesService：支持一次性佣金规则配置的 CRUD
• 7.2 简化 ShopSeriesAllocationService.Create：移除完整一次性佣金配置的处理
• 7.3 简化 ShopSeriesAllocationService.Update：同上
• 7.4 更新验证逻辑：从套餐系列获取一次性佣金规则进行校验
• 7.5 编写单元测试

8. Service 层更新 - 佣金计算

• 8.1 重构一次性佣金触发逻辑：支持按系列追踪首充和累计充值状态
• 8.2 实现链式分配计算逻辑：沿代理链向上计算各级代理分得的佣金
• 8.3 更新累计充值逻辑：只有充值操作累计，直接购买不累计
• 8.4 更新首充判断逻辑：从 single_recharge 改为 first_recharge
• 8.5 实现一次性佣金时效检查：过期规则不触发返佣
• 8.6 更新梯度佣金计算：支持 stat_scope 配置
• 8.7 编写佣金计算 Service 单元测试：链式分配场景
• 8.8 编写佣金计算 Service 单元测试：首充/累计充值场景
• 8.9 编写佣金计算 Service 单元测试：梯度升级场景（已实现时效检查测试）

9. Service 层更新 - 强充检查

• 9.1 更新首充强充金额计算：max(首充要求, 套餐售价)
• 9.2 新增累计充值强充金额计算：支持固定/动态两种模式
• 9.3 更新强充流程：支持累计充值的累计逻辑
• 9.4 编写强充检查 Service 单元测试

10. Handler 层更新

• 10.1 更新 PackageHandler：适配新 DTO 结构
• 10.2 更新 PackageSeriesHandler：支持一次性佣金规则配置
• 10.3 更新 ShopPackageAllocationHandler：支持一次性佣金金额
• 10.4 更新 ShopSeriesAllocationHandler：简化请求/响应结构
• 10.5 更新文档生成器 cmd/api/docs.go 和 cmd/gendocs/main.go
• 10.6 运行 lsp_diagnostics 验证 Handler 层无编译错误

11. 集成测试

• 11.1 编写套餐 CRUD 集成测试：验证虚流量配置
• 11.2 编写套餐分配集成测试：验证一次性佣金金额
• 11.3 编写系列分配集成测试：验证简化后的配置
• 11.4 编写代理视角套餐列表集成测试
• 11.5 编写一次性佣金触发集成测试：首充场景
• 11.6 编写一次性佣金触发集成测试：累计充值场景
• 11.7 编写链式佣金分配集成测试
• 11.8 运行全部测试确保通过

12. 验收

• 12.1 运行完整测试套件，确保全部通过
• 12.2 运行 go build 确保编译通过
• 12.3 本地环境功能验证：套餐创建/修改流程
• 12.4 本地环境功能验证：套餐分配流程
• 12.5 本地环境功能验证：一次性佣金触发流程
• 12.6 更新 OpenAPI 文档确认变更已反映