145 lines
3.4 KiB
Markdown
145 lines
3.4 KiB
Markdown
# 提现接口文档
|
||
|
||
## 基础信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 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），调用会返回空响应。
|
||
|
||
---
|