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

## 1. 设计原则

### 1.1 行业标准参考
- **ISO 26262**: 汽车功能安全标准
- **SAE J3016**: 自动驾驶分级标准
- **ISO 21448**: 预期功能安全标准(SOTIF)
- **IEEE 2857**: 自动驾驶系统隐私工程标准

### 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": {
      "engineStatus": "RUNNING",
      "transmissionState": "DRIVE",
      "brakingSystem": "NORMAL",
      "steeringSystem": "NORMAL",
      "fuelLevel": 75.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
        }
      ],
      "lidars": [
        {
          "sensorId": "LIDAR_360",
          "status": "ACTIVE",
          "health": "GOOD",
          "lastUpdate": 1736175610000
        }
      ],
      "radars": [
        {
          "sensorId": "RADAR_FRONT",
          "status": "ACTIVE",
          "health": "GOOD",
          "lastUpdate": 1736175610000
        }
      ],
      "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
      },
      "waypoints": [
        {
          "waypointId": "WP_001",
          "latitude": 36.354068,
          "longitude": 120.083410,
          "status": "COMPLETED"
        }
      ]
    },
    "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]

#### 速度信息 (velocity) [必填]
- **speed**: 速度值 [必填]
- **direction**: 方向角 [必填]
- **verticalSpeed**: 垂直速度 [可选]
- **speedUnit**: 速度单位 [可选，默认m/s]
- **directionUnit**: 方向单位 [可选，默认radians]

#### 加速度信息 (acceleration) [可选]
- **longitudinal**: 纵向加速度 [可选]
- **lateral**: 横向加速度 [可选]
- **vertical**: 垂直加速度 [可选]
- **unit**: 加速度单位 [可选，默认m/s²]

### 3.5 车辆状态 (vehicleState) - 可选
- **engineStatus**: 发动机状态 (RUNNING, STOPPED, IDLE, FAULT) [可选]
- **transmissionState**: 变速箱状态 (PARK, DRIVE, REVERSE, NEUTRAL) [可选]
- **brakingSystem**: 制动系统状态 (NORMAL, WARNING, FAULT) [可选]
- **steeringSystem**: 转向系统状态 (NORMAL, WARNING, FAULT) [可选]
- **fuelLevel**: 燃油液位百分比 [可选]

### 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**: 充电状态 [可选]

#### 备用电池 (backupBattery) [可选]
- **chargeLevel**: 电量百分比 [可选]
- **voltage**: 电压值 [可选]
- **health**: 健康状态 [可选]
- **lastMaintenance**: 最后维护时间戳 [可选]

### 3.7 安全状态 (safetyStatus) - 可选
- **collisionAvoidanceActive**: 碰撞避免系统是否激活 [可选]
- **emergencyBrakingReady**: 紧急制动系统是否就绪 [可选]
- **pathPlanningStatus**: 路径规划状态 (ACTIVE, INACTIVE, FAULT) [可选]
- **obstacleDetectionStatus**: 障碍物检测状态 (ACTIVE, INACTIVE, FAULT) [可选]
- **minimumRiskManeuverTriggered**: 最小风险策略是否触发 [可选]

### 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**: 最后更新时间戳 [可选]

#### 激光雷达 (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) [可选]

### 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**: 任务进度百分比 [可选]

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

### 3.14 合规状态 (complianceStatus) - 可选
- **regulatoryCompliance**: 法规合规状态 (COMPLIANT, NON_COMPLIANT, UNKNOWN) [可选]
- **certificationStatus**: 认证状态 (VALID, EXPIRED, PENDING) [可选]
- **auditTrail**: 审计跟踪状态 (ENABLED, DISABLED) [可选]

## 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**: 合规信息

### 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. **向后兼容**: 新增字段不影响现有系统