740 lines
25 KiB
Markdown
740 lines
25 KiB
Markdown
# 通用无人车运行状态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 请求示例
|
||
|
||
#### 基本请求
|
||
```bash
|
||
GET /api/v1/vehicles/AV-001/status
|
||
Host: api.example.com
|
||
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 指定字段请求
|
||
```bash
|
||
GET /api/v1/vehicles/AV-001/status?fields=vehicleInfo,operationalStatus,motionStatus
|
||
Host: api.example.com
|
||
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### cURL 请求示例
|
||
```bash
|
||
# 获取完整状态信息
|
||
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 响应数据结构
|
||
|
||
```json
|
||
{
|
||
"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 错误响应格式
|
||
```json
|
||
{
|
||
"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 实现建议
|
||
1. **渐进式实现**: 厂商可先实现必填字段，再逐步添加可选字段
|
||
2. **配置驱动**: 通过配置文件控制哪些字段组需要返回
|
||
3. **字段过滤**: 支持通过fields参数指定返回的字段组
|
||
4. **版本兼容**: 新增字段不影响现有客户端的兼容性
|
||
|
||
## 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**: 紧急，必须立即处理
|
||
|
||
这个优化后的设计方案具有以下特点：
|
||
|
||
1. **灵活性**: 大部分字段设为可选，厂商可根据实际情况实现
|
||
2. **实用性**: 突出了核心必需字段，确保基本功能
|
||
3. **详细的电池信息**: 提供了完整的电池状态监控能力
|
||
4. **简化的故障信息**: 保持核心故障诊断功能，结构简洁
|
||
5. **渐进式实现**: 支持分阶段实现，降低开发成本
|
||
6. **向后兼容**: 新增字段不影响现有系统 |