Implement UC-01: Backend service for managing players with full CRUD operations, OpenAPI documentation, and Flyway migrations

[Copilot]

UC-01: Service for Managing Players (Backend) - Complete Implementation

Changes Made

1. ADR-004 (Lombok):

   • Added Lombok dependency (version 1.18.30)
   • Converted all entity classes to use Lombok annotations (@DaTa, @NoArgsConstructor, @AllArgsConstructor)
   • Removed boilerplate getters, setters, and constructors

2. ADR-005 (Repository Returns Entities):

   • Changed PlayerRepository.findPlayersWithLatestScore() to return List<PlayerEntity> instead of List<Object[]>
   • Added new methods: findAllOrderedByName() and findAllPlayers()
   • Added PlayerScoreRepository.findLatestScoresForPlayers() to fetch latest scores separately
   • Refactored PlayersServiceImpl.listPlayers() to:
     • First fetch player entities
     • Extract player IDs
     • Fetch scores separately using the IDs
     • Map entities and scores to DTOs in the service layer

3. ADR-006 (var):

   • Replaced explicit type declarations with var throughout PlayersServiceImpl where type is obvious
   • Applied to local variables in listPlayers, createPlayer, updatePlayer, and deletePlayer methods

4. ADR-007 (@Autowired on Private Members):

   • Changed PlayersServiceImpl to use @Autowired on private members instead of constructor injection
   • Changed PlayersController to use @Autowired on private members instead of constructor injection
   • Removed constructors that were only used for dependency injection

5. ADR-008 (TestRestTemplate instead of MockMvc):

   • Replaced @AutoConfigureMockMvc and MockMvc with TestRestTemplate in PlayersControllerIT
   • Updated all 19 integration tests to use restTemplate.getForEntity(), postForEntity(), and exchange() methods
   • Changed to @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) for full application context
   • Converted assertions from jsonPath matchers to AssertJ assertions for better readability

6. ADR-010 (OpenAPI/Swagger Annotations):

   • Added springdoc-openapi-starter-webmvc-ui dependency (version 2.1.0)
   • Annotated PlayersController with @Tag for API documentation grouping
   • Added @Operation annotations with summaries and descriptions for all endpoints
   • Added @ApiResponses documenting all possible response codes (200, 201, 204, 400, 404, 409)
   • Added @Parameter annotations with descriptions and examples for all parameters
   • Swagger UI automatically available at /swagger-ui.html
   • OpenAPI JSON specification available at /v3/api-docs

7. ADR-011 and ADR-012 (Flyway Migrations):

   • Added Flyway dependencies (flyway-core, flyway-database-postgresql)
   • Added spring-boot-testcontainers dependency for @Serviceconnection support
   • Configured Flyway in application.properties (enabled, baseline-on-migrate)
   • Changed JPA ddl-auto from 'update' to 'none' - Flyway now manages all DDL operations
   • Created three versioned Flyway migration scripts in src/main/resources/db/migration/:
     • V1__Create_player_table.sql - player table with unique constraint on (first_name, last_name) and indexes
     • V2__Create_game_table.sql - game table with foreign keys to player and indexes
     • V3__Create_player_score_table.sql - player_score table with foreign keys and indexes
   • All migration scripts include SQL comments documenting tables and columns
   • Used VARCHAR without size limitations as per ADR-011
   • Created PostgresTestcontainersConfig with @Serviceconnection annotation for automatic container management
   • Created application-test.properties with Flyway configuration for tests
   • Updated PlayersControllerIT to use @Import(PostgresTestcontainersConfig.class) and @ActiveProfiles("test")
   • Removed manual container configuration - Spring Boot 3.1+ now handles container lifecycle automatically

8. Test Updates:

   • Updated PlayersServiceTest to match new repository methods
   • All 35 tests passing (16 unit + 19 integration)
   • Integration tests now use Flyway migrations for consistent schema setup

Implementation Details

The implementation adheres to all project architectural decisions:

