Doni/QDAirPortBackend0122

Fork 0

sladro 725c0be448 Initial commit

2026-01-22 13:19:47 +08:00

25 KiB

Raw Blame History

通用无人车运行状态API设计方案

1. 设计原则

1.1 行业标准参考

ISO 26262: 汽车功能安全标准
SAE J3016: 自动驾驶分级标准
ISO 21448: 预期功能安全标准(SOTIF)
IEEE 2857: 自动驾驶系统隐私工程标准
AC-137-CA-202X-XX: 民用机场无人驾驶车辆检测规范（报批稿）

1.2 API设计原则

RESTful设计: 遵循REST架构风格
版本控制: 支持API版本管理
统一响应格式: 标准化的响应结构
错误处理: 完善的错误码和错误信息
安全性: 认证授权机制
可扩展性: 支持未来功能扩展

2. API接口设计

2.1 基础信息

接口地址: GET /api/v1/vehicles/{vehicleId}/status

认证方式: Bearer Token (JWT)

内容类型: application/json

2.2 请求参数

路径参数

参数名	类型	必填	描述
vehicleId	string	是	车辆唯一标识符

查询参数

参数名	类型	必填	描述	默认值
fields	string	否	指定返回字段，逗号分隔	全部字段
format	string	否	响应格式 (json/xml)	json

2.3 请求示例

基本请求

GET /api/v1/vehicles/AV-001/status
Host: api.example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

指定字段请求

GET /api/v1/vehicles/AV-001/status?fields=vehicleInfo,operationalStatus,motionStatus
Host: api.example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

cURL 请求示例

# 获取完整状态信息
curl -X GET "https://api.example.com/api/v1/vehicles/AV-001/status" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

# 只获取核心状态信息
curl -X GET "https://api.example.com/api/v1/vehicles/AV-001/status?fields=vehicleInfo,operationalStatus,controlStatus,motionStatus" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

# 获取电池和诊断信息
curl -X GET "https://api.example.com/api/v1/vehicles/AV-001/status?fields=vehicleInfo,batteryStatus,diagnostics" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

2.4 响应数据结构

