lingniu-vehicle-ingest/vehicle-data-platform/docs/vehicle-platform-blueprint.md

Vehicle Data Management Platform Blueprint

Goal

Build one vehicle data management platform around a single vehicle service. GB32960, JT808, and Yutong MQTT are source evidence for the same vehicle, not separate applications. The three sources are only acquisition paths; the product outcome is one searchable, monitorable, and diagnosable vehicle service. The platform should help operations users answer six questions quickly:

1. Is this vehicle online now?
2. Where is it and what is its latest state?
3. Can I replay its trajectory and inspect evidence?
4. Is its data reliable across sources?
5. Which alert or data-breakage event needs action?
6. Which operational statistic or data gap needs follow-up?

The product direction should reference production telematics and fleet IoT platforms, but keep the Lingniu domain model simple: one vehicle service, multiple source evidences, auditable history, and operational alerts. Realtime data source pages are not product destinations; they are evidence and diagnosis layers under the vehicle.

Market Reference

Common telematics, fleet-management, and vehicle IoT platforms converge on a small set of durable workflows:

• Live map: current vehicle distribution, online state, abnormal state, geofence or area context.
• Trip replay: historical polyline, playback marker, speed/time panel, raw evidence drill-down.
• Alerts: offline timeout, location missing, mileage abnormality, parse failure, route deviation, geofence, device fault, and notification state.
• Reports: daily mileage, online rate, source completeness, abnormal vehicles, driver or vehicle behavior.
• Asset service file: vehicle identity, device, source coverage, latest realtime state, history, alerts, and maintenance evidence.

Relevant references:

• TDengine vehicle IoT scenario: online monitoring, trajectory replay, and high-volume time-series storage.
• AMap Open Platform: Web JS map, geocoding, route planning, geofence, logistics, and trajectory services.
• AMap trajectory replay demo: marker replay over historical points.
• Commercial fleet platforms: live GPS tracking, historical route playback, geofence, driver behavior, alerts, reports, and asset management.
• Domestic vehicle-monitoring platforms: monitoring cockpit, vehicle monitor, trip replay, realtime alerts, running statistics, and alert management.

Information Architecture

The left navigation should be vehicle-service oriented:

1. Operations Cockpit
2. Live Monitor
3. Vehicle Center
4. Vehicle Detail
5. Trajectory Replay
6. History Query
7. Alert Events
8. Statistics
9. Notification Rules
10. Ops Quality

The global search stays persistent in the top bar. It accepts VIN, plate, or JT808 phone and resolves to one vehicle context. The selected vehicle context should travel across all pages.

Page Design

Operations Cockpit

Purpose: executive and operations snapshot.

Primary modules:

• Fleet KPI strip: bound vehicles, online vehicles, abnormal vehicles, vehicles without source, multi-source vehicles.
• Live map preview: recent online distribution and abnormal points.
• Data breakage queue: source offline, no realtime update, missing binding, parse failure, mileage divergence.
• Source health: GB32960, JT808, Yutong MQTT, Kafka, NATS, Redis, TDengine, MySQL.
• Quick statistics: today mileage coverage, online rate, source completeness.

Interaction:

• Clicking KPI cards routes into filtered Vehicle Center or Alert Events.
• Clicking a map point opens Vehicle Detail.
• Clicking a source health item opens Ops Quality with the source filter.

Visual rule:

• Use a compact operations-console layout: KPI strip, map band, alert queue, source health, and statistics evidence in one screen.
• Avoid marketing-style hero sections and oversized decorative dashboard cards.

Live Monitor

Purpose: near-realtime vehicle monitoring.

Primary modules:

• Full-width AMap panel with clustered or bounded vehicle points and selected-vehicle context.
• Right-side vehicle queue: online, offline, degraded, abnormal, no location.
• Bottom table: latest position, speed, mileage, source freshness, service status.
• Map overlays: online state, protocol source, alert severity.

AMap behavior:

• Use runtime AMAP_WEB_JS_KEY.
• Use server-side security proxy through AMAP_SECURITY_SERVICE_HOST.
• Keep AMAP_SECURITY_JS_CODE on the API service. Do not hardcode it into frontend bundles.
• Keep the AMap service/API key for future server-side calls such as geocoding, route planning, geofence, and trajectory services.
• Fall back to coordinate preview when AMap cannot load.
• Support marker click, fit to filtered vehicles, selected vehicle highlight, and external AMap coordinate open.

