DHL Modul v0.5 Shipping Label ok

dev/dhl-modul/AKTUALISIERUNG-PAKET-ANSATZ.md

@@ -0,0 +1,151 @@
+# DHL Modul - Aktualisierung auf Paket-Ansatz
+
+## Überarbeitung: Von SDK zu eigenständigem Laravel-Paket
+
+**Datum**: $(date '+%Y-%m-%d')  
+**Grund**: Das christoph-schaeffer/dhl-business-shipping SDK ist veraltet und macht Probleme mit DHL-Login
+
+## Neue Architektur: packages/acme-laravel-dhl
+
+### ✅ Durchgeführte Überarbeitungen
+
+#### 1. Code Refactoring für bessere Lesbarkeit
+- **Services vollständig überarbeitet**:
+  - `ShippingService` - Versandlabel-Erstellung mit klarer Struktur
+  - `TrackingService` - Tracking-Status mit Bulk-Updates  
+  - `ReturnsService` - Retourenlabel-Management
+  - `DhlClient` - HTTP-Client mit umfassendem Error-Handling
+
+- **Verbesserungen**:
+  - Vollständige PHPDoc-Dokumentation
+  - Typisierung aller Parameter und Rückgabewerte
+  - Private Methoden für bessere Code-Organisation
+  - Validierung aller Eingabedaten
+  - Exception-Handling mit aussagekräftigen Fehlermeldungen
+
+#### 2. Datenbankschema an optimierten Plan angepasst
+- **Vereinfachtes Schema** entsprechend PLAN-OPTIMIERT.md:
+  - Eine zentrale `dhl_shipments` Tabelle
+  - `type` Spalte für Outbound/Return-Unterscheidung  
+  - `related_shipment_id` für Retour-Verknüpfung
+  - Tracking-Status direkt in Haupttabelle
+
+- **Migration erstellt**:
+  - `/database/migrations/2025_01_01_000000_create_dhl_shipments_table.php`
+  - `/database/migrations/2025_01_01_000200_create_dhl_tracking_events_table.php`
+
+- **Neue Models**:
+  - `DhlShipment` - Hauptmodel mit Relationships und Scopes
+  - `DhlTrackingEvent` - Tracking-Events für Phase 2
+
+#### 3. Error Handling und Validation implementiert
+- **DhlClient mit robustem Error-Handling**:
+  - HTTP-Status-Code spezifische Exceptions
+  - Retry-Mechanismus (3 Versuche)
+  - Timeout-Handling (30 Sekunden)
+  - User-Agent für API-Identifikation
+
+- **Service-Validierung**:
+  - Eingabedaten-Validierung vor API-Aufrufen
+  - Konfigurationsprüfung (Billing Number, etc.)
+  - Aussagekräftige Exception-Messages
+
+### 🗂️ Neue Paket-Struktur
+
+```
+packages/acme-laravel-dhl/
+├── composer.json                 # Laravel-Paket Konfiguration
+├── config/dhl.php               # DHL API Konfiguration
+├── database/migrations/         # Datenbank-Struktur
+│   ├── 2025_01_01_000000_create_dhl_shipments_table.php
+│   └── 2025_01_01_000200_create_dhl_tracking_events_table.php
+├── src/
+│   ├── DhlServiceProvider.php   # Laravel Service Provider
+│   ├── DhlManager.php           # Hauptmanager-Klasse
+│   ├── Facades/DHL.php          # Laravel Facade
+│   ├── Models/
+│   │   ├── DhlShipment.php      # Zentrales Shipment-Model
+│   │   └── DhlTrackingEvent.php # Tracking-Events
+│   ├── Services/
+│   │   ├── ShippingService.php  # Versandlabel-Service
+│   │   ├── TrackingService.php  # Tracking-Service
+│   │   └── ReturnsService.php   # Retour-Service
+│   ├── Support/
+│   │   └── DhlClient.php        # HTTP-API-Client
+│   └── Http/Controllers/        # Für spätere Web-Integration
+└── routes/api.php               # API-Routen für Webhooks
+```
+
+### 📋 Aktualisierter Implementierungsplan
+
+#### Phase 1: Paket-Integration (2 Schritte)
+1. **Paket-Registrierung im Hauptprojekt**
+   - composer.json Repositories-Eintrag
+   - Service Provider Registration
+   - Konfiguration publizieren
+
+2. **API-Credentials Setup**  
+   - .env Variablen konfigurieren
+   - Test-Verbindung zur DHL API
+
+#### Phase 2: Admin-Integration (4 Schritte)  
+3. **Admin-Controller erstellen**
+   - DhlShipmentController für Backend
+   - Integration in bestehende Order-Verwaltung
+
+4. **Blade-Views für DHL Cockpit**
+   - Sendungsübersicht mit DataTables
+   - Label-Download und -Druck
+
+5. **Queue-Jobs für Async-Processing**
+   - CreateShipmentJob
+   - CancelShipmentJob
+   - CreateReturnLabelJob
+
+6. **Tracking-Automation**
+   - UpdateTrackingStatusJob
+   - Artisan Command für Scheduler
+
+#### Phase 3: Testing & Finalisierung (2 Schritte)
+7. **Unit/Feature Tests**
+   - Service-Tests mit Mocked API
+   - Controller-Tests
+   - Database-Tests
+
+8. **Documentation & Polish**  
+   - Benutzerhandbuch
+   - API-Dokumentation
+   - Performance-Optimierung
+
+### ⚠️ Breaking Changes zum alten Ansatz
+
+1. **Namespace geändert**: `App\Services\DhlApiService` → `Acme\Dhl\Services\*`
+2. **Datenbank**: `dhl_shipments` statt mehrerer separater Tabellen
+3. **Model**: `DhlShipment` statt `DhlShipment` (ähnlich, aber neue Struktur)
+4. **API-Integration**: Direkter HTTP-Client statt SDK-Wrapper
+
+### 🔧 Migration vom alten System
+
+Falls bereits bestehende DHL-Integration vorhanden:
+1. Bestehende Daten nach `dhl_shipments` migrieren
+2. Controller-Aufrufe auf neue Services umstellen
+3. View-Integrationen aktualisieren
+
+### 📦 Vorteile des Paket-Ansatzes
+
+- **Unabhängigkeit**: Keine Abhängigkeit von veralteten SDKs
+- **Wartbarkeit**: Sauberer, dokumentierter Code
+- **Flexibilität**: Direkter API-Zugang ermöglicht alle DHL-Features
+- **Testbarkeit**: Vollständig mockbare Services
+- **Laravel-Integration**: Native Laravel-Patterns und Features
+- **Wiederverwendbarkeit**: Als eigenständiges Paket nutzbar
+
+### 🎯 Nächste Schritte
+
+1. **Paket im Hauptprojekt registrieren**
+2. **DHL API-Credentials konfigurieren**  
+3. **Erste Testlabel erstellen**
+4. **Admin-Interface implementieren**
+5. **Bestehende Order-Integration anpassen**
+
+Das überarbeitete System ist nun deutlich stabiler, wartbarer und zukunftssicher.

