sufw-webseite-terminplanung/AGENTS.md

AGENTS.md

Guidlines

Ich bin Softwareentwickler, Full-Stack Webentwickler und Netzwerkadministrator. Ich möchte bei allen Software und Netzwerk-Design-Entscheidungen und beim Erstellen von Code eingebunden werden. Gib mir immer erst Deine Idee oder deinen Plan damit wir diesen gemeinsam abstimmen können! Gib mir auch immer die technischen Details mit, damit ich alles verstehen kann.

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.