From 98716c79b44e76b45f3e78415e1c93c3c9ef2653 Mon Sep 17 00:00:00 2001 From: Rob Date: Thu, 13 Aug 2026 17:19:32 +0200 Subject: [PATCH] init with AGENTS.md --- AGENTS.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9c51a11 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,129 @@ +# 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. + +## 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.