lingniu-vehicle-ingest/vehicle-data-platform/docs/product-spec.md

# Vehicle Data Platform Product Spec

## Visual Direction

The UI is a professional vehicle data operations console. It uses Semi UI as the component base, a restrained gray-white control-room palette, dense but readable tables, right-side drawers for detail, and blue-cyan accents for primary actions. It should feel closer to a cloud data console and mature fleet telematics platform than a marketing dashboard.

## Product North Star

The platform is a vehicle service center. GB32960, JT808, and Yutong MQTT are ingestion evidence for the same vehicle, not three separate product surfaces. These three data sources ultimately exist to support one vehicle service. A user should be able to search one VIN, plate, or phone number and understand whether that vehicle is online, where it is, what its latest state is, how reliable its mileage is, and which source produced each piece of evidence.

Every primary workflow should answer a vehicle-level question first, then allow protocol-level drill-down only when diagnosis or raw evidence is needed.

The current product goal is to evolve toward a production vehicle data management center, comparable to mature fleet IoT and telematics platforms: realtime monitoring, trajectory replay, historical evidence query, alert triggering and notification, statistics, and production operation quality all serve the same vehicle object.

The product must not expose GB32960, JT808, and Yutong MQTT as three final products. They are acquisition paths. The final product is a vehicle service that answers online state, current location, historical trajectory, source reliability, alert responsibility, and statistical evidence for one vehicle.

## Adjusted Product Goal

The active goal is now a vehicle data management middle platform for production operations, not a protocol demo or raw-data console. The reference shape is a mature commercial telematics platform:

- Realtime monitoring: map-first fleet status, vehicle online state, source freshness, abnormal location and current telemetry.
- Trajectory replay: vehicle/time-window playback, AMap route context, speed and mileage evidence, gap detection, and raw-frame jump links.
- Historical query: paged location, raw frame, parsed fields, and export with field trimming for large responses.
- Alert events: source outage, no realtime update, VIN/binding failure, location missing, mileage abnormality, parse failure, and cross-source inconsistency.
- Notification workflow: rule owner, channel, escalation window, affected vehicle scope, recovery evidence, and copyable notification text.
- Statistics: daily/range mileage, online rate, offline duration, completeness, source consistency, and evidence-backed drill-down.
- Vehicle governance: VIN-centered identity, plate, phone, OEM, binding health, source coverage, and missing-source remediation.
- Ops quality: gateway, queue, Redis, TDengine, MySQL, AMap, release, capacity, and lag health.

The dashboard should behave like a command center for vehicle service operations. It should not use marketing-style hero composition. The first screen should expose operating state, map capability, alert pressure, and direct workflow entry points.

## Primary Screens

The platform navigation should use vehicle-service language rather than protocol-product language:

1. Operations Cockpit: vehicle service KPI summary, service status distribution, live map preview, alert queue, data quality, and link health.
2. Live Monitor: map-first current vehicle monitoring with online/offline state, abnormal highlights, source freshness, AMap readiness, and a dense vehicle table.
3. Vehicle Center: table-first vehicle registry, binding state, source coverage, service status, and missing-source governance.
4. Vehicle Detail: one vehicle service file with identity, latest realtime state, source evidence, history, raw, mileage, alerts, quality evidence, and copyable diagnostics.
5. Trajectory Replay: historical location playback with AMap polyline, playback marker, auto play/pause, speed controls, gap detection, mileage evidence, and table evidence.
6. History Query: historical locations, raw frames, and flattened parsed fields with pagination and field trimming.
7. Alert Events: alert trigger records, affected vehicles, rule evidence, manual state, notification state, escalation readiness, and recovery evidence.
8. Notification Rules: alert trigger rules, notification targets, channels, escalation windows, acceptance criteria, affected-user scope, and copyable runbooks.
9. Statistics: one vehicle-service statistics workspace covering daily/range mileage, online rate, offline duration, data completeness, source consistency, and exportable evidence.
10. Ops Quality: GB32960, JT808, Yutong MQTT, Kafka, NATS, Redis, TDengine, MySQL, AMap, gateway, and runtime health.

See `docs/vehicle-platform-blueprint.md` for the detailed page-level blueprint and phased implementation plan.

## Domain Principle

The product model is vehicle-first. GB32960, JT808, and Yutong MQTT are ingestion sources for one vehicle service, not separate business products. The UI should lead with VIN, plate, online state, location, mileage, and data quality; protocol appears only as source attribution, diagnosis, and raw-frame traceability.

Vehicle service coverage is always shown at VIN level. A vehicle may have one or more ingestion sources, but upper product views should summarize source count, online source count, last seen time, and binding status before drilling into protocol-specific diagnostics.

Vehicle lists should expose a vehicle-level service status derived from binding and source coverage: identity required, no data source, offline, degraded, or healthy. Protocol tags remain attribution and troubleshooting context, not the primary status.

Vehicle detail and top search context should expose one source-consistency conclusion, such as `来源一致`, `部分来源离线`, or `里程差异偏大`. This diagnosis comes from `sourceConsistency` and turns GB32960, JT808, and Yutong MQTT into explainable evidence under one vehicle service rather than three competing realtime products.

