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

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

## 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 文档确认变更已反映