junhong_cmp_fiber/openspec/changes/archive/2026-02-04-refactor-one-time-commission-allocation/tasks.md

Tasks: refactor-one-time-commission-allocation

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

• 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

• 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. 数据库迁移

• 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)

• 1.2 创建迁移：修改 tb_package_series 表

  • 新增字段：enable_one_time_commission (bool, 默认 false)

• 1.3 创建迁移：修改 tb_shop_package_allocation 表

  • 新增字段：series_allocation_id (uint)
  • 删除字段：one_time_commission_amount, series_id

• 1.4 创建迁移：删除 tb_shop_series_one_time_commission_tier 表

• 1.5 执行迁移并验证

  • source .env.local && ./scripts/migrate.sh up
  • 验证：表结构正确

2. Model 层

• 2.1 创建 internal/model/shop_series_allocation.go

  • ShopSeriesAllocation 结构体 + TableName()

• 2.2 创建 internal/model/dto/shop_series_allocation.go

  • Create/Update Request, Response, ListRequest

• 2.3 修改 internal/model/package.go

  • PackageSeries 添加 EnableOneTimeCommission 字段

• 2.4 修改 internal/model/shop_package_allocation.go

  • 删除 OneTimeCommissionAmount, SeriesID
  • 添加 SeriesAllocationID

• 2.5 修改 internal/model/dto/shop_package_allocation.go

  • 删除 one_time_commission_amount 字段

• 2.6 验证 Model 层

  • lsp_diagnostics 检查所有修改的文件
  • go build ./internal/model/...

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

• 3.1 创建 internal/store/postgres/shop_series_allocation_store.go

  • Create, Update, Delete, GetByID
  • GetByShopAndSeries(shopID, seriesID)
  • List（支持筛选）
  • CountBySeriesID

• 3.2 创建 internal/service/shop_series_allocation/service.go

  • Create: 验证上级分配、金额上限
  • Update: 验证金额上限
  • Delete: 检查套餐分配依赖
  • Get, List

• 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

• 3.4 添加路由和 Bootstrap

  • 路由注册
  • stores.go 添加 ShopSeriesAllocationStore
  • services.go 添加 ShopSeriesAllocationService
  • handlers.go 添加 ShopSeriesAllocationHandler

• 3.5 更新文档生成器

  • pkg/openapi/handlers.go 添加 Handler

• 3.6 验证：系列分配验收测试 PASS

  • source .env.local && go test -v ./tests/acceptance/... -run ShopSeriesAllocation
  • ✅ 所有系列分配 CRUD 相关测试全部 PASS

4. 套餐分配改造

• 4.1 修改 internal/store/postgres/shop_package_allocation_store.go

  • 删除 GetByShopAndSeries 方法
  • 添加 CountBySeriesAllocationID 方法
  • 更新 Create/Update 适配新字段

• 4.2 修改 internal/service/shop_package_allocation/service.go

  • Create: 添加系列分配依赖检查
  • Create: 自动关联 series_allocation_id
  • 移除 one_time_commission_amount 逻辑

• 4.3 修改 internal/handler/admin/shop_package_allocation.go

  • 移除请求/响应中的 one_time_commission_amount

• 4.4 验证：套餐分配依赖检查测试 PASS

  • source .env.local && go test -v ./tests/acceptance/... -run ShopPackageAllocation_SeriesDependency
  • ✅ 测试通过

5. 佣金计算改造

• 5.1 修改 internal/service/commission_calculation/service.go

  • 一次性佣金从 ShopSeriesAllocation 获取
  • 实现链式分配计算
  • 梯度模式：min(梯度匹配金额, 分配上限)

• 5.2 修改 internal/service/recharge/service.go

  • 充值触发一次性佣金从系列分配获取配置

• 5.3 修改佣金统计相关代码

  • CommissionStats.allocation_id 关联到系列分配

• 5.4 验证：佣金计算验收测试 PASS

  • source .env.local && go test -v ./tests/acceptance/... -run CommissionCalculation
  • ✅ 所有佣金计算测试通过

6. 清理废弃代码

• 6.1 删除 ShopSeriesOneTimeCommissionTier 相关代码

  • 删除 model 文件
  • 删除 store 文件
  • 删除 bootstrap 中的引用

• 6.2 全局搜索并清理遗留引用

  • 搜索 "one_time_commission_amount" 在 ShopPackageAllocation 的使用
  • 搜索 "GetByShopAndSeries" 的调用
  • 更新所有引用点

• 6.3 验证清理完成

  • go build ./... 编译通过

7. 常量定义

• 7.1 更新 pkg/constants/redis.go

  • 添加 RedisShopSeriesAllocationKey 函数

• 7.2 更新 pkg/constants/constants.go

  • 使用已有的通用常量 StatusEnabled/StatusDisabled (值 1/0)

8. 最终验证

• 8.1 运行所有验收测试

  • source .env.local && go test -v ./tests/acceptance/...
  • ✅ 全部 PASS

• 8.2 运行流程测试

  • source .env.local && go test -v ./tests/flows/...
  • ✅ 全部 PASS

• 8.3 运行完整测试套件

  • source .env.local && go test -v ./...
  • ✅ 验收测试和流程测试全部 PASS
  • ⚠️ 预先存在的失败（与本次重构无关）：gateway/account/store 等测试

• 8.4 编译和启动验证

  • go build ./... ✅ 编译通过
  • source .env.local && go run cmd/api/main.go
  • 验证：服务正常启动

• 8.5 重新生成 OpenAPI 文档

  • go run cmd/gendocs/main.go ✅
  • 验证：文档包含新接口 ✅ /api/admin/shop-series-allocations