# 提现接口文档

## 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `/v1/public/user` |
| 认证方式 | JWT Token（`AuthMiddleware` + `DeviceMiddleware`） |
| 数据表 | `user_withdrawal` |

## 数据模型

### user_withdrawal 表

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int64 | 主键 |
| `user_id` | int64 | 用户 ID |
| `amount` | int64 | 提现金额（单位：分） |
| `content` | text | 收款信息（账号、姓名等） |
| `status` | tinyint | 0=待审核, 1=已通过, 2=已拒绝 |
| `reason` | varchar(500) | 拒绝原因（通过时为空） |
| `created_at` | datetime | 创建时间 |
| `updated_at` | datetime | 更新时间 |

### status 枚举

| 值 | 含义 | 说明 |
|----|------|------|
| 0 | Pending（待审核） | 用户提交申请后的初始状态 |
| 1 | Approved（已通过） | 管理员审核通过，佣金已扣减 |
| 2 | Rejected（已拒绝） | 管理员拒绝，无需退款（申请时未扣款） |

---

## 用户端接口

### 1. 申请提现

申请佣金提现，创建一条待审核记录。申请时**不扣余额**，管理员审核通过后才扣。

```
POST /v1/public/user/commission_withdraw
```

#### 请求体

```json
{
  "amount": 1000,
  "content": "支付宝：138xxxx1234 / 张三"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `amount` | int64 | 是 | 提现金额（单位：分） |
| `content` | string | 是 | 收款信息（支付宝/银行卡等） |

#### 成功响应

```json
{
  "data": {
    "id": 1,
    "user_id": 10001,
    "amount": 1000,
    "content": "支付宝：138xxxx1234 / 张三",
    "status": 0,
    "reason": "",
    "created_at": 1716624000000,
    "updated_at": 1716624000000
  }
}
```

> **注意**：此接口的 `created_at` / `updated_at` 返回**毫秒级**时间戳（`.UnixMilli()`），与项目其他接口的秒级时间戳不一致。

#### 业务逻辑

1. 查询该用户所有 status=0（待审核）的提现记录，求和得 `pendingTotal`
2. 校验可用余额：`commission >= amount + pendingTotal`
3. 创建 `user_withdrawal` 记录，status=0
4. **不扣减** `user.commission`，等审核通过才扣

#### 错误码

| 错误码 | 常量 | 说明 |
|--------|------|------|
| 20010 | `UserCommissionNotEnough` | 可用余额不足（余额 = commission - 所有 pending 提现总额） |
| 40005 | `InvalidAccess` | 未登录 / Token 无效 |

#### 源码位置

- Handler: `internal/handler/public/user/commissionWithdrawHandler.go`
- Logic: `internal/logic/public/user/commissionWithdrawLogic.go`

---

### 2. 查询提现记录

分页查询当前用户的提现记录。

```
GET /v1/public/user/withdrawal_log
```

#### 请求参数（Query）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `page` | int | 否 | 页码 |
| `size` | int | 否 | 每页数量 |

#### 成功响应

```json
{
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 10001,
        "amount": 1000,
        "content": "支付宝：138xxxx1234",
        "status": 0,
        "reason": "",
        "created_at": 1716624000,
        "updated_at": 1716624000
      }
    ],
    "total": 1
  }
}
```

#### 源码位置

- Handler: `internal/handler/public/user/queryWithdrawalLogHandler.go`
- Logic: `internal/logic/public/user/queryWithdrawalLogLogic.go`

> **Warning**: Logic 层尚未实现（仍为 TODO），调用会返回空响应。

---