{
  "code": 200,
  "message": "success",
  "timestamp": 1736175610000,
  "data": {
    "vehicleInfo": {
      "vehicleId": "AV-001",
      "vehicleType": "GROUND_SUPPORT_EQUIPMENT",
      "manufacturer": "厂商名称",
      "model": "车型",
      "serialNumber": "序列号",
      "firmwareVersion": "1.2.3"
    },
    "operationalStatus": {
      "powerStatus": "ON",
      "systemHealth": "HEALTHY",
      "operationalMode": "AUTONOMOUS",
      "missionStatus": "IN_PROGRESS",
      "emergencyStatus": "NORMAL",
      "lastHeartbeat": 1736175610000
    },
    "controlStatus": {
      "controlMode": "AUTONOMOUS",
      "controlAuthority": "SYSTEM",
      "remoteControlActive": false,
      "manualOverrideActive": false,
      "safetyDriverPresent": false
    },
    "motionStatus": {
      "position": {
        "latitude": 36.354068,
        "longitude": 120.083410,
        "altitude": 45.2,
        "coordinateSystem": "WGS84"
      },
      "velocity": {
        "speed": 3.2,
        "direction": 1.57,
        "verticalSpeed": 0.0,
        "speedUnit": "m/s",
        "directionUnit": "radians"
      },
      "acceleration": {
        "longitudinal": 0.5,
        "lateral": 0.1,
        "vertical": 0.0,
        "unit": "m/s²"
      }
    },
    "vehicleState": {
      "motorStatus": [
        { "motorId": "M1", "status": "ACTIVE", "rpm": 3200, "torqueNm": 120, "powerKw": 25.5, "temperatureC": 65.0 }
      ]
    },
    "batteryStatus": {
      "mainBattery": {
        "chargeLevel": 85.5,
        "voltage": 48.2,
        "current": -15.3,
        "temperature": 35.2,
        "health": "GOOD",
        "cycleCount": 1250,
        "capacity": {
          "current": 95.2,
          "design": 100.0,
          "unit": "kWh"
        },
        "chargingStatus": "DISCHARGING",
        "estimatedRange": 120.5,
        "timeToEmpty": 480,
        "timeToFull": null,
        "cellVoltages": [3.85, 3.87, 3.86, 3.88],
        "balancingActive": false
      },
      "auxiliaryBattery": {
        "chargeLevel": 92.0,
        "voltage": 12.6,
        "current": -2.1,
        "temperature": 28.5,
        "health": "GOOD",
        "chargingStatus": "DISCHARGING"
      },
      "backupBattery": {
        "chargeLevel": 100.0,
        "voltage": 24.0,
        "health": "GOOD",
        "lastMaintenance": 1735571200000
      }
    },
    "safetyStatus": {
      "collisionAvoidanceActive": true,
      "emergencyBrakingReady": true,
      "pathPlanningStatus": "ACTIVE",
      "obstacleDetectionStatus": "ACTIVE",
      "minimumRiskManeuverTriggered": false
    },
    "autonomyLevel": {
      "currentLevel": 4,
      "availableLevels": [2, 3, 4],
      "fallbackLevel": 2
    },
    "sensorStatus": {
      "cameras": [
        {
          "sensorId": "CAM_FRONT",
          "status": "ACTIVE",
          "health": "GOOD",
          "lastUpdate": 1736175610000,
          "coverage": "OK",
          "latencyMs": 35,
          "accuracy": 0.02
        }
      ],
      "lidars": [
        {
          "sensorId": "LIDAR_360",
          "status": "ACTIVE",
          "health": "GOOD",
          "lastUpdate": 1736175610000,
          "coverage": "OK",
          "latencyMs": 28,
          "accuracy": 0.01
        }
      ],
      "radars": [
        {
          "sensorId": "RADAR_FRONT",
          "status": "ACTIVE",
          "health": "GOOD",
          "lastUpdate": 1736175610000,
          "coverage": "OK",
          "latencyMs": 22,
          "accuracy": 0.1
        }
      ],
      "gps": {
        "status": "ACTIVE",
        "accuracy": 0.5,
        "satelliteCount": 12,
        "lastUpdate": 1736175610000
      },
      "imu": {
        "status": "ACTIVE",
        "health": "GOOD",
        "lastUpdate": 1736175610000
      }
    },
    "communicationStatus": {
      "v2xStatus": "CONNECTED",
      "cellularSignalStrength": -65,
      "wifiStatus": "CONNECTED",
      "cloudConnectivity": "ONLINE"
    },
    "diagnostics": {
      "faultCodes": [
        {
          "code": "P0001",
          "severity": "CRITICAL",
          "description": "燃油系统压力过低",
          "component": "燃油泵",
          "timestamp": 1736175610000,
          "status": "ACTIVE"
        }
      ],
      "warnings": [
        {
          "severity": "WARNING",
          "description": "电池温度偏高",
          "component": "主电池组",
          "timestamp": 1736175610000
        }
      ],
      "maintenanceAlerts": [
        {
          "type": "SCHEDULED_MAINTENANCE",
          "description": "定期保养到期",
          "dueDate": 1736262000000,
          "priority": "HIGH"
        }
      ]
    },
    "environmentalContext": {
      "weatherCondition": "CLEAR",
      "roadCondition": "DRY",
      "trafficDensity": "LOW",
      "lightingCondition": "DAYLIGHT"
    },
    "missionContext": {
      "currentMission": {
        "missionId": "MISSION_001",
        "missionType": "CARGO_TRANSPORT",
        "startTime": 1736175000000,
        "estimatedEndTime": 1736178600000,
        "progress": 65.5,
        "totalMileage": 1250.8
      },
      "waypoints": [
        {
          "waypointId": "WP_001",
          "latitude": 36.354068,
          "longitude": 120.083410,
          "status": "COMPLETED"
        }
      ]
    },
    "vehicleSignals": {
      "headLamp": "ON",
      "brakeLamp": "ON",
      "turnSignal": "LEFT",
      "positionLamp": "ON",
      "horn": "OFF"
    },
    "eventReports": [
      {
        "eventId": "EVT-20250918-000123",
        "eventCode": "GEOFENCE_BREACH",
        "severity": "CRITICAL",
        "timestamp": 1736175600456,
        "location": { "latitude": 36.354072, "longitude": 120.083405 },
        "evidenceRef": ["vid://360/1736175600..1736175690","log://blackbox/seg-88421"],
        "details": "Entered restricted area"
      }
    ],
    "monitoring": {
      "dataRecordingPolicy": { "localRetentionDays": 3, "backendRetentionDays": 90 },
      "storagePolicy": { "overwriteStrategy": "FIFO", "capacityGb": 128, "estimatedDaysLocal": 4 },
      "recoveryStatus": { "lastPowerLossTime": 1736175500000, "dataRecovered": true, "recoveredSegments": ["BB-20250918-0001"] },
      "videoReferences": {
        "external360": ["vid://360/1736175600..1736175690"],
        "cabin": ["vid://cabin/1736175600..1736175690"],
        "audio": ["aud://cabin/1736175600..1736175690"]
      },
      "perceptionResponse": { "state": "OK", "responseActions": ["SLOWDOWN"] },
      "remoteCommands": [
        { "commandId": "CMD-88421", "commandType": "STOP", "issuedBy": "controller-001", "issuedAt": 1736175600123, "ackStatus": "ACKED", "executedAt": 1736175600456 }
      ],
      "blackboxWindow": { "preEventSeconds": 90, "postEventSeconds": 30, "segmentId": "BB-20250918-0001" }
    },
    "airportCompliance": {
      "oddProfile": {
        "environment": ["DAY","NIGHT","FOG"],
        "areaTypes": ["APRON","TAXIWAY","SERVICE_ROAD"],
        "speedRange": [0, 15],
        "weatherLimits": { "visibilityMin": 200, "windMax": 15 },
        "runwayProximityLimit": 50
      },
      "activationStatus": { "eligible": true, "unmetConditions": [], "promptIssued": { "audible": false, "visual": false }, "evaluatedAt": 1736175610000 },
      "perceptionBlindSpots": [{ "areaId": "FRONT_LOW", "azimuthRange": "350-10", "elevationRange": "-5~0", "lastVerifiedAt": 1736175600000 }],
      "startSafetyCheck": { "passed": true, "obstaclesDetected": 0, "minObstacleDistance": null, "checkTime": 1736175599000 },
      "geoFence": { "operationAreaId": "QD-APR-001", "geoFenceStatus": "INSIDE" }
    },
    "complianceStatus": {
      "regulatoryCompliance": "COMPLIANT",
      "certificationStatus": "VALID",
      "auditTrail": "ENABLED"
    }
  }
}

