# 获取卖家交易评价列表接口文档

## 接口概述

### 接口信息

| 项目 | 内容 |
|------|------|
| 接口名称 | 获取用户作为卖家的交易评价列表 |
| 接口路径 | `/secondTradeRecord/getSellerEvaluationList` |
| 请求方式 | GET |
| 接口版本 | v1.0 |
| 开发时间 | 2025-11-18 |
| 接口状态 | ✅ 已完成 |

### 功能描述

用于用户主页展示该用户作为卖家收到的所有交易评价，包含：
- 买家完整信息（昵称、头像、真实姓名、性别、简介等）
- 评价内容和评分
- 买家和卖家的信用积分
- 买家和卖家的风控评分等级
- 交易商品信息
- 交易基本信息

---

## 请求参数

### Query Parameters

| 参数名 | 类型 | 必填 | 描述 | 示例值 | 默认值 |
|--------|------|------|------|--------|--------|
| sellerId | Integer | ✅ 是 | 卖家用户ID（主页用户ID） | 123 | - |

### 请求示例

#### cURL

```bash
curl -X GET "http://localhost:8080/secondTradeRecord/getSellerEvaluationList?sellerId=123" \
  -H "Authorization: Bearer your_token_here"
```

#### JavaScript (Axios)

```javascript
axios.get('/secondTradeRecord/getSellerEvaluationList', {
  params: {
    sellerId: 123
  },
  headers: {
    'Authorization': 'Bearer your_token_here'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
```

#### Java (RestTemplate)

```java
String url = "http://localhost:8080/secondTradeRecord/getSellerEvaluationList?sellerId=123";
RestTemplate restTemplate = new RestTemplate();
R<List<SellerEvaluationVo>> result = restTemplate.getForObject(url, R.class);
```

---

## 响应参数

### 响应结构

| 字段名 | 类型 | 描述 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data | Array&lt;SellerEvaluationVo&gt; | 评价列表数据 |

### SellerEvaluationVo 对象结构

#### 交易基本信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| id | Integer | ✅ | 交易记录ID | 1 |
| tradeNo | String | ✅ | 交易编号 | S2025111800001 |
| transactionTime | String | ✅ | 交易时间 | 2025-11-18 10:00:00 |
| transactionAmount | BigDecimal | ✅ | 交易金额（元） | 3800.00 |
| tradeStatus | Integer | ✅ | 交易状态 | 4 |
| createdTime | String | ✅ | 创建时间 | 2025-11-18 09:00:00 |

#### 商品信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| goodsId | Integer | ✅ | 商品ID | 100 |
| goodsTitle | String | ❌ | 商品标题 | 二手iPhone 13 128G 白色 95新 |
| goodsHomeImage | String | ❌ | 商品封面图片URL | https://cdn.example.com/goods/iphone13.jpg |
| goodsPrice | BigDecimal | ❌ | 商品价格（元） | 3999.00 |

#### 买家信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| buyerId | Integer | ✅ | 买家ID | 456 |
| buyerName | String | ❌ | 买家昵称 | 张三 |
| buyerImage | String | ❌ | 买家头像URL | https://cdn.example.com/avatar/user456.jpg |
| buyerPhone | String | ❌ | 买家手机号 | 13800138000 |
| buyerRealName | String | ❌ | 买家真实姓名 | 张三三 |
| buyerSex | String | ❌ | 买家性别 | 男 |
| buyerJianjie | String | ❌ | 买家简介 | 热爱数码产品，诚信交易 |

#### 买家评价信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| buyerEvaluate | String | ✅ | 买家评价内容 | 商品质量很好，和描述一致，卖家态度也不错，推荐！ |
| buyerRating | Integer | ❌ | 买家评分（1-5分） | 5 |
| buyerCreditScore | Integer | ✅ | 买家信用积分 | 450 |
| buyerCreditLevel | String | ✅ | 买家风控评分等级 | A |

#### 卖家信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| sellerId | Integer | ✅ | 卖家ID | 123 |
| sellerName | String | ❌ | 卖家昵称 | 李四 |
| sellerImage | String | ❌ | 卖家头像URL | https://cdn.example.com/seller.jpg |
| sellerCreditScore | Integer | ✅ | 卖家信用积分 | 500 |
| sellerCreditLevel | String | ✅ | 卖家风控评分等级 | O |

---

## 枚举说明

### 交易状态 (tradeStatus)

| 状态值 | 状态名称 | 说明 |
|--------|----------|------|
| 1 | 待确认 | 买家发起交易请求，等待卖家确认 |
| 2 | 已拒绝 | 卖家拒绝了交易请求 |
| 3 | 待交易 | 双方确认交易，等待线下交易 |
| 4 | 交易成功 | 交易完成，双方确认成功 |
| 5 | 交易失败 | 交易失败 |
| 6 | 交易取消 | 交易被取消 |

