refactor: update payment API layer for Order integration

sylee6529 · sylee6529 · commit 6365416325bd · 2025-12-05T17:42:55.000+09:00
- PaymentController orderId → orderNo 변경
- PaymentTestController 로그 메시지 수정
- PaymentStatusSyncScheduler orderId() → orderNo() 변경
- PgPaymentClient 주석 정리
- API 응답 DTO orderNo 필드로 통일
diff --git a/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentStatusSyncScheduler.java b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentStatusSyncScheduler.java
@@ -8,33 +8,18 @@
 import java.time.LocalDateTime;
 import java.util.List;
 
-/**
- * Payment 상태 동기화 스케줄러
- *
- * 콜백이 오지 않은 PENDING 상태의 결제를 주기적으로 확인하여 상태 동기화
- */
 @Slf4j
 @Component
 @RequiredArgsConstructor
 public class PaymentStatusSyncScheduler {
 
     private final PaymentFacade paymentFacade;
 
-    /**
-     * PENDING 상태 결제 동기화
-     *
-     * - 10분 이상 PENDING 상태인 결제들을 조회
-     * - PG 상태 조회 API로 최종 상태 확인
-     * - Payment 및 Order 상태 업데이트
-     *
-     * 실행 주기: 1분마다
-     */
     @Scheduled(fixedDelay = 60000, initialDelay = 60000)
     public void syncPendingPayments() {
         log.info("[PaymentSync] PENDING 결제 동기화 시작");
 
         try {
-            // 10분 이상 PENDING 상태인 결제 조회
             LocalDateTime cutoffTime = LocalDateTime.now().minusMinutes(10);
             List<PaymentInfo> pendingPayments = paymentFacade.getPendingPaymentsOlderThan(cutoffTime);
 
@@ -51,25 +36,24 @@ public void syncPendingPayments() {
             for (PaymentInfo paymentInfo : pendingPayments) {
                 try {
                     if (paymentInfo.transactionKey() == null || paymentInfo.transactionKey().isEmpty()) {
-                        log.warn("[PaymentSync] transactionKey 없음, 스킵 - orderId: {}", paymentInfo.orderId());
+                        log.warn("[PaymentSync] transactionKey 없음, 스킵 - orderNo: {}", paymentInfo.orderNo());
                         continue;
                     }
 
-                    // PG 상태 조회 및 동기화
                     PaymentInfo syncedPayment = paymentFacade.syncPaymentStatus(
                             "SCHEDULER",
                             paymentInfo.transactionKey()
                     );
 
-                    log.info("[PaymentSync] 동기화 완료 - orderId: {}, status: {} -> {}",
-                            paymentInfo.orderId(),
+                    log.info("[PaymentSync] 동기화 완료 - orderNo: {}, status: {} -> {}",
+                            paymentInfo.orderNo(),
                             paymentInfo.status(),
                             syncedPayment.status());
 
                     successCount++;
 
                 } catch (Exception e) {
-                    log.error("[PaymentSync] 동기화 실패 - orderId: {}", paymentInfo.orderId(), e);
+                    log.error("[PaymentSync] 동기화 실패 - orderNo: {}", paymentInfo.orderNo(), e);
                     failureCount++;
                 }
             }
@@ -81,13 +65,6 @@ public void syncPendingPayments() {
         }
     }
 
-    /**
-     * 재시도 필요 결제 처리
-     *
-     * PG 장애로 인해 재시도가 필요한 결제들을 수동으로 처리
-     *
-     * 실행 주기: 5분마다
-     */
     @Scheduled(fixedDelay = 300000, initialDelay = 120000)
     public void processRetryPayments() {
         log.info("[PaymentRetry] 재시도 필요 결제 처리 시작");
@@ -103,7 +80,7 @@ public void processRetryPayments() {
             log.info("[PaymentRetry] 재시도 필요 결제 {}건 발견", retryPayments.size());
 
             for (PaymentInfo paymentInfo : retryPayments) {
-                log.warn("[PaymentRetry] 수동 처리 필요 - orderId: {}, 관리자 확인 필요", paymentInfo.orderId());
+                log.warn("[PaymentRetry] 수동 처리 필요 - orderNo: {}, 관리자 확인 필요", paymentInfo.orderNo());
                 // TODO: 관리자 알림, 수동 재시도 API 제공 등
             }
 
diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/pg/PgPaymentClient.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/pg/PgPaymentClient.java
@@ -1,5 +1,7 @@
 package com.loopers.infrastructure.payment.pg;
 
+import com.loopers.domain.payment.CardType;
+import com.loopers.domain.payment.gateway.PgGateway;
 import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
 import io.github.resilience4j.retry.annotation.Retry;
 import io.github.resilience4j.timelimiter.annotation.TimeLimiter;
@@ -17,7 +19,7 @@
 
 @Slf4j
 @Component
-public class PgPaymentClient {
+public class PgPaymentClient implements PgGateway {
 
     private final RestTemplate pgRestTemplate;
 
@@ -30,23 +32,26 @@ public PgPaymentClient(RestTemplate pgRestTemplate) {
         this.pgRestTemplate = pgRestTemplate;
     }
 
-    /**
-     * 결제 요청 API
-     * - CircuitBreaker: PG 장애 시 빠른 실패
-     * - Retry: 일시적 오류 시 재시도
-     * - TimeLimiter: 2초 타임아웃
-     */
+    @Override
     @CircuitBreaker(name = PG_INSTANCE, fallbackMethod = "requestPaymentFallback")
     @Retry(name = PG_INSTANCE)
     @TimeLimiter(name = PG_INSTANCE)
-    public CompletableFuture<PgPaymentResponse> requestPayment(String userId, PgPaymentRequest request) {
+    public CompletableFuture<PgPaymentResult> requestPayment(String userId, PgPaymentCommand command) {
         return CompletableFuture.supplyAsync(() -> {
-            log.info("[PG] 결제 요청 시작 - orderId: {}, amount: {}", request.orderId(), request.amount());
+            log.info("[PG] 결제 요청 시작 - orderId: {}, amount: {}", command.orderId(), command.amount());
 
             HttpHeaders headers = new HttpHeaders();
             headers.set("X-USER-ID", userId);
             headers.set("Content-Type", "application/json");
 
+            PgPaymentRequest request = new PgPaymentRequest(
+                    command.orderId(),
+                    toPgCardType(command.cardType()),
+                    command.cardNo(),
+                    command.amount(),
+                    command.callbackUrl()
+            );
+
             HttpEntity<PgPaymentRequest> entity = new HttpEntity<>(request, headers);
 
             try {
@@ -62,25 +67,25 @@ public CompletableFuture<PgPaymentResponse> requestPayment(String userId, PgPaym
                     PgPaymentResponse paymentResponse = response.getBody().data();
                     log.info("[PG] 결제 요청 성공 - transactionKey: {}, status: {}",
                             paymentResponse.transactionKey(), paymentResponse.status());
-                    return paymentResponse;
+                    return new PgPaymentResult(
+                            paymentResponse.transactionKey(),
+                            toPgTransactionStatus(paymentResponse.status()),
+                            paymentResponse.reason()
+                    );
                 } else {
                     throw new PgCommunicationException("PG 응답이 비어있습니다.");
                 }
             } catch (RestClientException e) {
-                log.error("[PG] 결제 요청 실패 - orderId: {}", request.orderId(), e);
+                log.error("[PG] 결제 요청 실패 - orderId: {}", command.orderId(), e);
                 throw new PgCommunicationException("PG 통신 실패", e);
             }
         });
     }
 
-    /**
-     * 결제 상태 조회 API
-     * - CircuitBreaker 적용
-     * - Retry 적용
-     */
+    @Override
     @CircuitBreaker(name = PG_INSTANCE, fallbackMethod = "getPaymentStatusFallback")
     @Retry(name = PG_INSTANCE)
-    public PgPaymentDetailResponse getPaymentStatus(String userId, String transactionKey) {
+    public PgPaymentDetail getPaymentStatus(String userId, String transactionKey) {
         log.info("[PG] 결제 상태 조회 - transactionKey: {}", transactionKey);
 
         HttpHeaders headers = new HttpHeaders();
@@ -101,7 +106,15 @@ public PgPaymentDetailResponse getPaymentStatus(String userId, String transactio
                 PgPaymentDetailResponse detailResponse = response.getBody().data();
                 log.info("[PG] 결제 상태 조회 성공 - transactionKey: {}, status: {}",
                         transactionKey, detailResponse.status());
-                return detailResponse;
+                return new PgPaymentDetail(
+                        detailResponse.transactionKey(),
+                        detailResponse.orderId(),
+                        toCardType(detailResponse.cardType()),
+                        detailResponse.cardNo(),
+                        detailResponse.amount(),
+                        toPgTransactionStatus(detailResponse.status()),
+                        detailResponse.reason()
+                );
             } else {
                 throw new PgCommunicationException("PG 응답이 비어있습니다.");
             }
@@ -111,69 +124,60 @@ public PgPaymentDetailResponse getPaymentStatus(String userId, String transactio
         }
     }
 
-    // ========== Fallback Methods ==========
-
-    /**
-     * 결제 요청 Fallback
-     * - Circuit Open 또는 재시도 실패 시 호출
-     * - transactionKey를 null로 반환하여 재시도 필요함을 표시
-     */
-    private CompletableFuture<PgPaymentResponse> requestPaymentFallback(
+    private CompletableFuture<PgPaymentResult> requestPaymentFallback(
             String userId,
-            PgPaymentRequest request,
+            PgPaymentCommand command,
             Exception ex
     ) {
         log.error("[PG Fallback] 결제 요청 실패 - orderId: {}, error: {}",
-                request.orderId(), ex.getMessage());
+                command.orderId(), ex.getMessage());
 
-        // transactionKey를 null로 반환하여 PG 장애를 명확히 표시
-        // Service 레이어에서 이를 감지하고 requiresRetry 플래그 설정
-        PgPaymentResponse fallbackResponse = new PgPaymentResponse(
-                null,  // transactionKey가 없음 = PG 호출 실패
-                PgPaymentResponse.PgTransactionStatus.PENDING,
+        PgPaymentResult fallbackResponse = new PgPaymentResult(
+                null,
+                PgTransactionStatus.PENDING,
                 "PG 시스템 일시 장애 - 나중에 재시도가 필요합니다."
         );
 
         return CompletableFuture.completedFuture(fallbackResponse);
     }
 
-    /**
-     * 결제 상태 조회 Fallback
-     * - 조회 실패 시 PENDING 상태로 반환
-     */
-    private PgPaymentDetailResponse getPaymentStatusFallback(
+    private PgPaymentDetail getPaymentStatusFallback(
             String userId,
             String transactionKey,
             Exception ex
     ) {
         log.warn("[PG Fallback] 결제 상태 조회 실패, PENDING 상태로 반환 - transactionKey: {}, error: {}",
                 transactionKey, ex.getMessage());
 
-        return new PgPaymentDetailResponse(
+        return new PgPaymentDetail(
                 transactionKey,
                 "UNKNOWN",
                 null,
                 "****-****-****-****",
                 0L,
-                PgPaymentResponse.PgTransactionStatus.PENDING,
+                PgTransactionStatus.PENDING,
                 "PG 시스템 일시 장애 - 결제 상태를 확인할 수 없습니다."
         );
     }
 
-    // ========== Helper Classes ==========
+    private PgPaymentRequest.PgCardType toPgCardType(CardType cardType) {
+        return PgPaymentRequest.PgCardType.valueOf(cardType.name());
+    }
+
+    private CardType toCardType(PgPaymentRequest.PgCardType cardType) {
+        return CardType.valueOf(cardType.name());
+    }
+
+    private PgTransactionStatus toPgTransactionStatus(PgPaymentResponse.PgTransactionStatus status) {
+        return PgTransactionStatus.valueOf(status.name());
+    }
 
-    /**
-     * PG API 응답 래퍼
-     */
     public record PgApiResponse<T>(
             String result,
             String message,
             T data
     ) {}
 
-    /**
-     * PG 통신 예외
-     */
     public static class PgCommunicationException extends RuntimeException {
         public PgCommunicationException(String message) {
             super(message);
diff --git a/apps/commerce-api/src/main/java/com/loopers/interfaces/api/payment/PaymentController.java b/apps/commerce-api/src/main/java/com/loopers/interfaces/api/payment/PaymentController.java
@@ -9,10 +9,6 @@
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
-/**
- * Payment API 컨트롤러
- * - 결제 요청, 조회, 상태 동기화
- */
 @Slf4j
 @RestController
 @RequestMapping("/api/v1/payments")
@@ -21,11 +17,6 @@ public class PaymentController {
 
     private final PaymentFacade paymentFacade;
 
-    /**
-     * 결제 요청
-     *
-     * POST /api/v1/payments
-     */
     @PostMapping
     public ResponseEntity<PaymentResponse> requestPayment(
             @RequestHeader("X-USER-ID") String userId,
@@ -46,28 +37,18 @@ public ResponseEntity<PaymentResponse> requestPayment(
         return ResponseEntity.ok(PaymentResponse.from(paymentInfo));
     }
 
-    /**
-     * orderId로 결제 정보 조회
-     *
-     * GET /api/v1/payments/orders/{orderId}
-     */
-    @GetMapping("/orders/{orderId}")
-    public ResponseEntity<PaymentResponse> getPaymentByOrderId(
+    @GetMapping("/orders/{orderNo}")
+    public ResponseEntity<PaymentResponse> getPaymentByOrderNo(
             @RequestHeader("X-USER-ID") String userId,
-            @PathVariable String orderId
+            @PathVariable String orderNo
     ) {
-        log.info("[Payment API] 결제 조회 - userId: {}, orderId: {}", userId, orderId);
+        log.info("[Payment API] 결제 조회 - userId: {}, orderNo: {}", userId, orderNo);
 
-        PaymentInfo paymentInfo = paymentFacade.getPaymentByOrderId(orderId);
+        PaymentInfo paymentInfo = paymentFacade.getPaymentByOrderNo(orderNo);
 
         return ResponseEntity.ok(PaymentResponse.from(paymentInfo));
     }
 
-    /**
-     * transactionKey로 결제 상태 동기화
-     *
-     * POST /api/v1/payments/{transactionKey}/sync
-     */
     @PostMapping("/{transactionKey}/sync")
     public ResponseEntity<PaymentResponse> syncPaymentStatus(
             @RequestHeader("X-USER-ID") String userId,
@@ -80,8 +61,6 @@ public ResponseEntity<PaymentResponse> syncPaymentStatus(
         return ResponseEntity.ok(PaymentResponse.from(paymentInfo));
     }
 
-    // ========== DTOs ==========
-
     public record PaymentRequest(
             String orderId,
             CardType cardType,
@@ -92,7 +71,7 @@ public record PaymentRequest(
 
     public record PaymentResponse(
             Long id,
-            String orderId,
+            String orderNo,
             String transactionKey,
             String status,
             String cardType,
@@ -104,7 +83,7 @@ public record PaymentResponse(
         public static PaymentResponse from(PaymentInfo info) {
             return new PaymentResponse(
                     info.id(),
-                    info.orderId(),
+                    info.orderNo(),
                     info.transactionKey(),
                     info.status().name(),
                     info.cardType().name(),
diff --git a/apps/commerce-api/src/main/java/com/loopers/interfaces/api/payment/PaymentTestController.java b/apps/commerce-api/src/main/java/com/loopers/interfaces/api/payment/PaymentTestController.java
