zhibo/虚拟货币和礼物系统开发文档.md

# 虚拟货币和礼物系统开发文档

## 功能概述

本系统实现了完整的虚拟货币充值和礼物赠送功能，包括：

1. **用户余额管理**
   - 查看当前虚拟货币余额
   - 充值虚拟货币
   - 查看充值记录
   - 查看消费记录

2. **礼物系统**
   - 查看礼物列表
   - 购买礼物送给主播
   - 查看送出的礼物记录
   - 查看收到的礼物记录（主播）
   - 直播间礼物统计

3. **后台管理**
   - 主播查看收到的礼物
   - 礼物收入统计
   - 充值套餐管理
   - 礼物配置管理

## 数据库设计

### 1. 用户余额字段
```sql
ALTER TABLE eb_user ADD COLUMN virtual_balance DECIMAL(10,2) DEFAULT 0.00;
```

### 2. 充值记录表 (eb_virtual_currency_recharge)
- id: 充值记录ID
- user_id: 用户ID
- order_no: 订单号
- amount: 充值金额（人民币）
- virtual_amount: 获得的虚拟货币
- payment_method: 支付方式
- payment_status: 支付状态
- create_time: 创建时间
- pay_time: 支付时间

### 3. 交易记录表 (eb_virtual_currency_transaction)
- id: 交易ID
- user_id: 用户ID
- transaction_type: 交易类型（recharge/gift/refund）
- amount: 交易金额
- balance_after: 交易后余额
- related_id: 关联ID
- description: 交易描述
- create_time: 创建时间

### 4. 礼物配置表 (eb_gift_config)
- id: 礼物ID
- name: 礼物名称
- icon: 礼物图标
- price: 礼物价格
- animation: 动画效果
- sort_order: 排序
- is_enabled: 是否启用

### 5. 礼物记录表 (eb_gift_record)
- id: 记录ID
- sender_id: 送礼者ID
- receiver_id: 接收者ID
- room_id: 直播间ID
- gift_id: 礼物ID
- gift_name: 礼物名称
- gift_price: 礼物价格
- quantity: 数量
- total_price: 总价格
- is_anonymous: 是否匿名
- create_time: 创建时间

### 6. 充值套餐表 (eb_recharge_package)
- id: 套餐ID
- amount: 充值金额
- virtual_amount: 获得虚拟货币
- bonus_amount: 赠送虚拟货币
- title: 套餐标题
- description: 套餐描述
- is_hot: 是否热门
- sort_order: 排序

## API接口

### 虚拟货币相关接口

#### 1. 获取用户余额
```
GET /api/front/virtual-currency/balance
```

响应：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "balance": 100.00,
    "userId": 43
  }
}
```

#### 2. 获取充值套餐列表
```
GET /api/front/virtual-currency/recharge/packages
```

响应：
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "amount": 6.00,
      "virtual_amount": 60.00,
      "bonus_amount": 0.00,
      "title": "6元",
      "description": "获得60虚拟币",
      "is_hot": 0
    }
  ]
}
```

#### 3. 创建充值订单
```
POST /api/front/virtual-currency/recharge/create
```

请求体：
```json
{
  "packageId": 1,
  "paymentMethod": "alipay"
}
```

响应：
```json
{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "orderNo": "RC20260103165030123456",
    "amount": 6.00,
    "virtualAmount": 60.00,
    "paymentMethod": "alipay"
  }
}
```

#### 4. 模拟支付成功（测试用）
```
POST /api/front/virtual-currency/recharge/mock-pay
```

请求体：
```json
{
  "orderNo": "RC20260103165030123456"
}
```

#### 5. 获取充值记录
```
GET /api/front/virtual-currency/recharge/records?page=1&limit=20
```

#### 6. 获取消费记录
```
GET /api/front/virtual-currency/transactions?page=1&limit=20
```

### 礼物系统接口

#### 1. 获取礼物列表
```
GET /api/front/gift/list
```

