# AGENTS.md

## Ziel

Diese Aufgabe betrifft die Implementierung einer Terminbuchungs-Funktion für die Website des Perspektivwerks und der Produktionsschule. Ziel ist eine nutzerfreundliche Buchungsoberfläche, die den genannten Terminarten entspricht, mobil nutzbar ist, sicher umgesetzt wird und später in einen Google-Kalender integriert werden kann.

## Projektkontext

- Website: https://www.sufw.de/perspektivwerk
- Website: https://www.sufw.de/produktionsschule
- Referenzstil: https://webtermin.medatixx.de/#/affe7e7b-bb18-46b6-aaf4-6ff75152606c/search
- Zugangsdaten für die Terminbuchung werden nachgereicht.
- Der aktuelle Stand ist noch unbekannt; deshalb wird zuerst ein Mockup basierend auf der bestehenden Seite erstellt, bevor Backend- und Integrationslogik angebunden wird.

## Technische Bestandsaufnahme der Website

Die folgenden Punkte sind aus einer passiven, öffentlich sichtbaren Analyse abgeleitet und sollen als Arbeitsannahmen dienen:

- Das Frontend wird serverseitig gerendert und ist kein Single-Page-Application-Setup.
- Als CMS ist sehr wahrscheinlich Contao im Einsatz.
- Der Webserver antwortet mit `Apache`.
- Die Anwendung läuft sehr wahrscheinlich auf einem PHP-Stack; Contao spricht dabei typischerweise über Symfony/Doctrine mit einer MySQL- oder MariaDB-Datenbank.
- Im Frontend sind Bootstrap-5-Elemente sowie jQuery erkennbar.
- Zusätzliche Frontend-Bausteine wie Slick-Slider und eigene CSS-Bundles sind eingebunden.
- Ein selbst gehostetes Matomo-Tracking ist sichtbar.
- Der genaue Contao- und PHP-Versionsstand ist von außen nicht belastbar bestimmbar und sollte für die Implementierung als offen behandelt werden.
- Der Host wirkt nach der Infrastruktur sehr wahrscheinlich wie eine IONOS-Umgebung, auch das ist aber nur eine Wahrscheinlichkeitsannahme.

Für die weitere Umsetzung bedeutet das:

- Die Terminbuchung sollte sich sauber in eine klassische CMS-Seite einbetten lassen.
- Ein kleines, eigenständiges TypeScript-Frontend ist hier voraussichtlich passender als eine große neue Framework-Schicht.
- Backend- und Kalenderanbindung sollten entkoppelt geplant werden, damit ein späterer Wechsel von Google Kalender zu Exchange möglich bleibt, ohne das UI neu bauen zu müssen.

## Lokales Entwicklungssystem

- Das lokale Setup bildet die vermutete Komponentenfamilie mit Docker Compose nach: Apache/PHP 8.3, Contao Managed Edition 5.3, MariaDB 10.11 und Adminer.
- Frontend-Abhängigkeiten für die angenommene Originalseite sind in `package.json` vorgesehen: Bootstrap 5, jQuery und Slick Carousel; die eigene Logik bleibt in TypeScript.
- Start über `docker compose up --build`; CMS auf Port 8080, Adminer auf Port 8081, MariaDB zusätzlich auf Host-Port 3307.
- Das Setup ist eine reproduzierbare Entwicklungsbasis und keine Kopie der Produktivinstallation. Exakte Contao-/PHP-Versionen, Templates, Erweiterungen und Hosting-Einstellungen der Originalseite müssen bei Zugriff auf die Produktivumgebung abgeglichen werden.

## Terminarten

### Projekt Perspektivwerk

- Erstgespräch Perspektivwerk (1 Std.)
- Soz. Päd. Modul Perspektivwerk (4 Std.)
- Psy Modul Perspektivwerk (4 Std.)
- Praxis Modul Perspektivwerk (1 Woche, ab Montag 08:00 Uhr)

### Projekt Produktionsschule

- Voranmeldung Kennenlerntermin Produktionsschule (1 Std., immer dienstags)
- Probearbeiten (1 Woche, ab Montag 08:00 Uhr)

## Grundprinzipien

- Mobile-first und barrierearm entwickeln.
- Die Frontend-Logik in TypeScript umsetzen.
- Für die Oberfläche möglichst einfache, weit verbreitete Technologien nutzen: HTML, CSS und TypeScript ohne unnötige Framework-Schicht.
- Performance hat Priorität: geringe Dateigrößen, wenig JavaScript, keine unnötigen Abhängigkeiten, schnelle Rendering- und Ladezeiten.
- Die Lösung soll modular, testbar und leicht später mit Backend oder Kalender-API verbunden werden können.

## Technische Anforderungen

