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