203 lines
4.1 KiB
Markdown
203 lines
4.1 KiB
Markdown
|
# 礼物打赏模块
|
|||
|
|
|
|||
|
|
## 📖 简介
|
|||
|
|
|
|||
|
|
礼物打赏模块是直播系统的核心功能之一，允许用户在直播间或私聊中向主播赠送虚拟礼物。本模块基于现有数据库表结构实现，完全兼容你的数据库设计。
|
|||
|
|
|
|||
|
|
## 🗂️ 数据库表
|
|||
|
|
|
|||
|
|
本模块使用以下4个数据库表：
|
|||
|
|
|
|||
|
|
| 表名 | 说明 | 用途 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `eb_gift` | 礼物表 | 存储礼物的基本信息 |
|
|||
|
|
| `eb_gift_reward_record` | 礼物打赏记录表 | 记录每次打赏的详细信息 |
|
|||
|
|
| `eb_gift_detail` | 送礼物明细表 | 记录送礼的详细明细 |
|
|||
|
|
| `eb_gift_quantity` | 礼物数量列表 | 充值选项配置 |
|
|||
|
|
|
|||
|
|
## 🚀 快速开始
|
|||
|
|
|
|||
|
|
### 1. 插入测试数据
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 在MySQL中执行
|
|||
|
|
mysql -u root -p your_database < sql/gift_test_data.sql
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 启动服务
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd crmeb-admin
|
|||
|
|
mvn spring-boot:run
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 测试接口
|
|||
|
|
|
|||
|
|
访问 Swagger 文档：http://localhost:8081/doc.html
|
|||
|
|
|
|||
|
|
或使用测试脚本：
|
|||
|
|
```bash
|
|||
|
|
# Windows
|
|||
|
|
test_gift_api.bat
|
|||
|
|
|
|||
|
|
# Linux/Mac
|
|||
|
|
./test_gift_api.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📡 API接口
|
|||
|
|
|
|||
|
|
### 1. 获取礼物列表
|
|||
|
|
```
|
|||
|
|
GET /api/front/gift/list
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 获取用户余额
|
|||
|
|
```
|
|||
|
|
GET /api/front/gift/balance
|
|||
|
|
需要登录
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 赠送礼物
|
|||
|
|
```
|
|||
|
|
POST /api/front/gift/send
|
|||
|
|
需要登录
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 获取充值选项
|
|||
|
|
```
|
|||
|
|
GET /api/front/gift/recharge/options
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. 创建充值订单
|
|||
|
|
```
|
|||
|
|
POST /api/front/gift/recharge/create
|
|||
|
|
需要登录
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📚 文档
|
|||
|
|
|
|||
|
|
- [开发说明](./礼物打赏模块开发说明.md) - 详细的技术文档
|
|||
|
|
- [快速开始](./礼物打赏模块快速开始.md) - 部署和测试指南
|
|||
|
|
- [实现总结](../礼物打赏模块实现总结.md) - 功能总结和统计
|
|||
|
|
|
|||
|
|
## 🔧 配置
|
|||
|
|
|
|||
|
|
### 数据库配置
|
|||
|
|
|
|||
|
|
确保 `application.yml` 中的数据库配置正确：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
spring:
|
|||
|
|
datasource:
|
|||
|
|
url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf-8
|
|||
|
|
username: your_username
|
|||
|
|
password: your_password
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 端口配置
|
|||
|
|
|
|||
|
|
默认端口：8081
|
|||
|
|
|
|||
|
|
如需修改，在 `application.yml` 中配置：
|
|||
|
|
```yaml
|
|||
|
|
server:
|
|||
|
|
port: 8081
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🧪 测试
|
|||
|
|
|
|||
|
|
### 使用Postman
|
|||
|
|
|
|||
|
|
1. 导入 `礼物打赏API测试集合.postman_collection.json`
|
|||
|
|
2. 设置环境变量：
|
|||
|
|
- `base_url`: http://localhost:8081
|
|||
|
|
- `token`: 你的登录token
|
|||
|
|
3. 运行测试
|
|||
|
|
|
|||
|
|
### 使用curl
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 获取礼物列表
|
|||
|
|
curl http://localhost:8081/api/front/gift/list
|
|||
|
|
|
|||
|
|
# 获取充值选项
|
|||
|
|
curl http://localhost:8081/api/front/gift/recharge/options
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📊 数据流程
|
|||
|
|
|
|||
|
|
### 礼物赠送流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
用户选择礼物
|
|||
|
|
↓
|
|||
|
|
验证登录状态
|
|||
|
|
↓
|
|||
|
|
验证礼物存在
|
|||
|
|
↓
|
|||
|
|
计算总金额
|
|||
|
|
↓
|
|||
|
|
检查余额
|
|||
|
|
↓
|
|||
|
|
扣除用户余额
|
|||
|
|
↓
|
|||
|
|
保存打赏记录 (eb_gift_reward_record)
|
|||
|
|
↓
|
|||
|
|
保存用户账单 (eb_user_bill)
|
|||
|
|
↓
|
|||
|
|
增加主播收益
|
|||
|
|
↓
|
|||
|
|
保存主播账单 (eb_user_bill)
|
|||
|
|
↓
|
|||
|
|
返回结果
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ⚠️ 注意事项
|
|||
|
|
|
|||
|
|
1. **充值功能**：当前返回模拟数据，需要集成真实支付SDK
|
|||
|
|
2. **分成比例**：当前主播收益100%，实际应按平台规则分成
|
|||
|
|
3. **并发控制**：高并发场景需要使用Redis锁
|
|||
|
|
4. **WebSocket**：礼物赠送后应推送消息到直播间
|
|||
|
|
|
|||
|
|
## 🔐 安全建议
|
|||
|
|
|
|||
|
|
1. 所有接口都需要验证用户登录状态
|
|||
|
|
2. 严格验证金额，防止篡改
|
|||
|
|
3. 限制用户赠送礼物的频率
|
|||
|
|
4. 使用数据库行锁或Redis锁防止超额扣款
|
|||
|
|
5. 记录所有金额变动操作
|
|||
|
|
|
|||
|
|
## 📈 后续优化
|
|||
|
|
|
|||
|
|
- [ ] 集成支付SDK（微信支付、支付宝）
|
|||
|
|
- [ ] 实现平台分成逻辑
|
|||
|
|
- [ ] 添加WebSocket推送
|
|||
|
|
- [ ] 实现礼物动画
|
|||
|
|
- [ ] 添加礼物排行榜
|
|||
|
|
- [ ] 实现连击功能
|
|||
|
|
- [ ] 使用 eb_gift_detail 表记录详细信息
|
|||
|
|
|
|||
|
|
## 🐛 问题排查
|
|||
|
|
|
|||
|
|
### 接口返回401
|
|||
|
|
- 检查是否传递了token
|
|||
|
|
- 检查token是否有效
|
|||
|
|
|
|||
|
|
### 余额不足
|
|||
|
|
- 查询用户余额：`SELECT now_money FROM eb_user WHERE uid = ?`
|
|||
|
|
- 手动充值：`UPDATE eb_user SET now_money = 1000 WHERE uid = ?`
|
|||
|
|
|
|||
|
|
### 找不到礼物
|
|||
|
|
- 检查礼物是否存在：`SELECT * FROM eb_gift WHERE id = ?`
|
|||
|
|
- 检查礼物状态：`status = 1` 表示启用
|
|||
|
|
|
|||
|
|
## 📞 技术支持
|
|||
|
|
|
|||
|
|
如有问题，请查看详细文档或联系开发团队。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**版本**: v1.0
|
|||
|
|
**状态**: ✅ 已完成
|
|||
|
|
**最后更新**: 2024年
|