huge documentaton restructure for docusaurus

docs/archive/implementation-roadmap.md

@@ -0,0 +1,176 @@
+### 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
+- [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** 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**: credits, 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 (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
+- [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.