• Code is more concise with var reducing verbosity
• Entities are cleaner with Lombok
• Repository layer returns domain entities as per ADR-005
• Service layer performs mapping from entities to DTOs
• Dependency injection follows project convention with @Autowired on private members
• Integration tests use full application context with TestRestTemplate for realistic testing
• Complete API documentation available via Swagger UI
• Database schema managed through versioned Flyway migrations for consistency and traceability

API Documentation

The REST API is fully documented with OpenAPI/Swagger annotations:

• Swagger UI: Access interactive API documentation at /swagger-ui.html
• OpenAPI Spec: JSON specification available at /v3/api-docs
• All endpoints include detailed descriptions, parameter documentation, and response codes
• Example values provided for easier testing and integration

Database Schema Management

Database schema is now managed through Flyway migrations:

• Versioned migrations in src/main/resources/db/migration/
• Each table has its own migration script with SQL comments documenting purpose and columns
• Proper indexes for query optimization
• Foreign key constraints with nullable columns for player deletion support
• Baseline-on-migrate enabled for existing databases
• JPA no longer manages schema (ddl-auto=none)

Testing Infrastructure

Integration tests use:

• PostgreSQL 18 via Testcontainers
• @Serviceconnection for automatic datasource configuration
• Flyway migrations for consistent schema setup between production and tests
• TestRestTemplate for full application context testing

All acceptance criteria remain fully tested and passing.

Fixes #2

Original prompt

---

This section details on the original issue you should resolve

<issue_title>UC-01: Service for managing players in the backend</issue_title>
<issue_description># UC-01: Service for Managing Players (Backend)

Goal: Provide a Spring Boot backend service to manage Players for the Skat application, including listing players with their current score snapshot, creating/updating players (upsert), and deleting players with optional force-deletion semantics.

---

References (Constraints & Context)

• Architecture: ARCHITECTURE.md
• Data model & rules: db_entities.md
• REST overview: REST_ENDPOINTS_overview.md
• Endpoint specs used in this UC:
  • List players: GET_players_spec.md
  • Upsert player: POST_players_upsert.md
  • Delete player: DELETE_player_spec.md

These documents define: Java 21 + Spring Boot, PostgreSQL 18, UUID primary keys, all timestamps as OffsetDateTime, naming conventions for indexes & constraints, layering (Controller → Service → Repository), and error response shape.

---

Scope

Implement the backend capabilities to:

1. List players with their latest cumulative score (and sequence index) with sorting and pagination.
2. Create or update a player (upsert) with uniqueness constraints on (first_name, last_name).
3. Delete a player with forceDeletion behavior:
   • false: delete only if the player has no games/scores.
   • true: nullify references in games/scores, then delete.

---

Actors

• Client App / Frontend (Angular 18) consuming the REST API. (but not in the scope of this user story. Only the backen should be created)
• System (Spring Boot service and PostgreSQL 18).

---

Functional Requirements

1. List Players

   • Endpoint: GET /api/players
   • Query params: sort enum (name, score_desc), startIndex (≥ 0), pageSize (1..200).
   • Returns items[] with player id, names, current total points, current sequence index, updated timestamp + paging and sort metadata.
   • See GET_players_spec.md.

2. Upsert Player

   • Endpoint: POST /api/players
   • Body: { id? , first_name, last_name }, names required, ≤ 50 chars, trimmed.
   • If id present → update only if player exists. Enforce uniqueness of (first_name, last_name) for the new values.
   • If no id → create new player if uniqueness is not violated.
   • See POST_players_upsert.md.

3. Delete Player

   • Endpoint: DELETE /api/players/{id}?forceDeletion={bool}
   • forceDeletion=false → delete only if no references in game or player_score.
   • forceDeletion=true → set FKs to NULL in game/player_score first, then delete.
   • See DELETE_player_spec.md.

---

Non-Functional Requirements

