Merge branch 'master' into test/bdd-given-when-then-pattern

Author: nanotaboada

.github/copilot-instructions.md

@@ -2,212 +2,131 @@
 
 ## Project Overview
 
-This is a Spring Boot REST API for managing football players, demonstrating modern Java patterns and clean architecture. It's a learning-focused proof-of-concept that follows Spring Boot best practices with layered architecture (Controller → Service → Repository).
+REST API for managing football players built with Java 25 and Spring Boot 4. Demonstrates layered architecture (Controller → Service → Repository), Spring Data JPA with SQLite, comprehensive validation, caching, and Swagger documentation.
 
-## Stack
-
-- **Java**: 25 (LTS, required for consistency)
-- **Spring Boot**: 4.0.0 (with Spring MVC)
-- **ORM**: Spring Data JPA with Hibernate
-- **Database**: SQLite (file-based for runtime, in-memory for tests)
-- **Build Tool**: Maven 3 (use `./mvnw` wrapper, NOT system Maven)
-- **Containers**: Docker with Docker Compose
-- **Logging**: SLF4J with Logback
-- **Monitoring**: Spring Boot Actuator
-- **API Docs**: SpringDoc OpenAPI 3 (Swagger UI)
-
-## Project Patterns
-
-- **Layered architecture**: Controller → Service → Repository → Database
-- **Dependency injection**: Constructor injection via Lombok's @RequiredArgsConstructor
-- **DTO pattern**: Never expose entities in controllers, use DTOs with ModelMapper
-- **Caching**: Spring Cache abstraction (@Cacheable) with 1-hour TTL
-- **Error handling**: @ControllerAdvice for global exception handling
-- **Validation**: Bean Validation (JSR-380) in DTOs
-- **Repository queries**: Mix of derived queries (findBySquadNumber) and custom JPQL (@Query)
-- **Date handling**: ISO-8601 strings with custom JPA converter for SQLite compatibility
-
-## Code Conventions
-
-### Naming
+## Quick Start
 
-- **Classes**: PascalCase (e.g., `PlayersController`, `PlayerDTO`)
-- **Methods/Variables**: camelCase (e.g., `findById`, `squadNumber`)
-- **Test methods**: `givenX_whenY_thenZ` (e.g., `givenSquadNumberExists_whenPost_thenReturnsConflict`)
-
-### Annotations
-
-- **Controllers**: @RestController (never @Controller for REST APIs)
-- **DTOs**: Lombok @Data, @Builder, @AllArgsConstructor
-- **Services**: @Service + @Transactional on mutating methods
-- **Repositories**: @Repository (extend JpaRepository)
-- **Entities**: @Entity with @Table, @Id, @GeneratedValue
+```bash
+# Development
+./mvnw spring-boot:run                      # Run with hot reload (port 9000)
+./mvnw clean test                           # Run tests
+./mvnw clean test jacoco:report             # Test with coverage
 
-### Lombok usage
+# Docker
+docker compose up                           # Start in container
+docker compose down -v                      # Reset database
 
-- Reduce boilerplate with @Data, @Builder, @AllArgsConstructor
-- Use @RequiredArgsConstructor for constructor injection
-- Never use field injection
+# Documentation
+http://localhost:9000/swagger/index.html    # API docs
+http://localhost:9001/actuator/health       # Health check
+```
 
-### REST conventions
+## Stack
 
-- Return ResponseEntity<T> from controllers
-- Use proper HTTP status codes (201 Created, 204 No Content, 409 Conflict)
-- OpenAPI annotations required on all endpoints
+- Java 25 (LTS, required)
+- Spring Boot 4.0.0 (Spring MVC)
+- Spring Data JPA + Hibernate
+- SQLite (file-based runtime, in-memory tests)
+- Maven 3 (use `./mvnw` wrapper)
+- Bean Validation (JSR-380)
+- Spring Cache (1-hour TTL)
+- JUnit 5 + AssertJ + MockMvc
+- JaCoCo (coverage)
+- SpringDoc OpenAPI 3 (Swagger)
+- Lombok (boilerplate reduction)
 
-### Logging
+## Project Patterns
 
-- Use SLF4J (injected via Lombok @Slf4j)
-- Never use System.out.println
+- **Architecture**: Layered (Controller → Service → Repository → JPA)
+- **Dependency Injection**: Constructor injection via Lombok `@RequiredArgsConstructor`
+- **Error Handling**: `@ControllerAdvice` for global exception handling
+- **Validation**: Bean Validation annotations in DTOs (`@NotNull`, `@Min`, etc.)
+- **Caching**: Spring `@Cacheable` on service layer (1-hour TTL)
+- **DTO Pattern**: ModelMapper for entity ↔ DTO transformations
+- **Repository**: Spring Data JPA with derived queries and custom JPQL
 
-### Configuration
+## Code Conventions
 
