Doni/QDAirPortBackend0122

Fork 0

sladro 725c0be448 Initial commit

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

13 KiB

Raw Blame History

通用无人车运行状态API（测试版）

本说明仅包含机场部署必须按时上报的最小字段集合，便于联调与验收。完整可选字段请参见《无人车通用运行状态API接口》。本文件已包含完整的请求方式与可运行示例，使用本文件即可进行开发与测试。

1. 接口信息

方法：GET /api/v1/vehicles/{vehicleId}/status
认证：Bearer Token (JWT)
响应：application/json; charset=utf-8
版本：v1（后续版本将以路径或Header方式区分）
超时建议：客户端超时 ≥ 5s；服务端处理 ≤ 1s（正常场景）

1.1 路径参数

参数名	类型	必填	描述
vehicleId	string	是	车辆唯一标识，字母数字 3~20 位，示例：AV-001

1.2 查询参数

参数名	类型	必填	描述	示例
fields	string	否	指定返回字段组，逗号分隔。不填返回全部字段	fields=vehicleInfo,operationalStatus,controlStatus,motionStatus
format	string	否	响应格式，默认 json（当前仅支持 json）	format=json

说明：

建议在联调时使用 fields 仅返回本精简版所需字段组，以降低带宽与解析成本。
返回字段组对应见“必须字段组与字段”。

1.3 请求头

Header	必填	示例	说明
Authorization	是	Bearer eyJhbGciOi...	JWT 鉴权令牌
Content-Type	是	application/json	固定为 JSON
Accept	否	application/json	建议显式声明
X-Request-Id	否	3b9c9e90-7c1f-4b6a-9b73-fb8dfb2d7f31	客户端生成的请求ID，便于排障

1.4 鉴权说明（JWT）

建议使用 RS256/ES256 非对称签名。
令牌应包含 iss（签发者）、exp（过期）、sub（主体/账户或系统ID）、aud（受众）等标准声明。
服务器应校验签名与过期时间；拒绝无效或过期令牌（返回 401）。

1.5 幂等性与频控

本接口为查询，天然幂等。
建议服务端设置频控：同一 vehicleId QPS ≤ 5；超过返回 429。
建议客户端重试策略：网络错误或 5xx，指数退避重试最多 3 次；遇到 4xx 不重试。

2. 必须字段组与字段

vehicleInfo

vehicleId: string

operationalStatus

powerStatus: ON | OFF | STANDBY
systemHealth: HEALTHY | DEGRADED | CRITICAL | FAULT
operationalMode: MANUAL | ASSISTED | AUTONOMOUS | REMOTE
emergencyStatus: NORMAL | WARNING | EMERGENCY | CRITICAL
lastHeartbeat: number (ms, UTC)

controlStatus

controlMode: MANUAL | AUTONOMOUS | REMOTE | HYBRID
controlAuthority: DRIVER | SYSTEM | REMOTE_OPERATOR
remoteControlActive: boolean

motionStatus.position

latitude: number
longitude: number

motionStatus.velocity

speed: number (m/s)
direction: number (radians)

safetyStatus

collisionAvoidanceActive: boolean
emergencyBrakingReady: boolean
pathPlanningStatus: ACTIVE | INACTIVE | FAULT
obstacleDetectionStatus: ACTIVE | INACTIVE | FAULT
minimumRiskManeuverTriggered: boolean

sensorStatus.gps

status: ACTIVE | INACTIVE | FAULT
accuracy: number (m)
lastUpdate: number (ms, UTC)

batteryStatus.mainBattery

chargeLevel: number (0-100)
voltage: number (V)
current: number (A；正值=充电，负值=放电)
temperature: number (°C)
chargingStatus: CHARGING | DISCHARGING | IDLE | FAULT

communicationStatus

v2xStatus: CONNECTED | DISCONNECTED | FAULT
cellularSignalStrength: number (dBm)
wifiStatus: CONNECTED | DISCONNECTED | FAULT
cloudConnectivity: ONLINE | OFFLINE | FAULT

missionContext.currentMission

missionId: string
missionType: string
startTime: number (ms, UTC)
estimatedEndTime: number (ms, UTC)
progress: number (0-100)
totalMileage: number (m)

missionContext.waypoints

waypointId: string
latitude: number
longitude: number
status: PENDING | COMPLETED | SKIPPED

3. 统一要求

时间戳：毫秒级 UTC
坐标系：WGS84（latitude/longitude）
单位约定：
- 速度 speed: m/s
- 方向 direction: radians
- 电压 voltage: V；电流 current: A；温度 temperature: °C
枚举一致性：状态枚举尽量统一使用 ACTIVE/INACTIVE/DEGRADED/FAULT；如已有定义，以主文档为准

4. 可直接运行的请求示例

4.1 cURL 示例（完整）

