# 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/vehicles/detail` exposes `lookupResolved=false` and quality issues for follow-up binding work.

## Core Query APIs

### Vehicle Detail

```http
GET /api/vehicles/detail?keyword=粤AG18312
```

Returns one vehicle service view with identity, realtime summary, source coverage, history preview, RAW preview, mileage preview, and quality issues.

### 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.

### 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.