junhong_cmp_fiber/openspec/changes/archive/2025-04-11-fix-commission-status-constants/design.md

Context

当前状态

佣金系统存在两套冲突的状态常量定义：

常量位置	状态	值	实际含义
model/commission.go	CommissionStatusReleased	1	已入账
model/commission.go	CommissionStatusInvalid	2	已失效
pkg/constants/iot.go	CommissionStatusFrozen	1	已冻结
pkg/constants/iot.go	CommissionStatusUnfreezing	2	解冻中
pkg/constants/iot.go	CommissionStatusReleased	3	已发放
pkg/constants/iot.go	CommissionStatusInvalid	4	已失效

问题：

1. 佣金计算时写入 model.CommissionStatusReleased（值=1），但 getCommissionStatusName() 使用 pkg/constants/ 的映射，导致 status=1 显示为"已冻结"
2. commission-records 接口 OrderNo、ICCID、VirtualNo 等字段硬编码为空，未关联查询
3. 缺少销售来源店铺信息

受影响代码位置

文件	问题
model/commission.go:40-46	定义了与 constants 包冲突的常量
commission_calculation/service.go:151,216,659	使用 model 常量
shop_commission/service.go:421	使用 constants 包做映射（值冲突）
shop_commission/service.go:423-426	硬编码空值
commission_record_store.go:60-110	过滤条件未实现

Goals / Non-Goals

Goals:

1. 统一佣金状态常量定义，消除二义性
2. 修复 commission-records 接口的关联查询
3. 新增销售来源店铺信息

Non-Goals:

• 不修改订单佣金状态（order.commission_status）的定义
• 不修改钱包冻结/解冻的业务逻辑
• 不修改佣金计算引擎的逻辑

Decisions

Decision 1: 统一使用 pkg/constants/iot.go 的四态定义

选择理由：

• pkg/constants/iot.go 已有完整的四态定义（冻结→解冻中→已发放→失效）
• 该常量包被多处使用，包括 getCommissionStatusName() 函数

关于冻结/解冻机制的澄清：

IoT 卡佣金系统不实现冻结/解冻机制（见 add-one-time-commission/design.md Non-Goals）。四态常量中 status=1（已冻结）和 status=2（解冻中）是为号卡业务预留的，IoT 卡差价佣金和一次性佣金均直接入账（status=3）。因此本次修复的核心是：消除 model 包旧常量（值=1 表示"已入账"）与 constants 包新常量（值=1 表示"已冻结"）之间的语义冲突，将所有写入和查询统一到 constants.CommissionStatusReleased（值=3）。

变更内容：

// 删除 model/commission.go 第 40-46 行
const (
    // CommissionStatusReleased = 1  // 删除
    // CommissionStatusInvalid  = 2  // 删除
)

// 使用 constants 包的定义
Status: constants.CommissionStatusReleased  // 值=3

Decision 2: 数据库状态值迁移

方案：通过 SQL 直接迁移历史数据

-- 迁移脚本
UPDATE tb_commission_record SET status = 3 WHERE status = 1;  -- 已入账（旧值=1）→ 已发放（新值=3）
UPDATE tb_commission_record SET status = 4 WHERE status = 2;  -- 已失效（旧值=2）→ 已失效（新值=4）

注意：迁移后需要验证数据一致性。

Decision 3: Store 层实现 JOIN 关联查询

方案：修改 ListByShopID 方法，添加 LEFT JOIN，并引入专用结果结构体承接扫描结果

// commission_record_store.go

// CommissionRecordWithRelations 包含关联字段的查询结果
type CommissionRecordWithRelations struct {
    model.CommissionRecord
    OrderNo        string     `gorm:"column:order_no"`
    OrderCreatedAt *time.Time `gorm:"column:order_created_at"`
    ICCID          string     `gorm:"column:iccid"`
    VirtualNo      string     `gorm:"column:virtual_no"`
    SellerShopID   *uint      `gorm:"column:seller_shop_id"`
}

