190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# Entwicklungskonzept DHL Modul
|
|
|
|
Stand: 13.05.2026
|
|
|
|
## Ziel
|
|
|
|
Diese Datei ist die aktuelle Arbeitsgrundlage fuer die Weiterentwicklung des DHL Moduls. Die bisherigen Markdown-Dateien in diesem Ordner dokumentieren abgeschlossene oder ueberholte Zwischenstaende, insbesondere den frueheren SDK-Ansatz, Paketinstallation, SSL/cURL-Fixes und einzelne abgeschlossene Entwicklungsschritte.
|
|
|
|
Aktuelle Anforderungen kommen aus `docs/dhl/Anpassung DHL Modul.md`:
|
|
|
|
- Internationaler Versand ausserhalb Deutschlands, insbesondere Oesterreich und Spanien.
|
|
- Freies Feld fuer Sendungsreferenz oder interne Hinweise wie "Nachlieferung".
|
|
- Adressvalidierung vor Labelerstellung, damit fehlerhafte Labels und kostenpflichtige Stornos vermieden werden.
|
|
- Storno im DHL Cockpit pruefen und stabilisieren.
|
|
- Gewicht von Kompensationsprodukten in das DHL-Paketgewicht einrechnen.
|
|
- Tracking-Mails auf Rhythmus, Ausloeser und Mehrfachversand pruefen.
|
|
- Tracking-Codes in Admin, User-Portal und User-N-Portal sichtbar machen.
|
|
- Tracking-Mail-Versand nur bei Statusaenderung.
|
|
- DHL-Umstellung von `V62WP` Warenpost auf `V62KP` DHL Kleinpaket bis spaetestens 31.05.2026.
|
|
|
|
## Aktueller technischer Stand
|
|
|
|
Das produktive Modul basiert auf dem Paket `packages/acme-laravel-dhl` und verwendet die DHL REST API ueber `Acme\Dhl\Support\DhlClient`. Die zentrale Tabelle ist `dhl_package_shipments`.
|
|
|
|
Wichtige produktive Einstiegspunkte:
|
|
|
|
- `app/Http/Controllers/DhlShipmentController.php`
|
|
- `app/Services/DhlShipmentService.php`
|
|
- `app/Services/DhlModalService.php`
|
|
- `app/Services/DhlDataHelper.php`
|
|
- `app/Services/DhlTrackingService.php`
|
|
- `packages/acme-laravel-dhl/src/Services/ShippingService.php`
|
|
- `packages/acme-laravel-dhl/src/Services/ReturnsService.php`
|
|
- `packages/acme-laravel-dhl/src/Models/DhlShipment.php`
|
|
- `config/dhl.php`
|
|
|
|
Historische Dokumente erwaehnen teilweise alte Strukturen wie `App\Models\DhlShipment`, `dhl_shipments` oder einen konsolidierten `DhlApiService`. Diese Angaben sind nicht mehr massgeblich, ausser sie werden explizit in aktuellem Code noch referenziert. Aktuell gibt es genau dort noch Altlasten, die bereinigt werden muessen.
|
|
|
|
## Offensichtliche Befunde
|
|
|
|
### 1. Produktkuerzel `V62WP` ist veraltet
|
|
|
|
`V62WP` ist weiterhin in Konfiguration, Admin-Settings, Validierung, Produktauswahl und Sprachdateien vorhanden. DHL verlangt die Umstellung auf `V62KP`.
|
|
|
|
Betroffene Stellen:
|
|
|
|
- `config/dhl.php`
|
|
- `app/Http/Controllers/SettingController.php`
|
|
- `app/Services/DhlModalService.php`
|
|
- `packages/acme-laravel-dhl/src/Services/ShippingService.php`
|
|
- `resources/lang/*/dhl.php`
|
|
|
|
Risiko: Kleinpaket/Warenpost-Labels koennen nach der DHL-Frist abgelehnt werden.
|
|
|
|
### 2. Async Tracking verwendet veraltetes Model
|
|
|
|
`app/Jobs/TrackShipmentJob.php` importiert `App\Models\DhlShipment`, dieses Model existiert im aktuellen System nicht mehr. Die produktive DHL-Integration verwendet `Acme\Dhl\Models\DhlShipment`.
|
|
|
|
Risiko: Asynchrones Tracking bricht zur Laufzeit, sobald Queue-Tracking genutzt wird.
|
|
|
|
### 3. Statuswerte fuer Storno sind inkonsistent
|
|
|
|
Im Paket wird bei erfolgreichem Storno `canceled` gesetzt. Andere Stellen, Uebersetzungen und historische Dokumente verwenden `cancelled`.
|
|
|
|
Risiko: Filter, Badges, Terminal-Status, Uebersetzungen und Storno-Buttons verhalten sich uneinheitlich.
|
|
|
|
### 4. Storno ist technisch vorhanden, aber nicht robust genug
|
|
|
|
Storno laeuft ueber `DELETE /parcel/de/shipping/v2/orders/{shipmentNumber}`. Der Code prueft `canCancel()`, speichert aber Fehler nur begrenzt fachlich verwertbar. Produktspezifische Einschraenkungen wie Warenpost/Kleinpaket sind nicht sauber modelliert.
|
|
|
|
Risiko: Anwender sehen generische Fehler und koennen nicht erkennen, ob ein Storno produktbedingt, statusbedingt, API-bedingt oder wegen Sandbox/Production-Mismatch scheitert.
|
|
|
|
### 5. Internationaler Versand ist nur teilweise vorbereitet
|
|
|
|
`V53PAK` ist als internationales Produkt vorhanden, und einige Laender werden in 3-stellige ISO-Codes konvertiert. Dennoch gibt es keinen zentralen Produktentscheid je Zielland, keine harte Validierung nicht unterstuetzter Laender und einen gefaehrlichen Fallback auf `DEU`.
|
|
|
|
Risiko: Sendungen nach Oesterreich, Spanien oder weitere Laender koennen falsche Produktcodes, falsche Abrechnungsnummern oder falsche Laendercodes erhalten.
|
|
|
|
### 6. Adressvalidierung ist nur formal
|
|
|
|
Aktuell prueft das Modul Pflichtfelder, Hausnummern und einfache PLZ-Regeln. Eine echte Pruefung, ob Strasse, PLZ und Ort postalisch existieren, findet nicht statt.
|
|
|
|
Empfohlene Loesung: DHL/Post & DHL `DATAFACTORY AUTOCOMPLETE 2.0` fuer DE/AT/CH pruefen und integrieren. Alternativen fuer breiteren Laenderumfang: Loqate, Google Address Validation oder HERE. Wichtig ist eine harte Sperre bei nicht versandfaehigen Adressen vor Labelerstellung.
|
|
|
|
### 7. Referenzfeld ist API-seitig vorhanden, aber nicht im Cockpit nutzbar
|
|
|
|
`ShippingService` kann `reference` nach `refNo` mappen. `DhlDataHelper` setzt aktuell automatisch `Order-{id}`.
|
|
|
|
Risiko: Admins koennen Hinweise wie "Nachlieferung" nicht strukturiert am Label/API-Auftrag hinterlegen.
|
|
|
|
### 8. Gewicht von Kompensationsprodukten fehlt
|
|
|
|
Kompensationsprodukte werden im Warenkorb mit Gewicht `0` abgelegt, damit die Kompensationslogik nicht beeinflusst wird. Das DHL-Gewicht kommt aus `ShoppingOrder->weight` und enthaelt dieses Produktgewicht dadurch nicht.
|
|
|
|
Risiko: DHL-Label wird mit zu geringem Paketgewicht erstellt.
|
|
|
|
### 9. Tracking-Mail-Logik ist grundsaetzlich brauchbar, muss aber abgesichert werden
|
|
|
|
Der Scheduler ruft stuendlich `dhl:update-tracking --days=30 --send-emails` auf. Statusabhaengige Intervalle verhindern zu viele API-Calls. Automatische Mails werden nur gesendet, wenn eine Sendung neu auf `in_transit` wechselt und noch keine Mail markiert wurde.
|
|
|
|
Risiko: Statusspruenge direkt auf `out_for_delivery` oder besondere DHL-Statuscodes koennen ohne Mail bleiben. Mehrere Sendungen einer Bestellung werden teils zusammengefasst, aber die fachliche Regel muss final bestaetigt werden.
|
|
|
|
## Entwicklungskonzept
|
|
|
|
### Phase 1: Pflichtkorrekturen vor DHL-Frist
|
|
|
|
1. `V62WP` vollstaendig auf `V62KP` migrieren.
|
|
2. Neue Konfigurationskeys fuer `DHL_ACCOUNT_NUMBER_V62KP`, Admin-Setting `dhl_account_v62kp`, Dimensionen und Uebersetzungen einfuehren.
|
|
3. `ShippingService` Validierung um `V62KP` erweitern und `V62WP` entfernen oder nur noch als Legacy-Mapping fuer Altdaten anzeigen.
|
|
4. Bestehende Sendungen mit `V62WP` historisch lesbar lassen, aber neue Labelerstellung blockieren.
|
|
5. Tests fuer Produktcode-Auswahl, Validierung und Payload-Erstellung schreiben.
|
|
|
|
### Phase 2: Stabilisierung von Tracking und Storno
|
|
|
|
1. `TrackShipmentJob` auf aktuelles Model und aktuellen `DhlTrackingService` umstellen.
|
|
2. Statuswerte vereinheitlichen. Empfehlung: intern `canceled` verwenden, Uebersetzung auf Deutsch "Storniert".
|
|
3. `TERMINAL_STATUSES`, Badges, Filter und Sprachdateien entsprechend angleichen.
|
|
4. Storno-Fehler strukturiert speichern: HTTP-Status, DHL-Fehlercode, DHL-Detailtext, Zeitpunkt.
|
|
5. Admin-Feedback verbessern: nicht stornierbar wegen Status, Produkt, API-Antwort oder nicht auffindbarer DHL-Sendung.
|
|
6. Tests fuer erfolgreiche Stornierung, bereits stornierte Sendung, nicht stornierbare Sendung und API-Fehler.
|
|
|
|
### Phase 3: Internationalisierung Versand
|
|
|
|
1. Zentralen Service fuer Produkt-/Billing-Entscheidung einfuehren, z. B. `DhlProductResolver`.
|
|
2. Zielland, Produktcode, Abrechnungsnummer und erlaubte Services dort validieren.
|
|
3. Regeln initial:
|
|
- `DE`: `V01PAK` oder `V62KP`
|
|
- `AT`, `ES` und weitere aktivierte Laender: `V53PAK`
|
|
4. Fallback auf `DEU` entfernen. Unbekannte Laender muessen mit klarer Fehlermeldung abbrechen.
|
|
5. Cockpit-Formular: Produkt anhand Zielland vorschlagen, aber Admin-Korrektur erlauben.
|
|
|
|
### Phase 4: Adressvalidierung vor Labelerstellung
|
|
|
|
1. Neuen serverseitigen Validierungsendpunkt fuer DHL-Adressen schaffen.
|
|
2. Basisvalidierung behalten: Pflichtfelder, Land, PLZ-Format, Hausnummer, Packstation/Postnummer.
|
|
3. DHL DATAFACTORY AUTOCOMPLETE 2.0 fuer DE/AT/CH evaluieren.
|
|
4. Falls DHL fuer alle benoetigten Laender nicht ausreicht, externen Provider evaluieren.
|
|
5. UI-Status einfuehren:
|
|
- gueltig: Labelerstellung erlaubt
|
|
- Warnung: Admin kann bewusst fortfahren
|
|
- Fehler: Labelerstellung gesperrt
|
|
6. Validierungsergebnis optional am Shipment/Order protokollieren.
|
|
|
|
### Phase 5: Referenzfeld und Admin-UX
|
|
|
|
1. Neues Formularfeld `reference` oder `shipment_reference` im DHL Cockpit.
|
|
2. Wert an `DhlDataHelper::prepareOrderData()` uebergeben.
|
|
3. `ShippingService` nutzt vorhandenes Mapping nach `refNo`.
|
|
4. Referenz im Shipment speichern, damit spaeter nachvollziehbar ist, warum eine Sendung erstellt wurde.
|
|
5. Laengenlimit der DHL API beachten, aktuell maximal 35 Zeichen.
|
|
|
|
### Phase 6: DHL-Gewicht korrekt berechnen
|
|
|
|
1. Separaten Gewichtsdienst fuer DHL einfuehren, z. B. `DhlShipmentWeightCalculator`.
|
|
2. Basis: `ShoppingOrder->weight`.
|
|
3. Fuer `shopping_order_items` mit `comp > 0` das Produktgewicht aus `Product->weight` nachladen und addieren.
|
|
4. Nur DHL-Gewicht anpassen, nicht die bestehende Warenkorb-/Versandkostenlogik.
|
|
5. Rundung und DHL-Grenzwerte je Produkt testen.
|
|
|
|
### Phase 7: Tracking-Codes und Mails fachlich finalisieren
|
|
|
|
1. Bestehende Admin-Anzeige pruefen und bei Bedarf vereinheitlichen.
|
|
2. Tracking-Code-Anzeige in User-Portal und User-N-Portal ergaenzen.
|
|
3. Mail-Regel final definieren:
|
|
- automatisch nur einmal pro Sendung
|
|
- nur bei relevanter Statusaenderung
|
|
- mehrere Sendungen einer Bestellung sinnvoll zusammenfassen
|
|
4. Statusspruenge wie `created` direkt nach `out_for_delivery` abdecken.
|
|
5. Command `dhl:update-tracking` Tests fuer Mailausloeser und Nicht-Ausloeser ergaenzen.
|
|
|
|
## Empfohlene Reihenfolge
|
|
|
|
1. `V62WP` -> `V62KP`, Statuswerte und `TrackShipmentJob` korrigieren.
|
|
2. Storno stabilisieren und bessere Fehlermeldungen im Cockpit anzeigen.
|
|
3. Internationalen Produktresolver einbauen.
|
|
4. Referenzfeld und Gewichtskorrektur umsetzen.
|
|
5. Adressvalidierung integrieren.
|
|
6. Tracking-Anzeigen und Mailregeln final testen.
|
|
|
|
## Teststrategie
|
|
|
|
- Feature-Tests fuer Controller-Endpunkte: Label erstellen, Storno, Tracking-Mail, Tracking-Update.
|
|
- Unit-Tests fuer Produktresolver, Gewichtskalkulation und Adressvalidierung.
|
|
- HTTP-Fakes fuer DHL API Responses inklusive Fehlerfaelle.
|
|
- Regression-Test fuer `V62KP` Payload.
|
|
- Command-Test fuer `dhl:update-tracking --send-emails`.
|
|
|
|
## Legacy-Dokumentation
|
|
|
|
Die bisherigen Markdown-Dateien wurden nach `dev/dhl-modul/legacy` verschoben. Sie bleiben als Historie erhalten, sind aber nicht mehr die aktuelle Arbeitsgrundlage.
|