Feature-Spezifikation: Feature 1 – Survey Management (Admin)

Hinweis zur Terminologie: Diese Spezifikation verwendet Begriffe aus dem semantischen Datenmodell (Survey, Question, AnswerOption, QuestionTypeEnum). Das Modell ist ein eigenes Artefakt und wird hier nicht kopiert.

Kurzbeschreibung

Survey-Administrator:innen legen Online-Umfragen über die REST-API eines Backends an, konfigurieren sie, rufen sie ab und löschen sie. Dieses Inkrement umfasst den administrativen Lebenszyklus: Metadaten der Umfrage, geordnete Fragen mit typspezifischen Antwortoptionen, Abruf der vollständigen Struktur und kaskadierendes Löschen. Das Einsammeln von Antworten bei Teilnehmenden liegt außerhalb des Scopes.

Ziele

• Eine Umfrage mit Titel und Ersteller:in anlegen, optional mit Beschreibung, Start- und Enddatum.
• Geordnete Fragen der im Datenmodell definierten Typen hinzufügen (Rating, Single Choice, Multiple Choice, Freitext).
• Antwortoptionen mit Anzeigetext und internem Wert für jeden Fragetyp anlegen, der sie benötigt.
• Eine Umfrage mit Fragen nach aufsteigender OrderNumber und Antwortoptionen je Frage in der beim Anlegen übergebenen Reihenfolge abrufen.
• Eine einzelne Frage inklusive ihrer Antwortoptionen löschen, ohne andere Fragen derselben Umfrage zu verändern.
• Eine Umfrage inklusive aller Fragen und Antwortoptionen löschen.

Nicht-Ziele

• Keine Teilnehmenden-UI und keine öffentliche API zum Ausfüllen der Umfrage.
• Kein Authentifizierungs- oder Autorisierungsmodell in diesem Inkrement; die aufrufende Seite gilt als Administrator:in.
• Kein Publikations-Workflow, kein Entwurf/Veröffentlicht-Status jenseits der optionalen Start- und Enddaten der Umfrage.
• Keine Persistenz von SurveyResponse, ResponseAnswer oder Respondent. Diese Entitäten stehen im Datenmodell für spätere Features.
• IsOtherOption wird in diesem Inkrement nicht unterstützt. Eine Freitext-Option “Sonstiges” an Open-Fragen, wie sie das Datenmodell erlaubt, ist zurückgestellt.
• Keine Umsetzungsreihenfolge, Schichtung oder Wahl des Test-Frameworks. Das gehört in den Implementierungsplan.

Akteure und Journeys

Akteur:in: Survey-Administrator:in, Aufruf der administrativen API.

Journey 1: Einen nutzbaren Fragebogen anlegen

1. Die Administratorin oder der Administrator legt eine Umfrage mit Titel Kundenzufriedenheit 2026 und Ersteller:in QA-Team an. Beschreibung sowie Start- und Enddatum entfallen.
2. Die API liefert eine generierte Umfragekennung.
3. Die Administratorin oder der Administrator fügt drei Fragen in dieser Reihenfolge hinzu:
   • Reihenfolge 1, Rating, Pflicht, mit vier Antwortoptionen und internen Werten 1 bis 4;
   • Reihenfolge 2, Single Choice, Pflicht, mit drei Antwortoptionen;
   • Reihenfolge 3, Freitext, optional, ohne Antwortoptionen.
4. Die Administratorin oder der Administrator ruft die Umfrage über die Kennung ab und erhält die Metadaten, die drei Fragen in der gespeicherten Reihenfolge und die Antwortoptionen der ersten beiden Fragen jeweils in der beim Anlegen übergebenen Reihenfolge.

Journey 2: Eine Frage entfernen und die Umfrage verwerfen

1. Die Administratorin oder der Administrator löscht Frage 2 der Umfrage aus Journey 1.
2. Die Administratorin oder der Administrator ruft die Umfrage erneut ab und erhält nur noch die Fragen 1 und 3; ihre Reihenfolgenummern bleiben 1 und 3.
3. Die Administratorin oder der Administrator löscht die Umfrage.
4. Die Administratorin oder der Administrator ruft die Umfrage unter derselben Kennung ab und erhält “Not Found”.

Domänenregeln

Datentypen, Kardinalitäten und Feldbedingungen von Survey, Question und AnswerOption stehen im semantischen Datenmodell. Diese Spezifikation beschreibt ihre Auswirkungen an der API-Grenze und ergänzt featurebezogene Verhaltensregeln:

• Eine Umfrage wird auch angelegt, wenn Beschreibung, Start- und Enddatum fehlen; diese Felder sind dann leer.
• EndDate darf nicht vor StartDate liegen, wenn beide gesetzt sind (dieselbe Bedingung wie im Datenmodell; die API muss den Schreibvorgang ablehnen).
• OrderNumber ist im Datenmodell je Umfrage eindeutig. Diese Spezifikation ergänzt, dass die API verbleibende Fragen nach einem Löschen nicht neu nummeriert.
• Antwortoptionen werden je Frage in der beim Anlegen übergebenen Reihenfolge zurückgegeben. Das Datenmodell definiert für Optionen keine Reihenfolge; die Erhaltung dieser Reihenfolge ist eine zusätzliche Verhaltensanforderung dieses Features. Wie sie gespeichert wird, legt die Umsetzung fest.
• Rating-, Single-Choice- und Multiple-Choice-Fragen benötigen mindestens zwei Antwortoptionen.
• Das Löschen einer Frage löscht ihre Antwortoptionen. Das Löschen einer Umfrage löscht ihre Fragen und deren Optionen.

