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

礼物分成配置快速指南

🚀 5分钟快速上手

步骤1：初始化默认配置

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

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

步骤2：查看配置列表

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

步骤3：创建自定义配置

为VIP主播设置80%分成:

POST /api/admin/gift/share-config/create
{
  "configName": "VIP主播分成",
  "configType": 2,
  "userLevel": 5,
  "streamerRatio": 80.00,
  "platformRatio": 20.00,
  "status": 1
}

为签约主播设置85%分成:

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%

---

⚡ 常用操作

修改全局默认分成

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

禁用某个配置

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

启用某个配置

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

删除配置

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

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

---

🔍 查询配置

查询所有配置

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

只查询启用的配置

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

只查询等级配置

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

查询单个配置详情

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%

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

解决: 确保 streamerRatio + platformRatio = 100

错误2：缺少必填字段

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

解决:

• type=2时必须填写userLevel
• type=3时必须填写userId

错误3：重复创建配置

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

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

---

🧪 测试验证

1. 验证配置生效

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

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

2. 验证优先级

-- 查询主播的分成配置
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;

---

📱 前端集成示例

显示分成比例

// 获取配置列表
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}%`);
    });
  });

创建配置表单

<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