Feature/pg client (#27)

* test: PG 호출 테스트 코드 추가

* feat: PG 호출 로직 구현

* test: PG CircuitBreaker 테스트 코드 추가

* feat: CircuitBreaker 로직 구현

Author: minor7295

apps/commerce-api/build.gradle.kts

@@ -10,6 +10,18 @@ dependencies {
     implementation("org.springframework.boot:spring-boot-starter-web")
     implementation("org.springframework.boot:spring-boot-starter-actuator")
     implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:${project.properties["springDocOpenApiVersion"]}")
+    
+    // feign client
+    implementation("org.springframework.cloud:spring-cloud-starter-openfeign")
+    
+    // resilience4j
+    implementation("io.github.resilience4j:resilience4j-spring-boot3")
+    implementation("io.github.resilience4j:resilience4j-core") // IntervalFunction을 위한 core 모듈
+    implementation("io.github.resilience4j:resilience4j-circuitbreaker")
+    implementation("io.github.resilience4j:resilience4j-retry")
+    implementation("io.github.resilience4j:resilience4j-timelimiter")
+    implementation("io.github.resilience4j:resilience4j-bulkhead") // Bulkheads 패턴 구현
+    implementation("org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j")
 
     // batch
     implementation("org.springframework.boot:spring-boot-starter-batch")

apps/commerce-api/src/main/java/com/loopers/CommerceApiApplication.java

@@ -4,12 +4,14 @@
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
+import org.springframework.cloud.openfeign.EnableFeignClients;
 import org.springframework.scheduling.annotation.EnableScheduling;
 import java.util.TimeZone;
 
 @ConfigurationPropertiesScan
 @SpringBootApplication
 @EnableScheduling
+@EnableFeignClients
 public class CommerceApiApplication {
 
     @PostConstruct

apps/commerce-api/src/main/java/com/loopers/application/purchasing/PaymentRecoveryScheduler.java

@@ -0,0 +1,118 @@
+package com.loopers.application.purchasing;
+
+import com.loopers.domain.order.Order;
+import com.loopers.domain.order.OrderRepository;
+import com.loopers.domain.order.OrderStatus;
+import com.loopers.infrastructure.paymentgateway.PaymentGatewayClient;
+import com.loopers.infrastructure.paymentgateway.PaymentGatewayDto;
+import com.loopers.infrastructure.user.UserJpaRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 결제 상태 복구 스케줄러.
+ * <p>
+ * 콜백이 오지 않은 PENDING 상태의 주문들을 주기적으로 조회하여
+ * PG 시스템의 결제 상태 확인 API를 통해 상태를 복구합니다.
+ * </p>
+ * <p>
+ * <b>동작 원리:</b>
+ * <ol>
+ *   <li>주기적으로 실행 (기본: 1분마다)</li>
+ *   <li>PENDING 상태인 주문들을 조회</li>
+ *   <li>각 주문에 대해 PG 결제 상태 확인 API 호출</li>
+ *   <li>결제 상태에 따라 주문 상태 업데이트</li>
+ * </ol>
+ * </p>
+ * <p>
+ * <b>설계 근거:</b>
+ * <ul>
+ *   <li><b>주기적 복구:</b> 콜백이 오지 않아도 자동으로 상태 복구</li>
+ *   <li><b>Eventually Consistent:</b> 약간의 지연 허용 가능</li>
+ *   <li><b>안전한 처리:</b> 각 주문별로 독립적으로 처리하여 실패 시에도 다른 주문에 영향 없음</li>
+ *   <li><b>성능 고려:</b> 배치로 처리하여 PG 시스템 부하 최소화</li>
+ * </ul>
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@Slf4j
+@RequiredArgsConstructor
+@Component
+public class PaymentRecoveryScheduler {
+
+    private final OrderRepository orderRepository;
+    private final UserJpaRepository userJpaRepository;
+    private final PurchasingFacade purchasingFacade;
+
+    /**
+     * PENDING 상태인 주문들의 결제 상태를 복구합니다.
+     * <p>
+     * 1분마다 실행되어 PENDING 상태인 주문들을 조회하고,
+     * 각 주문에 대해 PG 결제 상태 확인 API를 호출하여 상태를 복구합니다.
+     * </p>
+     * <p>
+     * <b>처리 전략:</b>
+     * <ul>
+     *   <li><b>배치 처리:</b> 한 번에 여러 주문 처리</li>
+     *   <li><b>독립적 처리:</b> 각 주문별로 독립적으로 처리하여 실패 시에도 다른 주문에 영향 없음</li>
+     *   <li><b>안전한 예외 처리:</b> 개별 주문 처리 실패 시에도 계속 진행</li>
+     * </ul>
+     * </p>
+     */
+    @Scheduled(fixedDelay = 60000) // 1분마다 실행
+    public void recoverPendingOrders() {
+        try {
+            log.debug("결제 상태 복구 스케줄러 시작");
+
+            // PENDING 상태인 주문들 조회
+            List<Order> pendingOrders = orderRepository.findAllByStatus(OrderStatus.PENDING);
+
+            if (pendingOrders.isEmpty()) {
+                log.debug("복구할 PENDING 상태 주문이 없습니다.");
+                return;
+            }
+
+            log.info("PENDING 상태 주문 {}건에 대한 결제 상태 복구 시작", pendingOrders.size());
+
+            int successCount = 0;
+            int failureCount = 0;
+
+            // 각 주문에 대해 결제 상태 확인 및 복구
+            for (Order order : pendingOrders) {
+                try {
+                    // Order의 userId는 User의 id (Long)이므로 User를 조회하여 userId (String)를 가져옴
+                    var userOptional = userJpaRepository.findById(order.getUserId());
+                    if (userOptional.isEmpty()) {
+                        log.warn("주문의 사용자를 찾을 수 없습니다. 복구를 건너뜁니다. (orderId: {}, userId: {})",
+                            order.getId(), order.getUserId());
+                        failureCount++;
+                        continue;
+                    }
+
+                    String userId = userOptional.get().getUserId();
+                    
+                    // 결제 상태 확인 및 복구
+                    purchasingFacade.recoverOrderStatusByPaymentCheck(userId, order.getId());
+                    successCount++;
+                } catch (Exception e) {
+                    // 개별 주문 처리 실패 시에도 계속 진행
+                    log.error("주문 상태 복구 중 오류 발생. (orderId: {})", order.getId(), e);
+                    failureCount++;
+                }
+            }
+
+            log.info("결제 상태 복구 완료. 성공: {}건, 실패: {}건", successCount, failureCount);
+
+        } catch (Exception e) {
+            log.error("결제 상태 복구 스케줄러 실행 중 오류 발생", e);
+        }
+    }
+}
+

apps/commerce-api/src/main/java/com/loopers/application/purchasing/PaymentRecoveryService.java

@@ -0,0 +1,62 @@
+package com.loopers.application.purchasing;
+
+import com.loopers.domain.order.OrderStatusUpdater;
+import com.loopers.infrastructure.paymentgateway.DelayProvider;
+import com.loopers.infrastructure.paymentgateway.PaymentGatewayAdapter;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.time.Duration;
+
+/**
+ * 결제 복구 서비스.
+ * <p>
+ * 타임아웃 발생 후 결제 상태를 확인하여 주문 상태를 복구합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class PaymentRecoveryService {
+    
+    private final PaymentGatewayAdapter paymentGatewayAdapter;
+    private final OrderStatusUpdater orderStatusUpdater;
+    private final DelayProvider delayProvider;
+    
+    /**
+     * 타임아웃 발생 후 결제 상태를 확인하여 주문 상태를 복구합니다.
+     * <p>
+     * 타임아웃은 요청이 전송되었을 수 있으므로, 실제 결제 상태를 확인하여
+     * 결제가 성공했다면 주문을 완료하고, 실패했다면 주문을 취소합니다.
+     * </p>
+     *
+     * @param userId 사용자 ID
+     * @param orderId 주문 ID
+     */
+    public void recoverAfterTimeout(String userId, Long orderId) {
+        try {
+            // 잠시 대기 후 상태 확인 (PG 처리 시간 고려)
+            // 타임아웃이 발생했지만 요청은 전송되었을 수 있으므로,
+            // PG 시스템이 처리할 시간을 주기 위해 짧은 대기
+            delayProvider.delay(Duration.ofSeconds(1));
+            
+            // PG에서 주문별 결제 정보 조회
+            var status = paymentGatewayAdapter.getPaymentStatus(userId, String.valueOf(orderId));
+            
+            // 별도 트랜잭션으로 상태 업데이트
+            orderStatusUpdater.updateByPaymentStatus(orderId, status, null, null);
+            
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            log.warn("타임아웃 후 상태 확인 중 인터럽트 발생. (orderId: {})", orderId);
+        } catch (Exception e) {
+            // 기타 오류: 나중에 스케줄러로 복구 가능
+            log.error("타임아웃 후 상태 확인 중 오류 발생. 나중에 스케줄러로 복구됩니다. (orderId: {})", orderId, e);
+        }
+    }
+}
+

apps/commerce-api/src/main/java/com/loopers/application/purchasing/PaymentRequest.java

@@ -0,0 +1,20 @@
+package com.loopers.application.purchasing;
+
+import com.loopers.infrastructure.paymentgateway.PaymentGatewayDto;
+
+/**
+ * 결제 요청 도메인 모델.
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+public record PaymentRequest(
+    String userId,
+    String orderId,
+    PaymentGatewayDto.CardType cardType,
+    String cardNo,
+    Long amount,
+    String callbackUrl
+) {
+}
+

apps/commerce-api/src/main/java/com/loopers/application/purchasing/PaymentRequestBuilder.java

@@ -0,0 +1,89 @@
+package com.loopers.application.purchasing;
+
+import com.loopers.infrastructure.paymentgateway.PaymentGatewayDto;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+/**
+ * 결제 요청 빌더.
+ * <p>
+ * 결제 요청 도메인 모델을 생성합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@Component
+@RequiredArgsConstructor
+public class PaymentRequestBuilder {
+    
+    @Value("${server.port:8080}")
+    private int serverPort;
+    
+    /**
+     * 결제 요청을 생성합니다.
+     *
+     * @param userId 사용자 ID
+     * @param orderId 주문 ID
+     * @param cardType 카드 타입 문자열
+     * @param cardNo 카드 번호
+     * @param amount 결제 금액
+     * @return 결제 요청 도메인 모델
+     * @throws CoreException 잘못된 카드 타입인 경우
+     */
+    public PaymentRequest build(String userId, Long orderId, String cardType, String cardNo, Integer amount) {
+        // 주문 ID를 6자리 이상 문자열로 변환 (pg-simulator 검증 요구사항)
+        String orderIdString = formatOrderId(orderId);
+        return new PaymentRequest(
+            userId,
+            orderIdString,
+            parseCardType(cardType),
+            cardNo,
+            amount.longValue(),
+            generateCallbackUrl(orderId)
+        );
+    }
+    
+    /**
+     * 카드 타입 문자열을 CardType enum으로 변환합니다.
+     *
+     * @param cardType 카드 타입 문자열
+     * @return CardType enum
+     * @throws CoreException 잘못된 카드 타입인 경우
+     */
+    private PaymentGatewayDto.CardType parseCardType(String cardType) {
+        try {
+            return PaymentGatewayDto.CardType.valueOf(cardType.toUpperCase());
+        } catch (IllegalArgumentException e) {
+            throw new CoreException(ErrorType.BAD_REQUEST,
+                String.format("잘못된 카드 타입입니다. (cardType: %s)", cardType));
+        }
+    }
+    
+    /**
+     * 콜백 URL을 생성합니다.
+     *
+     * @param orderId 주문 ID
+     * @return 콜백 URL
+     */
+    private String generateCallbackUrl(Long orderId) {
+        return String.format("http://localhost:%d/api/v1/orders/%d/callback", serverPort, orderId);
+    }
+    
+    /**
+     * 주문 ID를 6자리 이상 문자열로 변환합니다.
+     * <p>
+     * pg-simulator의 검증 요구사항에 맞추기 위해 최소 6자리로 패딩합니다.
+     * </p>
+     *
+     * @param orderId 주문 ID (Long)
+     * @return 6자리 이상의 주문 ID 문자열
+     */
+    public String formatOrderId(Long orderId) {
+        return String.format("%06d", orderId);
+    }
+}
+