487 lines
13 KiB
Markdown
487 lines
13 KiB
Markdown
# 提现管理后台接口文档
|
||
|
||
## 接口列表
|
||
|
||
| 接口地址 | 请求方法 | 说明 |
|
||
|---------|---------|------|
|
||
| `/withdraw/get` | POST | 获取提现申请详情 |
|
||
| `/withdraw/list` | POST | 获取提现申请列表（支持按状态筛选） |
|
||
| `/withdraw/user_list` | POST | 获取用户的提现申请列表 |
|
||
| `/withdraw/audit` | POST | 审核提现申请 |
|
||
|
||
**注意：**
|
||
- 所有接口都需要管理员权限（需要 `mw.CheckAdmin` 中间件验证）
|
||
- 这些接口操作的是 `withdraw_applications` 集合（用户申请的提现）
|
||
- 用户在前端申请提现后，后台管理员通过这些接口进行审核
|
||
|
||
---
|
||
|
||
## 1. 获取提现申请详情
|
||
|
||
**接口地址**: `/withdraw/get`
|
||
|
||
**请求方法**: `POST`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"withdrawID": "string" // 提现申请ID（必填）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"withdraw": {
|
||
"id": "string", // 提现申请ID
|
||
"userID": "string", // 用户ID
|
||
"amount": 10000, // 提现金额（单位：分）
|
||
"withdrawAccount": "string", // 提现账号
|
||
"status": 1, // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
|
||
"auditorID": "string", // 审核人ID（管理员ID）
|
||
"auditTime": 1699000000000, // 审核时间（毫秒时间戳）
|
||
"auditRemark": "string", // 审核备注
|
||
"ip": "string", // 申请IP
|
||
"deviceID": "string", // 设备ID
|
||
"platform": "string", // 平台（iOS、Android、Web等）
|
||
"deviceModel": "string", // 设备型号
|
||
"deviceBrand": "string", // 设备品牌
|
||
"osVersion": "string", // 操作系统版本
|
||
"appVersion": "string", // 应用版本
|
||
"createTime": 1699000000000, // 创建时间（毫秒时间戳）
|
||
"updateTime": 1699000000000 // 更新时间（毫秒时间戳）
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明**:
|
||
|
||
| 状态值 | 状态名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 1 | 待审核 | 用户已提交申请，等待审核 |
|
||
| 2 | 已通过 | 审核通过，提现成功（余额已在申请时扣除） |
|
||
| 3 | 已拒绝 | 审核拒绝，余额已退回 |
|
||
| 4 | 处理中 | 审核通过后，正在处理中 |
|
||
| 5 | 已完成 | 提现已完成 |
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | applicationID is required | 提现申请ID不能为空 |
|
||
| 404 | 记录不存在 | 提现申请不存在 |
|
||
| 401 | 无权限 | 需要管理员权限 |
|
||
|
||
---
|
||
|
||
## 2. 获取提现申请列表（支持按状态筛选）
|
||
|
||
**接口地址**: `/withdraw/list`
|
||
|
||
**请求方法**: `POST`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"status": 1, // 状态筛选（可选）：0-全部，1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成。默认为0（全部）
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码（必填，从1开始）
|
||
"showNumber": 10 // 每页数量（必填）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数
|
||
"list": [
|
||
{
|
||
"id": "string", // 提现申请ID
|
||
"userID": "string", // 用户ID
|
||
"amount": 10000, // 提现金额（单位：分）
|
||
"withdrawAccount": "string", // 提现账号
|
||
"status": 1, // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
|
||
"auditorID": "string", // 审核人ID（管理员ID）
|
||
"auditTime": 1699000000000, // 审核时间（毫秒时间戳）
|
||
"auditRemark": "string", // 审核备注
|
||
"ip": "string", // 申请IP
|
||
"deviceID": "string", // 设备ID
|
||
"platform": "string", // 平台（iOS、Android、Web等）
|
||
"deviceModel": "string", // 设备型号
|
||
"deviceBrand": "string", // 设备品牌
|
||
"osVersion": "string", // 操作系统版本
|
||
"appVersion": "string", // 应用版本
|
||
"createTime": 1699000000000, // 创建时间（毫秒时间戳）
|
||
"updateTime": 1699000000000 // 更新时间（毫秒时间戳）
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
// 获取所有提现申请
|
||
{
|
||
"status": 0,
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}
|
||
|
||
// 获取待审核的提现申请
|
||
{
|
||
"status": 1,
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}
|
||
|
||
// 获取已通过的提现申请
|
||
{
|
||
"status": 2,
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | invalid request | 请求参数格式错误 |
|
||
| 401 | 无权限 | 需要管理员权限 |
|
||
|
||
---
|
||
|
||
## 3. 获取用户的提现申请列表
|
||
|
||
**接口地址**: `/withdraw/user_list`
|
||
|
||
**请求方法**: `POST`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"userID": "string", // 用户ID（必填）
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码（必填，从1开始）
|
||
"showNumber": 10 // 每页数量（必填）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 10, // 总数
|
||
"list": [
|
||
{
|
||
"id": "string", // 提现申请ID
|
||
"userID": "string", // 用户ID
|
||
"amount": 10000, // 提现金额（单位：分）
|
||
"withdrawAccount": "string", // 提现账号
|
||
"status": 1, // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
|
||
"auditorID": "string", // 审核人ID（管理员ID）
|
||
"auditTime": 1699000000000, // 审核时间（毫秒时间戳）
|
||
"auditRemark": "string", // 审核备注
|
||
"ip": "string", // 申请IP
|
||
"deviceID": "string", // 设备ID
|
||
"platform": "string", // 平台（iOS、Android、Web等）
|
||
"deviceModel": "string", // 设备型号
|
||
"deviceBrand": "string", // 设备品牌
|
||
"osVersion": "string", // 操作系统版本
|
||
"appVersion": "string", // 应用版本
|
||
"createTime": 1699000000000, // 创建时间（毫秒时间戳）
|
||
"updateTime": 1699000000000 // 更新时间（毫秒时间戳）
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | userID is required | 用户ID不能为空 |
|
||
| 400 | invalid request | 请求参数格式错误 |
|
||
| 401 | 无权限 | 需要管理员权限 |
|
||
|
||
---
|
||
|
||
## 4. 批量审核提现申请
|
||
|
||
**接口地址**: `/withdraw/audit`
|
||
|
||
**请求方法**: `POST`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"withdrawIDs": ["string", "string"], // 提现申请ID列表（必填，支持批量审核）
|
||
"status": 2, // 审核状态（必填）：2-已通过，3-已拒绝
|
||
"auditRemark": "string" // 审核备注（可选）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"successCount": 5, // 成功审核的数量
|
||
"failCount": 2, // 失败审核的数量
|
||
"failedIDs": ["id1", "id2"] // 失败的提现申请ID列表
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明**:
|
||
|
||
| 状态值 | 状态名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 2 | 已通过 | 审核通过，提现成功（余额已在用户申请时扣除，无需额外操作） |
|
||
| 3 | 已拒绝 | 审核拒绝，系统会自动将余额退回用户钱包，并创建退款记录 |
|
||
|
||
**业务逻辑**:
|
||
|
||
1. 验证必填字段（提现申请ID列表、审核状态）
|
||
2. 验证审核状态必须是2（通过）或3（拒绝）
|
||
3. **批量处理每个提现申请**：
|
||
- 检查提现申请是否存在
|
||
- 检查提现申请状态，允许"待审核"和"已通过"状态的提现申请被审核（已通过的提现申请可以重新审核为拒绝）
|
||
- 更新提现申请状态和审核信息
|
||
- **如果审核拒绝**：
|
||
- 自动将提现金额退回用户钱包（包括从"待审核"改为"已拒绝"，或从"已通过"改为"已拒绝"）
|
||
- 创建一条类型为"退款"的余额变动记录
|
||
- 备注为"提现审核拒绝，退回余额"
|
||
4. 返回成功和失败的数量，以及失败的ID列表
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | withdrawIDs is required and cannot be empty | 提现申请ID列表不能为空 |
|
||
| 400 | status must be 2 (approved) or 3 (rejected) | 审核状态必须是2或3 |
|
||
| 401 | 无权限 | 需要管理员权限 |
|
||
|
||
**注意**：
|
||
- 批量审核时，部分成功部分失败是正常的
|
||
- 失败的提现申请会在 `failedIDs` 中返回
|
||
- 失败的常见原因：
|
||
- 提现申请不存在
|
||
- 提现申请状态不是"待审核"或"已通过"
|
||
- 更新状态时出错
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
// 批量审核通过
|
||
{
|
||
"withdrawIDs": ["xxx-xxx-xxx-1", "xxx-xxx-xxx-2", "xxx-xxx-xxx-3"],
|
||
"status": 2,
|
||
"auditRemark": "批量审核通过，已打款"
|
||
}
|
||
|
||
// 批量审核拒绝
|
||
{
|
||
"withdrawIDs": ["xxx-xxx-xxx-1", "xxx-xxx-xxx-2"],
|
||
"status": 3,
|
||
"auditRemark": "提现账号信息有误，已拒绝"
|
||
}
|
||
|
||
// 单个审核（也支持）
|
||
{
|
||
"withdrawIDs": ["xxx-xxx-xxx"],
|
||
"status": 2,
|
||
"auditRemark": "审核通过，已打款"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
// 全部成功
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"successCount": 3,
|
||
"failCount": 0,
|
||
"failedIDs": []
|
||
}
|
||
}
|
||
|
||
// 部分成功
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"successCount": 2,
|
||
"failCount": 1,
|
||
"failedIDs": ["xxx-xxx-xxx-3"] // 这个ID可能不存在或状态不对
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 分页参数说明
|
||
|
||
所有列表接口都使用统一的分页参数格式：
|
||
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码，从1开始
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
}
|
||
```
|
||
|
||
### 时间戳说明
|
||
|
||
所有时间字段都是毫秒时间戳（Unix timestamp in milliseconds），例如：
|
||
- `1699000000000` 表示 `2023-11-03 12:00:00`（UTC时间）
|
||
|
||
### 金额单位说明
|
||
|
||
所有金额字段的单位都是**分**（cent），例如：
|
||
- `10000` 表示 `100.00` 元
|
||
- `100` 表示 `1.00` 元
|
||
|
||
### 权限说明
|
||
|
||
所有接口都需要管理员权限，需要在请求头中携带有效的管理员 token。
|
||
|
||
### 响应格式说明
|
||
|
||
所有接口都遵循统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0表示成功
|
||
"errMsg": "", // 错误信息
|
||
"errDlt": "", // 错误详情
|
||
"data": {} // 响应数据
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口调用示例
|
||
|
||
### 示例1：获取待审核的提现申请列表
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/withdraw/list \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-admin-token" \
|
||
-d '{
|
||
"status": 1,
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 示例2：批量审核提现申请（通过）
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/withdraw/audit \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-admin-token" \
|
||
-d '{
|
||
"withdrawIDs": ["withdraw-123", "withdraw-124", "withdraw-125"],
|
||
"status": 2,
|
||
"auditRemark": "批量审核通过，已打款"
|
||
}'
|
||
```
|
||
|
||
### 示例3：批量审核提现申请（拒绝）
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/withdraw/audit \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-admin-token" \
|
||
-d '{
|
||
"withdrawIDs": ["withdraw-123", "withdraw-124"],
|
||
"status": 3,
|
||
"auditRemark": "提现账号信息有误，已拒绝"
|
||
}'
|
||
```
|
||
|
||
### 示例4：单个审核（也支持）
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/withdraw/audit \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-admin-token" \
|
||
-d '{
|
||
"withdrawIDs": ["withdraw-123"],
|
||
"status": 2,
|
||
"auditRemark": "审核通过，已打款"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 状态流转图
|
||
|
||
```
|
||
待审核 (1)
|
||
├─ 审核通过 (2) → 已通过（余额已在用户申请时扣除，无需额外操作）
|
||
│ ├─ 重新审核拒绝 (3) → 已拒绝（余额自动退回用户钱包）
|
||
│ └─ 处理中 (4) → 已完成 (5)
|
||
└─ 审核拒绝 (3) → 已拒绝（余额自动退回用户钱包）
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **用户申请提现**：用户在前端申请提现时，余额会立即扣除，创建提现申请记录
|
||
2. **后台审核**：管理员通过后台接口审核用户的提现申请，支持批量审核
|
||
3. **批量审核**：可以一次审核多个提现申请，返回成功和失败的数量
|
||
4. **审核通过**：余额已在用户申请时扣除，审核通过时无需额外操作
|
||
5. **审核拒绝**：审核拒绝时会自动退回余额到用户钱包，并创建退款记录（包括从"已通过"改为"已拒绝"的情况）
|
||
6. **状态检查**：允许"待审核"和"已通过"状态的提现申请被审核，已通过的提现申请可以重新审核为拒绝
|
||
7. **部分失败处理**：批量审核时，部分成功部分失败是正常的，失败的ID会在响应中返回
|
||
8. **金额单位**：所有金额都以"分"为单位，前端显示时需要除以100
|
||
9. **数据来源**：所有接口操作的都是 `withdraw_applications` 集合（用户申请的提现），不是 `withdraws` 集合
|