124 lines
3.6 KiB
Markdown
124 lines
3.6 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.
|
|
|
|
### Realtime Vehicles
|
|
|
|
```http
|
|
GET /api/realtime/vehicles?keyword=粤AG18312&protocol=JT808&online=online&limit=50&offset=0
|
|
```
|
|
|
|
Returns VIN-level realtime rows. 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`, and `identity_required`.
|
|
|
|
### 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.
|