itom-group/chat-deploy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

复制项目

Browse Source
This commit is contained in:
kim.dev.6789
2026-01-14 22:35:45 +08:00
parent 305d526110
commit b7f8db7d08
297 changed files with 81784 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
docs/API_WITHDRAW_APPLICATION.md Normal file
View File

@@ -0,0 +1,439 @@
# 提现申请接口文档
## 基础信息
- **基础路径**: `/wallet`
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckToken` 中间件验证）
- **请求方法**: 所有接口均为 `POST`
- **Content-Type**: `application/json`
## 响应格式说明
所有接口的响应格式统一为：
```json
{
"errCode": 0, // 错误码，0 表示成功
"errMsg": "", // 错误消息
"errDlt": "", // 错误详情
"data": {} // 响应数据
}
```
## 公共数据结构
### RequestPagination（分页信息）
```json
{
"pageNumber": 1, // 页码（从1开始）
"showNumber": 10 // 每页显示数量
}
```
### WithdrawApplicationInfo（提现申请信息）
```json
{
"id": "string", // 申请ID
"userID": "string", // 用户ID
"amount": 10000, // 提现金额（单位：分）
"withdrawAccount": "string", // 提现账号
"withdrawAccountType": 1, // 提现账号类型：1-支付宝，2-微信，3-银行卡
"status": 1, // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
"auditorID": "string", // 审核人ID（管理员ID）
"auditTime": 1234567890123, // 审核时间（毫秒时间戳，未审核时为0）
"auditRemark": "string", // 审核备注
"ip": "string", // 申请IP
"deviceID": "string", // 设备ID
"platform": "string", // 平台（iOS、Android、Web等）
"deviceModel": "string", // 设备型号
"deviceBrand": "string", // 设备品牌
"osVersion": "string", // 操作系统版本
"appVersion": "string", // 应用版本
"remark": "string", // 申请备注
"createTime": 1234567890123, // 创建时间（毫秒时间戳）
"updateTime": 1234567890123 // 更新时间（毫秒时间戳）
}
```
### 提现申请状态说明
| 状态值 | 状态名称 | 说明 |
|--------|---------|------|
| 1 | 待审核 | 用户已提交申请，等待管理员审核 |
| 2 | 已通过 | 管理员审核通过 |
| 3 | 已拒绝 | 管理员审核拒绝 |
| 4 | 处理中 | 审核通过后，正在处理提现 |
| 5 | 已完成 | 提现已完成 |
---
## 接口列表
### 1. 设置支付密码
**接口地址**: `/wallet/payment_password/set`
**请求参数**:
```json
{
"newPassword": "string", // 新支付密码（必填）
"oldPassword": "string" // 旧支付密码（修改时必填，首次设置时不需要）
}
```
**响应参数**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {}
}
```
**业务逻辑**:
1. **首次设置支付密码**（钱包不存在或未设置支付密码）:
- 不需要提供 `oldPassword`
- 如果提供了 `oldPassword`，会返回错误
- 如果钱包不存在，会自动创建钱包并设置支付密码
2. **修改支付密码**（已设置支付密码）:
- 必须提供 `oldPassword`
- 验证旧密码是否正确
- 验证新密码不能与旧密码相同
- 更新支付密码
**错误码说明**:
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 400 | 新支付密码不能为空 | newPassword 为空 |
| 400 | 修改支付密码需要提供旧密码 | 已设置密码但未提供 oldPassword |
| 400 | 首次设置支付密码不需要提供旧密码 | 未设置密码但提供了 oldPassword |
| 400 | 旧支付密码错误 | oldPassword 验证失败 |
| 400 | 新密码不能与旧密码相同 | newPassword == oldPassword |
**请求示例**:
首次设置：
```json
{
"newPassword": "123456"
}
```
修改密码：
```json
{
"newPassword": "654321",
"oldPassword": "123456"
}
```
---
### 2. 设置提现账号
**接口地址**: `/wallet/withdraw_account/set`
**请求参数**:
```json
{
"account": "string", // 提现账号（必填）
"accountType": 1 // 账号类型（必填）：1-支付宝，2-微信，3-银行卡
}
```
**响应参数**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {}
}
```
**账号类型说明**:
| 类型值 | 类型名称 | 说明 |
|--------|---------|------|
| 1 | 支付宝 | 支付宝账号 |
| 2 | 微信 | 微信账号 |
| 3 | 银行卡 | 银行卡号 |
**错误码说明**:
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 400 | 提现账号不能为空 | account 为空 |
| 400 | 账号类型无效，必须是1-支付宝，2-微信，3-银行卡 | accountType 不在有效范围内 |
**业务逻辑**:
1. 验证必填字段（账号、账号类型）
2. 验证账号类型是否有效（1-3）
3. 更新钱包中的提现账号和账号类型
---
### 3. 申请提现
**接口地址**: `/wallet/withdraw/apply`
**请求参数**:
```json
{
"amount": 10000, // 提现金额（单位：分，必填，必须大于0）
"paymentPassword": "string", // 支付密码（必填）
"ip": "string", // 申请IP（可选）
"deviceID": "string", // 设备ID（可选）
"platform": "string", // 平台（可选，如：iOS、Android、Web）
"deviceModel": "string", // 设备型号（可选，如：iPhone 14 Pro）
"deviceBrand": "string", // 设备品牌（可选，如：Apple）
"osVersion": "string", // 操作系统版本（可选，如：iOS 17.0）
"appVersion": "string" // 应用版本（可选）
}
```
**注意**:
- 提现账号从用户钱包中自动获取，不需要在请求中提供
- 如果钱包中未设置提现账号，会返回错误提示
- 备注（remark）由后台管理员在审核时填写，用户申请时不需要提供
**响应参数**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"applicationID": "uuid-string" // 申请ID
}
}
```
**错误码说明**:
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 400 | 提现金额必须大于0 | amount <= 0 |
| 400 | 支付密码不能为空 | paymentPassword 为空 |
| 400 | 钱包不存在，无法申请提现 | 用户钱包不存在 |
| 400 | 请先设置支付密码 | 用户未设置支付密码 |
| 400 | 支付密码错误 | 支付密码验证失败 |
| 400 | 余额不足，无法申请提现 | 钱包余额 < 提现金额 |
| 400 | 请先在钱包中设置提现账号 | 钱包中未设置提现账号 |
**业务逻辑**:
1. 验证必填字段（金额、支付密码）
2. 获取用户钱包信息
3. 验证支付密码
4. 检查余额是否足够
5. 检查钱包中是否设置了提现账号（从钱包中获取）
6. 创建提现申请记录（状态：待审核，提现账号从钱包中获取）
---
### 4. 获取提现申请列表
**接口地址**: `/wallet/withdraw/list`
**请求参数**:
```json
{
"pagination": {
"pageNumber": 1, // 页码（从1开始）
"showNumber": 10 // 每页显示数量
}
}
```
**响应参数**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"total": 100, // 总数
"applications": [ // 申请列表
{
"id": "string",
"userID": "string",
"amount": 10000,
"withdrawAccount": "string",
"status": 1,
"auditorID": "string",
"auditTime": 1234567890123,
"auditRemark": "string",
"ip": "string",
"deviceID": "string",
"platform": "string",
"deviceModel": "string",
"deviceBrand": "string",
"osVersion": "string",
"appVersion": "string",
"remark": "string",
"createTime": 1234567890123,
"updateTime": 1234567890123
}
]
}
}
```
**业务逻辑**:
1. 从 token 中获取当前用户ID
2. 根据用户ID查询提现申请列表
3. 按创建时间倒序排列
4. 支持分页查询
---
## 请求示例
### 申请提现
```bash
curl -X POST http://your-domain/wallet/withdraw/apply \
-H "Content-Type: application/json" \
-H "token: your-token" \
-d '{
"amount": 10000,
"paymentPassword": "123456",
"ip": "192.168.1.1",
"deviceID": "device-uuid",
"platform": "iOS",
"deviceModel": "iPhone 14 Pro",
"deviceBrand": "Apple",
"osVersion": "iOS 17.0",
"appVersion": "1.0.0"
}'
```
**响应示例**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"applicationID": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
### 获取提现申请列表
```bash
curl -X POST http://your-domain/wallet/withdraw/list \
-H "Content-Type: application/json" \
-H "token: your-token" \
-d '{
"pagination": {
"pageNumber": 1,
"showNumber": 10
}
}'
```
**响应示例**:
```json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"total": 5,
"applications": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userID": "user123",
"amount": 10000,
"withdrawAccount": "6222021234567890123",
"status": 1,
"auditorID": "",
"auditTime": 0,
"auditRemark": "",
"ip": "192.168.1.1",
"deviceID": "device-uuid",
"platform": "iOS",
"deviceModel": "iPhone 14 Pro",
"deviceBrand": "Apple",
"osVersion": "iOS 17.0",
"appVersion": "1.0.0",
"remark": "提现备注",
"createTime": 1704067200000,
"updateTime": 1704067200000
}
]
}
}
```
---
## RPC 接口说明
### gRPC 服务
**服务名**: `openim.chat.Chat`
### 1. CreateWithdrawApplication
**RPC 方法**: `CreateWithdrawApplication`
**请求消息**: `CreateWithdrawApplicationReq`
**响应消息**: `CreateWithdrawApplicationResp`
### 2. SetPaymentPassword
**RPC 方法**: `SetPaymentPassword`
**请求消息**: `SetPaymentPasswordReq`
**响应消息**: `SetPaymentPasswordResp`
### 3. GetWithdrawApplications
**RPC 方法**: `GetWithdrawApplications`
**请求消息**: `GetWithdrawApplicationsReq`
**响应消息**: `GetWithdrawApplicationsResp`
---
## 注意事项
1. **支付密码验证**: 申请提现时必须提供正确的支付密码
2. **余额检查**: 系统会检查钱包余额是否足够，余额不足时无法申请
3. **提现账号**: 如果钱包中已设置提现账号，可以不传 `withdrawAccount`，系统会使用钱包中的账号
4. **申请状态**: 新创建的申请状态为"待审核"（status=1），需要管理员审核
5. **分页查询**: 列表接口支持分页，默认按创建时间倒序排列
6. **权限控制**: 用户只能查看自己的提现申请列表
---
## 相关接口
- [钱包余额查询](./API_WALLET.md#获取钱包余额)
- [钱包信息查询](./API_WALLET.md#获取钱包详细信息)
- [设置支付密码](#设置支付密码)