### 风控评分等级 (creditLevel)

| 等级 | 违规次数 | 等级说明 | 风险程度 |
|------|----------|----------|----------|
| O | 0次 | 无违规记录 | 🟢 无风险（最优） |
| A | 1-2次 | 轻微违规 | 🟢 低风险 |
| B | 3-5次 | 一般违规 | 🟡 中等风险 |
| C | 6-9次 | 较严重违规 | 🟡 较高风险 |
| D | 10-14次 | 严重违规 | 🔴 高风险 |
| E | ≥15次 | 极差 | 🔴 极高风险（最差） |

**风控等级计算说明**：
- 基于用户在 `second_risk_control_record` 表中的违规记录数量
- 违规类型包括：洗钱嫌疑、账号异常、交易欺诈、异常发布
- 等级实时计算，反映用户最新的信用状态

---

## 响应示例

### 成功响应

```json
{
  "code": 200,
  "msg": "成功",
  "data": [
    {
      "id": 1,
      "tradeNo": "S2025111800001",
      "goodsId": 100,
      "goodsTitle": "二手iPhone 13 128G 白色 95新",
      "goodsHomeImage": "https://cdn.example.com/goods/iphone13.jpg",
      "goodsPrice": 3999.00,
      "transactionAmount": 3800.00,
      "buyerId": 456,
      "buyerName": "张三",
      "buyerImage": "https://cdn.example.com/avatar/user456.jpg",
      "buyerPhone": "13800138000",
      "buyerRealName": "张三三",
      "buyerSex": "男",
      "buyerJianjie": "热爱数码产品，诚信交易",
      "buyerEvaluate": "商品质量很好，和描述一致，卖家态度也不错，推荐！",
      "buyerRating": 5,
      "buyerCreditScore": 450,
      "buyerCreditLevel": "A",
      "sellerId": 123,
      "sellerName": "李四",
      "sellerImage": "https://cdn.example.com/avatar/user123.jpg",
      "sellerCreditScore": 500,
      "sellerCreditLevel": "O",
      "transactionTime": "2025-11-18 10:00:00",
      "tradeStatus": 4,
      "createdTime": "2025-11-18 09:00:00"
    },
    {
      "id": 2,
      "tradeNo": "S2025111700025",
      "goodsId": 101,
      "goodsTitle": "小米手环7 黑色 全新未拆封",
      "goodsHomeImage": "https://cdn.example.com/goods/miband7.jpg",
      "goodsPrice": 199.00,
      "transactionAmount": 180.00,
      "buyerId": 789,
      "buyerName": "王五",
      "buyerImage": "https://cdn.example.com/avatar/user789.jpg",
      "buyerPhone": "13900139000",
      "buyerRealName": "王小五",
      "buyerSex": "女",
      "buyerJianjie": "喜欢运动健身",
      "buyerEvaluate": "东西不错，发货速度快",
      "buyerRating": 4,
      "buyerCreditScore": 380,
      "buyerCreditLevel": "O",
      "sellerId": 123,
      "sellerName": "李四",
      "sellerImage": "https://cdn.example.com/avatar/user123.jpg",
      "sellerCreditScore": 500,
      "sellerCreditLevel": "O",
      "transactionTime": "2025-11-17 15:30:00",
      "tradeStatus": 4,
      "createdTime": "2025-11-17 14:20:00"
    }
  ]
}
```

### 空数据响应

```json
{
  "code": 200,
  "msg": "成功",
  "data": []
}
```

### 错误响应

#### 参数缺失

```json
{
  "code": 500,
  "msg": "获取评价列表失败: 卖家ID不能为空",
  "data": null
}
```

#### 系统异常

```json
{
  "code": 500,
  "msg": "获取评价列表失败: 数据库连接异常",
  "data": null
}
```

---

## 业务规则

### 查询规则

1. **数据过滤**
   - ✅ 只返回有买家评价内容的记录（`buyer_evaluate IS NOT NULL AND buyer_evaluate != ''`）
   - ✅ 只返回未删除的记录（`delete_flag = 0`）
   - ✅ 按创建时间倒序排列（最新评价在前）

2. **数据关联**
   - 商品信息：通过 `goods_record_id` 关联 `second_goods_record` 表
   - 买家信息：通过 `buyer_id` 关联 `life_user` 表
   - 卖家信息：通过 `seller_id` 关联 `life_user` 表
   - 信用积分：通过 `user_id` 关联 `second_user_credit` 表
   - 风控等级：实时计算，查询 `second_risk_control_record` 表