dev/dhl-modul/OPTIMIERUNGEN.md

@@ -0,0 +1,33 @@
+# Optimierungen am DHL-Modul
+
+## Code-Verbesserungen
+
+- Erweiterte Logging in allen Services und DhlClient.
+- Robuste Payload-Extraktion mit data_get().
+- Exponential Backoff für Rate-Limits in DhlClient.
+
+## Behebene Fehler
+
+- Namenskonflikt: Shipment zu DhlShipment geändert.
+- Erweiterte Status-Updates in Webhook und TrackingService (mehr Codes gemappt).
+- Validierung in cancelLabel: Prüft Existenz und canCancel().
+
+## Optionale Queues
+
+- Neu in config: 'use_queue' => false (Standard: synchron).
+- In Services: Wenn true, dispatch Job (z.B. SyncTrackingJob); sonst synchron.
+- Für Entwicklung/Erstrollout: Synchron. Bei höherer Last: Aktivieren für Asynchronität.
+
+## Weitere Dokumentation
+
+- Aktualisierte README.md und PAKET-INSTALLATION.md mit Queue-Infos.
+
+## Weitere Fixes
+
+- DhlClient: Sleep zu usleep geändert mit Cap auf 10 Sekunden.
+- ShippingService: HouseNumber required for DHL!, Retry für Storage::put.
+- TrackingService: Transaction um firstOrCreate.
+- Migration: Kommentar zur anonymen Klasse.
+- Status-Mappings: Zentral in DhlShipment, referenziert in TrackingService.
+- DhlManager: Descriptive Variablen, Typ-Hints.
+- Storage-Retry: 3 Versuche mit Logging in ShippingService.