3. 数据字段详细说明

3.1 车辆基础信息 (vehicleInfo) - 必填

vehicleId: 车辆唯一标识符 [必填]
vehicleType: 车辆类型 (PASSENGER_CAR, TRUCK, BUS, GROUND_SUPPORT_EQUIPMENT等) [可选]
manufacturer: 制造商 [可选]
model: 车型 [可选]
serialNumber: 序列号 [可选]
firmwareVersion: 固件版本 [可选]

3.2 运行状态 (operationalStatus) - 必填

powerStatus: 电源状态 (ON, OFF, STANDBY) [必填]
systemHealth: 系统健康状态 (HEALTHY, DEGRADED, CRITICAL, FAULT) [必填]
operationalMode: 运行模式 (MANUAL, ASSISTED, AUTONOMOUS, REMOTE) [必填]
missionStatus: 任务状态 (IDLE, IN_PROGRESS, COMPLETED, PAUSED, ABORTED) [可选]
emergencyStatus: 紧急状态 (NORMAL, WARNING, EMERGENCY, CRITICAL) [必填]
lastHeartbeat: 最后心跳时间戳 [必填]

3.3 控制状态 (controlStatus) - 必填

controlMode: 控制模式 (MANUAL, AUTONOMOUS, REMOTE, HYBRID) [必填]
controlAuthority: 控制权限 (DRIVER, SYSTEM, REMOTE_OPERATOR) [必填]
remoteControlActive: 远程控制是否激活 [必填]
manualOverrideActive: 手动接管是否激活 [可选]
safetyDriverPresent: 安全员是否在场 [可选]

3.4 运动状态 (motionStatus) - 必填

位置信息 (position) [必填]

latitude: 纬度 [必填]
longitude: 经度 [必填]
altitude: 海拔高度 [可选]
coordinateSystem: 坐标系统 [可选，默认WGS84]
新增字段（机场区域化与一致性）：
- positionAccuracy: 位置精度 (米) [可选]
- localizationStatus: 定位状态 (RTK_FIX, RTK_FLOAT, GNSS_ONLY, DR, FAULT) [可选]
- mapMatchingStatus: 地图匹配状态 (OK, OFF_ROUTE, NO_MAP, FAULT) [可选]
- 说明：支撑 6.5.3 在线监控a~d项及机场运行合规核查

