zhibo/虚拟货币余额系统说明.md

虚拟货币余额系统说明

数据库表结构

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. 余额不足时要有提示