lth/1818web-hoduan

Fork 0

Files

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

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

6.7 KiB

Raw Blame History

收益明细接口增强说明

概述

本次修改为 /user/balance/income-detail 接口的返回数据添加了详细的描述字段，让用户更清楚地了解每笔收益的具体来源和详情。

接口优化对比

修改前的返回数据

{
    "code": 200,
    "data": {
        "promotionIncome": 15.60,
        "promotionIncomes": [
            {
                "commissionId": 1,
                "orderNo": "ORD202508291217238529",
                "orderAmount": 39.00,
                "fanUserId": 17564409809714648,
                "fanUsername": "小杰訫",
                "commissionLevel": 2,
                "levelName": "Lv2",
                "commissionRate": 0.4000,
                "commissionAmount": 15.60,
                "commissionTime": "2025-08-29T12:17:42",
                "settledAt": "2025-08-29T12:17:42"
            }
        ],
        "contentIncomes": [
            {
                "contentType": "video",
                "contentTypeName": "视频",
                "contentId": 1,
                "contentName": "测试001",
                "incomeAmount": 125.00,
                "incomeTime": "2025-08-29T15:36:38"
            }
        ],
        "totalIncome": 140.60
    },
    "message": "获取收益明细成功"
}

修改后的返回数据

{
    "code": 200,
    "data": {
        "promotionIncome": 15.60,
        "promotionIncomes": [
            {
                "commissionId": 1,
                "orderNo": "ORD202508291217238529",
                "orderAmount": 39.00,
                "fanUserId": 17564409809714648,
                "fanUsername": "小杰訫",
                "commissionLevel": 2,
                "levelName": "Lv2",
                "commissionRate": 0.4000,
                "commissionAmount": 15.60,
                "commissionTime": "2025-08-29T12:17:42",
                "settledAt": "2025-08-29T12:17:42",
                "description": "【推广收益】粉丝 小杰訫 购买会员获得Lv2推广分成 - 订单金额39.00元，分成15.60元(40.0%)"
            }
        ],
        "contentIncomes": [
            {
                "contentType": "video",
                "contentTypeName": "视频",
                "contentId": 1,
                "contentName": "测试001",
                "incomeAmount": 125.00,
                "incomeTime": "2025-08-29T15:36:38",
                "description": "【视频收益】测试001 达到收益阶段奖励 - 累计3个阶段，共计125.00元"
            }
        ],
        "totalIncome": 140.60
    },
    "message": "获取收益明细成功"
}

技术实现详情

1. DTO 结构修改

PromotionIncomeItem 类

在 src/main/java/com/dora/dto/UserBalanceDto.java 中为推广收益项添加描述字段：

@Schema(description = "收益描述", example = "【推广收益】粉丝 用户张三 购买会员获得Lv1推广分成 - 订单金额39.00元，分成11.70元(30.0%)")
private String description;

ContentIncomeItem 类

为内容收益项添加描述字段：

@Schema(description = "收益描述", example = "【视频收益】AI基础教程 达到视频等级1阶段奖励 - 观看次数达到1000次，获得50.00元收益")
private String description;

2. SQL 查询优化

推广收益描述生成

在 src/main/resources/mapper/FanPromotionCommissionMapper.xml 中直接在 SQL 层面生成描述：

CONCAT('【推广收益】粉丝 ', IFNULL(u.username, '未知用户'), ' 购买会员获得Lv', fpc.commission_level, '推广分成 - 订单金额', CAST(fpc.order_amount AS CHAR), '元，分成', CAST(fpc.commission_amount AS CHAR), '元(', CAST(ROUND(fpc.commission_rate * 100, 1) AS CHAR), '%)') as description

3. 服务层逻辑增强

内容收益描述生成

在 src/main/java/com/dora/service/impl/UserBalanceServiceImpl.java 的 getContentIncomes 方法中：

工作流收益描述:

// 生成工作流收益描述
int userCount = logs.size(); // 简化统计，实际应该统计唯一用户数
item.setDescription(String.format("【工作流收益】%s 获得用户使用奖励 - 累计%d次收益，共计%.2f元", 
        workflowName, userCount, totalIncome));

视频收益描述:

// 生成视频收益描述
int achievementCount = logs.size(); // 达到的阶段数
item.setDescription(String.format("【视频收益】%s 达到收益阶段奖励 - 累计%d个阶段，共计%.2f元", 
        videoTitle, achievementCount, totalIncome));

描述字段详细信息

推广收益描述格式

【推广收益】粉丝 [用户名] 购买会员获得Lv[等级]推广分成 - 订单金额[金额]元，分成[分成金额]元([分成比例]%)

明确标识收益类型
显示具体的粉丝用户名
说明推广等级
详细展示订单金额、分成金额和分成比例

内容收益描述格式

工作流收益

【工作流收益】[工作流名称] 获得用户使用奖励 - 累计[次数]次收益，共计[总金额]元

显示具体的工作流名称
说明是用户使用产生的奖励
统计累计收益次数和总金额

视频收益

【视频收益】[视频标题] 达到收益阶段奖励 - 累计[阶段数]个阶段，共计[总金额]元

显示具体的视频标题
说明是阶段性奖励
统计累计达到的阶段数和总金额

用户体验提升

收益来源清晰化

分类标识: 每种收益类型都有明确的【类型】标识
具体内容: 显示详细的内容名称、用户名称等关键信息
数据透明: 展示收益产生的具体条件和计算方式

信息完整性

推广收益: 包含粉丝信息、订单详情、分成计算过程
工作流收益: 说明奖励机制和累计情况
视频收益: 展示阶段性成就和总体表现

兼容性保证

✅ 向后兼容: 新增字段，不影响现有功能
✅ 数据安全: 所有查询都有异常处理和默认值处理
✅ 性能优化: 利用 SQL 层面计算减少服务器处理压力
✅ 类型安全: 新增字段有完整的类型定义和文档注解

测试建议

接口测试: 调用 /user/balance/income-detail 接口，验证返回数据包含 description 字段
数据准确性: 检查描述信息是否与实际收益数据一致
边界情况: 测试用户名为空、内容名称为空等情况的处理
性能测试: 验证新增字段对接口响应时间的影响

注意事项

描述字段由系统自动生成，确保数据一致性
SQL 中使用了 IFNULL 函数处理空值情况
服务层对查询异常进行了妥善处理，不会影响主功能
新的描述信息更长，但仍在合理范围内，不会影响前端展示

6.7 KiB Raw Blame History Unescape Escape