feat(match-assignment): add atomic batch referee assignment by round

src/main/java/cat/udl/eps/softarch/fll/controller/MatchAssignmentController.java

@@ -6,6 +6,8 @@
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import cat.udl.eps.softarch.fll.controller.dto.BatchMatchAssignmentRequest;
+import cat.udl.eps.softarch.fll.controller.dto.BatchMatchAssignmentResponse;
 import cat.udl.eps.softarch.fll.controller.dto.MatchAssignmentRequest;
 import cat.udl.eps.softarch.fll.controller.dto.MatchAssignmentResponse;
 import cat.udl.eps.softarch.fll.domain.Match;
@@ -30,4 +32,11 @@ public ResponseEntity<MatchAssignmentResponse> assignReferee(@Valid @RequestBody
 				"ASSIGNED");
 		return ResponseEntity.status(HttpStatus.OK).body(response);
 	}
+
+	@PostMapping("/batch")
+	public ResponseEntity<BatchMatchAssignmentResponse> assignRefereesBatch(
+			@Valid @RequestBody BatchMatchAssignmentRequest request) {
+		BatchMatchAssignmentResponse response = matchAssignmentService.assignBatch(request.roundId(), request.assignments());
+		return ResponseEntity.status(HttpStatus.OK).body(response);
+	}
 }

src/main/java/cat/udl/eps/softarch/fll/controller/dto/BatchMatchAssignmentItemRequest.java

@@ -0,0 +1,8 @@
+package cat.udl.eps.softarch.fll.controller.dto;
+
+import jakarta.validation.constraints.NotBlank;
+
+public record BatchMatchAssignmentItemRequest(
+		@NotBlank String matchId,
+		@NotBlank String refereeId
+) {}

src/main/java/cat/udl/eps/softarch/fll/controller/dto/BatchMatchAssignmentItemResponse.java

@@ -0,0 +1,7 @@
+package cat.udl.eps.softarch.fll.controller.dto;
+
+public record BatchMatchAssignmentItemResponse(
+		String matchId,
+		String refereeId,
+		String status
+) {}

src/main/java/cat/udl/eps/softarch/fll/controller/dto/BatchMatchAssignmentRequest.java

@@ -0,0 +1,12 @@
+package cat.udl.eps.softarch.fll.controller.dto;
+
+import java.util.List;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+
+public record BatchMatchAssignmentRequest(
+		@NotBlank String roundId,
+		@NotEmpty List<@NotNull @Valid BatchMatchAssignmentItemRequest> assignments
+) {}

src/main/java/cat/udl/eps/softarch/fll/controller/dto/BatchMatchAssignmentResponse.java

@@ -0,0 +1,16 @@
+package cat.udl.eps.softarch.fll.controller.dto;
+
+import java.util.List;
+
+public record BatchMatchAssignmentResponse(
+		String roundId,
+		String status,
+		int processed,
+		List<BatchMatchAssignmentItemResponse> assignments
+) {
+	public BatchMatchAssignmentResponse {
+		if (assignments == null || processed != assignments.size()) {
+			throw new IllegalArgumentException("processed must match assignments size");
+		}
+	}
+}

src/main/java/cat/udl/eps/softarch/fll/exception/MatchAssignmentErrorCode.java

