soul-yongping/分销提现流程图.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，可在此完成用户确认收款闭环。