3. **性能优化**
   - 使用批量查询避免 N+1 问题
   - 关联数据使用 Map 索引，时间复杂度 O(1)
   - 分组查询：商品、用户、积分分别批量获取

### 数据完整性

1. **字段缺失处理**
   - 如果商品记录已删除，商品相关字段返回 `null`
   - 如果用户信息不存在，用户相关字段返回 `null`
   - 如果没有信用积分记录，`creditScore` 返回 `0`
   - 风控等级计算异常时返回默认等级 `"O"`

2. **评分有效性**
   - 买家评分 `buyerRating` 有效范围：1-5 分
   - 如果未评分，该字段可能为 `null`

---

## 错误码说明

| HTTP状态码 | code | msg | 说明 | 解决方案 |
|-----------|------|-----|------|----------|
| 200 | 200 | 成功 | 请求成功 | - |
| 200 | 500 | 卖家ID不能为空 | 未传入 sellerId 参数 | 检查请求参数，确保传入 sellerId |
| 200 | 500 | 获取评价列表失败: xxx | 系统异常 | 查看日志，联系后端开发人员 |
| 500 | - | - | 服务器内部错误 | 联系后端开发人员 |

---

## 使用场景

### 1. 用户主页展示

在用户主页展示该用户作为卖家的历史交易评价，供其他用户查看。

**场景示例**：
- 用户 A 点击用户 B 的主页
- 展示用户 B 作为卖家收到的所有评价
- 显示评价内容、评分、买家信息等

### 2. 信用评估

通过评价内容、评分和风控等级综合评估卖家的信誉度。

**评估维度**：
- 评价数量：评价越多，信誉参考价值越高
- 平均评分：反映买家满意度
- 风控等级：反映用户违规情况
- 信用积分：反映用户交易活跃度

### 3. 交易决策辅助

买家在决定是否与某卖家交易时，可以查看其历史评价。

**决策参考**：
- 查看近期评价内容
- 查看风控评分等级
- 了解卖家信用积分
- 参考其他买家的评价

---

## 技术实现

### 实现方式

| 技术点 | 实现方案 |
|--------|----------|
| 查询方式 | MyBatis Plus LambdaQueryWrapper |
| 关联查询 | 批量查询 + Map 索引 |
| 风控计算 | 实时查询违规记录并计算等级 |
| 事务处理 | 无需事务（只读查询） |
| 性能优化 | 批量查询避免 N+1 问题 |

### 代码示例

```java
// 1. 查询交易记录
LambdaQueryWrapper<SecondTradeRecord> tradeWrapper = new LambdaQueryWrapper<>();
tradeWrapper.eq(SecondTradeRecord::getSellerId, sellerId)
        .eq(SecondTradeRecord::getDeleteFlag, 0)
        .isNotNull(SecondTradeRecord::getBuyerEvaluate)
        .ne(SecondTradeRecord::getBuyerEvaluate, "")
        .orderByDesc(SecondTradeRecord::getCreatedTime);
List<SecondTradeRecord> tradeRecords = mapper.selectList(tradeWrapper);

// 2. 批量查询商品信息
LambdaQueryWrapper<SecondGoodsRecord> goodsWrapper = new LambdaQueryWrapper<>();
goodsWrapper.in(SecondGoodsRecord::getId, goodsRecordIds);
List<SecondGoodsRecord> goodsRecords = goodsRecordMapper.selectList(goodsWrapper);

// 3. 批量查询用户信息
LambdaQueryWrapper<LifeUser> userWrapper = new LambdaQueryWrapper<>();
userWrapper.in(LifeUser::getId, buyerIds).eq(LifeUser::getDeleteFlag, 0);
List<LifeUser> buyers = lifeUserMapper.selectList(userWrapper);

// 4. 批量查询信用积分
LambdaQueryWrapper<SecondUserCredit> creditWrapper = new LambdaQueryWrapper<>();
creditWrapper.in(SecondUserCredit::getUserId, allUserIds)
        .eq(SecondUserCredit::getDeleteFlag, 0);
List<SecondUserCredit> credits = secondUserCreditMapper.selectList(creditWrapper);

// 5. 计算风控等级
String creditLevel = calculateCreditLevel(userId);
```

### 数据库表

| 表名 | 说明 | 关联字段 |
|------|------|----------|
| second_trade_record | 交易记录表 | 主表 |
| second_goods_record | 商品记录表 | goods_record_id |
| life_user | 用户表 | buyer_id, seller_id |
| second_user_credit | 用户信用积分表 | user_id |
| second_risk_control_record | 风控记录表 | user_id（用于计算等级） |