Scale rule:

• The map API must never request all vehicles blindly. It should request bounded rows by viewport, search, state filter, or a server-defined cap.
• Marker rendering should degrade from precise points to clusters or table-first fallback when the result set is too large.

Vehicle Center

Purpose: one place to manage and inspect vehicle identity and source coverage.

Primary modules:

• Vehicle table: plate, VIN, phone, OEM, source coverage, online state, service status, latest location time.
• Filters: keyword, OEM, service status, source, online state, missing binding.
• Source evidence summary: 2/3 sources online, missing source list, latest source time delta.

Interaction:

• Row opens Vehicle Detail.
• Missing binding rows link to identity maintenance workflow.

Vehicle Detail

Purpose: single-vehicle service file.

Primary modules:

• Identity header: plate, VIN, phone, OEM, selected protocol evidence, latest service conclusion.
• Realtime cards: location, speed, mileage, SOC/energy, source freshness, platform name.
• Source evidence tabs: GB32960, JT808, Yutong MQTT.
• Timeline: latest realtime event, latest history point, latest raw frame, alert events.
• Evidence links: realtime, trajectory, raw frames, mileage, alerts.
• Copy diagnostic summary including platform release.

Rule:

• Protocol data must be shown as evidence under one vehicle, not as three separate products.

Trajectory Replay

Purpose: historical route verification and operations playback.

Primary modules:

• AMap route panel: polyline, start/end markers, playback marker, optional speed color ramp.
• Playback controls: play, pause, speed, step, seek, and auto-stop at the last point.
• Evidence table: time, longitude, latitude, speed, mileage, protocol, raw frame link.
• Quality strip: missing points, time gaps, mileage jumps.

Query:

• keyword, protocol optional, date range, paging.
• Long history should page the table but render map from a capped or sampled point set.

Evidence rule:

• Replay is not only animation. Every map point must be traceable to a location record and, when available, to the raw frame that produced it.
• A sampled map route can be shown, but the table must keep paginated auditable evidence.

History Query

Purpose: precise historical data inspection.

Primary modules:

• Location history tab.
• RAW frames tab.
• Parsed fields tab.
• Field filter drawer for POST query when fields are long.

Rule:

• Query results stay paginated.
• RAW fields are only returned when requested.
• Parsed fields use the maintained field mapping, not ad hoc paths.

Alert Events

Purpose: event trigger and notification workflow.

Primary modules:

• Alert list: severity, issue type, vehicle, source, trigger time, last seen, status, assignee.
• Alert detail drawer: evidence links, source diagnostics, affected users, notification log.
• Rules view: offline timeout, source gap, location missing, mileage divergence, raw parse failure, binding missing.

Notification phases:

• Phase 1: manual status and evidence links.
• Phase 2: email/webhook/enterprise chat.
• Phase 3: escalation for unresolved data breakage.

Required alert domains:

• Source no-update/offline.
• Vehicle online state timeout.
• Location missing or invalid.
• Mileage jump, rollback, or impossible delta.
• Raw parse failure or unknown field burst.
• Binding missing or VIN unresolved.
• Cross-source time/location/mileage inconsistency.

Notification Rules

Purpose: make alert triggering and notification strategy configurable.

Primary modules:

• Rule list: offline timeout, source no-update, location missing, mileage jump, parse failure, binding missing, gateway stopped.
• Rule editor: protocol/source scope, vehicle/OEM scope, threshold, silence window, severity, notification target.
• Recipient groups: operations, data platform owner, affected BI users, external platform contacts.
• Notification log: sent, suppressed, failed, acknowledged, escalated.

Rule:

• Data-breakage notifications should be evidence-first: every notification links to affected vehicles, last good data time, source endpoint, and current recovery status.

Statistics

Purpose: business and data-quality statistics.

Primary modules:

• Mileage: daily mileage, range mileage, vehicle ranking, source coverage.
• Online: online rate, offline duration, no update duration, source online distribution.
• Completeness: location, mileage, SOC, speed, source freshness.
• Consistency: cross-source time delta and mileage delta for multi-source vehicles.
• Statistics overview: show the four domains together so operations users understand that GB32960, JT808, and Yutong MQTT are evidence feeding one vehicle service.

