502 lines
11 KiB
Markdown
502 lines
11 KiB
Markdown
# 礼物分成配置管理功能说明
|
||
|
||
> **实现时间**: 2024-12-29
|
||
> **功能**: 管理员可配置主播和平台的礼物收益分成比例
|
||
> **状态**: ✅ 已完成
|
||
|
||
---
|
||
|
||
## 📋 功能概述
|
||
|
||
系统支持灵活的礼物分成配置，管理员可以设置：
|
||
|
||
1. ✅ **全局默认配置** - 适用于所有主播的默认分成比例
|
||
2. ✅ **主播等级配置** - 根据主播等级设置不同的分成比例
|
||
3. ✅ **特定主播配置** - 为特定主播设置专属分成比例
|
||
4. ✅ **优先级机制** - 特定主播 > 主播等级 > 全局默认
|
||
|
||
---
|
||
|
||
## 🎯 配置类型说明
|
||
|
||
### 1. 全局默认配置 (config_type = 1)
|
||
|
||
- **适用范围**: 所有主播
|
||
- **优先级**: 最低
|
||
- **示例**: 主播70%，平台30%
|
||
- **说明**: 当主播没有专属配置时使用
|
||
|
||
### 2. 主播等级配置 (config_type = 2)
|
||
|
||
- **适用范围**: 指定等级的所有主播
|
||
- **优先级**: 中等
|
||
- **示例**:
|
||
- 等级1-3: 主播60%，平台40%
|
||
- 等级4-6: 主播70%，平台30%
|
||
- 等级7-10: 主播80%，平台20%
|
||
|
||
### 3. 特定主播配置 (config_type = 3)
|
||
|
||
- **适用范围**: 指定的单个主播
|
||
- **优先级**: 最高
|
||
- **示例**: 头部主播可获得85%分成
|
||
- **说明**: 用于签约主播或特殊合作
|
||
|
||
---
|
||
|
||
## 🔧 数据库表结构
|
||
|
||
### eb_gift_share_config 表
|
||
|
||
| 字段 | 类型 | 说明 | 示例 |
|
||
|------|------|------|------|
|
||
| id | INT | 主键ID | 1 |
|
||
| config_name | VARCHAR(100) | 配置名称 | "默认分成配置" |
|
||
| config_type | TINYINT | 配置类型 | 1=全局 2=等级 3=特定 |
|
||
| user_id | INT | 用户ID | 100（type=3时） |
|
||
| user_level | INT | 用户等级 | 5（type=2时） |
|
||
| streamer_ratio | DECIMAL(5,2) | 主播分成比例 | 70.00 |
|
||
| platform_ratio | DECIMAL(5,2) | 平台分成比例 | 30.00 |
|
||
| status | TINYINT | 状态 | 1=启用 0=禁用 |
|
||
| priority | INT | 优先级 | 数字越大优先级越高 |
|
||
| description | VARCHAR(500) | 配置说明 | "全局默认配置" |
|
||
| is_deleted | TINYINT | 逻辑删除 | 0=未删除 1=已删除 |
|
||
| create_time | DATETIME | 创建时间 | 2024-12-29 |
|
||
| update_time | DATETIME | 更新时间 | 2024-12-29 |
|
||
|
||
---
|
||
|
||
## 📡 后台管理接口
|
||
|
||
### 1. 获取配置列表
|
||
|
||
```http
|
||
GET /api/admin/gift/share-config/list?pageNum=1&pageSize=20&configType=1&status=1
|
||
```
|
||
|
||
**请求参数**:
|
||
- `pageNum`: 页码（默认1）
|
||
- `pageSize`: 每页数量（默认20）
|
||
- `configType`: 配置类型（可选）
|
||
- `status`: 状态（可选）
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"configName": "全局默认分成配置",
|
||
"configType": 1,
|
||
"streamerRatio": 70.00,
|
||
"platformRatio": 30.00,
|
||
"status": 1,
|
||
"priority": 0,
|
||
"description": "系统默认分成配置"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"pageNum": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取配置详情
|
||
|
||
```http
|
||
GET /api/admin/gift/share-config/{id}
|
||
```
|
||
|
||
### 3. 创建分成配置
|
||
|
||
```http
|
||
POST /api/admin/gift/share-config/create
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"configName": "VIP主播分成配置",
|
||
"configType": 2,
|
||
"userLevel": 5,
|
||
"streamerRatio": 80.00,
|
||
"platformRatio": 20.00,
|
||
"status": 1,
|
||
"priority": 10,
|
||
"description": "等级5以上的VIP主播可获得80%分成"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `configName`: 配置名称（必填）
|
||
- `configType`: 配置类型（必填，1/2/3）
|
||
- `userId`: 用户ID（type=3时必填）
|
||
- `userLevel`: 用户等级（type=2时必填）
|
||
- `streamerRatio`: 主播分成比例（必填，0-100）
|
||
- `platformRatio`: 平台分成比例（必填，0-100）
|
||
- `status`: 状态（可选，默认1）
|
||
- `priority`: 优先级（可选，默认0）
|
||
- `description`: 配置说明（可选）
|
||
|
||
**验证规则**:
|
||
- ✅ `streamerRatio + platformRatio = 100`
|
||
- ✅ type=2时必须指定userLevel
|
||
- ✅ type=3时必须指定userId
|
||
- ✅ 不允许重复创建相同配置
|
||
|
||
### 4. 更新分成配置
|
||
|
||
```http
|
||
PUT /api/admin/gift/share-config/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"configName": "全局默认分成配置",
|
||
"configType": 1,
|
||
"streamerRatio": 75.00,
|
||
"platformRatio": 25.00,
|
||
"status": 1,
|
||
"priority": 0,
|
||
"description": "调整为主播75%，平台25%"
|
||
}
|
||
```
|
||
|
||
### 5. 删除分成配置
|
||
|
||
```http
|
||
DELETE /api/admin/gift/share-config/{id}
|
||
```
|
||
|
||
**注意**: 全局默认配置不允许删除，只能禁用
|
||
|
||
### 6. 启用/禁用配置
|
||
|
||
```http
|
||
PUT /api/admin/gift/share-config/{id}/status?status=1
|
||
```
|
||
|
||
**参数**:
|
||
- `status`: 1=启用，0=禁用
|
||
|
||
### 7. 初始化默认配置
|
||
|
||
```http
|
||
POST /api/admin/gift/share-config/init-default
|
||
```
|
||
|
||
**说明**: 创建系统默认配置（主播70%，平台30%）
|
||
|
||
---
|
||
|
||
## 🔄 分成计算逻辑
|
||
|
||
### 优先级匹配规则
|
||
|
||
```
|
||
用户赠送礼物
|
||
↓
|
||
查询分成配置（按优先级）
|
||
↓
|
||
1. 查找特定主播配置（config_type=3, user_id=主播ID）
|
||
↓ 未找到
|
||
2. 查找主播等级配置（config_type=2, user_level=主播等级）
|
||
↓ 未找到
|
||
3. 使用全局默认配置（config_type=1）
|
||
↓ 未找到
|
||
4. 使用硬编码默认值（主播70%，平台30%）
|
||
```
|
||
|
||
### 计算示例
|
||
|
||
**场景1：普通主播（使用全局默认配置）**
|
||
```
|
||
礼物总价: 100钻石
|
||
全局配置: 主播70%，平台30%
|
||
|
||
主播收益 = 100 × 0.70 = 70钻石
|
||
平台收益 = 100 × 0.30 = 30钻石
|
||
```
|
||
|
||
**场景2：VIP主播（使用等级配置）**
|
||
```
|
||
礼物总价: 100钻石
|
||
主播等级: 5
|
||
等级配置: 主播80%，平台20%
|
||
|
||
主播收益 = 100 × 0.80 = 80钻石
|
||
平台收益 = 100 × 0.20 = 20钻石
|
||
```
|
||
|
||
**场景3：签约主播（使用特定主播配置）**
|
||
```
|
||
礼物总价: 100钻石
|
||
主播ID: 1001
|
||
特定配置: 主播85%，平台15%
|
||
|
||
主播收益 = 100 × 0.85 = 85钻石
|
||
平台收益 = 100 × 0.15 = 15钻石
|
||
```
|
||
|
||
---
|
||
|
||
## 💻 代码使用示例
|
||
|
||
### 在赠送礼物时使用分成配置
|
||
|
||
```java
|
||
// 计算主播收益
|
||
BigDecimal streamerIncome = giftShareConfigService.calculateStreamerIncome(
|
||
totalAmount, // 礼物总价
|
||
streamerId, // 主播ID
|
||
streamerLevel // 主播等级
|
||
);
|
||
|
||
// 计算平台收益
|
||
BigDecimal platformIncome = giftShareConfigService.calculatePlatformIncome(
|
||
totalAmount,
|
||
streamerId,
|
||
streamerLevel
|
||
);
|
||
|
||
log.info("礼物分成 - 总金额:{}, 主播收益:{}, 平台收益:{}",
|
||
totalAmount, streamerIncome, platformIncome);
|
||
```
|
||
|
||
### 获取分成比例
|
||
|
||
```java
|
||
// 获取主播分成比例（小数形式）
|
||
BigDecimal streamerRatio = giftShareConfigService.getStreamerShareRatio(
|
||
streamerId,
|
||
streamerLevel
|
||
);
|
||
// 返回: 0.70 (表示70%)
|
||
|
||
// 获取平台分成比例
|
||
BigDecimal platformRatio = giftShareConfigService.getPlatformShareRatio(
|
||
streamerId,
|
||
streamerLevel
|
||
);
|
||
// 返回: 0.30 (表示30%)
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试步骤
|
||
|
||
### 1. 初始化默认配置
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/admin/gift/share-config/init-default
|
||
```
|
||
|
||
**预期结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "默认配置初始化成功"
|
||
}
|
||
```
|
||
|
||
### 2. 创建等级配置
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/admin/gift/share-config/create \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"configName": "高级主播分成",
|
||
"configType": 2,
|
||
"userLevel": 5,
|
||
"streamerRatio": 80.00,
|
||
"platformRatio": 20.00,
|
||
"status": 1,
|
||
"priority": 10,
|
||
"description": "等级5以上主播获得80%分成"
|
||
}'
|
||
```
|
||
|
||
### 3. 创建特定主播配置
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/admin/gift/share-config/create \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"configName": "签约主播专属分成",
|
||
"configType": 3,
|
||
"userId": 1001,
|
||
"streamerRatio": 85.00,
|
||
"platformRatio": 15.00,
|
||
"status": 1,
|
||
"priority": 20,
|
||
"description": "签约主播ID 1001的专属分成"
|
||
}'
|
||
```
|
||
|
||
### 4. 测试赠送礼物
|
||
|
||
```bash
|
||
# 赠送礼物给普通主播（使用全局默认70%）
|
||
curl -X POST http://localhost:8080/api/front/gift/send \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer {token}" \
|
||
-d '{
|
||
"roomId": 1,
|
||
"streamerId": 100,
|
||
"giftId": 1,
|
||
"count": 10
|
||
}'
|
||
```
|
||
|
||
**查看日志**:
|
||
```
|
||
礼物分成 - 总金额:100, 主播收益:70, 平台收益:30
|
||
```
|
||
|
||
### 5. 验证数据库
|
||
|
||
```sql
|
||
-- 查询配置列表
|
||
SELECT * FROM eb_gift_share_config WHERE is_deleted = 0;
|
||
|
||
-- 查询礼物记录
|
||
SELECT * FROM eb_gift_record ORDER BY create_time DESC LIMIT 10;
|
||
|
||
-- 查询用户账单
|
||
SELECT * FROM eb_user_bill WHERE category = 'gift' ORDER BY create_time DESC LIMIT 10;
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 配置示例
|
||
|
||
### 示例1：标准分成体系
|
||
|
||
| 配置名称 | 类型 | 条件 | 主播% | 平台% | 优先级 |
|
||
|---------|------|------|-------|-------|--------|
|
||
| 全局默认 | 全局 | - | 70 | 30 | 0 |
|
||
| 新手主播 | 等级 | 等级1-2 | 60 | 40 | 5 |
|
||
| 普通主播 | 等级 | 等级3-5 | 70 | 30 | 10 |
|
||
| 高级主播 | 等级 | 等级6-8 | 80 | 20 | 15 |
|
||
| 顶级主播 | 等级 | 等级9-10 | 85 | 15 | 20 |
|
||
|
||
### 示例2：签约主播体系
|
||
|
||
| 配置名称 | 类型 | 主播ID | 主播% | 平台% | 优先级 |
|
||
|---------|------|--------|-------|-------|--------|
|
||
| 签约主播A | 特定 | 1001 | 90 | 10 | 100 |
|
||
| 签约主播B | 特定 | 1002 | 85 | 15 | 100 |
|
||
| 签约主播C | 特定 | 1003 | 88 | 12 | 100 |
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 分成比例验证
|
||
|
||
- ✅ 主播分成 + 平台分成 = 100%
|
||
- ✅ 创建和更新时自动验证
|
||
- ❌ 不符合规则会返回错误
|
||
|
||
### 2. 配置优先级
|
||
|
||
- 数字越大优先级越高
|
||
- 相同优先级时，按配置类型排序（特定>等级>全局）
|
||
- 建议：全局0，等级5-20，特定100+
|
||
|
||
### 3. 全局默认配置
|
||
|
||
- 至少保留一个启用的全局默认配置
|
||
- 不允许删除全局默认配置
|
||
- 可以禁用后创建新的全局配置
|
||
|
||
### 4. 性能优化
|
||
|
||
- 分成配置会被频繁查询
|
||
- 建议添加Redis缓存
|
||
- 配置更新时清除缓存
|
||
|
||
---
|
||
|
||
## 🚀 扩展功能建议
|
||
|
||
### 1. 时间段分成
|
||
|
||
```java
|
||
// 扩展字段使用
|
||
ext_field1: "活动期间分成比例"
|
||
ext_field2: 开始时间戳
|
||
ext_field3: 结束时间戳
|
||
```
|
||
|
||
### 2. 礼物类型分成
|
||
|
||
```java
|
||
// 不同礼物类型不同分成
|
||
普通礼物: 70%
|
||
豪华礼物: 75%
|
||
限定礼物: 80%
|
||
```
|
||
|
||
### 3. 累计消费分成
|
||
|
||
```java
|
||
// 根据用户累计消费调整分成
|
||
消费<1000: 70%
|
||
消费1000-5000: 75%
|
||
消费>5000: 80%
|
||
```
|
||
|
||
### 4. 分成历史记录
|
||
|
||
```sql
|
||
CREATE TABLE eb_gift_share_history (
|
||
id BIGINT PRIMARY KEY,
|
||
record_id BIGINT,
|
||
config_id INT,
|
||
streamer_income DECIMAL(10,2),
|
||
platform_income DECIMAL(10,2),
|
||
create_time DATETIME
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 相关文件
|
||
|
||
### 新增文件
|
||
|
||
1. `GiftShareConfig.java` - 分成配置实体类
|
||
2. `GiftShareConfigRequest.java` - 配置请求对象
|
||
3. `GiftShareConfigDao.java` - 数据访问层
|
||
4. `GiftShareConfigService.java` - 服务接口
|
||
5. `GiftShareConfigServiceImpl.java` - 服务实现
|
||
6. `GiftShareConfigController.java` - 后台管理接口
|
||
|
||
### 修改文件
|
||
|
||
1. `GiftController.java` - 使用分成配置计算收益
|
||
|
||
---
|
||
|
||
## ✅ 功能检查清单
|
||
|
||
- [x] 数据库表自动创建
|
||
- [x] 三种配置类型支持
|
||
- [x] 优先级匹配机制
|
||
- [x] 分成比例验证
|
||
- [x] 后台管理接口
|
||
- [x] 赠送礼物集成
|
||
- [x] 日志记录
|
||
- [x] 异常处理
|
||
- [x] 初始化默认配置
|
||
- [x] 逻辑删除支持
|
||
|
||
---
|
||
|
||
**实现完成时间**: 2024-12-29
|
||
**开发者**: Kiro AI Assistant
|
||
**状态**: ✅ 生产就绪
|