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

Funktionale Spezifikationen für die Tenant Admin App

Status

• Version: 1.0.0 (2025-09-13)
• Supersedes: Teile von docs/prp/06-tenant-admin-pwa.md und docs/prp-addendum-2025-09-08-tenant-admin-pwa.md

Deliverables

Die Tenant Admin App muss folgende Kernfunktionen bereitstellen:

• Event-Management: CRUD-Operationen für Events (Erstellen, Bearbeiten, Archivieren, Veröffentlichen).
• Gallery-Management: Hochladen, Moderieren, Featured-Setten von Photos; Thumbnail-Generierung.
• Member-Management: Hinzufügen/Entfernen von Event-Mitgliedern; Rollen (Admin, Member).
• Task & Emotion Management: Zuweisen von Tasks und Emotions zu Events; Overrides für Tenant-spezifische Bibliotheken.
• Settings-Management: Tenant-spezifische Einstellungen (Theme, Limits, Legal Pages).
• Billing & Purchases: Kaufen von Packages (pro Event oder Tenant); Ledger-Übersicht; Integration mit Stripe.
• Notifications: Push-Benachrichtigungen für neue Photos, Event-Updates, niedrigen Credit-Balance.
• Offline-Support: Caching von Events und Photos; Queuing von Uploads/Mutations mit Sync bei Online-Wiederkehr.
• Audit & Compliance: Logging kritischer Aktionen; ETag-basierte Conflict-Resolution; GDPR-konforme Datenlöschung.

Die App ist API-first und interagiert ausschließlich über den Backend-API-Endpunkt /api/v1/tenant/*.

Capabilities

Authentifizierung & Autorisierung

• OAuth2 Flow: Authorization Code + PKCE für sichere Token-Erfassung.
• Token-Management: Refresh-Tokens mit automatischer Rotation; Secure Storage (Keychain/Keystore).
• Tenant-Scoping: Alle Requests enthalten tenant_id aus Token; Backend-Policies enforcen Isolation.
• Roles: Unterstützung für tenant_admin (volle CRUD), member (read-only + Uploads).

Core Features

• Event Lifecycle:
  • Erstellen: Erfordert Package-Auswahl (Free oder Kauf); Slug-Generierung (unique pro Tenant).
  • Bearbeiten: Update von Datum, Ort, Tasks, Emotions, Join-Link.
  • Veröffentlichen: Generiert QR-Code und Share-Link; aktiviert Guest-PWA-Zugriff.
  • Archivieren: Soft-Delete mit Retention-Periode (GDPR); Credit-Rückerstattung optional.
• Photo Management:
  • Upload: Signed URLs für direkte S3-Uploads; automatisierte Thumbnail-Generierung.
  • Moderation: Approve/Reject/Feature; Bulk-Operations.
  • Analytics: Stats zu Likes, Views, Uploads pro Event.
• Task & Emotion System:
  • Bibliothek: Globale + Tenant-spezifische Tasks/Emotions.
  • Zuweisung: Drag-and-Drop zu Events; Fortschritts-Tracking.
• Billing Integration:
  • Package-Auswahl: Anzeige verfügbarer Packages und Kauf (Einmalkauf/Subscription).
  • Ledger: Historie von Package-Käufen und Nutzung.
  • Stripe-Checkout: Server-side Intent-Erstellung; Webhook-Handling für Confirmation.

Offline & Sync

• Service Worker: Cache von App-Shell, Events, Photos (Cache-Control: max-age=5min für dynamische Daten).
• Background Sync: Queued Mutations (z.B. Photo-Approvals) syncen bei Connectivity.
• Conflict Resolution: ETag/If-Match Headers; Optimistic Updates mit Rollback bei Conflicts.

Error Handling & UX

• Rate Limits: 429-Responses handhaben mit Retry-Logic und User-Feedback ("Zu viele Anfragen, versuche es später").
• Offline Mode: Degradiertes UI (Read-Only); Sync-Status-Indikator.
• i18n: react-i18next mit JSON (public/lang/{locale}/admin.json); de/en; Locale aus User-Profile oder URL-Prefix (/de/, /en/); Detection via LanguageDetector; RTL nicht in MVP.

API-Integration

Die App konsumiert den API-Contract aus docs/prp/03-api.md. Schlüssel-Endpunkte:

Auth

• POST /oauth/token: PKCE-Code für Access/Refresh-Token.
• POST /oauth/token/refresh: Token-Rotation.

Events

• GET /tenant/events: Liste (paginiert, filterbar nach Status/Datum).
• POST /tenant/events: Erstellen (validiert Tenant-Package und erstellt Event-Package).
• GET /tenant/events/{id}: Details inkl. Tasks, Stats, package_limits.
• PATCH /tenant/events/{id}: Update (ETag für Concurrency).
• DELETE /tenant/events/{id}: Archivieren.

Photos

• GET /tenant/events/{event_id}/photos?since={cursor}: Inkrementelle Liste.
• POST /tenant/events/{event_id}/photos: Metadata + signed Upload-URL.
• PATCH /tenant/photos/{id}: Moderation (approve, feature).
• DELETE /tenant/photos/{id}: Löschung mit Audit.

Tasks & Emotions

• GET /tenant/tasks: Tenant-Overrides + globale Bibliothek.
• POST /tenant/events/{id}/tasks: Zuweisung.
• Ähnlich für Emotions.

Settings

• GET /tenant/settings: Tenant-Konfig (Theme, Limits, Legal-Links).
• PATCH /tenant/settings: Update.

Billing

• GET /tenant/packages: Tenant-Packages und Limits.
• POST /tenant/purchases/intent: Stripe-Checkout-Session für Package erstellen.
• GET /api/v1/packages: Verfügbare Packages.

Pagination & Errors

• Standard: page, per_page (max 50 für Mobile).
• Errors: Parsen von { error: { code, message } }; User-freundliche Messages (z.B. "Package-Limit überschritten").

Non-Functional Requirements

• Performance: Ladezeiten < 2s; Lazy-Loading für Galleries.
• Sicherheit: Kein PII-Logging; Token-Expiration-Handling; CSRF-Schutz via PKCE.
• Accessibility: Framework7 ARIA-Support; Dark Mode (System-Preference).
• Testing: Unit-Tests für API-Calls; E2E-Tests für Flows (Cypress).

Für detaillierte UI-Seiten siehe pages-ui.md; für Settings siehe settings-config.md.