huang
677d6239ce
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m33s
- 删除 model/commission.go 中与 constants 包冲突的旧常量（值=1/2） - 所有服务层改用 constants.CommissionStatusReleased（值=3）写入和查询 - 数据库迁移：status 1→3（已发放），2→4（已失效） - 修复佣金明细列表接口，通过 JOIN 关联返回 order_no、iccid、virtual_no、order_created_at - 新增 seller_shop_id / seller_shop_name 销售来源字段 - 统计接口过滤条件从精确匹配改为排除无效（NOT IN 4,99） - 更新 OpenAPI 文档及 commission-record-query spec
68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
## Why
|
||
|
||
佣金系统存在**状态常量定义冲突**和**接口数据不完整**两大问题：
|
||
|
||
1. **常量冲突**：`model/commission.go` 和 `pkg/constants/iot.go` 定义了两套不同的佣金状态常量，值 1 在 model 包表示"已入账"，在 constants 包表示"已冻结"，导致佣金记录显示错误
|
||
2. **接口缺陷**：`/commission-records` 接口返回的 ICCID、OrderNo、VirtualNo 等字段全部为空，且缺少销售来源店铺信息
|
||
|
||
这些问题导致：差价佣金被错误显示为"已冻结"、佣金明细无法关联到具体订单和卡、无法追溯佣金产生的销售来源。
|
||
|
||
## What Changes
|
||
|
||
### 1. 统一佣金状态常量
|
||
- 删除 `model/commission.go` 中的旧常量定义
|
||
- 统一使用 `pkg/constants/iot.go` 的四态定义（已冻结→解冻中→已发放→已失效）
|
||
- 迁移数据库中 status 值（1→3, 2→4）
|
||
- 修复 12 处引用旧常量的代码位置
|
||
|
||
### 2. 修复 commission-records 接口关联查询
|
||
- Store 层实现 JOIN 关联查询（订单表、卡表、设备表）
|
||
- 实现 ICCID、OrderNo、DeviceNo 的过滤条件
|
||
- Service 层正确填充 OrderNo、ICCID、VirtualNo、OrderCreatedAt 字段
|
||
|
||
### 3. 新增销售来源店铺信息
|
||
- DTO 新增 SellerShopID、SellerShopName 字段
|
||
- 关联查询订单的 `seller_shop_id` 显示销售来源
|
||
|
||
### 4. 修复佣金统计查询语义
|
||
- `GetStats` 和 `GetDailyStats` 的过滤条件从"精确匹配已发放（status=1）"改为"排除无效和待审（status NOT IN 4,99）"
|
||
- 使总佣金统计包含冻结中的佣金（面向未来的正确语义）
|
||
|
||
### 5. 数据迁移
|
||
- 编写数据库迁移脚本转换历史数据
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
- `commission-record-query`: 佣金记录完整查询能力
|
||
- 支持关联查询订单、卡、设备信息
|
||
- 支持按 ICCID、订单号、设备号过滤
|
||
- 显示销售来源店铺信息
|
||
|
||
### Modified Capabilities
|
||
- `commission-status`: 佣金状态定义
|
||
- 状态值从二态（已入账、已失效）扩展为四态（已冻结、解冻中、已发放、已失效）
|
||
|
||
## Impact
|
||
|
||
### 受影响代码
|
||
| 文件 | 影响 |
|
||
|------|------|
|
||
| `model/commission.go` | 删除旧常量定义 |
|
||
| `pkg/constants/iot.go` | 确认常量定义正确 |
|
||
| `internal/service/commission_calculation/service.go` | 替换常量引用（3处） |
|
||
| `internal/service/shop_commission/service.go` | 替换常量引用 + 填充关联字段（2处） |
|
||
| `internal/service/refund/service.go` | 替换常量引用（1处） |
|
||
| `internal/service/recharge/service.go` | 替换常量引用（1处） |
|
||
| `internal/store/postgres/commission_record_store.go` | 实现过滤条件和 JOIN；修复统计查询语义 |
|
||
| `internal/model/dto/shop_commission_dto.go` | DTO 新增字段 |
|
||
|
||
### 受影响接口
|
||
- `GET /api/admin/shops/:shop_id/commission-records` - 返回值结构变更（新增字段）
|
||
|
||
### 数据库迁移
|
||
- `tb_commission_record.status`: 1→3, 2→4
|
||
|
||
### 依赖项
|
||
- 无新增外部依赖
|