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

• 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