## Why 目前平台人员和代理账号均无法看到代理的预充值钱包（主钱包）余额与流水，佣金相关接口散落在 `/my/` 前缀下且与 `/shops/:id/` 路径存在职责重叠，亟需统一入口、补全预充值钱包可见性。 ## What Changes - **BREAKING** `GET /shops/commission-summary` 重命名为 `GET /shops/fund-summary`，响应 DTO 由 `ShopCommissionSummaryItem` 改为 `ShopFundSummaryItem`，新增 `main_balance`、`main_frozen_balance` 两个字段 - **新增** `GET /shops/:id/main-wallet/transactions` — 预充值钱包流水列表（全新功能） - **新增** `GET /shops/:id/commission-stats` — 佣金统计，迁移自 `/my/commission-stats` - **新增** `GET /shops/:id/commission-daily-stats` — 每日佣金统计，迁移自 `/my/commission-daily-stats` - **新增** `POST /shops/:id/withdrawal-requests` — 发起提现申请，迁移自 `POST /my/withdrawal-requests` - **BREAKING 废弃** `/my/` 全部 6 个路由（详见废弃对照表） ### 废弃路由对照表 | 废弃路由 | 作用 | 替代路由 | 状态 | |---------|------|---------|------| | `GET /my/commission-summary` | 代理看自己的佣金钱包余额概览 | `GET /shops/fund-summary` | 本次改造 | | `GET /my/withdrawal-requests` | 代理看自己的提现申请记录 | `GET /shops/:id/withdrawal-requests` | 已有，直接复用 | | `GET /my/commission-records` | 代理看自己的每笔佣金入账明细（订单维度） | `GET /shops/:id/commission-records` | 已有，直接复用 | | `GET /my/commission-stats` | 代理看自己的佣金汇总统计（按时间段） | `GET /shops/:id/commission-stats` | 本次新增 | | `GET /my/commission-daily-stats` | 代理看自己的每日佣金金额趋势 | `GET /shops/:id/commission-daily-stats` | 本次新增 | | `POST /my/withdrawal-requests` | 代理发起提现申请 | `POST /shops/:id/withdrawal-requests` | 本次新增 | ### API 全景（变更前 vs 变更后） ``` 变更前 变更后 ───────────────────────────────────────────────────────────────────────── GET /shops/commission-summary → GET /shops/fund-summary ★ 改造+扩展 GET /shops/:id/withdrawal-requests GET /shops/:id/withdrawal-requests GET /shops/:id/commission-records GET /shops/:id/commission-records → GET /shops/:id/commission-stats ★ 新增 → GET /shops/:id/commission-daily-stats ★ 新增 → POST /shops/:id/withdrawal-requests ★ 新增 → GET /shops/:id/main-wallet/transactions ★ 新增 GET /my/commission-summary × 废弃 GET /my/withdrawal-requests × 废弃 GET /my/commission-records × 废弃 GET /my/commission-stats × 废弃 GET /my/commission-daily-stats × 废弃 POST /my/withdrawal-requests × 废弃 GET /agent-recharges GET /agent-recharges 不变 GET /agent-recharges/:id GET /agent-recharges/:id 不变 POST /agent-recharges POST /agent-recharges 不变 POST /agent-recharges/:id/offline-pay POST /agent-recharges/:id/offline-pay 不变 ``` ### 两个视角的完整操作流 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 平台人员 │ ├──────────────────────────────────────────────────────────────────┤ │ [代理商资金概况列表] │ │ GET /shops/fund-summary │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ 店铺名 │ 预充值余额 │ 可提现佣金 │ 冻结佣金 │ 提现中 │ │ │ │ 代理A │ ¥2,000 │ ¥500 │ ¥100 │ ¥200 │ │ │ │ 代理B │ ¥500 │ ¥200 │ ¥0 │ ¥0 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ 进入某代理详情 │ │ ▼ │ │ [代理详情 — 分 tab 查看] │ │ ├─ 预充值流水 GET /shops/:id/main-wallet/transactions │ │ ├─ 佣金明细 GET /shops/:id/commission-records │ │ ├─ 佣金统计 GET /shops/:id/commission-stats │ │ ├─ 每日统计 GET /shops/:id/commission-daily-stats │ │ └─ 提现记录 GET /shops/:id/withdrawal-requests │ │ │ │ [充值管理] │ │ GET /agent-recharges 查看所有充值订单（含状态） │ │ POST /agent-recharges/:id/offline-pay 确认线下到账 │ │ │ │ [提现审批] │ │ GET /commission/withdrawal-requests 审批提现申请 │ └──────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────┐ │ 代理账号（同接口，按数据权限过滤） │ ├──────────────────────────────────────────────────────────────────┤ │ [我的资金概况（返回自己 + 所有下级代理店铺）] │ │ GET /shops/fund-summary │ │ ┌──────────────────────────────────────────────────┐ │ │ │ 预充值余额: ¥2,000 │ 可提现佣金: ¥500 │ │ │ │ 冻结余额: ¥100 │ 提现中: ¥200 │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ [预充值钱包流水] │ │ GET /shops/自己ID/main-wallet/transactions │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 时间 │ 类型 │ 金额 │ 变动后余额 │ │ │ │ 04-08 10:00 │ 充值入账 │ +¥500 │ ¥2,000 │ │ │ │ 04-07 15:30 │ 套餐扣款 │ -¥100 │ ¥1,500 │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ [佣金相关] │ │ GET /shops/自己ID/commission-records 佣金明细 │ │ GET /shops/自己ID/commission-stats 佣金统计 │ │ GET /shops/自己ID/withdrawal-requests 提现记录 │ │ POST /shops/自己ID/withdrawal-requests 发起提现 │ │ │ │ [充值订单（GORM 自动过滤，只见自己的）] │ │ GET /agent-recharges │ └──────────────────────────────────────────────────────────────────┘ ``` ### 数据流向 ``` 【充值流】 平台操作 POST /agent-recharges ↓ tb_agent_recharge_record（充值订单，含状态：待支付/已完成/已取消） ↓ 线下确认 / 微信回调 tb_agent_wallet (wallet_type=main) balance + tb_agent_wallet_transaction (transaction_type=recharge) ↓ 代理购买套餐 tb_agent_wallet (wallet_type=main) balance - tb_agent_wallet_transaction (transaction_type=deduct) 【佣金流】 用户下单 → 佣金计算 → tb_commission_record（订单维度明细） ↓ 佣金入账 tb_agent_wallet (wallet_type=commission) balance + tb_agent_wallet_transaction (transaction_type=commission) ↓ 代理发起提现 POST /shops/:id/withdrawal-requests tb_commission_withdrawal_request（提现申请） ↓ 平台审批通过 tb_agent_wallet (wallet_type=commission) balance - tb_agent_wallet_transaction (transaction_type=withdrawal) ``` ## Capabilities ### New Capabilities - `agent-fund-summary`: 代理商资金概况接口，同一接口支持平台（全量）和代理（仅自己）两种视角，包含预充值余额与佣金钱包字段 - `main-wallet-transactions`: 代理预充值钱包（主钱包）流水查询，按 shop_id 分页检索 tb_agent_wallet_transaction（wallet_type=main） ### Modified Capabilities - `commission-record-query`: 佣金统计和每日统计从 `/my/` 路径迁移至 `/shops/:id/` 路径，同时新增 POST 提现发起路由；原 `/my/` 路径全部废弃 - `agent-wallet`: 资金概况接口现在对外暴露主钱包余额，`AgentWalletStore.GetShopCommissionSummaryBatch` 需扩展以批量拉取主钱包余额 ## Impact - **Handler 层**: 扩展 `ShopCommissionHandler`，新增 `ListFundSummary`、`ListMainWalletTransactions`、`GetCommissionStats`、`GetCommissionDailyStats`、`CreateWithdrawal` 五个方法；`MyCommissionHandler` 整体删除 - **Service 层**: `ShopCommissionService` 构造函数补两个依赖（`commissionWithdrawalSettingStore`、`agentWalletTransactionStore`），`ListShopCommissionSummary` 改造为 `ListShopFundSummary`，新增 `ListMainWalletTransactions`，并从 `MyCommissionService` 迁移 `GetStats / GetDailyStats / CreateWithdrawalRequest` 三个方法（签名改为显式 `shopID`，入口强制调用 `middleware.CanManageShop` 校验）；`MyCommissionService` 整体删除 - **Store 层**: `AgentWalletStore` 新增 `GetShopMainWalletBatch`；`AgentWalletTransactionStore` 新增 `ListByWalletIDWithFilters` / `CountByWalletID`，并删除原 `ListByShopID` / `CountByShopID`（全局无其他调用者，且会跨钱包类型返回数据，留着易被误用） - **DTO 层**: `ShopCommissionSummaryItem` → `ShopFundSummaryItem`（新增 `main_balance`、`main_frozen_balance`）；新增主钱包流水 DTO；删除 `/my/` 系列 DTO - **路由层**: 删除 `registerMyCommissionRoutes`，在 `registerShopCommissionRoutes` 内将 `/commission-summary` 改为 `/fund-summary`，并追加 4 条 `/:shop_id/...` 路由 - **权限层**: 所有迁移过来的 `/shops/:shop_id/...` 入口必须在 Service 层显式调用 `middleware.CanManageShop(ctx, shopID)`，同时覆盖本次新增接口和已有的 `ListShopWithdrawalRequests`、`ListShopCommissionRecords`（当前只做了店铺存在性检查，未做越权校验，迁移后代理只要猜到其他 shopID 就能读取，必须补齐） - **文档生成器**: `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 同步更新