218 lines
6.3 KiB
Markdown
218 lines
6.3 KiB
Markdown
# 碰撞避免系统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% |