# 委托人详情查询接口文档（以人为维度）

## 接口概述

### 接口信息

| 项目 | 内容 |
|------|------|
| 接口名称 | 根据姓名和身份证号获取委托人详情 |
| 接口路径 | `/secondEntrustUser/detail` |
| 请求方式 | GET |
| 接口版本 | v2.0 |
| 开发时间 | 2025-11-21 |
| 接口状态 | ✅ 已完成 |

### 功能描述

根据委托人的**姓名和身份证号**获取该人的完整详情信息，**以人为维度聚合查询所有相关数据**，包含：
- 委托人基本信息
- **该人所有委托记录关联的所有交易记录列表**
- 每条交易记录包含：
  - 交易基本信息（交易编号、金额、状态等）
  - 买卖双方信息（姓名、电话）
  - **交易操作节点信息（交易流程）**
  - 商品信息

**查询逻辑**：
1. 根据"姓名+身份证号"查询该人的所有委托记录
2. 收集所有委托记录关联的交易ID
3. 批量查询所有交易记录及详细信息
4. 为每笔交易添加操作节点信息（参考 `/admin/secondGoods/detail` 接口逻辑）

---

## 请求参数

### Query Parameters

| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| userName | String | ✅ 是 | 委托人姓名 | 张三 |
| idCard | String | ✅ 是 | 委托人身份证号 | 110101199001011234 |

### 请求示例

#### cURL

```bash
# 获取委托人详情
curl -X GET "http://localhost:8080/secondEntrustUser/detail?userName=张三&idCard=110101199001011234" \
  -H "Authorization: Bearer your_token_here"
```

#### JavaScript (Axios)

```javascript
// 获取委托人详情
axios.get('/secondEntrustUser/detail', {
  params: {
    userName: '张三',
    idCard: '110101199001011234'
  },
  headers: {
    'Authorization': 'Bearer your_token_here'
  }
})
.then(response => {
  const { entrustUserInfo, tradeRecords } = response.data.data;
  console.log('委托人信息：', entrustUserInfo);
  console.log('该人所有交易记录：', tradeRecords);
  console.log('交易总数：', tradeRecords.length);
})
.catch(error => {
  console.error(error);
});
```

#### Java (RestTemplate)

```java
String url = "http://localhost:8080/secondEntrustUser/detail" +
             "?userName=张三&idCard=110101199001011234";
RestTemplate restTemplate = new RestTemplate();
R<SecondEntrustUserDetailVo> result = restTemplate.getForObject(url, R.class);

SecondEntrustUserDetailVo detailVo = result.getData();
SecondEntrustUser entrustUserInfo = detailVo.getEntrustUserInfo();
List<SecondTradeRecordVo> tradeRecords = detailVo.getTradeRecords();

System.out.println("委托人姓名：" + entrustUserInfo.getUserName());
System.out.println("该人关联的交易总数：" + tradeRecords.size());
```

---

## 响应参数

### 响应结构

| 字段名 | 类型 | 描述 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data | SecondEntrustUserDetailVo | 委托人详情对象 |

### SecondEntrustUserDetailVo 对象结构

| 字段名 | 类型 | 描述 |
|--------|------|------|
| entrustUserInfo | SecondEntrustUser | 委托人基本信息（该人的第一条记录） |
| tradeRecords | Array&lt;SecondTradeRecordVo&gt; | 该人所有委托记录关联的交易记录集合 |

### SecondEntrustUser 委托人信息结构

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| id | Integer | ✅ | 委托人记录ID | 1 |
| tradeId | Integer | ✅ | 关联的交易ID | 100 |
| userName | String | ✅ | 委托人姓名 | 张三 |
| userPhone | String | ✅ | 委托人电话 | 13800138000 |
| idCard | String | ✅ | 委托人身份证号 | 110101199001011234 |
| idCardImg | String | ❌ | 委托人身份证照片URL | https://cdn.example.com/idcard/123.jpg |
| deleteFlag | Integer | ✅ | 删除标记（0:未删除，1:已删除） | 0 |
| createdTime | Date | ✅ | 创建时间 | 2025-11-21 10:00:00 |
| updatedTime | Date | ✅ | 更新时间 | 2025-11-21 10:00:00 |

### SecondTradeRecordVo 交易记录结构

#### 交易基本信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| id | Integer | ✅ | 交易记录ID | 100 |
| tradeNo | String | ✅ | 交易编号 | S2025112100001 |
| goodsId | Integer | ✅ | 商品ID | 200 |
| goodsRecordId | Integer | ✅ | 商品记录ID | 300 |
| transactionAmount | BigDecimal | ✅ | 交易金额（元） | 3800.00 |
| tradeStatus | Integer | ✅ | 交易状态 | 4 |
| transactionTime | Date | ❌ | 交易时间 | 2025-11-21 14:00:00 |
| transactionLocation | String | ❌ | 交易地点 | 北京市朝阳区xxx |
| createdTime | Date | ✅ | 创建时间 | 2025-11-21 10:00:00 |

