Почетна Преглед Помоћ
Пријавите се
alien
/
alien_cloud
13
0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Грана: n-member
Гране Ознаке
alien_cloud
/
alien-second
/
doc
/
委托人详情查询接口文档.md

委托人详情查询接口文档.md 18 KB
Пермалинк Историја Датотека

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

接口概述

接口信息

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

功能描述

根据委托人的姓名和身份证号获取该人的完整详情信息，以人为维度聚合查询所有相关数据，包含：

  • 委托人基本信息
  • 该人所有委托记录关联的所有交易记录列表
  • 每条交易记录包含：
    • 交易基本信息（交易编号、金额、状态等）
    • 买卖双方信息（姓名、电话）
    • 交易操作节点信息（交易流程）
    • 商品信息

查询逻辑：

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

请求参数

Query Parameters

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

请求示例

cURL

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

JavaScript (Axios)

// 获取委托人详情
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)

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<SecondTradeRecordVo> 该人所有委托记录关联的交易记录集合

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<JSONObject> ✅ 交易操作节点列表，展示完整交易流程

每个操作节点包含：

  • operationType: 操作类型
  • operationTime: 操作时间
  • operationUserId: 操作人ID
  • operationUserName: 操作人姓名
  • operationDesc: 操作描述

响应示例

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

{
  "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笔交易，接口返回了他所有的交易信息，按创建时间倒序排列。

委托人不存在

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

参数缺失

{
  "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

<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 - 以人为维度）