[Claude Workbench] Initial commit - preserving existing code
This commit is contained in:
Claude Workbench
188
docs/income-detail-api-enhancement.md
Normal file
188
docs/income-detail-api-enhancement.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 收益明细接口增强说明
|
||||
|
||||
## 概述
|
||||
本次修改为 `/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` 函数处理空值情况
|
||||
- 服务层对查询异常进行了妥善处理，不会影响主功能
|
||||
- 新的描述信息更长，但仍在合理范围内，不会影响前端展示
|
||||
Reference in New Issue
Block a user