Einführung

Dieses Dokument beschreibt die verschiedenen Service-Typen im Werner-System und erklärt, wie client_service_role und address_service_provider verwendet werden, um Geschäftsprozesse zu steuern.

Das System verwendet Service-Typen, um zu bestimmen, welche Clients bestimmte Dienstleistungen erbringen können und welche Clients für bestimmte Adressen zuständig sind.

Service-Typen Übersicht

Das System definiert neun verschiedene Service-Typen (service_role), die verschiedene Dienstleistungsarten repräsentieren:

Diese Service-Typen werden in drei verschiedenen Kontexten verwendet:

1. client_service_role: Definiert, welche Services ein Client erbringen kann
2. address_service_provider: Definiert, welcher Client einen Service für eine bestimmte Adresse erbringt
3. job_tx_model: Definiert, welcher Service-Typ für eine bestimmte Job-Transaktion benötigt wird

client_service_role

Definition

Ein client_service_role ist eine Zuordnung zwischen einem Client und einem Service-Typ. Sie definiert, dass ein Client grundsätzlich in der Lage ist, einen bestimmten Service zu erbringen.

Datenbankstruktur

Die Tabelle client_service_role enthält:

• client_id: Referenz auf den Client
• service_role: Der Service-Typ, den der Client erbringen kann
• Eindeutige Constraint: Ein Client kann einen Service-Typ nur einmal haben

Wann ist client_service_role erforderlich?

1. Job-Erstellung (Fallback-Mechanismus)

Wenn ein Job erstellt wird, versucht das System zunächst, einen Client über address_service_provider zu finden. Falls keine adressspezifische Zuordnung existiert, wird client_service_role als Fallback verwendet.

Beispiel: Beim Erstellen eines Entsorgungsauftrags (drainage job):

• System prüft zuerst: Gibt es einen address_service_provider mit service_role = pump_out für diese Adresse?
• Falls nein: System prüft: Gibt es einen Client mit client_service_role = pump_out?
• Falls mehrere Clients gefunden werden: Fehler wird geworfen
• Falls kein Client gefunden wird: Fehler wird geworfen

2. Abwasserentsorgung (Leerpumpen) Validierung

Bei der Erstellung einer Abwasserentsorgung-Transaktion wird validiert, dass der angegebene Client tatsächlich die Rolle sewage_treatment_plant hat. Das System prüft automatisch, ob der Client einen client_service_role mit service_role = sewage_treatment_plant besitzt.

3. Stehende Aufträge (Standing Orders)

Bei der Erstellung von stehenden Aufträgen oder wiederkehrenden Entsorgungen wird client_service_role verwendet, wenn keine adressspezifische Zuordnung existiert.

Konfiguration

Ein client_service_role kann über die Oberfläche unter Master → Client Service Role erstellt werden:

1. Client auswählen
2. Service-Typ auswählen
3. Speichern

Ein Client kann mehrere Service-Typen haben (z.B. ein Client kann sowohl transport als auch recycle anbieten).

address_service_provider

Definition

Ein address_service_provider ist eine Zuordnung zwischen einer Adresse, einem Client und einem Service-Typ. Sie definiert, dass ein bestimmter Client einen bestimmten Service für eine bestimmte Adresse erbringt.

Datenbankstruktur

Die Tabelle address_service_provider enthält:

• address_id: Referenz auf die Adresse
• client_id: Referenz auf den Client, der den Service erbringt
• service_role: Der Service-Typ, der für diese Adresse erbracht wird
• Eindeutige Constraint: Eine Adresse kann für einen Service-Typ nur einen Client haben

Wann muss address_service_provider konfiguriert werden?

1. Job-Erstellung (Bevorzugte Methode)

Das System prüft zuerst address_service_provider, bevor es auf client_service_role zurückgreift. Dies ermöglicht adressspezifische Zuordnungen.

Auflösungslogik:

1. System prüft address_service_provider für die Adresse + benötigter service_role
2. Falls gefunden: Dieser Client wird verwendet
3. Falls nicht gefunden: System prüft client_service_role als Fallback

2. Einheiten-Journal Operationen (Unit Journal Operations)

Verschiedene Einheiten-Journal Operationen erfordern address_service_provider:

