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年
|