@@ -1,8 +1,10 @@
 package cat.udl.eps.softarch.fll.exception;
 
 public enum MatchAssignmentErrorCode {
+	ROUND_NOT_FOUND,
 	MATCH_NOT_FOUND,
 	REFEREE_NOT_FOUND,
+	DUPLICATE_MATCH_IN_BATCH,
 	INVALID_ROLE,
 	AVAILABILITY_CONFLICT,
 	MATCH_ALREADY_HAS_REFEREE,

src/main/java/cat/udl/eps/softarch/fll/exception/MatchAssignmentException.java

@@ -2,13 +2,48 @@
 
 public class MatchAssignmentException extends RuntimeException {
 	private final MatchAssignmentErrorCode errorCode;
+	private final Integer index;
+	private final String matchId;
+	private final String refereeId;
 
 	public MatchAssignmentException(MatchAssignmentErrorCode errorCode, String message) {
+		this(errorCode, message, null, null, null);
+	}
+
+	public MatchAssignmentException(
+			MatchAssignmentErrorCode errorCode,
+			String message,
+			Integer index,
+			String matchId,
+			String refereeId) {
 		super(message);
 		this.errorCode = errorCode;
+		this.index = index;
+		this.matchId = index != null ? defaultBatchValue(matchId) : null;
+		this.refereeId = index != null ? defaultBatchValue(refereeId) : null;
 	}
 
 	public MatchAssignmentErrorCode getErrorCode() {
 		return errorCode;
 	}
+
+	public Integer getIndex() {
+		return index;
+	}
+
+	public String getMatchId() {
+		return matchId;
+	}
+
+	public String getRefereeId() {
+		return refereeId;
+	}
+
+	public boolean hasBatchDetails() {
+		return index != null && matchId != null && refereeId != null;
+	}
+
+	private String defaultBatchValue(String value) {
+		return value != null ? value : "UNKNOWN";
+	}
 }

src/main/java/cat/udl/eps/softarch/fll/exception/MatchAssignmentExceptionHandler.java

@@ -1,23 +1,43 @@
 package cat.udl.eps.softarch.fll.exception;
 
+import java.time.Instant;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
+import jakarta.servlet.http.HttpServletRequest;
 
 @RestControllerAdvice
 public class MatchAssignmentExceptionHandler {
 
 	@ExceptionHandler(MatchAssignmentException.class)
-	public ResponseEntity<ErrorResponse> handleMatchAssignmentException(MatchAssignmentException ex) {
+	public ResponseEntity<ErrorResponse> handleMatchAssignmentException(
+			MatchAssignmentException ex,
+			HttpServletRequest request) {
 		HttpStatus status = switch (ex.getErrorCode()) {
-			case MATCH_NOT_FOUND, REFEREE_NOT_FOUND -> HttpStatus.NOT_FOUND;
-			case AVAILABILITY_CONFLICT, MATCH_ALREADY_HAS_REFEREE -> HttpStatus.CONFLICT;
+			case ROUND_NOT_FOUND, MATCH_NOT_FOUND, REFEREE_NOT_FOUND -> HttpStatus.NOT_FOUND;
+			case AVAILABILITY_CONFLICT, MATCH_ALREADY_HAS_REFEREE, DUPLICATE_MATCH_IN_BATCH -> HttpStatus.CONFLICT;
 			case INVALID_ROLE, INVALID_MATCH_STATE, INVALID_ID_FORMAT -> HttpStatus.UNPROCESSABLE_CONTENT;
 		};
-		ErrorResponse body = new ErrorResponse(ex.getErrorCode().name(), ex.getMessage());
+
+		BatchErrorDetails details = ex.hasBatchDetails()
+				? new BatchErrorDetails(ex.getIndex(), ex.getMatchId(), ex.getRefereeId(), ex.getErrorCode().name())
+				: null;
+		ErrorResponse body = new ErrorResponse(
+				ex.hasBatchDetails() ? "BATCH_ASSIGNMENT_FAILED" : ex.getErrorCode().name(),
+				ex.hasBatchDetails() ? "Assignment failed at index " + ex.getIndex() : ex.getMessage(),
+				Instant.now().toString(),
+				request.getRequestURI(),
+				details);
 		return ResponseEntity.status(status).body(body);
 	}
 
-	public record ErrorResponse(String error, String message) {}
+	public record ErrorResponse(
+			String error,
+			String message,
+			String timestamp,
+			String path,
+			BatchErrorDetails details) {}
+
+	public record BatchErrorDetails(Integer index, String matchId, String refereeId, String cause) {}
 }