mivita/dev/2026-01-22/dhl-tracking-emails.md

DHL Tracking E-Mails - Erweiterte Funktionen

📧 Mehrere Sendungen in einer E-Mail

Problem gelöst:

Wenn eine Bestellung in mehrere Pakete aufgeteilt wird, erhalten Kunden jetzt eine gesammelte E-Mail mit allen Tracking-Nummern, statt mehrere einzelne E-Mails.

---

✨ Neue Features

1. Automatische Zusammenfassung

Alle Sendungen einer Bestellung werden automatisch in einer E-Mail zusammengefasst:

┌─────────────────────────────────────┐
│ Deine 3 Sendungen sind unterwegs!  │
├─────────────────────────────────────┤
│                                     │
│ Paket 1                             │
│ Sendungsnummer: 00340433333...      │
│ [Sendung bei DHL verfolgen]         │
│                                     │
│ Paket 2                             │
│ Sendungsnummer: 00340433334...      │
│ [Sendung bei DHL verfolgen]         │
│                                     │
│ Paket 3                             │
│ Sendungsnummer: 00340433335...      │
│ [Sendung bei DHL verfolgen]         │
└─────────────────────────────────────┘

2. Intelligente Versand-Logik

• ✅ Sammelt alle Sendungen einer Bestellung
• ✅ Versendet eine E-Mail pro Bestellung (nicht pro Paket)
• ✅ Markiert alle Sendungen als versendet
• ✅ Verhindert doppelte E-Mails

3. Manuelle Versand-Option

Im Admin unter DHL Cockpit oder Bestelldetails:

• Button "Tracking-E-Mail senden" klicken
• Sendet automatisch alle Sendungen der Bestellung
• Zeigt Anzahl der Sendungen in der Bestätigung

4. Test-Modus für Cronjob

Testen Sie E-Mails, bevor sie an Kunden gehen!

---

🚀 Verwendung

Manuelle E-Mail versenden (Admin)

Option 1: Aus Bestelldetails

1. Bestellung öffnen
2. DHL Sendungen-Block scrollen
3. Button "📧" klicken
4. Alle Sendungen dieser Bestellung werden versendet

Option 2: Aus DHL Cockpit

1. DHL Cockpit öffnen
2. Sendung finden
3. Button "📧" klicken
4. Alle Sendungen dieser Bestellung werden versendet

Automatischer Cronjob

Standard (täglich 06:00 Uhr)

# Läuft automatisch via Cron
# Definiert in: app/Console/Kernel.php

Manuell ausführen

# Normale Ausführung
php artisan dhl:update-tracking --send-emails

# Mit Test-E-Mail
php artisan dhl:update-tracking --send-emails --test-email=admin@example.com

# Für bestimmte Bestellung
php artisan dhl:update-tracking --send-emails --order=45078

# Dry-Run (keine Änderungen)
php artisan dhl:update-tracking --send-emails --dry-run

---

🧪 Test-Optionen

Option 1: Test-E-Mail an eigene Adresse

php artisan dhl:update-tracking --send-emails --test-email=meine@email.de

✅ Sendet E-Mails an angegebene Adresse statt an Kunden ✅ Perfekt zum Testen des Layouts und Inhalts ✅ Markiert Sendungen TROTZDEM als versendet

Option 2: Dry-Run (Simulation)

php artisan dhl:update-tracking --send-emails --dry-run

✅ Simuliert alle Aktionen ✅ Sendet KEINE E-Mails ✅ Markiert Sendungen NICHT als versendet ✅ Zeigt was passieren würde

Option 3: Bestimmte Bestellung testen

php artisan dhl:update-tracking --send-emails --order=45078 --test-email=test@example.com

✅ Nur für eine Order-ID ✅ An Test-Adresse ✅ Perfekt für gezielte Tests

---

📊 Versand-Status in Bestelldetails

Anzeige

Für jede Sendung wird angezeigt:

Sendung	Status	Tracking	E-Mail	Aktionen
#11	created	-	✅ 23.01.2026 🤖 Automatisch	👁️ 📥 📧
#12	in_transit	...	✅ 23.01.2026 👤 Manuell	👁️ 📥 🔄 📧
#13	created	-	⏳ Nicht gesendet	👁️ 📥 📧

Informationen

• ✅ Datum: Wann wurde E-Mail versendet
• 🤖 Automatisch: Via Cronjob versendet
• 👤 Manuell: Über Admin-Button versendet
• ⏳ Nicht gesendet: Noch keine E-Mail

