From 809c30e5b525ed28352ad69a0b1f4d9274281c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Mummert?= Date: Sun, 7 Jun 2026 22:26:47 +0200 Subject: [PATCH] Add AI handover documentation --- AI_HANDOVER.md | 404 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 AI_HANDOVER.md diff --git a/AI_HANDOVER.md b/AI_HANDOVER.md new file mode 100644 index 0000000..89a17cf --- /dev/null +++ b/AI_HANDOVER.md @@ -0,0 +1,404 @@ +# Survey Bundle AI Handover + +Diese Datei beschreibt den aktuell gewünschten und umgesetzten Stand des Bundles. Ziel ist, dass ein KI-Modell oder ein neuer Bearbeiter die Logik, die Zustände und die wichtigsten Einstiegspunkte schnell versteht und darauf weiterarbeiten kann. + +## Zweck des Bundles + +Das Bundle stellt ein Contao-Umfragesystem bereit mit: + +- Frontend-Liste für Redakteure +- Frontend-Frageneditor +- Öffentlicher Umfrageansicht über Alias-Link +- Ergebnisseite im Frontend +- Excel-Export der Ergebnisse +- PDF-Export der Ergebnisse über Gotenberg +- Backend-Verwaltung in Contao-DCA-Listen und Editmasken + +## Zentrale Zustandsfelder + +Die Umfrage arbeitet mit drei relevanten Zuständen in `tl_survey`: + +- `published` + - Fachlich: Die Umfrage wurde veröffentlicht. + - Frontend: Ab Veröffentlichung darf der Redakteur im Frontend weder Fragen noch Metadaten bearbeiten. + - Backend: Reversibel erlaubt. Der Admin darf den Status im Backend ändern. + +- `isActive` + - Fachlich: Öffentliche Sichtbarkeit an/aus. + - Gilt unabhängig vom Veröffentlichungsstatus als technischer Sichtbarkeitszustand. + - Der öffentliche Reader liefert nur Umfragen aus, die `published = 1` und `isActive = 1` haben. + +- `isLocked` + - Fachlich: Struktur wurde bereits benutzt oder veröffentlicht. + - Wird automatisch gesetzt, wenn die erste Antwort gespeichert wird. + - Wird beim Veröffentlichen ebenfalls gesetzt. + - Im Backend gibt es bewusst keine harte Sperre mehr. Das Feld dient vor allem der internen Logik und Historie. + +## Gewollte Produktentscheidung + +- Frontend ist streng: + - Keine Fragenbearbeitung nach Veröffentlichung + - Keine Metadatenbearbeitung nach Veröffentlichung + - Keine Fragenbearbeitung nach ersten Teilnahmen + +- Backend ist bewusst toleranter: + - Ein einzelner Admin darf im Notfall weiter arbeiten + - Statt harter Sperre gibt es nur einen Warnhinweis in der Liste bei veröffentlichten Umfragen + - `published` ist im Backend editierbar + - `isActive` ist im Backend per Contao-Toggle schaltbar + +Diese Entscheidung ist absichtlich so getroffen und kein Bug. + +## Datenmodell und wichtige Tabellen + +- `tl_survey` + - Umfrage-Stammdaten und Statusfelder +- `tl_survey_content` + - Fragen der Umfrage +- `tl_survey_condition` + - Generische Sprungregeln +- `tl_survey_editor` + - Zugewiesene Frontend-Redakteure +- `tl_survey_submission` + - Umfrage-Durchläufe +- `tl_survey_answer` + - Gespeicherte Antworten inklusive Snapshot-Feldern zur Ergebnisstabilität + +Wichtige Snapshot-Felder in `tl_survey_answer`: + +- `questionType` +- `questionLabel` +- `questionDescription` +- `questionSorting` + +Diese Felder sorgen dafür, dass Ergebnisse auch dann stabil bleiben, wenn Fragen später im Backend verändert oder gelöscht wurden. + +## Frontend-Module und Controller + +### 1. Redakteursliste + +Controller: + +- `src/Controller/FrontendModule/MemberSurveyListController.php` + +Template: + +- `contao/templates/frontend/member_survey_list.html.twig` + +Zweck: + +- Zeigt alle dem eingeloggten Frontend-Mitglied zugewiesenen Umfragen +- Sortierung ist bewusst fest auf `Titel ASC` +- Hier liegen die Redakteursaktionen zur Veröffentlichung und Aktivierung + +Aktuelle Button- und Sichtbarkeitslogik pro Umfrage: + +- `Bearbeiten` + - Nur klickbar, solange `published = 0` + - Nach Veröffentlichung disabled +- `Öffentliche Ansicht` + - Nur sichtbar, wenn `published = 1` +- `Entwurfs-Ansicht` + - Nur sichtbar, wenn `published = 0` +- `Ergebnisse anzeigen` + - Immer verfügbar, sofern Results-Seite konfiguriert ist +- `Umfrage veröffentlichen` + - Eigene Aktion in der Liste + - Nach Veröffentlichung disabled und textlich als veröffentlicht markiert +- Kreis grau/grün + - Schaltet `isActive` + - Ist bewusst kein Auge mehr + +### 2. Frontend-Editor + +Controller: + +- `src/Controller/FrontendModule/MemberSurveyEditController.php` + +Template: + +- `contao/templates/frontend/member_survey_edit.html.twig` + +Zweck: + +- Anlegen neuer Umfragen +- Bearbeiten der Metadaten vor Veröffentlichung +- Bearbeiten der Fragenstruktur + +Aktueller Aufbau: + +- Bei neuer Umfrage: + - Titel und Beschreibung +- Bei bestehender, nicht veröffentlichter Umfrage: + - Metadatenformular oberhalb des Frageneditors + - Frage-für-Frage-Editor im Akkordeon + - Neue Frage anlegen + - Sprungregelübersicht rechts/unten je nach Breakpoint +- Bei veröffentlichter Umfrage oder bei `isLocked = 1`: + - Fragen im Frontend nicht mehr änderbar + - Metadaten im Frontend ebenfalls nicht mehr bearbeitbar + +Wichtige Entscheidung: + +- Die Header-Badges im Fragen-Akkordeon wurden bewusst entfernt. + - Typ, Pflicht usw. sollen nicht schon im Header gezeigt werden. + - Die Details sieht man erst nach dem Aufklappen. + +### 3. Öffentliche Umfrageansicht + +Controller: + +- `src/Controller/FrontendModule/ShowSurveyController.php` + +Services: + +- `src/Service/SurveyFlowService.php` +- `src/Service/SurveySubmissionService.php` + +Zweck: + +- Öffentliche Teilnahme an Umfragen +- Zusätzlich Entwurfsansicht per `?preview=1` + +Wichtige Regeln: + +- Öffentliche Ansicht findet eine Umfrage nur, wenn: + - `published = 1` + - `isActive = 1` +- Entwurfsansicht arbeitet ohne Speicherung +- Öffentliche Ansicht speichert Antworten und erstellt/führt Submission fort +- Rückwärtsnavigation ist implementiert + +### 4. Ergebnisseite + +Controller: + +- `src/Controller/FrontendModule/ShowSurveyResultsController.php` + +Service: + +- `src/Service/SurveyResultsViewService.php` + +Template: + +- `contao/templates/frontend/show_survey_results.html.twig` + +Zweck: + +- Aggregierte Auswertung pro Frage +- Anzeige von Anzahl Teilnahmen, Rücklauf und Frageergebnissen + +Aktuelle Ergebnislogik: + +- `yes_no_maybe` + - Optionsstatistik plus Kreisdiagramm +- `choice` + - Optionsstatistik plus Kreisdiagramm +- `range` + - Minimum, Maximum, Durchschnitt plus Verteilung und Linienchart +- `text` + - Kein Pie-Chart + - Stattdessen Response-Summary und Liste der Freitextantworten + +Wichtig: + +- Die Ergebnisse werden aus den Antwort-Snapshots aufgebaut, nicht nur aus den aktuellen Fragen. +- Dadurch bleiben historische Ergebnisse stabil. + +## Sprunglogik + +Relevante Services/Repos: + +- `src/Service/SurveyFlowService.php` +- `src/Repository/SurveyConditionRepository.php` +- `src/Controller/FrontendModule/MemberSurveyEditController.php` + +Reihenfolge der Navigation: + +1. Direkter Ja/Nein-Sprung über `jumpOnYes` / `jumpOnNo` +2. Generische Bedingung aus `tl_survey_condition` +3. Nächste Frage nach Sortierung + +Wichtiger Detailpunkt: + +- In der Sprungregelübersicht im Frontend-Editor werden bewusst die Positionsnummern innerhalb der Umfrage angezeigt, nicht die globalen Datenbank-IDs der Fragen. + +## Excel-Export + +Controller: + +- `src/Controller/SurveyResultsExportController.php` + +Service: + +- `src/Service/SurveyResultsExportService.php` + +Bibliothek: + +- `phpoffice/phpspreadsheet` + +Zweck: + +- Export aller abgeschlossenen Teilnahmen in eine XLSX-Datei + +Aktuelle Spaltenlogik: + +- Ja/Nein/Vielleicht: + - pro Antwortoption eigene Spalte +- Choice: + - pro Antwortoption eigene Spalte +- Range: + - eine Wertespalte +- Text: + - eine Textspalte + +Wichtige Eigenschaft: + +- Die Spalten orientieren sich an den aktuell vorhandenen Fragen im Survey. +- Die Zeilen enthalten nur abgeschlossene Submissions. + +## PDF-Export + +Controller: + +- `src/Controller/SurveyResultsExportController.php` + +Service: + +- `src/Service/SurveyResultsPdfService.php` + +Template: + +- `src/Resources/views/pdf/survey_results.html.twig` + +Externe Abhängigkeit: + +- Gotenberg über `surveyGotenbergUrl` in den Contao-Einstellungen + +Zweck: + +- Serverseitiger PDF-Export der Ergebnisse + +Aktuelle Logik: + +- HTML wird serverseitig mit Twig gerendert +- Diagramme werden als SVG/Data-URI vorbereitet +- Gotenberg rendert daraus das PDF +- Ist keine Gotenberg-URL gesetzt, wird im Frontend kein PDF-Download angeboten + +## Backend-Aufbau + +### tl_survey + +Dateien: + +- `contao/dca/tl_survey.php` +- `contao/languages/de/tl_survey.php` +- `contao/languages/en/tl_survey.php` + +Wichtige Listenoperationen: + +- `Fragen bearbeiten` +- `Umfrage bearbeiten` +- `isActive` als Contao-Toggle +- Warnsymbol bei veröffentlichten Umfragen +- `Link kopieren` +- `Ergebnisse anzeigen` + +Aktuelle Backend-Entscheidung: + +- Das Warnsymbol genügt als Hinweis bei veröffentlichten Umfragen +- Es gibt bewusst keine harte Sperre für Fragen im Backend + +### Child-Tabellen + +- `tl_survey_content` +- `tl_survey_condition` +- `tl_survey_editor` + +Hinweis: + +- `isLocked` wird in den Child-Headerfeldern nicht mehr angezeigt, weil der Backend-Lock bewusst keine führende Benutzerfunktion mehr ist. + +### Systemeinstellungen + +Datei: + +- `contao/dca/tl_settings.php` + +Wichtige Settings: + +- `surveyReaderPage` +- `surveyResultsPage` +- `surveyGotenbergUrl` + +## Aktuelle Produktregeln in Kurzform + +- Frontend-Liste: + - Titel alphabetisch + - Veröffentlichung und Aktivierung in der Liste +- Frontend-Editor: + - Metadaten nur vor Veröffentlichung + - Fragenbearbeitung nur solange nicht veröffentlicht und keine Teilnahmen vorliegen +- Öffentliche Ansicht: + - Nur `published = 1` und `isActive = 1` +- Backend: + - `published` reversibel erlaubt + - `isActive` per Standard-Contao-Toggle + - nur Warnsymbol statt Backend-Sperre + +## Wichtige Dateien nach Themengebiet + +Frontend-Liste: + +- `src/Controller/FrontendModule/MemberSurveyListController.php` +- `contao/templates/frontend/member_survey_list.html.twig` + +Frontend-Editor: + +- `src/Controller/FrontendModule/MemberSurveyEditController.php` +- `contao/templates/frontend/member_survey_edit.html.twig` + +Öffentliche Umfrage: + +- `src/Controller/FrontendModule/ShowSurveyController.php` +- `src/Service/SurveyFlowService.php` +- `src/Service/SurveySubmissionService.php` + +Ergebnisse: + +- `src/Controller/FrontendModule/ShowSurveyResultsController.php` +- `src/Service/SurveyResultsViewService.php` +- `contao/templates/frontend/show_survey_results.html.twig` + +Exporte: + +- `src/Controller/SurveyResultsExportController.php` +- `src/Service/SurveyResultsExportService.php` +- `src/Service/SurveyResultsPdfService.php` + +Backend: + +- `contao/dca/tl_survey.php` +- `src/EventListener/SurveyDcaListener.php` + +## Technische Validierung, die in diesem Projekt gut funktioniert + +- `php -l` auf die geänderten PHP-Dateien +- `ddev exec php bin/console lint:yaml ...` +- `ddev exec php bin/console cache:clear` + +## Bekannte bewusste Trade-offs + +- Backend kann veröffentlichte Umfragen technisch weiterhin verändern. + - Das ist bewusst akzeptiert, weil nur ein Admin arbeitet. +- `isLocked` bleibt als internes Logikfeld bestehen, obwohl der Backend-Lock nicht mehr durchgesetzt wird. +- PDF-Export hängt von Gotenberg ab und ist absichtlich optional. + +## Empfohlene Einstiegspunkte für künftige Änderungen + +- Status-/Sichtbarkeitslogik: `SurveyRepository`, `SurveyEditorService`, `MemberSurveyListController` +- Fragerouting: `SurveyFlowService`, `SurveyConditionRepository` +- Ergebnisdarstellung: `SurveyResultsViewService` +- Exportlogik: `SurveyResultsExportService`, `SurveyResultsPdfService` +- Backend-Operationen und DCA-Verhalten: `tl_survey.php`, `SurveyDcaListener` \ No newline at end of file