# 虚拟货币余额系统说明

## 数据库表结构

### 1. eb_user表（用户余额）
- `virtual_balance` - DECIMAL(10,2) - 用户虚拟货币余额

### 2. eb_recharge_package（充值套餐表）
- 存储充值套餐配置
- 包含充值金额、获得虚拟币、赠送虚拟币等信息

### 3. eb_virtual_currency_recharge（充值记录表）
- 记录用户的充值订单
- 包含订单号、金额、支付状态等

### 4. eb_virtual_currency_transaction（交易记录表）
- 记录所有虚拟货币的收支明细
- 包含充值、消费、退款等类型

## 后端API接口

### 基础路径
```
/api/front/virtual-currency
```

### 接口列表

1. **获取用户余额**
   - GET `/balance`
   - 返回：`{ balance: number, userId: number }`

2. **获取充值套餐列表**
   - GET `/recharge/packages`
   - 返回：套餐列表（金额、虚拟币数量、赠送等）

3. **创建充值订单**
   - POST `/recharge/create`
   - 参数：`{ packageId: number, paymentMethod: string }`
   - 返回：订单信息（订单号、金额等）

4. **模拟支付成功**（测试用）
   - POST `/recharge/mock-pay`
   - 参数：`{ orderNo: string }`
   - 功能：直接完成支付，增加用户余额

5. **获取充值记录**
   - GET `/recharge/records?page=1&limit=20`
   - 返回：充值记录列表

6. **获取消费记录**
   - GET `/transactions?page=1&limit=20`
   - 返回：交易记录列表

## APP端实现

### 页面结构

1. **ProfileActivity（个人中心）**
   - 显示"我的钱包"按钮
   - 显示当前余额

2. **WalletActivity（钱包页面）**
   - 显示虎牙币余额
   - 提供充值入口
   - 提供收支明细入口

3. **BalanceActivity（余额详情）**
   - 显示详细余额
   - 充值记录和消费记录Tab

4. **RechargeActivity（充值页面）**
   - 显示充值套餐列表
   - 选择支付方式（支付宝/微信）
   - 确认充值

5. **TransactionHistoryActivity（收支明细）**
   - 显示所有交易记录

### 数据流程

1. **查看余额**
   ```
   用户打开钱包 → 调用 /balance 接口 → 显示余额
   ```

2. **充值流程**
   ```
   选择套餐 → 选择支付方式 → 创建订单 → 模拟支付 → 余额增加
   ```

3. **余额更新**
   ```
   充值成功 → 更新 eb_user.virtual_balance → 记录到 eb_virtual_currency_transaction
   ```

## 使用说明

### 测试充值功能

1. 登录APP
2. 进入"我的"页面
3. 点击"我的钱包"
4. 点击"充值"按钮
5. 选择充值套餐
6. 选择支付方式（支付宝/微信）
7. 点击"确认充值"
8. 系统自动模拟支付成功
9. 余额立即更新

### 查看余额

- 个人中心：显示简要余额
- 钱包页面：显示详细余额和虎牙币图标
- 余额详情：显示充值记录和消费记录

## 后续扩展

### 支付集成（待实现）

目前使用模拟支付，后续可以集成：

1. **支付宝支付**
   - 集成支付宝SDK
   - 在createRechargeOrder后跳转到支付宝
   - 支付成功后回调更新余额

2. **微信支付**
   - 集成微信支付SDK
   - 在createRechargeOrder后跳转到微信
   - 支付成功后回调更新余额

### 消费功能

余额可用于：
- 送礼物给主播
- 购买虚拟道具
- 开通会员服务
- 其他增值服务

## 注意事项

1. 所有金额使用DECIMAL(10,2)存储，避免精度问题
2. 每次余额变动都记录到交易表
3. 充值订单有状态管理（待支付、已支付、已取消）
4. 支付接口需要做好安全验证
5. 余额不足时要有提示