# Package Limit Experience Overhaul

**Status:** Planned  
**Owner:** Codegen Agent  
**Related Areas:** Packages, Tenant Admin PWA, Guest PWA, Notifications

## Motivation
- Uneinheitliche Limit-Prüfungen (Public Upload vs. Admin Upload vs. Event-Erstellung).
- Fehlende, generische oder kryptische Fehlermeldungen im Admin-Frontend.
- Keine Frühwarnungen bei 80 %/95 % Auslastung, kein Countdown für Galerien.
- Fehlende Automatisierung für E-Mail-/In-App-Warnungen bei kritischen Zuständen.

## High-Level Goals
1. Konsistente Limit-Prüfungen & Fehlercodes im Backend.
2. Verbesserte UX in Guest & Tenant Admin PWA (Warnungen, klare Fehlermeldungen).
3. Proaktive Benachrichtigungen (E-Mail, In-App) bei bevorstehenden Grenzwerten / Ablauf.
4. Monitoring, Dokumentation, Tests für alle neuen Abläufe.

## Work Breakdown

### 1. Backend Unification
- [x] Paket-Limit-Service erstellen (Fotos, Gäste, Aufgaben, Events/Jahr, Galerie-Laufzeit). *(Initial evaluator + Middleware Integration für Events/Fotos)*
- [x] Public Uploads um Paketlimit-Prüfung erweitern (inkl. Events ohne Aktivpaket blockieren). *(Guest Upload prüft & erhöht Zähler)*
- [x] Konsistentes Fehler-Response-Schema (`code`, `title`, `message`, `meta`) implementieren.
- [x] Domain-Events für Grenzwerte & Ablaufzustände emitten.
- [x] Feature-/Unit-Tests für neue Services & Events.

### 2. Threshold Detection & Storage
- [x] Schwellenwerte konfigurieren (Fotos/Gäste, Gallery D-7/D-1).
- [x] Scheduler/Jobs für regelmäßige Galerie-Checks.
- [x] Persistenz für Galerie-Benachrichtigungen (warning/expired timestamps).

### 3. Guest PWA Improvements
- [x] Limit-Status im Upload-Flow anzeigen (Warnbanner + Sperrzustände).
- [x] Upload-Fehlercodes auswerten und freundliche Dialoge zeigen.
- [x] Galerie-Countdown/Badge für Ablaufdatum + Call-to-Action.
- [x] E2E-Tests für Limitwarnungen & abgelaufene Galerie aktualisieren.

### 4. Tenant Admin PWA Improvements
- [x] Dashboard-Karten & Event-Header mit Ampelsystem für Limitfortschritt.
- [x] Event-Formular: Warnhinweise bei 80 %/95 % + Upgrade-CTA.
- [x] Globale Fehlerzustände aus Fehlerkontrakt (Toast/Dialog).
- [x] Übersetzungen für alle neuen Messages hinzufügen.

- [x] E-Mail-Schablonen & Notifications für Foto- und Gäste-Schwellen/Limits.
- [x] Galerie-Warnungen (D-7/D-1) & Ablauf-Mails + Cron Task.
- [x] Weitere Benachrichtigungen (Paket-Ablauf, Reseller-Eventlimit, Credits fast leer).
- [x] Opt-in/Opt-out-Konfiguration pro Tenant implementieren.
- [x] In-App/Toast-Benachrichtigungen für Admin UI (und optional Push/Slack intern).
- [x] Audit-Log & Retry-Logik für gesendete Mails.

### 6. Monitoring, Docs & Support
- [x] Prometheus/Grafana-Metriken für Paketnutzung & Warns triggern. *(`PackageLimitMetrics` + `php artisan metrics:package-limits` Snapshot)*
- [x] PRP & API-Doku mit neuem Fehlerschema & Limitverhalten aktualisieren.
- [x] Support-Playbook & FAQ für Limitwarnungen erweitern. *(docs/prp/06 Tenant Admin Playbook Abschnitt)*

## Dependencies & Notes
- Bestehende Credit-Logik parallel weiter unterstützen (Legacy-Kunden).
- Paddle/E-Mail-Dienste müssen auf Sandbox getestet werden.
- Mehrsprachigkeit (de/en) sicherstellen.

## Definition of Done
- Alle relevanten Grenzwerte serverseitig validiert und getestet.
- Frontends zeigen spezifische Warnungen + Handlungsanweisungen.
- Benachrichtigungssystem verschickt Mails bei konfigurierten Schwellen.
- Monitoring & Dokumentation sind aktualisiert.
- Regressionstests und neue Tests laufen grün.