junhong_cmp_fiber/openspec/changes/agent-fund-visibility/specs/agent-fund-summary/spec.md at 0627ffec4289ea42d86f54333a298acb61744a65

csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m10s

Details

- 将 GET /shops/commission-summary 重命名为 GET /shops/fund-summary，
  响应新增 main_balance、main_frozen_balance 两个预充值钱包字段
- 新增 GET /shops/:id/main-wallet/transactions 预充值钱包流水接口
- 将佣金统计、每日统计、发起提现从 /my/ 路径迁移至 /shops/:id/ 路径：
  GET /shops/:id/commission-stats
  GET /shops/:id/commission-daily-stats
  POST /shops/:id/withdrawal-requests
- 删除 MyCommissionService、MyCommissionHandler 及全部 /my/ 路由
- 补齐 ListShopWithdrawalRequests、ListShopCommissionRecords 的
  CanManageShop 越权校验（安全修复）
- 提现接口增加严格权限：仅代理账号本人可为自己店铺发起提现

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-09 14:40:39 +08:00

2.9 KiB

Raw Blame History

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

2.9 KiB Raw Blame History Unescape Escape