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-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 – (Legacy Credits entfernt), Packages/Add-ons aktiv; RevenueCat Webhook inkl. Queue/Retries produktionsreif; Token-Rotation folgt.
- **Phase 4 (Admin & Monitoring)**: 45% implementiert – **TenantResource erweitert (packages, 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
- [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] Legacy credit fields removed; package usage enforced
- [x] **Tenant::decrementCredits()/incrementCredits() Methoden** inkl. Logging implementiert
- [x] Credit-Middleware & Route-Alias greifen vor Event-Create; `Tenant::consumeEventAllowance()` nutzt zuerst Reseller-Pakete, sonst Credits
- [x] 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
- [x] Credit-Check funktioniert (Event-Create scheitert bei 0)
- [x] Webhooks verarbeiten Purchases
- [x] Rate Limiting aktiv
- [x] Token-Rotation implementiert

## Phase 4: Admin & Monitoring (In Arbeit, 4-5 Tage)
### Ziele
- SuperAdmin-Funktionen erweitern
- Analytics Dashboard, Testing

### Implementierter Fortschritt
- [x] **TenantResource erweitert**: packages, features, activeSubscription Attribute
- [x] **TenantModelTest**: 11 Unit-Tests für Beziehungen (events, photos, purchases), Attribute, Methoden
- [x] PurchaseHistoryResource, OAuthClientResource, Widgets, Policies

### Verbleibende Tasks
1. **Filament Resources erweitern (2 Tage)**
   - TenantResource: subscription_tier, Actions (packages), RelationsManager *(Credits-Aktion entfernt; 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
- [x] TenantResource basis erweitert
- [x] PurchaseHistoryResource funktioniert
- [x] Widgets zeigen Stats
- [x] 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.