---

⚙️ Technische Details

Datenbank-Felder

-- dhl_package_shipments Tabelle
tracking_email_sent_at  TIMESTAMP NULL  -- Wann versendet
tracking_email_type     VARCHAR(20)     -- 'auto' oder 'manual'

Mail-Klasse

// Unterstützt jetzt Collection von Shipments
new MailDhlTracking($shipments, $order)

// Oder einzelne Sendung (backward compatible)
new MailDhlTracking($shipment, $order)

Logik

// Sammelt alle Sendungen einer Bestellung
$allShipments = DhlShipment::where('order_id', $order->id)
    ->whereNotNull('dhl_shipment_no')
    ->whereIn('status', ['created', 'in_transit', 'out_for_delivery'])
    ->get();

// Sendet eine E-Mail mit allen Sendungen
Mail::to($email)->send(new MailDhlTracking($allShipments, $order));

// Markiert alle als versendet
foreach ($allShipments as $shipment) {
    $shipment->markTrackingEmailSent('manual');
}

---

🎯 Anwendungsfälle

Fall 1: Mehrere Pakete bei Erstellung

1. Admin erstellt 3 Labels für Order #45078
2. Alle 3 Labels werden erstellt (Status: created)
3. Cronjob läuft (06:00 Uhr)
4. Status wird aktualisiert (created → in_transit)
5. EINE E-Mail mit allen 3 Sendungen wird versendet

Fall 2: Nachträgliches Label

1. Order #45078 hat bereits 2 Labels (E-Mail bereits versendet)
2. Admin erstellt 3. Label
3. Admin klickt "📧" Button
4. NEUE E-Mail mit allen 3 Sendungen wird versendet

Fall 3: Test vor Produktiv-Einsatz

# 1. Test mit eigener E-Mail
php artisan dhl:update-tracking --send-emails --test-email=admin@firma.de

# 2. Prüfen der E-Mail
# 3. Bei OK: Cronjob aktivieren (läuft automatisch)

---

🔧 Konfiguration

Cronjob-Einstellung

// app/Console/Kernel.php
$schedule->command('dhl:update-tracking --days=14 --send-emails')
    ->dailyAt('06:00')
    ->withoutOverlapping()
    ->runInBackground();

Anpassungen

// Andere Uhrzeit
->dailyAt('08:00')

// Nur Werktage
->weekdays()->at('06:00')

// Nur wenn Sendungen vorhanden
->when(function() {
    return DhlShipment::active()->count() > 0;
})

---

📝 Übersetzungen

Neue Übersetzungs-Keys in resources/lang/{de,en,es}/email.php:

'dhl_tracking_subject_multiple' => 'Deine :count Sendungen sind unterwegs'
'dhl_tracking_message_multiple' => 'Deine Bestellung wurde in :count Paketen versendet'
'dhl_tracking_package_label' => 'Paket :number'

---

✅ Vorteile

Vorher	Nachher
3 Pakete = 3 E-Mails	3 Pakete = 1 E-Mail
Kunde verwirrt	Kunde hat Überblick
Einzelne Tracking-Nummern	Alle Nummern auf einen Blick
Manuell testen schwierig	Test-Modus integriert
Kein Überblick über Versand	Klare Anzeige in Admin

---

🐛 Troubleshooting

Problem: E-Mail wird nicht versendet

# Prüfen ob Sendungen vorhanden
php artisan tinker
>>> Acme\Dhl\Models\DhlShipment::active()->count()

# Prüfen ob E-Mail-Adresse vorhanden
>>> $order = App\Models\ShoppingOrder::find(45078);
>>> $order->shopping_user->email

Problem: Mehrfache E-Mails

# Prüfen welche Sendungen noch keine E-Mail haben
php artisan tinker
>>> Acme\Dhl\Models\DhlShipment::whereNull('tracking_email_sent_at')->count()

Problem: Test-E-Mail kommt nicht an

# Queue prüfen
php artisan queue:work --once

# Logs prüfen
tail -f storage/logs/laravel.log

---

📞 Support

Bei Fragen zur Implementierung siehe:

• /dev/22-01-2026/next-steps.md - Vollständige Dokumentation
• app/Console/Commands/DhlUpdateTracking.php - Command-Code
• app/Mail/MailDhlTracking.php - Mail-Klasse
• resources/views/emails/dhl_tracking.blade.php - E-Mail Template