Neustrukturierung Customer / Lead / Booking Phase 2
This commit is contained in:
parent
313f0dbf4e
commit
6df9c401af
69 changed files with 3809 additions and 374 deletions
|
|
@ -1,324 +0,0 @@
|
|||
# Newsletter-Modul Dokumentation
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das Newsletter-Modul ermöglicht die zentrale Verwaltung von Newsletter-Kontakten aus beiden Buchungssystemen (Kulturreisen und Ferienwohnungen). Es synchronisiert automatisch Kundendaten aus Buchungen und bietet Export-Funktionen für Newsletter-Kampagnen.
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Zentrale Kontaktverwaltung für beide Newsletter-Gruppen
|
||||
- ✅ Automatische Synchronisation aus Buchungssystemen
|
||||
- ✅ Duplikat-Erkennung über E-Mail-Adressen
|
||||
- ✅ Tracking von Buchungsstatistiken
|
||||
- ✅ Status-Verwaltung (Aktiv, Inaktiv, Abgemeldet, Bounced)
|
||||
- ✅ Herkunfts-Tracking (Buchung, Newsletter-Anmeldung, etc.)
|
||||
- ✅ Export-Funktion (CSV)
|
||||
- ✅ Aktivitäts-Log für jeden Kontakt
|
||||
- ✅ Filter- und Suchfunktionen
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Migrationen ausführen
|
||||
|
||||
```bash
|
||||
./vendor/bin/sail artisan migrate
|
||||
```
|
||||
|
||||
Dies erstellt folgende Tabellen:
|
||||
- `newsletter_contacts` - Haupt-Kontakte-Tabelle
|
||||
- `newsletter_logs` - Aktivitäts-Log
|
||||
|
||||
### 2. Berechtigung hinzufügen
|
||||
|
||||
In der Datenbank muss die Berechtigung `cms-newsletter` für Benutzer aktiviert werden, die Zugriff auf das Newsletter-Modul haben sollen.
|
||||
|
||||
```sql
|
||||
-- Beispiel: Berechtigung für einen User aktivieren
|
||||
-- Dies muss über das bestehende Berechtigungssystem erfolgen
|
||||
```
|
||||
|
||||
### 3. Erste Synchronisation
|
||||
|
||||
Nach der Installation sollte eine vollständige Synchronisation durchgeführt werden:
|
||||
|
||||
```bash
|
||||
# Alle Buchungen synchronisieren
|
||||
./vendor/bin/sail artisan newsletter:sync-kulturreisen --force
|
||||
./vendor/bin/sail artisan newsletter:sync-ferienwohnungen --force
|
||||
```
|
||||
|
||||
## Verwendung
|
||||
|
||||
### Admin-Panel
|
||||
|
||||
Das Newsletter-Modul ist im Admin-Panel unter **CMS > Inhalte > Newsletter** erreichbar.
|
||||
|
||||
#### Hauptfunktionen:
|
||||
|
||||
1. **Kontaktliste**
|
||||
- Übersicht aller Newsletter-Kontakte
|
||||
- Filter nach Gruppe, Status, Herkunft
|
||||
- Suchfunktion nach E-Mail und Name
|
||||
- DataTables mit Sortierung und Pagination
|
||||
|
||||
2. **Kontakt-Detail**
|
||||
- Vollständige Kontaktinformationen
|
||||
- Buchungsstatistiken
|
||||
- Aktivitäts-Log
|
||||
- Verlinkung zu Original-Kundendaten
|
||||
|
||||
3. **Kontakt bearbeiten**
|
||||
- Manuelles Erstellen von Kontakten
|
||||
- Bearbeiten von Kontaktdaten
|
||||
- Status-Änderung
|
||||
- Gruppen-Zuweisung
|
||||
|
||||
4. **Synchronisation**
|
||||
- Manuelle Synchronisation über UI
|
||||
- Incremental Sync (letzte 30 Tage)
|
||||
- Full Sync (alle Buchungen)
|
||||
|
||||
5. **Export**
|
||||
- Export nach Gruppe
|
||||
- Export nach Status
|
||||
- CSV-Format
|
||||
- Vorkonfigurierte Export-Optionen
|
||||
|
||||
### Artisan-Befehle
|
||||
|
||||
#### Synchronisation Kulturreisen
|
||||
|
||||
```bash
|
||||
# Incremental Sync (letzte 30 Tage)
|
||||
./vendor/bin/sail artisan newsletter:sync-kulturreisen
|
||||
|
||||
# Full Sync (alle Buchungen)
|
||||
./vendor/bin/sail artisan newsletter:sync-kulturreisen --force
|
||||
```
|
||||
|
||||
Dieser Befehl:
|
||||
- Liest alle Buchungen aus der `booking` Tabelle
|
||||
- Verknüpft mit `customer` Daten
|
||||
- Erstellt oder aktualisiert Newsletter-Kontakte
|
||||
- Zählt Buchungen pro Kunde
|
||||
- Trackt letzte Buchung
|
||||
|
||||
#### Synchronisation Ferienwohnungen
|
||||
|
||||
```bash
|
||||
# Incremental Sync (letzte 30 Tage)
|
||||
./vendor/bin/sail artisan newsletter:sync-ferienwohnungen
|
||||
|
||||
# Full Sync (alle Buchungen)
|
||||
./vendor/bin/sail artisan newsletter:sync-ferienwohnungen --force
|
||||
```
|
||||
|
||||
Dieser Befehl:
|
||||
- Liest Buchungen aus `travel_user_booking_fewos` mit `invoice_number`
|
||||
- Nur Buchungen mit reiner Nummer (keine Storno etc.)
|
||||
- Verknüpft mit `travel_users` Daten
|
||||
- Erstellt oder aktualisiert Newsletter-Kontakte
|
||||
- Zählt Buchungen pro Kunde
|
||||
|
||||
### Automatische Synchronisation
|
||||
|
||||
Für regelmäßige Synchronisation empfiehlt sich ein Cron-Job:
|
||||
|
||||
```bash
|
||||
# In der crontab
|
||||
# Täglich um 2 Uhr morgens
|
||||
0 2 * * * cd /var/www/html && ./vendor/bin/sail artisan newsletter:sync-kulturreisen
|
||||
0 2 * * * cd /var/www/html && ./vendor/bin/sail artisan newsletter:sync-ferienwohnungen
|
||||
```
|
||||
|
||||
Oder im Laravel Scheduler (`app/Console/Kernel.php`):
|
||||
|
||||
```php
|
||||
protected function schedule(Schedule $schedule)
|
||||
{
|
||||
// Täglich um 2 Uhr
|
||||
$schedule->command('newsletter:sync-kulturreisen')->dailyAt('02:00');
|
||||
$schedule->command('newsletter:sync-ferienwohnungen')->dailyAt('02:15');
|
||||
}
|
||||
```
|
||||
|
||||
## Datenmodell
|
||||
|
||||
### Newsletter Contact
|
||||
|
||||
| Feld | Typ | Beschreibung |
|
||||
|------|-----|--------------|
|
||||
| `id` | bigint | Primary Key |
|
||||
| `email` | string | E-Mail-Adresse (unique) |
|
||||
| `firstname` | string | Vorname |
|
||||
| `lastname` | string | Nachname |
|
||||
| `group_kulturreisen` | boolean | Zugehörigkeit zur Gruppe Kulturreisen |
|
||||
| `group_ferienwohnungen` | boolean | Zugehörigkeit zur Gruppe Ferienwohnungen |
|
||||
| `source` | enum | Herkunft des Kontakts |
|
||||
| `status` | enum | Status (active, inactive, unsubscribed, bounced) |
|
||||
| `subscribed_at` | timestamp | Zeitpunkt der Anmeldung |
|
||||
| `unsubscribed_at` | timestamp | Zeitpunkt der Abmeldung |
|
||||
| `last_booking_at` | timestamp | Zeitpunkt der letzten Buchung |
|
||||
| `total_bookings_kulturreisen` | int | Anzahl Buchungen Kulturreisen |
|
||||
| `total_bookings_ferienwohnungen` | int | Anzahl Buchungen Ferienwohnungen |
|
||||
| `customer_id` | int | Referenz zu `customer` (Kulturreisen) |
|
||||
| `travel_user_id` | int | Referenz zu `travel_users` (Ferienwohnungen) |
|
||||
| `last_synced_at` | timestamp | Letzte Synchronisation |
|
||||
| `sync_hash` | string | Hash für Duplikat-Erkennung |
|
||||
| `notes` | text | Notizen |
|
||||
|
||||
### Newsletter Log
|
||||
|
||||
| Feld | Typ | Beschreibung |
|
||||
|------|-----|--------------|
|
||||
| `id` | bigint | Primary Key |
|
||||
| `newsletter_contact_id` | bigint | Foreign Key zu newsletter_contacts |
|
||||
| `action` | enum | Aktion (subscribed, unsubscribed, etc.) |
|
||||
| `description` | string | Beschreibung der Aktion |
|
||||
| `metadata` | json | Zusätzliche Daten |
|
||||
| `user_id` | int | Admin-User der die Aktion ausgeführt hat |
|
||||
|
||||
## Status-Typen
|
||||
|
||||
- **active**: Aktiver Newsletter-Empfänger
|
||||
- **inactive**: Inaktiv (z.B. temporär deaktiviert)
|
||||
- **unsubscribed**: Abgemeldet vom Newsletter
|
||||
- **bounced**: E-Mail nicht zustellbar (Bounced)
|
||||
|
||||
## Herkunfts-Typen
|
||||
|
||||
- **booking_kulturreisen**: Aus Kulturreisen-Buchung
|
||||
- **booking_ferienwohnungen**: Aus Ferienwohnungs-Buchung
|
||||
- **newsletter_signup**: Newsletter-Anmeldung über Formular
|
||||
- **manual**: Manuell erstellt
|
||||
- **import**: Über Import hinzugefügt
|
||||
|
||||
## Export-Formate
|
||||
|
||||
### CSV-Export
|
||||
|
||||
Der CSV-Export enthält folgende Spalten:
|
||||
|
||||
1. ID
|
||||
2. E-Mail
|
||||
3. Vorname
|
||||
4. Nachname
|
||||
5. Gruppe Kulturreisen (Ja/Nein)
|
||||
6. Gruppe Ferienwohnungen (Ja/Nein)
|
||||
7. Status
|
||||
8. Herkunft
|
||||
9. Buchungen Kulturreisen
|
||||
10. Buchungen Ferienwohnungen
|
||||
11. Letzte Buchung
|
||||
12. Angemeldet am
|
||||
13. Abgemeldet am
|
||||
14. Erstellt am
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Duplikat-Vermeidung
|
||||
|
||||
Das System verwendet einen Hash basierend auf E-Mail und Quelle zur Duplikat-Erkennung. Kontakte werden automatisch zusammengeführt, wenn:
|
||||
- Dieselbe E-Mail-Adresse in beiden Systemen vorkommt
|
||||
- Der neuere Datensatz wird bevorzugt
|
||||
- Gruppenzugehörigkeiten werden kombiniert
|
||||
|
||||
### Datenschutz
|
||||
|
||||
- Soft-Delete: Gelöschte Kontakte werden nicht permanent entfernt
|
||||
- Log-Tracking: Alle Änderungen werden protokolliert
|
||||
- Abmelde-Funktion: Kontakte können sich jederzeit abmelden
|
||||
- Export-Kontrolle: Nur autorisierte Benutzer können exportieren
|
||||
|
||||
### Performance
|
||||
|
||||
- Incremental Sync: Standardmäßig werden nur die letzten 30 Tage synchronisiert
|
||||
- Indexierung: E-Mail, Status und Gruppen sind indexiert
|
||||
- DataTables: Server-Side Processing für große Datenmengen
|
||||
- Batch-Processing: Synchronisation verarbeitet Datensätze effizient
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Synchronisation schlägt fehl
|
||||
|
||||
**Lösung:**
|
||||
1. Prüfe Datenbankverbindungen (beide Datenbanken müssen erreichbar sein)
|
||||
2. Prüfe Logs: `storage/logs/laravel.log`
|
||||
3. Führe Sync mit `--force` aus für vollständige Synchronisation
|
||||
|
||||
### Problem: Duplikate in der Liste
|
||||
|
||||
**Lösung:**
|
||||
1. Prüfe `sync_hash` Spalte
|
||||
2. Führe manuelle Bereinigung durch
|
||||
3. Kontakte können manuell zusammengeführt werden
|
||||
|
||||
### Problem: Export enthält keine Daten
|
||||
|
||||
**Lösung:**
|
||||
1. Prüfe Filter-Einstellungen
|
||||
2. Prüfe Status der Kontakte
|
||||
3. Prüfe Berechtigungen
|
||||
|
||||
## API-Endpunkte
|
||||
|
||||
Alle Routen sind unter dem Middleware-Schutz `['admin', '2fa', 'auth.permission:cms-newsletter']`.
|
||||
|
||||
| Methode | Route | Beschreibung |
|
||||
|---------|-------|--------------|
|
||||
| GET | `/newsletter` | Liste aller Kontakte |
|
||||
| GET | `/newsletter/datatable` | DataTables AJAX |
|
||||
| GET | `/newsletter/{id}` | Detail eines Kontakts |
|
||||
| GET | `/newsletter/{id}/edit` | Bearbeitungsformular |
|
||||
| POST | `/newsletter/{id}/store` | Speichern |
|
||||
| DELETE | `/newsletter/{id}` | Löschen (soft delete) |
|
||||
| POST | `/newsletter/{id}/unsubscribe` | Abmelden |
|
||||
| POST | `/newsletter/{id}/resubscribe` | Wieder aktivieren |
|
||||
| POST | `/newsletter/sync` | Synchronisation starten |
|
||||
| GET | `/newsletter/export` | Export |
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Integration mit Newsletter-Diensten
|
||||
|
||||
Das Modul kann einfach mit externen Newsletter-Diensten (Mailchimp, SendGrid, etc.) integriert werden:
|
||||
|
||||
```php
|
||||
// Beispiel: Export für Mailchimp
|
||||
$contacts = NewsletterContact::active()->kulturreisen()->get();
|
||||
foreach ($contacts as $contact) {
|
||||
// Mailchimp API Call
|
||||
}
|
||||
```
|
||||
|
||||
### Webhook für Abmeldungen
|
||||
|
||||
Eine öffentliche Abmelde-Route kann hinzugefügt werden:
|
||||
|
||||
```php
|
||||
// routes/web.php
|
||||
Route::get('/newsletter/unsubscribe/{token}', 'NewsletterPublicController@unsubscribe');
|
||||
```
|
||||
|
||||
### Double-Opt-In
|
||||
|
||||
Für Newsletter-Anmeldungen kann ein Double-Opt-In Prozess implementiert werden.
|
||||
|
||||
## Support
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
1. Prüfe diese Dokumentation
|
||||
2. Prüfe Laravel Logs
|
||||
3. Prüfe Artisan Command Output
|
||||
4. Kontaktiere das Entwickler-Team
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 1.0.0 (2025-11-07)
|
||||
- ✅ Initiales Release
|
||||
- ✅ Kontaktverwaltung
|
||||
- ✅ Synchronisation Kulturreisen
|
||||
- ✅ Synchronisation Ferienwohnungen
|
||||
- ✅ Export-Funktion
|
||||
- ✅ Admin-Panel Integration
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue