fotospiel-app/docs/archive/implementation-roadmap.md

Update 2025-10-21

• Phase 3 credit scope delivered: tenant event creation now honours package allowances and credit balances (middleware + ledger logging), RevenueCat webhook signature checks ship with queue/backoff + env config, idempotency covered via unit tests.
• Follow-up (separate): evaluate photo upload quota enforcement + SuperAdmin ledger visualisations once package analytics stabilise.

Upcoming (Next Weeks — Security Hardening)

• Week 1
  • SEC-IO-01 dual-key rollout playbook.
  • SEC-GT-01 hashed join tokens migration.
  • SEC-API-01 signed asset URLs.
  • SEC-MS-01 AV/EXIF worker integration.
  • SEC-BILL-01 checkout session linkage.
  • SEC-FE-01 CSP nonce utility.
• Week 2
  • SEC-IO-02 refresh-token management UI. (delivered 2025-10-23)
  • SEC-GT-02 token analytics dashboards.
  • SEC-API-02 incident response playbook.
  • SEC-MS-02 streaming upload refactor.
  • SEC-BILL-02 webhook signature freshness.
  • SEC-FE-02 consent-gated analytics loader.
• Week 3
  • SEC-IO-03 subnet/device configuration.
  • SEC-GT-03 gallery rate-limit alerts.
  • SEC-API-03 synthetic monitoring.
  • SEC-MS-03 checksum validation alerts.
  • SEC-BILL-03 failed capture notifications.
  • SEC-FE-03 cookie banner localisation refresh.
• Week 4
  • SEC-MS-04 storage health dashboard widget (Media Services).

Backend-Erweiterung Implementation Roadmap (Aktualisiert: 2025-09-15 - Fortschritt)

Implementierungsstand (Aktualisiert: 2025-09-15)

Basierend auf aktueller Code-Analyse und Implementierung:

• Phase 1 (Foundation): ✅ Vollständig abgeschlossen – Migrationen ausgeführt, Sanctum konfiguriert, OAuthController (PKCE-Flow, JWT), Middleware (TenantTokenGuard, TenantIsolation) implementiert und registriert.
• Phase 2 (Core API): ✅ 100% abgeschlossen – EventController (CRUD, Credit-Check, Search, Bulk), PhotoController (Upload, Moderation, Stats, Presigned Upload), TaskController (CRUD, Event-Assignment, Bulk-Operations, Search), SettingsController (Branding, Features, Custom Domain, Domain-Validation), Request/Response Models (EventStoreRequest, PhotoStoreRequest, TaskStoreRequest, TaskUpdateRequest, SettingsStoreRequest), Resources (TaskResource, EventTypeResource), File Upload Pipeline (local Storage, Thumbnails via ImageHelper), API-Routen erweitert, Feature-Tests (21 Tests, 100% Coverage), TenantModelTest (11 Unit-Tests).
• Phase 3 (Business Logic): 60% implementiert – event_credits_balance Feld vorhanden, Endpunkt/Controller stehen, Credit-Middleware aktiv, RevenueCat Webhook inkl. Queue/Retries produktionsreif; Token-Rotation folgt.
• Phase 4 (Admin & Monitoring): 45% implementiert – TenantResource erweitert (credits, features, activeSubscription), PurchaseHistory/OAuthClient-Management sowie Dashboard-Widgets fertig; verbleibend sind Advanced Actions (subscription_tier) und erweiterte Monitoring-Policies.

Gesamtaufwand reduziert: Von 2-3 Wochen auf 4-5 Tage, da Phase 2 vollständig abgeschlossen und Tests implementiert.

Phasenübersicht

Phase	Fokus	Dauer	Dependencies	Status	Milestone
Phase 1: Foundation	Database & Authentication	0 Tage	Laravel Sanctum/Passport	Vollständig abgeschlossen	OAuth-Flow funktioniert, Tokens validierbar
Phase 2: Core API	Tenant-spezifische Endpunkte	0 Tage	Phase 1	✅ 100% abgeschlossen	CRUD für Events/Photos/Tasks, Settings, Upload, Tests (100% Coverage)
Phase 3: Business Logic	Freemium & Security	3-4 Tage	Phase 2	30% implementiert	Credit-System aktiv, Rate Limiting implementiert
Phase 4: Admin & Monitoring	SuperAdmin & Analytics	4-5 Tage	Phase 3	In Arbeit	Filament-Resources erweitert, Dashboard funktioniert

Phase 1: Foundation (Abgeschlossen)

Status: Vollständig implementiert

• DB-Migrationen ausgeführt (OAuth, PurchaseHistory, Subscriptions)
• Models erstellt (OAuthClient, RefreshToken, TenantToken, PurchaseHistory)
• Sanctum konfiguriert (api guard, HasApiTokens Trait)
• OAuthController implementiert (authorize, token, me mit PKCE/JWT)
• Middleware implementiert (TenantTokenGuard, TenantIsolation)
• API-Routen mit Middleware geschützt
• Testbar: OAuth-Flow funktioniert mit Postman

Phase 2: Core API (80% abgeschlossen, 2-3 Tage verbleibend)

Ziele

• Vollständige tenant-spezifische API mit CRUD für Events, Photos, Tasks
• File Upload Pipeline mit Moderation

Implementierter Fortschritt