#### 买卖双方信息

| 字段名 | 类型 | 是否必返 | 描述 | 示例值 |
|--------|------|----------|------|--------|
| buyerId | Integer | ✅ | 买方ID | 456 |
| buyerName | String | ❌ | 买方姓名 | 李四 |
| buyerPhone | String | ❌ | 买方电话 | 13900139000 |
| sellerId | Integer | ✅ | 卖方ID | 789 |
| sellerName | String | ❌ | 卖方姓名 | 王五 |
| sellerPhone | String | ❌ | 卖方电话 | 13700137000 |

#### 交易操作节点信息

| 字段名 | 类型 | 是否必返 | 描述 |
|--------|------|----------|------|
| operationJsonList | Array&lt;JSONObject&gt; | ✅ | 交易操作节点列表，展示完整交易流程 |

每个操作节点包含：
- `operationType`: 操作类型
- `operationTime`: 操作时间
- `operationUserId`: 操作人ID
- `operationUserName`: 操作人姓名
- `operationDesc`: 操作描述

---

## 响应示例

### 成功响应（张三有3条委托记录）

```json
{
  "code": 200,
  "msg": "成功",
  "data": {
    "entrustUserInfo": {
      "id": 1,
      "tradeId": 100,
      "userName": "张三",
      "userPhone": "13800138000",
      "idCard": "110101199001011234",
      "idCardImg": "https://cdn.example.com/idcard/123.jpg",
      "deleteFlag": 0,
      "createdTime": "2025-11-21 10:00:00",
      "updatedTime": "2025-11-21 10:00:00"
    },
    "tradeRecords": [
      {
        "id": 102,
        "tradeNo": "S2025112100003",
        "goodsId": 202,
        "goodsRecordId": 302,
        "transactionAmount": 2800.00,
        "tradeStatus": 4,
        "transactionTime": "2025-11-21 15:30:00",
        "transactionLocation": "北京市海淀区xxx",
        "buyerId": 456,
        "buyerName": "李四",
        "buyerPhone": "13900139000",
        "sellerId": 789,
        "sellerName": "王五",
        "sellerPhone": "13700137000",
        "createdTime": "2025-11-21 15:00:00",
        "operationJsonList": [
          {
            "operationType": "CREATE",
            "operationTime": "2025-11-21 15:00:00",
            "operationUserId": 456,
            "operationUserName": "李四",
            "operationDesc": "创建交易"
          },
          {
            "operationType": "COMPLETE",
            "operationTime": "2025-11-21 15:30:00",
            "operationUserId": 456,
            "operationUserName": "李四",
            "operationDesc": "完成交易"
          }
        ]
      },
      {
        "id": 101,
        "tradeNo": "S2025112100002",
        "goodsId": 201,
        "goodsRecordId": 301,
        "transactionAmount": 4500.00,
        "tradeStatus": 4,
        "transactionTime": "2025-11-21 14:00:00",
        "transactionLocation": "北京市朝阳区xxx",
        "buyerId": 457,
        "buyerName": "赵六",
        "buyerPhone": "13600136000",
        "sellerId": 788,
        "sellerName": "孙七",
        "sellerPhone": "13500135000",
        "createdTime": "2025-11-21 13:30:00",
        "operationJsonList": [
          {
            "operationType": "CREATE",
            "operationTime": "2025-11-21 13:30:00",
            "operationUserId": 457,
            "operationUserName": "赵六",
            "operationDesc": "创建交易"
          },
          {
            "operationType": "COMPLETE",
            "operationTime": "2025-11-21 14:00:00",
            "operationUserId": 457,
            "operationUserName": "赵六",
            "operationDesc": "完成交易"
          }
        ]
      },
      {
        "id": 100,
        "tradeNo": "S2025112100001",
        "goodsId": 200,
        "goodsRecordId": 300,
        "transactionAmount": 3800.00,
        "tradeStatus": 4,
        "transactionTime": "2025-11-21 10:00:00",
        "transactionLocation": "北京市东城区xxx",
        "buyerId": 455,
        "buyerName": "周八",
        "buyerPhone": "13400134000",
        "sellerId": 787,
        "sellerName": "吴九",
        "sellerPhone": "13300133000",
        "createdTime": "2025-11-21 09:30:00",
        "operationJsonList": [
          {
            "operationType": "CREATE",
            "operationTime": "2025-11-21 09:30:00",
            "operationUserId": 455,
            "operationUserName": "周八",
            "operationDesc": "创建交易"
          },
          {
            "operationType": "COMPLETE",
            "operationTime": "2025-11-21 10:00:00",
            "operationUserId": 455,
            "operationUserName": "周八",
            "operationDesc": "完成交易"
          }
        ]
      }
    ]
  }
}
```

