zhibo/android-app/礼物打赏功能说明.md

# 礼物打赏功能说明文档

## 功能概述

在直播间页面添加了礼物打赏功能，用户可以在观看直播时给主播赠送各种礼物。

## 功能特点

### 1. 礼物按钮位置
- 礼物按钮位于直播间底部聊天输入框的右侧
- 在发送按钮的左边，方便用户快速访问
- 使用礼物图标（🎁），颜色为橙色（#FF9800），醒目易识别

### 2. 礼物种类（8种）

| 礼物名称 | 价格 | 等级 | 图标 |
|---------|------|------|------|
| 玫瑰 | 10金币 | ⭐ | 🌹 |
| 爱心 | 20金币 | ⭐ | ❤️ |
| 蛋糕 | 50金币 | ⭐⭐ | 🎂 |
| 星星 | 100金币 | ⭐⭐ | ⭐ |
| 钻石 | 200金币 | ⭐⭐⭐ | 💎 |
| 皇冠 | 500金币 | ⭐⭐⭐⭐ | 👑 |
| 跑车 | 1000金币 | ⭐⭐⭐⭐⭐ | 🚗 |
| 火箭 | 2000金币 | ⭐⭐⭐⭐⭐ | 🚀 |

### 3. 礼物选择弹窗

#### 弹窗布局
- 底部弹出式设计（BottomSheetDialog）
- 标题栏显示"选择礼物"、用户金币余额和充值按钮
- 礼物列表采用4列网格布局（GridLayoutManager）
- 每个礼物显示图标、名称和价格

#### 交互功能
- **礼物选择**：点击礼物卡片进行选择，选中后显示蓝色边框
- **数量调整**：通过 +/- 按钮调整赠送数量（1-99）
- **余额显示**：实时显示用户当前金币余额
- **充值按钮**：点击充值按钮打开充值对话框
- **选中信息**：底部显示选中礼物的图标、名称和价格
- **赠送按钮**：点击赠送按钮完成礼物赠送

### 4. 充值功能

#### 充值入口
- 在礼物选择弹窗的标题栏右侧
- 显示为带边框的"充值"按钮，带有加号图标
- 颜色为橙色（#FF9800），与金币主题一致

#### 充值对话框
- 居中弹出式设计（MaterialAlertDialog）
- 显示当前金币余额
- 提供6种充值选项（2列网格布局）：
  - 100金币 - ¥10（首充优惠）
  - 300金币 - ¥30
  - 500金币 - ¥50（热门）
  - 1000金币 - ¥100
  - 3000金币 - ¥300（最划算）
  - 5000金币 - ¥500

#### 充值流程
1. 用户点击充值按钮
2. 显示充值对话框
3. 用户选择充值金额（选中后显示橙色边框）
4. 点击"确认充值"按钮
5. 调用支付接口（待集成支付SDK）
6. 支付成功后更新金币余额
7. 显示充值成功提示
8. 关闭充值对话框

### 5. 赠送流程

1. 用户点击礼物按钮
2. 检查登录状态（未登录则提示登录）
3. 显示礼物选择弹窗
4. 用户选择礼物和数量
5. 点击赠送按钮
6. 检查金币余额是否足够
7. 赠送成功后：
   - 扣除相应金币
   - 更新余额显示
   - 在聊天区显示赠送消息
   - 显示成功提示
   - 关闭弹窗

### 5. 聊天区显示

赠送礼物后，在聊天区会显示类似以下的消息：
```
我 送出了 1 个 玫瑰
我 送出了 5 个 钻石
```

礼物消息使用特殊标识（isGiftMessage），可以在后续添加特殊样式或动画效果。

## 文件结构

### 新增文件

#### Java类
- `Gift.java` - 礼物数据模型
- `GiftAdapter.java` - 礼物列表适配器
- `RechargeOption.java` - 充值选项数据模型
- `RechargeAdapter.java` - 充值选项适配器

