# 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.