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

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.