junhong_cmp_fiber/openspec/changes/archive/2026-01-30-remove-tier-commission-redundancy/tasks.md

1. 准备工作

• 1.1 使用 IDE 的 "Find Usages" 全局搜索 TierCommission、tier_commission、tier_bonus 确认所有引用位置
• 1.2 查看 migrations/ 目录获取最新的 migration 编号，确定新 migration 的编号
• 1.3 备份当前数据库结构（开发环境）以便回滚

2. 删除 Model 层

• 2.1 删除 internal/model/shop_series_commission_tier.go 文件
• 2.2 在 internal/model/shop_series_allocation.go 中删除 EnableTierCommission 字段
• 2.3 在 internal/model/shop_series_allocation_config.go 中删除 EnableTierCommission 字段
• 2.4 在 internal/model/commission.go 中删除 CommissionSourceTierBonus 常量定义
• 2.5 更新 internal/model/commission.go 中的注释，说明佣金来源只有 cost_diff 和 one_time 两种
• 2.6 运行 go build ./... 检查编译错误

3. 删除和更新 DTO

• 3.1 删除 internal/model/dto/shop_series_allocation.go 中的 TierCommissionConfig 类型
• 3.2 删除 internal/model/dto/shop_series_allocation.go 中的 TierEntry 类型
• 3.3 在 CreateShopSeriesAllocationRequest 中删除 EnableTierCommission 和 TierConfig 字段
• 3.4 在 UpdateShopSeriesAllocationRequest 中删除 EnableTierCommission 和 TierConfig 字段
• 3.5 在 ShopSeriesAllocationResponse 中删除 EnableTierCommission 字段
• 3.6 删除 internal/model/dto/commission.go 中 CommissionStatsResponse 的 TierBonusAmount、TierBonusCount、TierBonusPercent 字段
• 3.7 更新 internal/model/dto/commission.go 中 CommissionRecordListRequest 的 commission_source 验证规则，使用 validate:"omitempty,oneof=cost_diff one_time"
• 3.8 更新所有相关 DTO 中的 commission_source 字段验证规则和注释
• 3.9 运行 go build ./... 检查编译错误

4. 删除 Store 层

• 4.1 删除 internal/store/postgres/shop_series_commission_tier_store.go 文件
• 4.2 在 internal/store/interface.go 中删除 ShopSeriesCommissionTierStore 接口定义
• 4.3 更新 internal/store/postgres/commission_record_store.go 的统计查询 SQL，删除 tier_bonus_amount、tier_bonus_count 的计算逻辑
• 4.4 更新 internal/store/postgres/commission_record_store.go 中统计结果的结构体定义，删除 TierBonusAmount 和 TierBonusCount 字段
• 4.5 运行 go build ./... 检查编译错误

5. 更新 Service 层

• 5.1 在 internal/service/shop_series_allocation/service.go 中删除 tierStore 字段（如果存在）
• 5.2 在 internal/service/shop_series_allocation/service.go 中删除 validateTierConfig() 方法（如果存在）
• 5.3 在 internal/service/shop_series_allocation/service.go 的 Create 方法中删除处理 TierConfig 的逻辑
• 5.4 在 internal/service/shop_series_allocation/service.go 的 Update 方法中删除处理 TierConfig 的逻辑
• 5.5 在 internal/service/my_commission/service.go 中删除 tierBonusPercent 的计算逻辑
• 5.6 更新 internal/service/my_commission/service.go 中构建 CommissionStatsResponse 的代码，删除 tier_bonus 相关字段的赋值
• 5.7 运行 go build ./... 检查编译错误

6. 更新 Handler 层

• 6.1 检查 internal/handler/shop_series_allocation_handler.go 是否有直接处理 tier_config 的逻辑，如有则删除
• 6.2 运行 go build ./... 检查编译错误

7. 更新依赖注入

• 7.1 在 internal/bootstrap/wire.go（或相关依赖注入配置文件）中删除 ShopSeriesCommissionTierStore 的 provider
• 7.2 在 internal/bootstrap/wire.go 中删除 NewShopSeriesCommissionTierStore 的调用（如果存在）
• 7.3 在 internal/service/shop_series_allocation/service.go 的构造函数中删除 tierStore 参数（如果存在）
• 7.4 运行 go build ./... 确保依赖注入编译通过

8. 创建数据库迁移

• 8.1 创建新的 migration up 文件（如 migrations/000034_remove_tier_commission.up.sql）
• 8.2 在 up migration 中添加删除 tb_shop_series_allocation.enable_tier_commission 字段的 SQL
• 8.3 在 up migration 中添加删除 tb_shop_series_allocation_config.enable_tier_commission 字段的 SQL
• 8.4 在 up migration 中添加删除 tb_shop_series_commission_tier 表的 SQL（使用 DROP TABLE IF EXISTS）
• 8.5 创建对应的 down migration 文件（如 migrations/000034_remove_tier_commission.down.sql）
• 8.6 在 down migration 中添加恢复 tb_shop_series_commission_tier 表的 SQL
• 8.7 在 down migration 中添加恢复 enable_tier_commission 字段的 SQL
• 8.8 在开发环境执行 go run cmd/migrate/main.go up 测试 migration
• 8.9 验证数据库结构正确（检查字段和表已删除）
• 8.10 执行 go run cmd/migrate/main.go down 测试回滚
• 8.11 验证数据库结构已恢复
• 8.12 重新执行 go run cmd/migrate/main.go up 应用变更

