[🚀 방탈출 예약 외부 API 연동 3단계] 캐리 미션 제출합니다.

src/main/java/roomescape/controller/dto/response/BookingPaymentResponse.java

@@ -0,0 +1,28 @@
+package roomescape.controller.dto.response;
+
+import roomescape.domain.PaymentStatus;
+import roomescape.service.dto.BookingPaymentInfo;
+
+public record BookingPaymentResponse(
+        String orderId,
+        Long amount,
+        String paymentKey,
+        PaymentStatus status,
+        String failureCode,
+        String failureMessage
+) {
+
+    public static BookingPaymentResponse from(BookingPaymentInfo payment) {
+        if (payment == null) {
+            return null;
+        }
+        return new BookingPaymentResponse(
+                payment.orderId(),
+                payment.amount(),
+                payment.paymentKey(),
+                payment.status(),
+                payment.failureCode(),
+                payment.failureMessage()
+        );
+    }
+}

src/main/java/roomescape/controller/dto/response/BookingStatusResponse.java

@@ -13,7 +13,8 @@ public record BookingStatusResponse(
         ReservationThemeResponse theme,
         BookingType bookingType,
         ReservationStatus reservationStatus,
-        Long turn
+        Long turn,
+        BookingPaymentResponse payment
 ) {
 
     public static BookingStatusResponse from(BookingStatus bookingStatus) {
@@ -25,7 +26,8 @@ public static BookingStatusResponse from(BookingStatus bookingStatus) {
                 ReservationThemeResponse.from(bookingStatus.theme()),
                 bookingStatus.bookingType(),
                 bookingStatus.reservationStatus(),
-                bookingStatus.turn()
+                bookingStatus.turn(),
+                BookingPaymentResponse.from(bookingStatus.payment())
         );
     }
 }

src/main/java/roomescape/controller/view/PaymentSuccessController.java

@@ -3,8 +3,10 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.ui.Model;
 import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import roomescape.controller.view.dto.PaymentFailRequest;
 import roomescape.controller.view.dto.PaymentReservationView;
+import roomescape.controller.view.dto.PaymentSuccessRequest;
 import roomescape.domain.Reservation;
 import roomescape.service.payment.PaymentAmountMismatchException;
 import roomescape.service.payment.PaymentGatewayException;
