120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
# DHL Versandmodul - Entwicklungsdokumentation
|
|
|
|
## Projektübersicht
|
|
|
|
Laravel 11 DHL Versandmodul als eigenständiges Paket mit direkter DHL API-Integration.
|
|
|
|
## Architektur-Überarbeitungen ✅
|
|
|
|
**August 2025**: Wechsel von SDK-Ansatz zu eigenständigem Laravel-Paket
|
|
|
|
### Grund für Überarbeitung
|
|
|
|
- `christoph-schaeffer/dhl-business-shipping` SDK ist veraltet
|
|
- Probleme mit DHL-Login im alten SDK
|
|
- Bessere Kontrolle durch direkte API-Integration
|
|
|
|
### Neue Architektur
|
|
|
|
- **Eigenständiges Laravel-Paket**: `packages/acme-laravel-dhl`
|
|
- **Direkte DHL API**: HTTP-Client statt SDK-Wrapper
|
|
- **Vereinfachtes Schema**: Eine `dhl_package_shipments` Tabelle für Outbound/Returns
|
|
- **Moderne Laravel-Patterns**: Service Provider, Facades, Models
|
|
|
|
## Aktueller Entwicklungsstand ✅
|
|
|
|
### Phase 1: Paket-Grundlagen (ABGESCHLOSSEN)
|
|
|
|
- ✅ **Code Refactoring**: Services mit besserer Lesbarkeit
|
|
- ✅ **Datenbankschema**: Vereinfacht nach optimiertem Plan
|
|
- ✅ **Error Handling**: Umfassende Exception-Behandlung
|
|
- ✅ **Models**: DhlShipment + DhlTrackingEvent, inkl. Relationen
|
|
- ✅ **Services**: ShippingService, TrackingService, ReturnsService
|
|
- ✅ **HTTP-Client**: DhlClient mit Retry-Mechanismus
|
|
|
|
### Phase 2: Integration (ABGESCHLOSSEN)
|
|
|
|
- ✅ **Paket-Registration**: In Hauptprojekt eingebunden
|
|
- ✅ **API-Setup**: Credentials und Konfiguration
|
|
- ✅ **Admin-Controller**: Backend-Integration
|
|
- ✅ **Queue-Jobs**: Asynchrone Verarbeitung
|
|
|
|
### Phase 3: Admin-Interface (TEILWEISE ABGESCHLOSSEN)
|
|
|
|
- ✅ **DHL Cockpit**: Sendungsübersicht mit serverseitigem DataTables
|
|
- ✅ **Label-Management**: Download und Druck
|
|
- [ ] **Order-Integration**: DHL-Buttons in Bestellverwaltung
|
|
|
|
### Phase 4: Advanced Features (NÄCHSTE SCHRITTE)
|
|
|
|
- [ ] **Tracking-Automation**: Scheduler-Integration
|
|
- [ ] **Notifications**: E-Mail-Benachrichtigungen
|
|
- [ ] **Testing**: Unit/Feature Tests
|
|
- [ ] **Documentation**: Benutzerhandbuch
|
|
|
|
## Optimierungen und Änderungen (Letzte Updates)
|
|
|
|
- **Performance-Boost im Cockpit**: Die Sendungsübersicht wurde auf serverseitiges DataTables umgestellt, was die Ladezeiten bei großen Datenmengen drastisch reduziert.
|
|
- **Erweiterte Druckformate**: Das Modul unterstützt jetzt die Konfiguration von `print_format` und `retoure_print_format` via `.env` oder Admin-Einstellungen. Diese werden als Query-Parameter an die DHL API übergeben, um das physische Layout der Etiketten (z.B. A4, 910-300-700) zu steuern.
|
|
- **Speicherung des Routing-Codes**: Der `routing_code` (Leitcode) von DHL wird nun aus der API-Antwort extrahiert und in der Datenbank in der Spalte `dhl_package_shipments.routing_code` gespeichert.
|
|
- **API-Antwort-Parsing verbessert**: Die Logik wurde angepasst, um die Sendungsdaten korrekt aus dem `items`-Array der API-Antwort zu extrahieren.
|
|
- **Code optimiert**: Verbesserte Error-Handling, Logging in Services und Client.
|
|
- **Fehler behoben**: Namenskonflikte (Shipment -> DhlShipment), erweiterte Status-Mappings, robuste Validierungen.
|
|
- **Optionale Queues**: Konfiguriert via 'use_queue' in `config/dhl.php`. Synchron in Entwicklung, asynchron bei hoher Last.
|
|
|
|
## Dateistruktur
|
|
|
|
### Aktuelle Dokumentation
|
|
|
|
- `AKTUALISIERUNG-PAKET-ANSATZ.md` - Überarbeitungsdetails
|
|
- `PLAN-OPTIMIERT.md` - Ursprünglicher Plan (aktualisiert)
|
|
- `PAKET-INSTALLATION.md` - Setup-Anleitung
|
|
- `OPTIMIERUNGEN.md` - Details zu früheren Optimierungen
|
|
|
|
### Paket-Struktur
|
|
|
|
```
|
|
packages/acme-laravel-dhl/
|
|
├── config/dhl.php # Konfiguration
|
|
├── database/migrations/ # Datenbankstruktur
|
|
├── src/
|
|
│ ├── Services/ # Business Logic
|
|
│ ├── Models/ # Eloquent Models
|
|
│ ├── Support/ # HTTP Client
|
|
│ └── DhlServiceProvider.php # Laravel Integration
|
|
```
|
|
|
|
## Technische Highlights
|
|
|
|
### Moderne Laravel-Integration
|
|
|
|
- **PSR-4 Autoloading**: Sauberer Namespace
|
|
- **Service Provider**: Auto-Discovery Support
|
|
- **Facades**: `DHL::createLabel()` Syntax
|
|
- **Config Publishing**: `php artisan vendor:publish`
|
|
|
|
### Robuste API-Integration
|
|
|
|
- **Retry-Mechanismus**: 3 Versuche mit ansteigendem Delay
|
|
- **Timeout-Handling**: 30 Sekunden pro Request
|
|
- **HTTP-Status Mapping**: Spezifische Exceptions
|
|
- **Request/Response Logging**: Vollständige Nachverfolgung
|
|
- **Flexible API-Parameter**: Unterstützt Body-Payload und Query-Parameter bei POST-Requests.
|
|
|
|
### Optimiertes Datenbankschema
|
|
|
|
- **Eine Haupttabelle**: `dhl_package_shipments` für Outbound + Returns
|
|
- **Zusätzliche Felder**: `routing_code` für interne DHL-Logistik
|
|
- **Efficient Indexing**: Performance-optimiert
|
|
- **JSON-Felder**: Flexible API-Daten-Speicherung
|
|
- **Self-References**: Retour-Verknüpfungen
|
|
|
|
## Nächste Schritte
|
|
|
|
1. **Order-Integration** abschließen (Buttons in Bestelldetails).
|
|
2. **Tracking-Automatisierung** implementieren.
|
|
3. **Umfassende Tests** für die neuen Features schreiben.
|
|
|
|
---
|
|
|
|
**Status**: Admin-Cockpit implementiert und performant, Kernfunktionalität stabil.
|