Files

kim.dev.6789 b7f8db7d08 复制项目

2026-01-14 22:35:45 +08:00

13 KiB

Raw Blame History

提现管理后台接口文档

接口列表

接口地址	请求方法	说明
`/withdraw/get`	POST	获取提现申请详情
`/withdraw/list`	POST	获取提现申请列表（支持按状态筛选）
`/withdraw/user_list`	POST	获取用户的提现申请列表
`/withdraw/audit`	POST	审核提现申请

注意：

所有接口都需要管理员权限（需要 mw.CheckAdmin 中间件验证）
这些接口操作的是 withdraw_applications 集合（用户申请的提现）
用户在前端申请提现后，后台管理员通过这些接口进行审核

1. 获取提现申请详情

接口地址: /withdraw/get

请求方法: POST

请求参数:

{
  "withdrawID": "string"  // 提现申请ID（必填）
}

响应参数:

{
  "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

请求参数:

{
  "status": 1,  // 状态筛选（可选）：0-全部，1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成。默认为0（全部）
  "pagination": {
    "pageNumber": 1,   // 页码（必填，从1开始）
    "showNumber": 10   // 每页数量（必填）
  }
}

响应参数:

{
  "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  // 更新时间（毫秒时间戳）
      }
    ]
  }
}

请求示例:

// 获取所有提现申请
{
  "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

请求参数:

{
  "userID": "string",  // 用户ID（必填）
  "pagination": {
    "pageNumber": 1,   // 页码（必填，从1开始）
    "showNumber": 10   // 每页数量（必填）
  }
}

响应参数:

{
  "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

请求参数:

{
  "withdrawIDs": ["string", "string"],  // 提现申请ID列表（必填，支持批量审核）
  "status": 2,                          // 审核状态（必填）：2-已通过，3-已拒绝
  "auditRemark": "string"               // 审核备注（可选）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "successCount": 5,              // 成功审核的数量
    "failCount": 2,                 // 失败审核的数量
    "failedIDs": ["id1", "id2"]     // 失败的提现申请ID列表
  }
}

状态说明:

状态值	状态名称	说明
2	已通过	审核通过，提现成功（余额已在用户申请时扣除，无需额外操作）
3	已拒绝	审核拒绝，系统会自动将余额退回用户钱包，并创建退款记录

业务逻辑:

验证必填字段（提现申请ID列表、审核状态）
验证审核状态必须是2（通过）或3（拒绝）
批量处理每个提现申请：
- 检查提现申请是否存在
- 检查提现申请状态，允许"待审核"和"已通过"状态的提现申请被审核（已通过的提现申请可以重新审核为拒绝）
- 更新提现申请状态和审核信息
- 如果审核拒绝：
  - 自动将提现金额退回用户钱包（包括从"待审核"改为"已拒绝"，或从"已通过"改为"已拒绝"）
  - 创建一条类型为"退款"的余额变动记录
  - 备注为"提现审核拒绝，退回余额"
返回成功和失败的数量，以及失败的ID列表

错误码说明:

错误码	错误信息	说明
400	withdrawIDs is required and cannot be empty	提现申请ID列表不能为空
400	status must be 2 (approved) or 3 (rejected)	审核状态必须是2或3
401	无权限	需要管理员权限

注意：

批量审核时，部分成功部分失败是正常的
失败的提现申请会在 failedIDs 中返回
失败的常见原因：
- 提现申请不存在
- 提现申请状态不是"待审核"或"已通过"
- 更新状态时出错

请求示例:

// 批量审核通过
{
  "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": "审核通过，已打款"
}

响应示例:

// 全部成功
{
  "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可能不存在或状态不对
  }
}

通用说明

分页参数说明

所有列表接口都使用统一的分页参数格式：

{
  "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。

响应格式说明

所有接口都遵循统一的响应格式：

{
  "errCode": 0,        // 错误码，0表示成功
  "errMsg": "",        // 错误信息
  "errDlt": "",        // 错误详情
  "data": {}           // 响应数据
}

接口调用示例

示例1：获取待审核的提现申请列表

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：批量审核提现申请（通过）

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：批量审核提现申请（拒绝）

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：单个审核（也支持）

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) → 已拒绝（余额自动退回用户钱包）

注意事项

用户申请提现：用户在前端申请提现时，余额会立即扣除，创建提现申请记录
后台审核：管理员通过后台接口审核用户的提现申请，支持批量审核
批量审核：可以一次审核多个提现申请，返回成功和失败的数量
审核通过：余额已在用户申请时扣除，审核通过时无需额外操作
审核拒绝：审核拒绝时会自动退回余额到用户钱包，并创建退款记录（包括从"已通过"改为"已拒绝"的情况）
状态检查：允许"待审核"和"已通过"状态的提现申请被审核，已通过的提现申请可以重新审核为拒绝
部分失败处理：批量审核时，部分成功部分失败是正常的，失败的ID会在响应中返回
金额单位：所有金额都以"分"为单位，前端显示时需要除以100
数据来源：所有接口操作的都是 withdraw_applications 集合（用户申请的提现），不是 withdraws 集合

13 KiB Raw Blame History Unescape Escape

提现管理后台接口文档

接口列表

1. 获取提现申请详情

2. 获取提现申请列表（支持按状态筛选）

3. 获取用户的提现申请列表

4. 批量审核提现申请

通用说明

分页参数说明

时间戳说明

金额单位说明

权限说明

响应格式说明

接口调用示例

示例1：获取待审核的提现申请列表

示例2：批量审核提现申请（通过）

示例3：批量审核提现申请（拒绝）

示例4：单个审核（也支持）

状态流转图

注意事项

13 KiB

Raw Blame History