-- Externalize via @Value or application.yml
-- Never hardcode values in code
+- **Naming**: camelCase (methods/variables), PascalCase (classes), UPPER_SNAKE_CASE (constants)
+- **Files**: Class name matches file name (e.g., `PlayersController.java`)
+- **Package Structure**:
+  - `controllers/` - REST endpoints (`@RestController`)
+  - `services/` - Business logic (`@Service`)
+  - `repositories/` - Data access (`@Repository`, extends `JpaRepository`)
+  - `models/` - Domain entities (`@Entity`) and DTOs
+  - `converters/` - JPA attribute converters
+- **Annotations**:
+  - Controllers: `@RestController`, `@RequestMapping`, `@Operation` (OpenAPI)
+  - Services: `@Service`, `@Transactional`, `@Cacheable`
+  - Repositories: `@Repository` (Spring Data JPA)
+  - DTOs: `@NotNull`, `@Min`, `@Max` (Bean Validation)
+  - Entities: `@Entity`, `@Table`, `@Id`, `@GeneratedValue`
+- **Lombok**: `@Data`, `@Builder`, `@AllArgsConstructor`, `@RequiredArgsConstructor`
+- **Logging**: SLF4J (never `System.out.println`)
 
 ## Testing
 
-### Framework
-
-- **Unit tests**: JUnit 5 with AssertJ for fluent assertions
-- **Integration tests**: @SpringBootTest with MockMvc
-- **Coverage**: JaCoCo reports (must maintain high coverage)
-
-### Test naming
-
-**Pattern**: `givenX_whenY_thenZ()` (BDD Given-When-Then)
-
-**Naming philosophy:**
-
-Use **semantic naming** that describes the business/domain state and behavior, not technical implementation details:
-
-- **Given** (precondition): Describe the state of the system or data
-  - `givenPlayerExists` - A player is present in the system
-  - `givenNoExistingPlayer` - No player matching criteria
-  - `givenInvalidPlayer` - Invalid data provided
-  - `givenRaceCondition` - Concurrent modification scenario
-  - `givenNullId` - Missing required identifier
-- **When** (action): The method/operation being tested
-  - `whenCreate` - Creating a new entity
-  - `whenRetrieveById` - Fetching by identifier
-  - `whenUpdate` - Updating existing entity
-  - `whenDelete` - Removing an entity
-  - `whenSearchByLeague` - Searching/filtering operation
-- **Then** (outcome): Expected result or behavior
-  - `thenReturnsPlayerDTO` - Returns the DTO object
-  - `thenReturnsNull` - Returns null (not found/conflict)
-  - `thenReturnsTrue` / `thenReturnsFalse` - Boolean success indicator
-  - `thenReturns26Players` - Specific count of results
-  - `thenReturnsEmptyList` - No results found
-  - `thenReturnsOk` - HTTP 200 response
-  - `thenReturnsNotFound` - HTTP 404 response
-  - `thenReturnsCreated` - HTTP 201 response
-
-**Code conventions:**
-
-- Comments: Use **Given/When/Then** (BDD pattern)
-- Assertions: Use `then()` from AssertJ BDDAssertions
-- Variables:
-  - Use `actual` for operation results
-  - Use `expected` for comparison values when verifying equality
-  - Use `existing` for pre-saved entities in database
-
-**Why BDD Given-When-Then?**
-
-- ✅ **Readable**: Natural language flow, accessible to all stakeholders
-- ✅ **Behavior-focused**: Tests business logic, not implementation details
-- ✅ **Self-documenting**: Method name clearly states test scenario
-- ✅ **Framework-aligned**: Matches Cucumber/SpecFlow patterns
-
-```java
-// Examples across layers:
-givenNoExistingPlayer_whenCreate_thenReturnsPlayerDTO()     // Service: success case
-givenPlayerAlreadyExists_whenCreate_thenReturnsNull()       // Service: conflict case
-givenPlayerExists_whenFindById_thenReturnsPlayer()          // Repository: found
-givenPlayerDoesNotExist_whenFindById_thenReturnsEmpty()     // Repository: not found
-givenValidPlayer_whenPost_thenReturnsCreated()              // Controller: HTTP 201
-givenPlayerDoesNotExist_whenGetById_thenReturnsNotFound()   // Controller: HTTP 404
-```
-
-### Test structure
-
-Use BDD (Given/When/Then) consistently in JavaDoc comments, method names, and code sections:
-
-```java
-/**
- * Given no existing player with the same squad number
- * When create() is called with valid player data
- * Then the player is saved and a PlayerDTO is returned
- */
-@Test
-void givenNoExistingPlayer_whenCreate_thenReturnsPlayerDTO() {
-    // Given
-    Player player = PlayerFakes.createOneValid();
-    PlayerDTO expected = PlayerDTOFakes.createOneValid();
-    // When
-    PlayerDTO actual = playersService.create(expected);
-    // Then
-    then(actual).isEqualTo(expected);
-}
-```
-
-### Test requirements
-
-- Unit tests required for all service and repository methods
-- Integration tests required for all controller endpoints
-- Tests use in-memory SQLite (jdbc:sqlite::memory:)
-- All tests must pass before PR (`./mvnw clean install`)
-- **Assertion quality**: Verify actual behavior, not just counts (e.g., verify league content, not just `hasSize()`)
+- **Structure**: `*Tests.java` in `src/test/java/` (mirrors main package structure)
+- **Naming Pattern**: `method_scenario_outcome`
+  - `method`: Method under test (e.g., `post`, `findById`, `create`)
+  - `scenario`: Context (e.g., `playerExists`, `invalidData`, `noMatches`)
+  - `outcome`: Expected result (e.g., `returnsPlayer`, `returnsConflict`, `returnsEmpty`)
+- **Examples**:
+
+  ```java
+  // Controller
+  void post_squadNumberExists_returnsConflict()
+
+  // Service
+  void create_noConflict_returnsPlayerDTO()
+
+  // Repository
+  void findById_playerExists_returnsPlayer()
+  ```
+
+- **JavaDoc**: BDD Given/When/Then structure in test comments
+
+  ```java
+  /**
+   * Given a player with squad number 5 already exists in the database
+   * When POST /players is called with a new player using squad number 5
+   * Then response status is 409 Conflict
+   */
+  @Test
+  void post_squadNumberExists_returnsConflict() { ... }
+  ```
+
+- **Annotations**: `@SpringBootTest`, `@AutoConfigureMockMvc`, `@Test`
+- **Assertions**: AssertJ (fluent, e.g., `assertThat(result).isNotNull()`)
+- **Mocking**: Mockito for service layer tests
+- **Database**: Tests use in-memory SQLite (auto-cleared after each test)
+- **Coverage**: Target high coverage (JaCoCo reports in `target/site/jacoco/`)
 
 ## Avoid
 
-- **Field injection** - Always use constructor injection
-- **Using `new` for Spring beans** - Breaks dependency injection
-- **Missing @Transactional** - Required on service methods that modify data
-- **Exposing entities in controllers** - Always use DTOs
-- **System.out.println** - Use SLF4J logging
-- **Hardcoded config** - Use @Value or application.yml
-- **System Maven** - Always use `./mvnw` wrapper for consistency
-- **SQLite in production** - This is a demo/development-only setup
-
-## Folder Structure
-
-```tree
-src/main/java/                    # Application code
-  ├── Application.java            # @SpringBootApplication entry point
-  ├── controllers/                # REST endpoints
-  ├── services/                   # Business logic + caching
-  ├── repositories/               # Data access (Spring Data JPA)
-  ├── models/                     # Entities (Player) and DTOs (PlayerDTO)
-  └── converters/                 # JPA converters (ISO date handling)
-src/test/java/                    # Test classes (mirrors main structure)
-storage/                          # SQLite database file (runtime)
-scripts/                          # Docker entrypoint and healthcheck
-```
-
-## Quick Reference
+- Field injection (use constructor injection)
+- Using `new` for Spring beans (breaks DI)
+- Missing `@Transactional` on service methods that modify data
+- Exposing entities directly in controllers (use DTOs)
+- `System.out.println` (use SLF4J logging)
+- Hardcoded configuration (use `@Value` or `application.properties`)
+- Ignoring exceptions (always handle or propagate)
+- Testing implementation details (test behavior, not internals)
 
-```bash
-# Development
-./mvnw spring-boot:run              # Run with hot reload
-./mvnw clean test jacoco:report     # Test with coverage
+## Commit Messages
 
-# Docker
-docker compose up                   # Start in container
+Follow Conventional Commits format (enforced by commitlint in CI):
 
-# Documentation
-http://localhost:8080/swagger-ui.html       # API docs
-http://localhost:8080/actuator/health       # Health check
-```
+**Format**: `type(scope): description (#issue)` (max 80 chars)
 
-## Commit Messages
+**Types**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`, `perf`, `style`, `build`
 
-Follow Conventional Commits with issue number suffix:
+**Examples**:
 
-- **Format**: `type(scope): description (#issue)` (max 80 chars)
-- **Types**: feat, fix, chore, docs, test, refactor
-- **Example**: `feat(api): add squad number search endpoint (#123)`
+- `feat(api): add player stats endpoint (#42)`
+- `fix(service): resolve cache invalidation bug (#88)`
+- `test: adopt BDD Given-When-Then pattern across all tests (#266)`
 
-## Additional Context
+---
 
-For detailed operational procedures, workflows, and troubleshooting, see `AGENTS.md`.
+For detailed workflows, troubleshooting, and CI/CD setup, load `#file:AGENTS.md`.