sufw-webseite-terminplanung/AGENTS.md

# AGENTS.md

## Guidelines

Die Fragende Person/der Nutzer ist Softwareentwickler, Full-Stack Webentwickler und Netzwerkadministrator.
Der Fragende/der Nutzer wird bei allen Software und Netzwerk-Design-Entscheidungen und beim Erstellen von Code durch Nachfrage eingebunden!
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 der zu entwicklenden Anwendung

Entwicklung einer abgeschlossenen Komponente für das CMS Contao, um Terminbuchungs-Funktionen in der Website des Perspektivwerks (PW) und der Produktionsschule (PS) zu implementieren.
Ziel ist eine nutzerfreundliche und schöne Buchungsoberfläche, die den genannten Terminarten entspricht, mobil nutzbar ist, sicher umgesetzt wird und später mittels ICS Addresse in Kalenderprogramme integriert werden kann.

### Technik

Contao ist ein in PHP geschriebenes CMS, das ansonsten einfach Webtechnologien verwendet.
In dieses soll eine WebComponente integriert werden, die einen Terminbuchungskalender anzeigt.
Termininformationen kommen aus der Datenbank entweder mittels Contao oder direkt als MySQL Query.
Es gibt zwei Kalender (je für PW/PS) und jeder Kalender enthält eigene Termine die von Besuchern gebucht werden können.

### Die Oberfläche / UI

- ein Kalender-view aller Tage des aktuellen Monats
- der Monat kann vor und zurück gewechselt werden
- Tage mit freien Terminen werden farblich dargestellt
- wird auf einen Tag geklickt sind alle slots an diesem Tag zu sehen (farblich unterschieden verfügbar/schon belegt)
- wird auf einen freien Slot geklickt kann dieser durch eine E-Mail-Bestätigung (Datenschutzbedingung akzeptiert, Art. 13 DSGVO) verbindlich gebucht werden
- is barrierefrei. Alle Komponenten haben WAI-ARIA tags, sinnvolle Focus-Reihenfolge, Bildbeschreibungen, gute Kontraste, Farbenblindheit ist berücksichtigt

### Besucher der Webseite können

- in der Komponente die verfügbaren Termine sehen (offen / schon belegt)
- einen der verfügbaren Termine für sich buchen (Angabe einer E-Mail Adresse, Bestätigung des Termins via Email)
- Nach der Bestätigung via E-Mail kommt zweite Mail zur Bestätigung. Diese enthält ein *.ics file mit dem Termin (Kalenderintegration des Klienten)
- Nicht bestätigte Buchungen laufen nach 30 Minuten ab, der Slot wird wieder frei

### Mitarbeiter von PS oder PW können

- alle gebuchten Termine mittels einer Kalenderaddresse abonnieren und in ihren eigenen Kalender (Google & Outlook) integrieren
   - wann abonnierte Kalender synchronisiert werden   unklar,     Mitarbeiter müssen im Zweifel bei kurz bevorstehenden Terminen     im tool nachsehen
- soweit vorgesehen: Ihre Verfügbarkeit für Termin-Slots im eintragen (via. Contao-Backend)
- soweit vorgesehen: Ihre Verfügbarkeit für Termin-Slots bearbeiten (via. Contao-Backend)


### Fachliche Fragen

 1. Sind die buchbaren Zeiten immer gleich (z.B.. Mo. & Mit. 13, 14 und 15Uhr) oder ständig neu (Feiertage, Schließzeiten, etc.)?
     1. Wer darf alles die Zeiten anpassen (müssen leicht anzupassen sein),
     2. Mit wieviel Vorlaufzeit sind offene Terminslots bekannt?
     3. Wie sollen Terminslots geändert werden?
         1.  per Contao-Backend?
         2. ein eigenes Backend des Tools?
         3. per Mail an das Tool?
         4. per eigenem Kalendereintrag?
 2. Dürfen Besucher auch belegte (anonyme) Termine  sehen (um über die Terminlage generell informiert zu sein)?
 3. Sollen Besucher eine Bestätigungsmail bekommen und in dieser den Termin auch bestätigen?
 4. Welche Informationen sollen Besucher der Seite für den Termin eingeben?
     1. Name, Telefon, Alter, Nachricht, Ansprechpartner bei AfA/Jobcenter?
     2. Wer soll die Informationen bekommen? (eine Koordinierungstelle,     die konkreten verschiedenen Sachbarbeitenden, andere?)
 5. Wer oder wie viele Menschen/Kontakte werden informiert? Gibt es nur ein Stelle die je für PW/PS involviert  , oder müssen wie bei deiner Arztreferenz auch verschiedene Personen/Themen/Schwerpunkte o.ä. koordiniert werden?
 6. Gibt es mehrere Räume die z.B. abhängig genutzt und in die Modellierung eingebaut werden müssen?
 7. Gibt es irgendwas zu beachten bei Minderjährigen und E-Mails oder Zeitbuchungen?
 8. Wenn E-Mail nicht klappt, Fallback auf Telefon (WhatsApp, Signal whatever?)
 9. Hinweis: Rücksprache mit Datenschutzbeauftragtem bzgl. E-Mail Validierung!
