# 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
- OAuth2 Authorization Code mit PKCE, Refresh-Tokens via Secure Storage (Web: IndexedDB, Capacitor: Preferences/Keychain).
- Tenant-Scoped Tokens; Rollen `tenant_admin` (vollständig) & `member` (read-only, Upload).

### 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 /oauth/token`, `POST /oauth/token/refresh` |
| 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-mitigiert via PKCE/OAuth; Token-Refresh automatisiert.
- **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.