# 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.