395 lines
12 KiB
Markdown
395 lines
12 KiB
Markdown
|
# 礼物打赏模块
|
|||
|
|
|
|||
|
|
## 模块概述
|
|||
|
|
礼物打赏模块负责处理直播间内的虚拟礼物赠送功能，包括礼物列表、用户余额、礼物赠送、充值等功能。
|
|||
|
|
|
|||
|
|
## 相关文件
|
|||
|
|
- `RoomDetailActivity.java` - 直播间详情（礼物赠送）
|
|||
|
|
- `Gift.java` - 礼物模型
|
|||
|
|
- `GiftAdapter.java` - 礼物列表适配器
|
|||
|
|
- `GiftResponse.java` - 礼物响应模型
|
|||
|
|
- `SendGiftRequest.java` - 赠送礼物请求模型
|
|||
|
|
- `SendGiftResponse.java` - 赠送礼物响应模型
|
|||
|
|
- `UserBalanceResponse.java` - 用户余额响应模型
|
|||
|
|
- `RechargeOption.java` - 充值选项模型
|
|||
|
|
- `RechargeAdapter.java` - 充值选项适配器
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 接口列表
|
|||
|
|
|
|||
|
|
### 1. 获取礼物列表
|
|||
|
|
**接口地址**: `GET /api/front/gift/list`
|
|||
|
|
|
|||
|
|
**请求参数**: 无
|
|||
|
|
|
|||
|
|
**返回数据**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": "integer", // 礼物ID
|
|||
|
|
"name": "string", // 礼物名称
|
|||
|
|
"price": "integer", // 礼物价格（金币）
|
|||
|
|
"icon": "string", // 礼物图标URL
|
|||
|
|
"level": "integer", // 礼物等级（1-5）
|
|||
|
|
"description": "string", // 礼物描述
|
|||
|
|
"animation": "string", // 动画效果URL
|
|||
|
|
"sort": "integer" // 排序
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2. 获取用户余额
|
|||
|
|
**接口地址**: `GET /api/front/gift/balance`
|
|||
|
|
|
|||
|
|
**请求参数**: 无
|
|||
|
|
|
|||
|
|
**返回数据** (UserBalanceResponse):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "success",
|
|||
|
|
"data": {
|
|||
|
|
"userId": "integer", // 用户ID
|
|||
|
|
"coinBalance": "integer", // 金币余额
|
|||
|
|
"totalRecharge": "integer",// 累计充值金币
|
|||
|
|
"totalConsume": "integer", // 累计消费金币
|
|||
|
|
"vipLevel": "integer" // VIP等级
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. 赠送礼物
|
|||
|
|
**接口地址**: `POST /api/front/gift/send`
|
|||
|
|
|
|||
|
|
**请求参数** (SendGiftRequest):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"giftId": "integer", // 礼物ID（必填）
|
|||
|
|
"receiverId": "integer", // 接收者ID（必填）
|
|||
|
|
"roomId": "string", // 直播间ID（必填）
|
|||
|
|
"count": "integer", // 赠送数量（必填）
|
|||
|
|
"message": "string" // 附加消息（可选）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**返回数据** (SendGiftResponse):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "赠送成功",
|
|||
|
|
"data": {
|
|||
|
|
"giftRecordId": "long", // 礼物记录ID
|
|||
|
|
"giftId": "integer", // 礼物ID
|
|||
|
|
"giftName": "string", // 礼物名称
|
|||
|
|
"count": "integer", // 赠送数量
|
|||
|
|
"totalPrice": "integer", // 总价格
|
|||
|
|
"newBalance": "integer", // 赠送后的余额
|
|||
|
|
"sendTime": "long" // 赠送时间戳
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. 获取充值选项
|
|||
|
|
**接口地址**: `GET /api/front/gift/recharge/options`
|
|||
|
|
|
|||
|
|
**请求参数**: 无
|
|||
|
|
|
|||
|
|
**返回数据**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": "string", // 选项ID
|
|||
|
|
"coinAmount": "integer", // 金币数量
|
|||
|
|
"price": "number", // 价格（元）
|
|||
|
|
"discountLabel": "string",// 优惠标签（可选）
|
|||
|
|
"isHot": "boolean", // 是否热门
|
|||
|
|
"sort": "integer" // 排序
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5. 创建充值订单
|
|||
|
|
**接口地址**: `POST /api/front/gift/recharge/create`
|
|||
|
|
|
|||
|
|
**请求参数** (CreateRechargeRequest):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"optionId": "string", // 充值选项ID（必填）
|
|||
|
|
"coinAmount": "integer", // 金币数量（必填）
|
|||
|
|
"price": "number" // 价格（必填）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**返回数据** (CreateRechargeResponse):
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "订单创建成功",
|
|||
|
|
"data": {
|
|||
|
|
"orderId": "string", // 订单ID
|
|||
|
|
"orderNo": "string", // 订单号
|
|||
|
|
"coinAmount": "integer", // 金币数量
|
|||
|
|
"price": "number", // 价格
|
|||
|
|
"paymentUrl": "string", // 支付URL
|
|||
|
|
"createTime": "long" // 创建时间
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 功能说明
|
|||
|
|
|
|||
|
|
### 礼物等级
|
|||
|
|
|
|||
|
|
| 等级 | 价格范围 | 说明 |
|
|||
|
|
|------|---------|------|
|
|||
|
|
| 1 | 1-50金币 | 普通礼物 |
|
|||
|
|
| 2 | 51-100金币 | 精美礼物 |
|
|||
|
|
| 3 | 101-500金币 | 豪华礼物 |
|
|||
|
|
| 4 | 501-1000金币 | 贵族礼物 |
|
|||
|
|
| 5 | 1000+金币 | 至尊礼物 |
|
|||
|
|
|
|||
|
|
### 赠送流程
|
|||
|
|
1. 用户点击礼物按钮
|
|||
|
|
2. 显示礼物列表和当前余额
|
|||
|
|
3. 选择礼物和数量
|
|||
|
|
4. 检查余额是否足够
|
|||
|
|
5. 调用赠送接口
|
|||
|
|
6. 扣除金币，更新余额
|
|||
|
|
7. 在直播间显示礼物动画
|
|||
|
|
8. 通过WebSocket推送给其他观众
|
|||
|
|
|
|||
|
|
### 充值流程
|
|||
|
|
1. 用户点击充值按钮
|
|||
|
|
2. 显示充值选项列表
|
|||
|
|
3. 选择充值金额
|
|||
|
|
4. 创建充值订单
|
|||
|
|
5. 选择支付方式（支付宝/微信）
|
|||
|
|
6. 调用支付接口
|
|||
|
|
7. 支付成功后更新余额
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 使用场景
|
|||
|
|
|
|||
|
|
### 1. 加载礼物列表
|
|||
|
|
```java
|
|||
|
|
private void loadGiftsFromBackend() {
|
|||
|
|
ApiService apiService = ApiClient.getService(getApplicationContext());
|
|||
|
|
Call<ApiResponse<List<GiftResponse>>> call = apiService.getGiftList();
|
|||
|
|
|
|||
|
|
call.enqueue(new Callback<ApiResponse<List<GiftResponse>>>() {
|
|||
|
|
@Override
|
|||
|
|
public void onResponse(Call<ApiResponse<List<GiftResponse>>> call,
|
|||
|
|
Response<ApiResponse<List<GiftResponse>>> response) {
|
|||
|
|
if (response.isSuccessful() && response.body() != null) {
|
|||
|
|
ApiResponse<List<GiftResponse>> apiResponse = response.body();
|
|||
|
|
if (apiResponse.getCode() == 200 && apiResponse.getData() != null) {
|
|||
|
|
availableGifts = new ArrayList<>();
|
|||
|
|
for (GiftResponse giftResponse : apiResponse.getData()) {
|
|||
|
|
Gift gift = new Gift(
|
|||
|
|
String.valueOf(giftResponse.getId()),
|
|||
|
|
giftResponse.getName(),
|
|||
|
|
giftResponse.getPrice().intValue(),
|
|||
|
|
R.drawable.ic_gift_rose,
|
|||
|
|
giftResponse.getLevel() != null ? giftResponse.getLevel() : 1
|
|||
|
|
);
|
|||
|
|
availableGifts.add(gift);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public void onFailure(Call<ApiResponse<List<GiftResponse>>> call, Throwable t) {
|
|||
|
|
Log.e("Gift", "加载礼物列表失败: " + t.getMessage());
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 获取用户余额
|
|||
|
|
```java
|
|||
|
|
private void loadUserBalance(TextView coinBalanceView) {
|
|||
|
|
ApiService apiService = ApiClient.getService(getApplicationContext());
|
|||
|
|
Call<ApiResponse<UserBalanceResponse>> call = apiService.getUserBalance();
|
|||
|
|
|
|||
|
|
call.enqueue(new Callback<ApiResponse<UserBalanceResponse>>() {
|
|||
|
|
@Override
|
|||
|
|
public void onResponse(Call<ApiResponse<UserBalanceResponse>> call,
|
|||
|
|
Response<ApiResponse<UserBalanceResponse>> response) {
|
|||
|
|
if (response.isSuccessful() && response.body() != null) {
|
|||
|
|
ApiResponse<UserBalanceResponse> apiResponse = response.body();
|
|||
|
|
if (apiResponse.getCode() == 200 && apiResponse.getData() != null) {
|
|||
|
|
userCoinBalance = apiResponse.getData().getCoinBalance().intValue();
|
|||
|
|
coinBalanceView.setText(String.valueOf(userCoinBalance));
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public void onFailure(Call<ApiResponse<UserBalanceResponse>> call, Throwable t) {
|
|||
|
|
Log.e("Gift", "获取余额失败: " + t.getMessage());
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 赠送礼物
|
|||
|
|
```java
|
|||
|
|
private void sendGiftToBackend(Gift selectedGift, int count, int totalPrice) {
|
|||
|
|
// 检查余额
|
|||
|
|
if (userCoinBalance < totalPrice) {
|
|||
|
|
Toast.makeText(this, "金币不足，请先充值", Toast.LENGTH_SHORT).show();
|
|||
|
|
showRechargeDialog();
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ApiService apiService = ApiClient.getService(getApplicationContext());
|
|||
|
|
|
|||
|
|
SendGiftRequest request = new SendGiftRequest();
|
|||
|
|
request.setGiftId(Integer.parseInt(selectedGift.getId()));
|
|||
|
|
request.setReceiverId(room.getStreamerId());
|
|||
|
|
request.setRoomId(roomId);
|
|||
|
|
request.setCount(count);
|
|||
|
|
|
|||
|
|
Call<ApiResponse<SendGiftResponse>> call = apiService.sendGift(request);
|
|||
|
|
|
|||
|
|
call.enqueue(new Callback<ApiResponse<SendGiftResponse>>() {
|
|||
|
|
@Override
|
|||
|
|
public void onResponse(Call<ApiResponse<SendGiftResponse>> call,
|
|||
|
|
Response<ApiResponse<SendGiftResponse>> response) {
|
|||
|
|
if (response.isSuccessful() && response.body() != null) {
|
|||
|
|
ApiResponse<SendGiftResponse> apiResponse = response.body();
|
|||
|
|
if (apiResponse.getCode() == 200 && apiResponse.getData() != null) {
|
|||
|
|
SendGiftResponse giftResponse = apiResponse.getData();
|
|||
|
|
|
|||
|
|
// 更新余额
|
|||
|
|
userCoinBalance = giftResponse.getNewBalance().intValue();
|
|||
|
|
|
|||
|
|
// 显示赠送消息
|
|||
|
|
String giftMessage = String.format("送出了 %d 个 %s",
|
|||
|
|
count, selectedGift.getName());
|
|||
|
|
addChatMessage(new ChatMessage("我", giftMessage, true));
|
|||
|
|
|
|||
|
|
Toast.makeText(RoomDetailActivity.this,
|
|||
|
|
"赠送成功！", Toast.LENGTH_SHORT).show();
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public void onFailure(Call<ApiResponse<SendGiftResponse>> call, Throwable t) {
|
|||
|
|
Toast.makeText(RoomDetailActivity.this,
|
|||
|
|
"网络错误: " + t.getMessage(), Toast.LENGTH_SHORT).show();
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 创建充值订单
|
|||
|
|
```java
|
|||
|
|
private void createRechargeOrder(RechargeOption selectedOption) {
|
|||
|
|
ApiService apiService = ApiClient.getService(getApplicationContext());
|
|||
|
|
|
|||
|
|
CreateRechargeRequest request = new CreateRechargeRequest();
|
|||
|
|
request.setOptionId(selectedOption.getId());
|
|||
|
|
request.setCoinAmount(selectedOption.getCoinAmount());
|
|||
|
|
request.setPrice(selectedOption.getPrice());
|
|||
|
|
|
|||
|
|
Call<ApiResponse<CreateRechargeResponse>> call =
|
|||
|
|
apiService.createRecharge(request);
|
|||
|
|
|
|||
|
|
call.enqueue(new Callback<ApiResponse<CreateRechargeResponse>>() {
|
|||
|
|
@Override
|
|||
|
|
public void onResponse(Call<ApiResponse<CreateRechargeResponse>> call,
|
|||
|
|
Response<ApiResponse<CreateRechargeResponse>> response) {
|
|||
|
|
if (response.isSuccessful() && response.body() != null) {
|
|||
|
|
ApiResponse<CreateRechargeResponse> apiResponse = response.body();
|
|||
|
|
if (apiResponse.getCode() == 200 && apiResponse.getData() != null) {
|
|||
|
|
CreateRechargeResponse rechargeResponse = apiResponse.getData();
|
|||
|
|
String orderId = rechargeResponse.getOrderId();
|
|||
|
|
|
|||
|
|
// 显示支付选择对话框
|
|||
|
|
showPaymentMethodDialog(orderId, selectedOption);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public void onFailure(Call<ApiResponse<CreateRechargeResponse>> call, Throwable t) {
|
|||
|
|
Toast.makeText(RoomDetailActivity.this,
|
|||
|
|
"网络错误: " + t.getMessage(), Toast.LENGTH_SHORT).show();
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## WebSocket推送
|
|||
|
|
|
|||
|
|
礼物赠送后会通过WebSocket推送给直播间内的所有用户，用于显示礼物动画。
|
|||
|
|
|
|||
|
|
**推送消息格式**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "gift",
|
|||
|
|
"giftId": 1,
|
|||
|
|
"giftName": "玫瑰",
|
|||
|
|
"count": 10,
|
|||
|
|
"senderId": 123,
|
|||
|
|
"senderNickname": "张三",
|
|||
|
|
"receiverId": 456,
|
|||
|
|
"receiverNickname": "主播",
|
|||
|
|
"roomId": "room123"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 默认礼物列表
|
|||
|
|
|
|||
|
|
如果接口加载失败，可以使用以下默认礼物：
|
|||
|
|
|
|||
|
|
| ID | 名称 | 价格 | 等级 |
|
|||
|
|
|----|------|------|------|
|
|||
|
|
| 1 | 玫瑰 | 10 | 1 |
|
|||
|
|
| 2 | 爱心 | 20 | 1 |
|
|||
|
|
| 3 | 蛋糕 | 50 | 2 |
|
|||
|
|
| 4 | 星星 | 100 | 2 |
|
|||
|
|
| 5 | 钻石 | 200 | 3 |
|
|||
|
|
| 6 | 皇冠 | 500 | 4 |
|
|||
|
|
| 7 | 跑车 | 1000 | 5 |
|
|||
|
|
| 8 | 火箭 | 2000 | 5 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
1. 所有接口都需要登录认证
|
|||
|
|
2. 赠送礼物前必须检查余额是否足够
|
|||
|
|
3. 礼物价格以金币为单位，不是人民币
|
|||
|
|
4. 充值需要集成第三方支付SDK（支付宝/微信）
|
|||
|
|
5. 礼物动画效果需要前端实现
|
|||
|
|
6. 建议缓存礼物列表，减少网络请求
|
|||
|
|
7. 余额变化后及时更新UI显示
|
|||
|
|
8. 赠送失败时不扣除金币
|