# 礼物打赏模块

## 📖 简介

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

## 🗂️ 数据库表

本模块使用以下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年