#### 布局文件
- `bottom_sheet_gift.xml` - 礼物选择弹窗布局
- `item_gift.xml` - 礼物列表项布局
- `dialog_recharge.xml` - 充值对话框布局
- `item_recharge_option.xml` - 充值选项列表项布局

#### 图标资源
- `ic_gift_24.xml` - 礼物按钮图标
- `ic_coin_24.xml` - 金币图标
- `ic_add_24.xml` - 增加数量图标
- `ic_remove_24.xml` - 减少数量图标
- `ic_add_circle_24.xml` - 充值按钮图标
- `ic_gift_rose.xml` - 玫瑰礼物图标
- `ic_gift_heart.xml` - 爱心礼物图标
- `ic_gift_cake.xml` - 蛋糕礼物图标
- `ic_gift_star.xml` - 星星礼物图标
- `ic_gift_diamond.xml` - 钻石礼物图标
- `ic_gift_crown.xml` - 皇冠礼物图标
- `ic_gift_car.xml` - 跑车礼物图标
- `ic_gift_rocket.xml` - 火箭礼物图标

#### 背景资源
- `bg_gift_selected.xml` - 礼物选中状态背景
- `bg_recharge_selected.xml` - 充值选项选中状态背景
- `bg_discount_label.xml` - 优惠标签背景

### 修改文件

- `RoomDetailActivity.java` - 添加礼物功能逻辑
- `activity_room_detail_new.xml` - 添加礼物按钮
- `ChatMessage.java` - 添加礼物消息标识

## 后端接口对接

### 1. 获取礼物列表
```
GET /api/gifts
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "name": "玫瑰",
      "price": 10,
      "iconUrl": "https://example.com/gifts/rose.png",
      "description": "浪漫的玫瑰",
      "level": 1
    }
  ]
}
```

### 2. 获取用户金币余额
```
GET /api/user/balance
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "coinBalance": 1000
  }
}
```

### 3. 赠送礼物
```
POST /api/gifts/send
```
**请求参数：**
```json
{
  "roomId": "room123",
  "streamerId": "user456",
  "giftId": "1",
  "count": 5
}
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "赠送成功",
  "data": {
    "success": true,
    "newBalance": 950,
    "message": "赠送成功！"
  }
}
```

### 4. 获取充值选项列表
```
GET /api/recharge/options
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "coinAmount": 100,
      "price": 10.0,
      "discountLabel": "首充优惠"
    },
    {
      "id": "2",
      "coinAmount": 300,
      "price": 30.0,
      "discountLabel": null
    }
  ]
}
```

### 5. 创建充值订单
```
POST /api/recharge/create
```
**请求参数：**
```json
{
  "optionId": "1",
  "coinAmount": 100,
  "price": 10.0
}
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "orderId": "order123456",
    "paymentUrl": "https://pay.example.com/order123456",
    "qrCode": "https://example.com/qr/order123456.png"
  }
}
```

