fotospiel-app/docs/implementation-roadmap.md

### Update 2025-09-25
- Phase 3 credits scope: credit middleware on create/update, rate limiters for OAuth/tenant APIs, RevenueCat webhook + processing job live with idempotency tests.
- Remaining: extend middleware to photo/other credit drains, admin ledger surfaces, document RevenueCat env vars in PRP.
# 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
- [x] DB-Migrationen ausgeführt (OAuth, PurchaseHistory, Subscriptions)
- [x] Models erstellt (OAuthClient, RefreshToken, TenantToken, PurchaseHistory)
- [x] Sanctum konfiguriert (api guard, HasApiTokens Trait)
- [x] OAuthController implementiert (authorize, token, me mit PKCE/JWT)
- [x] Middleware implementiert (TenantTokenGuard, TenantIsolation)
- [x] 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
- [x] EventController: CRUD, Credit-Check, Search, Bulk-Update
- [x] PhotoController: Upload, Moderation (bulk approve/reject), Stats, Presigned Upload
- [x] **TaskController**: CRUD, Event-Assignment, Bulk-Operations, Search/Filter
- [x] **SettingsController**: Branding, Features, Custom Domain, Domain-Validation, Reset
- [x] Request Models: EventStoreRequest, PhotoStoreRequest, **TaskStoreRequest, TaskUpdateRequest, SettingsStoreRequest**
- [x] Response Resources: EventResource, PhotoResource, **TaskResource, EventTypeResource**
- [x] File Upload: Local Storage, Thumbnail-Generation (ImageHelper)
- [x] API-Routen: Events/Photos/Tasks/Settings (tenant-scoped, slug-basiert)
- [x] Pagination, Filtering, Search, Error-Handling
- [x] **Feature-Tests**: 21 Tests (SettingsApiTest: 8, TaskApiTest: 13, 100% Coverage)
- [x] **Unit-Tests**: TenantModelTest (11 Tests für Beziehungen, Attribute, Methoden)

### Verbleibende Tasks
- Phase 2 vollständig abgeschlossen

### Milestones
- [x] Events/Photos Endpunkte funktionieren
- [x] Photo-Upload und Moderation testbar
- [x] Task/Settings implementiert (CRUD, Assignment, Branding, Custom Domain)
- [x] 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
- [x] Credit-Feld in Tenant-Model mit `event_credits_balance`
- [x] **Tenant::decrementCredits()/incrementCredits() Methoden** implementiert
- [x] 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
- [x] 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
- [x] **TenantResource erweitert**: credits, features, activeSubscription Attribute
- [x] **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
- [x] 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.