survey-bundle/AI_HANDOVER.md

# 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
- Die Frontend-Sperre für veröffentlichte Umfragen soll bewusst nicht tief im System verankert sein.
  - Für Redakteure genügt das Ausblenden bzw. Deaktivieren der relevanten Buttons und Formulare im Frontend.
  - Es ist ausdrücklich keine zusätzliche harte Systembarriere gewünscht, solange die Redakteursoberfläche den Bearbeitungspfad sauber schließt.

- 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

- Bewusster Trade-off zwischen Frontend und Backend:
  - Ein veröffentlichter Survey soll für Frontend-Redakteure praktisch nicht mehr bearbeitbar sein.
  - Im Backend darf der Admin trotz Veröffentlichung weiterhin Änderungen vornehmen, zum Beispiel für Rechtschreibfehler oder kleine Korrekturen.
  - Dadurch bleibt bewusst das Risiko bestehen, dass der Admin auch Fragen oder Strukturen ändert, obwohl bereits Antworten vorliegen.
  - Mögliche Folgen sind verwässerte oder fachlich falsche Ergebnisseiten sowie Inkonsistenzen, wenn bestehende Antworten nicht mehr sauber zur später geänderten Struktur passen.
  - Dieses Risiko wird bewusst akzeptiert und organisatorisch über Briefing/Disziplin des Admins bzw. der zuständigen Redakteure abgefangen, nicht über eine harte technische Sperre im Backend.

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`