102 lines
7.6 KiB
Markdown
102 lines
7.6 KiB
Markdown
# 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 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. 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.
|
|
|
|
## 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, 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, controls, 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, and escalation readiness.
|
|
8. Statistics: daily/range mileage, online rate, offline duration, data completeness, and source consistency.
|
|
9. 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, playback 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 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_SECURITY_JS_CODE`: private security code kept by the API service.
|
|
- `AMAP_SECURITY_SERVICE_HOST=/_AMapService`: frontend proxy path used by the AMap loader.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|