Feature/refactor purchasing

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

@@ -0,0 +1,43 @@
+package com.loopers.application.purchasing;
+
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+
+/**
+ * 결제 요청 명령.
+ * <p>
+ * PG 결제 요청에 필요한 정보를 담는 명령 모델입니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+public record PaymentRequestCommand(
+    String userId,
+    Long orderId,
+    String cardType,
+    String cardNo,
+    Long amount,
+    String callbackUrl
+) {
+    public PaymentRequestCommand {
+        if (userId == null || userId.isBlank()) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "userId는 필수입니다.");
+        }
+        if (orderId == null) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "orderId는 필수입니다.");
+        }
+        if (cardType == null || cardType.isBlank()) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "cardType은 필수입니다.");
+        }
+        if (cardNo == null || cardNo.isBlank()) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "cardNo는 필수입니다.");
+        }
+        if (amount == null || amount <= 0) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "amount는 0보다 커야 합니다.");
+        }
+        if (callbackUrl == null || callbackUrl.isBlank()) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "callbackUrl은 필수입니다.");
+        }
+    }
+}

apps/commerce-api/src/main/java/com/loopers/config/Resilience4jRetryConfig.java

@@ -119,9 +119,9 @@ public RetryRegistry retryRegistry() {
         // Exponential Backoff 적용하여 일시적 오류 자동 복구
         retryRegistry.addConfiguration("paymentGatewaySchedulerClient", retryConfig);
 
-        log.info("Resilience4j Retry 설정 완료:");
-        log.info("  - 결제 요청 API (paymentGatewayClient): Retry 없음 (유저 요청 경로 - 빠른 실패)");
-        log.info("  - 조회 API (paymentGatewaySchedulerClient): Exponential Backoff 적용 (스케줄러 - 비동기/배치 기반 Retry)");
+        log.debug("Resilience4j Retry 설정 완료:");
+        log.debug("  - 결제 요청 API (paymentGatewayClient): Retry 없음 (유저 요청 경로 - 빠른 실패)");
+        log.debug("  - 조회 API (paymentGatewaySchedulerClient): Exponential Backoff 적용 (스케줄러 - 비동기/배치 기반 Retry)");
 
         return retryRegistry;
     }

apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponService.java

@@ -0,0 +1,84 @@
+package com.loopers.domain.coupon;
+
+import com.loopers.domain.coupon.discount.CouponDiscountStrategyFactory;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import lombok.RequiredArgsConstructor;
+import org.springframework.orm.ObjectOptimisticLockingFailureException;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 쿠폰 도메인 서비스.
+ * <p>
+ * 쿠폰 조회, 사용 등의 도메인 로직을 처리합니다.
+ * Repository에 의존하며 비즈니스 규칙을 캡슐화합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@RequiredArgsConstructor
+@Component
+public class CouponService {
+    private final CouponRepository couponRepository;
+    private final UserCouponRepository userCouponRepository;
+    private final CouponDiscountStrategyFactory couponDiscountStrategyFactory;
+
+    /**
+     * 쿠폰을 적용하여 할인 금액을 계산하고 쿠폰을 사용 처리합니다.
+     * <p>
+     * <b>동시성 제어 전략:</b>
+     * <ul>
+     *   <li><b>OPTIMISTIC_LOCK 사용 근거:</b> 쿠폰 중복 사용 방지, Hot Spot 대응</li>
+     *   <li><b>@Version 필드:</b> UserCoupon 엔티티의 version 필드를 통해 자동으로 낙관적 락 적용</li>
+     *   <li><b>동시 사용 시:</b> 한 명만 성공하고 나머지는 OptimisticLockException 발생</li>
+     *   <li><b>사용 목적:</b> 동일 쿠폰으로 여러 기기에서 동시 주문해도 한 번만 사용되도록 보장</li>
+     * </ul>
+     * </p>
+     *
+     * @param userId 사용자 ID
+     * @param couponCode 쿠폰 코드
+     * @param subtotal 주문 소계 금액
+     * @return 할인 금액
+     * @throws CoreException 쿠폰을 찾을 수 없거나 사용 불가능한 경우, 동시 사용으로 인한 충돌 시
+     */
+    @Transactional
+    public Integer applyCoupon(Long userId, String couponCode, Integer subtotal) {
+        // 쿠폰 존재 여부 확인
+        Coupon coupon = couponRepository.findByCode(couponCode)
+            .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND,
+                String.format("쿠폰을 찾을 수 없습니다. (쿠폰 코드: %s)", couponCode)));
+
+        // 낙관적 락을 사용하여 사용자 쿠폰 조회 (동시성 제어)
+        // @Version 필드가 있어 자동으로 낙관적 락이 적용됨
+        UserCoupon userCoupon = userCouponRepository.findByUserIdAndCouponCodeForUpdate(userId, couponCode)
+            .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND,
+                String.format("사용자가 소유한 쿠폰을 찾을 수 없습니다. (쿠폰 코드: %s)", couponCode)));
+
+        // 쿠폰 사용 가능 여부 확인
+        if (!userCoupon.isAvailable()) {
+            throw new CoreException(ErrorType.BAD_REQUEST,
+                String.format("이미 사용된 쿠폰입니다. (쿠폰 코드: %s)", couponCode));
+        }
+
+        // 쿠폰 사용 처리
+        userCoupon.use();
+
+        // 할인 금액 계산 (전략 패턴 사용)
+        Integer discountAmount = coupon.calculateDiscountAmount(subtotal, couponDiscountStrategyFactory);
+
+        try {
+            // 사용자 쿠폰 저장 (version 체크 자동 수행)
+            // 다른 트랜잭션이 먼저 수정했다면 OptimisticLockException 발생
+            userCouponRepository.save(userCoupon);
+        } catch (ObjectOptimisticLockingFailureException e) {
+            // 낙관적 락 충돌: 다른 트랜잭션이 먼저 쿠폰을 사용함
+            throw new CoreException(ErrorType.CONFLICT,
+                String.format("쿠폰이 이미 사용되었습니다. (쿠폰 코드: %s)", couponCode));
+        }
+
+        return discountAmount;
+    }
+}
+

