18 KiB
前端接口变更通知
背景 & 原因
平台需要展示代理的**预充值钱包（主钱包）**余额与流水，原来这部分数据完全不可见。同时，代理的佣金相关接口散落在 /my/ 路径下，与平台统一的 /shops/:id/ 资源路径存在职责重叠，本次统一收拢到 /shops/ 下。
一、BREAKING CHANGE — 必须迁移
- 概况列表接口改造
┌──────────────┬──────────────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────┐ │ │ 旧 │ 新 │ ├──────────────┼──────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ 路径 │ GET /api/admin/shops/commission-summary │ GET /api/admin/shops/fund-summary │ ├──────────────┼──────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ 入参 │ 完全相同（page, page_size, shop_name, username） │ 无变化 │ ├──────────────┼──────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ 响应新增字段 │ — │ main_balance（预充值余额，分）main_frozen_balance（预充值冻结余额，分） │ ├──────────────┼──────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ 响应删除字段 │ — │ 无 │ └──────────────┴──────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────┘
旧响应 items 字段（已废弃 DTO ShopCommissionSummaryItem）→ 新 DTO ShopFundSummaryItem：
{ "shop_id": 1, "shop_name": "代理A", "shop_code": "A001", "username": "agent_a", "phone": "138xxxx",
- "main_balance": 200000, // 新增：预充值钱包余额（分）
- "main_frozen_balance": 0, // 新增：预充值冻结余额（分，当前均为0） "total_commission": 50000, "withdrawn_commission": 10000, "unwithdraw_commission": 30000, "frozen_commission": 5000, "withdrawing_commission": 5000, "available_commission": 30000, "created_at": "2025-01-01T00:00:00Z" }
▎ 操作：把所有调用 /commission-summary 的地方改为 /fund-summary，同时在 UI 上新增"预充值余额"列。
- 废弃的 /my/ 接口 — 全部删除，必须切换
┌────────────────────────────────┬─────────────────────────────────────────────┬─────────────────────────────────────────────┐ │ 废弃路由 │ 替代路由 │ 变化 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ GET /my/commission-summary │ GET /shops/fund-summary │ 见上方，返回结构有变化 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ GET /my/withdrawal-requests │ GET /shops/{shop_id}/withdrawal-requests │ 入参、响应完全一致，只需把 shop_id 放进路径 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ GET /my/commission-records │ GET /shops/{shop_id}/commission-records │ 入参、响应完全一致，只需把 shop_id 放进路径 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ GET /my/commission-stats │ GET /shops/{shop_id}/commission-stats │ 见下方详情 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ GET /my/commission-daily-stats │ GET /shops/{shop_id}/commission-daily-stats │ 见下方详情 │ ├────────────────────────────────┼─────────────────────────────────────────────┼─────────────────────────────────────────────┤ │ POST /my/withdrawal-requests │ POST /shops/{shop_id}/withdrawal-requests │ 见下方详情 │ └────────────────────────────────┴─────────────────────────────────────────────┴─────────────────────────────────────────────┘
▎ 旧 /my/ 接口已从服务端完全删除，调用会 404。
二、新增接口详情
GET /api/admin/shops/{shop_id}/commission-stats
替代 GET /my/commission-stats
入参（Query）：
┌────────────┬────────┬──────────────────┐ │ 参数 │ 类型 │ 说明 │ ├────────────┼────────┼──────────────────┤ │ start_time │ string │ 开始时间（可选） │ ├────────────┼────────┼──────────────────┤ │ end_time │ string │ 结束时间（可选） │ └────────────┴────────┴──────────────────┘
▎ 旧接口的 shop_id query 参数已去掉，改为路径参数 {shop_id}
响应（无变化）： { "total_amount": 50000, "cost_diff_amount": 30000, "one_time_amount": 20000, "cost_diff_percent": 600, "one_time_percent": 400, "total_count": 15, "cost_diff_count": 10, "one_time_count": 5 }
GET /api/admin/shops/{shop_id}/commission-daily-stats
替代 GET /my/commission-daily-stats
入参（Query）：
┌────────────┬────────┬───────────────────────────────────┐ │ 参数 │ 类型 │ 说明 │ ├────────────┼────────┼───────────────────────────────────┤ │ start_date │ string │ 开始日期 YYYY-MM-DD（可选） │ ├────────────┼────────┼───────────────────────────────────┤ │ end_date │ string │ 结束日期 YYYY-MM-DD（可选） │ ├────────────┼────────┼───────────────────────────────────┤ │ days │ int │ 查询天数，默认30，最大365（可选） │ └────────────┴────────┴───────────────────────────────────┘
响应（无变化）： [ { "date": "2025-04-08", "total_amount": 10000, "total_count": 3 }, { "date": "2025-04-07", "total_amount": 5000, "total_count": 2 } ]
POST /api/admin/shops/{shop_id}/withdrawal-requests
替代 POST /my/withdrawal-requests
Body（无变化）： { "amount": 10000, "withdrawal_method": "alipay", "account_name": "张三", "account_number": "138xxxx" }
权限变化（重要）：
- 仅代理账号可调用，平台账号调用返回 403 仅代理商用户可发起提现
- 只能为自己的 shop_id 提现，topLevel 代理不能替下级提现，否则返回 403 仅可为本人店铺发起提现
GET /api/admin/shops/{shop_id}/main-wallet/transactions ✨ 全新
预充值钱包流水列表（此前无此功能）
入参（Query）：
┌──────────────────┬────────┬────────────────────────────────────────────────────────────────────────┐ │ 参数 │ 类型 │ 说明 │ ├──────────────────┼────────┼────────────────────────────────────────────────────────────────────────┤ │ page │ int │ 页码，默认1 │ ├──────────────────┼────────┼────────────────────────────────────────────────────────────────────────┤ │ page_size │ int │ 每页数量，默认20，最大100 │ ├──────────────────┼────────┼────────────────────────────────────────────────────────────────────────┤ │ transaction_type │ string │ 交易类型过滤：recharge（充值入账）/ deduct（套餐扣款）/ refund（退款） │ ├──────────────────┼────────┼────────────────────────────────────────────────────────────────────────┤ │ start_date │ string │ 开始日期 YYYY-MM-DD │ ├──────────────────┼────────┼────────────────────────────────────────────────────────────────────────┤ │ end_date │ string │ 结束日期 YYYY-MM-DD │ └──────────────────┴────────┴────────────────────────────────────────────────────────────────────────┘
响应： { "items": [ { "id": 1, "transaction_type": "recharge", "transaction_subtype": "", "amount": 50000, "balance_before": 150000, "balance_after": 200000, "remark": "线下充值", "created_at": "2025-04-08T10:00:00Z" } ], "total": 3, "page": 1, "size": 20 }
▎ amount 正数为入账，负数为扣款，单位：分
三、数据权限说明（前端需了解）
两种角色访问同一套接口，后端自动过滤数据：
┌──────────┬─────────────────────────┬──────────────────────────────────────────┐ │ 角色 │ /shops/fund-summary │ /shops/{shop_id}/... │ ├──────────┼─────────────────────────┼──────────────────────────────────────────┤ │ 平台账号 │ 返回所有代理店铺 │ 可查任意 shop_id │ ├──────────┼─────────────────────────┼──────────────────────────────────────────┤ │ 代理账号 │ 返回自己 + 所有下级店铺 │ 只能查自己和下级的 shop_id，其他返回 403 │ └──────────┴─────────────────────────┴──────────────────────────────────────────┘
提现操作额外限制：代理账号只能为自己的 shop_id 发起提现，即使是上级代理也不能替下级操作。
四、变更全景图
变更前 变更后 ────────────────────────────────────────────────────────────────────── 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 /shops/commission-summary → 改为 GET /shops/fund-summary，UI 新增"预充值余额"列
- 代理侧"我的余额概览"调用改为 GET /shops/fund-summary（不再有独立的 /my/commission-summary）
- 代理侧"提现记录"改为 GET /shops/{自己shopID}/withdrawal-requests
- 代理侧"佣金明细"改为 GET /shops/{自己shopID}/commission-records
- 代理侧"佣金统计"改为 GET /shops/{自己shopID}/commission-stats（去掉 query 里的 shop_id）
- 代理侧"每日统计"改为 GET /shops/{自己shopID}/commission-daily-stats（去掉 query 里的 shop_id）
- 代理侧"发起提现"改为 POST /shops/{自己shopID}/withdrawal-requests（shop_id 进路径，body 不变）
- 新建"预充值钱包流水"页面，调用 GET /shops/{shopID}/main-wallet/transactions
\