Container am Bauhof aufladen (pickup_unit_at_yard)

• Erforderlich: address_service_provider mit service_role = yard für den Client des Fahrzeugs
• Verwendung: Ermittelt die Werkhof-Adresse, von der eine Einheit abgeholt wird
• Das System sucht nach einer Werkhof-Adresse, die dem Client des Fahrzeugs zugeordnet ist

Container am Bauhof abstellen (dropoff_unit_at_yard)

• Erforderlich: address_service_provider mit service_role = yard für den Client des Fahrzeugs
• Verwendung: Ermittelt die Werkhof-Adresse, an die eine Einheit geliefert wird
• Das System sucht nach einer Werkhof-Adresse, die dem Client des Fahrzeugs zugeordnet ist

Container beim Entsorger entladen & wiegen (dropoff_unit_at_recycling_center)

• Erforderlich: address_service_provider mit service_role = recycle für den Recycling-Client
• Verwendung: Ermittelt die Entsorgungsadresse für den Recycling-Client
• Das System sucht nach einer Entsorgungsadresse, die dem Recycling-Client zugeordnet ist

3. Stehende Aufträge und Wiederkehrende Entsorgungen

Bei der Erstellung von stehenden Aufträgen oder wiederkehrenden Entsorgungen wird address_service_provider verwendet, um zu bestimmen, welcher Client den Service für die Adresse erbringt. Das System prüft zuerst, ob für die Adresse ein spezifischer Service-Provider konfiguriert ist, bevor es auf client_service_role zurückgreift.

4. View-Queries (vw_job_state)

Die View vw_job_state verwendet address_service_provider mit service_role = yard, um Werkhof-Adressen zu identifizieren. Dies wird für verschiedene Job-Status-Abfragen verwendet.

Verwendung: Identifizierung von Werkhof-Adressen in verschiedenen Job-Typen (inbound, outbound, sewage disposal, etc.)

Konfiguration

Ein address_service_provider kann über die Oberfläche unter Master → Address Service Provider erstellt werden:

1. Adresse auswählen
2. Client auswählen
3. Service-Typ auswählen
4. Speichern

Eine Adresse kann mehrere Service-Provider haben (z.B. eine Adresse kann sowohl einen pump_out als auch einen sewage_treatment_plant Provider haben).

Automatische Erstellung

address_service_provider Einträge können auch automatisch erstellt werden, z.B. durch Import-Jobs:

• kVASY Adressimport: Erstellt automatisch address_service_provider Einträge für neue Adressen mit den konfigurierten Service-Typen (sewage_treatment_plant, wastewater_association, pump_out)

Service-Role Auflösungslogik

Das System verwendet eine klare Hierarchie bei der Auflösung, welcher Client einen Service erbringt:

Auflösungsprozess

flowchart TD
    A[Job wird erstellt] --> B{Benötigter service_role aus job_tx_model}
    B --> C[Prüfe address_service_provider für Adresse + service_role]
    C --> D{Gefunden?}
    D -->|Ja| E[Verwende diesen Client]
    D -->|Nein| F[Prüfe client_service_role für service_role]
    F --> G{Gefunden?}
    G -->|Ja, genau einer| H[Verwende diesen Client]
    G -->|Ja, mehrere| I[Fehler: Client nicht eindeutig]
    G -->|Nein| J[Fehler: Kein Client gefunden]

Fehlerbehandlung

Das System wirft spezifische Fehler, wenn die Auflösung fehlschlägt:

1. 412_ADDRESS_DOES_NOT_YIELD_SERVICE_PROVIDER_AND_CLIENT_NOT_UNIQUE_BY_SERVICE_ROLE

   • Ursache: Keine address_service_provider gefunden, aber mehrere Clients mit client_service_role existieren
   • Lösung: Erstellen Sie einen address_service_provider für die Adresse, um die Zuordnung eindeutig zu machen

2. 412_ADDRESS_DOES_NOT_YIELD_SERVICE_PROVIDER_AND_NO_CLIENT_ASSIGNED_TO_SERVICE_ROLE

   • Ursache: Weder address_service_provider noch client_service_role gefunden
   • Lösung: Erstellen Sie entweder einen address_service_provider für die Adresse oder einen client_service_role für einen Client

