zhibo/Zhibo/zhibo-h/礼物打赏模块README.md

礼物打赏模块

📖 简介

礼物打赏模块是直播系统的核心功能之一，允许用户在直播间或私聊中向主播赠送虚拟礼物。本模块基于现有数据库表结构实现，完全兼容你的数据库设计。

🗂️ 数据库表

本模块使用以下4个数据库表：

表名	说明	用途
eb_gift	礼物表	存储礼物的基本信息
eb_gift_reward_record	礼物打赏记录表	记录每次打赏的详细信息
eb_gift_detail	送礼物明细表	记录送礼的详细明细
eb_gift_quantity	礼物数量列表	充值选项配置

🚀 快速开始

1. 插入测试数据

# 在MySQL中执行
mysql -u root -p your_database < sql/gift_test_data.sql

2. 启动服务

cd crmeb-admin
mvn spring-boot:run

3. 测试接口

访问 Swagger 文档：http://localhost:8081/doc.html

或使用测试脚本：

# 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
需要登录

📚 文档

• 开发说明 - 详细的技术文档
• 快速开始 - 部署和测试指南
• 实现总结 - 功能总结和统计

🔧 配置

数据库配置

确保 application.yml 中的数据库配置正确：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf-8
    username: your_username
    password: your_password

端口配置

默认端口：8081

如需修改，在 application.yml 中配置：

server:
  port: 8081

🧪 测试

使用Postman

1. 导入 礼物打赏API测试集合.postman_collection.json
2. 设置环境变量：
   • base_url: http://localhost:8081
   • token: 你的登录token
3. 运行测试

使用curl

# 获取礼物列表
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年