9. 更新集成测试

• 9.1 在 tests/integration/shop_series_allocation_test.go 中删除所有包含 enable_tier_commission 的测试用例
• 9.2 在 tests/integration/shop_package_batch_allocation_test.go 中删除 tier_config 相关的测试数据
• 9.3 添加测试验证创建分配时不接受 enable_tier_commission 字段
• 9.4 添加测试验证更新分配时不接受 enable_tier_commission 字段
• 9.5 添加测试验证查询佣金记录时使用 commission_source=tier_bonus 返回空列表或错误
• 9.6 添加测试验证佣金统计响应中不包含 tier_bonus_amount、tier_bonus_count、tier_bonus_percent 字段
• 9.7 运行 go test ./tests/integration/shop_series_allocation_test.go -v 确保测试通过
• 9.8 运行 go test ./tests/integration/shop_package_batch_allocation_test.go -v 确保测试通过

10. 更新单元测试

• 10.1 检查并更新 internal/service/shop_series_allocation/service_test.go 中的测试（如果存在）
• 10.2 检查并更新 internal/service/my_commission/service_test.go 中的测试
• 10.3 删除 internal/store/postgres/shop_series_commission_tier_store_test.go 文件（如果存在）
• 10.4 运行 go test ./internal/service/... -v 确保所有 Service 测试通过
• 10.5 运行 go test ./internal/store/... -v 确保所有 Store 测试通过

11. 更新 API 文档

• 11.1 检查项目中 OpenAPI 文档的位置（可能在 docs/ 或 api/ 目录）
• 11.2 在 OpenAPI schema 定义中删除 TierCommissionConfig 和 TierEntry
• 11.3 更新 CreateShopSeriesAllocationRequest 的 schema，删除 enable_tier_commission 和 tier_config 字段
• 11.4 更新 UpdateShopSeriesAllocationRequest 的 schema，删除 enable_tier_commission 和 tier_config 字段
• 11.5 更新 ShopSeriesAllocationResponse 的 schema，删除 enable_tier_commission 字段
• 11.6 更新 CommissionStatsResponse 的 schema，删除 tier_bonus_amount、tier_bonus_count、tier_bonus_percent 字段
• 11.7 更新所有 commission_source 的枚举定义，只保留 cost_diff 和 one_time
• 11.8 如果项目使用代码生成 OpenAPI 文档，运行生成命令（如 make generate-docs 或 go run cmd/gendocs/main.go）
• 11.9 检查生成的文档，确认变更正确

12. 完整测试验证

• 12.1 运行完整的单元测试套件：go test ./... -v
• 12.2 运行完整的集成测试套件：go test ./tests/integration/... -v
• 12.3 运行 linter 检查代码质量：golangci-lint run（如果项目使用）
• 12.4 运行 go fmt ./... 确保代码格式正确
• 12.5 运行 go vet ./... 检查潜在问题
• 12.6 检查测试覆盖率：go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out

13. 手动功能验证

• 13.1 启动开发服务器：go run cmd/server/main.go
• 13.2 测试创建套餐系列分配 API，确认请求体中不包含 enable_tier_commission 和 tier_config 字段
• 13.3 测试更新套餐系列分配 API，确认请求体中不包含 enable_tier_commission 和 tier_config 字段
• 13.4 测试查询套餐系列分配列表 API，确认响应中不包含 enable_tier_commission 字段
• 13.5 测试查询套餐系列分配详情 API，确认响应中不包含 enable_tier_commission 字段
• 13.6 测试查询佣金统计 API，确认响应中不包含 tier_bonus_amount、tier_bonus_count、tier_bonus_percent 字段
• 13.7 测试佣金计算流程，确认只生成 cost_diff 和 one_time 类型的佣金记录
• 13.8 测试查询佣金记录列表时使用 commission_source=tier_bonus 筛选，确认返回空列表或错误

14. 文档和变更日志

• 14.1 在 CHANGELOG.md 中记录此次变更（标记为 BREAKING CHANGE）
• 14.2 更新项目 README（如果有相关说明需要修改）
• 14.3 创建迁移指南文档，说明如何从旧的梯度返佣迁移到一次性梯度佣金（如果需要）
• 14.4 通知前端团队 API 契约变更内容

15. 代码审查和合并

• 15.1 提交所有变更到 Git，使用清晰的 commit message（如 "清理冗余的梯度返佣(TierCommission)配置"）
• 15.2 创建 Pull Request，标题和描述引用 proposal 和 design 文档
• 15.3 在 PR 描述中列出所有受影响的 API 端点和破坏性变更
• 15.4 在 PR 中附加测试结果截图或报告
• 15.5 请求团队成员进行代码审查
• 15.6 根据审查意见修改代码
• 15.7 确保 CI/CD 流水线全部通过
• 15.8 合并 PR 到主分支

16. 部署后验证（未来上线时）

• 16.1 在测试环境部署并验证功能
• 16.2 在预发布环境部署并验证功能
• 16.3 执行冒烟测试确认核心功能正常
• 16.4 监控错误日志，确认没有与删除相关的错误
• 16.5 验证数据库 migration 执行成功
• 16.6 准备回滚方案（git revert + migration down）