WebAPP/CLAUDE.md

WebApp_Install — Handball Team Manager

Projekt-Typ

Laravel 12 WebApp zur Verwaltung von Handball-Teams, Spielern, Eltern, Terminen und Dateien. PHP 8.2+, SQLite/MySQL, Blade + Alpine.js + Tailwind CSS, Quill.js WYSIWYG-Editor. Deployment: Shared Hosting (all-inkl.com, FTP only, kein SSH).

Architektur

Verzeichnisstruktur

• app/Models/ — Eloquent Models (User, Player, Team, Event, Setting, etc.)
• app/Http/Controllers/Admin/ — Admin-Bereich (UserController, SettingsController, etc.)
• app/Http/Controllers/Auth/ — Login, Register, ForgotPassword, ResetPassword
• app/Http/Middleware/ — InstallerMiddleware, SetLocaleMiddleware, SecurityHeadersMiddleware, ActiveUserMiddleware, DsgvoConsentMiddleware, StaffMiddleware, AdminOnlyMiddleware
• app/Services/ — HtmlSanitizerService (HTMLPurifier), GeocodingService, SupportApiService
• app/Enums/ — UserRole, EventType, EventStatus, ParticipantStatus, CateringStatus
• app/Notifications/ — ResetPasswordNotification (Custom, mit Setting-Template)
• resources/views/ — Blade-Templates (layouts: admin, guest, app, installer)
• lang/{de,en,pl,ru,ar,tr}/ — 6 Sprachen: Deutsch, Englisch, Polnisch, Russisch, Arabisch, Tuerkisch
• database/migrations/ — Nummeriert mit Prefix 0001-0035
• database/seeders/ — AdminSeeder, DemoSeeder, FaqSeeder

Wichtige Patterns

• Settings: Key-Value Store in settings Tabelle. Setting::get($key) mit 1-Stunden-Cache, Setting::set($key, $value) mit Cache-Invalidierung
• Locale-Settings: Rechtliche Texte und E-Mail-Templates sind locale-suffixed: impressum_html_de, datenschutz_html_en, password_reset_email_pl etc.
• Passwort-Hashing: User-Model nutzt Laravel Cast 'password' => 'hashed' — KEIN manuelles Hash::make beim Setzen via $user->password = $pw noetig
• HTML-Output: Alle {!! !!}-Ausgaben von User-Content muessen durch HtmlSanitizerService::sanitize() gehen
• Rollen: Admin, Coach, ParentRep, User (Enum UserRole)
• Soft-Deletes: User und Player (7 Tage Wiederherstellung)
• Activity-Log: ActivityLog::log() / ActivityLog::logWithChanges() fuer Audit-Trail
• User-Model: Nutzt Notifiable Trait (erforderlich fuer Passwort-Reset-Notifications)
• .env-Manipulation: updateEnvValues() Helper in InstallerController und SettingsController

Multi-Language

• 6 Sprachen: de, en, pl, ru, ar, tr
• Translation-Dateien: lang/{locale}/admin.php, auth_ui.php, passwords.php, ui.php, events.php, profile.php, validation.php
• Locale wird per SetLocaleMiddleware aus $user->locale oder Session gesetzt
• RTL-Support fuer Arabisch (ar)
• Alle Uebersetzungsschluessel muessen in ALLEN 6 Sprachen hinzugefuegt werden

Installer (5-Step Wizard)

1. Systemcheck (PHP-Version, Extensions, Berechtigungen)
2. Datenbank (SQLite/MySQL Konfiguration)
3. Einstellungen (App-Name, Admin-Account)
4. E-Mail (SMTP-Konfiguration mit Verbindungstest, oder Log-Modus zum Ueberspringen)
5. Abschluss (Finalize, Demo-Daten, Lizenz)

• InstallerMiddleware prueft storage/installed Datei
• Setup-Token-Schutz: Token in storage/setup-token, SHA256 im Laravel-Log
• SMTP-Test nutzt Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport
• PW-Reset-Standardtexte fuer 6 Sprachen in getDefaultPasswordResetTexts()
• Session-basierte Datenpersistenz zwischen Schritten

Password Reset Flow

1. User klickt "Passwort vergessen?" auf Login-Seite
2. ForgotPasswordController sendet Reset-Link via Laravel Password Broker
3. ResetPasswordNotification laedt Custom-Template aus Setting::get('password_reset_email_{locale}')
4. Platzhalter: {name}, {link}, {app_name}
5. Fallback auf Standard-Laravel-Template mit Translation-Keys (passwords.reset_*)

Admin Settings Tabs

• Allgemein: App-Name, Slogan, Favicon, Saison
• E-Mail: SMTP-Konfiguration mit Verbindungstest (schreibt in .env, Artisan::call('config:clear'))
• Rechtliches: Impressum + Datenschutz + PW-Reset-E-Mail pro Sprache (Quill-Editor mit Flaggen-Selector)
• Event-Standards: Min-Werte fuer Spieler, Catering, Zeitnehmer pro Event-Typ
• Dateikategorien: CRUD fuer File-Categories
• Sichtbarkeit: Feature-Toggles
• Lizenz: License-Key-Validierung via SupportApiService
• Wartung: Demo-Daten loeschen, Factory-Reset

