# 钱包相关接口汇总

## 基础信息

- **基础路径**: `/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分）
   - 时间戳单位为毫秒