gitmedia/mivita
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mivita/dev/dhl-modul/PLAN-OPTIMIERT.md
Kevin Adametz 8fdaa0ba1d DHL Modul v0.5 Shipping Label ok
2025-08-22 18:18:26 +02:00

5.2 KiB
Raw Blame History

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.