获取全部必需字段：

curl -X GET "https://api.example.com/api/v1/vehicles/AV-001/status" \
  -H "Authorization: Bearer REPLACE_WITH_JWT_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

仅获取核心字段组（推荐用于联调）：

curl -G "https://api.example.com/api/v1/vehicles/AV-001/status" \
  -H "Authorization: Bearer REPLACE_WITH_JWT_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-urlencode "fields=vehicleInfo,operationalStatus,controlStatus,motionStatus,safetyStatus,sensorStatus,batteryStatus,communicationStatus"

4.2 Postman/HTTP 示例

HTTPie：

http GET https://api.example.com/api/v1/vehicles/AV-001/status \
  Authorization:"Bearer REPLACE_WITH_JWT_TOKEN" \
  Accept:application/json

4.3 可复制的一键测试脚本（本地替换变量后直接运行）

#!/usr/bin/env bash
BASE_URL="https://api.example.com"
VEHICLE_ID="AV-001"
JWT="REPLACE_WITH_JWT_TOKEN"

curl -sS -X GET "${BASE_URL}/api/v1/vehicles/${VEHICLE_ID}/status" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -w "\nHTTP_STATUS:%{http_code}\n" \
  --connect-timeout 5 --max-time 10

5. 示例响应（仅包含必需字段）

{
  "code": 200,
  "message": "success",
  "timestamp": 1736175610000,
  "data": {
    "vehicleInfo": {
      "vehicleId": "AV-001"
    },
    "operationalStatus": {
      "powerStatus": "ON",
      "systemHealth": "HEALTHY",
      "operationalMode": "AUTONOMOUS",
      "emergencyStatus": "NORMAL",
      "lastHeartbeat": 1736175610000
    },
    "controlStatus": {
      "controlMode": "AUTONOMOUS",
      "controlAuthority": "SYSTEM",
      "remoteControlActive": false
    },
    "motionStatus": {
      "position": {
        "latitude": 36.354068,
        "longitude": 120.083410
      },
      "velocity": {
        "speed": 3.2,
        "direction": 1.57
      }
    },
    "safetyStatus": {
      "collisionAvoidanceActive": true,
      "emergencyBrakingReady": true,
      "pathPlanningStatus": "ACTIVE",
      "obstacleDetectionStatus": "ACTIVE",
      "minimumRiskManeuverTriggered": false
    },
    "sensorStatus": {
      "gps": {
        "status": "ACTIVE",
        "accuracy": 0.5,
        "lastUpdate": 1736175610000
      }
    },
    "batteryStatus": {
      "mainBattery": {
        "chargeLevel": 85.5,
        "voltage": 48.2,
        "current": -15.3,
        "temperature": 35.2,
        "chargingStatus": "DISCHARGING"
      }
    },
    "communicationStatus": {
      "v2xStatus": "CONNECTED",
      "cellularSignalStrength": -65,
      "wifiStatus": "CONNECTED",
      "cloudConnectivity": "ONLINE"
    },
    "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"
        },
        {
          "waypointId": "WP_002",
          "latitude": 36.355123,
          "longitude": 120.084567,
          "status": "PENDING"
        }
      ]
    }
  }
}

6. 错误码与错误响应示例

6.1 常见错误码

200 成功
400 请求参数错误（如 vehicleId 不符合规范）
401 未授权（JWT 无效或过期）
403 禁止访问（无权限）
404 车辆不存在
429 请求过多（频控触发）
500 服务器内部错误
503 服务不可用（临时维护或下游故障）

6.2 错误响应示例

{
  "code": 401,
  "message": "Unauthorized",
  "timestamp": 1736175610000,
  "error": {
    "type": "AUTH_ERROR",
    "details": "Invalid or expired token",
    "field": null
  }
}

7. 数据字段详细说明（必须字段）

