## 手动充值功能说明文档

---

### 一、功能概述

手动充值功能允许玩家通过银行转账或USDT方式进行充值，管理员在后台审核并确认充值后，系统自动为玩家上分。

**核心流程**：

```
管理员配置收款方式（银行/USDT）
        ↓
玩家选择充值方式，输入金额，上传转账截图
        ↓
生成充值订单（状态：PENDING 审核中）
        ↓
管理员审核充值记录
   ├─ 批准 → 自动给玩家钱包上分（可调整金额）
   └─ 拒绝 → 记录拒绝原因
```

---

### 二、数据库表结构

#### `payment_methods` — 收款方式配置表

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | BigInt | 主键 |
| `method_type` | VARCHAR(20) | 类型：`BANK`（银行）/ `USDT` |
| `bank_name` | VARCHAR(128) | 银行名称（BANK 类型使用） |
| `account_holder` | VARCHAR(128) | 银行账户名（BANK 类型使用） |
| `account_number` | VARCHAR(128) | 银行账号（BANK 类型使用） |
| `usdt_address` | VARCHAR(256) | USDT 地址（USDT 类型使用） |
| `qr_code_url` | VARCHAR(500) | USDT 二维码图片 URL（USDT 类型使用） |
| `display_name` | VARCHAR(128) | 展示名称 |
| `sort_order` | INT | 排序序号，越小越靠前 |
| `is_active` | BOOLEAN | 是否启用（管理员可见性） |
| `show_on_player` | BOOLEAN | 是否对玩家展示 |
| `created_by` | BigInt | 创建者 ID |
| `created_at` / `updated_at` | DateTime | 创建/更新时间 |

#### `deposit_orders` — 充值订单表

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | BigInt | 主键 |
| `order_no` | VARCHAR(64) | 订单号（唯一），格式：`DEP{timestamp}{random}` |
| `player_id` | BigInt | 玩家 ID |
| `payment_method_id` | BigInt | 关联的收款方式 ID |
| `method_type` | VARCHAR(20) | 冗余的类型（BANK/USDT），便于筛选 |
| `amount` | DECIMAL(18,4) | 玩家申报的充值金额 |
| `screenshot_url` | VARCHAR(500) | 转账截图 URL |
| `status` | VARCHAR(20) | 状态：`PENDING` / `APPROVED` / `REJECTED` |
| `approved_amount` | DECIMAL(18,4) | 实际批准的金额（批准时写入，可能与申报金额不同） |
| `reviewer_id` | BigInt | 审核人 ID |
| `reviewed_at` | DateTime | 审核时间 |
| `reject_reason` | VARCHAR(500) | 拒绝原因 |
| `remark` | VARCHAR(500) | 备注 |
| `created_at` / `updated_at` | DateTime | 创建/更新时间 |

---

### 三、管理后台操作

#### 3.1 配置收款方式

**入口**：管理后台左侧菜单 → 「收款方式」

支持两种类型：

**银行转账**：
- 填写银行名称（如：工商银行）
- 填写账户持有人姓名
- 填写银行账号
- 设置展示名称（可选）
- 设置排序、是否启用、是否展示给玩家

**USDT 充值**：
- 填写 USDT 收款地址
- 上传 USDT 二维码图片（通过后台媒体库上传，类别为 `payments`）
- 设置展示名称（可选）
- 设置排序、是否启用、是否展示给玩家

**操作说明**：
- `Active` 开关：控制该收款方式是否启用（管理员可见）
- `Show Player` 开关：控制是否在前台展示给玩家
- 一个收款方式可以同时启用但不展示给玩家（用于暂停充值）
- 支持创建多个同类型的收款方式

#### 3.2 审核充值订单

**入口**：管理后台左侧菜单 → 「充值审核」

**列表功能**：
- 显示所有充值订单，包含：订单号、玩家、收款方式类型、金额、截图、状态、批准金额、审核人、时间
- 支持按状态筛选（全部/待审核/已批准/已拒绝）
- 支持按类型筛选（全部/银行/USDT）
- 支持按玩家用户名搜索
- 点击截图缩略图可放大查看

**批准操作**：
1. 点击订单行的「Approve」按钮
2. 在弹窗中查看截图
3. 系统默认填入玩家申报的金额，管理员可根据截图实际情况调整金额
4. 可选填写备注
5. 点击「Confirm Approve」确认

**批准后自动执行**：
- 订单状态变为 `APPROVED`
- 系统自动调用钱包充值服务，将批准金额添加到玩家可用余额
- 生成一条钱包交易记录，类型为 `PLAYER_DEPOSIT`
- 记录审核人和审核时间

**拒绝操作**：
1. 点击订单行的「Reject」按钮
2. 在弹窗中必须填写拒绝原因
3. 点击「Confirm Reject」确认

**拒绝后**：
- 订单状态变为 `REJECTED`
- 记录拒绝原因和审核人
- 玩家不会收到任何资金

---

### 四、玩家端操作

#### 4.1 充值入口

- 玩家登录后，进入「账单」页面
- 顶部有一个「+ 充值」按钮，点击进入充值页面
- 或直接访问 `/wallet/recharge`

#### 4.2 充值流程

1. **选择充值方式**：顶部有「银行转账」和「USDT」两个标签切换
2. **选择收款账户**：系统展示管理员配置的可用收款方式列表，点击选中
3. **查看收款信息**：
   - 银行转账：显示银行名称、账户持有人、银行账号（支持点击复制）
   - USDT：显示 USDT 地址（支持点击复制）和二维码图片
