1818web-hoduan/docs/user-balance-log-description-enhancement.md

用户余额记录描述增强说明

概述

本次修改增强了 user_balance_log 表中 description 字段的详细程度，让用户更清楚地了解余额变动的具体原因和来源。

修改内容

1. 工作流收益描述增强

修改文件: src/main/java/com/dora/service/impl/ContentRevenueStageServiceImpl.java

原描述格式:

工作流用户使用奖励 - 工作流:%s, 奖励:%s元

新描述格式:

【工作流收益】%s 获得新用户使用奖励 - 每个用户首次使用获得%.2f元收益

改进说明:

• 添加了明确的收益类型标识 【工作流收益】
• 包含具体的工作流名称
• 解释了触发条件（新用户首次使用）
• 使用更精确的数字格式显示

2. 视频收益描述增强

修改文件: src/main/java/com/dora/service/impl/ContentRevenueStageServiceImpl.java

原描述格式:

视频收益阶段达成 - %s, 观看数:%d, 奖励:%s元

新描述格式:

【视频收益】%s 达到%s阶段奖励 - 观看次数达到%d次，获得%.2f元收益

改进说明:

• 添加了明确的收益类型标识 【视频收益】
• 包含具体的视频标题（从数据库查询获取）
• 详细说明了达成的阶段和具体观看次数
• 明确标示奖励金额

3. 推广收益描述增强

修改文件: src/main/java/com/dora/service/impl/PromotionCommissionServiceImpl.java

原描述格式:

推广分成收益 - 订单:%d, 金额:%s

新描述格式:

【推广收益】粉丝 %s 购买会员获得Lv%d推广分成 - 订单金额%.2f元，分成%.2f元(%.1f%%)

改进说明:

• 添加了明确的收益类型标识 【推广收益】
• 包含具体的粉丝用户名
• 显示推广等级信息
• 详细显示订单金额、分成金额和分成比例

技术实现细节

1. 新增依赖注入

在 ContentRevenueStageServiceImpl 中添加了 VideoMapper 依赖，用于查询视频详细信息：

private final VideoMapper videoMapper;

2. 动态获取内容名称

• 视频收益: 通过 videoMapper.selectById(videoId) 获取视频标题
• 工作流收益: 直接使用已有的 workflow.getName()
• 推广收益: 通过 userMapper.selectById(commission.getFanId()) 获取粉丝用户名

3. 数字格式统一

所有金额显示统一使用 %.2f 格式，确保显示两位小数

用户体验改进

原来的描述示例

推广分成收益 - 订单:12345, 金额:11.70
视频收益阶段达成 - 视频等级1, 观看数:1000, 奖励:50.00元
工作流用户使用奖励 - 工作流:AI图像生成, 奖励:1.00元

改进后的描述示例

【推广收益】粉丝 用户张三 购买会员获得Lv1推广分成 - 订单金额39.00元，分成11.70元(30.0%)
【视频收益】AI基础教程 达到视频等级1阶段奖励 - 观看次数达到1000次，获得50.00元收益
【工作流收益】AI图像生成 获得新用户使用奖励 - 每个用户首次使用获得1.00元收益

兼容性说明

• ✅ 不破坏现有数据结构
• ✅ 不影响现有业务逻辑
• ✅ 向后兼容，老数据正常显示
• ✅ 新数据使用增强的描述格式

测试建议

1. 创建新的工作流使用记录，验证描述格式
2. 触发视频观看阶段奖励，验证视频名称显示
3. 产生推广分成，验证粉丝信息和分成比例显示
4. 查看用户余额明细接口 /user/balance/income-detail，确认描述显示正确

注意事项

• 如果关联的视频或用户信息不存在，会显示默认值（如"未知视频"、"未知用户"）
• 所有数据库查询都有异常处理，不会影响主业务流程
• 新的描述格式更长，需确保 description 字段长度（255字符）足够使用