Lazy Quill-Initialisierung (Rechtliches-Tab)

• Quill-Editoren werden erst bei Klick auf die Sprach-Flagge erstellt (initLocaleEditors(locale))
• Verhindert Datenverlust: Nicht-initialisierte Locales behalten ihre Server-Werte in Hidden-Inputs
• $watch('legalLocale') + $nextTick() fuer verzoegerte Erstellung
• syncEditors() synchronisiert nur tatsaechlich initialisierte Editoren

Route-Struktur (Middleware)

• Installer: throttle:10,1, ohne SetLocaleMiddleware/ActiveUserMiddleware
• Oeffentlich: Login, Register, Legal-Pages, Locale-Switch
• User-Bereich: auth Middleware
• Admin-Bereich: auth + admin + prefix('admin')
  • Staff-Routes (Admin + Coach): staff Middleware
  • Admin-Only-Routes: admin-only Middleware (Settings, Locations, Support)

Security

Middleware-Stack

• CSP und Permissions-Policy via SecurityHeadersMiddleware (inkl. COOP-Header)
• StaffMiddleware — prueft Admin oder Coach Rolle
• AdminOnlyMiddleware — prueft explizit Admin-Rolle (Route-Level-Schutz)
• Rate-Limiting auf Auth-Routes, User-Actions, Geocoding, Installer

Schutzmassnahmen

• Honeypot-Feld auf Login/Register-Formularen
• DSGVO-Consent-System mit Datei-Upload und Admin-Bestaetigung
• Factory Reset benoetigt Passwort + Bestaetigung "RESET-BESTAETIGT"
• File-Autorisierung: authorizeFileAccess() in FileController prueft Team-Zugehoerigkeit
• Settings-Whitelist: SettingsController akzeptiert nur bekannte Keys + validierte Locale-Suffixe
• SSRF-Schutz: GeocodingService mit Host-Whitelist, HTTPS-only, DNS-Rebinding-Check, Timeout 5s
• Installer-Sicherheit: Admin-Passwort sofort gehasht, Setup-Token nur als SHA256 geloggt
• Path-Traversal-Schutz: DSGVO-Datei-Downloads pruefen str_starts_with('dsgvo/')
• HTML-Sanitisierung: Alle User-Content-Ausgaben durch HtmlSanitizerService geschuetzt
• Invitation-Tokens: SHA-256 gehasht in DB gespeichert
• E-Mail-Normalisierung: Lowercase-Vergleich bei Login und Password-Reset
• Team-Scoping: Coach/ParentRep sehen nur ihre zugewiesenen Teams

Security-Audit-Historie (Maerz 2026)

6 Audits durchgefuehrt, Score: 6.5 → 9.5/10

• 95 Findings insgesamt, 88 behoben, 3 akzeptierte Risiken, 4 verbleibende Niedrig/Info
• Akzeptierte Risiken: MIME-Spoofing (F05), Enum-Reuse (F20), CSP unsafe-inline (W04, CDN-Abhaengigkeit)

Conventions

• Controller-Methoden: resourceful (index, create, store, show, edit, update, destroy)
• Blade-Components: <x-layouts.admin>, <x-layouts.guest>, <x-layouts.app>, <x-layouts.installer>
• Alpine.js fuer interaktive UI-Elemente
• Quill.js v1.3.7 fuer WYSIWYG-Editoren (via CDN mit SRI-Hashes)
• Keine Tests vorhanden — bei Aenderungen manuell testen
• Commit-Sprache: Deutsch oder Englisch
• Alle Uebersetzungsschluessel muessen in ALLEN 6 Sprachen hinzugefuegt werden

Haeufige Aufgaben

Neuen Translation-Key hinzufuegen

Immer in allen 6 Dateien: lang/de/, lang/en/, lang/pl/, lang/ru/, lang/ar/, lang/tr/

Neues Setting hinzufuegen

1. Migration erstellen: Setting::firstOrCreate(['key' => '...'], [...])
2. In SettingsController edit() laden
3. In View rendern
4. In update() speichern (mit Sanitization fuer HTML)

Neues locale-spezifisches Setting

1. Keys: {setting_name}_{locale} (z.B. impressum_html_de)
2. Migration fuer alle 6 Locales
3. In SettingsController $localeSettings Array aufnehmen
4. In View mit Sprach-Flaggen-Selector anzeigen
5. In update() mit Whitelist und updateOrCreate() behandeln
6. Wichtig: Neuen Key zur Whitelist in SettingsController::update() hinzufuegen ($allowedLocaleKeys)

Neue Admin-Route hinzufuegen

1. Route in routes/web.php im passenden Middleware-Block:
   • Alle Admin-Panel-Nutzer: direkt unter admin Prefix
   • Staff (Admin + Coach): unter staff Middleware
   • Nur Admin: unter admin-only Middleware
2. Controller-Methode mit Autorisierungs-Pruefung
3. View erstellen
4. Translation-Keys fuer alle 6 Sprachen