QAUP_Management/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

**响应示例：**
```json
{
  "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

**响应示例：**
```json
{
  "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`

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

**请求体示例：**
```json
{
  "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. 轨迹查询接口

```bash
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. 轨迹回放接口

```bash
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. 轨迹统计信息接口

```bash
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. 批量轨迹查询接口

```bash
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. 区域内轨迹查询接口

```bash
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"
```