69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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 错误，消息为"企业账号无权访问代理资金功能"
|