[Claude Workbench] Initial commit - preserving existing code

docs/user-balance-log-description-enhancement.md

@@ -0,0 +1,112 @@
+# 用户余额记录描述增强说明
+
+## 概述
+本次修改增强了 `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` 依赖，用于查询视频详细信息：
+```java
+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字符）足够使用