Implementierungsplan: Feature 1 – Survey Management (Admin)

Kontext

Dieses Dokument beschreibt den Implementierungsplan für das Feature “Survey Management” im Online-Survey-Backend.

Projektkontext: Spring Boot 3.x, Java 17, Spring Data JPA, H2 (Dev), jqwik (Property-Based Testing)

Referenzdokumente:

• Feature-Spezifikation: /docs/features/feature-1-survey-management.md
• Semantisches Datenmodell: /docs/semantic_data_model.md
• Architektur-Dokumentation: /docs/architecture.md

Entscheidungen

• Schichtenreihenfolge: Bottom-up: zuerst Persistenzmodell, dann Datenzugriff, Business-Logik und API; jeder Schritt wird verifiziert, bevor der nächste beginnt
• Testdesign: Automatisierte Tests entstehen zusammen mit der jeweiligen Schicht; Property-Based Tests ergänzen anschließend die kritischen Validierungsinvarianten
• Datenzugriff: Spring Data Naming Conventions werden bevorzugt; explizite Abfragen sind zulässig, wenn sich ein Use Case damit nicht sinnvoll ausdrücken lässt
• Fehlerbehandlung: Einheitliche HTTP-Fehlerantworten über einen zentralen Exception-Handler

---

Schritt 1: Persistenzmodell gemäß Datenmodell

Ziel: Das Persistenzmodell für Surveys, Fragen und Antwortoptionen gemäß dem semantischen Datenmodell anlegen.

Scope:

• Abbildung der Entitäten und Aufzählungstypen aus dem Datenmodell
• Validierungsregeln und Kaskadierverhalten gemäß Feature-Spezifikation
• Schema-Erzeugung für die Dev-Datenbank

Nicht im Scope: Repositories, Business-Logik, API

Akzeptanzkriterien:

• Persistenzmodell entspricht dem semantischen Datenmodell
• Anwendung startet fehlerfrei, Schema wird korrekt erzeugt

Verifikation:

• Bestehenden Maven-Testlauf mit mvn test ausführen
• Anwendung im Dev-Profil starten und die Schema-Erzeugung auf Fehler prüfen

---

Schritt 2: Datenzugriffsschicht

Ziel: Den Datenzugriff für Surveys, Fragen und Antwortoptionen bereitstellen.

Scope:

• Repository-Schnittstellen für die Persistenzobjekte aus Schritt 1
• Abfragen, die für die Feature-Use-Cases benötigt werden (z. B. Fragen einer Survey in Reihenfolge)
• Integrationstests für die benötigten Abfragen und Kaskadierregeln

Nicht im Scope: Business-Logik, API

Akzeptanzkriterien:

• Datenzugriff folgt den bestehenden Projektkonventionen
• Benötigte Abfragen und Kaskadierregeln funktionieren für die relevanten Erfolgs- und Fehlerfälle

Verifikation:

• Maven-Testlauf mit mvn test ausführen
• Prüfen, dass die neuen Datenzugriffstests unabhängig voneinander erfolgreich laufen

---

Schritt 3: Business-Logik und API-Verträge

Ziel: Die Business-Regeln der Survey-Verwaltung und die zugehörigen Request/Response-Verträge umsetzen.

Scope:

• Anlegen und Lesen von Surveys
• Hinzufügen und Löschen von Fragen inklusive Validierungsregeln aus der Feature-Spezifikation
• Löschen von Surveys inklusive abhängiger Daten
• Abbildung zwischen Persistenzmodell und API-Verträgen
• Fachliche Fehlerfälle (nicht gefunden, Validierung, Konflikte)
• Unit-Tests für die Business-Logik mit Erfolgs- und Fehlerfällen

Nicht im Scope: REST-Controller, API-Integrationstests, Property-Based Tests

Akzeptanzkriterien:

• Alle Business-Regeln aus der Feature-Spezifikation sind umgesetzt
• Validierungs- und Konfliktfälle liefern klare Fehlermeldungen
• Unit-Tests decken die relevanten Erfolgs- und Fehlerfälle ab

Verifikation:

• Maven-Testlauf mit mvn test ausführen
• Prüfen, dass für jede Business-Regel mindestens ein positiver oder negativer Testfall existiert

---

Schritt 4: REST-API

Ziel: Die Survey-Verwaltung über REST-Endpunkte bereitstellen.

Scope:

• Endpunkte für die Use Cases aus Schritt 3
• Einheitliche Fehlerbehandlung und Request-Validierung
• Ausrichtung an den bestehenden REST-Konventionen des Projekts
• API-Integrationstests für die zentralen Erfolgs- und Fehlerfälle

Nicht im Scope: Property-Based Tests, End-to-End-/UI-Tests, Lasttests

Akzeptanzkriterien:

• Endpunkte decken die Feature-Use-Cases ab
• Fehlerantworten haben ein einheitliches Format
• API-Integrationstests prüfen die zentralen Erfolgs- und Fehlerfälle

Verifikation:

• Maven-Testlauf mit mvn test ausführen
• Anwendung im Dev-Profil starten und die zentralen Use Cases manuell gegen die REST-API prüfen

---

Schritt 5: Absicherung durch Property-Based Tests

Ziel: Die kritischen Validierungsinvarianten mit generierten Eingaben automatisiert absichern.

Scope:

• Property-Based Tests für die zentralen Validierungsinvarianten
• Eigene Generatoren für gültige und ungültige Survey- und Question-Daten, soweit erforderlich
• Ausführung als Bestandteil des bestehenden Maven-Testlaufs

Nicht im Scope: Weitere API-Endpunkte, End-to-End-/UI-Tests, Lasttests

Akzeptanzkriterien:

• Kritische Invarianten aus der Feature-Spezifikation sind durch Properties abgedeckt
• Property-Based Tests prüfen Invarianten, nicht nur einzelne Beispiele
• Der vollständige Testlauf ist deterministisch reproduzierbar oder meldet den verwendeten Seed für eine Wiederholung

Verifikation:

• Vollständigen Maven-Testlauf mit mvn test ausführen
• Einen fehlgeschlagenen Property-Test anhand seines Seeds lokal wiederholen können

---

Hinweise zur Verwendung

1. Sequenzielle Ausführung: Die Schritte bauen aufeinander auf. Schritt N setzt die Fertigstellung von Schritt N-1 voraus.
2. Bootstrap zuerst: Vor dem ersten Schritt den Bootstrap-Prompt ausführen, damit der Agent den Projektkontext versteht.
3. Review-Gates: Nach jedem Schritt das Ergebnis und die dokumentierte Verifikation prüfen, bevor der nächste startet. Bei klar zusammenhängenden Teilergebnissen können eng verwandte Schritte in einem Review-Gate gebündelt werden.
4. Scope-Disziplin: Der Agent setzt nur den definierten Scope um. Konkrete Typ- und Methodennamen wählt er während der Umsetzung anhand von Feature-Spezifikation, Datenmodell und bestehenden Patterns.
5. Living Plan: Wesentliche Abweichungen vom Plan begründen, den Plan aktualisieren und bei größeren Scope-Änderungen erneut freigeben.
6. Kontext-Management: Bei langen Sessions kann eine frische Session mit erneutem Bootstrap sinnvoll sein.