# 收益明细接口增强说明

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

## 接口优化对比

### 修改前的返回数据
```json
{
    "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": "获取收益明细成功"
}
```

### 修改后的返回数据
```json
{
    "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` 中为推广收益项添加描述字段：
```java
@Schema(description = "收益描述", example = "【推广收益】粉丝 用户张三 购买会员获得Lv1推广分成 - 订单金额39.00元，分成11.70元(30.0%)")
private String description;
```

#### ContentIncomeItem 类  
为内容收益项添加描述字段：
```java
@Schema(description = "收益描述", example = "【视频收益】AI基础教程 达到视频等级1阶段奖励 - 观看次数达到1000次，获得50.00元收益")
private String description;
```

### 2. SQL 查询优化
#### 推广收益描述生成
在 `src/main/resources/mapper/FanPromotionCommissionMapper.xml` 中直接在 SQL 层面生成描述：
```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` 方法中：

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

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

## 描述字段详细信息

### 推广收益描述格式
```
【推广收益】粉丝 [用户名] 购买会员获得Lv[等级]推广分成 - 订单金额[金额]元，分成[分成金额]元([分成比例]%)
```
- 明确标识收益类型
- 显示具体的粉丝用户名
- 说明推广等级
- 详细展示订单金额、分成金额和分成比例

### 内容收益描述格式

#### 工作流收益
```
【工作流收益】[工作流名称] 获得用户使用奖励 - 累计[次数]次收益，共计[总金额]元
```
- 显示具体的工作流名称
- 说明是用户使用产生的奖励
- 统计累计收益次数和总金额

#### 视频收益
```
【视频收益】[视频标题] 达到收益阶段奖励 - 累计[阶段数]个阶段，共计[总金额]元
```
- 显示具体的视频标题
- 说明是阶段性奖励
- 统计累计达到的阶段数和总金额

## 用户体验提升

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

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

## 兼容性保证

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

## 测试建议

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

## 注意事项

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