shishengliang/lingniu-vehicle-ingest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(platform): define vehicle service platform blueprint

Browse Source
This commit is contained in:
lingniu
2026-07-04 16:09:51 +08:00
parent 19f260d94a
commit 0c7910d6b9
3 changed files with 331 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
vehicle-data-platform/docs/api-contract.md
View File

@@ -107,6 +107,13 @@ GET /api/history/locations?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-03
Returns historical location points from TDengine, enriched with plate where possible.
For trajectory replay, the BFF should eventually return two shapes from the same evidence set:
- `items`: paginated table rows for audit and export.
- `mapPoints`: bounded or sampled points for map rendering and playback.
This keeps table pagination precise while preventing large routes from overloading the browser map.
### RAW Frames
Short GET query:
@@ -144,6 +151,43 @@ GET /api/mileage/summary?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&d
Returns daily mileage rows and aggregate mileage summary.
### Alert Events
Planned API surface:
```http
GET /api/alerts/events?keyword=粤AG18312&severity=warning&status=open&limit=20&offset=0
GET /api/alerts/events/{id}
PATCH /api/alerts/events/{id}
GET /api/alerts/rules
GET /api/alerts/notifications?eventId=xxx&limit=20&offset=0
```
Alert records should be vehicle-first and evidence-backed. Each event should include vehicle identity, issue type, severity, protocol/source when relevant, trigger time, last seen time, current status, evidence links, trace ID if available, and notification state.
Initial alert types:
- `SOURCE_OFFLINE`
- `NO_REALTIME_UPDATE`
- `LOCATION_MISSING`
- `MILEAGE_DIVERGENT`
- `RAW_PARSE_FAILURE`
- `BINDING_MISSING`
- `SOURCE_TIME_DIVERGENT`
- `QUEUE_BACKLOG`
### Online And Completeness Statistics
Planned API surface:
```http
GET /api/statistics/online-rate?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
GET /api/statistics/completeness?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
GET /api/statistics/source-consistency?keyword=粤AG18312&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
```
These APIs should link back to `/api/history/locations` or `/api/history/raw-frames/query` evidence. The UI must not show statistics as untraceable numbers.
## Compatibility Rule
Existing callers may still send `vin`. The BFF treats `vin` as a vehicle lookup value for compatibility, so `vin=粤AG18312` still resolves through identity binding. New code should use `keyword` to avoid implying the value is already a real VIN.

31
vehicle-data-platform/docs/product-spec.md
View File

@@ -12,15 +12,19 @@ Every primary workflow should answer a vehicle-level question first, then allow
## Primary Screens
1. Dashboard: vehicle service KPI summary, service status distribution, map preview, alerts, data quality, and link health.
2. Vehicle Service: table-first vehicle registry, binding state, source coverage, and service status.
3. Realtime Monitor: map/table switch for current online vehicles and abnormal vehicles.
4. Vehicle Detail: one vehicle profile with latest state, sources, history, raw, mileage, alerts, and quality evidence.
5. Trajectory Playback: location history with map track playback and table evidence.
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, notification state, and evidence links.
8. Statistics: daily/range mileage, online rate, data completeness, and source consistency.
9. Ops Quality: Kafka, NATS, Redis, TDengine, MySQL, gateway, and writer health.
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
@@ -57,11 +61,18 @@ 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.
- Realtime monitor shows current vehicle points, online/offline color, abnormal highlights, and source freshness.
- Trajectory playback shows historical polyline, start/end markers, current playback marker, and the table row that backs the selected point.
- 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.

266
vehicle-data-platform/docs/vehicle-platform-blueprint.md Normal file
View File

@@ -0,0 +1,266 @@
# Vehicle Data Management Platform Blueprint
## Goal
Build one vehicle service platform. GB32960, JT808, and Yutong MQTT are source evidence for the same vehicle, not separate applications. The platform should help operations users answer five 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?
## Market Reference
Common telematics and fleet-management 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 JavaScript API 2.0: production WebGL map rendering and browser map controls.
- AMap trajectory replay demo: marker replay over historical points.
- Fleet platforms such as Verizon Connect and similar commercial systems: live maps, geofences, route replay, alerts, and reports.
## 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. 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.
### Live Monitor
Purpose: near-realtime vehicle monitoring.
Primary modules:
- Full-width AMap panel with clustered vehicle points.
- 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`.
- Fall back to coordinate preview when AMap cannot load.
- Support marker click, fit to filtered vehicles, selected vehicle highlight, and external AMap coordinate open.
### 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.
- 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.
### 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.
### 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.
Rule:
- Statistics should link back to trajectory or RAW evidence, so numbers remain auditable.
### 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.
### 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.
### Phase 3: Alert Events
- Add alert records and list/detail UI.
- Add rule labels and evidence links.
- Add manual status and notification plan preview.
### 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.
### 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.