junhong_cmp_fiber/openspec/changes/agent-fund-visibility/specs/main-wallet-transactions/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

3.2 KiB

Raw Blame History

ADDED Requirements

Requirement: 预充值钱包流水查询

系统 SHALL 提供 GET /api/admin/shops/:shop_id/main-wallet/transactions 接口，分页返回指定代理店铺的预充值钱包（主钱包）交易流水记录。

响应字段（MainWalletTransactionItem）：

id：流水记录 ID
transaction_type：交易类型。主钱包可能出现的值为 recharge-充值入账 / deduct-套餐扣款 / refund-退款（当前 DB 数据仅见 recharge，deduct / refund 随代购扣款/退款业务上线而出现；接口不对类型做枚举白名单，透传 DB 原值）
transaction_subtype：交易子类型（细分场景，如 order_payment，可为空）
amount：变动金额（分，正数为入账，负数为扣款）
balance_before：变动前余额（分）
balance_after：变动后余额（分）
remark：备注（可为空）
created_at：流水时间

查询参数（MainWalletTransactionListRequest）：

shop_id：路径参数，店铺 ID（必填）
page：页码（默认 1）
page_size：每页数量（默认 20，最大 100）
transaction_type：按类型过滤（可选）
start_date：开始日期，YYYY-MM-DD（可选）
end_date：结束日期，YYYY-MM-DD（可选）

实现要求：

Service 层入口必须调用 middleware.CanManageShop(ctx, shopID) 做越权校验，校验失败直接返回 errors.CodeForbidden；不得依赖 GetMainWallet 的隐式过滤（该方法不做权限校验）
先通过 AgentWalletStore.GetMainWallet(shopID) 获取主钱包；若不存在则返回空列表（total=0），不报错
使用 AgentWalletTransactionStore.ListByWalletIDWithFilters / CountByWalletID（task 2.2 新增）查询流水，支持 transaction_type 和日期过滤
旧方法 ListByShopID / CountByShopID 已在 task 2.3 删除（会跨钱包类型返回数据，易被误用）
结果按 created_at DESC 排序

Scenario: 平台人员查看指定代理的预充值流水

WHEN 平台人员请求 GET /shops/123/main-wallet/transactions
THEN 系统返回店铺 123 的主钱包流水，按时间倒序，含变动前后余额

Scenario: 代理查看自己的预充值流水

WHEN 代理账号请求 GET /shops/自己shop_id/main-wallet/transactions
THEN 系统返回该代理自己的主钱包流水记录

Scenario: 代理尝试查看他人流水被拦截

WHEN 代理账号请求 GET /shops/他人shop_id/main-wallet/transactions
THEN 系统返回 403 错误，消息为"无权限操作该资源或资源不存在"

Scenario: 代理暂无主钱包时返回空列表

WHEN 代理从未充值，主钱包不存在
THEN 系统返回空列表，total 为 0，不报错

Scenario: 按交易类型过滤

WHEN 传入 transaction_type=recharge
THEN 系统只返回充值入账类型的流水

Scenario: 按日期范围过滤

WHEN 传入 start_date=2026-01-01&end_date=2026-03-31
THEN 系统只返回该日期范围内的流水记录

Scenario: 企业账号无权访问

WHEN 企业账号请求此接口
THEN 系统返回 403 错误

3.2 KiB Raw Blame History Unescape Escape