Implement package limit notification system

docs/todo/package-limit-experience-overhaul.md

@@ -0,0 +1,67 @@
+# 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)*
+- [ ] Konsistentes Fehler-Response-Schema (`code`, `title`, `message`, `meta`) implementieren. *(Begonnen: Gästeadmin/Admin Uploads nutzen ApiError)*
+- [ ] Domain-Events für Grenzwerte & Ablaufzustände emitten.
+- [ ] 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
+- [ ] Limit-Status im Upload-Flow anzeigen (Warnbanner + Sperrzustände).
+- [ ] Upload-Fehlercodes auswerten und freundliche Dialoge zeigen.
+- [ ] Galerie-Countdown/Badge für Ablaufdatum + Call-to-Action.
+- [ ] E2E-Tests für Limitwarnungen & abgelaufene Galerie aktualisieren.
+
+### 4. Tenant Admin PWA Improvements
+- [ ] Dashboard-Karten & Event-Header mit Ampelsystem für Limitfortschritt.
+- [ ] Event-Formular: Warnhinweise bei 80 %/95 % + Upgrade-CTA.
+- [ ] Globale Fehlerzustände aus Fehlerkontrakt (Toast/Dialog).
+- [ ] Ü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.
+- [ ] Weitere Benachrichtigungen (Paket-Ablauf, Reseller-Eventlimit, Credits fast leer).
+- [x] Opt-in/Opt-out-Konfiguration pro Tenant implementieren.
+- [ ] In-App/Toast-Benachrichtigungen für Admin UI (und optional Push/Slack intern).
+- [ ] Audit-Log & Retry-Logik für gesendete Mails.
+
+### 6. Monitoring, Docs & Support
+- [ ] Prometheus/Grafana-Metriken für Paketnutzung & Warns triggern.
+- [ ] PRP & API-Doku mit neuem Fehlerschema & Limitverhalten aktualisieren.
+- [ ] Support-Playbook & FAQ für Limitwarnungen erweitern.
+
+## 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.