soeren/fotospiel-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- Reworked the tenant admin login page

Browse Source 
- Updated the User model to implement Filament’s tenancy contracts
- Seeded a ready-to-use demo tenant (user, tenant, active package, purchase)
- Introduced a branded, translated 403 error page to replace the generic forbidden message for unauthorised admin hits
- Removed the public “Register” links from the marketing header
- hardened join event logic and improved error handling in the guest pwa.
This commit is contained in:
Codex Agent
2025-10-13 12:50:46 +02:00
parent 9394c3171e
commit 64a5411fb9
69 changed files with 5447 additions and 588 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
docs/prp/tenant-app-specs/functional-specs.md
View File

@@ -1,100 +1,87 @@
# Funktionale Spezifikationen für die Tenant Admin App
# Funktionale Spezifikationen – 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
- **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 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/*`.
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, Stripe/PayPal 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 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).
- 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).
### 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.
### Onboarding Journey
- Routen `/event-admin/welcome/*` bilden den Flow.
- `useOnboardingProgress` persistiert Fortschritt (localStorage) und synchronisiert mit Backend (`onboarding_completed_at`).
- Paketwahl nutzt `GET /tenant/packages`; Stripe/PayPal-Fallbacks informieren bei fehlender Konfiguration.
- Dashboard weist per CTA auf offenes Onboarding hin, bis ein erstes Event erstellt wurde.
### 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.
### Event Lifecycle
- Erstellung prüft Paketverfügbarkeit; generiert Join-Token.
- Bearbeiten erlaubt Statuswechsel, Aufgaben, Emotions, Join-Token-Verwaltung.
- Veröffentlichen schaltet Guest-PWA frei; Archivieren respektiert Retention-Policy.
### 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.
### 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
- `GET /tenant/tasks`: Tenant-Overrides + globale Bibliothek.
- `POST /tenant/events/{id}/tasks`: Zuweisung.
- Ähnlich für Emotions.
- Globale + Tenant-spezifische Bibliothek.
- Drag-and-Drop Zuweisung, Fortschritt je Event, Emotion-Tagging.
### Billing & Checkout
- Pakete + Credit-Balance anzeigen.
- Stripe PaymentIntent & PayPal Smart Buttons; Fallback-Meldung bei fehlender Konfiguration.
- Ledger mit Historie (Paginierung, Filter).
### Settings
- `GET /tenant/settings`: Tenant-Konfig (Theme, Limits, Legal-Links).
- `PATCH /tenant/settings`: Update.
- Branding (Logo, Farben), Domain/Links, Legal Pages.
- Notification Preferences, Paketlimits, Onboarding-Reset.
### 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.
### 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.
### 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").
### 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`.
## 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).
## API-Integration
Die App nutzt Endpunkte aus `docs/prp/03-api.md`.
Für detaillierte UI-Seiten siehe pages-ui.md; für Settings siehe settings-config.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 Stripe/PayPal Happy Paths und Offline/Retry geplant.
- **Smoke Tests**: `npm run test:e2e` in CI mit optionalen Credentials (`E2E_TENANT_EMAIL`, `E2E_TENANT_PASSWORD`, Stripe/PayPal 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.