lth/1818web-hoduan

Fork 0

Files

Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00

13 KiB

Raw Blame History

推广收益配置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

响应示例：

{
  "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

请求示例：

{
  "promotionSettings": [
    {
      "level": 1,
      "minFans": 0,
      "commissionRate": 6.0
    },
    {
      "level": 2,
      "minFans": 15,
      "commissionRate": 9.0
    },
    {
      "level": 3,
      "minFans": 60,
      "commissionRate": 13.0
    }
  ]
}

响应示例：

{
  "code": 200,
  "message": "收益设置更新成功",
  "data": "收益设置更新成功"
}

数据转换说明：

前端传入 commissionRate: 6.0 表示 6%
后端自动转换为 0.0600 存储到数据库
查询时自动转换为 6.0 返回前端

1.3 删除收益配置

接口地址： DELETE /admin/config/{configKey}

请求示例：

DELETE /admin/config/promotion_level_4

响应示例：

{
  "code": 200,
  "message": "配置删除成功",
  "data": "配置删除成功"
}

1.4 删除推广等级

接口地址： DELETE /admin/promotion-level/{levelId}

请求示例：

DELETE /admin/promotion-level/5

⚠️ 注意：路径中没有 /settings，正确路径是 /admin/promotion-level/{levelId}

响应示例：

{
  "code": 200,
  "message": "推广等级删除成功",
  "data": "推广等级删除成功"
}

2. 用户端接口

2.1 获取推广规则

接口地址： GET /user/v1/promotion-rules

请求头：

Authorization: Bearer <user_jwt_token>
Content-Type: application/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 兼容性处理

为了处理历史数据可能存在的格式不一致问题，转换逻辑包含安全检查：

// 安全地将数据库存储的佣金比例转换为百分比显示
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 管理端测试

获取当前配置：

curl -X GET "http://localhost:8081/admin/settings/revenue" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json"

更新推广等级：

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
      }
    ]
  }'

删除配置：

curl -X DELETE "http://localhost:8081/admin/config/promotion_level_5" \
  -H "Authorization: Bearer <admin_token>"

删除推广等级：

curl -X DELETE "http://localhost:8081/admin/promotion-level/5" \
  -H "Authorization: Bearer <admin_token>"

4.2 用户端测试

获取推广规则：

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：查看当前配置

curl -X GET "http://localhost:8081/admin/settings/revenue" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

步骤2：修改等级3的佣金比例从12%调整为15%

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

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 用户查看推广规则

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 字段更新：

<if test="isDeleted != null">is_deleted = #{isDeleted},</if>

验证方法： 删除后立即调用查询接口，确认已删除的记录不再出现在返回列表中。

9. 联系方式

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

13 KiB Raw Blame History Unescape Escape

推广收益配置API接口文档

概述

核心特性

1. 管理端接口

1.1 获取收益设置

1.2 更新推广等级配置

1.3 删除收益配置

1.4 删除推广等级

2. 用户端接口

2.1 获取推广规则

3. 数据一致性保障

3.1 统一数据源

3.2 数据转换规则

3.3 兼容性处理

4. 测试用例

4.1 管理端测试

4.2 用户端测试

5. 常见问题

Q1: 为什么管理端设置的数据和用户端显示的不一致？

Q2: 佣金比例的单位是什么？

Q3: 如何验证数据一致性？

Q4: 更新配置后多久生效？

6. 版本历史

7. 实际使用示例

7.1 管理员配置推广等级流程

7.2 用户查看推广规则

8. 故障排除

8.1 常见错误码

8.2 日志查看

8.3 路径错误排查

8.4 软删除问题排查

9. 联系方式

13 KiB

Raw Blame History