yml/hfb_sys
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

后端提现增加

Browse Source
This commit is contained in:
yml
2026-06-06 10:08:39 +08:00
parent 082fd908e9
commit 8a2d2f2a18
15 changed files with 2763 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/提现功能API文档.md
+636
View File
@@ -0,0 +1,636 @@
# 提现功能 API 文档
## 目录
- [收款账号管理 API](#收款账号管理-api)
- [提现申请 API (用户端)](#提现申请-api-用户端)
- [提现管理 API (管理员端)](#提现管理-api-管理员端)
---
## 收款账号管理 API
### 1. 查询收款账号列表
**请求**
```
GET /api/payment-accounts?page=1&page_size=20
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"bank_branch": "",
"certificate_urls": ["https://..."],
"is_default": true,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 2. 查询收款账号详情
**请求**
```
GET /api/payment-accounts/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"bank_branch": "",
"certificate_urls": ["https://..."],
"is_default": true,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
### 3. 添加收款账号
**请求**
```
POST /api/payment-accounts
Authorization: Bearer {user_token}
Content-Type: application/json
{
"account_type": "alipay", // alipay | wechat | bank
"account_name": "张三", // 必须与实名认证姓名一致
"account_no": "13812345678", // 支付宝账号/微信号/银行卡号
"bank_name": "中国工商银行", // 银行卡必填
"bank_branch": "北京分行", // 银行卡可选
"certificate_urls": [ // 凭证截图（可选）
"https://..."
]
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"is_default": false,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "账户名必须与实名认证姓名一致"
}
```
```json
{
"code": 40002,
"message": "请先完成实名认证"
}
```
```json
{
"code": 40003,
"message": "收款账号数量已达上限（最多5个）"
}
```
### 4. 更新收款账号
**请求**
```
PUT /api/payment-accounts/:id
Authorization: Bearer {user_token}
Content-Type: application/json
{
"bank_branch": "北京朝阳支行",
"certificate_urls": ["https://..."]
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"account_type": "bank",
"account_name": "张三",
"account_no": "6222****1234",
"bank_name": "中国工商银行",
"bank_branch": "北京朝阳支行",
"is_default": false,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:05:00Z"
}
}
```
### 5. 删除收款账号
**请求**
```
DELETE /api/payment-accounts/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"deleted": true
}
}
```
### 6. 设置默认收款账号
**请求**
```
POST /api/payment-accounts/:id/set-default
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"updated": true
}
}
```
---
## 提现申请 API (用户端)
### 1. 创建提现申请
**请求**
```
POST /api/withdrawals
Authorization: Bearer {user_token}
Content-Type: application/json
{
"payment_account_id": 1,
"amount": 100.00
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "pending",
"review_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z",
"reviewed_at": null,
"paid_at": null
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "提现金额低于最小限额"
}
```
```json
{
"code": 40002,
"message": "提现金额超过最大限额"
}
```
```json
{
"code": 40003,
"message": "余额不足"
}
```
### 2. 查询提现列表
**请求**
```
GET /api/withdrawals?page=1&page_size=20
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "completed",
"review_remark": "审核通过",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:30:00Z",
"reviewed_at": "2026-06-06T10:10:00Z",
"paid_at": "2026-06-06T10:30:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 3. 查询提现详情
**请求**
```
GET /api/withdrawals/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "processing",
"review_remark": "审核通过",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:10:00Z",
"reviewed_at": "2026-06-06T10:10:00Z",
"paid_at": null
}
}
```
### 4. 取消提现申请
**请求**
```
POST /api/withdrawals/:id/cancel
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"cancelled": true
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "提现申请状态已锁定，无法操作"
}
```
---
## 提现管理 API (管理员端)
### 1. 查询提现列表
**请求**
```
GET /api/admin/withdrawals?status=pending&page=1&page_size=20
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:list
```
**查询参数**
- `status`: 状态筛选 (pending | processing | completed | rejected | cancelled)
- `user_id`: 用户ID筛选
- `page`: 页码
- `page_size`: 每页数量
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"user_nickname": "用户昵称",
"user_phone": "138****5678",
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"payment_account_id": 1,
"account_type": "alipay",
"account_name": "张三",
"account_no": "13812345678", // 管理员可见完整账号
"bank_name": "",
"bank_branch": "",
"status": "pending",
"reviewed_by": null,
"reviewed_by_name": "",
"reviewed_at": null,
"review_remark": "",
"paid_by": null,
"paid_by_name": "",
"paid_at": null,
"payment_proof_url": "",
"payment_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 2. 查询提现详情
**请求**
```
GET /api/admin/withdrawals/:id
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:detail
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"user_nickname": "用户昵称",
"user_phone": "13812345678",
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"payment_account_id": 1,
"account_type": "alipay",
"account_name": "张三",
"account_no": "13812345678",
"bank_name": "",
"bank_branch": "",
"status": "pending",
"reviewed_by": null,
"reviewed_by_name": "",
"reviewed_at": null,
"review_remark": "",
"paid_by": null,
"paid_by_name": "",
"paid_at": null,
"payment_proof_url": "",
"payment_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
### 3. 审核提现申请
**请求**
```
POST /api/admin/withdrawals/:id/review
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:review
Content-Type: application/json
{
"approved": true,
"remark": "审核通过"
}
```
**审核通过响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "processing",
"reviewed_by": 10,
"reviewed_by_name": "财务管理员",
"reviewed_at": "2026-06-06T10:10:00Z",
"review_remark": "审核通过",
...
}
}
```
**审核拒绝请求**
```json
{
"approved": false,
"remark": "账号信息不符"
}
```
**审核拒绝响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "rejected",
"reviewed_by": 10,
"reviewed_by_name": "财务管理员",
"reviewed_at": "2026-06-06T10:10:00Z",
"review_remark": "账号信息不符",
...
}
}
```
### 4. 确认打款
**请求**
```
POST /api/admin/withdrawals/:id/confirm-payment
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:pay
Content-Type: application/json
{
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
"remark": "已通过支付宝转账"
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "completed",
"paid_by": 10,
"paid_by_name": "财务管理员",
"paid_at": "2026-06-06T10:30:00Z",
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
"payment_remark": "已通过支付宝转账",
...
}
}
```
---
## 状态说明
### 提现状态 (status)
| 状态 | 说明 | 允许操作 |
|------|------|---------|
| `pending` | 待审核 | 用户可取消、管理员可审核 |
| `processing` | 处理中 | 管理员可确认打款 |
| `completed` | 已完成 | 无 |
| `rejected` | 已拒绝 | 无 |
| `cancelled` | 已取消 | 无 |
### 账号类型 (account_type)
| 类型 | 说明 |
|------|------|
| `alipay` | 支付宝 |
| `wechat` | 微信 |
| `bank` | 银行卡 |
---
## 错误码说明
| 错误码 | 说明 |
|--------|------|
| 40001 | 请求参数错误 |
| 40002 | 实名认证未通过 |
| 40003 | 账号数量限制 |
| 40004 | 提现金额错误 |
| 40005 | 余额不足 |
| 40006 | 状态锁定 |
| 40401 | 未找到资源 |
| 40301 | 未授权 |
| 50001 | 服务器错误 |
---
## 接口权限说明
### 用户端接口
所有用户端接口需要携带用户 Token (`Authorization: Bearer {user_token}`)
### 管理员端接口
所有管理员端接口需要：
1. 携带管理员 Token (`Authorization: Bearer {admin_token}`)
2. 拥有对应的权限
#### 提现管理权限列表
- `withdrawal:list` - 查看提现申请列表
- `withdrawal:detail` - 查看提现详情
- `withdrawal:review` - 审核提现申请
- `withdrawal:pay` - 确认打款
**财务角色 (finance)** 默认拥有以上所有权限。