Appearance
withdrawal — 提现审批（6 action）
前缀：
/api/v1/admin/withdrawal/权限：WITHDRAWAL_READ（list/detail）·WITHDRAWAL_APPROVE（approve/reject/payout/recall）— 仅 super + operator，it 一律 403 代码：src/app/admin/interface/api/withdrawal_mgmt.py+application/usecase/withdrawal_mgmt.py
3.6.1 list —— 提现列表
GET /api/v1/admin/withdrawal/list · 权限 WITHDRAWAL_READ
Query 参数：
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
page | int | ⬜ | 1 | ≥1 |
page_size | int | ⬜ | 20 | 1~100 |
status | string | ⬜ | — | 提现状态过滤 |
user_id | string | ⬜ | — | 按用户过滤 |
date_from / date_to | string | ⬜ | — | ISO 日期区间 |
响应 data：{ total, page, page_size, items: [WithdrawalSummary] }
WithdrawalSummary 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
id / user_id | string | 提现单 / 用户 |
amount | float | 金额 |
status | string | pending | approved | rejected | paid | recalled |
payment_reference | string | null | 打款凭证号 |
payment_channel | string | null | 打款渠道 |
created_at / updated_at | string | ISO |
错误码：40201001 page/page_size < 1。
3.6.2 detail —— 提现详情
GET /api/v1/admin/withdrawal/detail/{withdrawal_id} · 权限 WITHDRAWAL_READ
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
withdrawal | object | 全字段 |
user | object | 用户摘要 |
bank_info | object | 收款信息 |
audit_trail | array | 审批轨迹 |
错误码：40201401（404）提现单不存在。
3.6.3 approve —— 审批通过
POST /api/v1/admin/withdrawal/approve · 权限 WITHDRAWAL_APPROVE
请求 body：{ withdrawal_id✅, note? }
响应 data：{ "success": true, "approved_at": "<ISO>" }
错误码：40201401（404）· 40201402 状态不允许审批（含重复审批）· 40201001 参数非法。
3.6.4 reject —— 审批拒绝
POST /api/v1/admin/withdrawal/reject · 权限 WITHDRAWAL_APPROVE
请求 body：{ withdrawal_id✅, reason✅, note? }
响应 data：{ "success": true }
错误码：40201401（404）· 40201402 状态不允许 · 40201001 reason 缺失。
3.6.5 payout —— 打款（⚠️ 最敏感）
POST /api/v1/admin/withdrawal/payout · 权限 WITHDRAWAL_APPROVE · confirm_text = "PAYOUT"
请求 body：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
withdrawal_id | string | ✅ | 提现单 |
payment_reference | string | ✅ | 打款凭证号（银行/渠道流水号） |
confirm_text | string | ✅ | 必须逐字为 "PAYOUT"，否则 40201001（400） |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 恒 true |
paid_at | string | ISO 打款时间 |
payment_channel | string | 打款渠道 |
错误码：
| code | 场景 |
|---|---|
40201401 | 提现单不存在（404） |
40201402 | 状态不允许打款 |
40201403 | 重复打款（DUPLICATE_PAYOUT） |
40201404 | 支付渠道故障 |
40201405 | 银行账户信息不一致 |
40201406 | 单日打款金额超上限 |
40201001 | confirm_text 不匹配 / payment_reference 缺失 |
3.6.6 recall —— 追回
POST /api/v1/admin/withdrawal/recall · 权限 WITHDRAWAL_APPROVE
请求 body：{ withdrawal_id✅, reason✅ }
响应 data：{ "success": true, "recalled_at": "<ISO>" }
错误码：40201401（404）· 40201402 状态不允许 · 40201001 参数非法。
本域错误码汇总：40201401-40201406（§6.6）。验收链路（§7.5）：approve → payout → notification。通用失败见 admin 总览。