fix: 统一佣金状态常量并修复佣金明细关联查询

- 删除 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
2026-04-11 10:42:37 +08:00
parent d0989c66bb
commit 677d6239ce
17 changed files with 604 additions and 38 deletions
--- a/docs/admin-openapi.yaml
+++ b/docs/admin-openapi.yaml
@@ -6182,8 +6182,15 @@ components:
                order_no:
                    description: 订单号
                    type: string
+                seller_shop_id:
+                    description: 销售来源店铺ID
+                    minimum: 0
+                    type: integer
+                seller_shop_name:
+                    description: 销售来源店铺名称
+                    type: string
                status:
-                    description: 状态 (1:已入账, 2:已失效)
+                    description: 状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效)
                    type: integer
                status_name:
                    description: 状态名称
--- a/internal/model/commission.go
+++ b/internal/model/commission.go
@@ -19,7 +19,7 @@ type CommissionRecord struct {
 	CommissionSource string     `gorm:"column:commission_source;type:varchar(20);not null;index;comment:佣金来源 cost_diff-成本价差 one_time-一次性佣金" json:"commission_source"`
 	Amount           int64      `gorm:"column:amount;type:bigint;not null;comment:佣金金额(分)" json:"amount"`
 	BalanceAfter     int64      `gorm:"column:balance_after;type:bigint;default:0;comment:入账后钱包余额（分）" json:"balance_after"`
-	Status           int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-已入账 2-已失效" json:"status"`
+	Status           int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-已冻结 2-解冻中 3-已发放 4-已失效" json:"status"`
 	ReleasedAt       *time.Time `gorm:"column:released_at;comment:入账时间" json:"released_at"`
 	Remark           string     `gorm:"column:remark;type:varchar(500);comment:备注" json:"remark"`
 }
@@ -36,11 +36,3 @@ const (
 	// CommissionSourceOneTime 一次性佣金
 	CommissionSourceOneTime = "one_time"
 )
-
-// 佣金状态常量
-const (
-	// CommissionStatusReleased 已入账
-	CommissionStatusReleased = 1
-	// CommissionStatusInvalid 已失效
-	CommissionStatusInvalid = 2
-)
--- a/internal/model/dto/shop_commission_dto.go
+++ b/internal/model/dto/shop_commission_dto.go
@@ -144,13 +144,15 @@ type ShopCommissionRecordItem struct {
 	Amount           int64  `json:"amount" description:"佣金金额（分）"`
 	BalanceAfter     int64  `json:"balance_after" description:"入账后佣金余额（分）"`
 	CommissionSource string `json:"commission_source" description:"佣金来源 (cost_diff:成本价差, one_time:一次性佣金, tier_bonus(已废弃):梯度奖励)"`
-	Status           int    `json:"status" description:"状态 (1:已入账, 2:已失效)"`
+	Status           int    `json:"status" description:"状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效)"`
 	StatusName       string `json:"status_name" description:"状态名称"`
 	OrderID          uint   `json:"order_id" description:"订单ID"`
 	OrderNo          string `json:"order_no" description:"订单号"`
 	VirtualNo        string `json:"virtual_no,omitempty" description:"设备虚拟号"`
 	ICCID            string `json:"iccid,omitempty" description:"ICCID"`
 	OrderCreatedAt   string `json:"order_created_at" description:"订单创建时间"`
+	SellerShopID     uint   `json:"seller_shop_id" description:"销售来源店铺ID"`
+	SellerShopName   string `json:"seller_shop_name" description:"销售来源店铺名称"`
 	CreatedAt        string `json:"created_at" description:"佣金入账时间"`
 }

--- a/internal/service/commission_calculation/service.go
+++ b/internal/service/commission_calculation/service.go
@@ -148,7 +148,7 @@ func (s *Service) CalculateCostDiffCommission(ctx context.Context, order *model.
 			DeviceID:         order.DeviceID,
 			CommissionSource: model.CommissionSourceCostDiff,
 			Amount:           sellerProfit,
-			Status:           model.CommissionStatusReleased,
+			Status:           constants.CommissionStatusReleased,
 		})
 	}

