复制项目

2026-01-14 22:35:45 +08:00
parent 305d526110
commit b7f8db7d08
297 changed files with 81784 additions and 0 deletions
--- a/docs/API_WALLET_SUMMARY.md
+++ b/docs/API_WALLET_SUMMARY.md
@@ -0,0 +1,453 @@
+# 钱包相关接口汇总
+
+## 基础信息
+
+- **基础路径**: `/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分）
+   - 时间戳单位为毫秒