# 提现管理后台接口文档 ## 接口列表 | 接口地址 | 请求方法 | 说明 | |---------|---------|------| | `/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` 集合