# 提现功能 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)** 默认拥有以上所有权限。