## ADDED Requirements

### Requirement: 代理商佣金列表查询
系统 SHALL 提供代理商佣金列表查询接口，返回代理商及其佣金汇总信息。

**接口**：`GET /api/admin/shops/commission-summary`

**请求参数**：
- `page`：页码（默认1）
- `page_size`：每页数量（默认20，最大100）
- `shop_name`：店铺名称（模糊查询）
- `username`：主账号用户名（模糊查询）

**响应字段**：
- 店铺基本信息（shop_id, shop_name, shop_code）
- 主账号信息（username, phone）
- 佣金汇总（total, withdrawn, unwithdraw, frozen, withdrawing, available）

#### Scenario: 平台用户查询所有代理商
- **WHEN** 平台用户请求代理商佣金列表
- **THEN** 返回所有代理商及其佣金汇总
- **AND** 按店铺创建时间倒序排列

#### Scenario: 代理商用户查询下级代理商
- **WHEN** 代理商用户请求代理商佣金列表
- **THEN** 只返回自己店铺及下级店铺的数据
- **AND** 数据权限自动过滤

#### Scenario: 按店铺名称筛选
- **WHEN** 请求包含 `shop_name` 参数
- **THEN** 返回店铺名称包含该关键字的记录

#### Scenario: 按主账号用户名筛选
- **WHEN** 请求包含 `username` 参数
- **THEN** 返回主账号用户名包含该关键字的记录

---

### Requirement: 代理商提现记录查询
系统 SHALL 提供按代理商查询提现记录的接口。

**接口**：`GET /api/admin/shops/:shop_id/withdrawal-requests`

**请求参数**：
- `shop_id`：店铺ID（路径参数）
- `page`：页码
- `page_size`：每页数量
- `withdrawal_no`：提现单号（精确查询）
- `start_time`：申请开始时间
- `end_time`：申请结束时间

**响应字段**：
- 提现申请详情（id, withdrawal_no, amount, fee_rate, fee, actual_amount）
- 状态信息（status, status_name）
- 店铺信息（shop_name, shop_hierarchy）
- 申请人/处理人信息
- 收款信息（withdrawal_method, account_name, account_number）
- 时间信息（created_at, processed_at）

#### Scenario: 查询指定店铺的提现记录
- **WHEN** 请求指定店铺的提现记录
- **THEN** 返回该店铺的所有提现记录
- **AND** 按申请时间倒序排列

#### Scenario: 按时间范围筛选
- **WHEN** 请求包含 `start_time` 和 `end_time`
- **THEN** 只返回该时间范围内的记录

#### Scenario: 按提现单号精确查询
- **WHEN** 请求包含 `withdrawal_no`
- **THEN** 返回匹配该单号的记录

#### Scenario: 店铺层级路径显示
- **WHEN** 返回提现记录
- **THEN** 包含店铺层级路径（格式：上上级_上级_本身，最多两层上级）

---

### Requirement: 代理商佣金明细查询
系统 SHALL 提供按代理商查询佣金入账明细的接口。

**接口**：`GET /api/admin/shops/:shop_id/commission-records`

**请求参数**：
- `shop_id`：店铺ID（路径参数）
- `page`：页码
- `page_size`：每页数量
- `commission_type`：佣金类型（one_time/long_term）
- `iccid`：ICCID（模糊查询）
- `device_no`：设备号（模糊查询）
- `order_no`：订单号（模糊查询）

**响应字段**：
- 佣金详情（id, amount, balance_after, commission_type）
- 关联信息（order_no, device_no, iccid）
- 时间信息（order_created_at, created_at）
- 状态信息（status, status_name）

#### Scenario: 查询指定店铺的佣金明细
- **WHEN** 请求指定店铺的佣金明细
- **THEN** 返回该店铺的所有佣金记录
- **AND** 按创建时间倒序排列

#### Scenario: 按佣金类型筛选
- **WHEN** 请求包含 `commission_type`
- **THEN** 只返回该类型的佣金记录

#### Scenario: 按 ICCID 模糊查询
- **WHEN** 请求包含 `iccid`
- **THEN** 返回 ICCID 包含该关键字的记录

#### Scenario: 关联订单和设备信息
- **WHEN** 返回佣金明细
- **THEN** 包含关联的订单号、设备号、ICCID
- **AND** 通过 Order 表关联查询

---

### Requirement: 佣金汇总计算规则
系统 SHALL 按以下规则计算代理商佣金汇总：

- `total_commission`：总佣金 = 钱包余额 + 钱包冻结金额 + 已提现金额
- `withdrawn_commission`：已提现 = 提现申请（status=已通过）总金额
- `unwithdraw_commission`：未提现 = 总佣金 - 已提现
- `frozen_commission`：冻结中 = 钱包冻结金额
- `withdrawing_commission`：提现中 = 提现申请（status=待审批）总金额
- `available_commission`：可提现 = 钱包余额 - 提现中

#### Scenario: 计算新店铺的佣金汇总
- **WHEN** 店铺没有任何佣金记录和提现记录
- **THEN** 所有佣金汇总字段返回 0

#### Scenario: 计算有提现申请的佣金汇总
- **WHEN** 店铺有待审批的提现申请
- **THEN** `withdrawing_commission` 等于待审批申请的总金额
- **AND** `available_commission` 扣除提现中金额