### 相关文件

1. **Controller**  
   `alien-second/src/main/java/shop/alien/second/controller/SecondTradeRecordController.java`

2. **Service Interface**  
   `alien-second/src/main/java/shop/alien/second/service/SecondTradeRecordService.java`

3. **Service Implementation**  
   `alien-second/src/main/java/shop/alien/second/service/impl/SecondTradeRecordServiceImpl.java`

4. **VO Object**  
   `alien-entity/src/main/java/shop/alien/entity/second/vo/SellerEvaluationVo.java`

5. **Entity**  
   `alien-entity/src/main/java/shop/alien/entity/second/SecondTradeRecord.java`

---

## 注意事项

### ⚠️ 重要提示

1. **必传参数**
   - `sellerId` 为必传参数，用于查看指定用户的评价列表
   - 不传或传空会返回错误：`"卖家ID不能为空"`

2. **数据权限**
   - 接口不做权限校验，任何人都可以查看用户主页的公开评价
   - 如需增加权限控制，请联系后端开发人员

3. **空数据处理**
   - 如果该用户没有收到任何评价，返回空数组 `[]`
   - 不会返回 `null`，前端可以直接遍历

4. **字段可空性**
   - 部分字段可能为 `null`，前端需要做空值判断
   - 建议使用可选链操作符或空值合并运算符

5. **评分范围**
   - 买家评分 `buyerRating` 的有效范围是 1-5 分
   - 超出范围的数据为异常数据

### 💡 最佳实践

1. **前端展示建议**
   ```javascript
   // 显示买家昵称，为空时显示默认值
   const buyerName = evaluation.buyerName || '匿名用户';
   
   // 显示评分，为空时显示未评分
   const rating = evaluation.buyerRating ? `${evaluation.buyerRating}分` : '未评分';
   
   // 风控等级颜色映射
   const levelColorMap = {
     'O': 'green',  // 最好
     'A': 'green',
     'B': 'orange',
     'C': 'orange',
     'D': 'red',
     'E': 'red'     // 最差
   };
   ```

2. **缓存策略**
   - 评价数据变化频率低，建议前端缓存
   - 缓存时间：5-10 分钟
   - 用户主动刷新时清除缓存

3. **分页处理**
   - 当前接口返回所有评价
   - 如评价数量过多，建议前端实现虚拟滚动
   - 或联系后端增加分页功能

---

## 测试用例

### 测试场景 1：正常查询

**测试步骤**：
1. 准备测试数据：用户 ID 为 123 的卖家有 3 条评价记录
2. 调用接口：`GET /secondTradeRecord/getSellerEvaluationList?sellerId=123`
3. 验证响应：返回 3 条评价数据

**期望结果**：
- 返回 code = 200
- data 数组长度为 3
- 每条数据包含完整字段
- 按创建时间倒序排列

---

### 测试场景 2：无评价数据

**测试步骤**：
1. 准备测试数据：用户 ID 为 999 的卖家没有任何评价
2. 调用接口：`GET /secondTradeRecord/getSellerEvaluationList?sellerId=999`
3. 验证响应：返回空数组

**期望结果**：
- 返回 code = 200
- data 为空数组 `[]`

---

### 测试场景 3：参数缺失

**测试步骤**：
1. 调用接口：`GET /secondTradeRecord/getSellerEvaluationList`（不传 sellerId）
2. 验证响应：返回错误信息

**期望结果**：
- 返回 code = 500
- msg = "获取评价列表失败: 卖家ID不能为空"

---

### 测试场景 4：风控等级计算

**测试步骤**：
1. 准备测试数据：
   - 买家 A（ID 456）有 2 条违规记录
   - 买家 B（ID 789）有 0 条违规记录
2. 调用接口查询包含这两位买家的评价
3. 验证风控等级

**期望结果**：
- 买家 A 的 `buyerCreditLevel` = "A"
- 买家 B 的 `buyerCreditLevel` = "O"

---

## 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2025-11-18 | 初始版本，实现基本功能 | 开发团队 |
| v1.0 | 2025-11-18 | 优化查询方式，使用 MyBatis Plus | 开发团队 |
| v1.0 | 2025-11-18 | 增加风控评分等级计算 | 开发团队 |
| v1.0 | 2025-11-18 | 增加更多用户信息字段 | 开发团队 |

---

## 联系方式

如有问题或建议，请联系：

- **开发团队**：二手交易平台开发组
- **服务名称**：alien-second
- **文档路径**：`alien-second/doc/获取卖家交易评价列表接口文档.md`

---

*最后更新时间：2025-11-18*