dev/dhl-modul/PAKET-INSTALLATION.md

@@ -0,0 +1,257 @@
+# DHL Paket Installation & Setup
+
+## 1. Paket im Hauptprojekt registrieren
+
+### composer.json erweitern
+
+```json
+{
+  "repositories": [
+    {
+      "type": "path",
+      "url": "./packages/acme-laravel-dhl"
+    }
+  ],
+  "require": {
+    "acme/laravel-dhl": "*"
+  }
+}
+```
+
+### Installation
+
+```bash
+composer update acme/laravel-dhl
+```
+
+## 2. Service Provider registrieren
+
+### config/app.php (falls Auto-Discovery nicht funktioniert)
+
+```php
+'providers' => [
+    // ...
+    Acme\Dhl\DhlServiceProvider::class,
+],
+
+'aliases' => [
+    // ...
+    'DHL' => Acme\Dhl\Facades\DHL::class,
+],
+```
+
+## 3. Konfiguration publizieren
+
+```bash
+# Konfigurationsdatei publizieren
+php artisan vendor:publish --provider="Acme\Dhl\DhlServiceProvider" --tag="config"
+
+# Migrations ausführen
+php artisan migrate
+```
+
+## 4. Umgebungsvariablen konfigurieren
+
+### .env erweitern
+
+```env
+# DHL API Configuration
+DHL_BASE_URL=https://api-eu.dhl.com
+DHL_API_KEY=your_api_key_here
+DHL_USERNAME=your_username
+DHL_PASSWORD=your_password
+DHL_BILLING_NUMBER=your_billing_number
+
+# DHL Default Settings
+DHL_PRODUCT=V01PAK
+DHL_LABEL_FORMAT=PDF
+DHL_PRINT_FORMAT=A4
+DHL_RETOURE_PRINT_FORMAT=A4
+DHL_PROFILE=STANDARD_GRUPPENPROFIL
+
+# DHL Webhook (optional)
+DHL_WEBHOOK_ENABLED=false
+DHL_WEBHOOK_SECRET=your_webhook_secret
+DHL_WEBHOOK_ROUTE=dhl/webhooks/tracking
+
+# DHL Queue Settings (optional)
+DHL_USE_QUEUE=false
+```
+
+## 5. Test-Verbindung prüfen
+
+### Artisan Command (zu erstellen)
+
+```bash
+php artisan dhl:test-connection
+```
+
+### Oder via Tinker
+
+```php
+php artisan tinker
+
+// Service-Container Test
+app(Acme\Dhl\Services\ShippingService::class);
+
+// Model Test
+use Acme\Dhl\Models\DhlShipment;
+DhlShipment::query()->count();
+
+// API-Test (vereinfacht)
+// $client = app(Acme\Dhl\Support\DhlClient::class);
+// $client->testConnection();
+```
+
+## 6. Integration in bestehende Models
+
+### ShoppingOrder Model erweitern
+
+```php
+use Acme\Dhl\Models\DhlShipment;
+
+class ShoppingOrder extends Model
+{
+    /**
+     * DHL Sendungen für diese Bestellung
+     */
+    public function dhlShipments(): HasMany
+    {
+        return $this->hasMany(DhlShipment::class, 'order_id');
+    }
+
+    /**
+     * Ausgehende DHL Sendungen
+     */
+    public function dhlOutboundShipments(): HasMany
+    {
+        return $this->dhlShipments()->outbound();
+    }
+
+    /**
+     * DHL Retouren
+     */
+    public function dhlReturns(): HasMany
+    {
+        return $this->dhlShipments()->returns();
+    }
+
+    /**
+     * Hat DHL Sendungen
+     */
+    public function hasDhlShipments(): bool
+    {
+        return $this->dhlShipments()->exists();
+    }
+
+    /**
+     * Neueste DHL Sendung
+     */
+    public function latestDhlShipment(): ?DhlShipment
+    {
+        return $this->dhlShipments()
+            ->latest()
+            ->first();
+    }
+}
+```
+
+## 7. Verwendung in Controllern
+
+### Beispiel Controller-Integration
+
+```php
+use Acme\Dhl\Services\ShippingService;
+use Acme\Dhl\Services\TrackingService;
+use Acme\Dhl\Services\ReturnsService;
+
+class OrderController extends Controller
+{
+    public function createDhlLabel(
+        ShoppingOrder $order,
+        ShippingService $shippingService
+    ) {
+        try {
+            $result = $shippingService->createLabel([
+                'order_id' => $order->id,
+                'shipper' => [
+                    'name' => 'Ihre Firma',
+                    'street' => 'Ihre Straße 123',
+                    'postalCode' => '12345',
+                    'city' => 'Ihre Stadt',
+                    'country' => 'DE'
+                ],
+                'consignee' => [
+                    'name' => $order->shipping_name,
+                    'street' => $order->shipping_street,
+                    'postalCode' => $order->shipping_zip,
+                    'city' => $order->shipping_city,
+                    'country' => $order->shipping_country
+                ],
+                'weight_kg' => $order->total_weight ?? 1.0
+            ]);
+
+            return response()->json([
+                'success' => true,
+                'shipment_number' => $result['shipmentNumber'],
+                'label_path' => $result['label_path']
+            ]);
+
+        } catch (Exception $e) {
+            return response()->json([
+                'success' => false,
+                'error' => $e->getMessage()
+            ], 422);
+        }
+    }
+}
+```
+
+## 8. Facade-Verwendung
+
+```php
+use DHL;
+
+// Label erstellen
+$result = DHL::createLabel($orderData);
+
+// Tracking-Status abrufen
+$status = DHL::getTrackingStatus('1234567890');
+
+// Retourenlabel erstellen
+$return = DHL::createReturn($returnData);
+```
+
+## Troubleshooting
+
+### Composer-Probleme
+
+```bash
+# Cache leeren
+composer dump-autoload
+php artisan config:clear
+php artisan cache:clear
+
+# Paket neu installieren
+composer remove acme/laravel-dhl
+composer install
+```
+
+### Migration-Probleme
+
+```bash
+# Migrations-Status prüfen
+php artisan migrate:status
+
+# Rollback und neu migrieren
+php artisan migrate:rollback --step=2
+php artisan migrate
+```
+
+### Service-Provider nicht gefunden
+
+```bash
+# Auto-Discovery cache leeren
+composer dump-autoload
+php artisan package:discover
+```

