xiaozhang/zhibo

Fork 0

ShiQi 721d588971 前后端接口对接

2025-12-29 15:12:12 +08:00

11 KiB

Raw Blame History

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

实现时间: 2024-12-29
功能: 管理员可配置主播和平台的礼物收益分成比例
状态: ✅ 已完成

📋 功能概述

系统支持灵活的礼物分成配置，管理员可以设置：

✅ 全局默认配置 - 适用于所有主播的默认分成比例
✅ 主播等级配置 - 根据主播等级设置不同的分成比例
✅ 特定主播配置 - 为特定主播设置专属分成比例
✅ 优先级机制 - 特定主播 > 主播等级 > 全局默认

🎯 配置类型说明

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. 获取配置列表

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

请求参数:

pageNum: 页码（默认1）
pageSize: 每页数量（默认20）
configType: 配置类型（可选）
status: 状态（可选）

响应示例:

{
  "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. 获取配置详情

GET /api/admin/gift/share-config/{id}

3. 创建分成配置

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. 更新分成配置

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. 删除分成配置

DELETE /api/admin/gift/share-config/{id}

注意: 全局默认配置不允许删除，只能禁用

6. 启用/禁用配置

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

参数:

status: 1=启用，0=禁用

7. 初始化默认配置

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钻石

💻 代码使用示例

在赠送礼物时使用分成配置

// 计算主播收益
BigDecimal streamerIncome = giftShareConfigService.calculateStreamerIncome(
    totalAmount,           // 礼物总价
    streamerId,            // 主播ID
    streamerLevel          // 主播等级
);

// 计算平台收益
BigDecimal platformIncome = giftShareConfigService.calculatePlatformIncome(
    totalAmount,
    streamerId,
    streamerLevel
);

log.info("礼物分成 - 总金额:{}, 主播收益:{}, 平台收益:{}", 
         totalAmount, streamerIncome, platformIncome);

获取分成比例

// 获取主播分成比例（小数形式）
BigDecimal streamerRatio = giftShareConfigService.getStreamerShareRatio(
    streamerId, 
    streamerLevel
);
// 返回: 0.70 (表示70%)

// 获取平台分成比例
BigDecimal platformRatio = giftShareConfigService.getPlatformShareRatio(
    streamerId, 
    streamerLevel
);
// 返回: 0.30 (表示30%)

🧪 测试步骤

1. 初始化默认配置

curl -X POST http://localhost:8080/api/admin/gift/share-config/init-default

预期结果:

{
  "code": 200,
  "message": "默认配置初始化成功"
}

2. 创建等级配置

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. 创建特定主播配置

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. 测试赠送礼物

# 赠送礼物给普通主播（使用全局默认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. 验证数据库

-- 查询配置列表
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. 时间段分成

// 扩展字段使用
ext_field1: "活动期间分成比例"
ext_field2: 开始时间戳
ext_field3: 结束时间戳

2. 礼物类型分成

// 不同礼物类型不同分成
普通礼物: 70%
豪华礼物: 75%
限定礼物: 80%

3. 累计消费分成

// 根据用户累计消费调整分成
消费<1000: 70%
消费1000-5000: 75%
消费>5000: 80%

4. 分成历史记录

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
);

📝 相关文件

新增文件

GiftShareConfig.java - 分成配置实体类
GiftShareConfigRequest.java - 配置请求对象
GiftShareConfigDao.java - 数据访问层
GiftShareConfigService.java - 服务接口
GiftShareConfigServiceImpl.java - 服务实现
GiftShareConfigController.java - 后台管理接口

修改文件

GiftController.java - 使用分成配置计算收益

✅ 功能检查清单

数据库表自动创建
三种配置类型支持
优先级匹配机制
分成比例验证
后台管理接口
赠送礼物集成
日志记录
异常处理
初始化默认配置
逻辑删除支持

实现完成时间: 2024-12-29
开发者: Kiro AI Assistant
状态: ✅ 生产就绪

11 KiB Raw Blame History Unescape Escape