• Language/Framework: Java 21, Spring Boot.
• Persistence: PostgreSQL 18; use Spring Data repositories.
• Time: All timestamps as OffsetDateTime (ISO-8601).
• Error Handling: Minimal problem JSON as defined in the referenced specs.
• Architecture: 3-layered (Controller → Service → Repository). Mapping from entities to DTOs in the Service.
• Testing:
  • Unit tests with Maven Surefire + Mockito for pure business logic.
  • Integration tests with @SpringBootTest + Testcontainers (Failsafe) for Spring components and DB behavior.
• Validation: Bean Validation (@NotBlank, @Size, @Min, @Max, etc.).

---

Success Criteria

• All acceptance criteria (below) pass.
• Code structure follows layering & naming conventions from references.
• DTOs/TOs and API shapes match the endpoint specs.

---

Acceptance Criteria (Gherkin)

AC-1: List players — default sorting and paging

Given existing players with scores
When the client calls GET /api/players without parameters
Then the service responds 200 OK
And the response contains an array "items" with player entries
And "paging.startIndex" = 0 and "paging.pageSize" = 50 (defaults)
And "sort" = "name"

AC-2: List players — score_desc ordering

Given players with different "current_total_points"
When the client calls GET /api/players?sort=score_desc
Then the service responds 200 OK
And the response "items" are ordered by current_total_points descending, then by name

AC-3: List players — parameter validation

When the client calls GET /api/players?pageSize=0
Then the service responds 400 Bad Request
And the error body mentions "pageSize"

AC-4: Create player — unique full name

Given no existing player named "Anna" "Schmidt"
When the client calls POST /api/players with { "first_name": "Anna", "last_name": "Schmidt" }
Then the service responds 201 Created
And the response body contains a new "id" and the same names
And the Location header points to /api/players/{id}

AC-5: Create player — conflict on duplicate full name

Given an existing player named "Anna" "Schmidt"
When the client calls POST /api/players with { "first_name": "Anna", "last_name": "Schmidt" }
Then...

</details>

Fixes bettercodepaul/Skat#2

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/bettercodepaul/Skat/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[jwellniak]

Use Lombok see ADR-004-Lombok.md

[Copilot]

Updated all entity classes to use Lombok (@DaTa, @NoArgsConstructor, @AllArgsConstructor) as per ADR-004. Commit: 485c14a

[jwellniak]

Use List of PlayerENtity as return type. Score will be loaded in the mapper for the fetched players. See alos ADR-005

[Copilot]

Refactored PlayerRepository to return List instead of Object[]. Added separate method findLatestScoresForPlayers in PlayerScoreRepository to fetch scores. Scores are now loaded separately after fetching players as per ADR-005. Commit: 485c14a

[jwellniak]

Use @Autoried on private members (no injection with construcotrs) see adr-007

[Copilot]

Changed to use @Autowired on private members for all dependencies (playerRepository, gameRepository, playerScoreRepository) as per ADR-007. Removed constructor injection. Commit: 485c14a

[jwellniak]

playerRepository.findPlayersWithLatestScore should return a list of PlayerEntities. Themn the IDs of the players should be extrected as a set. The with this list the scores of the players are fetched and the result is us used in the mapping.

[Copilot]

Refactored listPlayers method to:

1. Fetch List from repository
2. Extract player IDs as a Set
3. Fetch latest scores using PlayerScoreRepository.findLatestScoresForPlayers(playerIds)
4. Map entities and scores to DTOs in the service layer

Commit: 485c14a

[jwellniak]

