feat(s1): application controllers — REST endpoints + CommandHandler (STA-114)

payment-orchestrator/payment-orchestrator/build.gradle.kts

@@ -127,6 +127,8 @@ dependencies {
 
     // Test
     testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
+    testImplementation("org.springframework.boot:spring-boot-starter-security-test")
     testImplementation("org.springframework.kafka:spring-kafka-test")
     testImplementation("com.tngtech.archunit:archunit-junit5:$archunitVersion")
     testImplementation("org.wiremock:wiremock-standalone:$wiremockVersion")

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/application/controller/CancelPaymentRequest.java

@@ -0,0 +1,11 @@
+package com.stablecoin.payments.orchestrator.application.controller;
+
+import jakarta.validation.constraints.NotBlank;
+
+/**
+ * Request DTO for cancelling a payment.
+ */
+public record CancelPaymentRequest(
+        @NotBlank(message = "reason is required")
+        String reason
+) {}

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/application/controller/GlobalExceptionHandler.java

@@ -1,22 +1,32 @@
 package com.stablecoin.payments.orchestrator.application.controller;
 
 import com.stablecoin.payments.orchestrator.api.ApiError;
+import com.stablecoin.payments.orchestrator.domain.model.PaymentNotCancellableException;
+import com.stablecoin.payments.orchestrator.domain.model.PaymentNotFoundException;
 import jakarta.validation.ConstraintViolationException;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
 import org.springframework.validation.FieldError;
 import org.springframework.validation.ObjectError;
+import org.springframework.validation.method.ParameterValidationResult;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.ResponseStatus;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.HandlerMethodValidationException;
 
+import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 
 import static com.stablecoin.payments.orchestrator.application.controller.ErrorCodes.INTERNAL_ERROR;
+import static com.stablecoin.payments.orchestrator.application.controller.ErrorCodes.PAYMENT_NOT_CANCELLABLE;
+import static com.stablecoin.payments.orchestrator.application.controller.ErrorCodes.PAYMENT_NOT_FOUND;
 import static com.stablecoin.payments.orchestrator.application.controller.ErrorCodes.VALIDATION_ERROR;
 import static org.springframework.http.HttpStatus.BAD_REQUEST;
+import static org.springframework.http.HttpStatus.CONFLICT;
 import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR;
+import static org.springframework.http.HttpStatus.NOT_FOUND;
 import static org.springframework.http.HttpStatus.UNPROCESSABLE_ENTITY;
 
 @Slf4j
@@ -35,6 +45,31 @@ public ApiError handleValidation(MethodArgumentNotValidException ex) {
                 "Invalid request content", errors);
     }
 
