195 lines
5.2 KiB
Markdown
195 lines
5.2 KiB
Markdown
# 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.
|