Fehlerfälle

Die folgenden Fehlerfälle sind zur eindeutigen Prüfung als Gegeben–Wenn–Dann-Szenarien formuliert. Validierungsfehler benennen das betroffene Feld oder den betroffenen Konflikt. Die API muss auch die referenzierten Regeln aus dem semantischen Datenmodell beim Schreiben durchsetzen.

1. Leerer Titel

   • Gegeben eine Anfrage zum Anlegen einer Umfrage
   • Wenn der Titel fehlt, leer ist oder nur aus Leerzeichen besteht
   • Dann wird die Anfrage mit einem Validierungsfehler zu Title abgelehnt

2. Vertauschte Datumsangaben

   • Gegeben eine Anfrage zum Anlegen mit beiden Datumsangaben
   • Wenn EndDate vor StartDate liegt
   • Dann wird die Anfrage mit einem Validierungsfehler zum Datumsbereich abgelehnt

3. Unbekannte Umfrage

   • Gegeben keine Umfrage mit der übergebenen Kennung
   • Wenn eine Frage hinzugefügt, die Umfrage abgerufen oder gelöscht wird
   • Dann wird die Anfrage als Not Found abgelehnt

4. Doppelte Reihenfolge

   • Gegeben eine Umfrage, die bereits eine Frage mit OrderNumber 2 hat
   • Wenn eine weitere Frage mit OrderNumber 2 hinzugefügt wird
   • Dann wird die Anfrage mit einem Validierungsfehler zu OrderNumber abgelehnt

5. Zu wenige Optionen

   • Gegeben eine Rating-, Single-Choice- oder Multiple-Choice-Frage
   • Wenn weniger als zwei Antwortoptionen übergeben werden
   • Dann wird die Anfrage mit einem Validierungsfehler zu den Antwortoptionen abgelehnt

6. Doppelte interne Werte

   • Gegeben eine Frage mit Antwortoptionen
   • Wenn zwei Optionen denselben internen Wert haben
   • Dann wird die Anfrage mit einem Validierungsfehler zu den kollidierenden Werten abgelehnt

7. Optionen an Freitextfrage

   • Gegeben eine Freitextfrage
   • Wenn Antwortoptionen übergeben werden
   • Dann wird die Anfrage mit einem Validierungsfehler zu den Antwortoptionen abgelehnt

8. IsOtherOption gesetzt

   • Gegeben eine beliebige Frage
   • Wenn eine Antwortoption IsOtherOption auf wahr setzt
   • Dann wird die Anfrage mit einem Validierungsfehler zu den Antwortoptionen abgelehnt, weil die Freitext-Option außerhalb dieses Inkrements liegt

9. Unbekannte Frage löschen

   • Gegeben keine Frage mit der übergebenen Kennung, auch nach einem vorherigen erfolgreichen Löschen
   • Wenn die Administratorin oder der Administrator diese Frage löscht
   • Dann wird die Anfrage als Not Found abgelehnt und die gespeicherte Umfrage bleibt unverändert

10. Abgelehntes Hinzufügen ohne Teiländerungen

    • Gegeben eine bestehende Umfrage und eine Anfrage zum Hinzufügen einer Frage mit einer ungültigen Antwortoption
    • Wenn die API die Anfrage bei der Validierung ablehnt
    • Dann bleiben weder die neue Frage noch einzelne Antwortoptionen gespeichert; die bestehende Umfrage bleibt unverändert

Akzeptanzkriterien

• Journey 1 lässt sich gegen die API ausführen und liefert die Fragen nach aufsteigender OrderNumber sowie deren Antwortoptionen jeweils in der beim Anlegen übergebenen Reihenfolge zurück.
• Journey 2 liefert nach dem Löschen einer Frage die unveränderten übrigen Fragen und nach dem Löschen der Umfrage “Not Found” beim erneuten Abruf.
• Alle oben beschriebenen Fehlerfälle liefern über die API die jeweils festgelegte Fehlerantwort. Abgelehnte Schreibvorgänge verändern die abrufbare Umfragestruktur nicht.
• Erfolgreiches Anlegen liefert die generierte Kennung der Umfrage oder Frage.
• Fehlerantworten nutzen ein einheitliches Format und benennen das Feld oder den Konflikt, der zur Ablehnung geführt hat.
• Die über die API angenommenen und zurückgegebenen Daten entsprechen den Namen, Typen und Bedingungen des semantischen Datenmodells für Survey, Question und AnswerOption. Die Einschränkungen aus den Nicht-Zielen werden durchgesetzt.

Verifikation

Jedes Gegeben–Wenn–Dann-Szenario wird durch mindestens einen automatisierten API-Test abgesichert. Ergänzende Persistenztests weisen nach, dass kaskadierendes Löschen keine Restdatensätze hinterlässt und abgelehnte Schreibvorgänge keine Teildaten speichern. Die Zuordnung zu den Umsetzungsschritten steht im Implementierungsplan.

Referenzen

Die folgenden Pfade beziehen sich auf das Beispielprojekt:

• Semantisches Datenmodell: /docs/semantic_data_model.md
• Architektur: /docs/architecture.md