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

docs: clarify analytics runtime scope

Browse Source
This commit is contained in:
lingniu
2026-07-01 06:15:43 +08:00
parent f91fa21463
commit 6bc36eb5a8
2 changed files with 17 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/operations/gb32960-service-split-runbook.md
View File

@@ -9,7 +9,7 @@ This runbook covers the split GB32960 ingest, history, and analytics runtimes. K
| GB32960 ingest | `:gb32960-ingest-app` | Accept GB32960 TCP connections, decode/authenticate frames, produce raw and normalized records to Kafka, and send protocol ACKs after required Kafka production succeeds. | TCP `32960`, HTTP `20100` |
| JT808 ingest | `:jt808-ingest-app` | Accept JT/T 808 TCP connections on the production receive port, parse raw frames, archive frame bytes, and produce raw/event envelopes to Kafka. | TCP `808`, HTTP `20482` |
| Vehicle history | `:vehicle-history-app` | Consume GB32960/JT808 raw/event Kafka records, store compact history rows plus TDengine `raw_frames` `parsedJson`/`metadataJson`/`rawUri`, and expose TDengine-backed history APIs. | HTTP `20200` |
| Vehicle analytics | `:vehicle-analytics-app` | Consume GB32960 event Kafka records and update analytics outputs such as daily vehicle statistics. Vehicle state can also be enabled from this runtime. | HTTP `20300` |
| Vehicle analytics | `:vehicle-analytics-app` | Consume JT808 event Kafka records, calculate daily mileage from reported GPS total mileage, and write metrics to `vehicle_stat_metric`. | HTTP `20300` |
## Kafka Contract
@@ -25,7 +25,6 @@ This runbook covers the split GB32960 ingest, history, and analytics runtimes. K
Default local consumer groups:
- History: `vehicle-history`
- Analytics state: `vehicle-state` when `VEHICLE_STATE_ENABLED=true`
- Analytics statistics: `vehicle-stat`
## ACK Semantics
@@ -132,7 +131,7 @@ java --sun-misc-unsafe-memory-access=allow \
-jar modules/apps/vehicle-analytics-app/target/vehicle-analytics-app.jar
```
To enable the latest-state API in analytics, also set `VEHICLE_STATE_ENABLED=true` and configure the state repository requirements used by `vehicle-state-service`.
`vehicle-analytics-app` is intentionally a metric runtime only. Latest-state APIs belong to `vehicle-state-service` and should be deployed as a separate consumer if that surface is needed.
## Health Verification
@@ -189,7 +188,7 @@ Expected E2E result when Kafka and all services are running:
- `vehicle.raw.gb32960.v1` receives a raw archive reference envelope.
- `vehicle.event.gb32960.v1` receives one or more normalized records.
- `target/split-event-store` receives event-store files after the history service flushes consumed Kafka records, including raw archive reference records.
- `target/split-vehicle-stat` receives stat output after analytics consumes applicable event records.
- JT808 analytics writes daily mileage rows to MySQL `vehicle_stat_metric` after consuming applicable `vehicle.event.jt808.v1` records.
Do not expect `vehicle-history-app` to create raw `.bin` archive files from Kafka raw records in the current implementation. `RawArchiveEventSink` can write archive files only when it receives `VehicleEvent.RawArchive.rawBytes()` inside the same JVM; the Kafka envelope carries only `RawArchiveRef` metadata.