归档

openspec/specs/agent-fund-summary/spec.md

@@ -0,0 +1,68 @@
+# 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 错误，消息为"企业账号无权访问代理资金功能"