func (s *CommissionRecordStore) ListByShopID(...) ([]*CommissionRecordWithRelations, int64, error) {
    query := s.db.WithContext(ctx).Model(&model.CommissionRecord{}).
        Joins("LEFT JOIN tb_order o ON tb_commission_record.order_id = o.id").
        Joins("LEFT JOIN tb_iot_card ic ON tb_commission_record.iot_card_id = ic.id").
        Joins("LEFT JOIN tb_device d ON tb_commission_record.device_id = d.id")
    
    // 投影必要字段
    query = query.Select(`tb_commission_record.*, 
        o.order_no, o.created_at as order_created_at, o.seller_shop_id,
        ic.iccid, d.virtual_no`)
    
    // 过滤条件...
    var records []*CommissionRecordWithRelations
    // ...
    query.Find(&records)
}

说明：

• JOIN 条件必须使用实际表名 tb_commission_record，GORM 不自动生成别名
• 使用嵌入 model.CommissionRecord 的专用结构体，避免污染原始模型
• SellerShopID 直接从订单表 JOIN 取得，SellerShopName 在 Service 层批量查询（见 Decision 5）

替代方案考虑：

• 方案 A（当前选择）：Store 层 JOIN - 减少数据库往返次数
• 方案 B：Service 层批量查询 - 更灵活但 N+1 查询

Decision 4: DTO 新增销售来源字段

// shop_commission_dto.go
type ShopCommissionRecordItem struct {
    // ... 现有字段
    SellerShopID   uint   `json:"seller_shop_id"`   // 新增
    SellerShopName string `json:"seller_shop_name"` // 新增
}

查询逻辑：

• SellerShopID：通过 o.seller_shop_id 从订单 JOIN 直接获取（已在 Decision 3 的 SELECT 中包含）
• SellerShopName：Store 层不再多加一次 JOIN（避免进一步增加 JOIN 复杂度），由 Service 层收集所有 SellerShopID 后批量查询 tb_shop，填充到 DTO

// service 层伪代码
sellerShopIDs := collectUniqueSellerShopIDs(records)
shops, _ := s.shopStore.GetByIDs(ctx, sellerShopIDs)
shopNameMap := buildShopNameMap(shops)
for _, item := range items {
    item.SellerShopName = shopNameMap[item.SellerShopID]
}

Decision 5: 佣金统计查询的状态过滤语义

问题：GetStats 和 GetDailyStats 目前用 status = model.CommissionStatusReleased（值=1）过滤，语义是"只统计已发放的佣金"。但总佣金应包含冻结中的佣金（status=1,2,3 均为有效佣金，仅 status=4 失效、status=99 待人工处理应排除）。

决策：将两处过滤条件从"精确匹配已发放"改为"排除无效和待审"：

// 修改前
Where("status = ?", model.CommissionStatusReleased)  // 值=1（旧语义：已入账）

// 修改后
Where("status NOT IN (?)", []int{constants.CommissionStatusInvalid, constants.CommissionStatusPendingReview})
// 即 status NOT IN (4, 99)，包含已冻结(1)、解冻中(2)、已发放(3)

影响文件：internal/store/postgres/commission_record_store.go 第 123 行（GetStats）和第 169 行（GetDailyStats）。

注：IoT 卡当前实现中不存在 status=1/2 的记录，此改动为面向未来的正确语义，不影响现有数据结果。

Risks / Trade-offs

[风险] 数据库迁移可能影响历史数据

→ 缓解措施：

1. 迁移前先备份数据
2. 在测试环境验证迁移脚本
3. 迁移后对比记录数确认

[风险] JOIN 查询可能影响性能

→ 缓解措施：

1. 确保 order_id、iot_card_id、device_id 有索引
2. 添加 LIMIT 和分页
3. 监控查询性能（P95 < 200ms）

[风险] 常量变更可能影响其他模块

→ 缓解措施：

1. 全局搜索 model.CommissionStatus 确保无遗漏
2. 编写单元测试验证状态值

Open Questions

1. 一次性佣金是否需要冻结逻辑？ 已确认：IoT 卡差价佣金和一次性佣金均直接入账，不实现冻结/解冻。冻结机制为号卡业务预留，IoT 卡侧本期 Non-Goal（见 add-one-time-commission/design.md）。

2. 是否需要回滚旧数据的 status 值？ 还是直接迁移？→ 直接迁移（1→3, 2→4）。

3. 销售店铺名称是否需要缓存？ 避免每次查询都 JOIN shop 表。