@@ -213,7 +213,7 @@ func (s *Service) CalculateCostDiffCommission(ctx context.Context, order *model.
 				DeviceID:         order.DeviceID,
 				CommissionSource: model.CommissionSourceCostDiff,
 				Amount:           profit,
-				Status:           model.CommissionStatusReleased,
+				Status:           constants.CommissionStatusReleased,
 			})
 		}

@@ -514,7 +514,7 @@ func (s *Service) calculateChainOneTimeCommission(ctx context.Context, bottomSho
 				DeviceID:         deviceID,
 				CommissionSource: model.CommissionSourceOneTime,
 				Amount:           actualProfit,
-				Status:           model.CommissionStatusReleased,
+				Status:           constants.CommissionStatusReleased,
 				Remark:           remark,
 			})
 		}
@@ -656,7 +656,7 @@ func (s *Service) creditCommissionInTx(ctx context.Context, tx *gorm.DB, record
 	now := time.Now()
 	if err := tx.Model(record).Updates(map[string]any{
 		"balance_after": balanceBefore + record.Amount,
-		"status":        model.CommissionStatusReleased,
+		"status":        constants.CommissionStatusReleased,
 		"released_at":   now,
 	}).Error; err != nil {
 		return errors.Wrap(errors.CodeDatabaseError, err, "更新佣金记录失败")
--- a/internal/service/recharge/service.go
+++ b/internal/service/recharge/service.go
@@ -661,7 +661,7 @@ func (s *Service) triggerOneTimeCommissionIfNeededInTx(ctx context.Context, tx *
 		DeviceID:         deviceID,
 		CommissionSource: model.CommissionSourceOneTime,
 		Amount:           commissionAmount,
-		Status:           model.CommissionStatusReleased,
+		Status:           constants.CommissionStatusReleased,
 		Remark:           "钱包充值触发一次性佣金",
 	}

--- a/internal/service/refund/service.go
+++ b/internal/service/refund/service.go
@@ -341,7 +341,7 @@ func (s *Service) deductAllCommission(ctx context.Context, refundID uint) {

 	// 查询该订单所有已入账佣金记录
 	var commissions []model.CommissionRecord
-	if err := s.db.Where("order_id = ? AND status = ?", refund.OrderID, model.CommissionStatusReleased).Find(&commissions).Error; err != nil {
+	if err := s.db.Where("order_id = ? AND status = ?", refund.OrderID, constants.CommissionStatusReleased).Find(&commissions).Error; err != nil {
 		logger.Error("佣金回扣：查询佣金记录失败", zap.Uint("refund_id", refundID), zap.Uint("order_id", refund.OrderID), zap.Error(err))
 		return
 	}
--- a/internal/service/shop_commission/service.go
+++ b/internal/service/shop_commission/service.go
@@ -410,8 +410,33 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 		return nil, errors.Wrap(errors.CodeInternalError, err, "查询佣金明细失败")
 	}

+	sellerShopIDs := make([]uint, 0)
+	for _, r := range records {
+		if r.SellerShopID != nil && *r.SellerShopID > 0 {
+			sellerShopIDs = append(sellerShopIDs, *r.SellerShopID)
+		}
+	}
+
+	shopNameMap := make(map[uint]string)
+	if len(sellerShopIDs) > 0 {
+		shops, err := s.shopStore.GetByIDs(ctx, sellerShopIDs)
+		if err == nil {
+			for _, sh := range shops {
+				shopNameMap[sh.ID] = sh.ShopName
+			}
+		}
+	}
+
 	items := make([]dto.ShopCommissionRecordItem, 0, len(records))
 	for _, r := range records {
+		var orderCreatedAt string
+		if r.OrderCreatedAt != nil {
+			orderCreatedAt = r.OrderCreatedAt.Format("2006-01-02 15:04:05")
+		}
+		var sellerShopID uint
+		if r.SellerShopID != nil {
+			sellerShopID = *r.SellerShopID
+		}
 		item := dto.ShopCommissionRecordItem{
 			ID:               r.ID,
 			Amount:           r.Amount,
@@ -420,10 +445,12 @@ func (s *Service) ListShopCommissionRecords(ctx context.Context, shopID uint, re
 			Status:           r.Status,
 			StatusName:       getCommissionStatusName(r.Status),
 			OrderID:          r.OrderID,
-			OrderNo:          "",
-			VirtualNo:        "",
-			ICCID:            "",
-			OrderCreatedAt:   "",
+			OrderNo:          r.OrderNo,
+			VirtualNo:        r.VirtualNo,
+			ICCID:            r.ICCID,
+			OrderCreatedAt:   orderCreatedAt,
+			SellerShopID:     sellerShopID,
+			SellerShopName:   shopNameMap[sellerShopID],
 			CreatedAt:        r.CreatedAt.Format("2006-01-02 15:04:05"),
 		}
 		items = append(items, item)
@@ -746,7 +773,7 @@ func (s *Service) ResolveCommissionRecord(ctx context.Context, recordID uint, re

 	if req.Action == "invalidate" {
 		return s.commissionRecordStore.UpdateByID(ctx, nil, recordID, map[string]any{
-			"status": model.CommissionStatusInvalid,
+			"status": constants.CommissionStatusInvalid,
 			"remark": resolveRemark,
 		})
 	}
@@ -764,7 +791,7 @@ func (s *Service) ResolveCommissionRecord(ctx context.Context, recordID uint, re

 	return s.db.Transaction(func(tx *gorm.DB) error {
 		if err := s.commissionRecordStore.UpdateByID(ctx, tx, recordID, map[string]any{
-			"status":      model.CommissionStatusReleased,
+			"status":      constants.CommissionStatusReleased,
 			"amount":      amount,
 			"released_at": now,
 			"remark":      resolveRemark,
--- a/internal/store/postgres/commission_record_store.go
+++ b/internal/store/postgres/commission_record_store.go
@@ -2,6 +2,7 @@ package postgres

 import (
 	"context"
+	"time"

 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/store"
@@ -11,6 +12,15 @@ import (
 	"gorm.io/gorm"
 )

+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"`
+}
+
 type CommissionRecordStore struct {
 	db    *gorm.DB
 	redis *redis.Client
@@ -57,29 +67,39 @@ type CommissionRecordListFilters struct {
 	Status           *int
 }

-func (s *CommissionRecordStore) ListByShopID(ctx context.Context, opts *store.QueryOptions, filters *CommissionRecordListFilters) ([]*model.CommissionRecord, int64, error) {
-	var records []*model.CommissionRecord
+func (s *CommissionRecordStore) ListByShopID(ctx context.Context, opts *store.QueryOptions, filters *CommissionRecordListFilters) ([]*CommissionRecordWithRelations, int64, error) {
 	var total int64

-	query := s.db.WithContext(ctx).Model(&model.CommissionRecord{})
-	// 应用数据权限过滤
+	query := s.db.WithContext(ctx).Model(&model.CommissionRecord{}).
+		Joins("LEFT JOIN tb_order o ON tb_commission_record.order_id = o.id AND o.deleted_at IS NULL").
+		Joins("LEFT JOIN tb_iot_card ic ON tb_commission_record.iot_card_id = ic.id AND ic.deleted_at IS NULL").
+		Joins("LEFT JOIN tb_device d ON tb_commission_record.device_id = d.id AND d.deleted_at IS NULL")
 	query = middleware.ApplyShopFilter(ctx, query)

 	if filters != nil {
 		if filters.ShopID > 0 {
-			query = query.Where("shop_id = ?", filters.ShopID)
+			query = query.Where("tb_commission_record.shop_id = ?", filters.ShopID)
 		}
 		if filters.CommissionSource != "" {
-			query = query.Where("commission_source = ?", filters.CommissionSource)
+			query = query.Where("tb_commission_record.commission_source = ?", filters.CommissionSource)
 		}
 		if filters.StartTime != nil && *filters.StartTime != "" {
-			query = query.Where("created_at >= ?", *filters.StartTime)
+			query = query.Where("tb_commission_record.created_at >= ?", *filters.StartTime)
 		}
 		if filters.EndTime != nil && *filters.EndTime != "" {
-			query = query.Where("created_at <= ?", *filters.EndTime)
+			query = query.Where("tb_commission_record.created_at <= ?", *filters.EndTime)
 		}
 		if filters.Status != nil {
-			query = query.Where("status = ?", *filters.Status)
+			query = query.Where("tb_commission_record.status = ?", *filters.Status)
+		}
+		if filters.ICCID != "" {
+			query = query.Where("ic.iccid LIKE ?", "%"+filters.ICCID+"%")
+		}
+		if filters.OrderNo != "" {
+			query = query.Where("o.order_no = ?", filters.OrderNo)
+		}
+		if filters.DeviceNo != "" {
+			query = query.Where("d.virtual_no LIKE ?", "%"+filters.DeviceNo+"%")
 		}
 	}

@@ -94,14 +114,16 @@ func (s *CommissionRecordStore) ListByShopID(ctx context.Context, opts *store.Qu
 		}
 	}
 	offset := (opts.Page - 1) * opts.PageSize
+	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`)
 	query = query.Offset(offset).Limit(opts.PageSize)

 	if opts.OrderBy != "" {
 		query = query.Order(opts.OrderBy)
 	} else {
-		query = query.Order("created_at DESC")
+		query = query.Order("tb_commission_record.created_at DESC")
 	}

+	var records []*CommissionRecordWithRelations
 	if err := query.Find(&records).Error; err != nil {
 		return nil, 0, err
 	}
@@ -120,7 +142,7 @@ type CommissionStats struct {

 func (s *CommissionRecordStore) GetStats(ctx context.Context, filters *CommissionRecordListFilters) (*CommissionStats, error) {
 	query := s.db.WithContext(ctx).Model(&model.CommissionRecord{}).
-		Where("status = ?", model.CommissionStatusReleased)
+		Where("status NOT IN (?)", []int{constants.CommissionStatusInvalid, constants.CommissionStatusPendingReview})
 	// 应用数据权限过滤
 	query = middleware.ApplyShopFilter(ctx, query)

@@ -166,7 +188,7 @@ func (s *CommissionRecordStore) GetDailyStats(ctx context.Context, filters *Comm
 	}

 	query := s.db.WithContext(ctx).Model(&model.CommissionRecord{}).
-		Where("status = ?", model.CommissionStatusReleased)
+		Where("status NOT IN (?)", []int{constants.CommissionStatusInvalid, constants.CommissionStatusPendingReview})
 	// 应用数据权限过滤
 	query = middleware.ApplyShopFilter(ctx, query)

--- a/migrations/000113_migrate_commission_status.down.sql
+++ b/migrations/000113_migrate_commission_status.down.sql
@@ -0,0 +1,2 @@
+UPDATE tb_commission_record SET status = 1 WHERE status = 3;
+UPDATE tb_commission_record SET status = 2 WHERE status = 4;
--- a/migrations/000113_migrate_commission_status.up.sql
+++ b/migrations/000113_migrate_commission_status.up.sql
@@ -0,0 +1,5 @@
+-- 迁移佣金记录状态值：将旧常量值迁移到新四态常量值
+-- 旧值 1（已入账） → 新值 3（已发放）
+-- 旧值 2（已失效） → 新值 4（已失效）
+UPDATE tb_commission_record SET status = 3 WHERE status = 1;
+UPDATE tb_commission_record SET status = 4 WHERE status = 2;
--- a/opencode.json
+++ b/opencode.json
@@ -7,9 +7,9 @@
        "apiKey": "sk-ZBGcMXCdwtSK7G35s"
      }
    },
-    "google": {
+    "minimax": {
      "options": {
-        "baseURL": "http://45.155.220.179:8317/v1beta",
+        "baseURL": "http://45.155.220.179:8317/v1",
        "apiKey": "sk-ZBGcMXCdwtSK7G35s"
      }
    }
--- a/openspec/changes/archive/2025-04-11-fix-commission-status-constants/.openspec.yaml
+++ b/openspec/changes/archive/2025-04-11-fix-commission-status-constants/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-11
--- a/openspec/changes/archive/2025-04-11-fix-commission-status-constants/design.md
+++ b/openspec/changes/archive/2025-04-11-fix-commission-status-constants/design.md
@@ -0,0 +1,195 @@
+## 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）。
+
+**变更内容**：
+```go
+// 删除 model/commission.go 第 40-46 行
+const (
+    // CommissionStatusReleased = 1  // 删除
+    // CommissionStatusInvalid  = 2  // 删除
+)
+
+// 使用 constants 包的定义
+Status: constants.CommissionStatusReleased  // 值=3
+```
+
+### Decision 2: 数据库状态值迁移
+
+**方案**：通过 SQL 直接迁移历史数据
+
+```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，并引入专用结果结构体承接扫描结果
+
+```go
+// 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 新增销售来源字段
+
+```go
+// 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
+
+```go
+// 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 待人工处理应排除）。
+
+**决策**：将两处过滤条件从"精确匹配已发放"改为"排除无效和待审"：
+
+```go
+// 修改前
+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 表。
--- a/openspec/changes/archive/2025-04-11-fix-commission-status-constants/proposal.md
+++ b/openspec/changes/archive/2025-04-11-fix-commission-status-constants/proposal.md
@@ -0,0 +1,67 @@
+## 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
+
+### 依赖项
+- 无新增外部依赖
--- a/openspec/changes/archive/2025-04-11-fix-commission-status-constants/specs/commission-record-query/spec.md
+++ b/openspec/changes/archive/2025-04-11-fix-commission-status-constants/specs/commission-record-query/spec.md
@@ -0,0 +1,104 @@
+# Commission Record Query
+
+## ADDED Requirements
+
+### Requirement: 佣金明细列表查询
+
+系统 SHALL 支持通过店铺 ID 查询该店铺的佣金明细列表，包含完整的订单、卡、设备关联信息。
+
+#### Scenario: 查询佣金明细列表
+- **WHEN** 调用 `GET /api/admin/shops/:shop_id/commission-records` 接口
+- **THEN** 返回佣金记录列表，每条记录包含：
+  - 佣金记录 ID、金额、状态、状态名称
+  - 订单号（order_no）
+  - 订单创建时间（order_created_at）
+  - ICCID（当订单类型为单卡时）
+  - 设备虚拟号（当订单类型为设备时）
+  - 销售来源店铺 ID 和名称（seller_shop_id, seller_shop_name）
+  - 佣金入账时间
+
+#### Scenario: 按佣金来源过滤
+- **WHEN** 请求包含 `commission_source` 查询参数
+- **THEN** 仅返回指定来源的记录（cost_diff 或 one_time）
+
+#### Scenario: 按 ICCID 模糊查询
+- **WHEN** 请求包含 `iccid` 查询参数
+- **THEN** 仅返回 ICCID 包含指定值的记录
+
+#### Scenario: 按设备虚拟号模糊查询
+- **WHEN** 请求包含 `virtual_no` 查询参数
+- **THEN** 仅返回设备虚拟号包含指定值的记录
+
+#### Scenario: 按订单号精确查询
+- **WHEN** 请求包含 `order_no` 查询参数
+- **THEN** 仅返回订单号完全匹配的记录
+
+#### Scenario: 分页查询
+- **WHEN** 请求分页参数（page, page_size）
+- **THEN** 返回指定页的记录，总数和页码信息
+
+---
+
+### Requirement: 佣金状态常量一致性
+
+系统 SHALL 使用统一的状态值和状态名称映射，确保佣金状态显示正确。
+
+#### Scenario: 已发放状态正确显示
+- **WHEN** 佣金记录 status = 3
+- **THEN** 状态名称返回 "已发放"
+
+#### Scenario: 已冻结状态正确显示
+- **WHEN** 佣金记录 status = 1
+- **THEN** 状态名称返回 "已冻结"
+
+#### Scenario: 解冻中状态正确显示
+- **WHEN** 佣金记录 status = 2
+- **THEN** 状态名称返回 "解冻中"
+
+#### Scenario: 已失效状态正确显示
+- **WHEN** 佣金记录 status = 4
+- **THEN** 状态名称返回 "已失效"
+
+---
+
+### Requirement: 佣金统计接口
+
+系统 SHALL 支持获取指定店铺的佣金统计信息，包括累计佣金、已提现、可提现等。
+
+#### Scenario: 查询佣金统计
+- **WHEN** 调用 `GET /api/admin/shops/:shop_id/commission-stats` 接口
+- **THEN** 返回佣金统计数据：
+  - 总佣金金额
+  - 差价佣金金额和占比
+  - 一次性佣金金额和占比
+  - 佣金记录数
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: 佣金状态定义
+
+**原内容**：
+
+佣金记录状态为二态：1=已入账，2=已失效
+
+**修改为**：
+
+佣金记录状态为四态：
+- 1 = 已冻结：佣金已计算但暂不可提现
+- 2 = 解冻中：满足解冻条件，正在等待发放
+- 3 = 已发放：佣金已入账可提现
+- 4 = 已失效：佣金核验失败或订单退款导致失效
+
+#### Scenario: 差价佣金创建时状态
+- **WHEN** 差价佣金计算完成并创建记录
+- **THEN** 记录状态为 3（已发放）
+
+#### Scenario: 链路断裂时状态
+- **WHEN** 佣金链路断裂（上级代理未分配套餐）
+- **THEN** 记录状态为 99（待人工修正）
+
+#### Scenario: 订单退款时状态
+- **WHEN** 关联订单发生退款
+- **THEN** 佣金记录状态更新为 4（已失效）
--- a/openspec/changes/archive/2025-04-11-fix-commission-status-constants/tasks.md
+++ b/openspec/changes/archive/2025-04-11-fix-commission-status-constants/tasks.md
@@ -0,0 +1,83 @@
+## 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` 验证统计接口正常
--- a/openspec/specs/commission-record-query/spec.md
+++ b/openspec/specs/commission-record-query/spec.md
@@ -49,7 +49,13 @@

 #### Scenario: 响应包含关联信息
 - **WHEN** 查询佣金记录列表
- **THEN** 每条记录包含：订单号、卡/设备信息、套餐名称
+- **THEN** 每条记录包含：
+  - 佣金记录 ID、金额、状态、状态名称
+  - 订单号（order_no）、订单创建时间（order_created_at）
+  - ICCID（当订单类型为单卡时）
+  - 设备虚拟号（当订单类型为设备时）
+  - 销售来源店铺 ID 和名称（seller_shop_id, seller_shop_name）
+  - 佣金入账时间

 ---

@@ -100,3 +106,55 @@
 #### Scenario: 默认最近30天
 - **WHEN** 代理查询每日统计不指定日期范围
 - **THEN** 系统返回最近 30 天的数据
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: 佣金状态定义
+
+**原内容**：
+
+佣金记录状态为二态：1=已入账，2=已失效
+
+**修改为**：
+
+佣金记录状态为四态：
+- 1 = 已冻结：佣金已计算但暂不可提现
+- 2 = 解冻中：满足解冻条件，正在等待发放
+- 3 = 已发放：佣金已入账可提现
+- 4 = 已失效：佣金核验失败或订单退款导致失效
+
+#### Scenario: 差价佣金创建时状态
+- **WHEN** 差价佣金计算完成并创建记录
+- **THEN** 记录状态为 3（已发放）
+
+#### Scenario: 链路断裂时状态
+- **WHEN** 佣金链路断裂（上级代理未分配套餐）
+- **THEN** 记录状态为 99（待人工修正）
+
+#### Scenario: 订单退款时状态
+- **WHEN** 关联订单发生退款
+- **THEN** 佣金记录状态更新为 4（已失效）
+
+---
+
+### Requirement: 佣金状态常量一致性
+
+系统 SHALL 使用统一的状态值和状态名称映射，确保佣金状态显示正确。
+
+#### Scenario: 已发放状态正确显示
+- **WHEN** 佣金记录 status = 3
+- **THEN** 状态名称返回 "已发放"
+
+#### Scenario: 已冻结状态正确显示
+- **WHEN** 佣金记录 status = 1
+- **THEN** 状态名称返回 "已冻结"
+
+#### Scenario: 解冻中状态正确显示
+- **WHEN** 佣金记录 status = 2
+- **THEN** 状态名称返回 "解冻中"
+
+#### Scenario: 已失效状态正确显示
+- **WHEN** 佣金记录 status = 4
+- **THEN** 状态名称返回 "已失效"