Vehicle service lists and dashboard previews should label protocol coverage as `来源证据`. The row should make the vehicle service coverage explicit, for example `2/3 来源在线`, while protocol tags remain compact evidence labels underneath the same vehicle row.

Dashboard and vehicle-list summary cards should expose both `单源车辆` and `多源车辆`. Single-source vehicles are operationally important because they cannot be cross-checked across sources, so they must be one-click filter targets rather than hidden behind the generic coverage filter.

`暂无来源车辆` is also a first-class governance entry. It represents bound vehicles that have no current GB32960, JT808, or Yutong MQTT source evidence, and should route directly to the `no_data` vehicle service filter.

## Vehicle Service Workflow

Global vehicle search accepts VIN, plate, JT808 phone, or known source identifier. The resolved vehicle context should travel across the whole product:

- Realtime monitor opens the current position and source freshness for that vehicle.
- Trajectory playback opens the same VIN and selected time window.
- History query opens raw and parsed evidence for the same VIN.
- Statistics opens daily or range mileage for the same VIN.
- Alert events opens active and historical alerts for the same VIN.
- Vehicle detail acts as the hub that links all of the above.

The user should rarely need to choose a protocol before choosing a vehicle. Protocol filters are secondary and are used for source diagnosis, cross-source comparison, and raw frame verification.

## Map Capability

The product uses AMap as the map provider for production map rendering.

- Web JS key is injected through frontend runtime config, not hard-coded into source.
- API/server key is kept in backend or ECS environment configuration.
- The AMap security code must stay server-side in production. The browser should receive `AMAP_SECURITY_SERVICE_HOST`, not the raw security code.
- Realtime monitor shows current vehicle points, clustering or bounded point rendering, online/offline color, abnormal highlights, selected vehicle highlight, and source freshness.
- Trajectory playback shows historical polyline, start/end markers, current playback marker, auto play/pause, speed controls, step controls, and the table row that backs the selected point.
- Alert events can highlight affected vehicle locations when the alert has valid coordinates.
- If AMap is unavailable or not configured, pages must fall back to coordinate preview instead of blocking the workflow.

AMap should be treated as infrastructure for vehicle operations, not only as a visual widget:

- Realtime monitor: bounded vehicle point loading, fit-to-result, selected vehicle highlight, online/offline/alert color semantics, and source freshness labels.
- Trajectory replay: route polyline, playback cursor, sampled map points, paginated evidence table, and raw-frame jump links.
- History query: location evidence can open the same coordinate in the map context.
- Alert events: vehicle location at trigger time should be shown when longitude and latitude are available.
- Ops quality: map key readiness, security proxy readiness, and frontend loader failures should be visible.
- Statistics: mileage and online-rate anomalies should link back to a map/time-window context so operators can verify whether the issue is vehicle behavior or source data loss.

AMap credentials supplied by operations must be configured through ECS environment variables:

- `AMAP_WEB_JS_KEY`: public Web JS key served through `/app-config.js`.
- `AMAP_API_KEY`: server-side AMap service key for backend map/geocode/future server calls.
- `AMAP_SECURITY_JS_CODE`: private security code kept by the API service.
- `AMAP_SECURITY_SERVICE_HOST=/_AMapService`: frontend proxy path used by the AMap loader.

Supplied AMap production credentials must be applied on ECS only:

- API service key: configure as `AMAP_API_KEY`.
- Web JS key: configure as `AMAP_WEB_JS_KEY`.
- Web JS security code: configure as `AMAP_SECURITY_JS_CODE`.

## Alert And Notification Scope

Alert events are first-class product records, but notification delivery can be implemented incrementally.

- Phase 1: alert list, severity, trigger time, affected vehicle, evidence links, and manual status.
- Phase 2: notification channels such as email, webhook, or enterprise chat.
- Phase 3: escalation policy for unresolved data breakage and affected-user notification.

Alerts should cover source offline, no realtime update, location missing, mileage abnormality, raw parse failure, binding missing, and cross-source inconsistency.

Notification rules are managed separately from alert records. Alert Events answers "what is happening now"; Notification Rules answers "who should be notified, when to escalate, and how to verify recovery." A rule should always expose trigger condition, owner, channel, escalation window, and acceptance criteria.

## Statistics Scope

Statistics must stay vehicle-first and evidence-backed:

- Daily mileage and range mileage should link back to trajectory and raw evidence.
- Online rate should be computed by vehicle and then broken down by source.
- Data completeness should report missing location, mileage, SOC, speed, and source freshness.
- Source consistency should compare GB32960, JT808, and Yutong MQTT only when the same VIN has multiple sources.
- The statistics page should show these four domains together, because all protocol data ultimately supports one vehicle service view.

## Interaction Rules

- Tables are the default data surface.
- Filters stay above the table.
- Details open in a right drawer unless a full route is needed.
- Error and empty states must be explicit.
- No decorative hero, no oversized marketing card layout, no dark large-screen style.