响应：
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "玫瑰",
      "icon": "https://example.com/gifts/rose.png",
      "price": 1.00,
      "animation": null
    }
  ]
}
```

#### 2. 送礼物
```
POST /api/front/gift/send
```

请求体：
```json
{
  "giftId": 1,
  "receiverId": 43,
  "roomId": 8,
  "quantity": 1,
  "isAnonymous": false
}
```

响应：
```json
{
  "code": 200,
  "message": "送礼成功",
  "data": {
    "giftRecordId": 1,
    "giftName": "玫瑰",
    "quantity": 1,
    "totalPrice": 1.00,
    "newBalance": 99.00
  }
}
```

#### 3. 获取送出的礼物记录
```
GET /api/front/gift/sent?page=1&limit=20
```

#### 4. 获取收到的礼物记录
```
GET /api/front/gift/received?page=1&limit=20
```

#### 5. 获取直播间礼物统计
```
GET /api/front/gift/room/{roomId}/stats
```

响应：
```json
{
  "code": 200,
  "data": {
    "totalCount": 100,
    "totalValue": 1000.00,
    "giftRank": [
      {
        "gift_name": "玫瑰",
        "gift_icon": "...",
        "total_quantity": 50,
        "total_value": 50.00
      }
    ],
    "userRank": [
      {
        "sender_id": 42,
        "nickname": "用户A",
        "avatar": "...",
        "total_value": 500.00
      }
    ]
  }
}
```

## Android端实现

### 1. 在个人中心添加"我的余额"入口

在 `ProfileActivity.java` 中添加：

```java
findViewById(R.id.layout_balance).setOnClickListener(v -> {
    Intent intent = new Intent(this, BalanceActivity.class);
    startActivity(intent);
});
```

### 2. 余额页面 (BalanceActivity)

功能：
- 显示当前余额
- 充值按钮
- 充值记录和消费记录Tab切换

### 3. 充值页面 (RechargeActivity)

功能：
- 显示充值套餐列表（网格布局）
- 选择支付方式（支付宝/微信）
- 确认充值按钮

### 4. 礼物面板 (GiftPanelDialog)

在直播间页面添加礼物按钮，点击弹出礼物面板：

功能：
- 显示礼物列表
- 选择礼物和数量
- 显示当前余额
- 发送礼物

### 5. 主播收礼记录页面

在主播中心添加"收到的礼物"入口，显示：
- 礼物列表
- 送礼用户信息
- 礼物价值统计

## 部署步骤

### 1. 执行数据库脚本
```bash
mysql -h 1.15.149.240 -u root -p zhibo < virtual_currency_and_gift_system.sql
```

### 2. 编译后端代码
```bash
cd Zhibo/zhibo-h
mvn clean package -DskipTests
```

### 3. 部署后端服务
```bash
# 停止服务
ssh root@1.15.149.240 "cd /root/zhibo && docker-compose stop crmeb-front"

# 上传jar包
scp crmeb-front/target/Crmeb-front.jar root@1.15.149.240:/root/zhibo/

