QDAirPortBackend0122/doc/design/vehicle-trajectory-api.md

车辆轨迹查询和回放API文档

概述

本文档描述了车辆轨迹查询和回放功能的API接口，支持无人车轨迹回放和车辆行驶信息轨迹回放需求。

接口列表

1. 车辆轨迹查询接口

接口地址： GET /system/vehicle_location/trajectory/{vehicleId}

功能描述： 查询指定车辆在指定时间段内的运行轨迹，支持数据简化和采样优化

请求参数：

• vehicleId (路径参数): 车辆ID
• startTime (查询参数): 开始时间，格式：yyyy-MM-dd HH:mm:ss
• endTime (查询参数): 结束时间，格式：yyyy-MM-dd HH:mm:ss
• simplified (查询参数，可选): 是否简化数据，默认false
• maxPoints (查询参数，可选): 最大轨迹点数量，默认1000

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "vehicleId": 1,
    "licensePlate": "测A12345",
    "vehicleType": "无人车",
    "brand": "品牌A",
    "owningUnit": "测试单位",
    "startTime": "2025-01-17 08:00:00",
    "endTime": "2025-01-17 18:00:00",
    "statistics": {
      "pointCount": 360,
      "totalDistance": 15.68,
      "averageSpeed": 25.5,
      "maxSpeed": 45.2,
      "durationSeconds": 3600,
      "durationFormatted": "1小时0分钟"
    },
    "points": [
      {
        "longitude": 116.397128,
        "latitude": 39.916527,
        "altitude": 45.5,
        "speed": 25.8,
        "heading": 135.5,
        "timestamp": "2025-01-17 08:00:00",
        "dataQuality": "HIGH"
      }
    ],
    "simplified": false
  }
}

2. 轨迹回放数据接口

接口地址： GET /system/vehicle_location/trajectory/{vehicleId}/playback

功能描述： 获取用于轨迹回放的数据，按指定时间间隔采样，包含回放所需的序列和时间信息

请求参数：

• vehicleId (路径参数): 车辆ID
• startTime (查询参数): 开始时间，格式：yyyy-MM-dd HH:mm:ss
• endTime (查询参数): 结束时间，格式：yyyy-MM-dd HH:mm:ss
• intervalSeconds (查询参数，可选): 时间间隔(秒)，默认10

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "vehicleId": 1,
      "licensePlate": "测A12345",
      "sequenceNumber": 1,
      "longitude": 116.397128,
      "latitude": 39.916527,
      "speed": 25.8,
      "timestamp": "2025-01-17 08:00:00",
      "intervalMs": 0,
      "cumulativeDistance": 0.0,
      "progressPercentage": 0.0,
      "isKeyFrame": true,
      "keyFrameType": "START",
      "suggestedDelay": 1000
    },
    {
      "vehicleId": 1,
      "licensePlate": "测A12345",
      "sequenceNumber": 2,
      "longitude": 116.398128,
      "latitude": 39.917527,
      "speed": 30.0,
      "timestamp": "2025-01-17 08:00:10",
      "intervalMs": 10000,
      "cumulativeDistance": 125.6,
      "progressPercentage": 25.5,
      "isKeyFrame": false,
      "suggestedDelay": 5000
    }
  ]
}

3. 多车辆轨迹查询接口

接口地址： POST /system/vehicle_location/trajectory/batch

功能描述： 批量查询多个车辆的运行轨迹，支持复杂查询条件

请求体示例：

{
  "vehicleIds": [1, 2, 3],
  "startTime": "2025-01-17 08:00:00",
  "endTime": "2025-01-17 18:00:00",
  "simplified": false,
  "maxPoints": 1000,
  "includeStatistics": true,
  "includeGeoJson": false
}

4. 区域内轨迹查询接口

接口地址： GET /system/vehicle_location/trajectory/{vehicleId}/area

功能描述： 查询车辆在指定区域内的运行轨迹

请求参数：

• vehicleId (路径参数): 车辆ID
• startTime (查询参数): 开始时间
• endTime (查询参数): 结束时间
• areaWkt (查询参数): 区域WKT格式字符串

5. 轨迹统计信息查询接口

接口地址： GET /system/vehicle_location/trajectory/{vehicleId}/statistics

功能描述： 获取车辆轨迹的统计信息，如总距离、平均速度、行驶时长等

请求参数：

• vehicleId (路径参数): 车辆ID
• startTime (查询参数): 开始时间
• endTime (查询参数): 结束时间

使用场景

轨迹查询 vs 轨迹回放

1. 轨迹查询接口 适用于：

   • 静态轨迹展示
   • 轨迹分析
   • 数据导出
   • 历史轨迹查看

2. 轨迹回放接口 适用于：

   • 动画回放
   • 实时模拟
   • 时间轴播放
   • 交互式回放控制

技术特性

• 智能采样：根据时间间隔和点数限制自动优化轨迹数据
• 统计计算：利用PostGIS计算精确的距离和轨迹统计
• 回放优化：提供专门的回放数据格式，支持前端动画
• 性能优化：通过索引和查询优化支持大数据量轨迹查询
• 空间查询：支持区域内轨迹过滤功能

错误码

• 200: 操作成功
• 400: 参数错误
• 404: 数据不存在
• 500: 服务器内部错误

测试命令

1. 轨迹查询接口

curl -X GET "http://localhost:8080/system/vehicle_location/trajectory/5?startTime=2025-01-01%2000:00:00&endTime=2025-10-17%2023:59:59&simplified=false&maxPoints=100" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

2. 轨迹回放接口

curl -X GET "http://localhost:8080/system/vehicle_location/trajectory/5/playback?startTime=2025-01-01%2000:00:00&endTime=2025-10-17%2023:59:59&intervalSeconds=10" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

3. 轨迹统计信息接口

curl -X GET "http://localhost:8080/system/vehicle_location/trajectory/5/statistics?startTime=2025-01-01%2000:00:00&endTime=2025-10-17%2023:59:59" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

4. 批量轨迹查询接口

curl -X POST "http://localhost:8080/system/vehicle_location/trajectory/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleIds": [5, 6],
    "startTime": "2025-01-01 00:00:00",
    "endTime": "2025-10-17 23:59:59",
    "simplified": false,
    "maxPoints": 100,
    "includeStatistics": true
  }' \
  -w "\nHTTP Status: %{http_code}\n"

5. 区域内轨迹查询接口

curl -X GET "http://localhost:8080/system/vehicle_location/trajectory/5/area?startTime=2025-01-01%2000:00:00&endTime=2025-10-17%2023:59:59&areaWkt=POLYGON((116.3%2039.9,116.4%2039.9,116.4%2040.0,116.3%2040.0,116.3%2039.9))" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"