soul-yongping/开发文档/8、部署/分销提现流程图.md

分销提现流程图

一、整体流程

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            小 程 序 端                                           │
└─────────────────────────────────────────────────────────────────────────────────┘

  [用户] 推广中心 → 可提现金额 ≥ 最低额 → 点击「申请提现」
       │
       ▼
  POST /api/miniprogram/withdraw  (WithdrawPost)
       │ 校验：可提现余额、最低金额、用户 openId
       ▼
  写入 withdrawals：status = pending
       │
       ▼
  提示「提现申请已提交，审核通过后将打款至您的微信零钱」

─────────────────────────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            管 理 端 (soul-admin)                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

  [管理员] 分销 / 提现审核 → GET /api/admin/withdrawals 拉列表
       │
       ├── 点「拒绝」 → PUT /api/admin/withdrawals { action: "reject" }
       │                    ▼
       │                status = failed，写 error_message
       │
       └── 点「通过」 → PUT /api/admin/withdrawals { action: "approve" }
                            │
                            ▼
                       调 wechat.InitiateTransferByFundApp (FundApp 单笔)
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
       [微信报错]      [未返回单号]      [成功受理]
            │               │               │
            ▼               ▼               ▼
       status=failed   status=failed   status=processing
       返回报错信息     返回提示         写 detail_no,batch_no,batch_id
                                       返回「已发起打款，微信处理中」

─────────────────────────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            微 信 侧 与 回 调                                       │
└─────────────────────────────────────────────────────────────────────────────────┘

  微信异步打款
       │
       ▼
  打款结果 → POST /api/payment/wechat/transfer/notify (PaymentWechatTransferNotify)
       │ 验签、解密，得到 out_bill_no / transfer_bill_no / state / fail_reason
       │ 用 detail_no = out_bill_no 找到提现记录，且仅当 status 为 processing / pending_confirm 时更新
       ▼
  state=SUCCESS  → status = success
  state=FAIL/CANCELLED → status = failed，写 fail_reason

─────────────────────────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            可 选：主 动 同 步                                      │
└─────────────────────────────────────────────────────────────────────────────────┘

  管理端 POST /api/admin/withdrawals/sync（可带 id 同步单条，或不带 id 同步所有）
       │ 只处理 status IN (processing, pending_confirm)
       │ FundApp 单笔：用 detail_no 调 QueryTransferByOutBill
       ▼
  按微信返回的 state 更新 status = success / failed（与回调逻辑一致）

─────────────────────────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            小 程 序「我 的」- 待 确 认 收 款                        │
└─────────────────────────────────────────────────────────────────────────────────┘

  [用户] 我的页 → 仅登录显示「待确认收款」区块
       │
       ▼
  GET /api/miniprogram/withdraw/pending-confirm?userId=xxx  (WithdrawPendingConfirm)
       │ 只返回 status IN (processing, pending_confirm) 的提现（审核通过后的）
       ▼
  展示列表：金额、日期、「确认收款」按钮
       │
       ▼
  点击「确认收款」→ 需要 item.package + mchId + appId 调 wx.requestMerchantTransfer
       │ 当前后端 list 里 package 为空，故会提示「请稍后刷新再试」
       └─ 若后续接入微信返回的 package，可在此完成「用户确认收款」闭环

二、状态流转

阶段	状态 (status)	含义
用户申请	pending	待审核，已占可提现额度
管理员通过	processing	已发起打款，微信处理中
微信回调成功	success	打款成功（已到账）
微信回调失败/拒绝	failed	打款失败，写 fail_reason
预留	pending_confirm	待用户确认收款（当前流程未改此状态，仅接口可返回）

三、可提现与待确认口径

• 可提现 = 累计佣金 − 已提现 − 待审核金额
  待审核金额 = 所有 status 为 pending、processing、pending_confirm 的提现金额之和。
• 待确认收款列表：仅包含 审核已通过 的提现，即 status 为 processing 或 pending_confirm，不包含 pending。

四、主要接口与代码位置

环节	接口/行为	代码位置
用户申请	POST /api/miniprogram/withdraw	soul-api internal/handler/withdraw.go WithdrawPost
可提现计算	referral/data、withdraw 校验	withdraw.go computeAvailableWithdraw；referral.go 提现统计
管理端列表	GET /api/admin/withdrawals	internal/handler/admin_withdrawals.go AdminWithdrawalsList
管理端通过/拒绝	PUT /api/admin/withdrawals	admin_withdrawals.go AdminWithdrawalsAction
微信打款	FundApp 单笔	soul-api internal/wechat/transfer.go InitiateTransferByFundApp
微信回调	POST /api/payment/wechat/transfer/notify	internal/handler/payment.go PaymentWechatTransferNotify
管理端同步	POST /api/admin/withdrawals/sync	admin_withdrawals.go AdminWithdrawalsSync
待确认列表	GET /api/miniprogram/withdraw/pending-confirm	withdraw.go WithdrawPendingConfirm

五、说明

• 当前实现：审核通过后直接调微信 FundApp 单笔打款，最终由微信回调或管理端同步把状态更新为 success/failed。
• 「待确认收款」列表只展示已审核通过的记录；点击「确认收款」需后端下发的 package 才能调起 wx.requestMerchantTransfer，目前该字段为空，前端会提示「请稍后刷新再试」。若后续接入微信返回的 package，可在此完成用户确认收款闭环。