# 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 Event-Credits; 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 mind. 1 Event-Credit; 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**:
  - Credit-Balance: Anzeige und Kauf von Packs (z.B. 5 Events für 29€).
  - Ledger: Historie von Käufen, Consumptions, Refunds.
  - 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**: Unterstützung für de/en; Locale aus User-Profile.

## 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 Credit-Balance).
- `GET /tenant/events/{id}`: Details inkl. Tasks, Stats.
- `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/ledger`: Credit-Historie.
- `POST /tenant/purchases/intent`: Stripe-Checkout-Session erstellen.
- `GET /tenant/credits/balance`: Aktueller Stand.

### Pagination & Errors
- Standard: `page`, `per_page` (max 50 für Mobile).
- Errors: Parsen von `{ error: { code, message } }`; User-freundliche Messages (z.B. "Nicht genug Credits").

## 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.