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

The current product goal is therefore adjusted to: build a complete vehicle data management center with realtime monitoring, trajectory replay, history query, alert triggering and notification, statistics, and operations quality. GB32960, JT808, and Yutong MQTT remain source evidence and should disappear from the primary user mental model unless the user is diagnosing a specific source.

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

Reference principles used for the Lingniu platform:

- Samsara-style telematics products emphasize realtime GPS visibility, diagnostics, routing/navigation, energy/fuel, alerts, and operational efficiency.
- AMap Web JS should power map rendering, marker interaction, and trajectory display while keeping the security code behind a service proxy.
- TDengine vehicle IoT guidance fits the platform's realtime location monitoring and trajectory replay query pattern, while Redis remains the low-latency realtime projection.

## 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.
- Production readiness rail: AMap Web JS state, security proxy state, location point cap, latest refresh time, and fallback mode.

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.
- Export and share controls: copy query link, open AMap line, export current page evidence.

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.
- AMap unavailable or security proxy misconfigured.

### 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.
- Notification impact: affected vehicles, affected BI users, last normal data time, and recovery time after alert closure.

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.
- Primary navigation should use user jobs: operations cockpit, realtime monitor, vehicle center, trajectory replay, history query, alerts, statistics, notification rules, and ops quality.

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