docs(platform): define vehicle service platform blueprint

vehicle-data-platform/docs/api-contract.md

@@ -107,6 +107,13 @@ GET /api/history/locations?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-03
 
 Returns historical location points from TDengine, enriched with plate where possible.
 
+For trajectory replay, the BFF should eventually return two shapes from the same evidence set:
+
+- `items`: paginated table rows for audit and export.
+- `mapPoints`: bounded or sampled points for map rendering and playback.
+
+This keeps table pagination precise while preventing large routes from overloading the browser map.
+
 ### RAW Frames
 
 Short GET query:
@@ -144,6 +151,43 @@ GET /api/mileage/summary?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&d
 
 Returns daily mileage rows and aggregate mileage summary.
 
+### Alert Events
+
+Planned API surface:
+
+```http
+GET /api/alerts/events?keyword=粤AG18312&severity=warning&status=open&limit=20&offset=0
+GET /api/alerts/events/{id}
+PATCH /api/alerts/events/{id}
+GET /api/alerts/rules
+GET /api/alerts/notifications?eventId=xxx&limit=20&offset=0
+```
+
+Alert records should be vehicle-first and evidence-backed. Each event should include vehicle identity, issue type, severity, protocol/source when relevant, trigger time, last seen time, current status, evidence links, trace ID if available, and notification state.
+
+Initial alert types:
+
+- `SOURCE_OFFLINE`
+- `NO_REALTIME_UPDATE`
+- `LOCATION_MISSING`
+- `MILEAGE_DIVERGENT`
+- `RAW_PARSE_FAILURE`
+- `BINDING_MISSING`
+- `SOURCE_TIME_DIVERGENT`
+- `QUEUE_BACKLOG`
+
+### Online And Completeness Statistics
+
+Planned API surface:
+
+```http
+GET /api/statistics/online-rate?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
+GET /api/statistics/completeness?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
+GET /api/statistics/source-consistency?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
+```
+
+These APIs should link back to `/api/history/locations` or `/api/history/raw-frames/query` evidence. The UI must not show statistics as untraceable numbers.
+
 ## 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.