- Die Lösung muss auf der bestehenden Website sauber einbindbar sein.
- Die Terminliste soll klar, verständlich und mobil kompatibel sein.
- Das Frontend soll nach einem „mockup-first“-Ansatz entstehen: zunächst ein realistisches, klickbares UI-Prototyping basierend auf der aktuellen Seite, dann später Anbindung an echte Daten und Kalender.
- Zugriffsdaten und Zugangsspezifika sind als Umgebungsvariablen bzw. sichere Konfiguration zu behandeln.
- Die Terminbuchung soll zunächst in einen Google-Kalender integriert werden.
- Ein späterer Wechsel auf Exchange-Kalender muss technisch berücksichtigt werden.
- Die technische Architektur soll die spätere Integration von Backend, API und Kalender sauber abbilden, ohne dass das Frontend später neu geschrieben werden muss.

## Sicherheitsanforderungen

- Keine geheimen Zugangsdaten, Tokens, Keys oder Secrets im Repository speichern.
- Eingaben immer validieren und bereinigen; XSS- und Injection-Angriffe vermeiden.
- Wenn Sicherheitsrelevanter Code geschrieben wurde, soll gefragt werden ob eine gesonderete tiefe Sicherheitsanalyse dafür durchgeführt werden soll. 
- Wenn Formulare oder API-Calls später eingesetzt werden, nur mit abgesicherten, validierten Requests arbeiten.
- Bei späterem Backend- und API-Setup: sichere Authentifizierung, autorisierte Zugriffe und minimal notwendige Berechtigungen verwenden.
- Keine sensiblen Daten im Client- oder Mockup-Code sichtbar machen.

## Qualitätsmaßstäbe

- Saubere, verständliche Code-Struktur
- Reaktionsfähige und barrierearme Oberfläche
- Keine geheimen Zugangsdaten im Repository
- Sinnvolle Fehlerbehandlung bei falschen/fehlenden Konfigurationen
- Dokumentation der Integration für spätere Pflege und Erweiterung
- Fokus auf Lesbarkeit, Stabilität und Wartbarkeit statt auf Overengineering

## Test-Driven Development

- Neue Funktionalität zuerst mit einem fehlenden Test dokumentieren und dann implementieren.
- Für UI- und Zustandslogik kleine, verständliche Tests schreiben, z. B. für Auswahl von Termin, Projekt, Validierung und Fehlerzustände.
- Die wichtigsten Abläufe mit End-to-End-Tests absichern, damit die Auswahl und der Buchungsfluss funktionieren.
- Einfache Regressionstests für mobile Darstellung und Kernfunktionalität ergänzen.
- TDD ist verbindlich für neue Logik, nicht optional.

## Dokumentationsanforderungen

- Eine README mit Installations- und Startanweisungen erstellen.
- Eine kurze Architektur- und Integrationsdokumentation für Frontend, Mockup, späteres Backend und Kalender-API ergänzen.
- Konfigurationswerte und Umgebungsvariablen sauber dokumentieren, aber keine geheimen Daten enthalten.
- Hinweise zur späteren Google-Calendar- und Exchange-Anbindung dokumentieren.
- Frontend-Entscheidungen, nicht trivialen Implementierungsdetails und potenzielle Risiken ebenfalls kurz dokumentieren.

## Arbeitsweise

1. Zuerst die bestehende Website-Struktur bzw. vorhandene technische Basis analysieren.
2. Das Design und die Nutzerführung für ein mockup-basiertes Booking-Flow definieren.
3. Die geeignete Architektur für die Terminbuchung bestimmen.
4. Die Buchungs-UI mit den erforderlichen Projekten und Terminarten umsetzen.
5. Testfälle für Kernfunktionen schreiben und anschließend die Umsetzung validieren.
6. Die Kalender-Integration vorbereiten und auf Google-Kalender ausrichten.
7. Das Ergebnis lokalisieren, validieren und möglichst mit Beispiel- oder Testdaten absichern.

## Abnahme

Die Aufgabe gilt als abgeschlossen, wenn:

- die Angebotsseite für beide Projekte korrekt funktioniert,
- die Terminarten auswählbar sind,
- die Oberfläche mobil-first, performant und barrierearm ist,
- das Frontend in TypeScript umgesetzt wurde,
- die Lösung als Mockup auf der aktuellen Seite verankert ist und später backendfähig bleibt,
- die Integration zur Kalender-API bzw. zum Google-Kalender vorbereitet ist,
- die Konfiguration sicher, dokumentiert und nachvollziehbar ist,
- die Kernfunktionen durch Tests abgesichert sind.

## Wichtig

- Zugangsdaten sind vertraulich und dürfen nicht in die Versionskontrolle eingegeben werden.
- Wenn die Umgebung oder der vorhandene Stack unklar ist, zuerst die technische Basis prüfen und dann gezielt implementieren.
- Das Projekt ist zunächst als funktionierende Terminbuchung mit klarer Erweiterbarkeit zu sehen; keine Über-Engineering-Phase ohne Notwendigkeit.
- Das Frontend muss zunächst als robustes, realistisches Mockup funktionieren, auch wenn das Backend noch nicht definiert ist.