FightReg — Entwicklerhandbuch

fightReg/
├── config.php                  ← DB, SMTP, JWT-Secret, API-Keys
├── install.php                 ← DB-Setup + Seed (Erstinstallation)
├── composer.json               ← PSR-4 Autoload: FightReg\
├── migrations/                 ← SQL-Migrations (000–069)
├── public/
│   ├── api.php                 ← REST API Entry Point
│   ├── index.php               ← SPA Shell
│   ├── sw.js                   ← Service Worker (v561)
│   ├── manifest.json           ← PWA Manifest
│   ├── locales/
│   │   ├── de.json             ← Deutsche Übersetzungen
│   │   └── en.json             ← Englische Übersetzungen
│   └── assets/
│       ├── css/app.css         ← Design System
│       ├── js/
│       │   ├── app.js          ← App Bootstrap
│       │   ├── core.js         ← Utilities
│       │   ├── components.js   ← Shared Components
│       │   └── pages/          ← Page Modules (~20 Dateien)
│       └── fonts/              ← DM Sans self-hosted
├── src/
│   ├── Config/
│   │   ├── Database.php        ← PDO Singleton
│   │   └── Permissions.php     ← 67 Permission-Slugs (SSOT)
│   ├── Controllers/            ← ~50 Controller-Klassen
│   ├── Services/               ← ~20 Service-Klassen
│   ├── Repositories/           ← ParticipantRepository, CategoryRepository
│   ├── Middleware/             ← AuthMiddleware, CorsMiddleware
│   ├── Helpers/                ← Response, Validator
│   └── Router.php
├── storage/
│   ├── invoices/               ← PDF-Rechnungen
│   └── tts/                    ← Gecachte MP3-Ansagen
├── templates/email/            ← Mail-Templates (DB-basiert)
└── tests/                      ← PHPUnit Test-Suite

Der Service Worker nutzt eine versionierte Cache-Strategie. Bei Änderungen an JS/CSS-Dateien muss die Version erhöht werden.

// public/sw.js — Cache-Version erhöhen bei JS-Änderungen
const CACHE_NAME = 'fightreg-v561';   // ← bei jeder JS- oder CSS-Aenderung erhoehen
const ASSETS = [
  '/assets/js/app.js',
  '/assets/js/core.js',
  '/assets/js/components.js',
  // alle page-JS-Dateien...
  '/assets/css/app.css',
];

Das RBAC-System arbeitet mit der Klasse Permissions.php als Single Source of Truth (67 Slugs in 20 Modulen, verteilt auf zwölf Rollen).

// src/Config/Permissions.php
class Permissions {
  const BRACKETS_EDIT       = 'brackets.edit';
  const BRACKETS_SCORE      = 'brackets.score';
  const BILLING_VIEW        = 'billing.view';
  // ... 67 Slugs insgesamt
}

// Backend-Check
AuthMiddleware::requirePermission($user, Permissions::BILLING_SEND, $compId);

// Frontend-Check (JS)
if (can('billing.send')) {
  // Button anzeigen
}

78 Controller. Die Liste ist aus src/Controllers erzeugt — von Hand gepflegt wäre sie nach zwei Sprints unvollständig.

53 Dienste, erzeugt aus src/Services. Ein Dienst hält fachliche Regeln, die mehr als ein Controller braucht.

Vier Repositories plus Schnittstelle: ParticipantRepository, CategoryRepository, SchoolRepository, BookingRepository.

// public/api.php — Routen registrieren
$router->get('/api/competitions',           [CompetitionController::class, 'index']);
$router->post('/api/competitions',          [CompetitionController::class, 'store']);
$router->get('/api/competitions/{id}',      [CompetitionController::class, 'show']);
$router->patch('/api/competitions/{id}',    [CompetitionController::class, 'patch']);
$router->delete('/api/competitions/{id}',   [CompetitionController::class, 'destroy']);

// Wichtig: Literale Pfade VOR Wildcard-Routen!
$router->get('/api/rankings/global-points', [RankingController::class, 'getGlobalPoints']);  // ✅ zuerst
$router->get('/api/rankings/athlete/{pid}', [RankingController::class, 'athleteDetail']);    // ✅ dann

// Request-Body auslesen
$body = Router::getBody();  // json_decode(file_get_contents('php://input'), true)

FightReg nutzt 59 Tabellen in MySQL 8. Alle FK-Spalten nutzen INT UNSIGNED. Soft-Delete via Status-Felder (kein physisches Delete außer purge).

organizer ──────────────────────────────────────────┐
competitions  (53 cols)                              │
  ├── FK organizer_id → organizer                   │
  ├── FK invoice_issuer_id → invoice_issuer         │
  ├── competition_schools  (Schul-Anmeldung)        │
  ├── competition_participants (TN-Anmeldung)       │
  ├── competition_areas → rings → ring_categories   │
  ├── brackets → matches                            │
  ├── main_categories → sub_categories              │
  └── area_category_assignments

schools (19 cols)
  ├── trainers → users (role: trainer)
  └── participants (23 cols)
        ├── FK user_id (Athlet-Account)
        ├── athlete_id (Format: CC-SC-NNNNN)
        └── bookings (sub_category_id)

users (18 cols)
  └── FK role_id → roles → role_permissions → permissions

