readme und docs von der tenant app hinzugefügt

2025-09-15 13:27:31 +02:00
parent 216ee063ff
commit 5fbb9cb240
8 changed files with 1366 additions and 0 deletions
--- a/docs/prp/tenant-app-specs/README.md
+++ b/docs/prp/tenant-app-specs/README.md
@@ -0,0 +1,43 @@
+# Detaillierte PRP für Tenant Admin App (Capacitor + Framework7)
+
+## Status
+- **Aktiv**: Erste Version (2025-09-13)
+- **Version**: 1.0.0
+- **Autor**: Sonoma (AI Architect)
+- **Supersedes**: docs/prp/06-tenant-admin-pwa.md (erweitert und detailliert)
+
+## Überblick
+Diese detaillierte Product Requirement Plan (PRP) beschreibt die Spezifikationen für die Tenant Admin App. Die App ist eine store-ready mobile Anwendung, die mit Capacitor für iOS und Trusted Web Activity (TWA) für Android gepackt wird. Die UI basiert auf Framework7 für ein natives Mobile-Erlebnis. Die App ermöglicht Tenant-Admins (z.B. Event-Organisatoren) die vollständige Verwaltung ihrer Events, Galerien, Mitglieder, Einstellungen und Käufe über eine API-first Backend-Integration.
+
+Die App ersetzt das frühere Filament-basierte Tenant-Panel und fokussiert auf Mobile-First-UX mit Offline-Fähigkeiten, Push-Notifications und sicherer Authentifizierung. Sie respektiert das Multi-Tenancy-Modell und GDPR-Anforderungen.
+
+## Kernziele
+- **Deliverables**: Voll funktionsfähige App mit CRUD-Operationen für Tenant-Ressourcen (Events, Photos, Tasks, etc.).
+- **UI/UX**: Framework7-Komponenten für konsistente, native Mobile-Interfaces (iOS/Android).
+- **Technologie-Stack**: React/Vite (Core), Framework7 (UI), Capacitor (Native), OAuth2 + PKCE (Auth).
+- **Distribution**: App Store (iOS), Google Play (Android), PWA-Install (Web).
+
+## Struktur dieser PRP
+- **README.md**: Dieser Überblick.
+- **functional-specs.md**: Funktionale Anforderungen, Capabilities und API-Integration.
+- **pages-ui.md**: Detaillierte Seitenbeschreibungen, Framework7-Komponenten und Wireframe-Ideen.
+- **settings-config.md**: App- und Tenant-spezifische Einstellungen, Capacitor-Plugins.
+- **capacitor-setup.md**: Packaging, Distribution und Native-Features.
+
+## Referenzen
+- **Haupt-PRP**: docs/prp/README.md
+- **Tenancy**: docs/prp/02-tenancy.md
+- **API**: docs/prp/03-api.md
+- **Bestehende Tenant PWA**: docs/prp/06-tenant-admin-pwa.md
+- **Addendum**: docs/prp-addendum-2025-09-08-tenant-admin-pwa.md
+- **ADR**: docs/adr/ADR-0006-tenant-admin-pwa.md
+- **Billing**: docs/prp/08-billing.md
+- **Glossar**: docs/prp/99-glossary.md
+
+## Änderungen und Erweiterungen
+Diese PRP erweitert die knappe Beschreibung in 06-tenant-admin-pwa.md um:
+- Spezifische Seiten und UI-Elemente mit Framework7.
+- Detaillierte Settings und Capacitor-Integration.
+- Mobile-spezifische Features wie Push-Notifications und Offline-Sync.
+
+Für Feedback oder Änderungen: Siehe TODO.md oder Issues.
--- a/docs/prp/tenant-app-specs/api-usage.md
+++ b/docs/prp/tenant-app-specs/api-usage.md
@@ -0,0 +1,257 @@
+# API-Nutzung der Tenant Admin App
+
+Diese Dokumentation beschreibt alle API-Endpunkte, die die Tenant Admin App mit der Backend-Hauptapp kommuniziert. Alle Requests sind tenant-scoped und erfordern JWT-Authentifizierung.
+
+## Authentifizierung
+
+### OAuth2 Flow (PKCE)
+- **Start**: `GET /oauth/authorize` (Browser-Redirect mit PKCE-Challenge)
+  - **Params**: `client_id`, `redirect_uri`, `scope=tenant:read tenant:write`, `state`, `code_challenge`, `code_challenge_method=S256`
+  - **Response**: Authorization Code
+
+- **Token Exchange**: `POST /oauth/token`
+  - **Body**: `grant_type=authorization_code`, `client_id`, `code`, `redirect_uri`, `code_verifier`
+  - **Response**: `{ access_token, refresh_token, expires_in, token_type }`
+  - **Headers**: `Content-Type: application/x-www-form-urlencoded`
+
+- **Token Refresh**: `POST /oauth/token`
+  - **Body**: `grant_type=refresh_token`, `client_id`, `refresh_token`
+  - **Response**: Neuer Access/Refresh-Token
+
+- **Token Validation**: `GET /api/v1/tenant/me`
+  - **Headers**: `Authorization: Bearer {access_token}`
+  - **Response**: `{ id, email, tenant_id, role, name }`
+
+## Dashboard
+
+### Stats laden
+- **GET /api/v1/tenant/dashboard**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Response**: `{ credits, active_events, new_photos, task_progress }`
+  - **Zweck**: Übersicht-Daten für Dashboard-Cards
+
+## Events
+
+### Events-Liste
+- **GET /api/v1/tenant/events**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Params**: 
+    - `page=1` (Pagination)
+    - `per_page=50` (max für Mobile)
+    - `status=draft|active|archived` (Filter)
+    - `search=query` (Suche in Titel/Ort)
+  - **Response**: `{ data: Event[], current_page, last_page, total }`
+  - **Event-Shape**: `{ id, title, date, location, status, photoCount, slug }`
+
+### Event erstellen
+- **POST /api/v1/tenant/events**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: `{ title, date, location, description }`
+  - **Response**: 201 Created mit erstelltem Event
+  - **Validierung**: Prüft Credit-Balance (1 Credit pro Event)
+
+### Event-Details
+- **GET /api/v1/tenant/events/{id}**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Response**: Erweitertes Event mit `{ tasks[], members, stats { likes, views, uploads } }`
+
+### Event updaten
+- **PATCH /api/v1/tenant/events/{id}**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`, `If-Match: {etag}`
+  - **Body**: Partial Event-Daten (title, date, location, description)
+  - **Response**: Updated Event
+
+### Event archivieren
+- **DELETE /api/v1/tenant/events/{id}**
+  - **Headers**: `Authorization: Bearer {token}`, `If-Match: {etag}`
+  - **Response**: 204 No Content (soft-delete)
+
+## Photos
+
+### Photos laden
+- **GET /api/v1/tenant/events/{event_id}/photos**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Params**: 
+    - `page=1`, `per_page=50`
+    - `status=pending|approved|rejected|featured`
+    - `sort=date|likes`
+    - `since=cursor` (für Infinite Scroll)
+  - **Response**: `{ data: Photo[], current_page, last_page }`
+  - **Photo-Shape**: `{ id, eventId, url, thumbnail, uploadedAt, status, likes, views, uploader, etag }`
+
+### Upload-URL anfordern
+- **POST /api/v1/tenant/events/{event_id}/photos**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: `{ file_name, description? }`
+  - **Response**: `{ id, upload_url (S3 signed), thumbnail_url }`
+
+### Photo moderieren
+- **PATCH /api/v1/tenant/photos/{id}**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`, `If-Match: {etag}`
+  - **Body**: `{ status: 'approved'|'rejected'|'featured', featured?, reason? }`
+  - **Response**: Updated Photo
+
+### Photo löschen
+- **DELETE /api/v1/tenant/photos/{id}**
+  - **Headers**: `Authorization: Bearer {token}`, `If-Match: {etag}`
+  - **Response**: 204 No Content
+
+## Members
+
+### Mitglieder laden
+- **GET /api/v1/tenant/events/{event_id}/members**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Params**: `page`, `per_page`, `status=pending|active|invited`
+  - **Response**: `{ data: Member[], current_page, last_page }`
+  - **Member-Shape**: `{ id, name, email, role, joinedAt, avatar?, status }`
+
+### Mitglied einladen
+- **POST /api/v1/tenant/events/{event_id}/members**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: `{ email, role: 'member'|'guest', name? }`
+  - **Response**: 201 Created, E-Mail wird versendet
+
+## Tasks
+
+### Tasks laden
+- **GET /api/v1/tasks**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Params**: 
+    - `global=true/false` (globale vs. tenant Tasks)
+    - `tenant_id=me` (nur eigene Tasks)
+    - `category=setup|photo|event|cleanup`
+  - **Response**: `{ data: Task[], global: boolean }`
+  - **Task-Shape**: `{ id, title, description?, category, isGlobal, tenantId?, createdAt, color? }`
+
+### Event-Tasks laden
+- **GET /api/v1/tenant/events/{event_id}/tasks**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Response**: `{ data: EventTask[], overall_progress }`
+  - **EventTask-Shape**: `{ id, eventId, taskId, task: Task, order, completed, assignedTo?, progress }`
+
+### Tasks bulk zuweisen
+- **POST /api/v1/tenant/events/{event_id}/tasks/bulk**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: `{ task_ids: string[], order: number[] }`
+  - **Response**: Updated EventTasks mit neuer Reihenfolge
+
+## Settings
+
+### Settings laden
+- **GET /api/v1/tenant/settings**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Response**: `{ primaryColor, tenantName, maxEventsPerMonth, enableTasks, enableEmotions, legalPages { impressumUrl, privacyUrl } }`
+
+### Settings updaten
+- **PATCH /api/v1/tenant/settings**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: Partial Settings-Daten
+  - **Response**: Updated Settings
+
+## Billing
+
+### Balance laden
+- **GET /api/v1/tenant/credits/balance**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Response**: `{ balance: number }`
+
+### Ledger-Verlauf
+- **GET /api/v1/tenant/ledger**
+  - **Headers**: `Authorization: Bearer {token}`
+  - **Params**: `page`, `per_page` (Pagination)
+  - **Response**: `{ data: LedgerEntry[], current_page, last_page }`
+  - **LedgerEntry**: `{ id, type, amount, credits, date, description, transactionId? }`
+
+### Kauf-Intent erstellen
+- **POST /api/v1/tenant/purchases/intent**
+  - **Headers**: `Authorization: Bearer {token}`, `Content-Type: application/json`
+  - **Body**: `{ package_id }`
+  - **Response**: `{ checkout_url: string }` (Stripe-Checkout)
+  - **Nach dem Kauf**: Webhook-Handling auf Backend für Balance-Update
+
+## Allgemeine Headers
+
+Alle API-Requests enthalten:
+- **Authorization**: `Bearer {access_token}` (JWT mit tenant_id)
+- **Content-Type**: `application/json` (für POST/PATCH)
+- **If-Match**: `{etag}` (für Concurrency-Control bei Updates)
+- **Accept**: `application/json`
+
+## Error-Handling
+
+**Standard-Error-Response:**
+```json
+{
+  "error": {
+    "code": "INSUFFICIENT_CREDITS",
+    "message": "Nicht genügend Credits verfügbar"
+  }
+}
+```
+
+**HTTP Status Codes:**
+- 200: Erfolg
+- 201: Created
+- 400: Bad Request (Validierungsfehler)
+- 401: Unauthorized (Token-Refresh wird versucht)
+- 403: Forbidden (RBAC-Verletzung)
+- 404: Not Found
+- 422: Unprocessable Entity
+- 429: Rate Limited (Client retry mit Backoff)
+
+## Pagination
+
+Alle Listen-Endpunkte unterstützen:
+- **page**: Aktuelle Seite (default 1)
+- **per_page**: Einträge pro Seite (default 20, max 50 für Mobile)
+- **Response**: `{ data: [], current_page, last_page, per_page, total }`
+
+## Headers für Concurrency
+
+Mutierende Endpunkte (PATCH/DELETE) erfordern:
+- **If-Match**: `{etag}` aus GET-Response
+- **Response**: 412 Precondition Failed bei Conflict
+
+## Sicherheit
+
+- **Tenant-Isolation**: Alle Endpunkte prüfen JWT-tenant_id gegen request tenant_id
+- **RBAC**: Nur tenant_admin kann mutieren, member kann nur lesen/hochladen
+- **Rate Limiting**: 100 Requests/Minute pro Tenant
+- **ETag**: Automatische Concurrency-Control
+- **No PII-Logging**: Keine sensiblen Daten in Logs
+
+## Testing
+
+### API-Test-Setup
+1. **Backend starten**: Stelle sicher, dass die Hauptapp läuft und Endpunkte verfügbar sind.
+2. **Token erzeugen**: Verwende Postman mit gültigem Access-Token.
+3. **Endpoints testen**: Jeder Endpunkt einzeln mit curl oder Postman.
+
+### Beispiel curl (mit Token)
+```bash
+curl -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  https://api.fotospiel.com/api/v1/tenant/events
+```
+
+### Frontend-Test
+1. `.env` mit korrekter API-URL konfigurieren.
+2. `npm run dev` starten.
+3. Browser-Network-Tab überprüfen für API-Calls.
+
+## Deployment
+
+### Environment-Variablen
+- **REACT_APP_API_URL**: Backend-API-URL (Pflicht)
+- **REACT_APP_OAUTH_CLIENT_ID**: OAuth-Client-ID (Pflicht)
+
+### Build & Deploy
+1. **Development**: `npm run dev`
+2. **Production**: `npm run build`
+3. **Vorschau**: `npm run preview`
+
+### PWA-Installation
+- App ist PWA-fähig (Manifest, Service Worker).
+- Installierbar auf Desktop/Mobile via "Zum Startbildschirm hinzufügen".
+
+Für weitere Details siehe die spezifischen Dokumentationsdateien.
--- a/docs/prp/tenant-app-specs/capacitor-setup.md
+++ b/docs/prp/tenant-app-specs/capacitor-setup.md
@@ -0,0 +1,155 @@
+# Capacitor Setup für die Tenant Admin App
+
+## Status
+- **Version**: 1.0.0 (2025-09-13)
+- **Fokus**: Mobile Packaging, Distribution und Native-Integration basierend auf ADR-0006.
+
+## Überblick
+Die Tenant Admin App wird als Progressive Web App (PWA) entwickelt und mit Capacitor für native Mobile-Distribution gepackt. Dies ermöglicht:
+- **Android**: Trusted Web Activity (TWA) für Chrome-basierte Installation (Google Play) oder voller Capacitor-Build bei Bedarf an Native APIs.
+- **iOS**: Capacitor-App für App Store-Distribution mit Push-Notifications und Keychain-Support.
+- **Web/PWA**: Fallback für Browser-Installation (A2HS) mit Service Worker.
+
+Der Build-Prozess integriert sich in das bestehende Vite-Setup (resources/js/admin). Nach `npm run build` wird `npx cap sync` ausgeführt, um die Web-Assets in native Projekte zu kopieren.
+
+## Projektstruktur
+```
+apps/admin-pwa/          # React/Vite Source (Haupt-App)
+├── src/                 # Components, Pages, API
+├── vite.config.ts       # Framework7 + Capacitor-Integration
+├── capacitor.config.ts  # Native Config
+├── android/             # Capacitor Android-Projekt (TWA oder App)
+├── ios/                 # Capacitor iOS-Projekt (Xcode)
+└── package.json         # Dependencies (framework7, @capacitor/*)
+
+packages/mobile/         # Shared Native-Config (optional)
+├── fastlane/            # iOS/Android Deployment
+├── assetlinks.json      # TWA Digital Asset Links
+└── privacy-manifest.json # iOS Privacy
+```
+
+## Packaging und Build-Prozess
+
+### 1. Vite + Framework7 Setup
+- **Dependencies**: `framework7`, `framework7-react`, `@capacitor/core`, `@capacitor/cli`.
+- **vite.config.ts** (Auszug):
+  ```typescript
+  import { defineConfig } from 'vite';
+  import react from '@vitejs/plugin-react';
+  import { framework7 } from 'framework7/vite';
+
+  export default defineConfig({
+    plugins: [react(), framework7()],
+    build: {
+      outDir: 'dist',
+      sourcemap: true,
+    },
+    define: {
+      __CAPACITOR__: true, // Enable Capacitor globals
+    },
+  });
+  ```
+- **Build-Skript** (package.json): `"build": "vite build && npx cap sync"`.
+
+### 2. Capacitor Initialisierung
+- **Befehle**:
+  ```
+  npx cap init com.fotospiel.tenantadmin "Event Photo Admin"
+  npx cap add android
+  npx cap add ios
+  npx cap sync  # Kopiert dist/ in native Projekte
+  ```
+- **capacitor.config.ts** (siehe settings-config.md für erweiterte Plugins).
+
+### 3. Android Packaging (TWA bevorzugt)
+- **Trusted Web Activity (TWA)**: Für store-ready Distribution ohne vollen Native-Wrapper.
+  - **Voraussetzungen**: App bound an `admin.fotospiel.app` (HTTPS); Digital Asset Links.
+  - **assetlinks.json** (public/.well-known/assetlinks.json):
+    ```json
+    [{
+      "relation": ["delegate_permission/common.handle_all_urls"],
+      "target": {
+        "namespace": "android_app",
+        "package_name": "com.fotospiel.tenantadmin",
+        "sha256_cert_fingerprints": ["DE:AD:BE:EF:..."]  // Von Play Console
+      }
+    }]
+    ```
+  - **Build**: `npx cap open android` → Android Studio → Generate Signed Bundle (AAB für Play Store).
+  - **Vorteile**: Kleiner Footprint, Web-Push via Chrome; Fallback zu Capacitor bei Bedarf (z.B. Biometrie).
+  - **TWA-Tools**: `npm i -g @bubblewrap/cli` → `bubblewrap init --manifest=https://admin.fotospiel.app/manifest.json`.
+
+- **Vollständiger Capacitor-Build** (falls Native-Plugins benötigt):
+  - `npx cap sync android`
+  - `npx cap open android` → Build APK/AAB mit ProGuard.
+
+### 4. iOS Packaging (Capacitor)
+- **Xcode-Setup**: `npx cap open ios` → Signing mit Apple Developer Account.
+- **Privacy Manifest** (ios/App/App/PrivacyInfo.xcprivacy):
+  ```xml
+  <?xml version="1.0" encoding="UTF-8"?>
+  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+  <plist version="1.0">
+  <dict>
+      <key>NSPrivacyAccessedAPITypes</key>
+      <array>
+          <dict>
+              <key>NSPrivacyAccessedAPIType</key>
+              <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+              <key>NSPrivacyAccessedAPITypeReasons</key>
+              <array>
+                  <string>CA92.1</string>  <!-- Preferences für Settings -->
+              </array>
+          </dict>
+          <!-- Push, Camera, etc. -->
+      </array>
+  </dict>
+  </plist>
+  ```
+- **Build**: Archive in Xcode → Upload zu App Store Connect.
+- **Entitlements**: Push-Notifications (APNs), Background App Refresh für Sync.
+
+### 5. Distribution und CI/CD
+- **Google Play**:
+  - **TWA**: Internal Testing Track; Target SDK 34+; Feature: Installable.
+  - **Fastlane**: `packages/mobile/fastlane/android` mit `supply` für Metadata/Screenshots.
+  - **Versioning**: Align mit Backend (z.B. 1.0.0); Feature Flags via API.
+
+- **Apple App Store**:
+  - **Capacitor**: Review-Guidelines beachten (HTTPS-only, No Crash-Reporting ohne Consent).
+  - **Fastlane**: `packages/mobile/fastlane/ios` mit `deliver` für Upload.
+  - **Privacy**: Usage Descriptions in Info.plist (z.B. "Kamera für QR-Scans").
+
+- **PWA-Fallback** (Web):
+  - **manifest.json**: `start_url: '/admin/'`, `display: 'standalone'`.
+  - **Service Worker**: Caching von Assets; Background Sync für Mutations.
+  - **Distribution**: Hosting auf `admin.fotospiel.app` mit A2HS-Prompt.
+
+### Native Features (Erweiterung zu settings-config.md)
+- **Push-Notifications**:
+  - **Android**: FCM-Integration; Token an Backend (`POST /tenant/push-tokens`).
+  - **iOS**: APNs; Silent-Pushes für Sync-Triggers.
+  - **Cross-Platform**: Capacitor Push-Plugin handhabt Plattform-Unterschiede.
+
+- **Secure Storage**:
+  - **Tokens**: Capacitor Preferences mit Auto-Encryption.
+  - **Offline Data**: IndexedDB (Web) + Native Storage; Encryption via Web Crypto API.
+
+- **Background Processing**:
+  - **Sync**: Capacitor App-State-Listener für Foreground/Background; Queue Mutations.
+  - **iOS**: Background Fetch (via Plugin); Android: WorkManager für periodische Syncs.
+
+- **Biometrie (optional)**: `@capacitor-community/biometric-auth` für App-Lock.
+
+### Testing und Deployment
+- **E2E-Tests**: Cypress für Web; Detox/Appium für Native (z.B. Push-Handling).
+- **CI/CD**: GitHub Actions oder Gogs-Integration (siehe docs/prp/11-ops-ci-cd.md).
+  - Steps: Build → Test → Cap Sync → Fastlane Deploy (Staging → Production).
+- **Version Alignment**: App-Version matcht Backend-API-Version; Changelog in Store-Listing.
+
+### Constraints & Red-Lines
+- **GDPR**: Keine implizite Tracking; Explizite Consent für Push/Camera.
+- **Security**: HTTPS-only; Token-Rotation alle 24h; No Jailbreak-Detection.
+- **Performance**: Bundle-Size < 10MB (Web-Assets komprimiert); Lazy-Loading.
+
+Diese Setup ergänzt die funktionalen Specs und UI-Beschreibungen. Für Repo-Integration siehe ADR-0006.
--- a/docs/prp/tenant-app-specs/functional-specs.md
+++ b/docs/prp/tenant-app-specs/functional-specs.md
@@ -0,0 +1,100 @@
+# 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.
--- a/docs/prp/tenant-app-specs/pages-ui.md
+++ b/docs/prp/tenant-app-specs/pages-ui.md
@@ -0,0 +1,186 @@
+# Seiten und UI-Design für die Tenant Admin App
+
+## Status
+- **Version**: 1.0.0 (2025-09-13)
+- **Fokus**: Mobile-First Design mit Framework7 v8+ für native iOS/Android-Look & Feel.
+
+## Allgemeines UI-Prinzipien
+- **Framework7-Komponenten**: Toolbar (Navigation), List (Datenlisten), Card (Karten für Events/Photos), Modal (Details/Actions), Pull-to-Refresh (Sync), Infinite-Scroll (Pagination).
+- **Theming**: System-Dark-Mode-Support; Tenant-spezifische Farben (Primary/Secondary aus Settings).
+- **Navigation**: Tabbar unten (Dashboard, Events, Photos, Settings); Side-Menu für Profile/Logout.
+- **Offline-Indikator**: Banner oben ("Offline-Modus: Änderungen werden synchronisiert").
+- **Loading**: Spinner für API-Calls; Skeleton-Screens für Listen.
+- **i18n**: Rechts-nach-Links für de/en; Icons von Framework7-Icons (Material).
+
+## Benötigte Seiten und Komponenten
+
+### 1. Auth-Seiten (OAuth-Flow)
+#### Login-Seite
+- **Zweck**: OAuth-Authorization (PKCE-Challenge generieren, Redirect zu /oauth/authorize).
+- **Layout**: 
+  - Zentrale Card mit Logo, App-Name, "Mit Google/Email anmelden"-Buttons.
+  - Footer: "Noch kein Account? Registrieren" (Redirect zu Register).
+- **Framework7-Komponenten**:
+  - `f7-page` mit `f7-navbar` (Titel: "Willkommen zur Event Photo App").
+  - `f7-block` für Content; `f7-button` (large, filled) für OAuth-Start.
+  - `f7-preloader` während Redirect.
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Logo | Willkommen]
+  [Block: App-Beschreibung]
+  [Button: Anmelden mit Google]
+  [Button: Anmelden mit Email]
+  [Footer: Registrieren-Link]
+  ```
+- **API**: Kein direkter Call; Browser-Redirect zu Backend.
+
+#### Register-Seite (ähnlich Login)
+- **Unterschiede**: Form für Email/Password + Terms-Checkbox; Submit zu `/oauth/register`.
+
+### 2. Dashboard (Home)
+- **Zweck**: Übersicht über aktive Events, Stats, schnelle Actions.
+- **Layout**: 
+  - Top: Willkommens-Banner mit Tenant-Name, Credit-Balance.
+  - Stats-Cards: Aktive Events, Ungeprüfte Photos, Tasks-Fortschritt.
+  - Quick-Actions: "Neues Event erstellen", "Photos moderieren".
+- **Framework7-Komponenten**:
+  - `f7-toolbar` unten: Tabs (Home, Events, Photos, Settings).
+  - `f7-card` für Stats (mit `f7-icon` und Zahlen).
+  - `f7-list` für Quick-Actions (link mit Arrow).
+  - `f7-pull-to-refresh` für Sync.
+- **Wireframe-Beschreibung**:
+  ```
+  [Toolbar: Home | Events | Photos | Settings]
+  [Banner: Hallo [Name]! 3 Credits übrig]
+  [Row: Card(Events: 2 aktiv) | Card(Photos: 15 neu) | Card(Tasks: 80%)]
+  [List: > Neues Event | > Moderieren | > Einstellungen]
+  ```
+- **API**: `GET /tenant/dashboard` (Stats); `GET /tenant/credits/balance`.
+
+### 3. Events-Übersicht
+- **Zweck**: Liste aller Events mit Filter (aktiv/archiviert), Suche.
+- **Layout**: 
+  - Navbar: Suche-Feld, Filter-Button (Dropdown: Status, Datum).
+  - Infinite-Scroll-Liste von Event-Cards (Titel, Datum, Status-Tag, Photo-Count).
+  - FAB: "+" für Neues Event.
+- **Framework7-Komponenten**:
+  - `f7-searchbar` in Navbar.
+  - `f7-list` mit `f7-list-item` (Thumbnail, Title, Subtitle: Datum, Badge: Status).
+  - `f7-fab` (floating action button).
+  - `f7-segmented` für Filter-Tabs.
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Suche | Filter ▼]
+  [Segmented: Alle | Aktiv | Archiviert]
+  [List-Item: [Thumb] Hochzeit Müller (15.09.) [Tag: Aktiv] 45 Photos]
+  [List-Item: ...]
+  [+ FAB unten rechts]
+  ```
+- **API**: `GET /tenant/events?page=1&status=active` (paginiert).
+
+### 4. Event-Details-Seite
+- **Zweck**: Vollständige Event-Info, Edit-Modus, zugehörige Tasks/Photos.
+- **Layout**: 
+  - Tabs: Details, Tasks, Photos, Members, Stats.
+  - Edit-Button (öffnet Modal für Update).
+  - QR-Code-Section für Join-Link.
+- **Framework7-Komponenten**:
+  - `f7-tabs` mit `f7-tab` für Subseiten.
+  - `f7-card` für Details (Datum, Ort, Beschreibung).
+  - `f7-qrcode` (via Plugin) für Share-Link.
+  - `f7-button` (edit-icon) → `f7-modal` mit Form.
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Event-Titel | Edit-Icon]
+  [Tabs: Details | Tasks | Photos | Members | Stats]
+  [Details-Tab: Card(Datum: 15.09., Ort: Berlin) | QR-Code: Scan zum Beitreten]
+  [Tasks-Tab: Checklist (Drag-to-reorder)]
+  [Photos-Tab: Grid von Thumbs]
+  ```
+- **API**: `GET /tenant/events/{id}`; `PATCH /tenant/events/{id}` (ETag).
+
+### 5. Photo-Gallery-Seite (pro Event)
+- **Zweck**: Moderation von Photos; Grid-View mit Lightbox.
+- **Layout**: 
+  - Filter: Neu/Ungeprüft/Featured; Sortierung (Datum, Likes).
+  - Masonry-Grid von Photo-Cards (Thumb, Timestamp, Like-Count).
+  - Long-Press: Multi-Select für Bulk-Actions (Approve/Delete).
+- **Framework7-Komponenten**:
+  - `f7-photoset` oder custom Grid mit `f7-card` (small).
+  - `f7-lightbox` für Fullscreen-View.
+  - `f7-checkbox` für Multi-Select.
+  - `f7-popover` für Actions (Approve, Feature, Delete).
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Photos (Event) | Filter ▼]
+  [Grid: 3xN Cards [Thumb | Zeit | Likes] [Checkbox]]
+  [Lightbox: Fullscreen Photo mit Zoom, Actions]
+  [Bottom-Bar (bei Select): Approve All | Delete Selected]
+  ```
+- **API**: `GET /tenant/events/{id}/photos`; `PATCH /tenant/photos/{id}` (Batch).
+
+### 6. Members-Seite
+- **Zweck**: Verwalten von Event-Mitgliedern (Hinzufügen per Email, Rollen).
+- **Layout**: Liste von User-Cards (Name, Rolle, Joined-At); Invite-Button.
+- **Framework7-Komponenten**:
+  - `f7-list` mit `f7-list-item` (Avatar, Name, Badge: Rolle).
+  - `f7-modal` für Invite-Form (Email-Input, Send-Button).
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Members | + Invite]
+  [List: Anna (Admin) | Ben (Member) | ...]
+  [Modal: Email eingeben | Rolle wählen | Senden]
+  ```
+- **API**: `GET /tenant/events/{id}/members`; `POST /tenant/events/{id}/members`.
+
+### 7. Tasks-Seite
+- **Zweck**: Bibliothek verwalten, zu Events zuweisen, Fortschritt tracken.
+- **Layout**: Tabs: Meine Tasks, Bibliothek; Drag-and-Drop zwischen Listen.
+- **Framework7-Komponenten**:
+  - `f7-tabs`; `f7-sortable-list` für Drag-and-Drop.
+  - `f7-checkbox` für Zuweisung.
+- **Wireframe-Beschreibung**:
+  ```
+  [Tabs: Events | Bibliothek]
+  [Sortable List: Task1 [Checkbox] | Task2 ...]
+  [Drag: Von Bibliothek zu Event-Liste]
+  ```
+- **API**: `GET /tenant/tasks`; `POST /tenant/events/{id}/tasks`.
+
+### 8. Settings-Seite
+- **Zweck**: Tenant-Einstellungen bearbeiten (Theme, Limits, Legal).
+- **Layout**: Accordion-Sections (Theme, Notifications, Legal, App).
+- **Framework7-Komponenten**:
+  - `f7-accordion` für Sections.
+  - `f7-toggle`, `f7-select`, `f7-color-picker` für Optionen.
+- **Wireframe-Beschreibung**:
+  ```
+  [Navbar: Einstellungen]
+  [Accordion: Theme ▼ [Color-Picker] | Notifications [Toggle Push]]
+  [Legal: Impressum-Link bearbeiten]
+  [App: Logout-Button]
+  ```
+- **API**: `GET/PATCH /tenant/settings`. Details in settings-config.md.
+
+### 9. Billing-Seite
+- **Zweck**: Credit-Balance anzeigen, Packs kaufen.
+- **Layout**: Balance-Card; Liste von Purchase-Options; Ledger-Historie.
+- **Framework7-Komponenten**:
+  - `f7-card` für Balance (mit Warning bei niedrig).
+  - `f7-list` für Packs (Preis, Events-Count, Buy-Button).
+  - `f7-infinite-scroll` für Ledger.
+- **Wireframe-Beschreibung**:
+  ```
+  [Card: Balance: 3 Credits | [Warning: Niedrig!]]
+  [List: 5 Events (29€) [Buy] | 10 Events (49€) [Buy]]
+  [Ledger: Kauf 29.09. +5 | Event-Erstellung -1]
+  ```
+- **API**: `GET /tenant/credits/balance`; `POST /tenant/purchases/intent`.
+
+## Zusätzliche UI-Elemente
+- **Modals**: Confirm-Delete, Photo-Preview, Error-Alerts.
+- **Notifications**: `f7-notification` für Sync-Erfolg, neue Photos.
+- **Offline-Handling**: `f7-block` mit "Syncing..." Progress-Bar.
+- **Accessibility**: ARIA-Labels für alle interaktiven Elemente; VoiceOver-Support.
+
+Für Capacitor-spezifische UI-Anpassungen siehe capacitor-setup.md.
--- a/docs/prp/tenant-app-specs/settings-config.md
+++ b/docs/prp/tenant-app-specs/settings-config.md
@@ -0,0 +1,124 @@
+# Settings und Konfiguration für die Tenant Admin App
+
+## Status
+- **Version**: 1.0.0 (2025-09-13)
+- **Fokus**: App-interne und tenant-spezifische Einstellungen; Integration mit Capacitor-Plugins.
+
+## App-interne Settings
+Diese Settings werden lokal in der App gespeichert (via Capacitor Preferences oder IndexedDB) und beeinflussen das Verhalten der App:
+
+### Core App Settings
+- **language**: String (default: 'de') – UI-Sprache; Sync mit User-Locale.
+- **themeMode**: String ('system' | 'light' | 'dark') – Dark Mode-Präferenz; Framework7-Theming.
+- **offlineMode**: Boolean (default: true) – Aktiviert Offline-Caching und Background-Sync.
+- **pushNotifications**: Boolean (default: true) – Erlaubt Push-Registrierung.
+- **autoSyncInterval**: Number (default: 300) – Sekunden bis automatischer Sync (min: 60).
+- **maxPhotoCache**: Number (default: 100) – Anzahl gecachter Photos pro Event.
+
+### User-spezifische Settings
+- **notificationPreferences**: Object
+  - `newPhotos`: Boolean – Benachrichtigung bei neuen Uploads.
+  - `eventUpdates`: Boolean – Bei Event-Änderungen (z.B. Veröffentlicht).
+  - `lowCredits`: Boolean – Warnung bei < 2 Credits.
+- **privacySettings**: Object
+  - `shareAnalytics`: Boolean (default: false) – Anonyme Stats teilen.
+  - `dataRetention`: Number (default: 30) – Tage bis Auto-Delete von Cache.
+
+**Speicherung**: Capacitor Preferences API (`@capacitor/preferences`) für sichere, persistente Speicherung. Bei Web-Fallback: localStorage mit Encryption (via Crypto API).
+
+## Tenant-spezifische Optionen
+Diese werden über API (`GET/PATCH /tenant/settings`) geladen und überschreiben globale Defaults. Sie definieren das Verhalten für den Tenant und seine Events:
+
+### Theme & Branding
+- **primaryColor**: String (default: '#007AFF') – Hauptfarbe (iOS-Blau); verwendet in Framework7 CSS-Vars (`--f7-primary`).
+- **secondaryColor**: String (default: '#5856D6') – Sekundärfarbe für Buttons/Accents.
+- **logoUrl**: String – Custom Logo für App-Banner (URL zu S3/CDN).
+- **tenantName**: String – Anzeigename (z.B. "Müller Hochzeit"); in Dashboard-Banner.
+
+### Event Limits & Features
+- **maxEventsPerMonth**: Number (default: 5) – Limit pro Monat (enforced via Credits).
+- **maxPhotosPerEvent**: Number (default: 1000) – Soft-Limit; Warnung bei Überschreitung.
+- **enableTasks**: Boolean (default: true) – Tasks-System aktivieren.
+- **enableEmotions**: Boolean (default: true) – Emotions/Reactions erlauben.
+- **autoApprovePhotos**: Boolean (default: false) – Neue Uploads sofort freigeben (Risiko: Spam).
+
+### Legal & Compliance
+- **legalPages**: Object (von Backend geladen, siehe docs/prp/02-tenancy.md)
+  - `impressumUrl`: String – Pflicht in DE; Customizable Link.
+  - `privacyUrl`: String – Datenschutzerklärung.
+  - `agbUrl`: String – Allgemeine Geschäftsbedingungen.
+- **gdprRetentionDays**: Number (default: 30) – Automatische Löschung alter Photos/Events.
+- **contactEmail**: String – Support-Email für In-App-Feedback.
+
+### Notifications & Integration
+- **pushEnabled**: Boolean – Tenant-weit Push aktivieren (erfordert Plugin-Registrierung).
+- **stripePublicKey**: String – Für Client-side Checkout (aus Env, nicht persistent).
+- **eventJoinDomain**: String (default: 'events.fotospiel.app') – Custom Domain für Guest-PWA.
+
+**API-Handling**: Laden bei Login; Cache mit ETag; Update triggert UI-Refresh (z.B. Theme-Wechsel). Validation: Backend enforct Limits (z.B. Colors als HEX).
+
+## Capacitor-Plugins
+Die App integriert folgende Plugins für native Features. Installation via `npx cap add` und Sync nach Build.
+
+### Essentielle Plugins
+1. **@capacitor/preferences** (v6+)
+   - **Zweck**: Sichere Speicherung von App- und User-Settings.
+   - **Usage**: `Preferences.set({ key: 'themeMode', value: 'dark' })`; Migrate von localStorage.
+   - **iOS/Android**: Keychain/Keystore für Encryption.
+
+2. **@capacitor/push-notifications** (v6+)
+   - **Zweck**: Native Push für neue Photos, Event-Updates, Low-Credits.
+   - **Setup**: Registrierung bei App-Start (`PushNotifications.register()`); Token an Backend senden (`POST /tenant/devices`).
+   - **Events**: `registrationToken` (senden), `pushNotificationReceived` (In-App-Handling), `pushNotificationActionPerformed` (Tap-Actions).
+   - **Permissions**: Request bei erstem Login; Fallback zu Web Push in PWA/TWA.
+
+3. **@capacitor/storage** (v6+)
+   - **Zweck**: Offline-Caching von Events/Photos (als Alternative zu IndexedDB).
+   - **Usage**: `Storage.set({ key: 'event-123', value: JSON.stringify(data) })`; Size-Limit beachten (50MB).
+   - **Fallback**: Für Web; Sync mit Background-Sync.
+
+4. **@capacitor/camera** (v6+)
+   - **Zweck**: Direkte Kamera-Zugriff für Event-QR-Scans oder schnelle Photo-Uploads (Admin-Selfies).
+   - **Usage**: `Camera.getPhoto({ quality: 90, allowEditing: true })`; Upload via signed URL.
+   - **Permissions**: Camera/Mic; Privacy-Manifest für App Store.
+
+5. **@capacitor/network** (v6+)
+   - **Zweck**: Connectivity-Status überwachen; Offline-Modus triggern.
+   - **Usage**: `Network.addListener('networkStatusChange', handleOffline)`; UI-Update bei 'offline'.
+   - **Integration**: Deaktiviere Sync-Buttons; Zeige Cached-Data.
+
+### Optionale Plugins
+- **@capacitor/haptics** (v6+): Vibration-Feedback bei Actions (z.B. Photo-Approve).
+- **@capacitor/share** (v6+): Teilen von Event-QR-Codes via Native Share-Sheet.
+- **@capacitor/device** (v6+): Geräte-Info (Model, OS) für Analytics; Token zu Backend.
+
+### Plugin-Konfiguration (capacitor.config.ts)
+```typescript
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.fotospiel.tenantadmin',
+  appName: 'Event Photo Admin',
+  webDir: 'dist',
+  bundledWebRuntime: false,
+  plugins: {
+    PushNotifications: {
+      presentationOptions: ["badge", "sound", "alert"]
+    },
+    Camera: {
+      permissions: {
+        camera: true
+      }
+    }
+  }
+};
+
+export default config;
+```
+
+### Security & Privacy
+- **Plugin-Permissions**: Explizite Requests; Erkläre Zweck im Onboarding (z.B. "Push für neue Photos").
+- **Data Storage**: Kein PII in Preferences; Tokens encrypted (siehe Auth-Specs).
+- **App Store Compliance**: Privacy Manifest mit Usage-Descriptions (z.B. NSPhotoLibraryUsageDescription).
+
+Für detailliertes Packaging siehe capacitor-setup.md; UI-Integration in pages-ui.md.