• EventController: CRUD, Credit-Check, Search, Bulk-Update
• PhotoController: Upload, Moderation (bulk approve/reject), Stats, Presigned Upload
• TaskController: CRUD, Event-Assignment, Bulk-Operations, Search/Filter
• SettingsController: Branding, Features, Custom Domain, Domain-Validation, Reset
• Request Models: EventStoreRequest, PhotoStoreRequest, TaskStoreRequest, TaskUpdateRequest, SettingsStoreRequest
• Response Resources: EventResource, PhotoResource, TaskResource, EventTypeResource
• File Upload: Local Storage, Thumbnail-Generation (ImageHelper)
• API-Routen: Events/Photos/Tasks/Settings (tenant-scoped, slug-basiert)
• Pagination, Filtering, Search, Error-Handling
• Feature-Tests: 21 Tests (SettingsApiTest: 8, TaskApiTest: 13, 100% Coverage)
• Unit-Tests: TenantModelTest (11 Tests für Beziehungen, Attribute, Methoden)

Verbleibende Tasks

• Phase 2 vollständig abgeschlossen

Milestones

• Events/Photos Endpunkte funktionieren
• Photo-Upload und Moderation testbar
• Task/Settings implementiert (CRUD, Assignment, Branding, Custom Domain)
• Vollständige Testabdeckung (>90%)

Phase 3: Business Logic (30% implementiert, 3-4 Tage)

Ziele

• Freemium-Modell vollständig aktivieren
• Credit-Management, Webhooks, Security

Implementierter Fortschritt

• Credit-Feld in Tenant-Model mit event_credits_balance
• Tenant::decrementCredits()/incrementCredits() Methoden inkl. Logging implementiert
• Credit-Middleware & Route-Alias greifen vor Event-Create; Tenant::consumeEventAllowance() nutzt zuerst Reseller-Pakete, sonst Credits
• RevenueCat-Webhook: Signatur-Validierung, Queue-Konfiguration, Retry (tries/backoff) + Produkt-Mapping

Verbleibende Tasks

1. Security Implementation (1 Tag)
   • Rate Limiting: 100/min tenant API, 20/min tenant-auth login/exchange (aktiv)
   • Token issuance handled by Sanctum PAT endpoints; rotation via PAT revocation (aktiv)
   • IP-Binding für Refresh Tokens (konfigurierbar, Subnetzrelax optional)

Milestones

• Credit-Check funktioniert (Event-Create scheitert bei 0)
• Webhooks verarbeiten Purchases
• Rate Limiting aktiv
• Token-Rotation implementiert

Phase 4: Admin & Monitoring (In Arbeit, 4-5 Tage)

Ziele

• SuperAdmin-Funktionen erweitern
• Analytics Dashboard, Testing

Implementierter Fortschritt

• TenantResource erweitert: credits, features, activeSubscription Attribute
• TenantModelTest: 11 Unit-Tests für Beziehungen (events, photos, purchases), Attribute, Methoden
• PurchaseHistoryResource, OAuthClientResource, Widgets, Policies

Verbleibende Tasks

1. Filament Resources erweitern (2 Tage)

   • TenantResource: subscription_tier, Actions (add_credits, suspend), RelationsManager (Credits-Aktion fertig; subscription_tier-Actions noch offen)
   • PurchaseHistoryResource: CRUD, Filter, Export, Refund (CRUD & Export umgesetzt; Refund via UI noch offen)
   • OAuthClientResource: Client-Management (implementiert)
   • TenantPolicy mit superadmin before() (implementiert)

2. Dashboard Widgets (1 Tag)

   • RevenueChart, TopTenantsByRevenue, CreditAlerts

3. Admin Actions & Middleware (1 Tag)

   • SuperAdminMiddleware, manuelle Credit-Zuweisung
   • Bulk-Export, Token-Revoke

4. Testing & Deployment (1 Tag)

   • Unit/Feature-Tests für alle Phasen
   • Deployment-Skript, Monitoring-Setup

Milestones

• TenantResource basis erweitert
• PurchaseHistoryResource funktioniert
• Widgets zeigen Stats
• Policies schützen SuperAdmin
• >80% Testabdeckung

Gesamter Zeitplan

Woche	Phase	Status
1	Foundation	✅ Abgeschlossen
1	Core API	✅ Abgeschlossen
2	Business Logic	40% ⏳ In Arbeit
2	Admin & Monitoring	45% ✅ In Arbeit

Gesamtdauer: 4-5 Tage - Phase 2 vollständig abgeschlossen, Tests implementiert Kritische Pfade: Phase 3 (Business Logic) kann sofort starten Parallelisierbarkeit: Phase 4 (Admin) parallel zu Phase 3 (Webhooks/Credits) möglich

Risiken & Mitigation

Risiko	Wahrscheinlichkeit	Impact	Mitigation
File Upload Performance	Mittel	Mittel	Local Storage optimieren, später S3 migrieren
OAuth Security	Niedrig	Hoch	JWT Keys rotieren, Security-Review
Credit-Logik-Fehler	Niedrig	Hoch	Unit-Tests, Manual Testing mit Credits
Testing-Abdeckung	Mittel	Mittel	Priorisiere Feature-Tests für Core API

Nächste Schritte

1. Phase 3 Business Logic (2-3 Tage): CreditMiddleware, CreditController, Webhooks
2. Phase 4 Admin & Monitoring (2 Tage): PurchaseHistoryResource, Widgets, Policies
3. Stakeholder-Review: OAuth-Flow, Upload, Task/Settings testen
4. Development Setup: Postman Collection für API, Redis/S3 testen
5. Final Testing: 100% Coverage, Integration Tests
6. Deployment: Staging-Environment, Monitoring-Setup

Gesamtkosten: Ca. 60-100 Stunden (weit reduziert durch bestehende Basis).
Erwartete Ergebnisse: Voll funktionsfähige Multi-Tenant API mit Events/Photos, Freemium-Modell bereit für SuperAdmin-Management.