Häufige Anwendungsfälle

1. Erstellen eines Abpumpauftrags (Abpumpen)

Erforderlich:

• address_service_provider mit service_role = pump_out ODER
• client_service_role mit service_role = pump_out

Beispiel:

• Adresse "Musterstraße 42" benötigt einen Abpumpauftrag
• System prüft: Gibt es einen address_service_provider für diese Adresse mit pump_out?
• Falls ja: Dieser Client wird verwendet
• Falls nein: System verwendet einen Client mit client_service_role = pump_out

2. Erstellen eines Abfalltransport-Auftrags (Kunde und Artikel zuweisen)

Erforderlich:

• address_service_provider mit service_role = recycle für den Recycling-Client

Beispiel:

• Ein Abfalltransport wird erstellt mit einem Recycling-Client
• System benötigt die Entsorgungsadresse für diesen Client
• System prüft: Gibt es einen address_service_provider mit diesem Client und service_role = recycle?
• Falls ja: Diese Adresse wird als Entsorgungsadresse verwendet
• Falls nein: Fehler wird geworfen

3. Erstellen eines Stehenden Auftrags (Standing Order)

Erforderlich:

• address_service_provider mit dem benötigten service_role ODER
• client_service_role mit dem benötigten service_role

Beispiel:

• Ein wiederkehrender Entsorgungsauftrag wird für Adresse "Hauptstraße 10" erstellt
• Der Job-Typ benötigt service_role = pump_out
• System prüft zuerst address_service_provider, dann client_service_role
• Der gefundene Client wird für alle Aufträge dieser Serie verwendet

4. Einheiten-Operationen (Unit Operations)

Erforderlich:

• address_service_provider mit service_role = yard für den Client des Fahrzeugs

Beispiel:

• Ein Fahrzeug mit client_id = 3 holt eine Einheit vom Werkhof ab
• System prüft: Gibt es einen address_service_provider mit client_id = 3 und service_role = yard?
• Falls ja: Diese Adresse wird als Abholadresse verwendet
• Falls nein: Fehler wird geworfen (404_CLIENT_IS_MISSING_YARD_ADDRESS)

5. Abwasserentsorgung (Leerpumpen)

Erforderlich:

• client_service_role mit service_role = sewage_treatment_plant für den angegebenen Client

Beispiel:

• Eine Abwasserentsorgung-Transaktion wird erstellt mit einem Klärwerk-Client
• Das System validiert automatisch: Hat dieser Client einen client_service_role mit service_role = sewage_treatment_plant?
• Falls nein: Fehler wird geworfen

Konfigurationsbeispiele

Beispiel 1: Client mit mehreren Service-Rollen einrichten

Ein Transportunternehmen bietet sowohl Transport- als auch Entsorgungsdienstleistungen an:

1. Navigieren Sie zu Master → Client
2. Erstellen Sie einen neuen Client oder öffnen Sie einen bestehenden
3. Navigieren Sie zu Master → Client Service Role
4. Erstellen Sie einen neuen Eintrag:
   • Wählen Sie den Client aus
   • Wählen Sie transport als Service-Typ
5. Erstellen Sie einen weiteren Eintrag:
   • Wählen Sie denselben Client aus
   • Wählen Sie recycle als Service-Typ

Der Client kann nun sowohl Transport- als auch Entsorgungsdienstleistungen erbringen.

Beispiel 2: Address Service Provider für eine Adresse einrichten

Eine Adresse benötigt einen spezifischen Entsorger:

1. Navigieren Sie zu Master → Address Service Provider
2. Klicken Sie auf New
3. Wählen Sie die Adresse aus
4. Wählen Sie den Client aus, der den Service erbringen soll
5. Wählen Sie pump_out als Service-Typ
6. Speichern Sie den Eintrag

Die Adresse hat nun einen spezifischen Entsorger zugeordnet.

Beispiel 3: Werkhof-Adresse für einen Client einrichten

Ein Client benötigt eine Werkhof-Adresse für Einheiten-Operationen:

1. Erstellen Sie zuerst eine neue Adresse unter Master → Address:
   • Name: z.B. "Werkhof Nord"
   • Adressdaten eingeben
