fix(clients): add idempotent replay logic and handle malformed UUID

P1: When idempotencyKey is provided, look up existing Request first.
Same key+payload returns existing request (idempotent replay).
Same key+different payload throws IdempotencyKeyConflictException (409).

P2: Added HttpMessageNotReadableException handler in GlobalExceptionHandler
to return 400 instead of 500 for malformed UUID in request body.

Added i18n messages for both error cases in all three bundles.

Author: igorsatsyuk

src/main/java/lt/satsyuk/exception/GlobalExceptionHandler.java

@@ -8,6 +8,7 @@
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
 import org.springframework.security.access.AccessDeniedException;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
@@ -107,6 +108,24 @@ public ResponseEntity<AppResponse<Void>> handlePhoneExists(PhoneAlreadyExistsExc
                 .body(AppResponse.<Void>error(AppResponse.ErrorCode.CONFLICT.getCode(), message));
     }
 
+    @ExceptionHandler(IdempotencyKeyConflictException.class)
+    public ResponseEntity<AppResponse<Void>> handleIdempotencyKeyConflict(IdempotencyKeyConflictException ex) {
+        String message = messageService.getMessage(ex.getMessageCode(), new Object[]{ex.getIdempotencyKey()});
+        return ResponseEntity
+                .status(HttpStatus.CONFLICT)
+                .contentType(MediaType.APPLICATION_JSON)
+                .body(AppResponse.<Void>error(AppResponse.ErrorCode.CONFLICT.getCode(), message));
+    }
+
+    @ExceptionHandler(HttpMessageNotReadableException.class)
+    public ResponseEntity<AppResponse<Void>> handleHttpMessageNotReadable(HttpMessageNotReadableException ex) {
+        String message = messageService.getMessage("error.request.invalidPayload");
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .contentType(MediaType.APPLICATION_JSON)
+                .body(AppResponse.<Void>error(AppResponse.ErrorCode.BAD_REQUEST.getCode(), message));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<AppResponse<Void>> handleGeneric(Exception ex) {
         log.error("Unhandled exception caught by GlobalExceptionHandler", ex);

src/main/java/lt/satsyuk/exception/IdempotencyKeyConflictException.java

@@ -0,0 +1,17 @@
+package lt.satsyuk.exception;
+
+import lombok.Getter;
+
+@Getter
+public class IdempotencyKeyConflictException extends RuntimeException {
+    private final String idempotencyKey;
+
+    public IdempotencyKeyConflictException(String idempotencyKey) {
+        super("Request with idempotency key=" + idempotencyKey + " already exists with different payload");
+        this.idempotencyKey = idempotencyKey;
+    }
+
+    public String getMessageCode() {
+        return "error.request.idempotencyKeyConflict";
+    }
+}

src/main/java/lt/satsyuk/service/RequestService.java

@@ -6,6 +6,7 @@
 import lt.satsyuk.dto.CreateClientRequest;
 import lt.satsyuk.dto.RequestAcceptedResponse;
 import lt.satsyuk.dto.RequestStatusResponse;
+import lt.satsyuk.exception.IdempotencyKeyConflictException;
 import lt.satsyuk.exception.RequestNotFoundException;
 import lt.satsyuk.model.Request;
 import lt.satsyuk.model.RequestStatus;
@@ -18,6 +19,7 @@
 
 import java.time.OffsetDateTime;
 import java.time.ZoneOffset;
+import java.util.Optional;
 import java.util.UUID;
 
 @Service
@@ -32,6 +34,18 @@ public class RequestService {
 
     public RequestAcceptedResponse submitClientCreateRequest(CreateClientRequest createClientRequest) {
         OffsetDateTime now = now();
+
+        if (createClientRequest.idempotencyKey() != null) {
+            Optional<Request> existing = requestRepository.findById(createClientRequest.idempotencyKey());
+            if (existing.isPresent()) {
+                Request request = existing.get();
+                if (request.getRequestData().equals(writeJson(createClientRequest))) {
+                    return new RequestAcceptedResponse(request.getId(), request.getStatus());
+                }
+                throw new IdempotencyKeyConflictException(createClientRequest.idempotencyKey().toString());
+            }
+        }
+
         UUID requestId = createClientRequest.idempotencyKey() != null
                 ? createClientRequest.idempotencyKey()
                 : UUID.randomUUID();

src/main/resources/messages.properties

@@ -20,6 +20,8 @@ error.account.notFound=Account for client id\u003D{0} not found
 error.account.optimisticLock=Too many optimistic lock retries for client id\u003D{0}
 error.request.notFound=Request with id\u003D{0} not found
 error.request.schedulingFailed=Failed to schedule request processing
+error.request.idempotencyKeyConflict=Request with idempotency key\u003D{0} already exists with different payload
+error.request.invalidPayload=Invalid request payload
 error.validation.failed=Validation failed
 error.typeMismatch=Invalid value\: {0}
 

src/main/resources/messages_en.properties

@@ -20,6 +20,8 @@ error.account.notFound=Account for client id\u003D{0} not found
 error.account.optimisticLock=Too many optimistic lock retries for client id\u003D{0}
 error.request.notFound=Request with id\u003D{0} not found
 error.request.schedulingFailed=Failed to schedule request processing
+error.request.idempotencyKeyConflict=Request with idempotency key\u003D{0} already exists with different payload
+error.request.invalidPayload=Invalid request payload
 error.validation.failed=Validation failed
 error.typeMismatch=Invalid value: {0}
 

src/main/resources/messages_ru.properties

@@ -20,6 +20,8 @@ error.account.notFound=Счет для клиента с id={0} не найде
 error.account.optimisticLock=Превышено количество повторных попыток optimistic lock для клиента с id={0}
 error.request.notFound=Заявка с id={0} не найдена
 error.request.schedulingFailed=Не удалось запланировать обработку заявки
+error.request.idempotencyKeyConflict=Заявка с idempotency key={0} уже существует с другим телом запроса
+error.request.invalidPayload=Некорректное тело запроса
 error.validation.failed=Ошибка валидации
 error.typeMismatch=Неверное значение: {0}
 

src/test/java/lt/satsyuk/service/RequestServiceTest.java

@@ -6,6 +6,7 @@
 import lt.satsyuk.dto.RequestAcceptedResponse;
 import lt.satsyuk.dto.RequestStatusResponse;
 import lt.satsyuk.api.util.TestTime;
+import lt.satsyuk.exception.IdempotencyKeyConflictException;
 import lt.satsyuk.model.Request;
 import lt.satsyuk.model.RequestStatus;
 import lt.satsyuk.model.RequestType;
@@ -27,6 +28,7 @@
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
@@ -95,6 +97,50 @@ void submitClientCreateRequestUsesIdempotencyKeyAsRequestId() throws Exception {
         assertThat(response.requestId()).isEqualTo(idempotencyKey);
     }
 
+    @Test
+    void submitClientCreateRequestReturnsExistingRequestForSameIdempotencyKeyAndPayload() throws Exception {
+        UUID idempotencyKey = UUID.randomUUID();
+        CreateClientRequest createClientRequest = new CreateClientRequest(idempotencyKey, "John", "Doe", "+37061234567");
+        OffsetDateTime now = OffsetDateTime.now();
+        Request existingRequest = Request.builder()
+                .id(idempotencyKey)
+                .type(RequestType.CLIENT_CREATE)
+                .status(RequestStatus.COMPLETED)
+                .createdAt(now)
+                .statusChangedAt(now)
+                .requestData(objectMapper.writeValueAsString(createClientRequest))
+                .build();
+        when(requestRepository.findById(idempotencyKey)).thenReturn(Optional.of(existingRequest));
+
+        RequestAcceptedResponse response = requestService.submitClientCreateRequest(createClientRequest);
+
+        assertThat(response.requestId()).isEqualTo(idempotencyKey);
+        assertThat(response.status()).isEqualTo(RequestStatus.COMPLETED);
+        verify(requestRepository, never()).save(any(Request.class));
+        verify(requestSchedulerService, never()).scheduleClientCreateRequest(any(UUID.class));
+    }
+
+    @Test
+    void submitClientCreateRequestThrowsConflictForSameIdempotencyKeyDifferentPayload() throws Exception {
+        UUID idempotencyKey = UUID.randomUUID();
+        CreateClientRequest incoming = new CreateClientRequest(idempotencyKey, "John", "Doe", "+37061234567");
+        CreateClientRequest existingPayload = new CreateClientRequest(idempotencyKey, "Jane", "Roe", "+37069999999");
+        OffsetDateTime now = OffsetDateTime.now();
+        Request existingRequest = Request.builder()
+                .id(idempotencyKey)
+                .type(RequestType.CLIENT_CREATE)
+                .status(RequestStatus.COMPLETED)
+                .createdAt(now)
+                .statusChangedAt(now)
+                .requestData(objectMapper.writeValueAsString(existingPayload))
+                .build();
+        when(requestRepository.findById(idempotencyKey)).thenReturn(Optional.of(existingRequest));
+
+        assertThatThrownBy(() -> requestService.submitClientCreateRequest(incoming))
+                .isInstanceOf(IdempotencyKeyConflictException.class)
+                .hasMessageContaining(idempotencyKey.toString());
+    }
+
     @Test
     void getRequestStatusReturnsNestedJsonResponse() {
         UUID requestId = UUID.randomUUID();