# 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（已失效）
