13-05-2026 implementation FR

dev/2026-05-13-dhl-modul/legacy/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.