### 6. 查询充值订单状态
```
GET /api/recharge/status/{orderId}
```
**返回数据格式：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "orderId": "order123456",
    "status": "paid",
    "coinAmount": 100,
    "newBalance": 1100
  }
}
```

## 使用说明

### 测试步骤

1. 运行应用并进入任意直播间
2. 点击底部聊天输入框右侧的礼物图标（🎁）
3. 在弹出的礼物选择窗口中：
   - 查看顶部显示的金币余额（默认1000金币）
   - 点击"充值"按钮测试充值功能
   - 在充值对话框中选择充值金额
   - 点击"确认充值"按钮（模拟充值成功）
   - 查看余额是否增加
4. 选择礼物进行赠送：
   - 点击任意礼物进行选择
   - 使用 +/- 按钮调整赠送数量
   - 点击"赠送"按钮完成赠送
5. 观察聊天区显示的赠送消息
6. 再次打开礼物窗口，查看余额是否已扣除

### 注意事项

1. **登录检查**：赠送礼物需要登录，未登录用户会看到登录提示
2. **余额检查**：金币不足时会提示"金币余额不足，请充值"
3. **数量限制**：单次赠送数量限制为1-99个
4. **礼物选择**：必须选择礼物才能赠送，否则会提示"请选择礼物"
5. **充值选择**：必须选择充值金额才能充值，否则会提示"请选择充值金额"
6. **支付集成**：当前为模拟充值，实际使用需要集成支付SDK

## 后续优化建议

### 1. 礼物动画
- 添加礼物赠送的动画效果（如礼物飞入屏幕）
- 使用Lottie动画库实现更炫酷的效果
- 不同等级的礼物使用不同的动画效果

### 2. 礼物特效
- 高价值礼物（如火箭、跑车）添加全屏特效
- 连续赠送相同礼物时显示连击效果
- 添加音效和震动反馈

### 3. 礼物排行榜
- 显示直播间礼物贡献榜
- 显示主播收到的礼物总价值
- 显示用户赠送礼物的历史记录

### 4. 礼物墙
- 在直播间右侧显示最近的礼物赠送记录
- 滚动显示礼物消息
- 点击可查看赠送者信息

### 5. 充值功能
- 添加金币充值入口
- 集成支付SDK（微信支付、支付宝等）
- 显示充值优惠活动

### 6. 礼物分类
- 按价格分类（普通、高级、豪华）
- 按主题分类（浪漫、节日、特殊）
- 添加限时礼物和活动礼物

### 7. 社交功能
- 赠送礼物时可以添加留言
- 支持@主播或其他用户
- 礼物赠送记录可分享到社交平台

## 技术实现细节

### 1. 数据模型
```java
public class Gift {
    private String id;           // 礼物ID
    private String name;         // 礼物名称
    private int price;           // 价格（金币）
    private int iconResId;       // 本地图标资源ID
    private String iconUrl;      // 服务器图标URL
    private String description;  // 礼物描述
    private int level;           // 礼物等级（1-5星）
}
```

### 2. 适配器实现
- 使用RecyclerView + GridLayoutManager实现网格布局
- 支持礼物选中状态切换
- 使用接口回调通知选中事件

### 3. 弹窗管理
- 使用BottomSheetDialog实现底部弹窗
- 在Activity销毁时自动释放弹窗资源
- 支持点击外部区域关闭弹窗

### 4. 状态管理
- 使用局部变量管理礼物数量
- 实时更新金币余额显示
- 礼物选择状态通过Adapter管理

## 常见问题

### Q1: 礼物图标不显示？
**A:** 检查drawable资源文件是否正确创建，确保文件名和引用一致。

### Q2: 点击礼物按钮没有反应？
**A:** 检查是否已登录，未登录用户会看到登录提示。

### Q3: 赠送后金币没有扣除？
**A:** 当前使用模拟数据，金币余额存储在内存中，重启应用会重置。对接后端接口后会从服务器获取真实余额。

### Q4: 如何添加新的礼物？
**A:** 
1. 在drawable目录创建新的礼物图标XML文件
2. 在`setupGifts()`方法中添加新的Gift对象
3. 指定礼物名称、价格、图标资源ID和等级

### Q5: 如何修改礼物价格？
**A:** 在`setupGifts()`方法中修改对应Gift对象的price参数。

## 更新日志

### v1.0.0 (2024-12-24)
- ✅ 实现礼物选择弹窗
- ✅ 添加8种不同价格的礼物
- ✅ 实现礼物数量调整功能
- ✅ 实现金币余额检查
- ✅ 在聊天区显示赠送消息
- ✅ 添加登录状态检查
- ✅ 创建礼物相关图标资源

## 联系方式

如有问题或建议，请联系开发团队。

---

**文档版本**: v1.0.0  
**最后更新**: 2024年12月24日