# 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)
```bash
# Läuft automatisch via Cron
# Definiert in: app/Console/Kernel.php
```

#### Manuell ausführen
```bash
# 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
```bash
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)
```bash
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
```bash
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<br>🤖 Automatisch | 👁️ 📥 📧 |
| #12 | in_transit | ... | ✅ 23.01.2026<br>👤 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
```sql
-- dhl_package_shipments Tabelle
tracking_email_sent_at  TIMESTAMP NULL  -- Wann versendet
tracking_email_type     VARCHAR(20)     -- 'auto' oder 'manual'
```

### Mail-Klasse
```php
// Unterstützt jetzt Collection von Shipments
new MailDhlTracking($shipments, $order)

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

### Logik
```php
// 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
```bash
# 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
```php
// app/Console/Kernel.php
$schedule->command('dhl:update-tracking --days=14 --send-emails')
    ->dailyAt('06:00')
    ->withoutOverlapping()
    ->runInBackground();
```

### Anpassungen
```php
// 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`:

```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
```bash
# 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
```bash
# 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
```bash
# 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