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

## 1. 准备工作

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

## 2. 删除 Model 层

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

## 3. 删除和更新 DTO

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

## 4. 删除 Store 层

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

## 5. 更新 Service 层

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

## 6. 更新 Handler 层

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

## 7. 更新依赖注入

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

## 8. 创建数据库迁移

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

## 9. 更新集成测试

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

## 10. 更新单元测试

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

## 11. 更新 API 文档

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

## 12. 完整测试验证

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

## 13. 手动功能验证

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

## 14. 文档和变更日志

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

## 15. 代码审查和合并

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

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

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