# Implementation Plan: Feature 1 – Survey Management (Admin) ## Context This document describes the implementation plan for the "Survey Management" feature in the online survey backend. **Project context:** Spring Boot 3.x, Java 17, Spring Data JPA, H2 (Dev), jqwik (Property-Based Testing) **Reference documents:** - Feature specification: `/docs/features/feature-1-survey-management.md` - Semantic data model: `/docs/semantic_data_model.md` - Architecture documentation: `/docs/architecture.md` ## Decisions - **Layer order:** Bottom-up: persistence model first, followed by data access, business logic, and API; each step is verified before the next one begins - **Test design:** Automated tests are created together with the corresponding layer; property-based tests then complement them for the critical validation invariants - **Data access:** Prefer Spring Data naming conventions; explicit queries are allowed when a use case cannot be expressed clearly with them - **Error handling:** Consistent HTTP error responses via a central exception handler --- ## Step 1: Persistence Model According to the Data Model **Goal:** Create the persistence model for surveys, questions, and answer options according to the semantic data model. **Scope:** - Map the entities and enumeration types from the data model - Validation rules and cascading behavior according to the feature specification - Schema generation for the development database **Out of scope:** Repositories, business logic, API **Acceptance criteria:** - Persistence model matches the semantic data model - The application starts without errors and the schema is created correctly **Verification:** - Run the existing Maven test suite with `mvn test` - Start the application with the development profile and check the schema generation for errors --- ## Step 2: Data Access Layer **Goal:** Provide data access for surveys, questions, and answer options. **Scope:** - Repository interfaces for the persistence objects from step 1 - Queries required by the feature use cases (e.g. questions of a survey in order) - Integration tests for the required queries and cascading rules **Out of scope:** Business logic, API **Acceptance criteria:** - Data access follows existing project conventions - Required queries and cascading rules work for the relevant success and failure cases **Verification:** - Run the Maven test suite with `mvn test` - Confirm that the new data access tests pass independently --- ## Step 3: Business Logic and API Contracts **Goal:** Implement the business rules for survey management and the related request/response contracts. **Scope:** - Create and read surveys - Add and delete questions, including validation rules from the feature specification - Delete surveys, including dependent data - Map between the persistence model and API contracts - Domain error cases (not found, validation, conflicts) - Unit tests for the business logic covering success and failure cases **Out of scope:** REST controllers, API integration tests, property-based tests **Acceptance criteria:** - All business rules from the feature specification are implemented - Validation and conflict cases produce clear error messages - Unit tests cover the relevant success and failure cases **Verification:** - Run the Maven test suite with `mvn test` - Confirm that every business rule has at least one positive or negative test case --- ## Step 4: REST API **Goal:** Expose survey management through REST endpoints. **Scope:** - Endpoints for the use cases from step 3 - Consistent error handling and request validation - Alignment with the project's existing REST conventions - API integration tests for the central success and failure cases **Out of scope:** Property-based tests, end-to-end/UI tests, load tests **Acceptance criteria:** - Endpoints cover the feature use cases - Error responses use a consistent format - API integration tests cover the central success and failure cases **Verification:** - Run the Maven test suite with `mvn test` - Start the application with the development profile and manually exercise the central use cases against the REST API --- ## Step 5: Property-Based Test Coverage **Goal:** Automatically protect the critical validation invariants with generated inputs. **Scope:** - Property-based tests for the central validation invariants - Custom generators for valid and invalid survey and question data where needed - Execution as part of the existing Maven test suite **Out of scope:** Additional API endpoints, end-to-end/UI tests, load tests **Acceptance criteria:** - Critical invariants from the feature specification are covered by properties - Property-based tests check invariants rather than individual examples - The full test suite is deterministically reproducible or reports the seed required to repeat a run **Verification:** - Run the full Maven test suite with `mvn test` - Be able to reproduce a failed property test locally using its seed --- ## Usage Notes 1. **Sequential execution:** Steps build on each other. Step N assumes step N-1 is complete. 2. **Bootstrap first:** Before the first step, run the bootstrap prompt so the agent understands the project context. 3. **Review gates:** Review the result and documented verification after each step before starting the next one. Closely related partial results may be bundled into one review gate. 4. **Scope discipline:** The agent implements only the defined scope. Concrete type and method names are chosen during implementation based on the feature specification, data model, and existing patterns. 5. **Living plan:** Justify material deviations from the plan, update the plan, and re-approve larger scope changes. 6. **Context management:** For long sessions, a fresh session with another bootstrap can help.