速度信息 (velocity) [必填]

speed: 速度值 [必填]
direction: 方向角 [必填]
verticalSpeed: 垂直速度 [可选]
speedUnit: 速度单位 [可选，默认m/s]
directionUnit: 方向单位 [可选，默认radians]

加速度信息 (acceleration) [可选]

longitudinal: 纵向加速度 [可选]
lateral: 横向加速度 [可选]
vertical: 垂直加速度 [可选]
unit: 加速度单位 [可选，默认m/s²]

3.5 车辆状态 (vehicleState) - 可选

motorStatus: 电动机状态数组 [可选]
- motorId: 电机ID（如 M1 前轴、M2 后轴）[可选]
- status: 状态 (ACTIVE, INACTIVE, FAULT, OVERHEAT, THERMAL_LIMITED) [可选]
- rpm: 转速 (rpm) [可选]
- torqueNm: 实时输出扭矩 (N·m) [可选]
- powerKw: 实时功率 (kW) [可选]
- temperatureC: 电机温度 (°C) [可选]

3.6 电池状态 (batteryStatus) - 可选

主电池 (mainBattery) [可选]

chargeLevel: 电量百分比 (0-100) [可选]
voltage: 电压值 (V) [可选]
current: 电流值 (A，正值充电，负值放电) [可选]
temperature: 电池温度 (°C) [可选]
health: 电池健康状态 (GOOD, FAIR, POOR, CRITICAL) [可选]
cycleCount: 充放电循环次数 [可选]
capacity: 电池容量信息 [可选]
- current: 当前容量 [可选]
- design: 设计容量 [可选]
- unit: 容量单位 (kWh, Ah) [可选]
chargingStatus: 充电状态 (CHARGING, DISCHARGING, IDLE, FAULT) [可选]
estimatedRange: 预估续航里程 (km) [可选]
timeToEmpty: 预估放电时间 (分钟) [可选]
timeToFull: 预估充满时间 (分钟) [可选]
cellVoltages: 单体电池电压数组 [可选]
balancingActive: 电池均衡是否激活 [可选]

辅助电池 (auxiliaryBattery) [可选]

chargeLevel: 电量百分比 [可选]
voltage: 电压值 [可选]
current: 电流值 [可选]
temperature: 温度 [可选]
health: 健康状态 [可选]
chargingStatus: 充电状态 [可选]

3.7 安全状态 (safetyStatus) - 可选

collisionAvoidanceActive: 碰撞避免系统是否激活 [可选]
emergencyBrakingReady: 紧急制动系统是否就绪 [可选]
pathPlanningStatus: 路径规划状态 (ACTIVE, INACTIVE, FAULT) [可选]
obstacleDetectionStatus: 障碍物检测状态 (ACTIVE, INACTIVE, FAULT) [可选]
minimumRiskManeuverTriggered: 最小风险策略是否触发 [可选]
新增字段（合规扩展，建议用统一枚举表示状态）：
- collisionAvoidanceStatus: (INACTIVE, READY, ACTIVE, EMERGENCY, DEGRADED, FAULT) [可选]
- emergencyBrakingStatus: (INACTIVE, READY, ACTIVE, RECOVERING, FAULT) [可选]
- lastEmergencyBrakeTime: 最近一次紧急制动时间戳 [可选]
- evasiveActionType: 规避动作 (DECELERATE, STOP, BYPASS, HORN, LIGHT) [可选]
- obstacleDistanceMin: 最近障碍物最小距离 (m) [可选]
- obstacleBearingDeg: 最近障碍物方位角 (度) [可选]
- perceptionConfidence: 感知综合置信度 (0~1) [可选]
- 说明：用于在线监控与事件回溯（参见 6.5.2、6.5.3）

3.8 自动驾驶等级 (autonomyLevel) - 可选

currentLevel: 当前自动驾驶等级 (0-5, 基于SAE J3016标准) [可选]
availableLevels: 可用的自动驾驶等级数组 [可选]
fallbackLevel: 降级后的自动驾驶等级 [可选]

3.9 传感器状态 (sensorStatus) - 可选