dev/dhl-modul/PLAN-OPTIMIERT.md

@@ -0,0 +1,195 @@
+# DHL Versandmodul - Optimierter Programmierplan (MVP)
+
+## Bewertung der Optimierungsvorschläge
+
+### ✅ Akzeptierte Optimierungen:
+
+1. **Vereinfachtes Datenbank-Schema**: Eine `dhl_shipments` Tabelle mit `type` Spalte für Outbound/Return
+2. **Tracking vereinfacht**: Aktueller Status in Haupttabelle, separate Events-Tabelle für Phase 2
+3. **Konsolidierte Service-Klasse**: Ein `DhlApiService` statt drei separate Services
+4. **Advanced Features verschoben**: Excel Export, Webhooks, Notifications als Phase 2
+
+### 🔄 Kleine Anpassungen am Vorschlag:
+
+- Jobs bleiben getrennt (CreateShipment, Cancel, ReturnLabel) für bessere Queue-Verwaltung
+- Tracking-Job für Scheduler-Integration beibehalten
+- Admin-Navigation früher implementieren für bessere UX
+
+---
+
+# Finaler Optimierter Plan - DHL Modul (MVP)
+
+## Phase 1: Fundament und Kernlogik (8 Schritte)
+
+### 1. Setup & Dependencies ✅ AKTUALISIERT
+
+- ~~Composer: `dhl-sdk-api-php/dhl-sdk-bcs` installieren~~ (veraltet, Probleme mit DHL-Login)
+- **NEUER ANSATZ**: Eigenständiges Laravel-Paket `packages/acme-laravel-dhl`
+- Direkte DHL API-Integration über HTTP-Client (Guzzle)
+- Queue-System aktivieren (database driver)
+
+### 2. Konfiguration
+
+- `config/dhl.php` erstellen (API-Credentials, Absenderadressen)
+- Environment-Variablen in `.env` definieren
+
+### 3. Datenbank & Model ✅ ABGESCHLOSSEN
+
+- Migration für `dhl_shipments` Tabelle: ✅
+  - order_id, dhl_shipment_no, type (outbound/return)
+  - related_shipment_id (für Retouren), weight_kg, label_path
+  - status, tracking_status, last_tracked_at
+  - api_response_data (JSON), created_at, updated_at
+- `DhlShipment` Model mit vollständigen Relationships ✅
+- `DhlTrackingEvent` Model für detaillierte Events ✅
+
+### 4. Zentraler Service ✅ ABGESCHLOSSEN
+
+- ~~`DhlApiService` als Wrapper um DHL SDK~~ (SDK-Ansatz verworfen)
+- **NEUE STRUKTUR**:
+  - `DhlClient` - HTTP-Client für API-Kommunikation ✅
+  - `ShippingService` - Label-Erstellung und -Verwaltung ✅
+  - `TrackingService` - Status-Tracking und -Updates ✅  
+  - `ReturnsService` - Retourenlabel-Management ✅
+- Vollständige Error-Behandlung und Validation ✅
+
+### 5. Queue Jobs
+
+- `CreateShipmentJob` für asynchrone Label-Erstellung
+- `CancelShipmentJob` für Stornierungen
+- `CreateReturnLabelJob` für Retourenetiketten
+
+### 6. Controller Foundation
+
+- `DhlShipmentController` mit store/show/cancel Methoden
+- Basis-Routen in `routes/web.php`
+
+### 7. Error Handling & Logging ✅ ABGESCHLOSSEN
+
+- Exception-Handling für DHL API-Fehler ✅
+  - HTTP-Status spezifische Exceptions
+  - Retry-Mechanismus (3x mit 300ms Delay)
+  - Timeout-Handling (30s)
+- Aussagekräftige Fehlermeldungen ✅
+- Validation aller Eingabedaten ✅
+
+### 8. Basic Testing
+
+- Unit-Tests für `DhlApiService`
+- Feature-Tests für Controller
+
+---
+
+## Phase 2: Admin-Oberfläche (6 Schritte)
+
+### 9. Navigation & Layout
+
+- Admin-Menüpunkt "DHL Cockpit"
+- Bootstrap 5 Layout für DHL-Views
+
+### 10. Cockpit (Zentrale Übersicht)
+
+- `index()` Methode im Controller
+- `cockpit.blade.php` View mit DataTable
+- Filter: Datum, Status, Sendungstyp
+
+### 11. Einzelaktionen
+
+- "Label herunterladen" Button
+- "Sendung stornieren" Button mit Confirmation
+
+### 12. Batch-Operationen
+
+- Mehrere Sendungen auswählen
+- Stapeldruck von Labels
+- Massen-Stornierung
+
+### 13. Integration in Bestellverwaltung
+
+- DHL-Button in Bestelldetails
+- Direkter Zugang zu Sendungsinformationen
+
+### 14. Status-Anzeige & Feedback
+
+- Alert-System für Erfolgsmeldungen/Fehler
+- Real-time Status-Updates
+
+---
+
+## Phase 3: Tracking und Retouren (5 Schritte)
+
+### 15. Tracking-System
+
+- `UpdateTrackingStatusJob` für automatische Updates
+- Artisan Command `dhl:update-tracking`
+- Scheduler-Integration
+
+### 16. Tracking-Anzeige
+
+- Tracking-Status im Cockpit
+- Tracking-Details in Sendungsansicht
+- Timeline-View für Sendungsverlauf
+
+### 17. Retouren-Management
+
+- Button "Retourenlabel erstellen"
+- Retouren-Workflow im Admin
+- Verknüpfung Original-Sendung ↔ Retoure
+
+### 18. Customer-Interface (Basic)
+
+- Einfache öffentliche Tracking-Seite
+- Tracking-Nummer-Eingabe
+
+### 19. Notifications (Basic)
+
+- E-Mail bei Sendungserstellung
+- E-Mail bei wichtigen Status-Änderungen
+
+---
+
+## Phase 4: Finalisierung & Polish (4 Schritte)
+
+### 20. Performance-Optimierung
+
+- Eager Loading für Relationships
+- Caching für häufige API-Abfragen
+- Database-Indexe
+
+### 21. Comprehensive Testing
+
+- Integration-Tests für DHL SDK
+- Browser-Tests für Admin-Interface
+- Error-Scenario Tests
+
+### 22. Documentation
+
+- Benutzerhandbuch für Shop-Mitarbeiter
+- Code-Dokumentation
+- API-Dokumentation
+
+### 23. Production-Ready Features
+
+- Environment-spezifische Konfiguration
+- Monitoring & Alerting
+- Backup & Recovery-Konzept
+
+---
+
+## Optionale Erweiterungen (Phase 2 des Projekts)
+
+### Advanced Features (später):
+
+- Separate `dhl_tracking_events` Tabelle für detaillierte Historie
+- Excel/CSV Export von Sendungsdaten
+- Webhook-Integration für automatische Updates
+- SMS-Notifications
+- Erweiterte Reporting-Features
+- Multi-Tenant Support
+- API für externe Systeme
+
+---
+
+**Total: 23 konkrete Schritte** für ein vollständig funktionsfähiges DHL Versandmodul
+
+Dieser Plan fokussiert sich auf die Kernfunktionalitäten und liefert schnell ein nutzbares Ergebnis.