10. Sollen die Mitarbeiter direkten E-Mail Kontakt zu den Klienten aufnehmen können, z.B. um Termin zu verschieben, stornieren, Rückfragen?
11. Müssen stornierte Termine gespeichert werden? Wegen Kosten oder Rückverfolgung?
12. Soll das tool Klienten einen Tag vor dem Termin noch mal per Mail informieren o.ä.?


### Technische Fragen

 1. Die verwendete Contao-Version hat bekannte Sicherheitslücken, wann wird aktualisiert?
 2. Ich benötige eigene Datenbanken (oder Speicher direkt in Contao) für die Termine und E-Mails
 3. E-Mail Validierung bei Buchung:
     1. Terminbuchungstool muss E-Mails schicken können (IMAP-Konto)
     2. Wann sollen Nutzerdaten gelöscht werden? (Fachlich und aus DSGVO     Sicht)
 4. Art.13 DSGVO: festgelegte Rechtsgrundlage:
     1. Nutzer die sich anmelden haben das Recht auf Dateneinsicht und     Datenlöschung, wie damit am besten umgehen?
     2. Ein Löschkonzept sowie geregelte Zugriffe der Mitarbeitenden.
     3. Datenminimierung und Speicherbegrenzung verlangen, nur     notwendige Daten und nur so lange wie erforderlich zu speichern.
 5. Hat der Mailserver SPF, DKIM und DMARC für die Absenderdomain eingerichtet?
 6. Serverseitige Input-Validierung, CSRF-Schutz, Rate Limits, Bot-Schutz mit Datenschutzfreundlicher Eskalation und keine preisgebenden Fehlermeldungen?
 7. Gibt es Staging und Development Systeme für die Entwicklung?
 8. Wer verantwortet Betrieb, Updates, Backups, Monitoring und Datenschutzanfragen?


## 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.

## 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.
- Eine in Contao CMS funkionierende Lösung sein.
- 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 ins Contao Backend integriert werden können.

## Technische Anforderungen

- Die Lösung muss im Contao CMS sauber einbindbar sein.
- Die Terminliste soll klar, verständlich und mobil kompatibel sein.
- Zugriffsdaten und Zugangsspezifika sind als Umgebungsvariablen bzw. sichere Konfiguration zu behandeln.
- Die technische Architektur soll die Integration ins Contao Backend sauber abbilden, ohne dass das Frontend später neu geschrieben werden muss falls die Kommunikation zu Datenbank angepasst werden muss. (Separation of concerns)

## 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 eingesetzt werden, nur mit abgesicherten, validierten Requests arbeiten.
- Bei Backend- und API-Setup: sichere Authentifizierung, autorisierte Zugriffe und minimal notwendige Berechtigungen verwenden.

## 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 und Backend 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. Das Design und die Nutzerführung für Booking-Flow definieren.
2. Die geeignete Architektur für die Terminbuchung bestimmen.
3. Die Buchungs-UI mit den erforderlichen Projekten und Terminarten umsetzen.
4. Testfälle für Kernfunktionen schreiben und anschließend die Umsetzung validieren.

## Abnahme

Die Aufgabe gilt als abgeschlossen, wenn:

- wenn eine Contao-Komponente erstellt wurde die im Contao-Backend eingebunden werden kann
- auf der Contao-Webseite die Terminbuchung angezeigt wird.
- die Terminarten auswählbar sind,
- die Oberfläche mobil-first, performant und barrierearm ist,
- das Frontend in TypeScript umgesetzt wurde,
- 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.