4. **输入充值金额**：输入实际转账的金额
5. **上传转账截图**：
   - 点击上传区域选择图片
   - 前端自动压缩图片（目标大小 ≤1MB，最大分辨率 1920px）
   - 原文件限制 10MB，压缩后限制 5MB
   - 支持预览和删除已选截图
6. **提交充值**：点击提交按钮，系统创建充值订单
7. **成功提示**：显示订单号，提示等待管理员审核

#### 4.3 查看充值记录

- 充值页面右上角有「记录」链接，或访问 `/wallet/recharge/history`
- 显示所有充值订单列表，每条订单显示：
  - 收款方式类型标签
  - 充值金额
  - 状态（审核中/已通过/已拒绝）
  - 收款方式名称、提交时间
  - 如果批准金额与申报金额不同，显示「实际到账」金额
  - 如果被拒绝，显示拒绝原因
- 支持下拉刷新

---

### 五、API 接口列表

#### 管理后台接口

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| `POST` | `/admin/payment-methods` | `deposit.manage` | 创建收款方式 |
| `GET` | `/admin/payment-methods` | `deposit.manage` | 查看所有收款方式 |
| `PUT` | `/admin/payment-methods/:id` | `deposit.manage` | 更新收款方式 |
| `DELETE` | `/admin/payment-methods/:id` | `deposit.manage` | 停用收款方式（软删除） |
| `GET` | `/admin/deposit-orders` | `deposit.review` | 分页查看充值订单 |
| `POST` | `/admin/deposit-orders/:id/approve` | `deposit.review` | 批准充值订单 |
| `POST` | `/admin/deposit-orders/:id/reject` | `deposit.review` | 拒绝充值订单 |

**充值订单列表查询参数**：
- `page` — 页码（默认 1）
- `pageSize` — 每页数量（默认 20，最大 100）
- `status` — 状态筛选：`PENDING` / `APPROVED` / `REJECTED`
- `keyword` — 玩家用户名关键词
- `methodType` — 类型筛选：`BANK` / `USDT`
- `dateFrom` / `dateTo` — 日期范围（ISO 格式）

**批准充值订单请求体**：
```json
{
  "approvedAmount": 100.00,  // 可选，不传则使用玩家申报金额
  "remark": "备注信息"        // 可选
}
```

**拒绝充值订单请求体**：
```json
{
  "reason": "截图金额与申报金额不符"  // 必填
}
```

#### 玩家端接口

| 方法 | 路径 | 认证 | 说明 |
|------|------|------|------|
| `GET` | `/player/payment-methods` | 需要 | 查看可用的收款方式列表 |
| `POST` | `/player/deposit-orders` | 需要 | 提交充值订单（multipart/form-data） |
| `GET` | `/player/deposit-orders` | 需要 | 查看自己的充值记录 |

**提交充值订单**（multipart/form-data）：
- `paymentMethodId` — 收款方式 ID
- `amount` — 充值金额
- `screenshot` — 转账截图图片文件（最大 5MB，仅接受图片类型）

**查看收款方式请求参数**：
- `methodType` — 可选，筛选类型：`BANK` / `USDT`

---

### 六、文件存储

充值相关截图存储在 `uploads/deposits/` 目录下，文件命名格式：`{timestamp}-{random8}.{ext}`

USDT 二维码图片通过管理员上传接口上传，存储在 `uploads/payments/` 目录下。

**上传大小限制**：
- 管理员上传（USDT 二维码）：5MB
- 玩家上传（充值截图）：5MB（前端压缩后），原文件 10MB

---

### 七、错误码

| 错误码 | 说明 |
|--------|------|
| `INVALID_METHOD_TYPE` | 无效的收款方式类型 |
| `PAYMENT_METHOD_NOT_FOUND` | 收款方式不存在或已停用 |
| `ORDER_NOT_FOUND` | 充值订单不存在 |
| `ORDER_NOT_PENDING` | 订单不是待审核状态 |
| `REASON_REQUIRED` | 拒绝原因为必填项 |
| `SCREENSHOT_REQUIRED` | 转账截图为必填项 |
| `FILE_MUST_BE_IMAGE` | 必须上传图片文件 |
| `INVALID_AMOUNT` | 金额无效 |
| `PAYMENT_METHOD_REQUIRED` | 未选择收款方式 |

---

### 八、权限配置

新增两个后台权限码，需要在数据库中通过种子数据或手动添加到 `permissions` 表：

| 权限码 | 说明 |
|--------|------|
| `deposit.manage` | 管理收款方式 |
| `deposit.review` | 审核充值订单 |

并将这些权限分配给需要操作充值功能的管理员角色（通过 `role_permissions` 表关联）。

---

### 九、注意事项

1. **金额调整**：批准充值时，管理员可以调整实际充值金额。当玩家输入的金额与截图显示的不一致时，以截图为准进行调整。
2. **并发审核**：批准操作在数据库事务中执行，会检查订单状态是否为 `PENDING`，防止多人同时审核同一笔订单。
3. **停用收款方式**：删除操作为软删除（设置 `isActive=false` 和 `showOnPlayer=false`），不会删除历史记录。
4. **截图审核**：管理员应仔细核对截图中的转账金额、时间、收款账户是否与配置的收款方式一致。
5. **前端图片压缩**：使用 `browser-image-compression` 库在浏览器端压缩图片，减少上传时间和服务器存储压力。