TriTih
/
eventhub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
eventhub/docs/esper-poc/driver-card-activity-poc.md

3.9 KiB
Raw Blame History

Esper PoC: Tachograph Driver-Card Activity Evaluation

This PoC intentionally uses only existing imported EventHub source events:

  • provider: TACHOGRAPH
  • source kind: DRIVER_CARD
  • extraction code: CARD_ACTIVITY
  • event domain: DRIVER_ACTIVITY
  • event types: DRIVE, WORK, AVAILABILITY, BREAK_REST
  • lifecycles: START, END

It does not introduce canonical-event tables yet. The goal is to prove that Esper can replay one driver and one selected period and produce activity-level and operating-period results.

Endpoint

GET /api/eventhub/esper-poc/tachograph/driver-card-activities

Query parameters:

Parameter Required Example Meaning
tenantKey yes default EventHub tenant key.
driverEntityId yes UUID Existing eventhub.event.driver_entity_id.
occurredFrom yes 2026-04-01T00:00:00Z Requested period start.
occurredTo yes 2026-05-01T00:00:00Z Requested period end.
guardHours no 24 Extra loading window before/after requested period. Needed for activities crossing midnight/month boundaries and long rests crossing period boundaries.
significantDrivingMinutes no 3 DRIVE intervals longer than this threshold count as significant driving periods.
mergeGapSeconds no 60 Consecutive identical activities are merged if the gap is at most this value.
operatingPeriodSplitRestHours no 7 A BREAK_REST activity longer than this threshold splits operating time periods.

Produced levels

Level 1: Raw

raw contains the original point events from eventhub.event.

Level 2: Activities

Esper consumes the raw point events and produces intervals by pairing:

START + END with same sourceRowId, activity type, driver and card slot

The service merges consecutive identical activities in the full guard window first, then clips the merged activities to the requested period. This is important because a long BREAK_REST crossing the requested boundary must keep its full guard-window duration for operating-period splitting.

Operating time periods

operatingTimePeriods are derived from the merged activity timeline.

A BREAK_REST interval splits operating periods when:

activityType = BREAK_REST
and duration > operatingPeriodSplitRestHours

The default is 7 hours. With the default, a BREAK_REST of exactly 7 hours does not split; it must be longer than 7 hours.

Each operating period contains:

  • sequenceNumber
  • startedAt
  • endedAt
  • durationSeconds
  • activities
  • workingOperationTimes
  • drivingTimeInterruptionEvaluation
  • optional references to the long rest before/after the period

Departure and arrival are evaluated per operating period:

  • departure = first significant DRIVE interval inside that operating period
  • arrival = end of the last significant DRIVE interval inside that operating period
  • middle/interruption = gaps between significant DRIVE intervals inside the same operating period

Result semantics

  • workResultPerDriver and workingOperationTimesPerEmployee currently use the same PoC summary for the whole requested period.
  • workingSeconds = DRIVE + WORK.
  • operationSeconds = DRIVE + WORK + AVAILABILITY.
  • breakRestSeconds is reported separately.
  • Top-level drivingTimeInterruptionEvaluation evaluates the whole requested period.
  • Each item in operatingTimePeriods has its own drivingTimeInterruptionEvaluation.

Current limitations

  • Uses the existing source-level driver_entity_id, not a canonical employee table.
  • Reads only tachograph driver-card activity events.
  • Does not merge VU/card duplication.
  • Does not persist results; the endpoint returns a PoC calculation response.
  • Esper is used for interval creation. Summary, clipping, operating-period split, and merged activity report calculation are implemented in Java for auditability and easier future migration to canonical events.