# 启动服务
ssh root@1.15.149.240 "cd /root/zhibo && docker-compose up -d crmeb-front"
```

### 4. 编译Android应用
在Android Studio中编译并安装到设备

## 测试流程

### 1. 测试充值功能
1. 打开APP，进入个人中心
2. 点击"我的余额"
3. 点击"立即充值"
4. 选择充值套餐（如6元）
5. 选择支付方式
6. 点击"确认充值"
7. 系统自动模拟支付成功
8. 返回余额页面，查看余额是否增加

### 2. 测试送礼功能
1. 进入直播间
2. 点击礼物按钮
3. 选择礼物（如玫瑰）
4. 选择数量
5. 点击"发送"
6. 查看余额是否扣除
7. 主播端查看是否收到礼物

### 3. 测试记录查询
1. 在余额页面查看充值记录
2. 查看消费记录
3. 在主播中心查看收到的礼物

## 后续优化

### 1. 支付集成
- 集成支付宝SDK
- 集成微信支付SDK
- 实现真实的支付流程

### 2. 礼物动画
- 添加礼物发送动画
- 添加礼物接收特效
- 实现礼物连击效果

### 3. 提现功能
- 主播可以将收到的礼物提现
- 设置提现规则和手续费
- 实现提现审核流程

### 4. 礼物排行榜
- 实时更新礼物排行榜
- 显示贡献榜
- 添加榜单奖励

### 5. VIP会员
- 充值达到一定金额自动升级VIP
- VIP享受充值优惠
- VIP专属礼物

## 注意事项

1. **安全性**
   - 所有金额相关操作必须使用事务
   - 充值和消费必须记录详细日志
   - 防止并发导致的余额异常

2. **性能优化**
   - 礼物列表使用缓存
   - 统计数据定时更新
   - 大量礼物记录分页加载

3. **用户体验**
   - 充值失败要有明确提示
   - 余额不足要提示充值
   - 礼物发送要有即时反馈

4. **合规性**
   - 虚拟货币不能直接提现为人民币
   - 需要符合相关法律法规
   - 保留完整的交易记录

## 文件清单

### 数据库
- `virtual_currency_and_gift_system.sql` - 数据库表结构和初始数据

### 后端Java文件
- `VirtualCurrencyController.java` - 虚拟货币控制器
- `GiftSystemController.java` - 礼物系统控制器

### Android文件
- `BalanceActivity.java` - 余额页面
- `activity_balance.xml` - 余额页面布局
- `RechargeActivity.java` - 充值页面
- `activity_recharge.xml` - 充值页面布局
- `GiftPanelDialog.java` - 礼物面板对话框
- `RechargePackageAdapter.java` - 充值套餐适配器
- `GiftAdapter.java` - 礼物列表适配器
- `BalancePagerAdapter.java` - 余额页面ViewPager适配器

### API接口定义
需要在 `ApiService.java` 中添加以下接口：

```java
// 虚拟货币相关
@GET("api/front/virtual-currency/balance")
Call<ApiResponse<Map<String, Object>>> getVirtualBalance();

@GET("api/front/virtual-currency/recharge/packages")
Call<ApiResponse<List<Map<String, Object>>>> getRechargePackages();

@POST("api/front/virtual-currency/recharge/create")
Call<ApiResponse<Map<String, Object>>> createRechargeOrder(@Body Map<String, Object> request);

@POST("api/front/virtual-currency/recharge/mock-pay")
Call<ApiResponse<String>> mockPaySuccess(@Body Map<String, Object> request);

@GET("api/front/virtual-currency/recharge/records")
Call<ApiResponse<List<Map<String, Object>>>> getRechargeRecords(
    @Query("page") int page, 
    @Query("limit") int limit
);

@GET("api/front/virtual-currency/transactions")
Call<ApiResponse<List<Map<String, Object>>>> getTransactions(
    @Query("page") int page, 
    @Query("limit") int limit
);

// 礼物系统相关
@GET("api/front/gift/list")
Call<ApiResponse<List<Map<String, Object>>>> getGiftList();

@POST("api/front/gift/send")
Call<ApiResponse<Map<String, Object>>> sendGift(@Body Map<String, Object> request);

@GET("api/front/gift/sent")
Call<ApiResponse<List<Map<String, Object>>>> getSentGifts(
    @Query("page") int page, 
    @Query("limit") int limit
);

@GET("api/front/gift/received")
Call<ApiResponse<List<Map<String, Object>>>> getReceivedGifts(
    @Query("page") int page, 
    @Query("limit") int limit
);

@GET("api/front/gift/room/{roomId}/stats")
Call<ApiResponse<Map<String, Object>>> getRoomGiftStats(@Path("roomId") int roomId);
```

## 开发进度

- [x] 数据库设计
- [x] 后端API接口
- [x] Android余额页面
- [x] Android充值页面
- [ ] Android礼物面板
- [ ] Android礼物记录页面
- [ ] 后台管理页面
- [ ] 支付集成
- [ ] 礼物动画效果
- [ ] 完整测试

## 联系方式

如有问题，请查看相关文档或联系开发团队。