2. Navigieren Sie zu Master → Address Service Provider
3. Klicken Sie auf New
4. Wählen Sie die Werkhof-Adresse aus
5. Wählen Sie den Client aus
6. Wählen Sie yard als Service-Typ
7. Speichern Sie den Eintrag

Der Client kann nun Einheiten-Operationen durchführen, die eine Werkhof-Adresse erfordern (z.B. Container am Bauhof aufladen oder Container am Bauhof abstellen).

Beispiel 4: Automatische Erstellung durch Import-Job

Der kVASY Adressimport erstellt automatisch address_service_provider Einträge für neue Adressen:

• Kläranlage (sewage_treatment_plant): Wenn sewage_treatment_plant/client/ident in den Config Tags konfiguriert ist
• Abwasserzweckverband (wastewater_association): Wenn wastewater_association/client/ident in den Config Tags konfiguriert ist
• Abpumpunternehmen (pump_out): Wenn pump_out/client/ident in den Config Tags konfiguriert ist

Diese werden automatisch erstellt, wenn eine neue Adresse importiert wird. Siehe auch die Dokumentation zum kVASY Adressimport.

Fehlerbehebung

"Address does not yield service provider and client not unique by service role"

Problem: Das System kann keinen eindeutigen Client für einen Service-Typ finden.

Ursachen:

• Keine address_service_provider für die Adresse vorhanden
• Mehrere Clients haben client_service_role für den benötigten Service-Typ

Lösung:

1. Navigieren Sie zu Master → Address Service Provider und erstellen Sie einen Eintrag für die Adresse mit dem benötigten Service-Typ
2. Oder entfernen Sie überflüssige client_service_role Einträge unter Master → Client Service Role, sodass nur ein Client den Service anbietet

"Address does not yield service provider and no client assigned to the service role"

Problem: Kein Client kann den benötigten Service erbringen.

Ursachen:

• Keine address_service_provider für die Adresse vorhanden
• Kein Client hat client_service_role für den benötigten Service-Typ

Lösung:

1. Navigieren Sie zu Master → Client Service Role und erstellen Sie einen Eintrag für einen Client mit dem benötigten Service-Typ
2. Oder erstellen Sie einen address_service_provider für die Adresse unter Master → Address Service Provider

"Client is missing yard address"

Problem: Ein Fahrzeug benötigt eine Werkhof-Adresse, aber keine wurde gefunden.

Ursachen:

• Der Client des Fahrzeugs hat keine address_service_provider mit service_role = yard

Lösung:

1. Erstellen Sie eine neue Adresse unter Master → Address (z.B. "Werkhof Nord")
2. Navigieren Sie zu Master → Address Service Provider
3. Erstellen Sie einen neuen Eintrag:
   • Wählen Sie die Werkhof-Adresse aus
   • Wählen Sie den Client des Fahrzeugs aus
   • Wählen Sie yard als Service-Typ

"Client hat keine sewage_treatment_plant Rolle"

Problem: Ein Client ohne sewage_treatment_plant Rolle wurde für eine Abwasserentsorgung (Leerpumpen) verwendet.

Ursachen:

• Der angegebene Client hat keinen client_service_role mit service_role = sewage_treatment_plant

Lösung:

1. Navigieren Sie zu Master → Client Service Role
2. Erstellen Sie einen neuen Eintrag für den Client mit service_role = sewage_treatment_plant
3. Oder verwenden Sie einen anderen Client, der diese Rolle bereits hat

Best Practices

1. Adressspezifische Zuordnungen bevorzugen: Verwenden Sie address_service_provider, wenn möglich, da dies flexibler und spezifischer ist.

2. Werkhof-Adressen für alle Clients: Stellen Sie sicher, dass jeder Client, der Einheiten-Operationen durchführt, eine Werkhof-Adresse hat.

3. Eindeutige Zuordnungen: Vermeiden Sie Situationen, in denen mehrere Clients denselben Service-Typ anbieten, ohne adressspezifische Zuordnungen zu haben.

4. Import-Jobs nutzen: Verwenden Sie Import-Jobs wie den kVASY Adressimport, um address_service_provider Einträge automatisch zu erstellen.

5. Validierung: Überprüfen Sie regelmäßig, ob alle benötigten address_service_provider und client_service_role Einträge vorhanden sind.