+    @ResponseStatus(BAD_REQUEST)
+    @ExceptionHandler(HandlerMethodValidationException.class)
+    public ApiError handleMethodValidation(HandlerMethodValidationException ex) {
+        Map<String, List<String>> errors = ex.getParameterValidationResults().stream()
+                .flatMap(result -> result.getResolvableErrors().stream()
+                        .map(error -> Map.entry(
+                                resolveParameterName(result, error),
+                                error.getDefaultMessage())))
+                .collect(Collectors.groupingBy(
+                        Map.Entry::getKey,
+                        Collectors.mapping(Map.Entry::getValue, Collectors.toList())));
+        log.info("Method validation failed: {}", errors);
+        return ApiError.withErrors(VALIDATION_ERROR, BAD_REQUEST.getReasonPhrase(),
+                "Invalid request content", errors);
+    }
+
+    private static String resolveParameterName(ParameterValidationResult result,
+                                                org.springframework.context.MessageSourceResolvable error) {
+        if (error instanceof FieldError fieldError) {
+            return fieldError.getField();
+        }
+        var paramName = result.getMethodParameter().getParameterName();
+        return paramName != null ? paramName : "unknown";
+    }
+
     @ResponseStatus(BAD_REQUEST)
     @ExceptionHandler(ConstraintViolationException.class)
     public ApiError handleConstraintViolation(ConstraintViolationException ex) {
@@ -54,6 +89,20 @@ public ApiError handleIllegalArgument(IllegalArgumentException ex) {
         return ApiError.of(VALIDATION_ERROR, BAD_REQUEST.getReasonPhrase(), ex.getMessage());
     }
 
+    @ResponseStatus(NOT_FOUND)
+    @ExceptionHandler(PaymentNotFoundException.class)
+    public ApiError handlePaymentNotFound(PaymentNotFoundException ex) {
+        log.info("Payment not found: {}", ex.getMessage());
+        return ApiError.of(PAYMENT_NOT_FOUND, NOT_FOUND.getReasonPhrase(), ex.getMessage());
+    }
+
+    @ResponseStatus(CONFLICT)
+    @ExceptionHandler(PaymentNotCancellableException.class)
+    public ApiError handlePaymentNotCancellable(PaymentNotCancellableException ex) {
+        log.info("Payment not cancellable: {}", ex.getMessage());
+        return ApiError.of(PAYMENT_NOT_CANCELLABLE, CONFLICT.getReasonPhrase(), ex.getMessage());
+    }
+
     @ResponseStatus(UNPROCESSABLE_ENTITY)
     @ExceptionHandler(IllegalStateException.class)
     public ApiError handleInvalidState(IllegalStateException ex) {

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/application/controller/InitiatePaymentRequest.java

@@ -0,0 +1,35 @@
+package com.stablecoin.payments.orchestrator.application.controller;
+
+import jakarta.validation.constraints.DecimalMin;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+
+import java.math.BigDecimal;
+import java.util.UUID;
+
+/**
+ * Request DTO for initiating a cross-border payment.
+ */
+public record InitiatePaymentRequest(
+        @NotNull(message = "senderId is required")
+        UUID senderId,
+
+        @NotNull(message = "recipientId is required")
+        UUID recipientId,
+
+        @NotNull(message = "sourceAmount is required")
+        @DecimalMin(value = "0.01", message = "sourceAmount must be positive")
+        BigDecimal sourceAmount,
+
+        @NotBlank(message = "sourceCurrency is required")
+        String sourceCurrency,
+
+        @NotBlank(message = "targetCurrency is required")
+        String targetCurrency,
+
+        @NotBlank(message = "sourceCountry is required")
+        String sourceCountry,
+
+        @NotBlank(message = "targetCountry is required")
+        String targetCountry
+) {}

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/application/controller/PaymentController.java

@@ -0,0 +1,84 @@
+package com.stablecoin.payments.orchestrator.application.controller;
+
+import com.stablecoin.payments.orchestrator.domain.service.PaymentCommandHandler;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.UUID;
+
+/**
+ * REST controller for payment lifecycle management.
+ * <p>
+ * Thin HTTP handler that delegates all business logic to {@link PaymentCommandHandler}.
+ */
+@Slf4j
+@RestController
+@RequestMapping("/v1/payments")
+@RequiredArgsConstructor
+public class PaymentController {
+
+    private final PaymentCommandHandler commandHandler;
+
+    /**
+     * Initiates a new cross-border payment.
+     * <p>
+     * Idempotent: returns 200 with existing payment if the same Idempotency-Key is reused.
+     * Returns 201 on first creation.
+     */
+    @PostMapping
+    public ResponseEntity<PaymentResponse> initiatePayment(
+            @NotBlank(message = "Idempotency-Key header is required")
+            @RequestHeader("Idempotency-Key") String idempotencyKey,
+            @Valid @RequestBody InitiatePaymentRequest request) {
+        log.info("POST /v1/payments idempotencyKey={}, senderId={}", idempotencyKey, request.senderId());
+
+        var result = commandHandler.initiatePayment(
+                idempotencyKey,
+                UUID.randomUUID(),
+                request.senderId(),
+                request.recipientId(),
+                request.sourceAmount(),
+                request.sourceCurrency(),
+                request.targetCurrency(),
+                request.sourceCountry(),
+                request.targetCountry()
+        );
+
+        var response = PaymentResponse.from(result.payment());
+        var status = result.replay() ? HttpStatus.OK : HttpStatus.CREATED;
+
+        return ResponseEntity.status(status).body(response);
+    }
+
+    /**
+     * Retrieves a payment by its ID.
+     */
+    @GetMapping("/{paymentId}")
+    public PaymentResponse getPayment(@PathVariable UUID paymentId) {
+        log.info("GET /v1/payments/{}", paymentId);
+        return PaymentResponse.from(commandHandler.getPayment(paymentId));
+    }
+
+    /**
+     * Cancels a payment by sending a cancel signal to the workflow.
+     * Returns 200 if accepted, 409 if the payment is in a terminal state.
+     */
+    @PostMapping("/{paymentId}/cancel")
+    public PaymentResponse cancelPayment(
+            @PathVariable UUID paymentId,
+            @Valid @RequestBody CancelPaymentRequest request) {
+        log.info("POST /v1/payments/{}/cancel reason={}", paymentId, request.reason());
+        return PaymentResponse.from(commandHandler.cancelPayment(paymentId, request.reason()));
+    }
+}

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/application/controller/PaymentResponse.java

@@ -0,0 +1,54 @@
+package com.stablecoin.payments.orchestrator.application.controller;
+
+import com.stablecoin.payments.orchestrator.domain.model.Payment;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Response DTO representing a payment in the API layer.
+ */
+public record PaymentResponse(
+        UUID paymentId,
+        String idempotencyKey,
+        UUID correlationId,
+        String state,
+        UUID senderId,
+        UUID recipientId,
+        BigDecimal sourceAmount,
+        String sourceCurrency,
+        String targetCurrency,
+        BigDecimal targetAmount,
+        String sourceCountry,
+        String targetCountry,
+        String failureReason,
+        Instant createdAt,
+        Instant updatedAt,
+        Instant expiresAt
+) {
+
+    /**
+     * Maps a domain {@link Payment} aggregate to the API response DTO.
+     */
+    public static PaymentResponse from(Payment payment) {
+        return new PaymentResponse(
+                payment.paymentId(),
+                payment.idempotencyKey(),
+                payment.correlationId(),
+                payment.state().name(),
+                payment.senderId(),
+                payment.recipientId(),
+                payment.sourceAmount().amount(),
+                payment.sourceCurrency(),
+                payment.targetCurrency(),
+                payment.targetAmount() != null ? payment.targetAmount().amount() : null,
+                payment.corridor().sourceCountry(),
+                payment.corridor().targetCountry(),
+                payment.failureReason(),
+                payment.createdAt(),
+                payment.updatedAt(),
+                payment.expiresAt()
+        );
+    }
+}

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/domain/model/PaymentNotCancellableException.java

@@ -0,0 +1,14 @@
+package com.stablecoin.payments.orchestrator.domain.model;
+
+import java.util.UUID;
+
+/**
+ * Thrown when attempting to cancel a payment that is in a terminal state
+ * and cannot be cancelled.
+ */
+public class PaymentNotCancellableException extends RuntimeException {
+
+    public PaymentNotCancellableException(UUID paymentId, PaymentState state) {
+        super("Payment %s cannot be cancelled in state %s".formatted(paymentId, state));
+    }
+}

payment-orchestrator/payment-orchestrator/src/main/java/com/stablecoin/payments/orchestrator/domain/model/PaymentNotFoundException.java

@@ -0,0 +1,13 @@
+package com.stablecoin.payments.orchestrator.domain.model;
+
+import java.util.UUID;
+
+/**
+ * Thrown when a payment cannot be found by its ID.
+ */
+public class PaymentNotFoundException extends RuntimeException {
+
+    public PaymentNotFoundException(UUID paymentId) {
+        super("Payment not found: " + paymentId);
+    }
+}