dev/dhl-modul/README.md

@@ -0,0 +1,120 @@
+# 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.

dev/dhl-modul/SCHRITT-3-COMPLETED.md

@@ -0,0 +1,136 @@
+# Schritt 3: Datenbank & Model - ABGESCHLOSSEN ✅
+
+## Durchgeführte Arbeiten
+
+### 3.1 Migration für dhl_shipments Tabelle erstellt ✅
+- **File**: `database/migrations/2025_08_19_155158_create_dhl_shipments_table.php`
+- **Status**: Erfolgreich migriert
+- **Tabelle**: `dhl_shipments`
+
+#### Tabellenstruktur:
+```sql
+- id (bigint unsigned, Primary Key)
+- shopping_order_id (int unsigned, Foreign Key -> shopping_orders.id)
+- related_shipment_id (bigint unsigned, Self-Reference für Retouren)
+- shipment_number (varchar, DHL Sendungsnummer)  
+- tracking_number (varchar, DHL Tracking-Nummer)
+- type (enum: 'outbound', 'return')
+- weight, length, width, height (Paketdaten)
+- product_code (varchar, DHL Produktcode)
+- services (json, Zusätzliche Services)
+- label_path, label_format, label_printed (Label-Management)
+- status (enum: created, submitted, in_transit, delivered, returned, cancelled, failed)
+- tracking_status, tracking_details, last_tracked_at (Tracking)
+- recipient_* (vollständige Empfängeradresse)
+- api_request_data, api_response_data, api_errors (API Debugging)
+- shipping_cost, currency (Kostenabrechnung)
+- notes, metadata (Zusätzliche Daten)
+- shipped_at, delivered_at (Timestamps)
+- created_at, updated_at (Standard Laravel Timestamps)
+```
+
+#### Indizes:
+- shopping_order_id (Performance)
+- shipment_number (DHL Suche)  
+- tracking_number (Tracking-Suche)
+- [type, status] (Kombiniert für Filter)
+- created_at (Chronologische Sortierung)
+
+#### Foreign Key Constraints:
+- shopping_order_id → shopping_orders.id (CASCADE DELETE)
+- related_shipment_id → dhl_shipments.id (SET NULL)
+
+### 3.2 DhlShipment Model erstellt ✅
+- **File**: `app/Models/DhlShipment.php`
+- **Status**: Vollständig implementiert
+- **Namespace**: `App\Models\DhlShipment`
+
+#### Model Features:
+- ✅ **Vollständige Eloquent Konfiguration** (fillable, casts, table)
+- ✅ **Konstanten für Status und Typen** 
+- ✅ **Relationships**: belongsTo ShoppingOrder, self-reference für Retouren
+- ✅ **Scopes**: outbound(), returns(), active(), trackable()
+- ✅ **Helper Methods**: isOutbound(), isReturn(), canBeCancelled(), hasTracking(), hasLabel()
+- ✅ **Accessors**: getRecipientAddressAttribute(), getDimensionsAttribute(), getStatusLabelAttribute()
+- ✅ **Boot Method**: Setzt Default-Werte aus Konfiguration
+
+#### Konstanten:
+```php
+// Typen
+const TYPE_OUTBOUND = 'outbound';
+const TYPE_RETURN = 'return';
+
+// Status
+const STATUS_CREATED = 'created';
+const STATUS_SUBMITTED = 'submitted'; 
+const STATUS_IN_TRANSIT = 'in_transit';
+const STATUS_DELIVERED = 'delivered';
+const STATUS_RETURNED = 'returned';
+const STATUS_CANCELLED = 'cancelled';
+const STATUS_FAILED = 'failed';
+```
+
+### 3.3 ShoppingOrder Model erweitert ✅
+- **File**: `app/Models/ShoppingOrder.php`
+- **Erweitert um DHL Relationships**
+
+#### Neue Methods:
+```php
+dhlShipments() // Alle DHL Sendungen
+dhlOutboundShipments() // Nur Versand-Sendungen
+dhlReturnShipments() // Nur Retour-Sendungen  
+hasDhlShipments(): bool // Prüft ob DHL Sendungen existieren
+getLatestDhlShipment() // Neueste DHL Sendung
+```
+
+## Optimierungen implementiert
+
+### MVP-Fokus erreicht ✅
+- **Eine zentrale Tabelle** statt separater Tabellen für Retouren
+- **Vollständige Empfängeradresse** in der Tabelle (kein Join nötig)
+- **JSON-Felder** für flexible API-Daten und Services
+- **Self-Reference** für Retouren über `related_shipment_id`
+
+### Performance optimiert ✅  
+- **Strategische Indizes** für häufige Abfragen
+- **Efficient Relationships** mit korrekten Foreign Key Typen
+- **Scopes** für häufige Filter-Operationen
+- **Casts** für automatische Datentyp-Konvertierung
+
+### Developer Experience ✅
+- **Ausführliche PHPDoc** für IDE-Support
+- **Helper Methods** für Business Logic
+- **Konstanten** statt Magic Strings
+- **Accessors** für formatierte Ausgaben
+
+## Bugfixes durchgeführt ✅
+- **Foreign Key Type Mismatch** behoben: `unsignedInteger` statt `unsignedBigInteger` für shopping_order_id
+- **Migration Konflikt** gelöst: Tabelle manuell entfernt und korrekt migriert
+
+## Verifikation ✅
+```bash
+# Migration erfolgreich
+php artisan migrate 
+# ✅ 2025_08_19_155158_create_dhl_shipments_table: 78.05ms DONE
+
+# Model lädt korrekt
+php artisan tinker --execute="use App\Models\DhlShipment; echo DhlShipment::class;"
+# ✅ App\Models\DhlShipment
+
+# Relationships funktionieren
+php artisan tinker --execute="use App\Models\ShoppingOrder; ShoppingOrder::first()->dhlShipments()->count();"
+# ✅ 0 (erwartungsgemäß, da noch keine DHL Shipments existieren)
+```
+
+## Nächste Schritte
+- **Schritt 4**: Zentraler `DhlApiService` als Wrapper um das DHL SDK
+- Integration der christoph-schaeffer/dhl-business-shipping Library
+- Erste API-Verbindung und Test-Calls
+
+## Files Created/Modified
+- ✅ `database/migrations/2025_08_19_155158_create_dhl_shipments_table.php` (neu)
+- ✅ `app/Models/DhlShipment.php` (neu)
+- ✅ `app/Models/ShoppingOrder.php` (erweitert)
+
+## Technical Debt: NONE ✨
+Alle Optimierungen erfolgreich implementiert, keine bekannten Probleme.