摄像头 (cameras) [可选]

sensorId: 传感器ID [可选]
status: 状态 (ACTIVE, INACTIVE, FAULT) [可选]
health: 健康状态 (GOOD, FAIR, POOR) [可选]
lastUpdate: 最后更新时间戳 [可选]
新增通用字段（适用于各类传感器）：
- coverage: 覆盖状态 (OK, OCCLUDED, WEATHER_IMPACTED) [可选]
- latencyMs: 采集至上报延迟 (ms) [可选]
- accuracy: 关键测量精度（单位视传感器类型）[可选]
说明：覆盖 6.5.3e “环境感知与响应状态”与取证质量评估

激光雷达 (lidars) [可选]

sensorId: 传感器ID [可选]
status: 状态 [可选]
health: 健康状态 [可选]
lastUpdate: 最后更新时间戳 [可选]

毫米波雷达 (radars) [可选]

sensorId: 传感器ID [可选]
status: 状态 [可选]
health: 健康状态 [可选]
lastUpdate: 最后更新时间戳 [可选]

GPS (gps) [可选]

status: GPS状态 [可选]
accuracy: 精度 (米) [可选]
satelliteCount: 卫星数量 [可选]
lastUpdate: 最后更新时间戳 [可选]

惯性测量单元 (imu) [可选]

status: IMU状态 [可选]
health: 健康状态 [可选]
lastUpdate: 最后更新时间戳 [可选]

3.10 通信状态 (communicationStatus) - 可选

v2xStatus: V2X通信状态 (CONNECTED, DISCONNECTED, FAULT) [可选]
cellularSignalStrength: 蜂窝信号强度 (dBm) [可选]
wifiStatus: WiFi状态 (CONNECTED, DISCONNECTED, FAULT) [可选]
cloudConnectivity: 云端连接状态 (ONLINE, OFFLINE, FAULT) [可选]
新增字段：
- networkLatencyMs: 网络往返时延 (ms) [可选]
- packetLossRate: 丢包率 (0~1) [可选]
- failoverCount: 网络故障切换次数 [可选]
- rsuConnectedId: 已连接路侧单元ID（如有）[可选]
- remoteCommandAck: { lastCommandId: string, ackStatus: (PENDING, ACKED, FAILED), latencyMs: number } [可选]（最近一次指令确认摘要）
说明：满足 6.5.2e、6.5.3i 的远程指令闭环记录

3.11 诊断信息 (diagnostics) - 可选

故障代码 (faultCodes) [可选]

code: 故障代码 (如P0001, B0002等) [可选]
severity: 严重程度 (INFO, WARNING, CRITICAL, FATAL) [可选]
description: 故障描述 [可选]
component: 故障组件 [可选]
timestamp: 故障发生时间戳 [可选]
status: 故障状态 (ACTIVE, RESOLVED) [可选]

警告信息 (warnings) [可选]

severity: 严重程度 (LOW, MEDIUM, HIGH) [可选]
description: 警告描述 [可选]
component: 相关组件 [可选]
timestamp: 警告时间戳 [可选]

维护提醒 (maintenanceAlerts) [可选]

type: 维护类型 (SCHEDULED_MAINTENANCE, COMPONENT_REPLACEMENT, INSPECTION等) [可选]
description: 维护描述 [可选]
dueDate: 到期日期时间戳 [可选]
priority: 优先级 (LOW, MEDIUM, HIGH, URGENT) [可选]

3.12 环境上下文 (environmentalContext) - 可选

weatherCondition: 天气状况 (CLEAR, RAIN, SNOW, FOG等) [可选]
roadCondition: 路面状况 (DRY, WET, ICY, SNOW等) [可选]
trafficDensity: 交通密度 (LOW, MEDIUM, HIGH) [可选]
lightingCondition: 光照条件 (DAYLIGHT, DUSK, NIGHT, TUNNEL等) [可选]

3.13 任务上下文 (missionContext) - 可选

当前任务 (currentMission) [可选]

missionId: 任务ID [可选]
missionType: 任务类型 [可选]
startTime: 开始时间戳 [可选]
estimatedEndTime: 预计结束时间戳 [可选]
progress: 任务进度百分比 [可选]
totalMileage: 累计行驶里程 (米) [可选]

路径点 (waypoints) [可选]

