Anforderung: Historische Betriebsstunden | Requirement: Historical Operating Hours

⚡ Ausgangslage & Ziel Current State & Goal

⚠ Ist-Zustand ⚠ Current State

Der Equipment-Domain-Service liefert bei einer Abfrage immer die aktuellen Betriebsstunden eines Geräts. Wenn ein Claim mit einem zurückliegenden Reparaturdatum erstellt wird, werden trotzdem die heutigen Betriebsstunden eingetragen — nicht die, die zum Zeitpunkt der Reparatur tatsächlich galten.

The Equipment Domain Service always returns the current operating hours of a device. When a claim is created with a past repair date, today's operating hours are stored instead of the hours that were actually valid at the time of the repair.

✓ Soll-Zustand ✓ Target State

Ein neuer Endpunkt (oder eine Erweiterung des bestehenden) liefert zu einer gegebenen Equipment-Nummer und einem Stichtag die damals gültigen Betriebsstunden — mit klar definierter Fallback-Logik je nach Gerätetyp.

A new endpoint (or extension of the existing one) returns the operating hours that were valid at a given reference date for a specific equipment number — with clearly defined fallback logic per device type.

📥 API – Request-Parameter API – Request Parameters

ParameterParameter	TypType	PflichtRequired	BeschreibungDescription
`equipmentNumber`	string	required	Eindeutige Equipment-Nummer des Geräts Unique equipment identifier
`referenceDate`	date	required	Stichtag = Reparaturdatum des Claims (z. B. `2026-03-01`) Reference date = repair date of the claim (e.g. `2026-03-01`)

🔎 Ermittlungslogik (in dieser Reihenfolge) Lookup Logic (in this order)

📡 Telematik-GerätTelematics Device

1

Telematik-Historienwert ≤ referenceDate vorhanden? Telematics history value ≤ referenceDate found?

→ Betriebsstunden aus Telematik-Historie zurückgeben → Return operating hours from telematics history

kein Telematik-Wert gefunden → Fallbackno telematics value found → fallback

2

Paldiag-Daten ≤ referenceDate vorhanden? Paldiag data ≤ referenceDate available?

→ Betriebsstunden aus Paldiag zurückgeben → Return operating hours from Paldiag

kein Paldiag-Wert gefunden → letzter Fallbackno Paldiag value found → final fallback

3

Weder Telematik-Historie noch Paldiag vorhanden Neither telematics history nor Paldiag available

→ Aktuelle Betriebsstunden zurückgeben (Prozess wird nicht blockiert) → Return current operating hours (claim process not blocked)

🔧 Nicht-Telematik-GerätNon-Telematics Device

1

Paldiag-Daten ≤ referenceDate vorhanden? Paldiag data ≤ referenceDate available?

→ Betriebsstunden aus Paldiag zurückgeben → Return operating hours from Paldiag

kein Paldiag-Wert gefunden → kein Fallbackno Paldiag value found → no fallback

2

Keine Paldiag-Daten vorhanden No Paldiag data available

→ Kein Wert zurückgeben → User trägt Betriebsstunden manuell ein → Return no value → user enters operating hours manually

Wichtig:Note: Bei Nicht-Telematik-Geräten gibt es keinen Fallback auf aktuelle Betriebsstunden. Das ist bewusst so gewählt, da die aktuellen Stunden für ein zurückliegendes Datum irreführend wären. For non-telematics devices there is no fallback to current operating hours. This is intentional, as the current hours would be misleading for a past repair date.

📤 API – Response (Beispiel) API – Response (Example)

{
  "operatingHours": 50,
  "source":         "telematics_history",  // telematics_history | paldiag | current
  "referenceDate":   "2026-03-01",          // requested reference date
  "actualDate":      "2026-02-28"           // date of the found history entry
}

FeldField	TypType	BeschreibungDescription
`operatingHours`	integer	Die ermittelten Betriebsstunden zum Stichtag Operating hours determined for the reference date
`source`	string	Herkunft des Werts — erlaubt dem Claim-Service, dem User einen entsprechenden Hinweis anzuzeigen Origin of the value — allows the Claim Service to show the user an appropriate hint
`referenceDate`	date	Der angefragte Stichtag (= übergebenes Reparaturdatum) The requested reference date (= submitted repair date)
`actualDate`	date	Das tatsächliche Datum des gefundenen Historieneintrags. Bei Fallback auf aktuelle Stunden = heute. The actual date of the found history entry. When falling back to current hours = today.

telematics_history — Wert aus Telematik-HistoriendatenValue from telematics history data

paldiag — Wert aus PaldiagValue from Paldiag

current — Aktueller Wert (letzter Fallback, nur Telematik)Current value (final fallback, telematics only)

null — Kein Wert (Nicht-Telematik ohne Paldiag)No value (non-telematics, no Paldiag data)

🔗 Integration auf unserer Seite (Claim Management) Our Integration (Claim Management)

Wir rufen diesen Endpunkt in unserem Claim-Management-Service auf, sobald ein Claim mit einem Reparaturdatum erstellt wird. We will call this endpoint in our Claim Management Service whenever a claim is created that includes a repair date.

📡 Telematik-GeräteTelematics Devices

Historische Betriebsstunden werden automatisch ermittelt.Historical operating hours are determined automatically.
Das source-Feld zeigt dem User, woher der Wert stammt.The source field informs the user about the value's origin.
Bei Fallback auf current: Hinweis im UI, dass es sich um aktuelle Stunden handelt.When falling back to current: UI notice that current hours are being used.

🔧 Nicht-Telematik-GeräteNon-Telematics Devices

Zuerst Versuch über Paldiag-Wert.First attempt via Paldiag lookup.
Wenn kein Wert vorhanden: User kann Betriebsstunden manuell eintragen.If no value is available: user can enter hours manually.
Manuell eingetragene Werte fließen in die Service-Historie ein.Manually entered values are written to the service history.