diff --git a/vehicle-data-platform/docs/product-spec.md b/vehicle-data-platform/docs/product-spec.md index cc019c89..cb668951 100644 --- a/vehicle-data-platform/docs/product-spec.md +++ b/vehicle-data-platform/docs/product-spec.md @@ -10,6 +10,8 @@ The platform is a vehicle service center. GB32960, JT808, and Yutong MQTT are in 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. + ## Primary Screens The platform navigation should use vehicle-service language rather than protocol-product language: @@ -68,9 +70,18 @@ The product uses AMap as the map provider for production map rendering. - 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. + 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. diff --git a/vehicle-data-platform/docs/vehicle-platform-blueprint.md b/vehicle-data-platform/docs/vehicle-platform-blueprint.md index e895aa22..cf497181 100644 --- a/vehicle-data-platform/docs/vehicle-platform-blueprint.md +++ b/vehicle-data-platform/docs/vehicle-platform-blueprint.md @@ -11,6 +11,8 @@ Build one vehicle data management platform around a single vehicle service. GB32 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: @@ -66,13 +68,18 @@ Interaction: - 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 vehicle points and selected-vehicle context. +- 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. @@ -86,6 +93,11 @@ AMap behavior: - 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. @@ -134,6 +146,11 @@ 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. @@ -167,6 +184,16 @@ Notification phases: - 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. @@ -197,6 +224,8 @@ Primary modules: 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 @@ -260,6 +289,7 @@ Protocol-specific data appears as source evidence fields in these responses. New - 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 @@ -267,6 +297,7 @@ Protocol-specific data appears as source evidence fields in these responses. New - 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 @@ -274,12 +305,14 @@ Protocol-specific data appears as source evidence fields in these responses. New - 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 @@ -287,3 +320,5 @@ Protocol-specific data appears as source evidence fields in these responses. New - 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.