Kevin Adametz 70240d2b6a 13-05-2026 implementation FR

2026-05-13 17:33:52 +02:00

10 KiB

Raw Blame History

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.