6.3 KiB
6.3 KiB
碰撞避免系统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
发送控制指令给无人车，支持告警、信号灯、预警、恢复等指令类型。
请求参数:
{
"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" // 最小距离(可选)
}
响应结果:
{
"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
响应结果:
{
"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
查询无人车状态信息，支持单个车辆或所有车辆查询。
请求参数:
{
"transId": "string", // 消息唯一ID
"timestamp": "long", // 时间戳
"vehicleId": "string", // 车辆ID
"isSingle": "boolean" // true:单个车辆, false:所有车辆
}
响应结果:
{
"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 统一错误响应格式
{
"code": "int", // 错误代码
"message": "string", // 错误信息
"timestamp": "long", // 错误时间戳
"path": "string" // 请求路径
}
4.2 常见错误代码
200: 请求成功400: 请求参数错误401: 认证失败404: 资源不存在500: 服务器内部错误
5. 配置参数
5.1 无人车控制配置
unmanned-vehicle:
control:
timeout: 30000 # 控制指令超时时间(毫秒)
max-retry: 3 # 最大重试次数
batch-size: 100 # 批量处理大小
history-retention: 30 # 历史数据保留天数
5.2 数据持久化配置
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%