454 lines
10 KiB
Markdown
454 lines
10 KiB
Markdown
# 钱包相关接口汇总
|
||
|
||
## 基础信息
|
||
|
||
- **基础路径**: `/wallet`
|
||
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckToken` 中间件验证）
|
||
- **请求方法**: 所有接口均为 `POST`
|
||
- **Content-Type**: `application/json`
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取钱包余额
|
||
|
||
**接口地址**: `POST /wallet/balance`
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {
|
||
"balance": 10000 // 余额（单位：分）
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取钱包详细信息
|
||
|
||
**接口地址**: `POST /wallet/info`
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {
|
||
"balance": 10000, // 余额（单位：分）
|
||
"withdrawAccount": "string", // 提现账号
|
||
"withdrawAccountType": 1, // 提现账号类型：1-支付宝，2-微信，3-银行卡
|
||
"withdrawReceiveAccount": "string", // 提现收款账号
|
||
"hasPaymentPassword": true, // 是否已设置支付密码
|
||
"realNameAuth": { // 实名认证信息（可选）
|
||
"idCard": "string",
|
||
"idCardPhotoFront": "string",
|
||
"idCardPhotoBack": "string",
|
||
"name": "string"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取余额明细
|
||
|
||
**接口地址**: `POST /wallet/balance_records`
|
||
|
||
**请求参数**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| pagination | object | 是 | 分页参数 |
|
||
| pagination.pageNumber | int32 | 是 | 页码（从1开始） |
|
||
| pagination.showNumber | int32 | 是 | 每页显示数量 |
|
||
| type | int32 | 否 | 变动类型（可选，0表示查询所有类型）：1-充值，2-提现/提款，3-消费，4-退款，5-奖励，6-后台充值，7-发红包，8-抢红包，99-其他 |
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {
|
||
"total": 100,
|
||
"records": [
|
||
{
|
||
"id": "string",
|
||
"userID": "string",
|
||
"amount": 10000,
|
||
"type": 1,
|
||
"beforeBalance": 0,
|
||
"afterBalance": 10000,
|
||
"orderID": "string",
|
||
"transactionID": "string",
|
||
"redPacketID": "string",
|
||
"remark": "string",
|
||
"createTime": 1234567890123
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**变动类型说明**:
|
||
|
||
| 类型值 | 类型名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 1 | 充值 | 用户充值 |
|
||
| 2 | 提现/提款 | 提现申请 |
|
||
| 3 | 消费 | 消费支出 |
|
||
| 4 | 退款 | 退款收入 |
|
||
| 5 | 奖励 | 奖励收入 |
|
||
| 6 | 后台充值 | 管理员后台充值 |
|
||
| 7 | 发红包 | 发红包（减少余额） |
|
||
| 8 | 抢红包 | 抢红包（增加余额） |
|
||
| 99 | 其他 | 其他类型 |
|
||
|
||
**业务逻辑**:
|
||
|
||
1. 从 token 中获取当前用户ID
|
||
2. 如果指定了 type，按类型查询；否则查询所有类型
|
||
3. 按创建时间倒序排列
|
||
4. 支持分页查询
|
||
|
||
**请求示例**:
|
||
|
||
查询所有记录：
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
按类型查询（只查询充值记录）：
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 10
|
||
},
|
||
"type": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 设置支付密码
|
||
|
||
**接口地址**: `POST /wallet/payment_password/set`
|
||
|
||
**请求参数**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| newPassword | string | 是 | 新支付密码 |
|
||
| oldPassword | string | 条件必填 | 旧支付密码（修改时必填，首次设置时不需要） |
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**业务逻辑**:
|
||
|
||
1. **首次设置支付密码**:
|
||
- 钱包不存在或未设置支付密码
|
||
- 不需要提供 `oldPassword`
|
||
- 如果提供了 `oldPassword`，会返回错误
|
||
- 如果钱包不存在，会自动创建钱包并设置支付密码
|
||
|
||
2. **修改支付密码**:
|
||
- 已设置支付密码
|
||
- 必须提供 `oldPassword`
|
||
- 验证旧密码是否正确
|
||
- 验证新密码不能与旧密码相同
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误信息 | 说明 |
|
||
|---------|------|
|
||
| 新支付密码不能为空 | newPassword 为空 |
|
||
| 修改支付密码需要提供旧密码 | 已设置密码但未提供 oldPassword |
|
||
| 首次设置支付密码不需要提供旧密码 | 未设置密码但提供了 oldPassword |
|
||
| 旧支付密码错误 | oldPassword 验证失败 |
|
||
| 新密码不能与旧密码相同 | newPassword == oldPassword |
|
||
|
||
**请求示例**:
|
||
|
||
首次设置：
|
||
```json
|
||
{
|
||
"newPassword": "123456"
|
||
}
|
||
```
|
||
|
||
修改密码：
|
||
```json
|
||
{
|
||
"newPassword": "654321",
|
||
"oldPassword": "123456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 设置提现账号
|
||
|
||
**接口地址**: `POST /wallet/withdraw_account/set`
|
||
|
||
**请求参数**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| account | string | 是 | 提现账号 |
|
||
| accountType | int32 | 是 | 账号类型：1-支付宝，2-微信，3-银行卡 |
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**账号类型说明**:
|
||
|
||
| 类型值 | 类型名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 1 | 支付宝 | 支付宝账号 |
|
||
| 2 | 微信 | 微信账号 |
|
||
| 3 | 银行卡 | 银行卡号 |
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误信息 | 说明 |
|
||
|---------|------|
|
||
| 提现账号不能为空 | account 为空 |
|
||
| 账号类型无效，必须是1-支付宝，2-微信，3-银行卡 | accountType 不在有效范围内 |
|
||
|
||
**请求示例**:
|
||
|
||
设置支付宝账号：
|
||
```json
|
||
{
|
||
"account": "13800138000",
|
||
"accountType": 1
|
||
}
|
||
```
|
||
|
||
设置银行卡：
|
||
```json
|
||
{
|
||
"account": "6222021234567890123",
|
||
"accountType": 3
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 申请提现
|
||
|
||
**接口地址**: `POST /wallet/withdraw/apply`
|
||
|
||
**请求参数**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| amount | int64 | 是 | 提现金额（单位：分，必须 > 0） |
|
||
| paymentPassword | string | 是 | 支付密码 |
|
||
| ip | string | 否 | 申请IP |
|
||
| deviceID | string | 否 | 设备ID |
|
||
| platform | string | 否 | 平台（iOS、Android、Web等） |
|
||
| deviceModel | string | 否 | 设备型号 |
|
||
| deviceBrand | string | 否 | 设备品牌 |
|
||
| osVersion | string | 否 | 操作系统版本 |
|
||
| appVersion | string | 否 | 应用版本 |
|
||
|
||
**注意**:
|
||
- 提现账号从用户钱包中自动获取，不需要在请求中提供
|
||
- 如果钱包中未设置提现账号，会返回错误提示"请先在钱包中设置提现账号"
|
||
- 备注（remark）由后台管理员在审核时填写，用户申请时不需要提供
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {
|
||
"applicationID": "uuid-string" // 申请ID
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误信息 | 说明 |
|
||
|---------|------|
|
||
| 提现金额必须大于0 | amount <= 0 |
|
||
| 支付密码不能为空 | paymentPassword 为空 |
|
||
| 钱包不存在，无法申请提现 | 用户钱包不存在 |
|
||
| 请先设置支付密码 | 用户未设置支付密码 |
|
||
| 支付密码错误 | 支付密码验证失败 |
|
||
| 余额不足，无法申请提现 | 钱包余额 < 提现金额 |
|
||
| 请先在钱包中设置提现账号 | 钱包中未设置提现账号 |
|
||
|
||
---
|
||
|
||
### 6. 获取提现申请列表
|
||
|
||
**接口地址**: `POST /wallet/withdraw/list`
|
||
|
||
**请求参数**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| pagination | object | 是 | 分页参数 |
|
||
| pagination.pageNumber | int32 | 是 | 页码（从1开始） |
|
||
| pagination.showNumber | int32 | 是 | 每页显示数量 |
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"data": {
|
||
"total": 100,
|
||
"applications": [
|
||
{
|
||
"id": "string",
|
||
"userID": "string",
|
||
"amount": 10000,
|
||
"withdrawAccount": "string",
|
||
"withdrawAccountType": 1,
|
||
"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 | 待审核 | 用户已提交，等待管理员审核 |
|
||
| 2 | 已通过 | 管理员审核通过 |
|
||
| 3 | 已拒绝 | 管理员审核拒绝 |
|
||
| 4 | 处理中 | 审核通过后，正在处理提现 |
|
||
| 5 | 已完成 | 提现已完成 |
|
||
|
||
---
|
||
|
||
## RPC 接口对应关系
|
||
|
||
| HTTP 接口 | RPC 方法 | 请求消息 | 响应消息 |
|
||
|----------|---------|---------|---------|
|
||
| `/wallet/balance` | `GetWalletBalance` | `GetWalletBalanceReq` | `GetWalletBalanceResp` |
|
||
| `/wallet/info` | `GetWalletInfo` | `GetWalletInfoReq` | `GetWalletInfoResp` |
|
||
| `/wallet/balance_records` | `GetWalletBalanceRecords` | `GetWalletBalanceRecordsReq` | `GetWalletBalanceRecordsResp` |
|
||
| `/wallet/payment_password/set` | `SetPaymentPassword` | `SetPaymentPasswordReq` | `SetPaymentPasswordResp` |
|
||
| `/wallet/withdraw_account/set` | `SetWithdrawAccount` | `SetWithdrawAccountReq` | `SetWithdrawAccountResp` |
|
||
| `/wallet/withdraw/apply` | `CreateWithdrawApplication` | `CreateWithdrawApplicationReq` | `CreateWithdrawApplicationResp` |
|
||
| `/wallet/withdraw/list` | `GetWithdrawApplications` | `GetWithdrawApplicationsReq` | `GetWithdrawApplicationsResp` |
|
||
|
||
---
|
||
|
||
## 使用流程示例
|
||
|
||
### 1. 首次使用钱包
|
||
|
||
```bash
|
||
# 1. 获取钱包信息（检查是否已设置支付密码）
|
||
POST /wallet/info
|
||
|
||
# 2. 如果 hasPaymentPassword 为 false，设置支付密码
|
||
POST /wallet/payment_password/set
|
||
{
|
||
"newPassword": "123456"
|
||
}
|
||
|
||
# 3. 设置提现账号
|
||
POST /wallet/withdraw_account/set
|
||
{
|
||
"account": "13800138000",
|
||
"accountType": 1 // 1-支付宝，2-微信，3-银行卡
|
||
}
|
||
|
||
# 4. 申请提现（提现账号从钱包中自动获取）
|
||
POST /wallet/withdraw/apply
|
||
{
|
||
"amount": 10000,
|
||
"paymentPassword": "123456"
|
||
}
|
||
```
|
||
|
||
### 2. 修改支付密码
|
||
|
||
```bash
|
||
# 修改支付密码
|
||
POST /wallet/payment_password/set
|
||
{
|
||
"newPassword": "654321",
|
||
"oldPassword": "123456"
|
||
}
|
||
```
|
||
|
||
### 3. 查看提现记录
|
||
|
||
```bash
|
||
# 获取提现申请列表
|
||
POST /wallet/withdraw/list
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **支付密码设置**:
|
||
- 首次设置不需要旧密码
|
||
- 修改时必须提供正确的旧密码
|
||
- 新密码不能与旧密码相同
|
||
|
||
2. **提现申请**:
|
||
- 必须已设置支付密码
|
||
- 必须验证支付密码
|
||
- 余额必须足够
|
||
- 需要设置提现账号
|
||
|
||
3. **权限控制**:
|
||
- 所有接口都需要 token 认证
|
||
- 用户只能操作自己的钱包
|
||
- 用户只能查看自己的提现申请列表
|
||
|
||
4. **数据单位**:
|
||
- 所有金额单位均为"分"（1元 = 100分）
|
||
- 时间戳单位为毫秒
|