1818web-hoduan/docs/promotion-revenue-api-guide.md

# 推广收益配置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. 联系方式

如有问题，请联系开发团队或查看项目文档。