# 碰撞避免系统API文档

## 版本信息
- 版本: 0.5.1
- 更新日期: 2025-01-15
- 维护者: 开发团队

## 概述
本文档描述了碰撞避免系统的API接口，包括外部数据接入接口和无人车控制接口。

## 1. 外部数据接入接口

### 1.1 航空器位置数据接入
- **功能**: 接入并处理从空管接收到的航空器融合位置数据
- **数据流**: 实时数据，不持久化存储，仅用于实时处理和推送
- **处理策略**: 数据缓存到Redis，通过WebSocket推送给前端

### 1.2 车辆位置数据接入  
- **功能**: 接入机场已有车辆位置数据
- **数据流**: 实时数据，不持久化存储，仅用于实时处理和推送
- **处理策略**: 数据缓存到Redis，通过WebSocket推送给前端

## 2. 无人车控制接口

### 2.1 控制指令接口
**POST /api/unmanned-vehicle/command**

发送控制指令给无人车，支持告警、信号灯、预警、恢复等指令类型。

**请求参数:**
```json
{
  "transId": "string",           // 消息唯一ID
  "timestamp": "long",           // 时间戳
  "vehicleId": "string",         // 车辆ID
  "commandType": "string",       // 指令类型: ALERT, SIGNAL, WARNING, RESUME
  "commandReason": "string",     // 指令原因: TRAFFIC_LIGHT, AIRCRAFT_CROSSING等
  "signalState": "string",       // 信号灯状态(可选): RED, GREEN, YELLOW
  "intersectionId": "string",    // 路口ID(可选)
  "latitude": "double",          // 目标位置纬度
  "longitude": "double",         // 目标位置经度
  "relativeSpeed": "double",     // 相对速度(可选)
  "relativeMotionX": "double",   // 相对运动X分量(可选)
  "relativeMotionY": "double",   // 相对运动Y分量(可选)
  "minDistance": "double"        // 最小距离(可选)
}
```

**响应结果:**
```json
{
  "code": 200,
  "message": "控制指令执行成功",
  "data": {
    "transId": "string",         // 与请求ID一致
    "timestamp": "long",         // 处理时间戳
    "vehicleId": "string",       // 车辆ID
    "status": "string"           // 执行状态
  }
}
```

**数据持久化:** 控制指令会保存到数据库，包含PostGIS空间数据支持。

### 2.2 位置上报接口
**GET /api/unmanned-vehicle/location/{vehicleId}**

获取指定无人车的位置信息。

**路径参数:**
- `vehicleId`: 车辆ID

**响应结果:**
```json
{
  "code": 200,
  "message": "位置信息获取成功",
  "data": {
    "transId": "string",         // 消息唯一ID
    "timestamp": "long",         // 时间戳
    "vehicleId": "string",       // 车辆ID
    "latitude": "double",        // 纬度
    "longitude": "double",       // 经度
    "speed": "double",           // 速度(m/s)
    "direction": "double"        // 车头航向角(弧度)
  }
}
```

**数据持久化:** 无人车位置数据会保存到数据库。

### 2.3 状态查询接口
**POST /api/unmanned-vehicle/state**

查询无人车状态信息，支持单个车辆或所有车辆查询。

**请求参数:**
```json
{
  "transId": "string",           // 消息唯一ID
  "timestamp": "long",           // 时间戳
  "vehicleId": "string",         // 车辆ID
  "isSingle": "boolean"          // true:单个车辆, false:所有车辆
}
```

**响应结果:**
```json
{
  "code": 200,
  "message": "状态查询成功",
  "data": [
    {
      "transId": "string",       // 消息唯一ID
      "timestamp": "long",       // 时间戳
      "vehicleId": "string",     // 车辆ID
      "loginState": "boolean",   // 登录状态
      "faultInfo": ["string"],   // 故障信息列表
      "activeSafety": "boolean", // 主动安全触发状态
      "rc": "boolean",           // 远控模式状态
      "command": "int",          // 远程指令: 0恢复, 1急停, 2缓停
      "airportInfo": ["string"], // 机场特殊信息
      "vehicleMode": "int",      // 控制模式: 1手动, 2自动, 3遥控器, 4远程, 5故障
      "gearState": "int",        // 档位: 1N, 2D, 3P, 4R, 5未知
      "chassisReady": "boolean", // 底盘就绪状态
      "collisionStatus": "boolean", // 防撞梁触发状态
      "clearance": "int",        // 示廓灯状态: 0关闭, 1开启
      "turnSignalStatus": "int", // 转向灯: 0关闭, 1左转, 2右转, 3双闪
      "pointCloud": ["byte"]     // 点云数据(可选)
    }
  ]
}
```

## 3. 数据持久化策略

### 3.1 存储策略
- **无人车数据**: 控制指令和位置数据会持久化存储到PostgreSQL数据库
- **航空器数据**: 仅实时处理，不持久化存储
- **其他车辆数据**: 仅实时处理，不持久化存储

### 3.2 空间数据支持
- 使用PostGIS扩展处理地理位置数据
- 支持空间索引和空间查询
- 经纬度数据以POINT几何类型存储

### 3.3 实时数据流
- 使用Redis缓存实时位置数据
- 通过WebSocket推送实时数据给前端
- 数据过期时间30秒，推送频率2秒

## 4. 错误处理

### 4.1 统一错误响应格式
```json
{
  "code": "int",              // 错误代码
  "message": "string",        // 错误信息
  "timestamp": "long",        // 错误时间戳
  "path": "string"           // 请求路径
}
```

### 4.2 常见错误代码
- `200`: 请求成功
- `400`: 请求参数错误
- `401`: 认证失败
- `404`: 资源不存在
- `500`: 服务器内部错误

## 5. 配置参数

### 5.1 无人车控制配置
```yaml
unmanned-vehicle:
  control:
    timeout: 30000           # 控制指令超时时间(毫秒)
    max-retry: 3            # 最大重试次数
    batch-size: 100         # 批量处理大小
    history-retention: 30   # 历史数据保留天数
```

### 5.2 数据持久化配置
```yaml
data-persistence:
  vehicle-types:
    store: ["UNMANNED"]     # 需要持久化的车辆类型
    exclude: ["AIRCRAFT", "SPECIAL"]  # 排除的车辆类型
  batch:
    size: 50               # 批量插入大小
    timeout: 5000          # 批量操作超时时间
```

## 6. 安全考虑

### 6.1 数据验证
- 所有输入参数进行严格验证
- 地理坐标范围验证
- 时间戳合理性检查

### 6.2 访问控制
- API接口需要适当的认证和授权
- 敏感操作记录审计日志
- 控制指令执行权限管理

## 7. 性能监控

### 7.1 关键指标
- 控制指令响应时间
- 数据处理吞吐量
- 数据库连接池状态
- Redis缓存命中率

### 7.2 告警阈值
- 响应时间 > 1000ms
- 错误率 > 5%
- 数据库连接数 > 80%
- 内存使用率 > 85%