zhibo/Zhibo/zhibo-h/礼物分成配置管理功能说明.md

# 礼物分成配置管理功能说明

> **实现时间**: 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  
**状态**: ✅ 生产就绪