@@ -14,6 +16,8 @@
 @Controller
 public class PaymentSuccessController {
 
+    private static final String PAYMENT_CONFIRMATION_UNKNOWN = "PAYMENT_CONFIRMATION_UNKNOWN";
+
     private final PaymentService paymentService;
 
     public PaymentSuccessController(PaymentService paymentService) {
@@ -22,44 +26,37 @@ public PaymentSuccessController(PaymentService paymentService) {
 
     @GetMapping("/payments/success")
     public String success(
-            @RequestParam String paymentKey,
-            @RequestParam String orderId,
-            @RequestParam Long amount,
-            @RequestParam(required = false) String name,
+            @ModelAttribute PaymentSuccessRequest request,
             Model model
     ) {
         try {
-            PaymentResult result = paymentService.confirm(paymentKey, orderId, amount);
+            PaymentResult result = paymentService.confirm(request.paymentKey(), request.orderId(), request.amount());
             model.addAttribute("result", result);
-            addReservationViewByOrderId(model, orderId);
-            model.addAttribute("name", name);
+            addReservationViewByOrderId(model, request.orderId());
+            model.addAttribute("name", request.name());
             return "payment-success";
         } catch (PaymentAmountMismatchException e) {
-            return failView(model, "AMOUNT_MISMATCH", e.getMessage(), orderId, name,
-                    paymentService.findReservationByOrderId(orderId));
+            return failView(model, "AMOUNT_MISMATCH", e.getMessage(), request.orderId(), request.name(),
+                    paymentService.findReservationByOrderId(request.orderId()));
         } catch (PaymentGatewayException e) {
-            return failView(model, e.getCode(), e.getMessage(), orderId, name,
-                    paymentService.findReservationByOrderId(orderId));
+            return failView(model, e.getCode(), e.getMessage(), request.orderId(), request.name(),
+                    paymentService.findReservationByOrderId(request.orderId()));
         }
     }
 
     @GetMapping("/payments/fail")
     public String fail(
-            @RequestParam(required = false) String code,
-            @RequestParam(required = false) String message,
-            @RequestParam(required = false) String orderId,
-            @RequestParam(required = false) Long paymentId,
-            @RequestParam(required = false) String name,
+            @ModelAttribute PaymentFailRequest request,
             Model model
     ) {
         Reservation reservation = null;
-        if (paymentId != null) {
-            paymentService.fail(paymentId, code, message);
-            reservation = paymentService.findReservationByPaymentId(paymentId);
-        } else if (orderId != null) {
-            reservation = paymentService.findReservationByOrderId(orderId);
+        if (request.paymentId() != null) {
+            paymentService.fail(request.paymentId(), request.code(), request.message());
+            reservation = paymentService.findReservationByPaymentId(request.paymentId());
+        } else if (request.orderId() != null) {
+            reservation = paymentService.findReservationByOrderId(request.orderId());
         }
-        return failView(model, code, message, orderId, name, reservation);
+        return failView(model, request.code(), request.message(), request.orderId(), request.name(), reservation);
     }
 
     private void addReservationViewByOrderId(Model model, String orderId) {
@@ -73,6 +70,7 @@ private String failView(Model model, String code, String message, String orderId
         model.addAttribute("message", message);
         model.addAttribute("orderId", orderId);
         model.addAttribute("name", name);
+        model.addAttribute("confirmationUnknown", PAYMENT_CONFIRMATION_UNKNOWN.equals(code));
         if (reservation != null) {
             model.addAttribute("reservation", PaymentReservationView.from(reservation));
         }

src/main/java/roomescape/controller/view/dto/PaymentFailRequest.java

@@ -0,0 +1,10 @@
+package roomescape.controller.view.dto;
+
+public record PaymentFailRequest(
+        String code,
+        String message,
+        String orderId,
+        Long paymentId,
+        String name
+) {
+}

src/main/java/roomescape/controller/view/dto/PaymentSuccessRequest.java

@@ -0,0 +1,9 @@
+package roomescape.controller.view.dto;
+
+public record PaymentSuccessRequest(
+        String paymentKey,
+        String orderId,
+        Long amount,
+        String name
+) {
+}

src/main/java/roomescape/domain/Payment.java

@@ -13,12 +13,13 @@ public class Payment {
     private final String failureCode;
     private final String failureMessage;
 
-    public Payment(Long id, Long reservationId, String orderId, Long amount, String paymentKey,
-                   PaymentStatus status, String failureCode, String failureMessage) {
+    private Payment(Long id, Long reservationId, String orderId, Long amount, String paymentKey,
+                    PaymentStatus status, String failureCode, String failureMessage) {
         validateReservationId(reservationId);
         validateOrderId(orderId);
         validateAmount(amount);
         validateStatus(status);
+        validateStatusFields(status, paymentKey, failureCode);
 
         this.id = id;
         this.reservationId = reservationId;
@@ -34,24 +35,31 @@ public static Payment ready(Long reservationId, Long amount) {
         return new Payment(null, reservationId, generateOrderId(), amount, null, PaymentStatus.READY, null, null);
     }
 
+    public static Payment restore(Long id, Long reservationId, String orderId, Long amount, String paymentKey,
+                                  PaymentStatus status, String failureCode, String failureMessage) {
+        validateId(id);
+        return new Payment(id, reservationId, orderId, amount, paymentKey, status, failureCode, failureMessage);
+    }
+
     public Payment withId(Long id) {
+        validateId(id);
         return new Payment(id, reservationId, orderId, amount, paymentKey, status, failureCode, failureMessage);
     }
 
     public Payment confirm(String paymentKey) {
-        if (status != PaymentStatus.READY) {
-            throw new IllegalStateException("결제 대기 상태에서만 승인할 수 있습니다.");
+        if (!canConfirm()) {
+            throw new IllegalStateException("결제 대기 또는 확인 필요 상태에서만 승인할 수 있습니다.");
         }
         if (paymentKey == null || paymentKey.isBlank()) {
             throw new IllegalArgumentException("paymentKey는 비어 있을 수 없습니다.");
         }
         return new Payment(id, reservationId, orderId, amount, paymentKey, PaymentStatus.CONFIRMED,
-                failureCode, failureMessage);
+                null, null);
     }
 
     public Payment fail(String failureCode, String failureMessage) {
-        if (status != PaymentStatus.READY) {
-            throw new IllegalStateException("결제 대기 상태에서만 실패 처리할 수 있습니다.");
+        if (!canConfirm()) {
+            throw new IllegalStateException("결제 대기 또는 확인 필요 상태에서만 실패 처리할 수 있습니다.");
         }
         PaymentStatus failedStatus = "PAY_PROCESS_CANCELED".equals(failureCode)
                 ? PaymentStatus.CANCELED
@@ -60,6 +68,14 @@ public Payment fail(String failureCode, String failureMessage) {
                 failureCode, failureMessage);
     }
 
+    public Payment checkRequired(String failureCode, String failureMessage) {
+        if (!canConfirm()) {
+            throw new IllegalStateException("결제 대기 또는 확인 필요 상태에서만 확인 필요 처리할 수 있습니다.");
+        }
+        return new Payment(id, reservationId, orderId, amount, paymentKey, PaymentStatus.CHECK_REQUIRED,
+                failureCode, failureMessage);
+    }
+
     public Long getId() {
         return id;
     }
@@ -96,6 +112,12 @@ private static String generateOrderId() {
         return "payment_" + UUID.randomUUID().toString().replace("-", "");
     }
 
+    private static void validateId(Long id) {
+        if (id == null || id <= 0) {
+            throw new IllegalArgumentException("id는 양수여야 합니다.");
+        }
+    }
+
     private void validateReservationId(Long reservationId) {
         if (reservationId == null || reservationId <= 0) {
             throw new IllegalArgumentException("reservationId는 양수여야 합니다.");
@@ -119,4 +141,22 @@ private void validateStatus(PaymentStatus status) {
             throw new IllegalArgumentException("status는 비어 있을 수 없습니다.");
         }
     }
+
+    private void validateStatusFields(PaymentStatus status, String paymentKey, String failureCode) {
+        if (status == PaymentStatus.READY && (paymentKey != null || failureCode != null)) {
+            throw new IllegalArgumentException("결제 대기 상태는 paymentKey나 실패 코드를 가질 수 없습니다.");
+        }
+        if (status == PaymentStatus.CONFIRMED && (paymentKey == null || paymentKey.isBlank())) {
+            throw new IllegalArgumentException("승인된 결제는 paymentKey가 필요합니다.");
+        }
+        if ((status == PaymentStatus.FAILED || status == PaymentStatus.CANCELED
+                || status == PaymentStatus.CHECK_REQUIRED)
+                && (failureCode == null || failureCode.isBlank())) {
+            throw new IllegalArgumentException("실패, 취소 또는 확인 필요 결제는 실패 코드가 필요합니다.");
+        }
+    }
+
+    private boolean canConfirm() {
+        return status == PaymentStatus.READY || status == PaymentStatus.CHECK_REQUIRED;
+    }
 }

src/main/java/roomescape/domain/PaymentStatus.java

@@ -4,6 +4,7 @@ public enum PaymentStatus {
     READY,
     FAILED,
     CANCELED,
+    CHECK_REQUIRED,
     CONFIRMED;
 
     public static PaymentStatus fromTossStatus(String tossStatus) {

src/main/java/roomescape/exception/ErrorCode.java

@@ -18,6 +18,7 @@ public enum ErrorCode {
     PAYMENT_RETRY_NOT_ALLOWED(HttpStatus.CONFLICT, "결제를 다시 시도할 수 없는 예약입니다."),
     PAYMENT_CONFIRMATION_NOT_ALLOWED(HttpStatus.CONFLICT, "결제 승인을 진행할 수 없는 상태입니다."),
     TEMPORARY_UNAVAILABLE(HttpStatus.SERVICE_UNAVAILABLE, "요청을 처리하지 못했습니다. 잠시 후 다시 시도해주세요."),
+    TOO_MANY_REQUESTS(HttpStatus.TOO_MANY_REQUESTS, "요청이 많아 처리하지 못했습니다. 잠시 후 다시 시도해주세요."),
     INTERNAL_SERVER_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "서버에 문제가 발생했습니다.");
 
     private final HttpStatus status;

src/main/java/roomescape/payment/client/GatewayRateLimitException.java

@@ -0,0 +1,18 @@
+package roomescape.payment.client;
+
+import roomescape.service.payment.PaymentFailureCategory;
+import roomescape.service.payment.PaymentGatewayException;
+
+/**
+ * 토스가 429 를 반복해 재시도 횟수를 모두 소진했을 때 던지는 예외.
+ *
+ * <p>429 는 "아직 처리되지 않음"을 뜻하므로 결제는 그대로 두고(상태 유지) 안전하게 다시 시도할 수 있다.
+ */
+public class GatewayRateLimitException extends PaymentGatewayException {
+
+    public static final String CODE = "TOO_MANY_REQUESTS";
+
+    public GatewayRateLimitException(String message) {
+        super(PaymentFailureCategory.RATE_LIMITED, CODE, message);
+    }
+}

src/main/java/roomescape/payment/client/OutboundRateLimitException.java

@@ -0,0 +1,18 @@
+package roomescape.payment.client;
+
+import roomescape.service.payment.PaymentFailureCategory;
+import roomescape.service.payment.PaymentGatewayException;
+
+/**
+ * 나가는 결제 호출이 자체 Rate Limit 을 초과해 외부로 보내지 않고 거부할 때 던지는 예외.
+ *
+ * <p>호출이 토스에 도달하지 않았으므로 결제는 그대로 두고(상태 유지) 안전하게 다시 시도할 수 있다.
+ */
+public class OutboundRateLimitException extends PaymentGatewayException {
+
+    public static final String CODE = "OUTBOUND_RATE_LIMITED";
+
+    public OutboundRateLimitException(String message) {
+        super(PaymentFailureCategory.RATE_LIMITED, CODE, message);
+    }
+}

src/main/java/roomescape/payment/client/OutboundRateLimitInterceptor.java

@@ -0,0 +1,32 @@
+package roomescape.payment.client;
+
+import java.io.IOException;
+import org.springframework.http.HttpRequest;
+import org.springframework.http.client.ClientHttpRequestExecution;
+import org.springframework.http.client.ClientHttpRequestInterceptor;
+import org.springframework.http.client.ClientHttpResponse;
+import roomescape.ratelimit.TokenBucketRateLimiter;
+
+/**
+ * 나가는 결제 호출에 토큰 버킷 Rate Limit 을 적용하는 인터셉터.
+ *
+ * <p>외부로 보내기 전에 토큰을 소비해, 한도를 넘으면 토스에 보내지 않고 {@link OutboundRateLimitException}
+ * 으로 거부한다. 들어오는 쪽과 같은 {@link TokenBucketRateLimiter} 를 방향만 바꿔 재사용한다.
+ */
+public class OutboundRateLimitInterceptor implements ClientHttpRequestInterceptor {
+
+    private final TokenBucketRateLimiter rateLimiter;
+
+    public OutboundRateLimitInterceptor(TokenBucketRateLimiter rateLimiter) {
+        this.rateLimiter = rateLimiter;
+    }
+
+    @Override
+    public ClientHttpResponse intercept(
+            HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException {
+        if (!rateLimiter.tryConsume()) {
+            throw new OutboundRateLimitException("결제 요청이 많아 처리하지 못했습니다. 잠시 후 다시 시도해주세요.");
+        }
+        return execution.execute(request, body);
+    }
+}