waypointId: 路径点ID [可选]
latitude: 纬度 [可选]
longitude: 经度 [可选]
status: 状态 (PENDING, COMPLETED, SKIPPED) [可选]

3.14 合规状态 (complianceStatus) - 可选

regulatoryCompliance: 法规合规状态 (COMPLIANT, NON_COMPLIANT, UNKNOWN) [可选]
certificationStatus: 认证状态 (VALID, EXPIRED, PENDING) [可选]
auditTrail: 审计跟踪状态 (ENABLED, DISABLED) [可选]
新增字段：
- schemaVersion: 数据结构版本 [可选]
- dataQuality: 数据质量标签 (COMPLETE, PARTIAL, ESTIMATED, STALE) [可选]
说明：用于数据结构版本兼容与数据质量提示，不包含管理性合规声明

4. 错误处理

4.1 HTTP状态码

200: 成功
400: 请求参数错误
401: 未授权
403: 禁止访问
404: 车辆不存在
429: 请求频率过高
500: 服务器内部错误
503: 服务不可用

4.2 错误响应格式

{
  "code": 400,
  "message": "Invalid vehicle ID format",
  "timestamp": 1736175610000,
  "error": {
    "type": "VALIDATION_ERROR",
    "details": "Vehicle ID must be alphanumeric and 3-20 characters long",
    "field": "vehicleId"
  }
}

5. 安全考虑

5.1 认证授权

使用JWT Token进行身份认证
基于角色的访问控制(RBAC)
API密钥管理

5.2 数据保护

HTTPS加密传输
敏感数据脱敏
数据访问日志记录

5.3 隐私保护

位置数据匿名化选项
数据保留策略
用户同意管理

6. 性能优化

6.1 缓存策略

Redis缓存热点数据
CDN加速静态资源
数据库查询优化

6.2 限流控制

基于IP的限流
基于用户的限流
基于API的限流

7. 监控和日志

7.1 API监控

响应时间监控
错误率监控
吞吐量监控

7.2 日志记录

访问日志
错误日志
审计日志

8. 版本管理

8.1 版本策略

语义化版本控制
向后兼容性保证
废弃通知机制

8.2 版本迁移

渐进式迁移
并行版本支持
迁移工具提供

9. 扩展性设计

9.1 插件机制

自定义字段支持
厂商特定扩展
行业特定适配

9.2 集成能力

Webhook支持
消息队列集成
第三方系统对接

10. 测试策略

10.1 单元测试

API接口测试
数据验证测试
错误处理测试

10.2 集成测试

端到端测试
性能测试
安全测试

11. 字段可选性说明

11.1 必填字段组

以下字段组是API响应的核心，必须包含：

vehicleInfo.vehicleId: 车辆唯一标识
operationalStatus: 基本运行状态
controlStatus: 控制状态
motionStatus.position: 位置信息
motionStatus.velocity: 速度信息

11.2 可选字段组

其他所有字段组都是可选的，厂商可根据实际情况选择性实现：

batteryStatus: 电池相关信息（电动车必需，燃油车可选）
sensorStatus: 传感器状态（根据车辆配置）
safetyStatus: 安全系统状态
autonomyLevel: 自动驾驶等级信息
communicationStatus: 通信状态
diagnostics: 诊断信息
environmentalContext: 环境信息
missionContext: 任务信息
complianceStatus: 合规信息
vehicleSignals: 灯光/喇叭信号状态
eventReports: 事件上报与证据引用
monitoring: 在线监控与数据记录策略
airportCompliance: 机场场景合规扩展（ODD/激活/盲区/起步安全/许可区域）

11.3 实现建议

渐进式实现: 厂商可先实现必填字段，再逐步添加可选字段
配置驱动: 通过配置文件控制哪些字段组需要返回
字段过滤: 支持通过fields参数指定返回的字段组
版本兼容: 新增字段不影响现有客户端的兼容性

12. 电池状态详细说明

12.1 电池类型分类

主电池 (mainBattery): 车辆主要动力电池
辅助电池 (auxiliaryBattery): 12V/24V辅助系统电池
备用电池 (backupBattery): 紧急情况下的备用电源

12.2 电池健康状态定义

GOOD: 电池健康，容量>80%设计容量
FAIR: 电池轻微老化，容量60-80%设计容量
POOR: 电池明显老化，容量40-60%设计容量
CRITICAL: 电池严重老化，容量<40%设计容量