Rule:

• Statistics should link back to trajectory or RAW evidence, so numbers remain auditable.
• Online/offline statistics should be vehicle-first and then source-breakdown. The default view is one vehicle service, not three protocol reports.
• Mileage statistics should clearly state whether they use total-mileage difference, interval accumulation, or source-specific fallback.

Ops Quality

Purpose: production reliability screen.

Primary modules:

• Gateway health: GB32960, JT808, Yutong MQTT listener state and connection count.
• Queue health: NATS and Kafka lag/backlog.
• Storage health: Redis, TDengine, MySQL read/write state.
• Runtime health: release, timeout, AMap readiness, config safety.
• Slow query and error queue.

Visual System

Use Semi UI as the component base. The style should feel like a cloud operations console rather than a decorative dashboard:

• Dense, table-first layouts.
• White and neutral gray base, blue/cyan action color, small semantic red/orange/green states.
• Compact top bar with release, map readiness, and current selected vehicle.
• Full-width map bands, not map cards inside cards.
• Cards only for repeated metrics or detail blocks; avoid nested cards.
• Drawer for detail and evidence, full routes for heavy workflows.
• No landing page, no marketing hero, no oversized decorative cards.

Data Model Boundaries

Frontend pages should use vehicle-level BFF APIs first:

• /api/dashboard/summary
• /api/vehicle-service
• /api/vehicle-service/summary
• /api/vehicle-service/overview
• /api/vehicle-service/overviews
• /api/realtime/vehicles
• /api/history/locations
• /api/history/raw-frames
• /api/history/raw-frames/query
• /api/mileage/daily
• /api/mileage/summary
• /api/quality/issues
• /api/quality/notification-plan
• /api/ops/health

Protocol-specific data appears as source evidence fields in these responses. New API design should avoid adding separate top-level products for GB32960, JT808, or MQTT unless it is an ingestion operations page.

Backend Gaps To Close

1. Live monitor needs map-ready vehicle rows with bounded response size and source freshness.
2. Trajectory replay needs sampled map points plus paginated evidence table.
3. Alert Events needs durable alert records, manual status, and notification log.
4. Statistics needs online/offline interval aggregation in addition to mileage.
5. Vehicle Detail needs a compact latest-field summary per source to avoid shipping huge RAW payloads by default.
6. Ops Quality needs queue lag and gateway connection metrics surfaced consistently.

Implementation Phases

Phase 1: Make Current Platform Feel Like One Vehicle Service

• Rename and reorganize navigation around the IA above.
• Make Dashboard, Realtime, Vehicles, Detail, History, Mileage, and Quality copy consistent.
• Add empty/error states that explain vehicle-first resolution.
• Keep current APIs and avoid schema churn.
• Add a product-style top-level route structure that makes Live Monitor, Trajectory Replay, History Query, Alert Events, Notification Rules, Statistics, and Ops Quality equally discoverable.

Phase 2: Map-Centric Monitoring And Replay

• Expand VehicleMap for selected marker, fit controls, polyline playback, and large-point fallback.
• Add replay controls on History.
• Add AMap readiness diagnostics to Ops Quality and Dashboard.
• Keep Ops Quality as a standalone runtime page for gateway, queue, Redis, TDengine, MySQL, AMap, and release checks.
• Inject AMap Web JS key through runtime config and keep the API/service key in backend or ECS environment variables.

Phase 3: Alert Events

• Add alert records and list/detail UI.
• Add rule labels and evidence links.
• Add manual status and notification plan preview.
• Add notification rule configuration and send-log preview.
• Add affected-vehicle drill-down and location-at-trigger rendering when coordinates exist.

Phase 4: Statistics And Data Reliability

• Add online rate and offline duration APIs.
• Add source completeness and consistency trend views.
• Link every statistic back to trajectory or raw evidence.
• Expose online/offline vehicle detail lists with plate, VIN, source coverage, last seen, and offline duration.

Phase 5: Production Hardening For 100k Vehicles

• Add pagination and sampling contracts for every heavy query.
• Keep map responses bounded.
• Add slow-query budget and UI warnings.
• Add release and traceId to user-copyable diagnostics.
• Define latency budgets for realtime monitor, trajectory query, alert list, and statistics pages.
• Avoid shipping huge raw payloads to operational pages unless the user explicitly requests evidence details.