docs(platform): define vehicle keyword API contract

2026-07-04 00:45:29 +08:00
parent 20e2781f35
commit a4ff210c82
3 changed files with 154 additions and 4 deletions
--- a/vehicle-data-platform/docs/api-contract.md
+++ b/vehicle-data-platform/docs/api-contract.md
@@ -0,0 +1,105 @@
+# 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.