**说明**：张三（身份证号 110101199001011234）有3条委托记录，关联了3笔交易，接口返回了他所有的交易信息，按创建时间倒序排列。

### 委托人不存在

```json
{
  "code": 500,
  "msg": "委托人信息不存在",
  "data": null
}
```

### 参数缺失

```json
{
  "code": 500,
  "msg": "委托人姓名不能为空",
  "data": null
}
```

---

## 业务规则

### 查询规则

1. **查询维度**
   - ✅ 以"姓名+身份证号"为唯一标识
   - ✅ 查询该人的所有委托记录
   - ✅ 聚合该人所有委托记录关联的交易信息

2. **数据聚合**
   - 根据姓名和身份证号查询所有委托记录
   - 收集所有委托记录的 `tradeId`
   - 批量查询所有交易记录（自动去重）
   - 只返回未删除的记录（`delete_flag = 0`）

3. **交易记录排序**
   - ✅ 按交易创建时间倒序排列（最新的在前）

4. **交易详情处理**
   - ✅ 每条交易记录包含完整的买卖双方信息
   - ✅ **自动加载交易操作节点信息（参考商品详情接口逻辑）**
   - ✅ 操作节点按时间顺序排列，展示完整交易流程

5. **数据关联**
   - 委托人记录：从 `second_entrust_user` 表根据姓名和身份证号查询
   - 交易记录：从 `second_trade_record` 表根据 `tradeId` 列表查询
   - 买卖双方：通过 `buyer_id` 和 `seller_id` 关联 `life_user` 表
   - 操作节点：从 `second_trade_operation` 表获取交易流程

---

## 交易状态说明

### 交易状态 (tradeStatus)

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

---

## 使用场景

### 场景：查看某个委托人的完整交易历史

从分页列表点击某个委托人后，使用该接口获取该人的完整信息。

**步骤**：
1. 用户在分页列表看到"张三（110101199001011234）有3条委托记录"
2. 点击"查看详情"
3. 调用接口：`GET /secondEntrustUser/detail?userName=张三&idCard=110101199001011234`
4. 返回张三的基本信息和他所有的交易记录（3笔）
5. 每笔交易都包含完整的交易流程节点

**应用场景**：
- 委托人详情页展示
- 交易历史查询
- 纠纷处理和审核
- 数据分析和统计

---

## 前端实现示例

### Vue 3 + Element Plus