Jede Schemaänderung ist eine nummerierte SQL-Datei unter migrations/, idempotent geschrieben. Stand: 183. Was eingespielt ist, steht in schema_migrations — nicht im Gedächtnis.

# einspielen und nachsehen — beide Datenbanken
.\fr.ps1 migrate          # fightreg
.\fr.ps1 migrate-test     # fightreg_test
.\fr.ps1 migrate-status   # welche Datei fehlt wo?

# Jede neue Spalte zusaetzlich in install.php eintragen,
# sonst fehlt sie in jeder frischen Installation.

Alle Tabellen aus install.php, mit der Zahl ihrer Spalten. Zum Aufklappen anklicken.

Alle Endpunkte unter /api/. Auth via JWT Bearer-Token erforderlich (außer Public-Endpunkte). Response-Format: JSON.

// Erfolg
{ "success": true, "data": {...}, "message": "OK" }

// Fehler
{ "success": false, "error": "Fehlermeldung", "code": 422 }

// HTTP-Status-Codes
200 OK · 201 Created · 400 Bad Request · 401 Unauthorized
403 Forbidden · 404 Not Found · 422 Validation Error · 500 Server Error

// config.php
$config['elevenlabs']['api_key'] = 'your-api-key';
$config['elevenlabs']['voice_id'] = 'voice-id';

// TtsController — Ablauf
1. Text aufbereiten (Templates + Normalisierungsregeln)
2. MD5-Hash des Texts → Cache-Key
3. Cache prüfen: storage/tts/{hash}.mp3 vorhanden?
   - Ja → MP3 direkt streamen
   - Nein → ElevenLabs API aufrufen → MP3 speichern → streamen
4. Frontend: Audio-API spielt MP3 ab

Der KI-Assistent verwendet Anthropic Claude mit Tool-Use-Loop. 8 vordefinierte Tools ermöglichen sichere DB-Abfragen.

// ChatController → ChatService
1. System-Prompt mit Turnierkontext aufbauen (buildSystemPrompt)
2. User-Nachricht + Tool-Definitionen an Anthropic API senden
3. Modell kann bis zu N Tool-Use-Runden durchführen
4. Jedes Tool ist eine parametrisierte SQL-Query (competition_id-gebunden)
5. Finale Antwort → User

// Tools (Auswahl)
- search_participants(name, competition_id)
- get_category_stats(category_id)
- list_checked_in(competition_id)
- get_bracket_status(bracket_id)
- list_schools(competition_id)

// Modell: claude-sonnet-4-20250514
// Alternativ: OpenAI (gleiche Tool-Definitionen)

// InvoicePdfService nutzt TCPDF (Vendor-Bibliothek)
// Output: storage/invoices/INV-{id}-{timestamp}.pdf

// Features
- Firmenlogo (base64 eingebettet)
- Gesetzeskonforme Rechnungsstruktur
- Auflistung aller Buchungen als Positionen
- Netto/Brutto/MwSt.-Berechnung
- QR-Code für Zahlungsreferenz (optional)

# docker-compose.yml (Kurzversion)
services:
  app:
    image: php:8.1-apache
    volumes: [./:/var/www/html]
    ports: ["8080:80"]
  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: fightreg
      MYSQL_ROOT_PASSWORD: secret
  mailpit:
    image: axllent/mailpit
    ports: ["8025:8025"]   # Mail-UI
  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports: ["8081:80"]

# Starten
docker-compose up -d

# Datenbank initialisieren
curl http://localhost:8080/install.php

Ein Sprint gilt als fertig, wenn der Prüfstand grün ist — und test-all läuft vor dem Commit, nicht danach.

.\fr.ps1 test-all              # alle Laeufe, danach ein Bericht
                               # -> tests/berichte/-.json
.\fr.ps1 test-all nur=render   # Teillauf: nur render, der Rest wird uebernommen
make test-all                  # dasselbe unter Linux und macOS

33 Läufe: render, klassen-check, rauchtest, ladeschleife, theme-check, beschriftung-check, semantik-check, sprach-check, skalierung-check, dateien-check, dubletten-check, funktionsnamen-check, objektschluessel-check, eingabefarbe-check, farbpaar-check, dialog-inventur, dialog-oeffnung, seiten-bauen, kontrast, wirkung, ikonen, kontrast-360, wirkung-360, ikonen-360, rbac, routen, pfade, zeiten, schema, sprachen, joins, test-kurz, punkte-beruehrt

Dazu 317 PHPUnit-Tests und 282 Renderfälle. Jede neue Ansicht bekommt einen Fall in tests/render/cases.cjs — eine Ansicht ohne Fall ist für jede Prüfung unsichtbar: nicht rot, sondern abwesend.

# Deployment-Prozess
1. Geänderte Dateien in ZIP mit fightReg/ Unterordner paketieren
2. Per FTP auf fightreg.org hochladen
3. ZIP entpacken (überschreibt alte Dateien)
4. Migrations in phpMyAdmin ausführen (falls vorhanden)
5. Service Worker Version in sw.js prüfen/erhöhen

# prepare_claude_project.py
# Master-Script: FTP Download → Filter → Upload
# 88% File-Reduktion (642 → 77 Dateien) via 22 Exclusion Patterns

# Wichtig: config.php enthält Produktions-Secrets
# → NIEMALS in ZIP/Git einschließen!