[Claude Workbench] Initial commit - preserving existing code
This commit is contained in:
Claude Workbench
530
docs/promotion-revenue-api-guide.md
Normal file
530
docs/promotion-revenue-api-guide.md
Normal file
@@ -0,0 +1,530 @@
|
||||
# 推广收益配置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. 联系方式
|
||||
|
||||
如有问题，请联系开发团队或查看项目文档。
|
||||
Reference in New Issue
Block a user