## 0. 测试准备

- [x] 0.1 查询数据库中现有佣金记录的状态分布：`SELECT status, COUNT(*) FROM tb_commission_record GROUP BY status`
- [x] 0.2 确认现有状态值与常量定义的映射关系

## 1. 数据库迁移

- [x] 1.1 创建迁移文件：将 `tb_commission_record.status` 从旧值迁移到新值（1→3, 2→4）
- [x] 1.2 在测试环境执行迁移并验证：`SELECT status, COUNT(*) FROM tb_commission_record GROUP BY status`
- [x] 1.3 备份生产数据后执行迁移

## 2. 删除冲突常量

- [x] 2.1 删除 `internal/model/commission.go` 中的旧常量定义（第 40-46 行）
- [x] 2.2 更新 `internal/model/commission.go` 中 `CommissionRecord.Status` 字段的 GORM 注释：`1-已入账 2-已失效` → `1-已冻结 2-解冻中 3-已发放 4-已失效`

## 3. 替换常量引用

- [x] 3.1 修改 `internal/service/commission_calculation/service.go` 中的 4 处常量引用
  - [x] 3.1.1 第 151 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`
  - [x] 3.1.2 第 216 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`
  - [x] 3.1.3 第 517 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`
  - [x] 3.1.4 第 659 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`

- [x] 3.2 修改 `internal/service/refund/service.go` 中的 1 处常量引用
  - [x] 3.2.1 第 344 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`

- [x] 3.3 修改 `internal/service/recharge/service.go` 中的 1 处常量引用
  - [x] 3.3.1 第 664 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`

- [x] 3.4 修改 `internal/service/shop_commission/service.go` 中的 2 处常量引用
  - [x] 3.4.1 第 767 行：`model.CommissionStatusReleased` → `constants.CommissionStatusReleased`
  - [x] 3.4.2 第 749 行：`model.CommissionStatusInvalid` → `constants.CommissionStatusInvalid`

- [x] 3.5 修改 `internal/store/postgres/commission_record_store.go` 中的 2 处统计查询过滤条件（**注意：语义变更，不是简单替换常量**）
  - [x] 3.5.1 `GetStats`（第 123 行）：`Where("status = ?", model.CommissionStatusReleased)` → `Where("status NOT IN (?)", []int{constants.CommissionStatusInvalid, constants.CommissionStatusPendingReview})`
  - [x] 3.5.2 `GetDailyStats`（第 169 行）：同上，改为排除 status=4 和 status=99

## 4. 修复 commission-records 接口关联查询

- [x] 4.1 修改 `internal/store/postgres/commission_record_store.go` 的 `ListByShopID` 方法
  - [x] 4.1.1 添加 LEFT JOIN 关联查询（订单表、卡表、设备表）
  - [x] 4.1.2 实现 ICCID 过滤条件（模糊查询）
  - [x] 4.1.3 实现 OrderNo 过滤条件（精确查询）
  - [x] 4.1.4 实现 DeviceNo 过滤条件（模糊查询，通过 device_id JOIN device 表）

- [x] 4.2 修改 `internal/service/shop_commission/service.go` 的 `ListShopCommissionRecords` 方法
  - [x] 4.2.1 从查询结果中提取关联的 order_no、order_created_at
  - [x] 4.2.2 从查询结果中提取关联的 iccid
  - [x] 4.2.3 从查询结果中提取关联的 virtual_no
  - [x] 4.2.4 从查询结果中提取关联的 seller_shop_id

## 5. DTO 增强

- [x] 5.1 修改 `internal/model/dto/shop_commission_dto.go` 的 `ShopCommissionRecordItem` 结构体
  - [x] 5.1.1 新增 `SellerShopID uint` 字段
  - [x] 5.1.2 新增 `SellerShopName string` 字段

- [x] 5.2 更新 `ShopCommissionRecordItem` 的 JSON 标签和 description

## 6. Service 层填充销售店铺信息

- [x] 6.1 修改 `internal/service/shop_commission/service.go` 的 `ListShopCommissionRecords` 方法
  - [x] 6.1.1 批量查询销售店铺信息
  - [x] 6.1.2 填充 `SellerShopID` 和 `SellerShopName` 字段

## 7. 文档更新

- [x] 7.1 更新 `cmd/api/docs.go` 添加新字段说明（如有必要）
- [x] 7.2 更新 `cmd/gendocs/main.go` 如有必要
- [x] 7.3 更新 API 文档注释

## 8. 验证测试

- [x] 8.1 运行 `lsp_diagnostics` 检查所有修改文件的语法错误
- [x] 8.2 构建项目确认编译通过：`go build ./...`
- [x] 8.3 调用 `GET /api/admin/shops/:shop_id/commission-records` 接口验证返回数据
  - [x] 8.3.1 确认 OrderNo 有值
  - [x] 8.3.2 确认 ICCID 有值（单卡订单）
  - [x] 8.3.3 确认 VirtualNo 有值（设备订单）
  - [x] 8.3.4 确认 SellerShopID 和 SellerShopName 有值
  - [x] 8.3.5 确认状态名称正确（status=3 显示"已发放"）
- [x] 8.4 调用 `GET /api/admin/shops/:shop_id/commission-stats` 验证统计接口正常