150 lines
5.4 KiB
Markdown
150 lines
5.4 KiB
Markdown
# Vehicle Data Platform API Contract
|
|
|
|
## Response Envelope
|
|
|
|
All platform APIs return the same envelope:
|
|
|
|
```json
|
|
{
|
|
"data": {},
|
|
"traceId": "trace-20260704000000.000000",
|
|
"timestamp": 1783094400000
|
|
}
|
|
```
|
|
|
|
Pagination uses:
|
|
|
|
```json
|
|
{
|
|
"items": [],
|
|
"total": 0,
|
|
"limit": 20,
|
|
"offset": 0
|
|
}
|
|
```
|
|
|
|
## Vehicle Keyword
|
|
|
|
The platform is vehicle-first. Query APIs should accept `keyword` as the user-facing vehicle selector.
|
|
|
|
`keyword` may be:
|
|
|
|
- VIN
|
|
- plate
|
|
- JT808 phone
|
|
|
|
The BFF resolves `keyword` through vehicle identity data before querying realtime, history, RAW, or mileage data. `vin` remains accepted as a compatibility alias on data query APIs, but new UI and integrations should send `keyword`.
|
|
|
|
If a keyword cannot be resolved to a VIN, data APIs must not fabricate a VIN. They should return empty result pages for vehicle data, while `/api/vehicle-service` exposes `lookupResolved=false` and quality issues for follow-up binding work.
|
|
|
|
## Core Query APIs
|
|
|
|
### Dashboard Summary
|
|
|
|
```http
|
|
GET /api/dashboard/summary
|
|
```
|
|
|
|
Returns vehicle service KPIs, source distribution, vehicle service status distribution, link health, and realtime backlog.
|
|
|
|
### Vehicle Service
|
|
|
|
```http
|
|
GET /api/vehicle-service?keyword=粤AG18312
|
|
```
|
|
|
|
Returns one vehicle service view with identity, realtime summary, source coverage, history preview, RAW preview, mileage preview, and quality issues.
|
|
|
|
`/api/vehicles/detail` remains available as a compatibility alias. New UI and integrations should use `/api/vehicle-service` to make the vehicle-first boundary explicit.
|
|
|
|
`sourceConsistency` is the vehicle-level diagnosis across GB32960, JT808, and Yutong MQTT sources. The three protocols are source evidence for one vehicle service, so callers should display the diagnosis result instead of asking users to compare protocol rows manually.
|
|
|
|
```json
|
|
{
|
|
"sourceConsistency": {
|
|
"scope": "detail",
|
|
"sourceCount": 3,
|
|
"onlineSourceCount": 2,
|
|
"locatedSourceCount": 2,
|
|
"missingProtocols": ["YUTONG_MQTT"],
|
|
"mileageDeltaKm": 0.8,
|
|
"sourceTimeDeltaSeconds": 42,
|
|
"status": "degraded",
|
|
"severity": "warning",
|
|
"title": "来源不完整",
|
|
"detail": "2/3 个来源在线，车辆服务可用但缺少 YUTONG_MQTT 来源。"
|
|
}
|
|
}
|
|
```
|
|
|
|
`missingProtocols` lists canonical source evidence that is completely absent for the vehicle service, so callers can distinguish a missing source from an offline-but-known source. `status` values are `consistent`, `degraded`, `offline`, `single_source`, `no_source`, `mileage_divergent`, and `time_divergent`. `severity` values are `ok`, `warning`, and `error`. `/api/vehicle-service/overview` and `/api/vehicle-service/overviews` also return `sourceConsistency`; overview responses may only include lightweight counts and diagnosis, while detail responses include location, mileage, and source-time deltas when realtime source rows are available.
|
|
|
|
### Realtime Vehicles
|
|
|
|
```http
|
|
GET /api/realtime/vehicles?keyword=粤AG18312&protocol=JT808&online=online&serviceStatus=degraded&limit=50&offset=0
|
|
```
|
|
|
|
Returns VIN-level realtime rows with canonical vehicle-level `serviceStatus`. Protocol is a source filter, not a product boundary.
|
|
|
|
### Vehicle Coverage
|
|
|
|
```http
|
|
GET /api/vehicles/coverage?keyword=粤AG18312&serviceStatus=degraded&limit=20&offset=0
|
|
```
|
|
|
|
Returns VIN-level source coverage rows for the vehicle service list. Each row includes the canonical vehicle-level `serviceStatus` so frontend, exports, and external integrations share the same health definition. `serviceStatus` accepts `healthy`, `degraded`, `offline`, `no_data`, and `identity_required`.
|
|
|
|
Coverage summary also exposes `noDataVehicles`, so UI can show vehicles that exist in identity binding but have no GB32960, JT808, or Yutong MQTT source evidence. `/api/vehicles/coverage?serviceStatus=no_data` returns those bound vehicles for follow-up source onboarding.
|
|
|
|
Coverage rows also include lightweight `sourceConsistency` so list views can show the same vehicle-level source diagnosis without issuing per-row detail requests.
|
|
|
|
### History Locations
|
|
|
|
```http
|
|
GET /api/history/locations?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-03%2000:00:00&dateTo=2026-07-03%2023:59:59&limit=20&offset=0
|
|
```
|
|
|
|
Returns historical location points from TDengine, enriched with plate where possible.
|
|
|
|
### RAW Frames
|
|
|
|
Short GET query:
|
|
|
|
```http
|
|
GET /api/history/raw-frames?keyword=粤AG18312&protocol=GB32960&limit=20&offset=0&includeFields=true
|
|
```
|
|
|
|
Large field-filter query:
|
|
|
|
```http
|
|
POST /api/history/raw-frames/query
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"keyword": "粤AG18312",
|
|
"protocol": "GB32960",
|
|
"dateFrom": "2026-07-03 00:00:00",
|
|
"dateTo": "2026-07-03 23:59:59",
|
|
"fields": ["gb32960.vehicle.speed_kmh", "gb32960.vehicle.total_mileage_km"],
|
|
"includeFields": true,
|
|
"limit": 20,
|
|
"offset": 0
|
|
}
|
|
```
|
|
|
|
Use POST when `fields` may be long. `parsedFields` is returned only when `includeFields=true` or specific `fields` are requested.
|
|
|
|
### Mileage
|
|
|
|
```http
|
|
GET /api/mileage/daily?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
|
|
GET /api/mileage/summary?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&dateTo=2026-07-03
|
|
```
|
|
|
|
Returns daily mileage rows and aggregate mileage summary.
|
|
|
|
## Compatibility Rule
|
|
|
|
Existing callers may still send `vin`. The BFF treats `vin` as a vehicle lookup value for compatibility, so `vin=粤AG18312` still resolves through identity binding. New code should use `keyword` to avoid implying the value is already a real VIN.
|