95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```http
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|