further rework to the documentation

docs/archive/prp/tenant-app-specs/functional-specs.md

@@ -0,0 +1,89 @@
+# Funktionale Spezifikationen – Tenant-Admin-App
+
+## Status
+- **Version**: 1.1.0 (Stand 2025-10-13)
+- **Ersetzt**: docs/prp/06-tenant-admin-pwa.md, docs/prp-addendum-2025-09-08-tenant-admin-pwa.md (Legacy-Referenz über Git History).
+
+## Deliverables
+Die Admin-App muss folgende Kernfunktionen bereitstellen:
+- **Geführtes Onboarding**: Welcome Flow (Hero, How-It-Works, Paketwahl, Zusammenfassung, Erstes Event). Automatische Weiterleitung für Tenants ohne aktive Events.
+- **Event-Management**: Erstellen, Bearbeiten, Veröffentlichen, Archivieren; Join-Token-Verwaltung.
+- **Galerie-Management**: Upload, Moderation, Feature-Flags, Analytics.
+- **Mitglieder-Verwaltung**: Einladungen, Rollen, Zugriffskontrolle.
+- **Tasks & Emotions**: Bibliothek, Zuweisung, Fortschritts-Tracking.
+- **Abrechnung**: Paketübersicht, Paddle Checkout, Ledger.
+- **Einstellungen**: Branding, Limits, Rechtstexte, Benachrichtigungen.
+- **Offline-Support**: App-Shell-Caching, Queueing von Mutationen, Sync bei Reconnect.
+- **Compliance**: Audit-Logging, GDPR-konforme Löschung, ETag-basierte Konfliktlösung.
+
+## Capabilities
+### Authentifizierung & Autorisierung
+- Sanctum Personal Access Tokens (`/api/v1/tenant-auth/login|exchange`) mit Fähigkeiten `tenant-admin`, `tenant:{id}`; Speicherung in IndexedDB sowie Keychain/Keystore für Capacitor.
+- Rollenbasierte Fähigkeiten: `tenant_admin` (vollständig), `member` (read-only, Upload). Token-Exchange nach Google-Login oder Session-Login via `/tenant-auth/exchange`.
+
+### Onboarding Journey
+- Routen `/event-admin/welcome/*` bilden den Flow.
+- Filament stellt einen korrespondierenden Onboarding-Wizard (QR/Join-Token, Layout-Download) bereit; Abschluss setzt `onboarding_completed_at` serverseitig.
+- `useOnboardingProgress` persistiert Fortschritt (localStorage) und synchronisiert mit Backend (`onboarding_completed_at`).
+- Paketwahl nutzt `GET /tenant/packages`; Paddle-Fallbacks informieren bei fehlender Konfiguration.
+- Dashboard weist per CTA auf offenes Onboarding hin, bis ein erstes Event erstellt wurde.
+
+### Event Lifecycle
+- Erstellung prüft Paketverfügbarkeit; generiert Join-Token (EventJoinToken-Service).
+- QR-Layouts und Token-Rotation erfolgen über `/event-admin/welcome` bzw. das Filament-Panel; slug-basierte QR-Links wurden deaktiviert.
+- Bearbeiten erlaubt Statuswechsel, Aufgaben, Emotions, Join-Token-Verwaltung.
+- Veröffentlichen schaltet Guest-PWA frei; Archivieren respektiert Retention-Policy.
+
+### Medien & Moderation
+- Direktupload via signed URLs, Thumbnail-Generierung serverseitig.
+- Moderations-Grid mit Bulk-Aktionen, Filter (Neu, Genehmigt, Featured).
+- Analytics: Likes, Uploadzahlen, aktive Gäste.
+
+### Tasks & Emotions
+- Globale + Tenant-spezifische Bibliothek.
+- Drag-and-Drop Zuweisung, Fortschritt je Event, Emotion-Tagging.
+
+### Billing & Checkout
+- Pakete + Credit-Balance anzeigen.
+- Stripe PaymentIntent & Paddle Smart Buttons; Fallback-Meldung bei fehlender Konfiguration.
+- Ledger mit Historie (Paginierung, Filter).
+
+### Settings
+- Branding (Logo, Farben), Domain/Links, Legal Pages.
+- Notification Preferences, Paketlimits, Onboarding-Reset.
+
+### Offline & Sync
+- Service Worker `public/admin-sw.js` cached App-Shell `/event-admin` und statische Assets, liefert Offline-Fallback für Navigation.
+- Mutationen werden gequeued und nach Reconnect synchronisiert.
+- ETag / If-Match für konfliktfreie Updates, Optimistic UI mit Rollback.
+
+### Fehlerbehandlung & UX
+- Rate-Limit (429) → Retry-Hinweis.
+- Offline-Banner + Retry-Buttons an kritischen Stellen (Checkout, Upload).
+- i18n via `react-i18next` (de/en); Strings in `public/lang/{locale}/admin.json`.
+
+## API-Integration
+Die App nutzt Endpunkte aus `docs/prp/03-api.md`.
+
+| Bereich | Endpunkte |
+| --- | --- |
+| Auth | `POST /tenant-auth/login`, `POST /tenant-auth/exchange`, `POST /tenant-auth/logout` |
+| Onboarding | `GET /tenant/me` (Progress Flags), `GET /tenant/packages`, `POST /tenant/events` |
+| Events | `GET/POST/PATCH/DELETE /tenant/events`, `POST /tenant/events/{event}/toggle`, Join-Token Routen |
+| Medien | `GET /tenant/events/{event}/photos`, `POST /tenant/events/{event}/photos`, `PATCH /tenant/photos/{id}` |
+| Tasks & Emotions | `GET /tenant/tasks`, `POST /tenant/events/{event}/tasks`, `GET /tenant/emotions` |
+| Settings | `GET/PATCH /tenant/settings`, `GET /tenant/credits/balance`, `POST /tenant/purchases/intent` |
+
+## Nicht-funktionale Anforderungen
+- **Performance**: Ladezeit < 2s; Code-Splitting der Onboarding-Screens.
+- **Sicherheit**: Keine sensiblen Logs; CSRF abgesichert via Sanctum stateful middleware; Token-Neuausstellung durch erneutes Login oder Exchange.
+- **Accessibility**: Tastaturbedienung, Fokus-Indikatoren, `prefers-reduced-motion`.
+- **Internationalisierung**: Sprachumschaltung in Einstellungen; Standard de, Fallback en.
+
+## Teststrategie
+- **PHPUnit**: Feature-Tests für Auth-Guards (Tenant ohne Events → Welcome Flow).
+- **React Testing Library**: `TenantWelcomeLayout`, `PackageSelection`, `OnboardingGuard`, `OrderSummary`.
+- **Playwright**: `tests/e2e/tenant-onboarding-flow.test.ts` deckt Login, Welcome → Packages → Summary → Event Setup ab; Erweiterung um Paddle Happy Paths und Offline/Retry geplant.
+- **Smoke Tests**: `npm run test:e2e` in CI mit optionalen Credentials (`E2E_TENANT_EMAIL`, `E2E_TENANT_PASSWORD`, Paddle Keys).
+
+Für UI-Details siehe `docs/prp/tenant-app-specs/pages-ui.md`. Einstellungen werden in `docs/prp/tenant-app-specs/settings-config.md` beschrieben.