# agent-fund-summary Specification

## Purpose
代理商资金概况列表，聚合展示代理的预充值钱包（主钱包）和佣金钱包余额信息，供平台和代理多层级查看资金概况。

## ADDED Requirements

### Requirement: 代理商资金概况列表

系统 SHALL 提供 `GET /api/admin/shops/fund-summary` 接口，返回分页的代理商资金概况列表，同时包含预充值钱包（主钱包）和佣金钱包的余额信息。

**响应字段**（`ShopFundSummaryItem`）：
- `shop_id`：店铺 ID
- `shop_name`：店铺名称
- `shop_code`：店铺编码
- `username`：主账号用户名
- `phone`：主账号手机号
- `main_balance`：预充值钱包余额（分）
- `main_frozen_balance`：预充值钱包冻结余额（分）
- `total_commission`：累计佣金总额（分）
- `withdrawn_commission`：已提现佣金（分）
- `unwithdraw_commission`：未提现佣金（分）
- `frozen_commission`：冻结中佣金（分）
- `withdrawing_commission`：提现中佣金（分）
- `available_commission`：可提现佣金（分）
- `created_at`：店铺创建时间

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

**实现要求**：
- 主钱包余额通过 `AgentWalletStore.GetShopMainWalletBatch` 批量查询，避免 N+1
- 若代理暂无主钱包记录（未充值），`main_balance` 和 `main_frozen_balance` 返回 0
- `main_frozen_balance` 字段为未来预留（当前业务无主钱包冻结场景，值恒为 0），前端可暂不展示
- 数据权限：列表查询走 `Shop` 表的数据权限过滤（`SubordinateShopIDs`）。平台人员返回全部代理；代理账号返回自己 + 所有下级店铺（而不是只返回自己一条）

#### Scenario: 平台人员查看所有代理资金概况

- **WHEN** 平台人员请求 `GET /shops/fund-summary`
- **THEN** 系统返回所有代理的分页列表，每条包含 `main_balance` 和佣金钱包字段

#### Scenario: 无下级代理的账号查看自己的资金概况

- **WHEN** 无下级代理的代理账号请求 `GET /shops/fund-summary`
- **THEN** 系统按数据权限过滤，只返回该代理自己的一条记录

#### Scenario: 有下级代理的顶级代理查看资金概况

- **WHEN** 一个拥有多个下级代理的顶级代理账号请求 `GET /shops/fund-summary`
- **THEN** 系统返回自己 + 所有下级代理店铺的资金概况列表（按 `SubordinateShopIDs` 过滤）

#### Scenario: 代理暂无主钱包时返回零值

- **WHEN** 代理从未充值，`tb_agent_wallet` 中无该店铺的 `wallet_type=main` 记录
- **THEN** `main_balance` 和 `main_frozen_balance` 返回 0，其余字段正常返回

#### Scenario: 按店铺名称过滤

- **WHEN** 传入 `shop_name=张三`
- **THEN** 系统只返回店铺名称包含"张三"的代理记录

#### Scenario: 企业账号无权访问

- **WHEN** 企业账号请求此接口
- **THEN** 系统返回 403 错误，消息为"企业账号无权访问代理资金功能"