shishengliang/lingniu-vehicle-ingest

Fork 0

Files

lingniu 1235e76c32 feat(platform): promote alert events surface

2026-07-04 17:58:33 +08:00

7.5 KiB

Raw Blame History

Vehicle Data Platform API Contract

Response Envelope

All platform APIs return the same envelope:

{
  "data": {},
  "traceId": "trace-20260704000000.000000",
  "timestamp": 1783094400000
}

Pagination uses:

{
  "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

GET /api/dashboard/summary

Returns vehicle service KPIs, source distribution, vehicle service status distribution, link health, and realtime backlog.

Vehicle Service

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.

{
  "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

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

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

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.

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:

GET /api/history/raw-frames?keyword=粤AG18312&protocol=GB32960&limit=20&offset=0&includeFields=true

Large field-filter query:

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

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.

Alert Events

Current API surface:

GET /api/alert-events?keyword=粤AG18312&protocol=JT808&issueType=NO_SOURCE&limit=20&offset=0
GET /api/alert-events/summary?keyword=粤AG18312&protocol=JT808&issueType=NO_SOURCE
GET /api/alert-events/notification-plan?keyword=粤AG18312&protocol=JT808&issueType=NO_SOURCE&limit=20

/api/quality/issues, /api/quality/summary, and /api/quality/notification-plan remain compatibility aliases. New UI and integrations should use /api/alert-events* so the API language matches the vehicle data management center.

Alert event rows are vehicle-first and evidence-backed. Each event includes vehicle identity, issue type, severity, protocol/source when relevant, last seen time, source endpoint, detail, and links generated by the BFF/UI to realtime, trajectory, RAW, mileage, vehicle detail, or notification rule evidence.

Initial alert types:

NO_SOURCE
VIN_MISSING
LINK_GAP
FIELD_MISSING
CAPACITY_RISK

Future durable alert records should extend this surface with event IDs, manual status, assignee, acknowledgement, escalation state, and notification logs:

GET /api/alert-events/{id}
PATCH /api/alert-events/{id}
GET /api/alert-events/{id}/notifications?limit=20&offset=0

Online And Completeness Statistics

Planned API surface:

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.

7.5 KiB Raw Blame History