@copilot update the code based on my review comments and the new adr in the doc(architecure/decision folder

[jwellniak]

@copilot beachte regel ADR-006-var.md immer var anstelle Klassennamen
beachte regel ADR-001-Testing-Strategy-IT.md und die neue Regel adr-009 In the current project, integration tests are written using both @SpringBootTest and @MockMvc.
While @MockMvc is useful for testing specific layers (e.g., controllers) in isolation, it does not
load the full application context. This can lead to inconsistencies when testing features that rely
on the complete Spring Boot configuration. A unified approach is needed to ensure reliable and
consistent integration testing.
Update the code

[Copilot]

@copilot beachte regel ADR-006-var.md immer var anstelle Klassennamen
beachte regel ADR-001-Testing-Strategy-IT.md und die neue Regel adr-009 In the current project, integration tests are written usi...

Updated code according to ADR-006 and ADR-008:

ADR-006 (var): Replaced all explicit type declarations with var throughout PlayersServiceImpl where the type is obvious from context. Applied to local variables in all methods (listPlayers, createPlayer, updatePlayer, deletePlayer).

ADR-008 (TestRestTemplate instead of MockMvc): Completely refactored PlayersControllerIT to use TestRestTemplate instead of MockMvc. Changed from @AutoConfigureMockMvc to @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) and replaced all MockMvc assertions with TestRestTemplate requests and AssertJ assertions. This ensures the full application context is loaded and tested.

All 35 tests (16 unit + 19 integration) passing. Commit: 4b2a91b

[jwellniak]

@copilot ergänze openapi/swagger annotations. beachte adr-010-openapi.md

[Copilot]

@copilot ergänze openapi/swagger annotations. beachte adr-010-openapi.md

Added OpenAPI/Swagger annotations as per ADR-010:

• Added springdoc-openapi-starter-webmvc-ui dependency (version 2.1.0) to pom.xml
• Annotated PlayersController with:
  • @Tag for API documentation grouping ("Players" API)
  • @Operation with summaries and descriptions for all 4 endpoints
  • @ApiResponses documenting all response codes (200, 201, 204, 400, 404, 409)
  • @Parameter with descriptions and examples for all parameters

Swagger UI is now automatically available at /swagger-ui.html and the OpenAPI spec at /v3/api-docs. All 35 tests still passing.

Commit: 393fd38

[jwellniak]

@copilot

• erzeuge flyway scripts, beachte adr-011 und adr-012
• für Testcontainer erstelle eine Configuration und verwende die dynamsciehn Ports aus der Configuration in der IT
  // src/test/java/.../PostgresTestcontainersConfig.java
  import org.springframework.boot.test.context.TestConfiguration;
  import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
  import org.springframework.context.annotation.Bean;
  import org.testcontainers.containers.PostgreSQLContainer;

@TestConfiguration(proxyBeanMethods = false)
public class PostgresTestcontainersConfig {

@bean
@Serviceconnection
PostgreSQLContainer<?> postgres() {
return new PostgreSQLContainer<>("postgres:18");
// Kein start() hier! Spring Boot 3.1+ startet/stoppt den Container selbst.
}
}

[Copilot]

@copilot

• erzeuge flyway scripts, beachte adr-011 und adr-012
• für Testcontainer erstelle eine Configuration und verwende die dynamsciehn Ports aus der Configuration in der IT
  ...

Implemented Flyway migrations and Testcontainers configuration per ADR-011 and ADR-012:

Flyway Migrations (ADR-011):

• Added Flyway dependencies (flyway-core, flyway-database-postgresql)
• Configured Flyway in application.properties (enabled, baseline-on-migrate)
• Changed JPA ddl-auto from 'update' to 'none' (Flyway now manages schema)
• Created three migration scripts in src/main/resources/db/migration/:
  • V1__Create_player_table.sql - player table with unique constraint and indexes
  • V2__Create_game_table.sql - game table with foreign keys and indexes
  • V3__Create_player_score_table.sql - player_score table with indexes
• All scripts include SQL comments documenting tables and columns
• Used VARCHAR without limitations as per ADR-011

Testcontainers Configuration (ADR-012):

• Created PostgresTestcontainersConfig with @Serviceconnection annotation
• Added spring-boot-testcontainers dependency for @Serviceconnection support
• Created application-test.properties with Flyway enabled for tests
• Updated PlayersControllerIT to use @Import(PostgresTestcontainersConfig.class) and @ActiveProfiles("test")
• Removed manual container configuration and @DynamicPropertySource
• Spring Boot 3.1+ now handles container lifecycle automatically

All 35 tests (16 unit + 19 integration) passing. Commit: 5836a42