fotospiel-app/docs/implementation-roadmap.md

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): 40% implementiert – event_credits_balance Feld vorhanden, Credit-Check in EventController, Tenant::decrementCredits()/incrementCredits() Methoden, aber CreditMiddleware, CreditController, Webhooks fehlen.
• Phase 4 (Admin & Monitoring): 20% implementiert – TenantResource erweitert (credits, features, activeSubscription), aber fehlend: subscription_tier Actions, PurchaseHistoryResource, Widgets, 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 implementiert
• Credit-Check in EventController (decrement bei Create)
• CreditMiddleware für alle Event-Operationen

Verbleibende Tasks

1. Credit-System erweitern (1 Tag)

   • CreditMiddleware für alle Event-Create/Update
   • CreditController für Balance, Ledger, History
   • Tenant::decrementCredits() Methode mit Logging

2. Webhook-Integration (1-2 Tage)

   • RevenueCatController für Purchase-Webhooks
   • Signature-Validation, Balance-Update, Subscription-Sync
   • Queue-basierte Retry-Logic

3. Security Implementation (1 Tag)

   • Rate Limiting: 100/min tenant, 10/min oauth
   • Token-Rotation in OAuthController
   • IP-Binding für Refresh Tokens

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
   • PurchaseHistoryResource: CRUD, Filter, Export, Refund
   • OAuthClientResource: Client-Management
   • TenantPolicy mit superadmin before()

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	20% 🔄 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.