sufw-webseite-terminplanung/AGENTS.md

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.