# Tasks: refactor-one-time-commission-allocation

## 0. 测试准备（实现前执行）

- [x] 0.1 生成验收测试和流程测试
  - 运行 `/opsx:gen-tests refactor-one-time-commission-allocation`
  - 确认生成文件：`tests/acceptance/shop_series_allocation_acceptance_test.go`
  - 确认生成文件：`tests/acceptance/commission_calculation_acceptance_test.go`

- [x] 0.2 运行测试确认全部 FAIL
  - `source .env.local && go test -v ./tests/acceptance/... -run ShopSeriesAllocation`
  - `source .env.local && go test -v ./tests/acceptance/... -run CommissionCalculation`
  - 预期：全部 FAIL（功能未实现，证明测试有效）

## 1. 数据库迁移

- [x] 1.1 创建迁移：新增 `tb_shop_series_allocation` 表
  - 字段：id, created_at, updated_at, deleted_at, creator, updater
  - 字段：shop_id, series_id, allocator_shop_id, one_time_commission_amount, status
  - 字段：enable_one_time_commission, one_time_commission_trigger, one_time_commission_threshold
  - 字段：enable_force_recharge, force_recharge_amount, force_recharge_trigger_type
  - 唯一索引：(shop_id, series_id)

- [x] 1.2 创建迁移：修改 `tb_package_series` 表
  - 新增字段：enable_one_time_commission (bool, 默认 false)

- [x] 1.3 创建迁移：修改 `tb_shop_package_allocation` 表
  - 新增字段：series_allocation_id (uint)
  - 删除字段：one_time_commission_amount, series_id

- [x] 1.4 创建迁移：删除 `tb_shop_series_one_time_commission_tier` 表

- [x] 1.5 执行迁移并验证
  - `source .env.local && ./scripts/migrate.sh up`
  - 验证：表结构正确

## 2. Model 层

- [x] 2.1 创建 `internal/model/shop_series_allocation.go`
  - ShopSeriesAllocation 结构体 + TableName()

- [x] 2.2 创建 `internal/model/dto/shop_series_allocation.go`
  - Create/Update Request, Response, ListRequest

- [x] 2.3 修改 `internal/model/package.go`
  - PackageSeries 添加 EnableOneTimeCommission 字段

- [x] 2.4 修改 `internal/model/shop_package_allocation.go`
  - 删除 OneTimeCommissionAmount, SeriesID
  - 添加 SeriesAllocationID

- [x] 2.5 修改 `internal/model/dto/shop_package_allocation.go`
  - 删除 one_time_commission_amount 字段

- [x] 2.6 验证 Model 层
  - `lsp_diagnostics` 检查所有修改的文件
  - `go build ./internal/model/...`

## 3. 系列分配功能（完整功能单元）

- [x] 3.1 创建 `internal/store/postgres/shop_series_allocation_store.go`
  - Create, Update, Delete, GetByID
  - GetByShopAndSeries(shopID, seriesID)
  - List（支持筛选）
  - CountBySeriesID

- [x] 3.2 创建 `internal/service/shop_series_allocation/service.go`
  - Create: 验证上级分配、金额上限
  - Update: 验证金额上限
  - Delete: 检查套餐分配依赖
  - Get, List

- [x] 3.3 创建 `internal/handler/admin/shop_series_allocation.go`
  - POST /api/admin/shop-series-allocations
  - GET /api/admin/shop-series-allocations
  - GET /api/admin/shop-series-allocations/:id
  - PUT /api/admin/shop-series-allocations/:id
  - DELETE /api/admin/shop-series-allocations/:id

- [x] 3.4 添加路由和 Bootstrap
  - 路由注册
  - stores.go 添加 ShopSeriesAllocationStore
  - services.go 添加 ShopSeriesAllocationService
  - handlers.go 添加 ShopSeriesAllocationHandler

- [x] 3.5 更新文档生成器
  - pkg/openapi/handlers.go 添加 Handler

- [x] 3.6 **验证：系列分配验收测试 PASS**
  - `source .env.local && go test -v ./tests/acceptance/... -run ShopSeriesAllocation`
  - ✅ 所有系列分配 CRUD 相关测试全部 PASS

## 4. 套餐分配改造

- [x] 4.1 修改 `internal/store/postgres/shop_package_allocation_store.go`
  - 删除 GetByShopAndSeries 方法
  - 添加 CountBySeriesAllocationID 方法
  - 更新 Create/Update 适配新字段

- [x] 4.2 修改 `internal/service/shop_package_allocation/service.go`
  - Create: 添加系列分配依赖检查
  - Create: 自动关联 series_allocation_id
  - 移除 one_time_commission_amount 逻辑

- [x] 4.3 修改 `internal/handler/admin/shop_package_allocation.go`
  - 移除请求/响应中的 one_time_commission_amount

- [x] 4.4 **验证：套餐分配依赖检查测试 PASS**
  - `source .env.local && go test -v ./tests/acceptance/... -run ShopPackageAllocation_SeriesDependency`
  - ✅ 测试通过

## 5. 佣金计算改造

- [x] 5.1 修改 `internal/service/commission_calculation/service.go`
  - 一次性佣金从 ShopSeriesAllocation 获取
  - 实现链式分配计算
  - 梯度模式：min(梯度匹配金额, 分配上限)

- [x] 5.2 修改 `internal/service/recharge/service.go`
  - 充值触发一次性佣金从系列分配获取配置

- [x] 5.3 修改佣金统计相关代码
  - CommissionStats.allocation_id 关联到系列分配

- [x] 5.4 **验证：佣金计算验收测试 PASS**
  - `source .env.local && go test -v ./tests/acceptance/... -run CommissionCalculation`
  - ✅ 所有佣金计算测试通过

## 6. 清理废弃代码

- [x] 6.1 删除 ShopSeriesOneTimeCommissionTier 相关代码
  - 删除 model 文件
  - 删除 store 文件
  - 删除 bootstrap 中的引用

- [x] 6.2 全局搜索并清理遗留引用
  - 搜索 "one_time_commission_amount" 在 ShopPackageAllocation 的使用
  - 搜索 "GetByShopAndSeries" 的调用
  - 更新所有引用点

- [x] 6.3 验证清理完成
  - `go build ./...` 编译通过

## 7. 常量定义

- [x] 7.1 更新 `pkg/constants/redis.go`
  - 添加 RedisShopSeriesAllocationKey 函数

- [x] 7.2 更新 `pkg/constants/constants.go`
  - 使用已有的通用常量 StatusEnabled/StatusDisabled (值 1/0)

## 8. 最终验证

- [x] 8.1 运行所有验收测试
  - `source .env.local && go test -v ./tests/acceptance/...`
  - ✅ 全部 PASS

- [x] 8.2 运行流程测试
  - `source .env.local && go test -v ./tests/flows/...`
  - ✅ 全部 PASS

- [x] 8.3 运行完整测试套件
  - `source .env.local && go test -v ./...`
  - ✅ 验收测试和流程测试全部 PASS
  - ⚠️ 预先存在的失败（与本次重构无关）：gateway/account/store 等测试

- [x] 8.4 编译和启动验证
  - `go build ./...` ✅ 编译通过
  - `source .env.local && go run cmd/api/main.go`
  - 验证：服务正常启动

- [x] 8.5 重新生成 OpenAPI 文档
  - `go run cmd/gendocs/main.go` ✅
  - 验证：文档包含新接口 ✅ `/api/admin/shop-series-allocations`