531 lines
13 KiB
Markdown
531 lines
13 KiB
Markdown
# 推广收益配置API接口文档
|
||
|
||
## 概述
|
||
|
||
本文档详细说明了推广收益配置的管理端和用户端API接口，包括数据一致性保障和数据单位标准化。
|
||
|
||
## 核心特性
|
||
|
||
- **数据一致性**：管理端和用户端均使用 `revenue_config` 表作为唯一数据源
|
||
- **单位标准化**：数据库存储小数格式（0.0500 = 5%），前端显示百分比格式（5.00%）
|
||
- **自动转换**：API层自动处理百分比与小数的转换
|
||
|
||
---
|
||
|
||
## 1. 管理端接口
|
||
|
||
### 1.1 获取收益设置
|
||
**接口地址：** `GET /admin/settings/revenue`
|
||
|
||
**请求头：**
|
||
```
|
||
Authorization: Bearer <admin_jwt_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"contentCreatorSettings": {
|
||
"courseCreatorRate": 60.0,
|
||
"workflowCreatorRate": 70.0,
|
||
"videoPlayRate": 50.0,
|
||
"contentPurchaseRate": 80.0
|
||
},
|
||
"promotionLevels": [
|
||
{
|
||
"id": 1,
|
||
"levelName": "Lv1",
|
||
"minPaidFans": 0,
|
||
"commissionRate": 5.0,
|
||
"description": "推广等级1：0个付费粉丝，5%提成",
|
||
"createTime": "2025-08-27T15:30:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"levelName": "Lv2",
|
||
"minPaidFans": 10,
|
||
"commissionRate": 8.0,
|
||
"description": "推广等级2：10个付费粉丝，8%提成",
|
||
"createTime": "2025-08-27T15:30:00"
|
||
},
|
||
{
|
||
"id": 3,
|
||
"levelName": "Lv3",
|
||
"minPaidFans": 50,
|
||
"commissionRate": 12.0,
|
||
"description": "推广等级3：50个付费粉丝，12%提成",
|
||
"createTime": "2025-08-27T15:30:00"
|
||
},
|
||
{
|
||
"id": 4,
|
||
"levelName": "Lv4",
|
||
"minPaidFans": 100,
|
||
"commissionRate": 15.0,
|
||
"description": "推广等级4：100个付费粉丝，15%提成",
|
||
"createTime": "2025-08-27T15:30:00"
|
||
},
|
||
{
|
||
"id": 5,
|
||
"levelName": "Lv5",
|
||
"minPaidFans": 200,
|
||
"commissionRate": 20.0,
|
||
"description": "推广等级5：200个付费粉丝，20%提成",
|
||
"createTime": "2025-08-27T15:30:00"
|
||
}
|
||
],
|
||
"platformFeeSettings": {
|
||
"platformFeeRate": 5.0,
|
||
"minWithdrawAmount": 10.0,
|
||
"withdrawFeeRate": 2.0,
|
||
"withdrawFixedFee": 1.0
|
||
},
|
||
"workflowRevenueLevels": [
|
||
{
|
||
"level": 1,
|
||
"levelName": "初级创作者",
|
||
"targetCount": 100,
|
||
"rewardAmount": 50.0,
|
||
"description": "工作流复制100次奖励50元"
|
||
},
|
||
{
|
||
"level": 2,
|
||
"levelName": "中级创作者",
|
||
"targetCount": 500,
|
||
"rewardAmount": 200.0,
|
||
"description": "工作流复制500次奖励200元"
|
||
},
|
||
{
|
||
"level": 3,
|
||
"levelName": "高级创作者",
|
||
"targetCount": 1000,
|
||
"rewardAmount": 500.0,
|
||
"description": "工作流复制1000次奖励500元"
|
||
}
|
||
],
|
||
"videoRevenueLevels": [
|
||
{
|
||
"level": 1,
|
||
"levelName": "初级视频创作者",
|
||
"targetCount": 1000,
|
||
"rewardAmount": 100.0,
|
||
"description": "视频观看1000次奖励100元"
|
||
},
|
||
{
|
||
"level": 2,
|
||
"levelName": "中级视频创作者",
|
||
"targetCount": 5000,
|
||
"rewardAmount": 300.0,
|
||
"description": "视频观看5000次奖励300元"
|
||
},
|
||
{
|
||
"level": 3,
|
||
"levelName": "高级视频创作者",
|
||
"targetCount": 10000,
|
||
"rewardAmount": 800.0,
|
||
"description": "视频观看10000次奖励800元"
|
||
}
|
||
],
|
||
"lastUpdateTime": "2025-08-27T15:30:00",
|
||
"updatedBy": "系统"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 更新推广等级配置
|
||
**接口地址：** `PUT /admin/settings/revenue`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"promotionSettings": [
|
||
{
|
||
"level": 1,
|
||
"minFans": 0,
|
||
"commissionRate": 6.0
|
||
},
|
||
{
|
||
"level": 2,
|
||
"minFans": 15,
|
||
"commissionRate": 9.0
|
||
},
|
||
{
|
||
"level": 3,
|
||
"minFans": 60,
|
||
"commissionRate": 13.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "收益设置更新成功",
|
||
"data": "收益设置更新成功"
|
||
}
|
||
```
|
||
|
||
**数据转换说明：**
|
||
- 前端传入 `commissionRate: 6.0` 表示 6%
|
||
- 后端自动转换为 `0.0600` 存储到数据库
|
||
- 查询时自动转换为 `6.0` 返回前端
|
||
|
||
### 1.3 删除收益配置
|
||
**接口地址：** `DELETE /admin/config/{configKey}`
|
||
|
||
**请求示例：**
|
||
```
|
||
DELETE /admin/config/promotion_level_4
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "配置删除成功",
|
||
"data": "配置删除成功"
|
||
}
|
||
```
|
||
|
||
### 1.4 删除推广等级
|
||
**接口地址：** `DELETE /admin/promotion-level/{levelId}`
|
||
|
||
**请求示例：**
|
||
```
|
||
DELETE /admin/promotion-level/5
|
||
```
|
||
|
||
**⚠️ 注意：路径中没有 `/settings`，正确路径是 `/admin/promotion-level/{levelId}`**
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "推广等级删除成功",
|
||
"data": "推广等级删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 用户端接口
|
||
|
||
### 2.1 获取推广规则
|
||
**接口地址：** `GET /user/v1/promotion-rules`
|
||
|
||
**请求头：**
|
||
```
|
||
Authorization: Bearer <user_jwt_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"promotionLevels": [
|
||
{
|
||
"level": 1,
|
||
"levelName": "Lv1",
|
||
"minFans": 0,
|
||
"commissionRate": 5.0,
|
||
"description": "推广等级1：0个付费粉丝，5%提成"
|
||
},
|
||
{
|
||
"level": 2,
|
||
"levelName": "Lv2",
|
||
"minFans": 10,
|
||
"commissionRate": 8.0,
|
||
"description": "推广等级2：10个付费粉丝，8%提成"
|
||
},
|
||
{
|
||
"level": 3,
|
||
"levelName": "Lv3",
|
||
"minFans": 50,
|
||
"commissionRate": 12.0,
|
||
"description": "推广等级3：50个付费粉丝，12%提成"
|
||
},
|
||
{
|
||
"level": 4,
|
||
"levelName": "Lv4",
|
||
"minFans": 100,
|
||
"commissionRate": 15.0,
|
||
"description": "推广等级4：100个付费粉丝，15%提成"
|
||
},
|
||
{
|
||
"level": 5,
|
||
"levelName": "Lv5",
|
||
"minFans": 200,
|
||
"commissionRate": 20.0,
|
||
"description": "推广等级5：200个付费粉丝，20%提成"
|
||
}
|
||
],
|
||
"contentRewards": [
|
||
{
|
||
"level": 1,
|
||
"levelName": "初级创作者",
|
||
"type": "workflow",
|
||
"targetCount": 100,
|
||
"rewardAmount": 50.0,
|
||
"description": "工作流复制100次奖励50元"
|
||
},
|
||
{
|
||
"level": 2,
|
||
"levelName": "中级创作者",
|
||
"type": "workflow",
|
||
"targetCount": 500,
|
||
"rewardAmount": 200.0,
|
||
"description": "工作流复制500次奖励200元"
|
||
},
|
||
{
|
||
"level": 3,
|
||
"levelName": "高级创作者",
|
||
"type": "workflow",
|
||
"targetCount": 1000,
|
||
"rewardAmount": 500.0,
|
||
"description": "工作流复制1000次奖励500元"
|
||
},
|
||
{
|
||
"level": 1,
|
||
"levelName": "初级视频创作者",
|
||
"type": "video",
|
||
"targetCount": 1000,
|
||
"rewardAmount": 100.0,
|
||
"description": "视频观看1000次奖励100元"
|
||
},
|
||
{
|
||
"level": 2,
|
||
"levelName": "中级视频创作者",
|
||
"type": "video",
|
||
"targetCount": 5000,
|
||
"rewardAmount": 300.0,
|
||
"description": "视频观看5000次奖励300元"
|
||
},
|
||
{
|
||
"level": 3,
|
||
"levelName": "高级视频创作者",
|
||
"type": "video",
|
||
"targetCount": 10000,
|
||
"rewardAmount": 800.0,
|
||
"description": "视频观看10000次奖励800元"
|
||
}
|
||
],
|
||
"lastUpdateTime": "2025-08-27T15:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 数据一致性保障
|
||
|
||
### 3.1 统一数据源
|
||
- **管理端** `/admin/settings/revenue` 和 **用户端** `/user/v1/promotion-rules` 均从 `revenue_config` 表读取数据
|
||
- 所有相关服务类（`PromotionLevelServiceImpl`、`PromotionService`）均已迁移至 `revenue_config` 表
|
||
- 移除了 `promotion_level_config` 表的重复数据插入
|
||
|
||
### 3.2 数据转换规则
|
||
| 数据流向 | 存储格式 | 显示格式 | 转换规则 |
|
||
|---------|---------|---------|---------|
|
||
| 前端 → 后端 | 6.0% → 0.0600 | `rate.divide(100)` | 百分比转小数 |
|
||
| 后端 → 前端 | 0.0600 → 6.0% | `rate.multiply(100)` | 小数转百分比 |
|
||
| 数据库存储 | decimal(5,4) | 0.0600 | 小数格式 |
|
||
|
||
### 3.3 兼容性处理
|
||
为了处理历史数据可能存在的格式不一致问题，转换逻辑包含安全检查：
|
||
```java
|
||
// 安全地将数据库存储的佣金比例转换为百分比显示
|
||
if (config.getCommissionRate() != null) {
|
||
BigDecimal rate = config.getCommissionRate();
|
||
// 如果值大于1，说明已经是百分比格式，直接使用
|
||
// 如果值小于等于1，说明是小数格式，需要乘以100转换为百分比
|
||
if (rate.compareTo(BigDecimal.ONE) > 0) {
|
||
detail.setCommissionRate(rate);
|
||
} else {
|
||
detail.setCommissionRate(rate.multiply(new BigDecimal("100")));
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 测试用例
|
||
|
||
### 4.1 管理端测试
|
||
**获取当前配置：**
|
||
```bash
|
||
curl -X GET "http://localhost:8081/admin/settings/revenue" \
|
||
-H "Authorization: Bearer <admin_token>" \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
**更新推广等级：**
|
||
```bash
|
||
curl -X PUT "http://localhost:8081/admin/settings/revenue" \
|
||
-H "Authorization: Bearer <admin_token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"promotionSettings": [
|
||
{
|
||
"level": 1,
|
||
"minFans": 0,
|
||
"commissionRate": 6.0
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
**删除配置：**
|
||
```bash
|
||
curl -X DELETE "http://localhost:8081/admin/config/promotion_level_5" \
|
||
-H "Authorization: Bearer <admin_token>"
|
||
```
|
||
|
||
**删除推广等级：**
|
||
```bash
|
||
curl -X DELETE "http://localhost:8081/admin/promotion-level/5" \
|
||
-H "Authorization: Bearer <admin_token>"
|
||
```
|
||
|
||
### 4.2 用户端测试
|
||
**获取推广规则：**
|
||
```bash
|
||
curl -X GET "http://localhost:8081/user/v1/promotion-rules" \
|
||
-H "Authorization: Bearer <user_token>" \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 常见问题
|
||
|
||
### Q1: 为什么管理端设置的数据和用户端显示的不一致？
|
||
**A1:** 已通过统一数据源解决。现在两端都使用 `revenue_config` 表，确保数据一致性。
|
||
|
||
### Q2: 佣金比例的单位是什么？
|
||
**A2:** 数据库存储小数格式（如 0.0500 表示 5%），API 返回百分比格式（如 5.0 表示 5%）。
|
||
|
||
### Q3: 如何验证数据一致性？
|
||
**A3:** 可以分别调用管理端和用户端接口，对比 `promotionLevels` 数据是否完全一致。
|
||
|
||
### Q4: 更新配置后多久生效？
|
||
**A4:** 立即生效，无需重启服务。
|
||
|
||
---
|
||
|
||
## 6. 版本历史
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|-----|------|---------|
|
||
| v1.0 | 2025-08-27 | 初始版本，统一数据源和单位标准化 |
|
||
| v1.1 | 2025-08-27 | 增加删除接口和错误处理 |
|
||
|
||
---
|
||
|
||
## 7. 实际使用示例
|
||
|
||
### 7.1 管理员配置推广等级流程
|
||
|
||
**步骤1：查看当前配置**
|
||
```bash
|
||
curl -X GET "http://localhost:8081/admin/settings/revenue" \
|
||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
**步骤2：修改等级3的佣金比例从12%调整为15%**
|
||
```bash
|
||
curl -X PUT "http://localhost:8081/admin/settings/revenue" \
|
||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"promotionSettings": [
|
||
{
|
||
"level": 3,
|
||
"minFans": 50,
|
||
"commissionRate": 15.0
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
**步骤3：删除等级5**
|
||
```bash
|
||
curl -X DELETE "http://localhost:8081/admin/promotion-level/5" \
|
||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
**⚠️ 重要提醒：请确保使用正确路径 `/admin/promotion-level/5`，不是 `/admin/settings/promotion-level/5`**
|
||
|
||
### 7.2 用户查看推广规则
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8081/user/v1/promotion-rules" \
|
||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
**返回的数据与管理端设置完全一致，确保数据同步。**
|
||
|
||
---
|
||
|
||
## 8. 故障排除
|
||
|
||
### 8.1 常见错误码
|
||
- **400**: 请求参数错误
|
||
- **401**: 未授权访问
|
||
- **403**: 权限不足
|
||
- **404**: 资源不存在
|
||
- **500**: 服务器内部错误
|
||
|
||
### 8.2 日志查看
|
||
删除操作的日志示例：
|
||
```
|
||
2025-08-27T22:29:55.545 INFO - 删除推广等级，等级ID: 5
|
||
2025-08-27T22:29:55.546 INFO - 删除推广等级成功，等级ID: 5, 配置键: promotion_level_5
|
||
```
|
||
|
||
### 8.3 路径错误排查
|
||
如果出现 `NoResourceFoundException: No static resource admin/settings/promotion-level/5`，说明路径错误：
|
||
|
||
**❌ 错误路径：**
|
||
```
|
||
DELETE /admin/settings/promotion-level/5
|
||
```
|
||
|
||
**✅ 正确路径：**
|
||
```
|
||
DELETE /admin/promotion-level/5
|
||
```
|
||
|
||
### 8.4 软删除问题排查
|
||
如果删除接口返回成功，但查询列表时仍显示已删除的记录，可能是软删除没有生效：
|
||
|
||
**问题症状：**
|
||
- DELETE请求返回200状态码
|
||
- 日志显示"删除推广等级成功"
|
||
- 但GET请求仍返回已删除的记录
|
||
|
||
**修复方案（已解决）：**
|
||
确保 `RevenueConfigMapper.xml` 中的 `updateByConfigKey` 包含 `is_deleted` 字段更新：
|
||
```xml
|
||
<if test="isDeleted != null">is_deleted = #{isDeleted},</if>
|
||
```
|
||
|
||
**验证方法：**
|
||
删除后立即调用查询接口，确认已删除的记录不再出现在返回列表中。
|
||
|
||
---
|
||
|
||
## 9. 联系方式
|
||
|
||
如有问题，请联系开发团队或查看项目文档。
|