12.3 充电状态定义

CHARGING: 正在充电
DISCHARGING: 正在放电
IDLE: 空闲状态（既不充电也不放电）
FAULT: 充电系统故障

12.4 电池监控重点参数

温度监控: 防止过热和过冷
电压监控: 防止过充和过放
电流监控: 监控充放电电流
容量衰减: 跟踪电池老化程度
循环次数: 评估电池寿命

13. 故障诊断说明

13.1 故障严重程度定义

INFO: 信息性消息，不影响正常运行
WARNING: 警告级别，需要关注但可继续运行
CRITICAL: 严重故障，影响部分功能
FATAL: 致命故障，必须立即停车处理

13.2 故障状态定义

ACTIVE: 故障当前存在
RESOLVED: 故障已解决

13.3 维护类型定义

SCHEDULED_MAINTENANCE: 定期保养
COMPONENT_REPLACEMENT: 组件更换
INSPECTION: 检查维护

13.4 优先级定义

LOW: 低优先级，可延后处理
MEDIUM: 中等优先级，建议及时处理
HIGH: 高优先级，需要尽快处理
URGENT: 紧急，必须立即处理

这个优化后的设计方案具有以下特点：

灵活性: 大部分字段设为可选，厂商可根据实际情况实现
实用性: 突出了核心必需字段，确保基本功能
详细的电池信息: 提供了完整的电池状态监控能力
简化的故障信息: 保持核心故障诊断功能，结构简洁
渐进式实现: 支持分阶段实现，降低开发成本
向后兼容: 新增字段不影响现有系统

25 KiB Raw Blame History Unescape Escape

通用无人车运行状态API设计方案

1. 设计原则

1.1 行业标准参考

1.2 API设计原则

2. API接口设计

2.1 基础信息

2.2 请求参数

路径参数

查询参数

2.3 请求示例

基本请求

指定字段请求

cURL 请求示例

2.4 响应数据结构

3. 数据字段详细说明

3.1 车辆基础信息 (vehicleInfo) - 必填

3.2 运行状态 (operationalStatus) - 必填

3.3 控制状态 (controlStatus) - 必填

3.4 运动状态 (motionStatus) - 必填

位置信息 (position) [必填]

速度信息 (velocity) [必填]

加速度信息 (acceleration) [可选]

3.5 车辆状态 (vehicleState) - 可选

3.6 电池状态 (batteryStatus) - 可选

主电池 (mainBattery) [可选]

辅助电池 (auxiliaryBattery) [可选]

3.7 安全状态 (safetyStatus) - 可选

3.8 自动驾驶等级 (autonomyLevel) - 可选

3.9 传感器状态 (sensorStatus) - 可选

摄像头 (cameras) [可选]

激光雷达 (lidars) [可选]

毫米波雷达 (radars) [可选]

GPS (gps) [可选]

惯性测量单元 (imu) [可选]

3.10 通信状态 (communicationStatus) - 可选

3.11 诊断信息 (diagnostics) - 可选

故障代码 (faultCodes) [可选]

警告信息 (warnings) [可选]

维护提醒 (maintenanceAlerts) [可选]

3.12 环境上下文 (environmentalContext) - 可选

3.13 任务上下文 (missionContext) - 可选

当前任务 (currentMission) [可选]

路径点 (waypoints) [可选]

3.14 合规状态 (complianceStatus) - 可选

4. 错误处理

4.1 HTTP状态码

4.2 错误响应格式

5. 安全考虑

5.1 认证授权

5.2 数据保护

5.3 隐私保护

6. 性能优化

6.1 缓存策略

6.2 限流控制

7. 监控和日志

7.1 API监控

7.2 日志记录

8. 版本管理

8.1 版本策略

8.2 版本迁移

9. 扩展性设计

9.1 插件机制

9.2 集成能力

10. 测试策略

10.1 单元测试

10.2 集成测试

11. 字段可选性说明

11.1 必填字段组

11.2 可选字段组

11.3 实现建议

12. 电池状态详细说明

12.1 电池类型分类

12.2 电池健康状态定义

12.3 充电状态定义

12.4 电池监控重点参数

13. 故障诊断说明

13.1 故障严重程度定义

13.2 故障状态定义

13.3 维护类型定义

25 KiB

Raw Blame History