```vue
<template>
  <div class="entrust-user-detail">
    <el-page-header @back="goBack" title="返回列表">
      <template #content>
        <span class="page-title">委托人详情</span>
      </template>
    </el-page-header>

    <!-- 委托人基本信息 -->
    <el-card class="info-card" v-if="entrustUserInfo" style="margin-top: 20px;">
      <template #header>
        <div class="card-header">
          <span>委托人信息</span>
        </div>
      </template>
      <el-descriptions :column="2" border>
        <el-descriptions-item label="姓名">
          {{ entrustUserInfo.userName }}
        </el-descriptions-item>
        <el-descriptions-item label="身份证号">
          {{ entrustUserInfo.idCard }}
        </el-descriptions-item>
        <el-descriptions-item label="联系电话">
          {{ entrustUserInfo.userPhone }}
        </el-descriptions-item>
        <el-descriptions-item label="首次委托时间">
          {{ entrustUserInfo.createdTime }}
        </el-descriptions-item>
      </el-descriptions>
    </el-card>

    <!-- 交易记录列表 -->
    <el-card class="trade-card" style="margin-top: 20px;">
      <template #header>
        <div class="card-header">
          <span>关联交易记录（共 {{ tradeRecords.length }} 笔）</span>
        </div>
      </template>
      
      <el-timeline v-if="tradeRecords.length > 0">
        <el-timeline-item
          v-for="trade in tradeRecords"
          :key="trade.id"
          :timestamp="trade.createdTime"
          placement="top"
        >
          <el-card>
            <h4>交易编号：{{ trade.tradeNo }}</h4>
            <el-row :gutter="20">
              <el-col :span="12">
                <p>交易金额：<el-tag type="danger">¥{{ trade.transactionAmount }}</el-tag></p>
                <p>交易状态：<el-tag :type="getStatusType(trade.tradeStatus)">
                  {{ getTradeStatusText(trade.tradeStatus) }}
                </el-tag></p>
              </el-col>
              <el-col :span="12">
                <p>买方：{{ trade.buyerName }}（{{ trade.buyerPhone }}）</p>
                <p>卖方：{{ trade.sellerName }}（{{ trade.sellerPhone }}）</p>
              </el-col>
            </el-row>
            
            <!-- 交易操作流程 -->
            <el-divider content-position="left">交易流程</el-divider>
            <el-steps
              :active="trade.operationJsonList.length"
              finish-status="success"
              align-center
            >
              <el-step
                v-for="(operation, index) in trade.operationJsonList"
                :key="index"
                :title="operation.operationDesc"
                :description="`${operation.operationTime} - ${operation.operationUserName}`"
              />
            </el-steps>
          </el-card>
        </el-timeline-item>
      </el-timeline>
      
      <el-empty v-else description="暂无交易记录" />
    </el-card>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import axios from 'axios';
import { ElMessage } from 'element-plus';

const route = useRoute();
const router = useRouter();
const userName = ref(route.query.userName);
const idCard = ref(route.query.idCard);
const entrustUserInfo = ref(null);
const tradeRecords = ref([]);
const loading = ref(false);

// 交易状态映射
const tradeStatusMap = {
  1: '待确认',
  2: '已拒绝',
  3: '待交易',
  4: '交易成功',
  5: '交易失败',
  6: '交易取消'
};

const getTradeStatusText = (status) => {
  return tradeStatusMap[status] || '未知状态';
};

const getStatusType = (status) => {
  const typeMap = {
    1: 'info',
    2: 'danger',
    3: 'warning',
    4: 'success',
    5: 'danger',
    6: 'info'
  };
  return typeMap[status] || 'info';
};

const goBack = () => {
  router.back();
};

// 加载委托人详情
const loadDetail = async () => {
  loading.value = true;
  try {
    const response = await axios.get('/secondEntrustUser/detail', {
      params: {
        userName: userName.value,
        idCard: idCard.value
      }
    });
    
    const data = response.data.data;
    entrustUserInfo.value = data.entrustUserInfo;
    tradeRecords.value = data.tradeRecords || [];
  } catch (error) {
    ElMessage.error('加载失败：' + error.message);
  } finally {
    loading.value = false;
  }
};

onMounted(() => {
  if (userName.value && idCard.value) {
    loadDetail();
  } else {
    ElMessage.error('缺少必要参数');
    router.back();
  }
});
</script>

<style scoped>
.entrust-user-detail {
  padding: 20px;
}

.page-title {
  font-size: 18px;
  font-weight: bold;
}

.card-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
}
</style>
```

---

## 错误码说明

| HTTP状态码 | code | msg | 说明 | 解决方案 |
|-----------|------|-----|------|----------|
| 200 | 200 | 成功 | 请求成功 | - |
| 200 | 500 | 委托人信息不存在 | 该姓名和身份证号组合不存在 | 检查参数是否正确 |
| 200 | 500 | 委托人姓名不能为空 | 未传入姓名参数 | 必须传入userName参数 |
| 200 | 500 | 委托人身份证号不能为空 | 未传入身份证号参数 | 必须传入idCard参数 |
| 200 | 500 | 获取委托人详情失败: xxx | 系统异常 | 查看日志，联系后端开发人员 |
| 500 | - | - | 服务器内部错误 | 联系后端开发人员 |

---

## 注意事项

### ⚠️ 重要提示

1. **必传参数**
   - `userName` 和 `idCard` 都是必传参数
   - 两个参数必须同时传入且正确匹配

2. **查询维度**
   - 以"姓名+身份证号"为唯一标识
   - 返回该人所有委托记录关联的所有交易信息
   - 同一个人可能有多笔交易

3. **交易记录**
   - 交易记录按创建时间倒序排列
   - 只返回未删除的交易记录
   - 每笔交易都包含完整的操作节点信息

4. **操作节点信息**
   - 参考了 `/admin/secondGoods/detail` 接口的实现逻辑
   - 展示完整的交易流程
   - 包含操作时间、操作人、操作描述等信息

5. **性能考虑**
   - 如果该人关联的交易记录过多，可能影响响应速度
   - 建议在前端做分页展示或懒加载

---

## 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2025-11-21 | 初始版本，根据主键ID查询 | 开发团队 |
| v2.0 | 2025-11-21 | **重大更新：改为根据姓名+身份证号查询，以人为维度聚合交易** | 开发团队 |

---

## 联系方式

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

- **开发团队**：二手交易平台开发组
- **服务名称**：alien-second
- **Controller**：SecondEntrustUserController
- **文档路径**：`alien-second/doc/委托人详情查询接口文档.md`

---

*最后更新时间：2025-11-21（v2.0 - 以人为维度）*