90 lines
5.2 KiB
Markdown
90 lines
5.2 KiB
Markdown
# 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.
|