3.1 KiB
3.1 KiB
agent-fund-summary Specification
Purpose
代理商资金概况列表，聚合展示代理的预充值钱包（主钱包）和佣金钱包余额信息，供平台和代理多层级查看资金概况。
ADDED Requirements
Requirement: 代理商资金概况列表
系统 SHALL 提供 GET /api/admin/shops/fund-summary 接口，返回分页的代理商资金概况列表，同时包含预充值钱包（主钱包）和佣金钱包的余额信息。
响应字段（ShopFundSummaryItem）：
shop_id：店铺 IDshop_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 错误，消息为"企业账号无权访问代理资金功能"