zhibo/Zhibo/zhibo-h/礼物分成配置快速指南.md

# 礼物分成配置快速指南

## 🚀 5分钟快速上手

### 步骤1：初始化默认配置

```bash
POST /api/admin/gift/share-config/init-default
```

这将创建默认配置：主播70%，平台30%

### 步骤2：查看配置列表

```bash
GET /api/admin/gift/share-config/list
```

### 步骤3：创建自定义配置

**为VIP主播设置80%分成**:
```json
POST /api/admin/gift/share-config/create
{
  "configName": "VIP主播分成",
  "configType": 2,
  "userLevel": 5,
  "streamerRatio": 80.00,
  "platformRatio": 20.00,
  "status": 1
}
```

**为签约主播设置85%分成**:
```json
POST /api/admin/gift/share-config/create
{
  "configName": "签约主播分成",
  "configType": 3,
  "userId": 1001,
  "streamerRatio": 85.00,
  "platformRatio": 15.00,
  "status": 1
}
```

---

## 📊 配置类型对照表

| 类型 | config_type | 必填字段 | 示例 |
|------|-------------|---------|------|
| 全局默认 | 1 | - | 所有主播默认70% |
| 主播等级 | 2 | userLevel | 等级5主播80% |
| 特定主播 | 3 | userId | 主播1001获得85% |

---

## ⚡ 常用操作

### 修改全局默认分成

```json
PUT /api/admin/gift/share-config/update
{
  "id": 1,
  "configName": "全局默认分成配置",
  "configType": 1,
  "streamerRatio": 75.00,
  "platformRatio": 25.00
}
```

### 禁用某个配置

```bash
PUT /api/admin/gift/share-config/1/status?status=0
```

### 启用某个配置

```bash
PUT /api/admin/gift/share-config/1/status?status=1
```

### 删除配置

```bash
DELETE /api/admin/gift/share-config/2
```

注意：全局默认配置不能删除

---

## 🔍 查询配置

### 查询所有配置

```bash
GET /api/admin/gift/share-config/list?pageNum=1&pageSize=20
```

### 只查询启用的配置

```bash
GET /api/admin/gift/share-config/list?status=1
```

### 只查询等级配置

```bash
GET /api/admin/gift/share-config/list?configType=2
```

### 查询单个配置详情

```bash
GET /api/admin/gift/share-config/1
```

---

## 💡 最佳实践

### 1. 推荐的分成体系

```
新手主播（等级1-2）: 60% / 40%
普通主播（等级3-5）: 70% / 30%
高级主播（等级6-8）: 80% / 20%
顶级主播（等级9-10）: 85% / 15%
签约主播（特定）: 90% / 10%
```

### 2. 优先级设置建议

```
全局默认: priority = 0
等级配置: priority = 5-20
特定主播: priority = 100+
```

### 3. 配置命名规范

```
全局默认: "全局默认分成配置"
等级配置: "等级{X}主播分成配置"
特定主播: "{主播昵称}专属分成配置"
```

---

## ❌ 常见错误

### 错误1：分成比例不等于100%

```json
{
  "code": 500,
  "message": "主播分成比例和平台分成比例之和必须等于100%"
}
```

**解决**: 确保 `streamerRatio + platformRatio = 100`

### 错误2：缺少必填字段

```json
{
  "code": 500,
  "message": "主播等级配置必须指定用户等级"
}
```

**解决**: 
- type=2时必须填写`userLevel`
- type=3时必须填写`userId`

### 错误3：重复创建配置

```json
{
  "code": 500,
  "message": "该配置已存在，请勿重复创建"
}
```

**解决**: 使用更新接口而不是创建接口

---

## 🧪 测试验证

### 1. 验证配置生效

```bash
# 赠送礼物
POST /api/front/gift/send
{
  "roomId": 1,
  "streamerId": 100,
  "giftId": 1,
  "count": 10
}

# 查看后端日志
礼物分成 - 总金额:100, 主播收益:70, 平台收益:30
```

### 2. 验证优先级

```sql
-- 查询主播的分成配置
SELECT * FROM eb_gift_share_config 
WHERE status = 1 AND is_deleted = 0 
AND (
  (config_type = 3 AND user_id = 100) OR 
  (config_type = 2 AND user_level = 5) OR 
  (config_type = 1)
) 
ORDER BY priority DESC, config_type DESC 
LIMIT 1;
```

---

## 📱 前端集成示例

### 显示分成比例

```javascript
// 获取配置列表
fetch('/api/admin/gift/share-config/list')
  .then(res => res.json())
  .then(data => {
    data.data.list.forEach(config => {
      console.log(`${config.configName}: 主播${config.streamerRatio}% 平台${config.platformRatio}%`);
    });
  });
```

### 创建配置表单

```html
<form id="configForm">
  <input name="configName" placeholder="配置名称" required>
  <select name="configType" required>
    <option value="1">全局默认</option>
    <option value="2">主播等级</option>
    <option value="3">特定主播</option>
  </select>
  <input name="streamerRatio" type="number" placeholder="主播分成%" required>
  <input name="platformRatio" type="number" placeholder="平台分成%" required>
  <button type="submit">创建</button>
</form>
```

---

## 🎯 快速参考

### 接口列表

| 接口 | 方法 | 说明 |
|------|------|------|
| `/list` | GET | 获取配置列表 |
| `/{id}` | GET | 获取配置详情 |
| `/create` | POST | 创建配置 |
| `/update` | PUT | 更新配置 |
| `/{id}` | DELETE | 删除配置 |
| `/{id}/status` | PUT | 启用/禁用 |
| `/init-default` | POST | 初始化默认配置 |

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| configName | String | ✅ | 配置名称 |
| configType | Integer | ✅ | 1/2/3 |
| userId | Integer | ⚠️ | type=3时必填 |
| userLevel | Integer | ⚠️ | type=2时必填 |
| streamerRatio | Decimal | ✅ | 0-100 |
| platformRatio | Decimal | ✅ | 0-100 |
| status | Integer | ❌ | 默认1 |
| priority | Integer | ❌ | 默认0 |

---

**创建时间**: 2024-12-29  
**适用版本**: v1.0