apps/commerce-api/src/main/java/com/loopers/domain/order/OrderService.java

@@ -0,0 +1,216 @@
+package com.loopers.domain.order;
+
+import com.loopers.domain.payment.PaymentStatus;
+import com.loopers.domain.product.Product;
+import com.loopers.domain.user.Point;
+import com.loopers.domain.user.User;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * 주문 도메인 서비스.
+ * <p>
+ * 주문의 기본 CRUD 및 상태 변경을 담당합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@Component
+@RequiredArgsConstructor
+public class OrderService {
+
+    private final OrderRepository orderRepository;
+
+    /**
+     * 주문을 저장합니다.
+     *
+     * @param order 저장할 주문
+     * @return 저장된 주문
+     */
+    @Transactional
+    public Order save(Order order) {
+        return orderRepository.save(order);
+    }
+
+    /**
+     * 주문 ID로 주문을 조회합니다.
+     *
+     * @param orderId 주문 ID
+     * @return 조회된 주문
+     * @throws CoreException 주문을 찾을 수 없는 경우
+     */
+    @Transactional(readOnly = true)
+    public Order getById(Long orderId) {
+        return orderRepository.findById(orderId)
+            .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "주문을 찾을 수 없습니다."));
+    }
+
+    /**
+     * 주문 ID로 주문을 조회합니다 (Optional 반환).
+     *
+     * @param orderId 주문 ID
+     * @return 조회된 주문 (없으면 Optional.empty())
+     */
+    @Transactional(readOnly = true)
+    public Optional<Order> findById(Long orderId) {
+        return orderRepository.findById(orderId);
+    }
+
+    /**
+     * 사용자 ID로 주문 목록을 조회합니다.
+     *
+     * @param userId 사용자 ID
+     * @return 해당 사용자의 주문 목록
+     */
+    @Transactional(readOnly = true)
+    public List<Order> findAllByUserId(Long userId) {
+        return orderRepository.findAllByUserId(userId);
+    }
+
+    /**
+     * 주문 상태로 주문 목록을 조회합니다.
+     *
+     * @param status 주문 상태
+     * @return 해당 상태의 주문 목록
+     */
+    @Transactional(readOnly = true)
+    public List<Order> findAllByStatus(OrderStatus status) {
+        return orderRepository.findAllByStatus(status);
+    }
+
+    /**
+     * 주문을 생성합니다.
+     *
+     * @param userId 사용자 ID
+     * @param items 주문 아이템 목록
+     * @param couponCode 쿠폰 코드 (선택)
+     * @param discountAmount 할인 금액 (선택)
+     * @return 생성된 주문
+     */
+    @Transactional
+    public Order create(Long userId, List<OrderItem> items, String couponCode, Integer discountAmount) {
+        Order order = Order.of(userId, items, couponCode, discountAmount);
+        return orderRepository.save(order);
+    }
+
+    /**
+     * 주문을 생성합니다 (쿠폰 없음).
+     *
+     * @param userId 사용자 ID
+     * @param items 주문 아이템 목록
+     * @return 생성된 주문
+     */
+    @Transactional
+    public Order create(Long userId, List<OrderItem> items) {
+        Order order = Order.of(userId, items);
+        return orderRepository.save(order);
+    }
+
+    /**
+     * 주문을 완료 상태로 변경합니다.
+     *
+     * @param orderId 주문 ID
+     * @return 완료된 주문
+     * @throws CoreException 주문을 찾을 수 없는 경우
+     */
+    @Transactional
+    public Order completeOrder(Long orderId) {
+        Order order = getById(orderId);
+        order.complete();
+        return orderRepository.save(order);
+    }
+
+    /**
+     * 주문을 취소 상태로 변경하고 재고를 원복하며 포인트를 환불합니다.
+     * <p>
+     * 도메인 로직만 처리합니다. 사용자 조회, 상품 조회, Payment 조회는 애플리케이션 레이어에서 처리합니다.
+     * </p>
+     *
+     * @param order 주문 엔티티
+     * @param products 주문 아이템에 해당하는 상품 목록 (락이 이미 획득된 상태)
+     * @param user 사용자 엔티티 (락이 이미 획득된 상태)
+     * @param refundPointAmount 환불할 포인트 금액
+     * @throws CoreException 주문 또는 사용자 정보가 null인 경우
+     */
+    @Transactional
+    public void cancelOrder(Order order, List<Product> products, User user, Long refundPointAmount) {
+        if (order == null || user == null) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "취소할 주문과 사용자 정보는 필수입니다.");
+        }
+
+        // 주문 취소
+        order.cancel();
+
+        // 재고 원복
+        increaseStocksForOrderItems(order.getItems(), products);
+
+        // 포인트 환불
+        if (refundPointAmount > 0) {
+            user.receivePoint(Point.of(refundPointAmount));
+        }
+
+        orderRepository.save(order);
+    }
+
+    /**
+     * 결제 상태에 따라 주문 상태를 업데이트합니다.
+     * <p>
+     * 도메인 로직만 처리합니다. 사용자 조회, 트랜잭션 관리, 로깅은 애플리케이션 레이어에서 처리합니다.
+     * </p>
+     *
+     * @param order 주문 엔티티
+     * @param paymentStatus 결제 상태
+     * @throws CoreException 주문이 null이거나 이미 완료/취소된 경우
+     */
+    @Transactional
+    public void updateStatusByPaymentResult(Order order, PaymentStatus paymentStatus) {
+        if (order == null) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "주문 정보는 필수입니다.");
+        }
+
+        // 이미 완료되거나 취소된 주문인 경우 처리하지 않음
+        if (order.getStatus() == OrderStatus.COMPLETED || order.getStatus() == OrderStatus.CANCELED) {
+            return;
+        }
+
+        if (paymentStatus == PaymentStatus.SUCCESS) {
+            // 결제 성공: 주문 완료
+            order.complete();
+            orderRepository.save(order);
+        } else if (paymentStatus == PaymentStatus.FAILED) {
+            // 결제 실패: 주문 취소 (재고 원복 및 포인트 환불은 애플리케이션 레이어에서 처리)
+            order.cancel();
+            orderRepository.save(order);
+        }
+        // PENDING 상태: 상태 유지 (아무 작업도 하지 않음)
+    }
+
+    /**
+     * 주문 아이템에 대해 재고를 증가시킵니다.
+     *
+     * @param items 주문 아이템 목록
+     * @param products 상품 목록
+     */
+    private void increaseStocksForOrderItems(List<OrderItem> items, List<Product> products) {
+        Map<Long, Product> productMap = products.stream()
+            .collect(java.util.stream.Collectors.toMap(Product::getId, product -> product));
+
+        for (OrderItem item : items) {
+            Product product = productMap.get(item.getProductId());
+            if (product == null) {
+                throw new CoreException(ErrorType.NOT_FOUND,
+                    String.format("상품을 찾을 수 없습니다. (상품 ID: %d)", item.getProductId()));
+            }
+            product.increaseStock(item.getQuantity());
+        }
+    }
+}
+

apps/commerce-api/src/main/java/com/loopers/domain/payment/CardType.java

@@ -0,0 +1,11 @@
+package com.loopers.domain.payment;
+
+/**
+ * 카드 타입.
+ */
+public enum CardType {
+    SAMSUNG,
+    KB,
+    HYUNDAI
+}
+