vehicleInfo.vehicleId
- 类型：string；必填：是；示例：AV-001
- 说明：车辆唯一标识，建议字母数字 3~20 位
operationalStatus.powerStatus
- 类型：enum(ON|OFF|STANDBY)；必填：是
- 说明：供电与上电状态
operationalStatus.systemHealth
- 类型：enum(HEALTHY|DEGRADED|CRITICAL|FAULT)；必填：是
- 说明：系统健康概览；DEGRADED/CRITICAL 用于运营判定
operationalStatus.operationalMode
- 类型：enum(MANUAL|ASSISTED|AUTONOMOUS|REMOTE)；必填：是
- 说明：当前控制模式
operationalStatus.emergencyStatus
- 类型：enum(NORMAL|WARNING|EMERGENCY|CRITICAL)；必填：是
- 说明：紧急状态等级
operationalStatus.lastHeartbeat
- 类型：number(ms,UTC)；必填：是
- 说明：设备心跳时间，用于在线监控存活判定
controlStatus.controlMode
- 类型：enum(MANUAL|AUTONOMOUS|REMOTE|HYBRID)；必填：是
controlStatus.controlAuthority
- 类型：enum(DRIVER|SYSTEM|REMOTE_OPERATOR)；必填：是
controlStatus.remoteControlActive
- 类型：boolean；必填：是
- 说明：是否处于远程控制激活态
motionStatus.position.latitude / longitude
- 类型：number；必填：是；单位：WGS84 度
- 说明：位置信息最小集合
motionStatus.velocity.speed
- 类型：number；必填：是；单位：m/s
motionStatus.velocity.direction
- 类型：number；必填：是；单位：radians
safetyStatus.collisionAvoidanceActive
- 类型：boolean；必填：是
safetyStatus.emergencyBrakingReady
- 类型：boolean；必填：是
safetyStatus.pathPlanningStatus
- 类型：enum(ACTIVE|INACTIVE|FAULT)；必填：是
safetyStatus.obstacleDetectionStatus
- 类型：enum(ACTIVE|INACTIVE|FAULT)；必填：是
safetyStatus.minimumRiskManeuverTriggered
- 类型：boolean；必填：是
- 说明：MRM 是否被触发（仅标识，不含细节）
sensorStatus.gps.status
- 类型：enum(ACTIVE|INACTIVE|FAULT)；必填：是
sensorStatus.gps.accuracy
- 类型：number；必填：是；单位：m
sensorStatus.gps.lastUpdate
- 类型：number(ms,UTC)；必填：是
batteryStatus.mainBattery.chargeLevel
- 类型：number；必填：是；范围：0~100（%）
batteryStatus.mainBattery.voltage
- 类型：number；必填：是；单位：V
batteryStatus.mainBattery.current
- 类型：number；必填：是；单位：A（正=充电，负=放电）
batteryStatus.mainBattery.temperature
- 类型：number；必填：是；单位：°C
batteryStatus.mainBattery.chargingStatus
- 类型：enum(CHARGING|DISCHARGING|IDLE|FAULT)；必填：是
communicationStatus.v2xStatus
- 类型：enum(CONNECTED|DISCONNECTED|FAULT)；必填：是
communicationStatus.cellularSignalStrength
- 类型：number；必填：是；单位：dBm
communicationStatus.wifiStatus
- 类型：enum(CONNECTED|DISCONNECTED|FAULT)；必填：是
communicationStatus.cloudConnectivity
- 类型：enum(ONLINE|OFFLINE|FAULT)；必填：是
missionContext.currentMission.missionId
- 类型：string；必填：是
- 说明：当前任务的唯一标识符
missionContext.currentMission.missionType
- 类型：string；必填：是
- 说明：任务类型，如 CARGO_TRANSPORT、PATROL_TRANSPORT 等
missionContext.currentMission.startTime
- 类型：number(ms,UTC)；必填：是
- 说明：任务开始时间
missionContext.currentMission.estimatedEndTime
- 类型：number(ms,UTC)；必填：是
- 说明：预计任务结束时间
missionContext.currentMission.progress
- 类型：number；必填：是；范围：0~100（%）
- 说明：当前任务执行进度百分比
missionContext.currentMission.totalMileage
- 类型：number；必填：是；单位：m
- 说明：累计行驶里程（米）
missionContext.waypoints.waypointId
- 类型：string；必填：是
- 说明：路径点唯一标识符
missionContext.waypoints.latitude
- 类型：number；必填：是；单位：WGS84 度
- 说明：路径点纬度
missionContext.waypoints.longitude
- 类型：number；必填：是；单位：WGS84 度
- 说明：路径点经度
missionContext.waypoints.status
- 类型：enum(PENDING|COMPLETED|SKIPPED)；必填：是
- 说明：路径点状态，PENDING=待到达，COMPLETED=已完成，SKIPPED=已跳过

8. 兼容性与扩展

厂商可返回更多可选字段，但不得改变上述必需字段的语义与单位。
推荐支持 ?fields= 过滤机制，以便联调时仅回传必需集合。

13 KiB Raw Blame History Unescape Escape

通用无人车运行状态API（测试版）

1. 接口信息

1.1 路径参数

1.2 查询参数

1.3 请求头

1.4 鉴权说明（JWT）

1.5 幂等性与频控

2. 必须字段组与字段

3. 统一要求

4. 可直接运行的请求示例

4.1 cURL 示例（完整）

4.2 Postman/HTTP 示例

4.3 可复制的一键测试脚本（本地替换变量后直接运行）

5. 示例响应（仅包含必需字段）

6. 错误码与错误响应示例

6.1 常见错误码

6.2 错误响应示例

7. 数据字段详细说明（必须字段）

8. 兼容性与扩展

13 KiB

Raw Blame History