Add AI handover documentation
This commit is contained in:
Jürgen Mummert
+404
@@ -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`
|
||||||
Reference in New Issue
Block a user