+
+---
+
+## 🧩 4. 유스케이스 명세
+
+### 🛍 UC-01 상품 목록 조회
+| 구분 | 내용 |
+|------|------|
+| **액터** | User |
+| **기본 시나리오** | 1) 사용자가 상품 목록 페이지에 접근한다.+ * 브랜드 정보 조회 유즈케이스를 처리하는 애플리케이션 서비스입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class BrandService { + private final BrandRepository brandRepository; + + /** + * 브랜드 ID로 브랜드를 조회합니다. + * + * @param brandId 브랜드 ID + * @return 조회된 브랜드 + * @throws CoreException 브랜드를 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public Brand getBrand(Long brandId) { + return brandRepository.findById(brandId) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "브랜드를 찾을 수 없습니다.")); + } + + /** + * 브랜드 ID 목록으로 브랜드 목록을 조회합니다. + *+ * 배치 조회를 통해 N+1 쿼리 문제를 해결합니다. + *
+ * + * @param brandIds 조회할 브랜드 ID 목록 + * @return 조회된 브랜드 목록 + */ + @Transactional(readOnly = true) + public List+ * 상품 목록 조회 및 상품 정보 조회 유즈케이스를 처리하는 애플리케이션 서비스입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class CatalogFacade { + private final BrandService brandService; + private final ProductService productService; + private final ProductCacheService productCacheService; + private final ProductEventPublisher productEventPublisher; + private final RankingService rankingService; + + /** + * 상품 목록을 조회합니다. + *+ * Redis 캐시를 확인하고, 캐시에 없으면 DB에서 조회한 후 캐시에 저장합니다. + * 배치 조회를 통해 N+1 쿼리 문제를 해결합니다. + *
+ * + * @param brandId 브랜드 ID (선택) + * @param sort 정렬 기준 (latest, price_asc, likes_desc) + * @param page 페이지 번호 (0부터 시작) + * @param size 페이지당 상품 수 + * @return 상품 목록 조회 결과 + */ + public ProductInfoList getProducts(Long brandId, String sort, int page, int size) { + // sort 기본값 처리 (컨트롤러와 동일하게 "latest" 사용) + String normalizedSort = (sort != null && !sort.isBlank()) ? sort : "latest"; + + // 캐시에서 조회 시도 + ProductInfoList cachedResult = productCacheService.getCachedProductList(brandId, normalizedSort, page, size); + if (cachedResult != null) { + return cachedResult; + } + + // 캐시에 없으면 DB에서 조회 + long totalCount = productService.countAll(brandId); + List+ * Redis 캐시를 먼저 확인하고, 캐시에 없으면 DB에서 조회한 후 캐시에 저장합니다. + * 상품 조회 시 ProductViewed 이벤트를 발행하여 메트릭 집계에 사용합니다. + * 랭킹 정보도 함께 조회하여 반환합니다. + *
+ * + * @param productId 상품 ID + * @return 상품 정보와 좋아요 수, 랭킹 순위 + * @throws CoreException 상품을 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public ProductInfo getProduct(Long productId) { + // 캐시에서 조회 시도 + ProductInfo cachedResult = productCacheService.getCachedProduct(productId); + if (cachedResult != null) { + // 캐시 히트 시에도 조회 수 집계를 위해 이벤트 발행 + productEventPublisher.publish(ProductEvent.ProductViewed.from(productId)); + + // 랭킹 정보 조회 (캐시된 결과에 랭킹 정보 추가) + LocalDate today = LocalDate.now(); + Long rank = rankingService.getProductRank(productId, today); + return ProductInfo.withRank(cachedResult.productDetail(), rank); + } + + // 캐시에 없으면 DB에서 조회 + Product product = productService.getProduct(productId); + + // 브랜드 조회 + Brand brand = brandService.getBrand(product.getBrandId()); + + // ✅ Product.likeCount 필드 사용 (비동기 집계된 값) + Long likesCount = product.getLikeCount(); + + // ProductDetail 생성 (Aggregate 경계 준수: Brand 엔티티 대신 brandName만 전달) + ProductDetail productDetail = ProductDetail.from(product, brand.getName(), likesCount); + + // 랭킹 정보 조회 + LocalDate today = LocalDate.now(); + Long rank = rankingService.getProductRank(productId, today); + + // 캐시에 저장 (랭킹 정보는 제외하고 저장 - 랭킹은 실시간으로 조회) + productCacheService.cacheProduct(productId, ProductInfo.withoutRank(productDetail)); + + // ✅ 상품 조회 이벤트 발행 (메트릭 집계용) + productEventPublisher.publish(ProductEvent.ProductViewed.from(productId)); + + // 로컬 캐시의 좋아요 수 델타 적용 (DB 조회 결과에도 델타 반영) + ProductInfo deltaApplied = productCacheService.applyLikeCountDelta(ProductInfo.withoutRank(productDetail)); + return ProductInfo.withRank(deltaApplied.productDetail(), rank); + } + +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfo.java b/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfo.java new file mode 100644 index 000000000..ec634bc0a --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfo.java @@ -0,0 +1,33 @@ +package com.loopers.application.catalog; + +import com.loopers.domain.product.ProductDetail; + +/** + * 상품 상세 정보를 담는 레코드. + * + * @param productDetail 상품 상세 정보 (Product + Brand + 좋아요 수) + * @param rank 랭킹 순위 (1부터 시작, 랭킹에 없으면 null) + */ +public record ProductInfo(ProductDetail productDetail, Long rank) { + /** + * 랭킹 정보 없이 ProductInfo를 생성합니다. + * + * @param productDetail 상품 상세 정보 + * @return ProductInfo (rank는 null) + */ + public static ProductInfo withoutRank(ProductDetail productDetail) { + return new ProductInfo(productDetail, null); + } + + /** + * 랭킹 정보와 함께 ProductInfo를 생성합니다. + * + * @param productDetail 상품 상세 정보 + * @param rank 랭킹 순위 (1부터 시작, 랭킹에 없으면 null) + * @return ProductInfo + */ + public static ProductInfo withRank(ProductDetail productDetail, Long rank) { + return new ProductInfo(productDetail, rank); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfoList.java b/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfoList.java new file mode 100644 index 000000000..23f1a9345 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/catalog/ProductInfoList.java @@ -0,0 +1,46 @@ +package com.loopers.application.catalog; + +import java.util.List; + +/** + * 상품 목록 조회 결과. + * + * @param products 상품 목록 (좋아요 수 포함) + * @param totalCount 전체 상품 수 + * @param page 현재 페이지 번호 + * @param size 페이지당 상품 수 + */ +public record ProductInfoList( + List+ * 쿠폰 적용을 위한 명령 객체입니다. + *
+ * + * @param userId 사용자 ID + * @param couponCode 쿠폰 코드 + * @param subtotal 주문 소계 금액 + */ +public record ApplyCouponCommand( + Long userId, + String couponCode, + Integer subtotal +) { + public ApplyCouponCommand { + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (couponCode == null || couponCode.isBlank()) { + throw new IllegalArgumentException("couponCode는 필수입니다."); + } + if (subtotal == null || subtotal < 0) { + throw new IllegalArgumentException("subtotal은 0 이상이어야 합니다."); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponEventHandler.java b/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponEventHandler.java new file mode 100644 index 000000000..92f6b8ba3 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponEventHandler.java @@ -0,0 +1,116 @@ +package com.loopers.application.coupon; + +import com.loopers.domain.coupon.CouponEvent; +import com.loopers.domain.coupon.CouponEventPublisher; +import com.loopers.domain.order.OrderEvent; +import com.loopers.support.error.CoreException; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.orm.ObjectOptimisticLockingFailureException; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +/** + * 쿠폰 이벤트 핸들러. + *+ * 주문 생성 이벤트를 받아 쿠폰 사용 처리를 수행하는 애플리케이션 로직을 처리합니다. + *
+ *+ * DDD/EDA 관점: + *
+ * 쿠폰 코드가 있는 경우에만 쿠폰 사용 처리를 수행합니다. + * 쿠폰 적용 후 CouponApplied 이벤트를 발행하여 주문 도메인이 자신의 상태를 업데이트하도록 합니다. + *
+ * + * @param event 주문 생성 이벤트 + */ + @Transactional + public void handleOrderCreated(OrderEvent.OrderCreated event) { + // 쿠폰 코드가 없는 경우 처리하지 않음 + if (event.couponCode() == null || event.couponCode().isBlank()) { + log.debug("쿠폰 코드가 없어 쿠폰 사용 처리를 건너뜁니다. (orderId: {})", event.orderId()); + return; + } + + try { + // ✅ OrderEvent.OrderCreated를 구독하여 쿠폰 적용 Command 실행 + // 쿠폰 사용 처리 (쿠폰 사용 마킹 및 할인 금액 계산) + Integer discountAmount = couponService.applyCoupon( + new ApplyCouponCommand( + event.userId(), + event.couponCode(), + event.subtotal() + ) + ); + + // ✅ 도메인 이벤트 발행: 쿠폰이 적용되었음 (과거 사실) + // 주문 도메인이 이 이벤트를 구독하여 자신의 상태를 업데이트함 + couponEventPublisher.publish(CouponEvent.CouponApplied.of( + event.orderId(), + event.userId(), + event.couponCode(), + discountAmount + )); + + log.info("쿠폰 사용 처리 완료. (orderId: {}, couponCode: {}, discountAmount: {})", + event.orderId(), event.couponCode(), discountAmount); + } catch (CoreException e) { + // 비즈니스 예외 발생 시 실패 이벤트 발행 + String failureReason = e.getMessage() != null ? e.getMessage() : "쿠폰 적용 실패"; + log.error("쿠폰 적용 실패. (orderId: {}, couponCode: {})", + event.orderId(), event.couponCode(), e); + couponEventPublisher.publish(CouponEvent.CouponApplicationFailed.of( + event.orderId(), + event.userId(), + event.couponCode(), + failureReason + )); + throw e; + } catch (ObjectOptimisticLockingFailureException e) { + // 낙관적 락 충돌: 다른 트랜잭션이 먼저 쿠폰을 사용함 + String failureReason = "쿠폰이 이미 사용되었습니다. (동시성 충돌)"; + log.warn("쿠폰 사용 중 낙관적 락 충돌 발생. (orderId: {}, couponCode: {})", + event.orderId(), event.couponCode()); + couponEventPublisher.publish(CouponEvent.CouponApplicationFailed.of( + event.orderId(), + event.userId(), + event.couponCode(), + failureReason + )); + throw e; + } catch (Exception e) { + // 예상치 못한 오류 발생 시 실패 이벤트 발행 + String failureReason = e.getMessage() != null ? e.getMessage() : "쿠폰 적용 처리 중 오류 발생"; + log.error("쿠폰 적용 처리 중 오류 발생. (orderId: {}, couponCode: {})", + event.orderId(), event.couponCode(), e); + couponEventPublisher.publish(CouponEvent.CouponApplicationFailed.of( + event.orderId(), + event.userId(), + event.couponCode(), + failureReason + )); + throw e; + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponService.java b/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponService.java new file mode 100644 index 000000000..9a83d9df7 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponService.java @@ -0,0 +1,112 @@ +package com.loopers.application.coupon; + +import com.loopers.domain.coupon.Coupon; +import com.loopers.domain.coupon.CouponRepository; +import com.loopers.domain.coupon.UserCoupon; +import com.loopers.domain.coupon.UserCouponRepository; +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; + +/** + * 쿠폰 애플리케이션 서비스. + *+ * 쿠폰 조회, 사용 등의 애플리케이션 로직을 처리합니다. + * Repository에 의존하며 트랜잭션 관리 및 동시성 제어를 담당합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class CouponService { + private final CouponRepository couponRepository; + private final UserCouponRepository userCouponRepository; + private final CouponDiscountStrategyFactory couponDiscountStrategyFactory; + + /** + * 쿠폰을 적용하여 할인 금액을 계산하고 쿠폰을 사용 처리합니다. + *+ * 동시성 제어 전략: + *
+ * 동시성 제어 전략: + *
+ * 좋아요 추가, 삭제, 목록 조회 유즈케이스를 처리하는 애플리케이션 서비스입니다. + *
+ *+ * EDA 원칙 준수: + *
+ * 멱등성을 보장합니다. 이미 좋아요가 존재하는 경우 아무 작업도 수행하지 않습니다. + *
+ *+ * 동시성 제어 전략: + *
+ * DBA 설득 근거 (유니크 인덱스 사용): + *
+ * EDA 원칙: + *
+ * 멱등성을 보장합니다. 좋아요가 존재하지 않는 경우 아무 작업도 수행하지 않습니다. + *
+ *+ * EDA 원칙: + *
+ * 상품 정보 조회를 병렬로 처리하여 성능을 최적화합니다. + *
+ *+ * 좋아요 수 조회 전략: + *
+ * EDA 원칙: + *
+ * EDA 원칙에 따라 최소한의 UserService 의존만 사용합니다. + *
+ * + * @param userId 사용자 ID (String) + * @return 사용자 엔티티 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + private User loadUser(String userId) { + return userService.getUser(userId); + } + + /** + * 좋아요한 상품 정보. + * + * @param productId 상품 ID + * @param name 상품 이름 + * @param price 상품 가격 + * @param stock 상품 재고 + * @param brandId 브랜드 ID + * @param likesCount 좋아요 수 + */ + public record LikedProduct( + Long productId, + String name, + Integer price, + Integer stock, + Long brandId, + Long likesCount + ) { + /** + * Product로부터 LikedProduct를 생성합니다. + *+ * Product.likeCount 필드를 사용하여 좋아요 수를 가져옵니다. + *
+ * + * @param product 상품 엔티티 + * @return 생성된 LikedProduct + * @throws IllegalArgumentException product가 null인 경우 + */ + public static LikedProduct from(Product product) { + if (product == null) { + throw new IllegalArgumentException("상품은 null일 수 없습니다."); + } + return new LikedProduct( + product.getId(), + product.getName(), + product.getPrice(), + product.getStock(), + product.getBrandId(), + product.getLikeCount() // ✅ Product.likeCount 필드 사용 (이벤트 기반 실시간 집계된 값) + ); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/like/LikeService.java b/apps/commerce-api/src/main/java/com/loopers/application/like/LikeService.java new file mode 100644 index 000000000..a7c9874e6 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/like/LikeService.java @@ -0,0 +1,87 @@ +package com.loopers.application.like; + +import com.loopers.domain.like.Like; +import com.loopers.domain.like.LikeEvent; +import com.loopers.domain.like.LikeEventPublisher; +import com.loopers.domain.like.LikeRepository; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +import java.util.List; +import java.util.Optional; + +/** + * 좋아요 애플리케이션 서비스. + *+ * 좋아요 조회, 저장, 삭제 등의 애플리케이션 로직을 처리합니다. + * Repository에 의존하며 트랜잭션 관리를 담당합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class LikeService { + private final LikeRepository likeRepository; + private final LikeEventPublisher likeEventPublisher; + + /** + * 사용자 ID와 상품 ID로 좋아요를 조회합니다. + * + * @param userId 사용자 ID + * @param productId 상품 ID + * @return 조회된 좋아요를 담은 Optional + */ + @Transactional(readOnly = true) + public Optional+ * 저장 성공 시 좋아요 추가 이벤트를 발행합니다. + *
+ * + * @param like 저장할 좋아요 + * @return 저장된 좋아요 + */ + @Transactional + public Like save(Like like) { + Like savedLike = likeRepository.save(like); + + // ✅ 도메인 이벤트 발행: 좋아요가 추가되었음 (과거 사실) + likeEventPublisher.publish(LikeEvent.LikeAdded.from(savedLike)); + + return savedLike; + } + + /** + * 좋아요를 삭제합니다. + *+ * 삭제 전에 좋아요 취소 이벤트를 발행합니다. + *
+ * + * @param like 삭제할 좋아요 + */ + @Transactional + public void delete(Like like) { + // ✅ 도메인 이벤트 발행: 좋아요가 취소되었음 (과거 사실) + likeEventPublisher.publish(LikeEvent.LikeRemoved.from(like)); + + likeRepository.delete(like); + } + + /** + * 사용자 ID로 좋아요한 상품 목록을 조회합니다. + * + * @param userId 사용자 ID + * @return 좋아요 목록 + */ + @Transactional(readOnly = true) + public List+ * 주문 생성을 위한 명령 객체입니다. + *
+ * + * @param userId 사용자 ID + * @param items 주문 아이템 목록 + * @param couponCode 쿠폰 코드 (선택) + * @param subtotal 주문 소계 (쿠폰 할인 전 금액) + * @param usedPointAmount 사용할 포인트 금액 + */ +public record CreateOrderCommand( + Long userId, + List+ * 결제 완료/실패 이벤트와 쿠폰 적용 이벤트를 받아 주문 상태를 업데이트하는 애플리케이션 로직을 처리합니다. + *
+ *+ * DDD/EDA 관점: + *
+ * 트랜잭션 전략: + *
+ * 주문 상태만 CANCELED로 변경하고 OrderCanceled 이벤트를 발행합니다. + * 리소스 원복(재고, 포인트)은 OrderCanceled 이벤트를 구독하는 별도 핸들러에서 처리합니다. + *
+ *+ * 트랜잭션 전략: + *
+ * DDD/EDA 관점: + *
+ * 쿠폰 도메인에서 쿠폰이 적용되었다는 이벤트를 받아 주문 도메인이 자신의 상태를 업데이트합니다. + *
+ * + * @param event 쿠폰 적용 이벤트 + */ + @Transactional + public void handleCouponApplied(CouponEvent.CouponApplied event) { + try { + // 주문에 할인 금액 적용 (totalAmount 업데이트) + orderService.applyCouponDiscount(event.orderId(), event.discountAmount()); + + log.info("쿠폰 할인 금액이 주문에 적용되었습니다. (orderId: {}, couponCode: {}, discountAmount: {})", + event.orderId(), event.couponCode(), event.discountAmount()); + } catch (Exception e) { + // 주문 업데이트 실패는 로그만 기록 (쿠폰은 이미 적용되었으므로) + log.error("쿠폰 적용 이벤트 처리 중 오류 발생. (orderId: {}, couponCode: {})", + event.orderId(), event.couponCode(), e); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/order/OrderService.java b/apps/commerce-api/src/main/java/com/loopers/application/order/OrderService.java new file mode 100644 index 000000000..eb71438ab --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/order/OrderService.java @@ -0,0 +1,334 @@ +package com.loopers.application.order; + +import com.loopers.domain.order.Order; +import com.loopers.domain.order.OrderEvent; +import com.loopers.domain.order.OrderEventPublisher; +import com.loopers.domain.order.OrderItem; +import com.loopers.domain.order.OrderRepository; +import com.loopers.domain.order.OrderStatus; +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; + +/** + * 주문 애플리케이션 서비스. + *+ * 주문의 기본 CRUD 및 상태 변경을 담당하는 애플리케이션 서비스입니다. + * Repository에 의존하며 트랜잭션 관리를 담당합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class OrderService { + + private final OrderRepository orderRepository; + private final OrderEventPublisher orderEventPublisher; + + /** + * 주문을 저장합니다. + * + * @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+ * 주문 생성 후 OrderCreated 이벤트를 발행합니다. + *
+ * + * @param command 주문 생성 명령 + * @return 생성된 주문 + */ + @Transactional + public Order create(CreateOrderCommand command) { + // 쿠폰이 있어도 discountAmount는 0으로 설정 (CouponEventHandler가 이벤트를 받아 쿠폰 적용) + Order order = Order.of(command.userId(), command.items(), command.couponCode(), 0); + Order savedOrder = orderRepository.save(order); + + // ✅ 도메인 이벤트 발행: 주문이 생성되었음 (과거 사실) + orderEventPublisher.publish(OrderEvent.OrderCreated.from(savedOrder, command.subtotal(), command.usedPointAmount())); + + return savedOrder; + } + + /** + * 주문에 쿠폰 할인 금액을 적용합니다. + *+ * 이벤트 핸들러에서 쿠폰 적용 후 호출됩니다. + *
+ * + * @param orderId 주문 ID + * @param discountAmount 할인 금액 + * @return 업데이트된 주문 + * @throws CoreException 주문을 찾을 수 없거나 할인을 적용할 수 없는 상태인 경우 + */ + @Transactional + public Order applyCouponDiscount(Long orderId, Integer discountAmount) { + Order order = getById(orderId); + order.applyDiscount(discountAmount); + return orderRepository.save(order); + } + + /** + * 주문 아이템 목록으로부터 소계 금액을 계산합니다. + * + * @param orderItems 주문 아이템 목록 + * @return 계산된 소계 금액 + */ + private Integer calculateSubtotal(List+ * 주문 완료 후 OrderCompleted 이벤트를 발행합니다. + *
+ * + * @param orderId 주문 ID + * @return 완료된 주문 + * @throws CoreException 주문을 찾을 수 없는 경우 + */ + @Transactional + public Order completeOrder(Long orderId) { + Order order = getById(orderId); + order.complete(); + Order savedOrder = orderRepository.save(order); + + // ✅ 도메인 이벤트 발행: 주문이 완료되었음 (과거 사실) + orderEventPublisher.publish(OrderEvent.OrderCompleted.from(savedOrder)); + + return savedOrder; + } + + /** + * 주문을 취소 상태로 변경합니다. + *+ * 주문 취소 후 OrderCanceled 이벤트를 발행합니다. + * 리소스 원복(재고, 포인트)은 별도 이벤트 핸들러에서 처리합니다. + *
+ * + * @param orderId 주문 ID + * @param reason 취소 사유 + * @param refundPointAmount 환불할 포인트 금액 + * @return 취소된 주문 + * @throws CoreException 주문을 찾을 수 없는 경우 + */ + @Transactional + public Order cancelOrder(Long orderId, String reason, Long refundPointAmount) { + Order order = getById(orderId); + order.cancel(); + Order savedOrder = orderRepository.save(order); + + // ✅ 도메인 이벤트 발행: 주문이 취소되었음 (과거 사실) + orderEventPublisher.publish(OrderEvent.OrderCanceled.from(savedOrder, reason, refundPointAmount)); + + return savedOrder; + } + + /** + * 주문을 취소 상태로 변경하고 재고를 원복하며 포인트를 환불합니다. + *+ * 도메인 로직만 처리합니다. 사용자 조회, 상품 조회, Payment 조회는 애플리케이션 레이어에서 처리합니다. + *
+ * + * @param order 주문 엔티티 + * @param products 주문 아이템에 해당하는 상품 목록 (락이 이미 획득된 상태) + * @param user 사용자 엔티티 (락이 이미 획득된 상태) + * @param refundPointAmount 환불할 포인트 금액 + * @throws CoreException 주문 또는 사용자 정보가 null인 경우 + */ + @Transactional + public void cancelOrder(Order order, List+ * 주문 상태 변경 후 해당 이벤트(OrderCompleted 또는 OrderCanceled)를 발행합니다. + *
+ *+ * 도메인 로직만 처리합니다. 사용자 조회, 트랜잭션 관리, 로깅은 애플리케이션 레이어에서 처리합니다. + *
+ * + * @param order 주문 엔티티 + * @param paymentStatus 결제 상태 + * @param reason 취소 사유 (FAILED인 경우 필수, 그 외 null 가능) + * @param refundPointAmount 환불할 포인트 금액 (FAILED인 경우 필수, 그 외 null 가능) + * @throws CoreException 주문이 null이거나 이미 완료/취소된 경우 + */ + @Transactional + public void updateStatusByPaymentResult(Order order, PaymentStatus paymentStatus, String reason, Long refundPointAmount) { + if (order == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "주문 정보는 필수입니다."); + } + + // 이미 완료되거나 취소된 주문인 경우 처리하지 않음 + if (order.isCompleted() || order.isCanceled()) { + return; + } + + if (paymentStatus == PaymentStatus.SUCCESS) { + // 결제 성공: 주문 완료 + order.complete(); + Order savedOrder = orderRepository.save(order); + + // ✅ 도메인 이벤트 발행: 주문이 완료되었음 (과거 사실) + orderEventPublisher.publish(OrderEvent.OrderCompleted.from(savedOrder)); + } else if (paymentStatus == PaymentStatus.FAILED) { + // 결제 실패: 주문 취소 (재고 원복 및 포인트 환불은 이벤트 핸들러에서 처리) + if (reason == null || reason.isBlank()) { + throw new CoreException(ErrorType.BAD_REQUEST, "결제 실패 시 취소 사유는 필수입니다."); + } + if (refundPointAmount == null || refundPointAmount < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "환불할 포인트 금액은 0 이상이어야 합니다."); + } + + order.cancel(); + Order savedOrder = orderRepository.save(order); + + // ✅ 도메인 이벤트 발행: 주문이 취소되었음 (과거 사실) + orderEventPublisher.publish(OrderEvent.OrderCanceled.from(savedOrder, reason, refundPointAmount)); + } + // PENDING 상태: 상태 유지 (아무 작업도 하지 않음) + } + + /** + * 주문 아이템에 대해 재고를 증가시킵니다. + * + * @param items 주문 아이템 목록 + * @param products 상품 목록 + */ + private void increaseStocksForOrderItems(List+ * ApplicationEvent를 구독하여 외부 시스템(Kafka)으로 전송해야 하는 이벤트를 + * Transactional Outbox Pattern을 통해 Outbox에 저장합니다. + *
+ *+ * 표준 패턴: + *
+ * 처리 이벤트: + *
+ * 도메인 트랜잭션과 같은 트랜잭션에서 Outbox에 이벤트를 저장합니다. + * Application 레이어에 위치하여 비즈니스 로직(이벤트 저장 결정)을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class OutboxEventService { + + private final OutboxEventRepository outboxEventRepository; + private final ObjectMapper objectMapper; + + /** + * Kafka로 전송할 이벤트를 Outbox에 저장합니다. + *+ * 도메인 트랜잭션과 같은 트랜잭션에서 실행되어야 합니다. + * 집계 ID별로 순차적인 버전을 자동으로 부여합니다. + *
+ *+ * 버전 충돌 시 최대 3회까지 재시도합니다. + * 유니크 제약 조건을 통해 경쟁 조건을 감지하고 재시도합니다. + *
+ * + * @param eventType 이벤트 타입 (예: "OrderCreated", "LikeAdded") + * @param aggregateId 집계 ID (예: orderId, productId) + * @param aggregateType 집계 타입 (예: "Order", "Product") + * @param event 이벤트 객체 + * @param topic Kafka 토픽 이름 + * @param partitionKey 파티션 키 + */ + @Transactional + public void saveEvent( + String eventType, + String aggregateId, + String aggregateType, + Object event, + String topic, + String partitionKey + ) { + int maxRetries = 3; + for (int i = 0; i < maxRetries; i++) { + try { + String eventId = UUID.randomUUID().toString(); + String payload = objectMapper.writeValueAsString(event); + + // 집계 ID별 최신 버전 조회 후 +1 + Long latestVersion = outboxEventRepository.findLatestVersionByAggregateId(aggregateId, aggregateType); + Long nextVersion = latestVersion + 1L; + + OutboxEvent outboxEvent = OutboxEvent.builder() + .eventId(eventId) + .eventType(eventType) + .aggregateId(aggregateId) + .aggregateType(aggregateType) + .payload(payload) + .topic(topic) + .partitionKey(partitionKey) + .version(nextVersion) + .build(); + + outboxEventRepository.save(outboxEvent); + log.debug("Outbox 이벤트 저장: eventType={}, aggregateId={}, topic={}, version={}", + eventType, aggregateId, topic, nextVersion); + return; // 성공 + } catch (DataIntegrityViolationException e) { + // 유니크 제약 조건 위반 (버전 충돌) + if (i == maxRetries - 1) { + log.error("Outbox 이벤트 저장 실패 (최대 재시도 횟수 초과): eventType={}, aggregateId={}, retryCount={}", + eventType, aggregateId, i + 1, e); + throw new RuntimeException("Outbox 이벤트 저장 실패: 버전 충돌", e); + } + log.warn("Outbox 이벤트 저장 재시도: eventType={}, aggregateId={}, retryCount={}", + eventType, aggregateId, i + 1); + } catch (Exception e) { + log.error("Outbox 이벤트 저장 실패: eventType={}, aggregateId={}", + eventType, aggregateId, e); + throw new RuntimeException("Outbox 이벤트 저장 실패", e); + } + } + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentEventHandler.java b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentEventHandler.java new file mode 100644 index 000000000..dc8b250a1 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentEventHandler.java @@ -0,0 +1,234 @@ +package com.loopers.application.payment; + +import com.loopers.domain.coupon.CouponEvent; +import com.loopers.domain.payment.CardType; +import com.loopers.domain.payment.Payment; +import com.loopers.domain.payment.PaymentEvent; +import com.loopers.domain.payment.PaymentGateway; +import com.loopers.domain.payment.PaymentRequest; +import com.loopers.domain.payment.PaymentRequestResult; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; +import org.springframework.transaction.support.TransactionSynchronization; +import org.springframework.transaction.support.TransactionSynchronizationManager; + +import java.time.LocalDateTime; + +/** + * 결제 이벤트 핸들러. + *+ * 결제 요청 이벤트를 받아 Payment 생성 및 PG 결제 요청 처리를 수행하는 애플리케이션 로직을 처리합니다. + *
+ *+ * DDD/EDA 관점: + *
+ * 결제 금액이 0인 경우 PG 요청 없이 바로 완료 처리합니다. + *
+ * + * @param event 결제 요청 이벤트 + */ + @Transactional + public void handlePaymentRequested(PaymentEvent.PaymentRequested event) { + try { + // Payment 생성 + CardType cardTypeEnum = (event.cardType() != null && !event.cardType().isBlank()) + ? convertCardType(event.cardType()) + : null; + + Payment payment = paymentService.create( + event.orderId(), + event.userEntityId(), + event.totalAmount(), + event.usedPointAmount(), + cardTypeEnum, + event.cardNo(), + LocalDateTime.now() + ); + + // 결제 금액이 0인 경우 (포인트+쿠폰으로 전액 결제) + Long paidAmount = event.totalAmount() - event.usedPointAmount(); + if (paidAmount.equals(0L)) { + // PG 요청 없이 바로 완료 (PaymentCompleted 이벤트 발행) + paymentService.toSuccess(payment.getId(), LocalDateTime.now(), null); + log.info("포인트+쿠폰으로 전액 결제 완료. (orderId: {})", event.orderId()); + return; + } + + // PG 결제가 필요한 경우 + if (event.cardType() == null || event.cardType().isBlank() || + event.cardNo() == null || event.cardNo().isBlank()) { + log.error("카드 정보가 없어 PG 결제를 진행할 수 없습니다. (orderId: {})", event.orderId()); + throw new CoreException( + ErrorType.BAD_REQUEST, + "포인트와 쿠폰만으로 결제할 수 없습니다. 카드 정보를 입력해주세요."); + } + + // PG 결제 요청 (트랜잭션 커밋 후 별도 트랜잭션에서 처리) + TransactionSynchronizationManager.registerSynchronization( + new TransactionSynchronization() { + @Override + public void afterCommit() { + try { + // 쿠폰 할인이 적용된 후의 최신 Payment 정보 조회 + // 쿠폰 할인이 적용되면 Payment.applyCouponDiscount에서 paidAmount가 재계산됨 + Payment payment = paymentService.getPaymentByOrderId(event.orderId()) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, + String.format("주문 ID에 해당하는 결제를 찾을 수 없습니다. (orderId: %d)", event.orderId()))); + + // 이미 완료된 결제는 PG 요청 불필요 + if (payment.isCompleted()) { + log.info("결제가 이미 완료되어 PG 요청을 건너뜁니다. (orderId: {})", event.orderId()); + return; + } + + // 최신 paidAmount 사용 (쿠폰 할인 적용 후 금액) + Long paidAmount = payment.getPaidAmount(); + + // paidAmount가 0이면 PG 요청 불필요 (이미 완료 처리됨) + if (paidAmount == 0L) { + log.info("결제 금액이 0이어서 PG 요청을 건너뜁니다. (orderId: {})", event.orderId()); + return; + } + + // ✅ PaymentEvent.PaymentRequested를 구독하여 결제 요청 Command 실행 + String callbackUrl = generateCallbackUrl(event.orderId()); + // ✅ RequestPaymentCommand (PaymentRequestCommand) 생성 및 실행 + PaymentRequestCommand command = new PaymentRequestCommand( + event.userId(), + event.orderId(), + event.cardType(), + event.cardNo(), + paidAmount, + callbackUrl + ); + // 도메인 계층으로 변환하여 PG 결제 요청 + PaymentRequest paymentRequest = command.toPaymentRequest(); + PaymentRequestResult result = paymentGateway.requestPayment(paymentRequest); + + if (result instanceof PaymentRequestResult.Success success) { + // 결제 성공: PaymentService.toSuccess가 PaymentCompleted 이벤트를 발행하고, + // OrderEventHandler가 이를 받아 주문 상태를 COMPLETED로 변경 + paymentService.getPaymentByOrderId(event.orderId()).ifPresent(p -> { + if (p.isPending()) { + paymentService.toSuccess(p.getId(), LocalDateTime.now(), success.transactionKey()); + } + }); + log.info("PG 결제 요청 성공. (orderId: {}, transactionKey: {})", + event.orderId(), success.transactionKey()); + } else if (result instanceof PaymentRequestResult.Failure failure) { + // PG 요청 실패: PaymentService.toFailed가 PaymentFailed 이벤트를 발행하고, + // OrderEventHandler가 이를 받아 주문 취소 처리 + paymentService.getPaymentByOrderId(event.orderId()).ifPresent(p -> { + if (p.isPending()) { + paymentService.toFailed(p.getId(), failure.message(), + LocalDateTime.now(), null); + } + }); + log.warn("PG 결제 요청 실패. (orderId: {}, errorCode: {}, message: {})", + event.orderId(), failure.errorCode(), failure.message()); + } + } catch (Exception e) { + log.error("PG 결제 요청 중 예외 발생. 주문은 PENDING 상태로 유지됩니다. (orderId: {})", + event.orderId(), e); + } + } + } + ); + + log.info("결제 요청 처리 완료. (orderId: {}, totalAmount: {}, usedPointAmount: {})", + event.orderId(), event.totalAmount(), event.usedPointAmount()); + } catch (Exception e) { + log.error("결제 요청 처리 중 오류 발생. (orderId: {})", event.orderId(), e); + throw e; + } + } + + /** + * 쿠폰 적용 이벤트를 처리하여 결제 금액을 업데이트합니다. + *+ * 쿠폰 할인이 적용된 후 Order의 totalAmount가 업데이트되면, + * Payment의 totalAmount도 동기화하기 위해 호출됩니다. + *
+ *+ * EDA 원칙: + *
+ * PG 결제 요청에 필요한 정보를 담는 명령 모델입니다. + *
+ * + * @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은 필수입니다."); + } + } + + /** + * 도메인 계층의 PaymentRequest로 변환합니다. + *+ * 애플리케이션 계층의 Command를 도메인 계층의 Value Object로 변환하여 + * 도메인 서비스에 전달합니다. + *
+ * + * @return 도메인 계층의 PaymentRequest + */ + public PaymentRequest toPaymentRequest() { + return new PaymentRequest( + userId, + orderId, + cardType, + cardNo, + amount, + callbackUrl + ); + } + + @Override + public String toString() { + String maskedCardNo = cardNo != null && cardNo.length() > 4 + ? "****" + cardNo.substring(cardNo.length() - 4) + : "****"; + return "PaymentRequestCommand[userId=%s, orderId=%d, cardType=%s, cardNo=%s, amount=%d, callbackUrl=%s]" + .formatted(userId, orderId, cardType, maskedCardNo, amount, callbackUrl); + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentService.java b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentService.java new file mode 100644 index 000000000..5802d44a3 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentService.java @@ -0,0 +1,482 @@ +package com.loopers.application.payment; + +import com.loopers.domain.payment.*; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +import java.time.Duration; +import java.time.LocalDateTime; +import java.util.List; +import java.util.Optional; + +/** + * 결제 애플리케이션 서비스. + *+ * 결제의 생성, 조회, 상태 변경 및 PG 연동을 담당하는 애플리케이션 서비스입니다. + * 도메인 로직은 Payment 엔티티에 위임하며, Service는 조회/저장, 트랜잭션 관리 및 PG 연동을 담당합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class PaymentService { + + private final PaymentRepository paymentRepository; + private final PaymentGateway paymentGateway; + private final PaymentEventPublisher paymentEventPublisher; + + @Value("${payment.callback.base-url}") + private String callbackBaseUrl; + + /** + * 카드 결제를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param cardType 카드 타입 + * @param cardNo 카드 번호 + * @param amount 결제 금액 + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment + */ + @Transactional + public Payment create( + Long orderId, + Long userId, + CardType cardType, + String cardNo, + Long amount, + LocalDateTime requestedAt + ) { + Payment payment = Payment.of(orderId, userId, cardType, cardNo, amount, requestedAt); + return paymentRepository.save(payment); + } + + /** + * 포인트 결제를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param totalAmount 총 결제 금액 + * @param usedPoint 사용 포인트 + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment + */ + @Transactional + public Payment create( + Long orderId, + Long userId, + Long totalAmount, + Long usedPoint, + LocalDateTime requestedAt + ) { + Payment payment = Payment.of(orderId, userId, totalAmount, usedPoint, requestedAt); + return paymentRepository.save(payment); + } + + /** + * 포인트와 카드 혼합 결제를 생성합니다. + *+ * 포인트와 쿠폰 할인을 적용한 후 남은 금액을 카드로 결제하는 경우 사용합니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param totalAmount 총 결제 금액 + * @param usedPoint 사용 포인트 + * @param cardType 카드 타입 (paidAmount > 0일 때만 필수) + * @param cardNo 카드 번호 (paidAmount > 0일 때만 필수) + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment + */ + @Transactional + public Payment create( + Long orderId, + Long userId, + Long totalAmount, + Long usedPoint, + CardType cardType, + String cardNo, + LocalDateTime requestedAt + ) { + Payment payment = Payment.of(orderId, userId, totalAmount, usedPoint, cardType, cardNo, requestedAt); + return paymentRepository.save(payment); + } + + /** + * 결제를 SUCCESS 상태로 전이합니다. + *+ * 멱등성 보장: 이미 SUCCESS 상태인 경우 아무 작업도 하지 않습니다. + * 결제 완료 후 PaymentCompleted 이벤트를 발행합니다. + *
+ * + * @param paymentId 결제 ID + * @param completedAt PG 완료 시각 + * @param transactionKey 트랜잭션 키 (null 가능) + * @throws CoreException 결제를 찾을 수 없는 경우 + */ + @Transactional + public void toSuccess(Long paymentId, LocalDateTime completedAt, String transactionKey) { + Payment payment = getPayment(paymentId); + + // 이미 SUCCESS 상태인 경우 이벤트 발행하지 않음 (멱등성) + if (payment.isCompleted()) { + return; + } + + payment.toSuccess(completedAt); // Entity에 위임 + Payment savedPayment = paymentRepository.save(payment); + + // ✅ 도메인 이벤트 발행: 결제가 완료되었음 (과거 사실) + paymentEventPublisher.publish(PaymentEvent.PaymentCompleted.from(savedPayment, transactionKey)); + } + + /** + * 결제를 FAILED 상태로 전이합니다. + *+ * 멱등성 보장: 이미 FAILED 상태인 경우 아무 작업도 하지 않습니다. + * 결제 실패 후 PaymentFailed 이벤트를 발행합니다. + *
+ * + * @param paymentId 결제 ID + * @param failureReason 실패 사유 + * @param completedAt PG 완료 시각 + * @param transactionKey 트랜잭션 키 (null 가능) + * @throws CoreException 결제를 찾을 수 없는 경우 + */ + @Transactional + public void toFailed(Long paymentId, String failureReason, LocalDateTime completedAt, String transactionKey) { + Payment payment = getPayment(paymentId); + + // 이미 FAILED 상태인 경우 이벤트 발행하지 않음 (멱등성) + if (payment.getStatus() == PaymentStatus.FAILED) { + return; + } + + payment.toFailed(failureReason, completedAt); // Entity에 위임 + Payment savedPayment = paymentRepository.save(payment); + + // ✅ 도메인 이벤트 발행: 결제가 실패했음 (과거 사실) + paymentEventPublisher.publish(PaymentEvent.PaymentFailed.from(savedPayment, failureReason, transactionKey)); + } + + /** + * 결제 ID로 결제를 조회합니다. + * + * @param paymentId 결제 ID + * @return 조회된 Payment + * @throws CoreException 결제를 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public Payment getPayment(Long paymentId) { + return paymentRepository.findById(paymentId) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "결제를 찾을 수 없습니다.")); + } + + /** + * 주문 ID로 결제를 조회합니다. + * + * @param orderId 주문 ID + * @return 조회된 Payment (없으면 Optional.empty()) + */ + @Transactional(readOnly = true) + public Optional+ * 결제를 생성하고 PG에 결제 요청을 전송합니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (String - User.userId) + * @param userEntityId 사용자 엔티티 ID (Long - User.id) + * @param cardType 카드 타입 + * @param cardNo 카드 번호 + * @param amount 결제 금액 + * @return 결제 요청 결과 + */ + @Transactional + public PaymentRequestResult requestPayment( + Long orderId, + String userId, + Long userEntityId, + String cardType, + String cardNo, + Long amount + ) { + // 1. 카드 번호 유효성 검증 + validateCardNo(cardNo); + + // 2. 결제 생성 (User 엔티티의 id 사용) + Payment payment = create( + orderId, + userEntityId, + convertCardType(cardType), + cardNo, + amount, + LocalDateTime.now() + ); + + // 3. 결제 요청 명령 생성 (애플리케이션 계층) + String callbackUrl = generateCallbackUrl(orderId); + PaymentRequestCommand command = new PaymentRequestCommand( + userId, + orderId, + cardType, + cardNo, + amount, + callbackUrl + ); + + // 4. 도메인 계층으로 변환하여 PG 결제 요청 전송 + PaymentRequest paymentRequest = command.toPaymentRequest(); + PaymentRequestResult result = paymentGateway.requestPayment(paymentRequest); + + // 5. 결과 처리 + if (result instanceof PaymentRequestResult.Success success) { + log.info("PG 결제 요청 성공. (orderId: {}, transactionKey: {})", orderId, success.transactionKey()); + return result; + } else if (result instanceof PaymentRequestResult.Failure failure) { + // 실패 분류 + PaymentFailureType failureType = PaymentFailureType.classify(failure.errorCode()); + if (failureType == PaymentFailureType.BUSINESS_FAILURE) { + // 비즈니스 실패: 결제 상태를 FAILED로 변경 + toFailed(payment.getId(), failure.message(), LocalDateTime.now(), null); + } + // 외부 시스템 장애는 PENDING 상태 유지 + log.warn("PG 결제 요청 실패. (orderId: {}, errorCode: {}, message: {})", + orderId, failure.errorCode(), failure.message()); + return result; + } + + throw new IllegalStateException("알 수 없는 결제 결과 타입: " + result.getClass().getName()); + } + + /** + * 결제 상태를 조회합니다. + * + * @param userId 사용자 ID + * @param orderId 주문 ID + * @return 결제 상태 + */ + @Transactional(readOnly = true) + public PaymentStatus getPaymentStatus(String userId, Long orderId) { + return paymentGateway.getPaymentStatus(userId, orderId); + } + + /** + * PG 콜백을 처리합니다. + * + * @param orderId 주문 ID + * @param transactionKey 트랜잭션 키 + * @param status 결제 상태 + * @param reason 실패 사유 (실패 시) + */ + @Transactional + public void handleCallback(Long orderId, String transactionKey, PaymentStatus status, String reason) { + Optional+ * 타임아웃 발생 후 실제 결제 상태를 확인하여 결제 상태를 업데이트합니다. + *
+ * + * @param userId 사용자 ID + * @param orderId 주문 ID + * @param delayDuration 대기 시간 (PG 처리 시간 고려) + */ + public void recoverAfterTimeout(String userId, Long orderId, Duration delayDuration) { + try { + // 잠시 대기 후 상태 확인 (PG 처리 시간 고려) + if (delayDuration != null && !delayDuration.isZero()) { + Thread.sleep(delayDuration.toMillis()); + } + + // 결제 상태 조회 + PaymentStatus status = getPaymentStatus(userId, orderId); + Optional+ * 쿠폰 할인이 적용된 후 Order의 totalAmount가 업데이트되면, + * Payment의 totalAmount도 동기화하기 위해 호출됩니다. + *
+ * + * @param orderId 주문 ID + * @param discountAmount 할인 금액 + * @throws CoreException 결제를 찾을 수 없거나 할인 금액이 유효하지 않은 경우 + */ + @Transactional + public void applyCouponDiscount(Long orderId, Integer discountAmount) { + Payment payment = getPaymentByOrderId(orderId) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, + String.format("주문 ID에 해당하는 결제를 찾을 수 없습니다. (orderId: %d)", orderId))); + + payment.applyCouponDiscount(discountAmount); + paymentRepository.save(payment); + } + + // 내부 헬퍼 메서드들 + + private CardType convertCardType(String cardType) { + try { + return CardType.valueOf(cardType.toUpperCase()); + } catch (IllegalArgumentException e) { + throw new CoreException(ErrorType.BAD_REQUEST, + String.format("잘못된 카드 타입입니다. (cardType: %s)", cardType)); + } + } + + private String generateCallbackUrl(Long orderId) { + return String.format("%s/api/v1/orders/%d/callback", callbackBaseUrl, orderId); + } + + /** + * 카드 번호 유효성 검증을 수행합니다. + * + * @param cardNo 카드 번호 + * @throws CoreException 유효하지 않은 카드 번호인 경우 + */ + private void validateCardNo(String cardNo) { + if (cardNo == null || cardNo.isEmpty()) { + throw new CoreException(ErrorType.BAD_REQUEST, "카드 번호는 필수입니다."); + } + + // 공백/하이픈 제거 및 정규화 + String normalized = cardNo.replaceAll("[\\s-]", ""); + + // 길이 검증 (13-19자리) + if (normalized.length() < 13 || normalized.length() > 19) { + throw new CoreException(ErrorType.BAD_REQUEST, + String.format("유효하지 않은 카드 번호 길이입니다. (길이: %d, 요구사항: 13-19자리)", normalized.length())); + } + + // 숫자만 포함하는지 검증 + if (!normalized.matches("\\d+")) { + throw new CoreException(ErrorType.BAD_REQUEST, "카드 번호는 숫자만 포함해야 합니다."); + } + + // Luhn 알고리즘 체크섬 검증 + if (!isValidLuhn(normalized)) { + throw new CoreException(ErrorType.BAD_REQUEST, "유효하지 않은 카드 번호입니다. (Luhn 알고리즘 검증 실패)"); + } + } + + /** + * Luhn 알고리즘을 사용하여 카드 번호의 체크섬을 검증합니다. + * + * @param cardNo 정규화된 카드 번호 (숫자만 포함) + * @return 유효한 경우 true, 그렇지 않으면 false + */ + private boolean isValidLuhn(String cardNo) { + int sum = 0; + boolean alternate = false; + + // 오른쪽에서 왼쪽으로 순회 + for (int i = cardNo.length() - 1; i >= 0; i--) { + int digit = Character.getNumericValue(cardNo.charAt(i)); + + if (alternate) { + digit *= 2; + if (digit > 9) { + digit = (digit % 10) + 1; + } + } + + sum += digit; + alternate = !alternate; + } + + return (sum % 10) == 0; + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/product/DeductStockCommand.java b/apps/commerce-api/src/main/java/com/loopers/application/product/DeductStockCommand.java new file mode 100644 index 000000000..343292349 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/product/DeductStockCommand.java @@ -0,0 +1,27 @@ +package com.loopers.application.product; + +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; + +/** + * 재고 차감 명령. + *+ * 재고 차감을 위한 명령 객체입니다. + *
+ * + * @param productId 상품 ID + * @param quantity 차감할 수량 + */ +public record DeductStockCommand( + Long productId, + Integer quantity +) { + public DeductStockCommand { + if (productId == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "상품 ID는 필수입니다."); + } + if (quantity == null || quantity <= 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "차감 수량은 1 이상이어야 합니다."); + } + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/application/product/ProductCacheService.java b/apps/commerce-api/src/main/java/com/loopers/application/product/ProductCacheService.java new file mode 100644 index 000000000..32c4f915b --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/product/ProductCacheService.java @@ -0,0 +1,275 @@ +package com.loopers.application.product; + +import com.loopers.application.catalog.ProductInfo; +import com.loopers.application.catalog.ProductInfoList; +import com.loopers.cache.CacheKey; +import com.loopers.cache.CacheTemplate; +import com.loopers.cache.SimpleCacheKey; +import com.loopers.domain.product.ProductDetail; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; + +import java.time.Duration; +import java.util.List; +import java.util.Optional; +import java.util.concurrent.ConcurrentHashMap; +import java.util.stream.Collectors; + +/** + * 상품 조회 결과를 캐시하는 서비스. + *+ * 상품 목록 조회와 상품 상세 조회 결과를 캐시하여 성능을 향상시킵니다. + *
+ *+ * 캐시 전략: + *
+ * 좋아요 추가/취소 시 델타를 저장하고, 캐시 조회 시 델타를 적용하여 반환합니다. + * 배치 집계 후에는 초기화됩니다. + *
+ */ + private final ConcurrentHashMap+ * 페이지 번호와 관계없이 캐시를 확인하고, 캐시에 있으면 반환합니다. + * 캐시에 없으면 null을 반환하여 DB 조회를 유도합니다. + *
+ *+ * 로컬 캐시의 좋아요 수 델타를 적용하여 반환합니다. + *
+ * + * @param brandId 브랜드 ID (null이면 전체) + * @param sort 정렬 기준 + * @param page 페이지 번호 + * @param size 페이지당 상품 수 + * @return 캐시된 상품 목록 (없으면 null) + */ + public ProductInfoList getCachedProductList(Long brandId, String sort, int page, int size) { + String cacheKey = buildListCacheKey(brandId, sort, page, size); + CacheKey+ * 첫 3페이지인 경우에만 캐시에 저장합니다. + *
+ * + * @param brandId 브랜드 ID (null이면 전체) + * @param sort 정렬 기준 + * @param page 페이지 번호 + * @param size 페이지당 상품 수 + * @param productInfoList 캐시할 상품 목록 + */ + public void cacheProductList(Long brandId, String sort, int page, int size, ProductInfoList productInfoList) { + // 3페이지까지만 캐시 저장 + if (page > 2) { + return; + } + + String cacheKey = buildListCacheKey(brandId, sort, page, size); + CacheKey+ * 로컬 캐시의 좋아요 수 델타를 적용하여 반환합니다. + *
+ * + * @param productId 상품 ID + * @return 캐시된 상품 정보 (없으면 null) + */ + public ProductInfo getCachedProduct(Long productId) { + String cacheKey = buildDetailCacheKey(productId); + CacheKey+ * 좋아요 추가 시 호출됩니다. + *
+ * + * @param productId 상품 ID + */ + public void incrementLikeCountDelta(Long productId) { + likeCountDeltaCache.merge(productId, 1L, Long::sum); + } + + /** + * 좋아요 수 델타를 감소시킵니다. + *+ * 좋아요 취소 시 호출됩니다. + *
+ * + * @param productId 상품 ID + */ + public void decrementLikeCountDelta(Long productId) { + likeCountDeltaCache.merge(productId, -1L, Long::sum); + } + + /** + * 모든 좋아요 수 델타를 초기화합니다. + *+ * 배치 집계 후 호출됩니다. + *
+ */ + public void clearAllLikeCountDelta() { + likeCountDeltaCache.clear(); + } + + /** + * 상품 목록에 좋아요 수 델타를 적용합니다. + *+ * DB에서 직접 조회한 결과에도 델타를 적용하기 위해 public으로 제공합니다. + *
+ * + * @param productInfoList 상품 목록 + * @return 델타가 적용된 상품 목록 + */ + public ProductInfoList applyLikeCountDelta(ProductInfoList productInfoList) { + if (likeCountDeltaCache.isEmpty()) { + return productInfoList; + } + + List+ * DB에서 직접 조회한 결과에도 델타를 적용하기 위해 public으로 제공합니다. + *
+ * + * @param productInfo 상품 정보 + * @return 델타가 적용된 상품 정보 + */ + public ProductInfo applyLikeCountDelta(ProductInfo productInfo) { + Long delta = likeCountDeltaCache.get(productInfo.productDetail().getId()); + if (delta == null || delta == 0) { + return productInfo; + } + + ProductDetail originalDetail = productInfo.productDetail(); + Long updatedLikesCount = originalDetail.getLikesCount() + delta; + + ProductDetail updatedDetail = ProductDetail.of( + originalDetail.getId(), + originalDetail.getName(), + originalDetail.getPrice(), + originalDetail.getStock(), + originalDetail.getBrandId(), + originalDetail.getBrandName(), + updatedLikesCount + ); + + return ProductInfo.withoutRank(updatedDetail); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/product/ProductEventHandler.java b/apps/commerce-api/src/main/java/com/loopers/application/product/ProductEventHandler.java new file mode 100644 index 000000000..3cba362e3 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/product/ProductEventHandler.java @@ -0,0 +1,214 @@ +package com.loopers.application.product; + +import com.loopers.domain.like.LikeEvent; +import com.loopers.domain.order.OrderEvent; +import com.loopers.domain.product.Product; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +/** + * 상품 이벤트 핸들러. + *+ * 좋아요 추가/취소 이벤트와 주문 생성/취소 이벤트를 받아 상품의 좋아요 수 및 재고를 업데이트하는 애플리케이션 로직을 처리합니다. + *
+ *+ * DDD/EDA 관점: + *
+ * EDA 원칙: + *
+ * EDA 원칙: + *
+ * 동시성 제어: + *
+ * 동시성 제어: + *
+ * 상품 조회, 저장 등의 애플리케이션 로직을 처리합니다. + * Repository에 의존하며 트랜잭션 관리를 담당합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class ProductService { + private final ProductRepository productRepository; + + /** + * 상품 ID로 상품을 조회합니다. + * + * @param productId 조회할 상품 ID + * @return 조회된 상품 + * @throws CoreException 상품을 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public Product getProduct(Long productId) { + return productRepository.findById(productId) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, + String.format("상품을 찾을 수 없습니다. (상품 ID: %d)", productId))); + } + + /** + * 상품 ID 목록으로 상품 목록을 조회합니다. + *+ * 배치 조회를 통해 N+1 쿼리 문제를 해결합니다. + *
+ * + * @param productIds 조회할 상품 ID 목록 + * @return 조회된 상품 목록 + */ + @Transactional(readOnly = true) + public List+ * 동시성 제어가 필요한 경우 사용합니다. (예: 재고 차감) + *
+ * + * @param productId 조회할 상품 ID + * @return 조회된 상품 + * @throws CoreException 상품을 찾을 수 없는 경우 + */ + @Transactional + public Product getProductForUpdate(Long productId) { + return productRepository.findByIdForUpdate(productId) + .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, + String.format("상품을 찾을 수 없습니다. (상품 ID: %d)", productId))); + } + + /** + * 상품 목록을 저장합니다. + * + * @param products 저장할 상품 목록 + */ + @Transactional + public void saveAll(List+ * 이벤트 기반 집계에서 사용됩니다. + *
+ *+ * 동시성 제어: 비관적 락을 사용하지 않습니다. 좋아요 수는 정확도보다 성능이 중요하며, + * 약간의 오차는 허용 가능합니다. 필요시 나중에 비관적 락을 추가할 수 있습니다. + *
+ * + * @param productId 상품 ID + * @throws CoreException 상품을 찾을 수 없는 경우 + */ + @Transactional + public void incrementLikeCount(Long productId) { + Product product = getProduct(productId); + product.incrementLikeCount(); + productRepository.save(product); + } + + /** + * 상품의 좋아요 수를 감소시킵니다. + *+ * 이벤트 기반 집계에서 사용됩니다. + *
+ *+ * 동시성 제어: 비관적 락을 사용하지 않습니다. 좋아요 수는 정확도보다 성능이 중요하며, + * 약간의 오차는 허용 가능합니다. 필요시 나중에 비관적 락을 추가할 수 있습니다. + *
+ * + * @param productId 상품 ID + * @throws CoreException 상품을 찾을 수 없는 경우 + */ + @Transactional + public void decrementLikeCount(Long productId) { + Product product = getProduct(productId); + product.decrementLikeCount(); + productRepository.save(product); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/purchasing/OrderInfo.java b/apps/commerce-api/src/main/java/com/loopers/application/purchasing/OrderInfo.java new file mode 100644 index 000000000..48e9bdb58 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/purchasing/OrderInfo.java @@ -0,0 +1,46 @@ +package com.loopers.application.purchasing; + +import com.loopers.domain.order.Order; +import com.loopers.domain.order.OrderStatus; + +import java.util.List; + +/** + * 주문 정보를 담는 레코드. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param totalAmount 총 주문 금액 + * @param status 주문 상태 + * @param items 주문 아이템 목록 + */ +public record OrderInfo( + Long orderId, + Long userId, + Integer totalAmount, + OrderStatus status, + List+ * 주문 생성과 결제(포인트 차감), 재고 조정, 외부 연동을 조율하는 애플리케이션 서비스입니다. + * 여러 도메인 서비스를 조합하여 구매 유즈케이스를 처리합니다. + *
+ *+ * EDA 원칙 준수: + *
+ * 1. 사용자 조회 및 존재 여부 검증
+ * 2. 상품 조회 (재고 검증은 이벤트 핸들러에서 처리)
+ * 3. 쿠폰 할인 적용
+ * 4. 주문 저장 및 OrderEvent.OrderCreated 이벤트 발행
+ * 5. 결제 요청 시 PaymentEvent.PaymentRequested 이벤트 발행
+ *
+ * 결제 방식: + *
+ * EDA 원칙: + *
+ * EDA 원칙: + *
+ * 별도 트랜잭션으로 실행하여 외부 시스템 호출과 독립적으로 처리합니다. + *
+ * + * @param orderId 주문 ID + * @param paymentStatus 결제 상태 (도메인 모델) + * @param transactionKey 트랜잭션 키 + * @param reason 실패 사유 (실패 시) + * @return 업데이트 성공 여부 (true: 성공, false: 실패) + */ + @Transactional(propagation = Propagation.REQUIRES_NEW) + public boolean updateOrderStatusByPaymentResult( + Long orderId, + PaymentStatus paymentStatus, + String transactionKey, + String reason + ) { + try { + Order order = orderService.getOrder(orderId).orElse(null); + + if (order == null) { + log.warn("주문 상태 업데이트 시 주문을 찾을 수 없습니다. (orderId: {})", orderId); + return false; + } + + // 이미 완료되거나 취소된 주문인 경우 처리하지 않음 (정상적인 경우이므로 true 반환) + if (order.isCompleted()) { + log.debug("이미 완료된 주문입니다. 상태 업데이트를 건너뜁니다. (orderId: {})", orderId); + return true; + } + + if (order.isCanceled()) { + log.debug("이미 취소된 주문입니다. 상태 업데이트를 건너뜁니다. (orderId: {})", orderId); + return true; + } + + if (paymentStatus == PaymentStatus.SUCCESS) { + // 결제 성공: 주문 완료 + orderService.updateStatusByPaymentResult(order, paymentStatus, null, null); + log.info("결제 상태 확인 결과, 주문 상태를 COMPLETED로 업데이트했습니다. (orderId: {}, transactionKey: {})", + orderId, transactionKey); + return true; + } else if (paymentStatus == PaymentStatus.FAILED) { + // 결제 실패: 주문 취소 및 리소스 원복 + // 실제로 사용된 포인트만 환불 (Payment에서 확인) + Long refundPointAmount = paymentService.getPaymentByOrderId(order.getId()) + .map(Payment::getUsedPoint) + .orElse(0L); + + // 취소 사유 설정 (reason이 없으면 기본값 사용) + String cancelReason = (reason != null && !reason.isBlank()) + ? reason + : "결제 실패"; + + // 주문 취소 처리 (이벤트 발행 포함) + orderService.updateStatusByPaymentResult(order, paymentStatus, cancelReason, refundPointAmount); + log.info("결제 상태 확인 결과, 주문 상태를 CANCELED로 업데이트했습니다. (orderId: {}, transactionKey: {}, reason: {}, refundPointAmount: {})", + orderId, transactionKey, cancelReason, refundPointAmount); + return true; + } else { + // PENDING 상태: 아직 처리 중 (정상적인 경우이므로 true 반환) + log.debug("결제 상태 확인 결과, 아직 처리 중입니다. 주문은 PENDING 상태로 유지됩니다. (orderId: {}, transactionKey: {})", + orderId, transactionKey); + return true; + } + } catch (Exception e) { + log.error("주문 상태 업데이트 중 오류 발생. (orderId: {})", orderId, e); + return false; + } + } + + + + /** + * PG 결제 콜백을 처리합니다. + *+ * PG 시스템에서 결제 처리 완료 후 콜백으로 전송된 결제 결과를 받아 + * 주문 상태를 업데이트합니다. + *
+ *+ * 보안 및 정합성 강화: + *
+ * 처리 내용: + *
+ * 보안 및 정합성을 위해 콜백 정보를 직접 신뢰하지 않고, + * PG 원장(조회 API)을 기준으로 검증합니다. + *
+ *+ * 검증 전략: + *
+ * 콜백이 오지 않았거나 타임아웃된 경우, PG 시스템의 결제 상태 확인 API를 호출하여 + * 실제 결제 상태를 확인하고 주문 상태를 업데이트합니다. + *
+ * + * @param userId 사용자 ID (String - PG API 요구사항) + * @param orderId 주문 ID + */ + @Transactional + public void recoverOrderStatusByPaymentCheck(String userId, Long orderId) { + try { + // PaymentService를 통한 타임아웃 복구 + paymentService.recoverAfterTimeout(userId, orderId); + + // 결제 상태 조회 + PaymentStatus paymentStatus = paymentService.getPaymentStatus(userId, orderId); + + // 주문 상태 업데이트 처리 + boolean updated = updateOrderStatusByPaymentResult(orderId, paymentStatus, null, null); + + if (!updated) { + log.warn("상태 복구 실패. 주문 상태 업데이트에 실패했습니다. (orderId: {})", orderId); + } + + } catch (Exception e) { + log.error("상태 복구 중 오류 발생. (orderId: {})", orderId, e); + // 기타 오류도 로그만 기록 + } + } + +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingKeyGenerator.java b/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingKeyGenerator.java new file mode 100644 index 000000000..f87a52422 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingKeyGenerator.java @@ -0,0 +1,52 @@ +package com.loopers.application.ranking; + +import org.springframework.stereotype.Component; + +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.format.DateTimeFormatter; + +/** + * 랭킹 키 생성 유틸리티. + *+ * Redis ZSET 랭킹 키를 생성합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +public class RankingKeyGenerator { + private static final String DAILY_KEY_PREFIX = "ranking:all:"; + private static final String HOURLY_KEY_PREFIX = "ranking:hourly:"; + private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMdd"); + private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMddHH"); + + /** + * 일간 랭킹 키를 생성합니다. + *+ * 예: ranking:all:20241215 + *
+ * + * @param date 날짜 + * @return 일간 랭킹 키 + */ + public String generateDailyKey(LocalDate date) { + String dateStr = date.format(DATE_FORMATTER); + return DAILY_KEY_PREFIX + dateStr; + } + + /** + * 시간 단위 랭킹 키를 생성합니다. + *+ * 예: ranking:hourly:2024121514 + *
+ * + * @param dateTime 날짜 및 시간 + * @return 시간 단위 랭킹 키 + */ + public String generateHourlyKey(LocalDateTime dateTime) { + String dateTimeStr = dateTime.format(DATE_TIME_FORMATTER); + return HOURLY_KEY_PREFIX + dateTimeStr; + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingService.java b/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingService.java new file mode 100644 index 000000000..b6ebf5fc5 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/ranking/RankingService.java @@ -0,0 +1,526 @@ +package com.loopers.application.ranking; + +import com.loopers.application.brand.BrandService; +import com.loopers.application.product.ProductService; +import com.loopers.domain.brand.Brand; +import com.loopers.domain.product.Product; +import com.loopers.domain.product.ProductDetail; +import com.loopers.zset.ZSetEntry; +import com.loopers.zset.RedisZSetTemplate; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.dao.DataAccessException; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.stream.Collectors; + +/** + * 랭킹 조회 서비스. + *+ * Redis ZSET에서 랭킹을 조회하고 상품 정보를 Aggregation하여 제공합니다. + *
+ *+ * 설계 원칙: + *
+ * 기간별(일간/주간/월간) 랭킹을 조회합니다. + *
+ *+ * 기간별 조회 방식: + *
+ * Graceful Degradation (DAILY만 적용): + *
+ * ZSET에서 상위 N개를 조회하고, 상품 정보를 Aggregation하여 반환합니다. + *
+ *+ * Graceful Degradation: + *
+ * 스케줄러에서 스냅샷 저장 시 호출하기 위해 public으로 제공합니다. + *
+ * + * @param date 날짜 + * @param page 페이지 번호 + * @param size 페이지당 항목 수 + * @return 랭킹 조회 결과 + * @throws DataAccessException Redis 접근 실패 시 + */ + public RankingsResponse getRankingsFromRedis(LocalDate date, int page, int size) { + String key = keyGenerator.generateDailyKey(date); + long start = (long) page * size; + long end = start + size - 1; + + // ZSET에서 Top N 조회 + List+ * 최종 Fallback으로 사용됩니다. 랭킹을 새로 계산하는 것이 아니라 + * 이미 집계된 좋아요 수를 단순 조회하는 것이므로 DB 부하가 크지 않습니다. + *
+ * + * @param page 페이지 번호 (0부터 시작) + * @param size 페이지당 항목 수 + * @return 랭킹 조회 결과 + */ + private RankingsResponse getDefaultRankings(int page, int size) { + // 좋아요순으로 상품 조회 + List+ * 상품이 랭킹에 없으면 null을 반환합니다. + *
+ *+ * Graceful Degradation: + *
+ * Materialized View에 저장된 TOP 100 랭킹을 조회하고, 상품 정보를 Aggregation하여 반환합니다. + *
+ * + * @param date 기준 날짜 + * @param periodType 기간 타입 (WEEKLY 또는 MONTHLY) + * @param page 페이지 번호 (0부터 시작) + * @param size 페이지당 항목 수 + * @return 랭킹 조회 결과 + */ + private RankingsResponse getRankingsFromMaterializedView( + LocalDate date, + PeriodType periodType, + int page, + int size + ) { + // 기간 시작일 계산 + LocalDate periodStartDate; + if (periodType == PeriodType.WEEKLY) { + // 주간: 해당 주의 월요일 + periodStartDate = date.with(java.time.DayOfWeek.MONDAY); + } else { + // 월간: 해당 월의 1일 + periodStartDate = date.with(java.time.temporal.TemporalAdjusters.firstDayOfMonth()); + } + + // Materialized View에서 랭킹 조회 + com.loopers.domain.rank.ProductRank.PeriodType rankPeriodType = + periodType == PeriodType.WEEKLY + ? com.loopers.domain.rank.ProductRank.PeriodType.WEEKLY + : com.loopers.domain.rank.ProductRank.PeriodType.MONTHLY; + + List+ * 가중치: + *
+ * Redis 장애 시 Fallback으로 사용하기 위한 랭킹 데이터 스냅샷을 인메모리에 저장합니다. + *
+ *+ * 설계 원칙: + *
+ * 최근 7일치만 보관하여 메모리 사용량을 제한합니다. + *
+ */ + private void cleanupOldSnapshots() { + if (snapshotCache.size() <= MAX_SNAPSHOTS) { + return; + } + + // 가장 오래된 스냅샷 제거 + LocalDate today = LocalDate.now(ZoneId.of("UTC")); + LocalDate oldestDate = today.minusDays(MAX_SNAPSHOTS); + + snapshotCache.entrySet().removeIf(entry -> { + try { + LocalDate entryDate = LocalDate.parse(entry.getKey(), DATE_FORMATTER); + boolean shouldRemove = entryDate.isBefore(oldestDate); + if (shouldRemove) { + log.debug("오래된 스냅샷 제거: key={}", entry.getKey()); + } + return shouldRemove; + } catch (Exception e) { + log.warn("스냅샷 키 파싱 실패, 제거: key={}", entry.getKey(), e); + return true; // 파싱 실패한 키는 제거 + } + }); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/user/DeductPointCommand.java b/apps/commerce-api/src/main/java/com/loopers/application/user/DeductPointCommand.java new file mode 100644 index 000000000..f18b91b03 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/user/DeductPointCommand.java @@ -0,0 +1,22 @@ +package com.loopers.application.user; + +/** + * 포인트 차감 명령. + *+ * 포인트 차감을 위한 명령 객체입니다. + *
+ * + * @param userId 사용자 ID + * @param usedPointAmount 사용할 포인트 금액 + */ +public record DeductPointCommand( + Long userId, + Long usedPointAmount +) { + public DeductPointCommand { + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/application/user/PointEventHandler.java b/apps/commerce-api/src/main/java/com/loopers/application/user/PointEventHandler.java new file mode 100644 index 000000000..73af4d9d4 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/application/user/PointEventHandler.java @@ -0,0 +1,147 @@ +package com.loopers.application.user; + +import com.loopers.domain.order.OrderEvent; +import com.loopers.domain.user.Point; +import com.loopers.domain.user.PointEvent; +import com.loopers.domain.user.PointEventPublisher; +import com.loopers.domain.user.User; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +/** + * 포인트 이벤트 핸들러. + *+ * 주문 생성 이벤트를 받아 포인트 사용 처리를 수행하고, 주문 취소 이벤트를 받아 포인트 환불 처리를 수행하는 애플리케이션 로직을 처리합니다. + *
+ *+ * DDD/EDA 관점: + *
+ * OrderEvent.OrderCreated를 구독하여 포인트 차감 Command를 실행합니다. + *
+ * + * @param event 주문 생성 이벤트 + */ + @Transactional + public void handleOrderCreated(OrderEvent.OrderCreated event) { + // 포인트 사용량이 없는 경우 처리하지 않음 + if (event.usedPointAmount() == null || event.usedPointAmount() == 0) { + log.debug("포인트 사용량이 없어 포인트 차감 처리를 건너뜁니다. (orderId: {})", event.orderId()); + return; + } + + try { + // 사용자 조회 (비관적 락 사용) + // OrderEvent.OrderCreated의 userId는 Long 타입 (User.id - PK) + User user = userService.getUserByIdForUpdate(event.userId()); + + // 포인트 잔액 검증 + Long userPointBalance = user.getPointValue(); + if (userPointBalance < event.usedPointAmount()) { + String failureReason = String.format("포인트가 부족합니다. (현재 잔액: %d, 사용 요청 금액: %d)", + userPointBalance, event.usedPointAmount()); + log.error("포인트가 부족합니다. (orderId: {}, userId: {}, 현재 잔액: {}, 사용 요청 금액: {})", + event.orderId(), event.userId(), userPointBalance, event.usedPointAmount()); + + // 포인트 사용 실패 이벤트 발행 + pointEventPublisher.publish(PointEvent.PointUsedFailed.of( + event.orderId(), + event.userId(), + event.usedPointAmount(), + failureReason + )); + + throw new CoreException(ErrorType.BAD_REQUEST, failureReason); + } + + // ✅ OrderEvent.OrderCreated를 구독하여 포인트 차감 Command 실행 + DeductPointCommand command = new DeductPointCommand(event.userId(), event.usedPointAmount()); + user.deductPoint(Point.of(command.usedPointAmount())); + userService.save(user); + + log.info("포인트 차감 처리 완료. (orderId: {}, userId: {}, usedPointAmount: {})", + event.orderId(), event.userId(), event.usedPointAmount()); + } catch (CoreException e) { + // CoreException은 이미 이벤트가 발행되었거나 처리되었으므로 그대로 던짐 + throw e; + } catch (Exception e) { + // 예상치 못한 오류 발생 시 실패 이벤트 발행 + String failureReason = e.getMessage() != null ? e.getMessage() : "포인트 차감 처리 중 오류 발생"; + log.error("포인트 차감 처리 중 오류 발생. (orderId: {}, userId: {}, usedPointAmount: {})", + event.orderId(), event.userId(), event.usedPointAmount(), e); + + pointEventPublisher.publish(PointEvent.PointUsedFailed.of( + event.orderId(), + event.userId(), + event.usedPointAmount(), + failureReason + )); + + throw e; + } + } + + /** + * 주문 취소 이벤트를 처리하여 포인트를 환불합니다. + *+ * 환불할 포인트 금액이 0보다 큰 경우에만 포인트 환불 처리를 수행합니다. + *
+ *+ * 동시성 제어: + *
+ * 사용자 생성, 조회, 포인트 관리 등의 애플리케이션 로직을 처리합니다. + * Repository에 의존하며 트랜잭션 관리 및 데이터 무결성 제약 조건을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class UserService { + private final UserRepository userRepository; + + /** + * 새로운 사용자를 생성합니다. + * + * @param userId 사용자 ID + * @param email 이메일 주소 + * @param birthDateStr 생년월일 (yyyy-MM-dd) + * @param gender 성별 + * @return 생성된 사용자 + * @throws CoreException 중복된 사용자 ID가 존재하거나 유효성 검증 실패 시 + */ + public User create(String userId, String email, String birthDateStr, Gender gender, Point point) { + User user = User.of(userId, email, birthDateStr, gender, point); + try { + return userRepository.save(user); + } catch (DataIntegrityViolationException e) { + if (e.getMessage() != null && e.getMessage().contains("user_id")) { + throw new CoreException(ErrorType.CONFLICT, "이미 가입된 ID입니다: " + userId); + } + throw new CoreException(ErrorType.CONFLICT, "데이터 무결성 제약 조건 위반"); + } + } + + /** + * 사용자 ID로 사용자를 조회합니다. + * + * @param userId 조회할 사용자 ID + * @return 조회된 사용자 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public User getUser(String userId) { + User user = userRepository.findByUserId(userId); + if (user == null) { + throw new CoreException(ErrorType.NOT_FOUND, "사용자를 찾을 수 없습니다."); + } + return user; + } + + /** + * 사용자 ID로 사용자를 조회합니다. (비관적 락) + *+ * 포인트 차감 등 동시성 제어가 필요한 경우 사용합니다. + *
+ * + * @param userId 조회할 사용자 ID + * @return 조회된 사용자 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + @Transactional + public User getUserForUpdate(String userId) { + User user = userRepository.findByUserIdForUpdate(userId); + if (user == null) { + throw new CoreException(ErrorType.NOT_FOUND, "사용자를 찾을 수 없습니다."); + } + return user; + } + + /** + * 사용자 ID (PK)로 사용자를 조회합니다. + * + * @param id 사용자 ID (PK) + * @return 조회된 사용자 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public User getUserById(Long id) { + User user = userRepository.findById(id); + if (user == null) { + throw new CoreException(ErrorType.NOT_FOUND, "사용자를 찾을 수 없습니다."); + } + return user; + } + + /** + * 사용자 ID (PK)로 사용자를 조회합니다. (비관적 락) + *+ * 포인트 차감 등 동시성 제어가 필요한 경우 사용합니다. + *
+ * + * @param id 사용자 ID (PK) + * @return 조회된 사용자 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + @Transactional + public User getUserByIdForUpdate(Long id) { + User user = userRepository.findByIdForUpdate(id); + if (user == null) { + throw new CoreException(ErrorType.NOT_FOUND, "사용자를 찾을 수 없습니다."); + } + return user; + } + + /** + * 사용자를 저장합니다. + * + * @param user 저장할 사용자 + * @return 저장된 사용자 + */ + @Transactional + public User save(User user) { + return userRepository.save(user); + } + + /** + * 사용자의 포인트를 조회합니다. + * + * @param userId 조회할 사용자 ID + * @return 포인트 정보 + * @throws CoreException 사용자를 찾을 수 없는 경우 + */ + @Transactional(readOnly = true) + public PointsInfo getPoints(String userId) { + User user = getUser(userId); + return PointsInfo.from(user); + } + + /** + * 사용자의 포인트를 충전합니다. + *+ * 트랜잭션 내에서 실행되어 데이터 일관성을 보장합니다. + * 비관적 락(PESSIMISTIC_WRITE)을 사용하여 동시 충전 요청 시 Lost Update를 방지합니다. + *
+ *+ * 동시성 제어: + *
+ * 실무 권장 패턴에 따라 메서드별로 다른 Retry 정책을 적용합니다: + *
+ *+ * Retry 정책: + *
+ * Exponential Backoff 전략 (조회 API용): + *
+ * 재시도 시퀀스 예시 (조회 API): + *
+ * 설계 근거: + *
+ * Exponential Backoff 전략을 적용하여 재시도 간격을 점진적으로 증가시킵니다. + *
+ * + * @return RetryRegistry (커스터마이징된 설정이 적용됨) + */ + @Bean + public RetryRegistry retryRegistry() { + RetryRegistry retryRegistry = io.github.resilience4j.retry.RetryRegistry.ofDefaults(); + // Exponential Backoff 설정 + // - 초기 대기 시간: 500ms + // - 배수: 2 (각 재시도마다 2배씩 증가) + // - 최대 대기 시간: 5초 + // - 랜덤 jitter: 활성화 (thundering herd 문제 방지) + IntervalFunction intervalFunction = IntervalFunction + .ofExponentialRandomBackoff( + Duration.ofMillis(500), // 초기 대기 시간 + 2.0, // 배수 (exponential multiplier) + Duration.ofSeconds(5) // 최대 대기 시간 + ); + + // RetryConfig 커스터마이징 + RetryConfig retryConfig = RetryConfig.custom() + .maxAttempts(3) // 최대 재시도 횟수 (초기 시도 포함) + .intervalFunction(intervalFunction) // Exponential Backoff 적용 + .retryOnException(throwable -> { + // 일시적 오류만 재시도: 5xx 서버 오류, 타임아웃, 네트워크 오류 + if (throwable instanceof FeignException feignException) { + int status = feignException.status(); + // 5xx 서버 오류만 재시도 + if (status >= 500 && status < 600) { + log.debug("재시도 대상 예외: FeignException (status: {})", status); + return true; + } + return false; + } + if (throwable instanceof SocketTimeoutException || + throwable instanceof TimeoutException) { + log.debug("재시도 대상 예외: {}", throwable.getClass().getSimpleName()); + return true; + } + return false; + }) + // ignoreExceptions는 사용하지 않음 + // retryOnException에서 5xx만 재시도하고 4xx는 제외하므로, + // 별도로 ignoreExceptions를 설정할 필요가 없음 + .build(); + + // 결제 요청 API: 유저 요청 경로에서 사용되므로 Retry 비활성화 (빠른 실패) + // 실패 시 주문은 PENDING 상태로 유지되어 스케줄러에서 복구됨 + RetryConfig noRetryConfig = RetryConfig.custom() + .maxAttempts(1) // 재시도 없음 (초기 시도만) + .build(); + retryRegistry.addConfiguration("paymentGatewayClient", noRetryConfig); + + // 스케줄러 전용 클라이언트: 비동기/배치 기반으로 Retry 적용 + // Exponential Backoff 적용하여 일시적 오류 자동 복구 + retryRegistry.addConfiguration("paymentGatewaySchedulerClient", retryConfig); + + log.debug("Resilience4j Retry 설정 완료:"); + log.debug(" - 결제 요청 API (paymentGatewayClient): Retry 없음 (유저 요청 경로 - 빠른 실패)"); + log.debug(" - 조회 API (paymentGatewaySchedulerClient): Exponential Backoff 적용 (스케줄러 - 비동기/배치 기반 Retry)"); + + return retryRegistry; + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/brand/Brand.java b/apps/commerce-api/src/main/java/com/loopers/domain/brand/Brand.java new file mode 100644 index 000000000..b0b1f55c3 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/brand/Brand.java @@ -0,0 +1,63 @@ +package com.loopers.domain.brand; + +import com.loopers.domain.BaseEntity; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import jakarta.persistence.Column; +import jakarta.persistence.Entity; +import jakarta.persistence.Table; +import lombok.AccessLevel; +import lombok.Getter; +import lombok.NoArgsConstructor; + +/** + * 브랜드 도메인 엔티티. + *+ * 브랜드의 기본 정보(이름)를 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table(name = "brand") +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Brand extends BaseEntity { + @Column(name = "name", nullable = false) + private String name; + + /** + * Brand 인스턴스를 생성합니다. + * + * @param name 브랜드 이름 + * @throws CoreException name이 null이거나 공백일 경우 + */ + public Brand(String name) { + validateName(name); + this.name = name; + } + + /** + * 브랜드 이름의 유효성을 검증합니다. + * + * @param name 검증할 브랜드 이름 + * @throws CoreException name이 null이거나 공백일 경우 + */ + private void validateName(String name) { + if (name == null || name.isBlank()) { + throw new CoreException(ErrorType.BAD_REQUEST, "브랜드 이름은 필수입니다."); + } + } + + /** + * Brand 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param name 브랜드 이름 + * @return 생성된 Brand 인스턴스 + */ + public static Brand of(String name) { + return new Brand(name); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/brand/BrandRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/brand/BrandRepository.java new file mode 100644 index 000000000..03d6db682 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/brand/BrandRepository.java @@ -0,0 +1,43 @@ +package com.loopers.domain.brand; + +import java.util.List; +import java.util.Optional; + +/** + * Brand 엔티티에 대한 저장소 인터페이스. + *+ * 브랜드 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface BrandRepository { + /** + * 브랜드를 저장합니다. + * + * @param brand 저장할 브랜드 + * @return 저장된 브랜드 + */ + Brand save(Brand brand); + + /** + * 브랜드 ID로 브랜드를 조회합니다. + * + * @param brandId 조회할 브랜드 ID + * @return 조회된 브랜드를 담은 Optional + */ + Optional+ * 배치 조회를 통해 N+1 쿼리 문제를 해결합니다. + *
+ * + * @param brandIds 조회할 브랜드 ID 목록 + * @return 조회된 브랜드 목록 + */ + List+ * 쿠폰의 기본 정보(코드, 타입, 할인 금액/비율)를 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table(name = "coupon") +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Coupon extends BaseEntity { + @Column(name = "code", unique = true, nullable = false, length = 50) + private String code; + + @Enumerated(EnumType.STRING) + @Column(name = "type", nullable = false) + private CouponType type; + + @Column(name = "discount_value", nullable = false) + private Integer discountValue; + + /** + * Coupon 인스턴스를 생성합니다. + * + * @param code 쿠폰 코드 (필수, 최대 50자) + * @param type 쿠폰 타입 (필수) + * @param discountValue 할인 값 (필수, 0 초과) + * - FIXED_AMOUNT: 할인 금액 + * - PERCENTAGE: 할인 비율 (0-100) + * @throws CoreException 유효성 검증 실패 시 + */ + public Coupon(String code, CouponType type, Integer discountValue) { + validateCode(code); + validateType(type); + validateDiscountValue(type, discountValue); + this.code = code; + this.type = type; + this.discountValue = discountValue; + } + + /** + * Coupon 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param code 쿠폰 코드 + * @param type 쿠폰 타입 + * @param discountValue 할인 값 + * @return 생성된 Coupon 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static Coupon of(String code, CouponType type, Integer discountValue) { + return new Coupon(code, type, discountValue); + } + + /** + * 쿠폰 코드의 유효성을 검증합니다. + * + * @param code 검증할 쿠폰 코드 + * @throws CoreException code가 null, 공백이거나 50자를 초과할 경우 + */ + private void validateCode(String code) { + if (code == null || code.isBlank()) { + throw new CoreException(ErrorType.BAD_REQUEST, "쿠폰 코드는 필수입니다."); + } + if (code.length() > 50) { + throw new CoreException(ErrorType.BAD_REQUEST, "쿠폰 코드는 50자를 초과할 수 없습니다."); + } + } + + /** + * 쿠폰 타입의 유효성을 검증합니다. + * + * @param type 검증할 쿠폰 타입 + * @throws CoreException type이 null일 경우 + */ + private void validateType(CouponType type) { + if (type == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "쿠폰 타입은 필수입니다."); + } + } + + /** + * 할인 값의 유효성을 검증합니다. + * + * @param type 쿠폰 타입 + * @param discountValue 검증할 할인 값 + * @throws CoreException discountValue가 null이거나 유효하지 않을 경우 + */ + private void validateDiscountValue(CouponType type, Integer discountValue) { + if (discountValue == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "할인 값은 필수입니다."); + } + if (discountValue <= 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "할인 값은 0보다 커야 합니다."); + } + if (type == CouponType.PERCENTAGE && discountValue > 100) { + throw new CoreException(ErrorType.BAD_REQUEST, "정률 쿠폰의 할인 비율은 100을 초과할 수 없습니다."); + } + } + + /** + * 주문 금액에 쿠폰을 적용하여 할인 금액을 계산합니다. + *+ * 전략 패턴을 사용하여 쿠폰 타입별 할인 계산 로직을 분리합니다. + * 새로운 쿠폰 타입이 추가되어도 기존 코드를 수정하지 않고 확장할 수 있습니다. + *
+ * + * @param orderAmount 주문 금액 + * @param strategyFactory 할인 계산 전략 팩토리 + * @return 할인 금액 + * @throws CoreException orderAmount가 null이거나 0 이하일 경우 + */ + public Integer calculateDiscountAmount(Integer orderAmount, CouponDiscountStrategyFactory strategyFactory) { + if (orderAmount == null || orderAmount <= 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "주문 금액은 0보다 커야 합니다."); + } + + // 전략 패턴을 사용하여 쿠폰 타입별 할인 계산 + CouponDiscountStrategy strategy = strategyFactory.getStrategy(this.type); + return strategy.calculateDiscountAmount(orderAmount, this.discountValue); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEvent.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEvent.java new file mode 100644 index 000000000..10f8d6c9a --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEvent.java @@ -0,0 +1,124 @@ +package com.loopers.domain.coupon; + +import java.time.LocalDateTime; + +/** + * 쿠폰 도메인 이벤트. + *+ * 쿠폰 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public class CouponEvent { + + /** + * 쿠폰 적용 이벤트. + *+ * 쿠폰이 주문에 적용되었을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param couponCode 쿠폰 코드 + * @param discountAmount 할인 금액 + * @param appliedAt 쿠폰 적용 시각 + */ + public record CouponApplied( + Long orderId, + Long userId, + String couponCode, + Integer discountAmount, + LocalDateTime appliedAt + ) { + public CouponApplied { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (couponCode == null || couponCode.isBlank()) { + throw new IllegalArgumentException("couponCode는 필수입니다."); + } + if (discountAmount == null || discountAmount < 0) { + throw new IllegalArgumentException("discountAmount는 0 이상이어야 합니다."); + } + } + + /** + * 쿠폰 적용 정보로부터 CouponApplied 이벤트를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param couponCode 쿠폰 코드 + * @param discountAmount 할인 금액 + * @return CouponApplied 이벤트 + */ + public static CouponApplied of(Long orderId, Long userId, String couponCode, Integer discountAmount) { + return new CouponApplied( + orderId, + userId, + couponCode, + discountAmount, + LocalDateTime.now() + ); + } + } + + /** + * 쿠폰 적용 실패 이벤트. + *+ * 쿠폰 적용에 실패했을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param couponCode 쿠폰 코드 + * @param failureReason 실패 사유 + * @param failedAt 실패 시각 + */ + public record CouponApplicationFailed( + Long orderId, + Long userId, + String couponCode, + String failureReason, + LocalDateTime failedAt + ) { + public CouponApplicationFailed { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (couponCode == null || couponCode.isBlank()) { + throw new IllegalArgumentException("couponCode는 필수입니다."); + } + if (failureReason == null || failureReason.isBlank()) { + throw new IllegalArgumentException("failureReason는 필수입니다."); + } + } + + /** + * 쿠폰 적용 실패 정보로부터 CouponApplicationFailed 이벤트를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param couponCode 쿠폰 코드 + * @param failureReason 실패 사유 + * @return CouponApplicationFailed 이벤트 + */ + public static CouponApplicationFailed of(Long orderId, Long userId, String couponCode, String failureReason) { + return new CouponApplicationFailed( + orderId, + userId, + couponCode, + failureReason, + LocalDateTime.now() + ); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEventPublisher.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEventPublisher.java new file mode 100644 index 000000000..8269b35e4 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponEventPublisher.java @@ -0,0 +1,29 @@ +package com.loopers.domain.coupon; + +/** + * 쿠폰 도메인 이벤트 발행 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface CouponEventPublisher { + + /** + * 쿠폰 적용 이벤트를 발행합니다. + * + * @param event 쿠폰 적용 이벤트 + */ + void publish(CouponEvent.CouponApplied event); + + /** + * 쿠폰 적용 실패 이벤트를 발행합니다. + * + * @param event 쿠폰 적용 실패 이벤트 + */ + void publish(CouponEvent.CouponApplicationFailed event); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponRepository.java new file mode 100644 index 000000000..6ffe52a9e --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/CouponRepository.java @@ -0,0 +1,39 @@ +package com.loopers.domain.coupon; + +import java.util.Optional; + +/** + * Coupon 엔티티에 대한 저장소 인터페이스. + *+ * 쿠폰 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface CouponRepository { + /** + * 쿠폰을 저장합니다. + * + * @param coupon 저장할 쿠폰 + * @return 저장된 쿠폰 + */ + Coupon save(Coupon coupon); + + /** + * 쿠폰 코드로 쿠폰을 조회합니다. + * + * @param code 쿠폰 코드 + * @return 조회된 쿠폰을 담은 Optional + */ + Optional+ * 정액 쿠폰과 정률 쿠폰을 구분합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public enum CouponType { + /** + * 정액 쿠폰: 고정 금액 할인 + */ + FIXED_AMOUNT, + + /** + * 정률 쿠폰: 비율 할인 + */ + PERCENTAGE +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCoupon.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCoupon.java new file mode 100644 index 000000000..3f2e07322 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCoupon.java @@ -0,0 +1,134 @@ +package com.loopers.domain.coupon; + +import com.loopers.domain.BaseEntity; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import jakarta.persistence.*; +import lombok.AccessLevel; +import lombok.Getter; +import lombok.NoArgsConstructor; + +/** + * 사용자 쿠폰 도메인 엔티티. + *+ * 사용자가 소유한 쿠폰과 사용 여부를 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table(name = "user_coupon", uniqueConstraints = { + @UniqueConstraint(name = "uk_user_coupon_user_coupon", columnNames = {"ref_user_id", "ref_coupon_id"}) +}) +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class UserCoupon extends BaseEntity { + @Column(name = "ref_user_id", nullable = false) + private Long userId; + + @ManyToOne(fetch = FetchType.LAZY) + @JoinColumn(name = "ref_coupon_id", nullable = false) + private Coupon coupon; + + @Column(name = "is_used", nullable = false) + private Boolean isUsed; + + @Version + @Column(name = "version", nullable = false) + private Long version; + + /** + * UserCoupon 인스턴스를 생성합니다. + * + * @param userId 사용자 ID (필수) + * @param coupon 쿠폰 (필수) + * @throws CoreException 유효성 검증 실패 시 + */ + public UserCoupon(Long userId, Coupon coupon) { + validateUserId(userId); + validateCoupon(coupon); + this.userId = userId; + this.coupon = coupon; + this.isUsed = false; + } + + /** + * UserCoupon 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param userId 사용자 ID + * @param coupon 쿠폰 + * @return 생성된 UserCoupon 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static UserCoupon of(Long userId, Coupon coupon) { + return new UserCoupon(userId, coupon); + } + + /** + * 사용자 ID의 유효성을 검증합니다. + * + * @param userId 검증할 사용자 ID + * @throws CoreException userId가 null일 경우 + */ + private void validateUserId(Long userId) { + if (userId == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "사용자 ID는 필수입니다."); + } + } + + /** + * 쿠폰의 유효성을 검증합니다. + * + * @param coupon 검증할 쿠폰 + * @throws CoreException coupon이 null일 경우 + */ + private void validateCoupon(Coupon coupon) { + if (coupon == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "쿠폰은 필수입니다."); + } + } + + /** + * 쿠폰을 사용합니다. + *+ * 이미 사용된 쿠폰은 다시 사용할 수 없습니다. + *
+ * + * @throws CoreException 이미 사용된 쿠폰일 경우 + */ + public void use() { + if (this.isUsed) { + throw new CoreException(ErrorType.BAD_REQUEST, "이미 사용된 쿠폰입니다."); + } + this.isUsed = true; + } + + /** + * 쿠폰이 사용 가능한지 확인합니다. + * + * @return 사용 가능하면 true, 아니면 false + */ + public boolean isAvailable() { + return !this.isUsed; + } + + /** + * 쿠폰 코드를 반환합니다. + * + * @return 쿠폰 코드 + */ + public String getCouponCode() { + return coupon.getCode(); + } + + /** + * 쿠폰을 반환합니다. + * + * @return 쿠폰 + */ + public Coupon getCoupon() { + return coupon; + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCouponRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCouponRepository.java new file mode 100644 index 000000000..6a06032ff --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/UserCouponRepository.java @@ -0,0 +1,61 @@ +package com.loopers.domain.coupon; + +import java.util.Optional; + +/** + * UserCoupon 엔티티에 대한 저장소 인터페이스. + *+ * 사용자 쿠폰 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface UserCouponRepository { + /** + * 사용자 쿠폰을 저장합니다. + * + * @param userCoupon 저장할 사용자 쿠폰 + * @return 저장된 사용자 쿠폰 + */ + UserCoupon save(UserCoupon userCoupon); + + /** + * 사용자 ID와 쿠폰 코드로 사용자 쿠폰을 조회합니다. + * + * @param userId 사용자 ID + * @param couponCode 쿠폰 코드 + * @return 조회된 사용자 쿠폰을 담은 Optional + */ + Optional+ * 동시성 제어가 필요한 경우 사용합니다. (예: 쿠폰 사용) + *
+ *+ * Lock 전략: + *
+ * Optimistic Lock을 사용하는 경우, save() 후 flush()를 호출하여 + * version 체크를 즉시 수행하도록 합니다. + *
+ */ + void flush(); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategy.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategy.java new file mode 100644 index 000000000..883ab15bd --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategy.java @@ -0,0 +1,23 @@ +package com.loopers.domain.coupon.discount; + +/** + * 쿠폰 할인 계산 전략 인터페이스. + *+ * 전략 패턴을 사용하여 쿠폰 타입별 할인 계산 로직을 분리합니다. + * 새로운 쿠폰 타입이 추가되어도 기존 코드를 수정하지 않고 확장할 수 있습니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface CouponDiscountStrategy { + /** + * 주문 금액에 쿠폰을 적용하여 할인 금액을 계산합니다. + * + * @param orderAmount 주문 금액 + * @param discountValue 할인 값 (쿠폰 타입에 따라 의미가 다름) + * @return 할인 금액 + */ + Integer calculateDiscountAmount(Integer orderAmount, Integer discountValue); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategyFactory.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategyFactory.java new file mode 100644 index 000000000..36bc98a7f --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/CouponDiscountStrategyFactory.java @@ -0,0 +1,53 @@ +package com.loopers.domain.coupon.discount; + +import com.loopers.domain.coupon.CouponType; +import org.springframework.stereotype.Component; + +import java.util.Map; + +/** + * 쿠폰 할인 계산 전략 팩토리. + *+ * 쿠폰 타입에 따라 적절한 할인 계산 전략을 반환합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +public class CouponDiscountStrategyFactory { + private final Map+ * 고정 금액을 할인하며, 할인 금액이 주문 금액을 초과하지 않도록 보장합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +public class FixedAmountDiscountStrategy implements CouponDiscountStrategy { + /** + * {@inheritDoc} + *+ * 정액 쿠폰: 할인 금액이 주문 금액을 초과하지 않도록 제한합니다. + *
+ * + * @param orderAmount 주문 금액 + * @param discountValue 할인 금액 + * @return 할인 금액 (주문 금액을 초과하지 않음) + */ + @Override + public Integer calculateDiscountAmount(Integer orderAmount, Integer discountValue) { + // 할인 금액이 주문 금액을 초과하지 않도록 + return Math.min(discountValue, orderAmount); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/PercentageDiscountStrategy.java b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/PercentageDiscountStrategy.java new file mode 100644 index 000000000..c8b0a87e8 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/coupon/discount/PercentageDiscountStrategy.java @@ -0,0 +1,32 @@ +package com.loopers.domain.coupon.discount; + +import org.springframework.stereotype.Component; + +/** + * 정률 쿠폰 할인 계산 전략. + *+ * 주문 금액의 일정 비율을 할인합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +public class PercentageDiscountStrategy implements CouponDiscountStrategy { + /** + * {@inheritDoc} + *+ * 정률 쿠폰: 주문 금액의 할인 비율만큼 할인합니다. + *
+ * + * @param orderAmount 주문 금액 + * @param discountValue 할인 비율 (0-100) + * @return 할인 금액 + */ + @Override + public Integer calculateDiscountAmount(Integer orderAmount, Integer discountValue) { + // 주문 금액의 할인 비율만큼 할인 + return (int) Math.round(orderAmount * discountValue / 100.0); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/like/Like.java b/apps/commerce-api/src/main/java/com/loopers/domain/like/Like.java new file mode 100644 index 000000000..d6d78bd1b --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/like/Like.java @@ -0,0 +1,62 @@ +package com.loopers.domain.like; + +import com.loopers.domain.BaseEntity; +import jakarta.persistence.Column; +import jakarta.persistence.Entity; +import jakarta.persistence.Table; +import jakarta.persistence.UniqueConstraint; +import lombok.AccessLevel; +import lombok.Getter; +import lombok.NoArgsConstructor; + +/** + * 좋아요 도메인 엔티티. + *+ * 사용자와 상품 간의 좋아요 관계를 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table( + name = "`like`", + uniqueConstraints = { + @UniqueConstraint( + name = "uk_like_user_product", + columnNames = {"ref_user_id", "ref_product_id"} + ) + } +) +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Like extends BaseEntity { + @Column(name = "ref_user_id", nullable = false) + private Long userId; + + @Column(name = "ref_product_id", nullable = false) + private Long productId; + + /** + * Like 인스턴스를 생성합니다. + * + * @param userId 사용자 ID + * @param productId 상품 ID + */ + public Like(Long userId, Long productId) { + this.userId = userId; + this.productId = productId; + } + + /** + * Like 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param userId 사용자 ID + * @param productId 상품 ID + * @return 생성된 Like 인스턴스 + */ + public static Like of(Long userId, Long productId) { + return new Like(userId, productId); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEvent.java b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEvent.java new file mode 100644 index 000000000..36778dab5 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEvent.java @@ -0,0 +1,94 @@ +package com.loopers.domain.like; + +import java.time.LocalDateTime; + +/** + * 좋아요 도메인 이벤트. + *+ * 좋아요 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public class LikeEvent { + + /** + * 좋아요 추가 이벤트. + *+ * 좋아요가 추가되었을 때 발행되는 이벤트입니다. + *
+ * + * @param userId 사용자 ID (Long - User.id) + * @param productId 상품 ID + * @param occurredAt 이벤트 발생 시각 + */ + public record LikeAdded( + Long userId, + Long productId, + LocalDateTime occurredAt + ) { + public LikeAdded { + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (productId == null) { + throw new IllegalArgumentException("productId는 필수입니다."); + } + } + + /** + * Like 엔티티로부터 LikeAdded 이벤트를 생성합니다. + * + * @param like 좋아요 엔티티 + * @return LikeAdded 이벤트 + */ + public static LikeAdded from(Like like) { + return new LikeAdded( + like.getUserId(), + like.getProductId(), + LocalDateTime.now() + ); + } + } + + /** + * 좋아요 취소 이벤트. + *+ * 좋아요가 취소되었을 때 발행되는 이벤트입니다. + *
+ * + * @param userId 사용자 ID (Long - User.id) + * @param productId 상품 ID + * @param occurredAt 이벤트 발생 시각 + */ + public record LikeRemoved( + Long userId, + Long productId, + LocalDateTime occurredAt + ) { + public LikeRemoved { + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (productId == null) { + throw new IllegalArgumentException("productId는 필수입니다."); + } + } + + /** + * Like 엔티티로부터 LikeRemoved 이벤트를 생성합니다. + * + * @param like 좋아요 엔티티 + * @return LikeRemoved 이벤트 + */ + public static LikeRemoved from(Like like) { + return new LikeRemoved( + like.getUserId(), + like.getProductId(), + LocalDateTime.now() + ); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEventPublisher.java b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEventPublisher.java new file mode 100644 index 000000000..cc9e6bdf8 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeEventPublisher.java @@ -0,0 +1,29 @@ +package com.loopers.domain.like; + +/** + * 좋아요 도메인 이벤트 발행 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface LikeEventPublisher { + + /** + * 좋아요 추가 이벤트를 발행합니다. + * + * @param event 좋아요 추가 이벤트 + */ + void publish(LikeEvent.LikeAdded event); + + /** + * 좋아요 취소 이벤트를 발행합니다. + * + * @param event 좋아요 취소 이벤트 + */ + void publish(LikeEvent.LikeRemoved event); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeRepository.java new file mode 100644 index 000000000..96b09f43e --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/like/LikeRepository.java @@ -0,0 +1,67 @@ +package com.loopers.domain.like; + +import java.util.List; +import java.util.Map; +import java.util.Optional; + +/** + * Like 엔티티에 대한 저장소 인터페이스. + *+ * 좋아요 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface LikeRepository { + /** + * 좋아요를 저장합니다. + * + * @param like 저장할 좋아요 + * @return 저장된 좋아요 + */ + Like save(Like like); + + /** + * 사용자 ID와 상품 ID로 좋아요를 조회합니다. + * + * @param userId 사용자 ID + * @param productId 상품 ID + * @return 조회된 좋아요를 담은 Optional + */ + Optional+ * 비동기 집계 스케줄러에서 사용됩니다. + *
+ * + * @return 상품 ID를 키로, 좋아요 수를 값으로 하는 Map + */ + Map+ * 주문의 상태, 총액, 주문 아이템을 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table(name = "`order`") +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Order extends BaseEntity { + @Column(name = "ref_user_id", nullable = false) + private Long userId; + + @Enumerated(EnumType.STRING) + @Column(name = "status", nullable = false) + private OrderStatus status; + + @Column(name = "total_amount", nullable = false) + private Integer totalAmount; + + @Column(name = "coupon_code", length = 50) + private String couponCode; + + @Column(name = "discount_amount") + private Integer discountAmount; + + @JdbcTypeCode(SqlTypes.JSON) + @Column(name = "items", nullable = false, columnDefinition = "json") + private List+ * 주문 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ */ +public class OrderEvent { + + /** + * 주문 생성 이벤트. + *+ * 주문이 생성되었을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param couponCode 쿠폰 코드 (null 가능) + * @param subtotal 주문 소계 (쿠폰 할인 전 금액) + * @param usedPointAmount 사용할 포인트 금액 + * @param orderItems 주문 아이템 목록 (재고 차감용) + * @param createdAt 이벤트 발생 시각 + */ + public record OrderCreated( + Long orderId, + Long userId, + String couponCode, + Integer subtotal, + Long usedPointAmount, + List+ * 주문이 완료되었을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param totalAmount 주문 총액 + * @param completedAt 주문 완료 시각 + */ + public record OrderCompleted( + Long orderId, + Long userId, + Long totalAmount, + LocalDateTime completedAt + ) { + public OrderCompleted { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (totalAmount == null || totalAmount < 0) { + throw new IllegalArgumentException("totalAmount는 0 이상이어야 합니다."); + } + } + + /** + * Order 엔티티로부터 OrderCompleted 이벤트를 생성합니다. + * + * @param order 주문 엔티티 + * @return OrderCompleted 이벤트 + */ + public static OrderCompleted from(Order order) { + return new OrderCompleted( + order.getId(), + order.getUserId(), + order.getTotalAmount().longValue(), + LocalDateTime.now() + ); + } + } + + /** + * 주문 취소 이벤트. + *+ * 주문이 취소되었을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param reason 취소 사유 + * @param orderItems 주문 아이템 목록 (재고 원복용) + * @param refundPointAmount 환불할 포인트 금액 + * @param canceledAt 주문 취소 시각 + */ + public record OrderCanceled( + Long orderId, + Long userId, + String reason, + List+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface OrderEventPublisher { + + /** + * 주문 생성 이벤트를 발행합니다. + * + * @param event 주문 생성 이벤트 + */ + void publish(OrderEvent.OrderCreated event); + + /** + * 주문 완료 이벤트를 발행합니다. + * + * @param event 주문 완료 이벤트 + */ + void publish(OrderEvent.OrderCompleted event); + + /** + * 주문 취소 이벤트를 발행합니다. + * + * @param event 주문 취소 이벤트 + */ + void publish(OrderEvent.OrderCanceled event); +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderItem.java b/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderItem.java new file mode 100644 index 000000000..0b38e00b9 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderItem.java @@ -0,0 +1,55 @@ +package com.loopers.domain.order; + +import jakarta.persistence.Embeddable; +import lombok.EqualsAndHashCode; +import lombok.Getter; + +/** + * 주문 아이템 Value Object. + *+ * 주문에 포함된 상품 정보와 수량을 나타냅니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Getter +@EqualsAndHashCode +public class OrderItem { + private Long productId; + private String name; + private Integer price; + private Integer quantity; + + protected OrderItem() { + } + + /** + * OrderItem 인스턴스를 생성합니다. + * + * @param productId 상품 ID + * @param name 상품 이름 + * @param price 상품 가격 + * @param quantity 수량 + */ + public OrderItem(Long productId, String name, Integer price, Integer quantity) { + this.productId = productId; + this.name = name; + this.price = price; + this.quantity = quantity; + } + + /** + * OrderItem 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param productId 상품 ID + * @param name 상품 이름 + * @param price 상품 가격 + * @param quantity 수량 + * @return 생성된 OrderItem 인스턴스 + */ + public static OrderItem of(Long productId, String name, Integer price, Integer quantity) { + return new OrderItem(productId, name, price, quantity); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderRepository.java new file mode 100644 index 000000000..10b80fc16 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/order/OrderRepository.java @@ -0,0 +1,47 @@ +package com.loopers.domain.order; + +import java.util.List; +import java.util.Optional; + +/** + * 주문 저장소 인터페이스. + *+ * Order 엔티티의 영속성 계층 접근을 추상화합니다. + *
+ */ +public interface OrderRepository { + + /** + * 주문을 저장합니다. + * + * @param order 저장할 주문 + * @return 저장된 주문 + */ + Order save(Order order); + + /** + * 주문 ID로 주문을 조회합니다. + * + * @param orderId 조회할 주문 ID + * @return 조회된 주문 + */ + Optional+ * Transactional Outbox Pattern을 구현하기 위한 엔티티입니다. + * 도메인 트랜잭션과 같은 트랜잭션에서 이벤트를 저장하고, + * 별도 프로세스가 이를 읽어 Kafka로 발행합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table(name = "outbox_event", + indexes = { + @Index(name = "idx_status_created", columnList = "status, created_at") + }, + uniqueConstraints = { + @UniqueConstraint( + name = "uk_aggregate_version", + columnNames = {"aggregate_id", "aggregate_type", "version"} + ) + } +) +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class OutboxEvent { + + @Id + @GeneratedValue(strategy = GenerationType.IDENTITY) + @Column(name = "id") + private Long id; + + @Column(name = "event_id", nullable = false, unique = true, length = 255) + private String eventId; + + @Column(name = "event_type", nullable = false, length = 100) + private String eventType; + + @Column(name = "aggregate_id", nullable = false, length = 255) + private String aggregateId; + + @Column(name = "aggregate_type", nullable = false, length = 100) + private String aggregateType; + + @Column(name = "payload", nullable = false, columnDefinition = "TEXT") + private String payload; + + @Column(name = "topic", nullable = false, length = 255) + private String topic; + + @Column(name = "partition_key", length = 255) + private String partitionKey; + + @Column(name = "version") + private Long version; + + @Enumerated(EnumType.STRING) + @Column(name = "status", nullable = false, length = 50) + private OutboxStatus status; + + @Column(name = "created_at", nullable = false) + private LocalDateTime createdAt; + + @Column(name = "published_at") + private LocalDateTime publishedAt; + + @Builder + public OutboxEvent( + String eventId, + String eventType, + String aggregateId, + String aggregateType, + String payload, + String topic, + String partitionKey, + Long version + ) { + this.eventId = eventId; + this.eventType = eventType; + this.aggregateId = aggregateId; + this.aggregateType = aggregateType; + this.payload = payload; + this.topic = topic; + this.partitionKey = partitionKey; + this.version = version; + this.status = OutboxStatus.PENDING; + this.createdAt = LocalDateTime.now(); + } + + /** + * 이벤트를 발행 완료 상태로 변경합니다. + */ + public void markAsPublished() { + this.status = OutboxStatus.PUBLISHED; + this.publishedAt = LocalDateTime.now(); + } + + /** + * 이벤트를 실패 상태로 변경합니다. + */ + public void markAsFailed() { + this.status = OutboxStatus.FAILED; + } + + /** + * Outbox 이벤트 상태. + */ + public enum OutboxStatus { + PENDING, // 발행 대기 중 + PUBLISHED, // 발행 완료 + FAILED // 발행 실패 + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/outbox/OutboxEventRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/outbox/OutboxEventRepository.java new file mode 100644 index 000000000..fbf574688 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/outbox/OutboxEventRepository.java @@ -0,0 +1,51 @@ +package com.loopers.domain.outbox; + +import java.util.List; + +/** + * OutboxEvent 저장소 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 인터페이스를 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface OutboxEventRepository { + + /** + * Outbox 이벤트를 저장합니다. + * + * @param outboxEvent 저장할 Outbox 이벤트 + * @return 저장된 Outbox 이벤트 + */ + OutboxEvent save(OutboxEvent outboxEvent); + + /** + * 발행 대기 중인 이벤트 목록을 조회합니다. + * + * @param limit 조회할 최대 개수 + * @return 발행 대기 중인 이벤트 목록 + */ + List+ * 같은 집계에 대한 이벤트의 최신 버전을 조회하여 순차적인 버전 관리를 위해 사용됩니다. + *
+ * + * @param aggregateId 집계 ID (예: productId, orderId) + * @param aggregateType 집계 타입 (예: "Product", "Order") + * @return 최신 버전 (없으면 0L) + */ + Long findLatestVersionByAggregateId(String aggregateId, String aggregateType); +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/CardType.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/CardType.java new file mode 100644 index 000000000..ea3ab7d43 --- /dev/null +++ b/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 +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/Payment.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/Payment.java new file mode 100644 index 000000000..4a2c4c9e8 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/Payment.java @@ -0,0 +1,374 @@ +package com.loopers.domain.payment; + +import com.loopers.domain.BaseEntity; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import jakarta.persistence.*; +import lombok.AccessLevel; +import lombok.Getter; +import lombok.NoArgsConstructor; + +import java.time.LocalDateTime; + +/** + * 결제 도메인 엔티티. + *+ * 결제의 상태, 금액, 포인트 사용 정보를 관리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table( + name = "payment", + uniqueConstraints = { + @UniqueConstraint(name = "uk_payment_order_id", columnNames = "ref_order_id") + }, + indexes = { + @Index(name = "idx_payment_order_id", columnList = "ref_order_id"), + @Index(name = "idx_payment_user_id", columnList = "ref_user_id"), + @Index(name = "idx_payment_status", columnList = "status") + } +) +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Payment extends BaseEntity { + + @Column(name = "ref_order_id", nullable = false) + private Long orderId; + + @Column(name = "ref_user_id", nullable = false) + private Long userId; + + @Column(name = "total_amount", nullable = false) + private Long totalAmount; + + @Column(name = "used_point", nullable = false) + private Long usedPoint; + + @Column(name = "paid_amount", nullable = false) + private Long paidAmount; + + @Enumerated(EnumType.STRING) + @Column(name = "status", nullable = false) + private PaymentStatus status; + + @Enumerated(EnumType.STRING) + @Column(name = "card_type") + private CardType cardType; + + @Column(name = "card_no") + private String cardNo; + + @Column(name = "failure_reason", length = 500) + private String failureReason; + + @Column(name = "pg_requested_at", nullable = false) + private LocalDateTime pgRequestedAt; + + @Column(name = "pg_completed_at") + private LocalDateTime pgCompletedAt; + + /** + * 카드 결제용 Payment를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param cardType 카드 타입 + * @param cardNo 카드 번호 + * @param amount 결제 금액 + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static Payment of( + Long orderId, + Long userId, + CardType cardType, + String cardNo, + Long amount, + LocalDateTime requestedAt + ) { + validateOrderId(orderId); + validateUserId(userId); + validateCardType(cardType); + validateCardNo(cardNo); + validateAmount(amount); + validateRequestedAt(requestedAt); + + Payment payment = new Payment(); + payment.orderId = orderId; + payment.userId = userId; + payment.totalAmount = amount; + payment.usedPoint = 0L; + payment.paidAmount = amount; + payment.status = PaymentStatus.PENDING; + payment.cardType = cardType; + payment.cardNo = cardNo; + payment.pgRequestedAt = requestedAt; + + return payment; + } + + /** + * 포인트 결제용 Payment를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param totalAmount 총 결제 금액 + * @param usedPoint 사용 포인트 + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static Payment of( + Long orderId, + Long userId, + Long totalAmount, + Long usedPoint, + LocalDateTime requestedAt + ) { + return of(orderId, userId, totalAmount, usedPoint, null, null, requestedAt); + } + + /** + * 포인트와 카드 혼합 결제용 Payment를 생성합니다. + *+ * 포인트와 쿠폰 할인을 적용한 후 남은 금액을 카드로 결제하는 경우 사용합니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param totalAmount 총 결제 금액 + * @param usedPoint 사용 포인트 + * @param cardType 카드 타입 (paidAmount > 0일 때만 필수) + * @param cardNo 카드 번호 (paidAmount > 0일 때만 필수) + * @param requestedAt PG 요청 시각 + * @return 생성된 Payment 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static Payment of( + Long orderId, + Long userId, + Long totalAmount, + Long usedPoint, + CardType cardType, + String cardNo, + LocalDateTime requestedAt + ) { + validateOrderId(orderId); + validateUserId(userId); + validateAmount(totalAmount); + validateUsedPoint(usedPoint); + validateRequestedAt(requestedAt); + + Long paidAmount = totalAmount - usedPoint; + validatePaidAmount(paidAmount); + + // paidAmount > 0이면 카드 정보 필수 + if (paidAmount > 0) { + if (cardType == null || cardNo == null || cardNo.isBlank()) { + throw new CoreException(ErrorType.BAD_REQUEST, + "포인트와 쿠폰만으로 결제할 수 없습니다. 카드 정보를 입력해주세요."); + } + } + + Payment payment = new Payment(); + payment.orderId = orderId; + payment.userId = userId; + payment.totalAmount = totalAmount; + payment.usedPoint = usedPoint; + payment.paidAmount = paidAmount; + payment.status = (paidAmount == 0L) ? PaymentStatus.SUCCESS : PaymentStatus.PENDING; + payment.cardType = cardType; // paidAmount > 0일 때만 설정 + payment.cardNo = cardNo; // paidAmount > 0일 때만 설정 + payment.pgRequestedAt = requestedAt; + + return payment; + } + + /** + * 결제를 SUCCESS 상태로 전이합니다. + *+ * 멱등성 보장: 이미 SUCCESS 상태인 경우 아무 작업도 하지 않습니다. + *
+ * + * @param completedAt PG 완료 시각 + * @throws CoreException PENDING 상태가 아닌 경우 (SUCCESS는 제외) + */ + public void toSuccess(LocalDateTime completedAt) { + if (status == PaymentStatus.SUCCESS) { + // 멱등성: 이미 성공 상태면 아무 작업도 하지 않음 + return; + } + if (status != PaymentStatus.PENDING) { + throw new CoreException(ErrorType.BAD_REQUEST, "결제 대기 상태에서만 성공으로 전이할 수 있습니다."); + } + this.status = PaymentStatus.SUCCESS; + this.pgCompletedAt = completedAt; + } + + /** + * 결제를 FAILED 상태로 전이합니다. + *+ * 멱등성 보장: 이미 FAILED 상태인 경우 아무 작업도 하지 않습니다. + *
+ * + * @param failureReason 실패 사유 + * @param completedAt PG 완료 시각 + * @throws CoreException PENDING 상태가 아닌 경우 (FAILED는 제외) + */ + public void toFailed(String failureReason, LocalDateTime completedAt) { + if (status == PaymentStatus.FAILED) { + // 멱등성: 이미 실패 상태면 아무 작업도 하지 않음 + return; + } + if (status != PaymentStatus.PENDING) { + throw new CoreException(ErrorType.BAD_REQUEST, "결제 대기 상태에서만 실패로 전이할 수 있습니다."); + } + this.status = PaymentStatus.FAILED; + this.failureReason = failureReason; + this.pgCompletedAt = completedAt; + } + + /** + * 결제가 완료되었는지 확인합니다. + * + * @return 완료 여부 + */ + public boolean isCompleted() { + return status.isCompleted(); + } + + /** + * 결제가 대기 상태인지 확인합니다. + * + * @return 대기 상태이면 true, 아니면 false + */ + public boolean isPending() { + return status == PaymentStatus.PENDING; + } + + /** + * 결제가 성공 상태인지 확인합니다. + * + * @return 성공 상태이면 true, 아니면 false + */ + public boolean isSuccess() { + return status.isSuccess(); + } + + /** + * 결제가 실패 상태인지 확인합니다. + * + * @return 실패 상태이면 true, 아니면 false + */ + public boolean isFailed() { + return status == PaymentStatus.FAILED; + } + + /** + * 쿠폰 할인 금액을 적용하여 결제 금액을 업데이트합니다. + *+ * 쿠폰 할인이 적용된 후 Order의 totalAmount가 업데이트되면, + * Payment의 totalAmount도 동기화하기 위해 호출됩니다. + *
+ *+ * 주의사항: + *
+ * 결제 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ */ +public class PaymentEvent { + + /** + * 결제 완료 이벤트. + *+ * 결제가 성공적으로 완료되었을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param paymentId 결제 ID + * @param transactionKey 트랜잭션 키 (null 가능 - PG 응답 전에는 없을 수 있음) + * @param completedAt 결제 완료 시각 + */ + public record PaymentCompleted( + Long orderId, + Long paymentId, + String transactionKey, + LocalDateTime completedAt + ) { + public PaymentCompleted { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (paymentId == null) { + throw new IllegalArgumentException("paymentId는 필수입니다."); + } + } + + /** + * Payment 엔티티와 transactionKey로부터 PaymentCompleted 이벤트를 생성합니다. + * + * @param payment 결제 엔티티 + * @param transactionKey 트랜잭션 키 (null 가능) + * @return PaymentCompleted 이벤트 + */ + public static PaymentCompleted from(Payment payment, String transactionKey) { + return new PaymentCompleted( + payment.getOrderId(), + payment.getId(), + transactionKey, + payment.getPgCompletedAt() != null ? payment.getPgCompletedAt() : LocalDateTime.now() + ); + } + } + + /** + * 결제 실패 이벤트. + *+ * 결제가 실패했을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param paymentId 결제 ID + * @param transactionKey 트랜잭션 키 (null 가능) + * @param reason 실패 사유 + * @param refundPointAmount 환불할 포인트 금액 + * @param failedAt 결제 실패 시각 + */ + public record PaymentFailed( + Long orderId, + Long paymentId, + String transactionKey, + String reason, + Long refundPointAmount, + LocalDateTime failedAt + ) { + public PaymentFailed { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (paymentId == null) { + throw new IllegalArgumentException("paymentId는 필수입니다."); + } + if (reason == null || reason.isBlank()) { + throw new IllegalArgumentException("reason은 필수입니다."); + } + if (refundPointAmount == null || refundPointAmount < 0) { + throw new IllegalArgumentException("refundPointAmount는 0 이상이어야 합니다."); + } + } + + /** + * Payment 엔티티와 transactionKey로부터 PaymentFailed 이벤트를 생성합니다. + * + * @param payment 결제 엔티티 + * @param reason 실패 사유 + * @param transactionKey 트랜잭션 키 (null 가능) + * @return PaymentFailed 이벤트 + */ + public static PaymentFailed from(Payment payment, String reason, String transactionKey) { + return new PaymentFailed( + payment.getOrderId(), + payment.getId(), + transactionKey, + reason, + payment.getUsedPoint(), + payment.getPgCompletedAt() != null ? payment.getPgCompletedAt() : LocalDateTime.now() + ); + } + } + + /** + * 결제 요청 이벤트. + *+ * 주문에 대한 결제를 요청할 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (String - User.userId, PG 요청용) + * @param userEntityId 사용자 엔티티 ID (Long - User.id, Payment 엔티티용) + * @param totalAmount 주문 총액 + * @param usedPointAmount 사용된 포인트 금액 + * @param cardType 카드 타입 (null 가능) + * @param cardNo 카드 번호 (null 가능) + * @param occurredAt 이벤트 발생 시각 + */ + public record PaymentRequested( + Long orderId, + String userId, + Long userEntityId, + Long totalAmount, + Long usedPointAmount, + String cardType, + String cardNo, + LocalDateTime occurredAt + ) { + public PaymentRequested { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null || userId.isBlank()) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (userEntityId == null) { + throw new IllegalArgumentException("userEntityId는 필수입니다."); + } + if (totalAmount == null || totalAmount < 0) { + throw new IllegalArgumentException("totalAmount는 0 이상이어야 합니다."); + } + if (usedPointAmount == null || usedPointAmount < 0) { + throw new IllegalArgumentException("usedPointAmount는 0 이상이어야 합니다."); + } + } + + /** + * 결제 요청 이벤트를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID (String - User.userId) + * @param userEntityId 사용자 엔티티 ID (Long - User.id) + * @param totalAmount 주문 총액 + * @param usedPointAmount 사용된 포인트 금액 + * @param cardType 카드 타입 (null 가능) + * @param cardNo 카드 번호 (null 가능) + * @return PaymentRequested 이벤트 + */ + public static PaymentRequested of( + Long orderId, + String userId, + Long userEntityId, + Long totalAmount, + Long usedPointAmount, + String cardType, + String cardNo + ) { + return new PaymentRequested( + orderId, + userId, + userEntityId, + totalAmount, + usedPointAmount, + cardType, + cardNo, + LocalDateTime.now() + ); + } + + /** + * 마스킹된 카드 번호를 반환합니다. + *+ * PII 보호를 위해 카드 번호의 중간 부분을 마스킹합니다. + * 마지막 4자리만 표시하고 나머지는 *로 마스킹합니다. + * 예: "4111-1234-5678-9010" -> "****-****-****-9010" + * "4111123456789010" -> "************9010" + *
+ * + * @return 마스킹된 카드 번호 (cardNo가 null이거나 비어있으면 null 반환) + */ + public String maskedCardNo() { + if (cardNo == null || cardNo.isBlank()) { + return null; + } + + // 숫자만 추출 + String digitsOnly = cardNo.replaceAll("[^0-9]", ""); + + if (digitsOnly.length() < 4) { + // 카드 번호가 너무 짧으면 전체 마스킹 + return "****"; + } + + // 마지막 4자리 추출 + String lastFour = digitsOnly.substring(digitsOnly.length() - 4); + + // 원본에 하이픈이 있었다면 하이픈 패턴 유지 + if (cardNo.contains("-")) { + // 하이픈으로 구분된 각 부분 처리 + String[] parts = cardNo.split("-"); + StringBuilder result = new StringBuilder(); + + for (int i = 0; i < parts.length; i++) { + if (i > 0) { + result.append("-"); + } + + String part = parts[i].replaceAll("[^0-9]", ""); + if (i == parts.length - 1 && part.length() >= 4) { + // 마지막 부분은 마지막 4자리만 표시 + result.append("*".repeat(part.length() - 4)).append(lastFour); + } else { + // 중간 부분은 모두 마스킹 + result.append("*".repeat(part.length())); + } + } + return result.toString(); + } else { + // 하이픈이 없으면 마스킹된 부분과 마지막 4자리만 반환 + int maskedLength = digitsOnly.length() - 4; + return "*".repeat(maskedLength) + lastFour; + } + } + + /** + * 로깅 및 이벤트 저장 시 사용할 수 있도록 마스킹된 정보를 포함한 문자열을 반환합니다. + *+ * PII 보호를 위해 cardNo는 마스킹된 버전으로 출력됩니다. + *
+ * + * @return 마스킹된 정보를 포함한 문자열 표현 + */ + @Override + public String toString() { + return String.format( + "PaymentRequested[orderId=%d, userId='%s', userEntityId=%d, totalAmount=%d, usedPointAmount=%d, cardType='%s', cardNo='%s', occurredAt=%s]", + orderId, + userId, + userEntityId, + totalAmount, + usedPointAmount, + cardType, + maskedCardNo(), + occurredAt + ); + } + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentEventPublisher.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentEventPublisher.java new file mode 100644 index 000000000..f8f6e2687 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentEventPublisher.java @@ -0,0 +1,35 @@ +package com.loopers.domain.payment; + +/** + * 결제 도메인 이벤트 발행 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface PaymentEventPublisher { + + /** + * 결제 완료 이벤트를 발행합니다. + * + * @param event 결제 완료 이벤트 + */ + void publish(PaymentEvent.PaymentCompleted event); + + /** + * 결제 실패 이벤트를 발행합니다. + * + * @param event 결제 실패 이벤트 + */ + void publish(PaymentEvent.PaymentFailed event); + + /** + * 결제 요청 이벤트를 발행합니다. + * + * @param event 결제 요청 이벤트 + */ + void publish(PaymentEvent.PaymentRequested event); +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentFailureType.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentFailureType.java new file mode 100644 index 000000000..4a41411aa --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentFailureType.java @@ -0,0 +1,80 @@ +package com.loopers.domain.payment; + +import java.util.Set; + +/** + * 결제 실패 유형. + *+ * 결제 실패를 비즈니스 실패와 외부 시스템 장애로 구분합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public enum PaymentFailureType { + /** + * 비즈니스 실패: 주문 취소 필요 + * 예: 카드 한도 초과, 잘못된 카드 번호 등 + */ + BUSINESS_FAILURE, + + /** + * 외부 시스템 장애: 주문 PENDING 상태 유지 + * 예: CircuitBreaker Open, 서버 오류, 타임아웃 등 + */ + EXTERNAL_SYSTEM_FAILURE; + + private static final Set+ * 비즈니스 실패 예시: + *
+ * 외부 시스템 장애 예시: + *
+ * 도메인 계층에 정의하여 DIP를 준수합니다. + * 인프라 계층이 이 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface PaymentGateway { + /** + * PG 결제 요청을 전송합니다. + * + * @param request 결제 요청 값 객체 + * @return 결제 요청 결과 + */ + PaymentRequestResult requestPayment(PaymentRequest request); + + /** + * 결제 상태를 조회합니다. + *+ * 주의: userId는 PG 시스템이 요구하는 사용자 식별자(String)입니다. + * 도메인 모델의 User.id(Long)와는 다른 값입니다. + *
+ * + * @param userId 사용자 ID (PG 시스템이 요구하는 String 형식의 사용자 식별자) + * @param orderId 주문 ID + * @return 결제 상태 + */ + PaymentStatus getPaymentStatus(String userId, Long orderId); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRepository.java new file mode 100644 index 000000000..7d3a73868 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRepository.java @@ -0,0 +1,54 @@ +package com.loopers.domain.payment; + +import java.util.List; +import java.util.Optional; + +/** + * 결제 저장소 인터페이스. + *+ * Payment 엔티티의 영속성 계층 접근을 추상화합니다. + *
+ */ +public interface PaymentRepository { + + /** + * 결제를 저장합니다. + * + * @param payment 저장할 결제 + * @return 저장된 결제 + */ + Payment save(Payment payment); + + /** + * 결제 ID로 결제를 조회합니다. + * + * @param paymentId 조회할 결제 ID + * @return 조회된 결제 + */ + Optional+ * PG 결제 요청에 필요한 정보를 담는 도메인 값 객체입니다. + * 도메인 계층에 위치하여 DIP를 준수합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public record PaymentRequest( + String userId, + Long orderId, + String cardType, + String cardNo, + Long amount, + String callbackUrl +) { + public PaymentRequest { + 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은 필수입니다."); + } + } + + @Override + public String toString() { + String maskedCardNo = cardNo != null && cardNo.length() > 4 + ? "****" + cardNo.substring(cardNo.length() - 4) + : "****"; + return "PaymentRequest[userId=%s, orderId=%d, cardType=%s, cardNo=%s, amount=%d, callbackUrl=%s]" + .formatted(userId, orderId, cardType, maskedCardNo, amount, callbackUrl); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRequestResult.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRequestResult.java new file mode 100644 index 000000000..9c62dee8c --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentRequestResult.java @@ -0,0 +1,30 @@ +package com.loopers.domain.payment; + +/** + * 결제 요청 결과. + *+ * PG 결제 요청의 결과를 나타내는 도메인 모델입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public sealed interface PaymentRequestResult { + /** + * 결제 요청 성공. + * + * @param transactionKey 트랜잭션 키 + */ + record Success(String transactionKey) implements PaymentRequestResult {} + + /** + * 결제 요청 실패. + * + * @param errorCode 오류 코드 + * @param message 오류 메시지 + * @param isTimeout 타임아웃 여부 + * @param isRetryable 재시도 가능 여부 + */ + record Failure(String errorCode, String message, boolean isTimeout, boolean isRetryable) implements PaymentRequestResult {} +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentResult.java b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentResult.java new file mode 100644 index 000000000..792362f02 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentResult.java @@ -0,0 +1,55 @@ +package com.loopers.domain.payment; + +import java.util.function.Function; + +/** + * 결제 결과 도메인 모델. + *+ * 결제 요청의 성공/실패 결과를 표현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public sealed interface PaymentResult { + + /** + * 성공 결과. + */ + record Success(String transactionKey) implements PaymentResult { + } + + /** + * 실패 결과. + */ + record Failure( + String errorCode, + String message, + boolean isTimeout, + boolean isServerError, + boolean isClientError + ) implements PaymentResult { + } + + /** + * 결과에 따라 처리합니다. + * + * @param successHandler 성공 시 처리 함수 + * @param failureHandler 실패 시 처리 함수 + * @param+ * 상품의 기본 정보(이름, 가격, 재고, 브랜드)를 관리하며, + * 주문 시 재고 차감 기능을 제공합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Entity +@Table( + name = "product", + indexes = { + // 브랜드 필터 + 좋아요 순 정렬 최적화 (복합 인덱스: ref_brand_id, like_count) + @Index(name = "idx_product_brand_likes", columnList = "ref_brand_id,like_count"), + // 브랜드 필터 + 최신순 정렬 최적화 (복합 인덱스: ref_brand_id, created_at) + @Index(name = "idx_product_brand_created", columnList = "ref_brand_id,created_at"), + // 브랜드 필터 + 가격순 정렬 최적화 (복합 인덱스: ref_brand_id, price) + @Index(name = "idx_product_brand_price", columnList = "ref_brand_id,price"), + // 전체 조회 + 좋아요 순 정렬 최적화 + @Index(name = "idx_product_likes", columnList = "like_count"), + // 전체 조회 + 가격순 정렬 최적화 + @Index(name = "idx_product_price", columnList = "price"), + // 전체 조회 + 최신순 정렬 최적화 + @Index(name = "idx_product_created", columnList = "created_at") + } +) +@NoArgsConstructor(access = AccessLevel.PROTECTED) +@Getter +public class Product extends BaseEntity { + @Column(name = "name", nullable = false) + private String name; + + @Column(name = "price", nullable = false) + private Integer price; + + @Column(name = "stock", nullable = false) + private Integer stock; + + @Column(name = "ref_brand_id", nullable = false) + private Long brandId; + + @Column(name = "like_count", nullable = false) + private Long likeCount; + + /** + * Product 인스턴스를 생성합니다. + * + * @param name 상품 이름 (필수) + * @param price 상품 가격 (필수, 0 이상) + * @param stock 상품 재고 (필수, 0 이상) + * @param brandId 브랜드 ID (필수) + * @throws CoreException 유효성 검증 실패 시 + */ + public Product(String name, Integer price, Integer stock, Long brandId) { + validateName(name); + validatePrice(price); + validateStock(stock); + validateBrandId(brandId); + this.name = name; + this.price = price; + this.stock = stock; + this.brandId = brandId; + this.likeCount = 0L; + } + + /** + * Product 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param name 상품 이름 + * @param price 상품 가격 + * @param stock 상품 재고 + * @param brandId 브랜드 ID + * @return 생성된 Product 인스턴스 + * @throws CoreException 유효성 검증 실패 시 + */ + public static Product of(String name, Integer price, Integer stock, Long brandId) { + return new Product(name, price, stock, brandId); + } + + /** + * 재고를 차감합니다. + * 재고는 감소만 가능하며 음수가 되지 않도록 도메인 레벨에서 검증합니다. + * + * @param quantity 차감할 수량 (0보다 커야 함) + * @throws CoreException quantity가 null, 0 이하이거나 재고가 부족할 경우 + */ + public void decreaseStock(Integer quantity) { + validateQuantity(quantity); + if (this.stock < quantity) { + throw new CoreException(ErrorType.BAD_REQUEST, + String.format("재고가 부족합니다. (현재 재고: %d, 요청 수량: %d)", this.stock, quantity)); + } + this.stock -= quantity; + } + + /** + * 재고를 증가시킵니다. + * 주문 취소 시 재고를 원복하는 데 사용됩니다. + * + * @param quantity 증가시킬 수량 (0보다 커야 함) + * @throws CoreException quantity가 null이거나 0 이하일 경우 + */ + public void increaseStock(Integer quantity) { + validateQuantity(quantity); + this.stock += quantity; + } + + /** + * 상품 이름의 유효성을 검증합니다. + * + * @param name 검증할 상품 이름 + * @throws CoreException name이 null이거나 공백일 경우 + */ + private void validateName(String name) { + if (name == null || name.isBlank()) { + throw new CoreException(ErrorType.BAD_REQUEST, "상품 이름은 필수입니다."); + } + } + + /** + * 상품 가격의 유효성을 검증합니다. + * + * @param price 검증할 상품 가격 + * @throws CoreException price가 null이거나 0 미만일 경우 + */ + private void validatePrice(Integer price) { + if (price == null || price < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "상품 가격은 0 이상이어야 합니다."); + } + } + + /** + * 상품 재고의 유효성을 검증합니다. + * + * @param stock 검증할 상품 재고 + * @throws CoreException stock이 null이거나 0 미만일 경우 + */ + private void validateStock(Integer stock) { + if (stock == null || stock < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "상품 재고는 0 이상이어야 합니다."); + } + } + + /** + * 브랜드 ID의 유효성을 검증합니다. + * + * @param brandId 검증할 브랜드 ID + * @throws CoreException brandId가 null일 경우 + */ + private void validateBrandId(Long brandId) { + if (brandId == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "브랜드 ID는 필수입니다."); + } + } + + /** + * 수량의 유효성을 검증합니다. + * + * @param quantity 검증할 수량 + * @throws CoreException quantity가 null이거나 0 이하일 경우 + */ + private void validateQuantity(Integer quantity) { + if (quantity == null || quantity <= 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "수량은 0보다 커야 합니다."); + } + } + + /** + * 좋아요 수를 증가시킵니다. + *+ * 이벤트 기반 집계에서 사용됩니다. + *
+ * + * @throws CoreException 좋아요 수가 음수가 되는 경우 + */ + public void incrementLikeCount() { + if (this.likeCount < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "좋아요 수는 음수가 될 수 없습니다."); + } + this.likeCount++; + } + + /** + * 좋아요 수를 감소시킵니다. + *+ * 이벤트 기반 집계에서 사용됩니다. + *
+ *+ * 멱등성 보장: 좋아요 수가 0인 경우에도 예외를 던지지 않고 그대로 유지합니다. + * 이는 동시성 상황에서 이미 삭제된 좋아요에 대한 이벤트가 중복 처리될 수 있기 때문입니다. + *
+ */ + public void decrementLikeCount() { + if (this.likeCount > 0) { + this.likeCount--; + } + // likeCount가 0인 경우는 이미 삭제된 상태이므로 그대로 유지 (멱등성 보장) + } + + /** + * 좋아요 수를 업데이트합니다. + *+ * 배치 집계나 초기화 시 사용됩니다. + *
+ * + * @param likeCount 업데이트할 좋아요 수 (0 이상) + * @throws CoreException likeCount가 null이거나 음수일 경우 + */ + public void updateLikeCount(Long likeCount) { + if (likeCount == null || likeCount < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "좋아요 수는 0 이상이어야 합니다."); + } + this.likeCount = likeCount; + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetail.java b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetail.java new file mode 100644 index 000000000..24a7e3c4c --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetail.java @@ -0,0 +1,91 @@ +package com.loopers.domain.product; + +import lombok.EqualsAndHashCode; +import lombok.Getter; + +/** + * 상품 상세 정보 Value Object. + *+ * 상품 상세 조회 시 Product, Brand 정보, 좋아요 수를 조합한 결과를 나타냅니다. + * 값으로 식별되며 불변성을 가집니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Getter +@EqualsAndHashCode +public class ProductDetail { + private final Long id; + private final String name; + private final Integer price; + private final Integer stock; + private final Long brandId; + private final String brandName; + private final Long likesCount; + + private ProductDetail(Long id, String name, Integer price, Integer stock, Long brandId, String brandName, Long likesCount) { + this.id = id; + this.name = name; + this.price = price; + this.stock = stock; + this.brandId = brandId; + this.brandName = brandName; + this.likesCount = likesCount; + } + + /** + * ProductDetail 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param id 상품 ID + * @param name 상품 이름 + * @param price 상품 가격 + * @param stock 상품 재고 + * @param brandId 브랜드 ID + * @param brandName 브랜드 이름 + * @param likesCount 좋아요 수 + * @return 생성된 ProductDetail 인스턴스 + */ + public static ProductDetail of(Long id, String name, Integer price, Integer stock, Long brandId, String brandName, Long likesCount) { + return new ProductDetail(id, name, price, stock, brandId, brandName, likesCount); + } + + /** + * Product, 브랜드 이름, 좋아요 수로부터 ProductDetail을 생성하는 정적 팩토리 메서드. + *+ * 상품 상세 조회 시 Product와 브랜드 이름, 좋아요 수를 조합하여 ProductDetail을 생성합니다. + *
+ *+ * Aggregate 경계 준수: Brand Aggregate 엔티티 대신 필요한 값(brandName)만 전달하여 + * Aggregate 간 직접 참조를 피합니다. + *
+ * + * @param product 상품 엔티티 + * @param brandName 브랜드 이름 + * @param likesCount 좋아요 수 + * @return 생성된 ProductDetail 인스턴스 + * @throws IllegalArgumentException product, brandName, likesCount가 null인 경우 + */ + public static ProductDetail from(Product product, String brandName, Long likesCount) { + if (product == null) { + throw new IllegalArgumentException("상품은 null일 수 없습니다."); + } + if (brandName == null) { + throw new IllegalArgumentException("브랜드 이름은 필수입니다."); + } + if (likesCount == null) { + throw new IllegalArgumentException("좋아요 수는 null일 수 없습니다."); + } + + return ProductDetail.of( + product.getId(), + product.getName(), + product.getPrice(), + product.getStock(), + product.getBrandId(), + brandName, + likesCount + ); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetailService.java b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetailService.java new file mode 100644 index 000000000..ef2614040 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductDetailService.java @@ -0,0 +1,53 @@ +package com.loopers.domain.product; + +import com.loopers.domain.brand.Brand; +import org.springframework.stereotype.Component; + +/** + * 상품 상세 정보 조합 도메인 서비스. + *+ * 상품 상세 조회 시 Product와 Brand 정보, 좋아요 수를 조합하는 도메인 로직을 처리합니다. + * 도메인 간 협력 로직(Product + Brand + Like)을 담당합니다. + *
+ *+ * 상태가 없고, 도메인 객체의 협력 중심으로 설계되었습니다. + * Repository 의존성 없이 도메인 객체(Product, Brand, likesCount)를 파라미터로 받아 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +public class ProductDetailService { + + /** + * 상품과 브랜드 정보, 좋아요 수를 조합하여 상품 상세 정보를 생성합니다. + * + * @param product 상품 엔티티 + * @param brand 브랜드 엔티티 + * @param likesCount 좋아요 수 + * @return 조합된 상품 상세 정보 + */ + public ProductDetail combineProductAndBrand(Product product, Brand brand, Long likesCount) { + if (product == null) { + throw new IllegalArgumentException("상품은 null일 수 없습니다."); + } + if (brand == null) { + throw new IllegalArgumentException("브랜드 정보는 필수입니다."); + } + if (likesCount == null) { + throw new IllegalArgumentException("좋아요 수는 null일 수 없습니다."); + } + + return ProductDetail.of( + product.getId(), + product.getName(), + product.getPrice(), + product.getStock(), + product.getBrandId(), + brand.getName(), + likesCount + ); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEvent.java b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEvent.java new file mode 100644 index 000000000..054303b09 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEvent.java @@ -0,0 +1,59 @@ +package com.loopers.domain.product; + +import java.time.LocalDateTime; + +/** + * 상품 도메인 이벤트. + *+ * 상품 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public class ProductEvent { + + /** + * 상품 상세 페이지 조회 이벤트. + *+ * 상품 상세 페이지가 조회되었을 때 발행되는 이벤트입니다. + * 메트릭 집계를 위해 사용됩니다. + *
+ * + * @param productId 상품 ID + * @param userId 사용자 ID (null 가능 - 비로그인 사용자) + * @param occurredAt 이벤트 발생 시각 + */ + public record ProductViewed( + Long productId, + Long userId, + LocalDateTime occurredAt + ) { + public ProductViewed { + if (productId == null) { + throw new IllegalArgumentException("productId는 필수입니다."); + } + } + + /** + * 상품 ID로부터 ProductViewed 이벤트를 생성합니다. + * + * @param productId 상품 ID + * @return ProductViewed 이벤트 + */ + public static ProductViewed from(Long productId) { + return new ProductViewed(productId, null, LocalDateTime.now()); + } + + /** + * 상품 ID와 사용자 ID로부터 ProductViewed 이벤트를 생성합니다. + * + * @param productId 상품 ID + * @param userId 사용자 ID + * @return ProductViewed 이벤트 + */ + public static ProductViewed from(Long productId, Long userId) { + return new ProductViewed(productId, userId, LocalDateTime.now()); + } + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEventPublisher.java b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEventPublisher.java new file mode 100644 index 000000000..0cc60f495 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductEventPublisher.java @@ -0,0 +1,21 @@ +package com.loopers.domain.product; + +/** + * 상품 도메인 이벤트 발행 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface ProductEventPublisher { + + /** + * 상품 상세 페이지 조회 이벤트를 발행합니다. + * + * @param event 상품 조회 이벤트 + */ + void publish(ProductEvent.ProductViewed event); +} diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductRepository.java b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductRepository.java new file mode 100644 index 000000000..425ce977c --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/product/ProductRepository.java @@ -0,0 +1,102 @@ +package com.loopers.domain.product; + +import java.util.List; +import java.util.Optional; + +/** + * Product 엔티티에 대한 저장소 인터페이스. + *+ * 상품 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface ProductRepository { + /** + * 상품을 저장합니다. + * + * @param product 저장할 상품 + * @return 저장된 상품 + */ + Product save(Product product); + + /** + * 상품 ID로 상품을 조회합니다. + * + * @param productId 조회할 상품 ID + * @return 조회된 상품을 담은 Optional + */ + Optional+ * 동시성 제어가 필요한 경우 사용합니다. (예: 재고 차감) + *
+ *+ * Lock 전략: + *
+ * 배치 조회를 통해 N+1 쿼리 문제를 해결합니다. + *
+ * + * @param productIds 조회할 상품 ID 목록 + * @return 조회된 상품 목록 + */ + List+ * 비동기 집계 스케줄러에서 사용됩니다. + *
+ * + * @param productId 상품 ID + * @param likeCount 업데이트할 좋아요 수 + */ + void updateLikeCount(Long productId, Long likeCount); + + /** + * 모든 상품 ID를 조회합니다. + *+ * Spring Batch Reader에서 사용됩니다. + *
+ * + * @return 모든 상품 ID 목록 + */ + List+ * 주간/월간 TOP 100 랭킹을 저장하는 조회 전용 테이블입니다. + *
+ *+ * Materialized View 설계: + *
+ * 인덱스 전략: + *
+ * Materialized View에 저장된 상품 랭킹 데이터를 조회합니다. + *
+ */ +public interface ProductRankRepository { + + /** + * 특정 기간의 랭킹 데이터를 조회합니다. + * + * @param periodType 기간 타입 + * @param periodStartDate 기간 시작일 + * @param limit 조회할 랭킹 수 (기본: 100) + * @return 랭킹 리스트 (rank 오름차순) + */ + List+ * 사용자의 포인트 잔액을 나타내는 불변 값 객체입니다. + * 값으로 식별되며 불변성을 가집니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Embeddable +@Getter +@EqualsAndHashCode +public class Point { + @Column(name = "balance", nullable = false) + private Long value; + + protected Point() { + this.value = 0L; // JPA를 위한 기본 생성자 + } + + /** + * Point 인스턴스를 생성합니다. + * + * @param value 포인트 값 (0 이상이어야 함) + * @throws CoreException value가 null이거나 음수일 경우 + */ + public Point(Long value) { + validateValue(value); + this.value = value; + } + + /** + * Point 인스턴스를 생성하는 정적 팩토리 메서드. + * + * @param value 포인트 값 + * @return 생성된 Point 인스턴스 + * @throws CoreException value가 null이거나 음수일 경우 + */ + public static Point of(Long value) { + return new Point(value); + } + + /** + * 포인트를 더한 새로운 Point 인스턴스를 반환합니다. + * + * @param other 더할 포인트 + * @return 새로운 Point 인스턴스 + * @throws CoreException other가 null일 경우 + */ + public Point add(Point other) { + if (other == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "포인트는 null일 수 없습니다."); + } + return new Point(this.value + other.value); + } + + /** + * 포인트를 뺀 새로운 Point 인스턴스를 반환합니다. + * 포인트는 감소만 가능하며 음수가 되지 않도록 도메인 레벨에서 검증합니다. + * + * @param other 뺄 포인트 + * @return 새로운 Point 인스턴스 + * @throws CoreException other가 null이거나 잔액이 부족할 경우 + */ + public Point subtract(Point other) { + if (other == null) { + throw new CoreException(ErrorType.BAD_REQUEST, "포인트는 null일 수 없습니다."); + } + if (this.value < other.value) { + throw new CoreException(ErrorType.BAD_REQUEST, + String.format("포인트가 부족합니다. (현재 잔액: %d, 요청 금액: %d)", this.value, other.value)); + } + return new Point(this.value - other.value); + } + + /** + * 포인트 값의 유효성을 검증합니다. + * + * @param value 검증할 포인트 값 + * @throws CoreException value가 null이거나 음수일 경우 + */ + private void validateValue(Long value) { + if (value == null || value < 0) { + throw new CoreException(ErrorType.BAD_REQUEST, "포인트는 0 이상이어야 합니다."); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEvent.java b/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEvent.java new file mode 100644 index 000000000..8bba3b8a1 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEvent.java @@ -0,0 +1,114 @@ +package com.loopers.domain.user; + +import java.time.LocalDateTime; + +/** + * 포인트 도메인 이벤트. + *+ * 포인트 도메인의 중요한 상태 변화를 나타내는 이벤트들입니다. + *
+ */ +public class PointEvent { + + /** + * 포인트 사용 이벤트. + *+ * 주문에서 포인트를 사용할 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param usedPointAmount 사용할 포인트 금액 + * @param occurredAt 이벤트 발생 시각 + */ + public record PointUsed( + Long orderId, + Long userId, + Long usedPointAmount, + LocalDateTime occurredAt + ) { + public PointUsed { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (usedPointAmount == null || usedPointAmount < 0) { + throw new IllegalArgumentException("usedPointAmount는 0 이상이어야 합니다."); + } + } + + /** + * OrderCreated 이벤트로부터 PointUsed 이벤트를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param usedPointAmount 사용할 포인트 금액 + * @return PointUsed 이벤트 + */ + public static PointUsed of(Long orderId, Long userId, Long usedPointAmount) { + return new PointUsed( + orderId, + userId, + usedPointAmount, + LocalDateTime.now() + ); + } + } + + /** + * 포인트 사용 실패 이벤트. + *+ * 포인트 사용에 실패했을 때 발행되는 이벤트입니다. + *
+ * + * @param orderId 주문 ID + * @param userId 사용자 ID (Long - User.id) + * @param usedPointAmount 사용 요청 포인트 금액 + * @param failureReason 실패 사유 + * @param failedAt 실패 시각 + */ + public record PointUsedFailed( + Long orderId, + Long userId, + Long usedPointAmount, + String failureReason, + LocalDateTime failedAt + ) { + public PointUsedFailed { + if (orderId == null) { + throw new IllegalArgumentException("orderId는 필수입니다."); + } + if (userId == null) { + throw new IllegalArgumentException("userId는 필수입니다."); + } + if (usedPointAmount == null || usedPointAmount < 0) { + throw new IllegalArgumentException("usedPointAmount는 0 이상이어야 합니다."); + } + if (failureReason == null || failureReason.isBlank()) { + throw new IllegalArgumentException("failureReason는 필수입니다."); + } + } + + /** + * 포인트 사용 실패 정보로부터 PointUsedFailed 이벤트를 생성합니다. + * + * @param orderId 주문 ID + * @param userId 사용자 ID + * @param usedPointAmount 사용 요청 포인트 금액 + * @param failureReason 실패 사유 + * @return PointUsedFailed 이벤트 + */ + public static PointUsedFailed of(Long orderId, Long userId, Long usedPointAmount, String failureReason) { + return new PointUsedFailed( + orderId, + userId, + usedPointAmount, + failureReason, + LocalDateTime.now() + ); + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEventPublisher.java b/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEventPublisher.java new file mode 100644 index 000000000..8b01a7bca --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/user/PointEventPublisher.java @@ -0,0 +1,29 @@ +package com.loopers.domain.user; + +/** + * 포인트 도메인 이벤트 발행 인터페이스. + *+ * DIP를 준수하여 도메인 레이어에서 이벤트 발행 인터페이스를 정의합니다. + * 구현은 인프라 레이어에서 제공됩니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface PointEventPublisher { + + /** + * 포인트 사용 이벤트를 발행합니다. + * + * @param event 포인트 사용 이벤트 + */ + void publish(PointEvent.PointUsed event); + + /** + * 포인트 사용 실패 이벤트를 발행합니다. + * + * @param event 포인트 사용 실패 이벤트 + */ + void publish(PointEvent.PointUsedFailed event); +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/domain/user/User.java b/apps/commerce-api/src/main/java/com/loopers/domain/user/User.java new file mode 100644 index 000000000..b3ed48869 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/domain/user/User.java @@ -0,0 +1,178 @@ +package com.loopers.domain.user; + +import com.loopers.domain.BaseEntity; +import com.loopers.support.error.CoreException; +import com.loopers.support.error.ErrorType; +import jakarta.persistence.Column; +import jakarta.persistence.Embedded; +import jakarta.persistence.Entity; +import jakarta.persistence.Table; +import jakarta.persistence.Enumerated; +import jakarta.persistence.EnumType; +import lombok.Getter; +import lombok.AccessLevel; +import lombok.NoArgsConstructor; + +import java.time.LocalDate; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.regex.Pattern; + +/** + * 사용자 도메인 엔티티. + *+ * 사용자의 기본 정보(ID, 이메일, 생년월일, 성별)를 관리하며, + * 각 필드에 대한 유효성 검증을 수행합니다. + *
+ * + *+ * 사용자 정보의 영속성 계층과의 상호작용을 정의합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface UserRepository { + /** + * 사용자를 저장합니다. + * + * @param user 저장할 사용자 + * @return 저장된 사용자 + */ + User save(User user); + + /** + * 사용자 ID로 사용자를 조회합니다. + * + * @param userId 조회할 사용자 ID + * @return 조회된 사용자, 없으면 null + */ + User findByUserId(String userId); + + /** + * 사용자 ID로 사용자를 조회합니다. (비관적 락) + *+ * 동시성 제어가 필요한 경우 사용합니다. (예: 포인트 차감) + *
+ *+ * Lock 전략: + *
+ * 동시성 제어가 필요한 경우 사용합니다. (예: 포인트 차감) + *
+ *+ * Lock 전략: + *
+ * Spring ApplicationEventPublisher를 사용하여 쿠폰 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class CouponEventPublisherImpl implements CouponEventPublisher { + + private final ApplicationEventPublisher applicationEventPublisher; + + @Override + public void publish(CouponEvent.CouponApplied event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(CouponEvent.CouponApplicationFailed event) { + applicationEventPublisher.publishEvent(event); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/coupon/CouponJpaRepository.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/coupon/CouponJpaRepository.java new file mode 100644 index 000000000..bd4eb6ee9 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/coupon/CouponJpaRepository.java @@ -0,0 +1,26 @@ +package com.loopers.infrastructure.coupon; + +import com.loopers.domain.coupon.Coupon; +import org.springframework.data.jpa.repository.JpaRepository; + +import java.util.Optional; + +/** + * Coupon 엔티티를 위한 Spring Data JPA 리포지토리. + *+ * JpaRepository를 확장하여 기본 CRUD 기능을 제공합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface CouponJpaRepository extends JpaRepository+ * Spring Data JPA를 활용하여 Coupon 엔티티의 + * 영속성 작업을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class CouponRepositoryImpl implements CouponRepository { + private final CouponJpaRepository couponJpaRepository; + + /** + * {@inheritDoc} + */ + @Override + public Coupon save(Coupon coupon) { + return couponJpaRepository.save(coupon); + } + + /** + * {@inheritDoc} + */ + @Override + public Optional+ * JpaRepository를 확장하여 기본 CRUD 기능을 제공합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface UserCouponJpaRepository extends JpaRepository+ * Optimistic Lock을 사용하여 동시성 제어를 보장합니다. + * UserCoupon 엔티티의 @Version 필드를 통해 자동으로 낙관적 락이 적용됩니다. + *
+ *+ * Lock 전략: + *
+ * 동작 원리: + *
+ * Spring Data JPA를 활용하여 UserCoupon 엔티티의 + * 영속성 작업을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class UserCouponRepositoryImpl implements UserCouponRepository { + private final UserCouponJpaRepository userCouponJpaRepository; + + /** + * {@inheritDoc} + */ + @Override + public UserCoupon save(UserCoupon userCoupon) { + return userCouponJpaRepository.save(userCoupon); + } + + /** + * {@inheritDoc} + */ + @Override + public Optional+ * Spring ApplicationEventPublisher를 사용하여 좋아요 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class LikeEventPublisherImpl implements LikeEventPublisher { + + private final ApplicationEventPublisher applicationEventPublisher; + + @Override + public void publish(LikeEvent.LikeAdded event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(LikeEvent.LikeRemoved event) { + applicationEventPublisher.publishEvent(event); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/like/LikeJpaRepository.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/like/LikeJpaRepository.java new file mode 100644 index 000000000..61d335de8 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/like/LikeJpaRepository.java @@ -0,0 +1,71 @@ +package com.loopers.infrastructure.like; + +import com.loopers.domain.like.Like; +import org.springframework.data.jpa.repository.JpaRepository; +import org.springframework.data.jpa.repository.Query; +import org.springframework.data.repository.query.Param; + +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.stream.Collectors; + +/** + * Like 엔티티를 위한 Spring Data JPA 리포지토리. + */ +public interface LikeJpaRepository extends JpaRepository+ * 비동기 집계 스케줄러에서 사용됩니다. + *
+ * + * @return 상품 ID와 좋아요 수의 쌍 목록 + */ + @Query("SELECT l.productId, COUNT(l) FROM Like l GROUP BY l.productId") + List+ * Spring ApplicationEventPublisher를 사용하여 주문 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class OrderEventPublisherImpl implements OrderEventPublisher { + + private final ApplicationEventPublisher applicationEventPublisher; + + @Override + public void publish(OrderEvent.OrderCreated event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(OrderEvent.OrderCompleted event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(OrderEvent.OrderCanceled event) { + applicationEventPublisher.publishEvent(event); + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/order/OrderJpaRepository.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/order/OrderJpaRepository.java new file mode 100644 index 000000000..2e435b981 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/order/OrderJpaRepository.java @@ -0,0 +1,18 @@ +package com.loopers.infrastructure.order; + +import com.loopers.domain.order.Order; +import com.loopers.domain.order.OrderStatus; +import org.springframework.data.jpa.repository.JpaRepository; + +import java.util.List; + +/** + * Order JPA Repository. + */ +public interface OrderJpaRepository extends JpaRepository+ * 주기적으로 Outbox에서 발행 대기 중인 이벤트를 읽어 Kafka로 발행합니다. + * Transactional Outbox Pattern의 Polling 프로세스입니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class OutboxEventPublisher { + + private static final int BATCH_SIZE = 100; + + private final OutboxEventRepository outboxEventRepository; + private final KafkaTemplate+ * 1초마다 실행되어 PENDING 상태의 이벤트를 처리합니다. + *
+ */ + @Scheduled(fixedDelay = 1000) // 1초마다 실행 + @Transactional + public void publishPendingEvents() { + try { + List+ * 멱등성 처리를 위해 `eventId`를 Kafka 메시지 헤더에 포함시킵니다. + *
+ * + * @param event 발행할 Outbox 이벤트 + */ + private void publishEvent(OutboxEvent event) { + try { + // JSON 문자열을 Map으로 역직렬화하여 Kafka로 전송 + // KafkaTemplate의 JsonSerializer가 자동으로 직렬화합니다 + Object payload = objectMapper.readValue(event.getPayload(), Object.class); + + // Kafka 메시지 헤더에 eventId, eventType, version 추가 (멱등성 및 버전 비교 처리용) + var messageBuilder = MessageBuilder + .withPayload(payload) + .setHeader(KafkaHeaders.KEY, event.getPartitionKey()) + .setHeader("eventId", event.getEventId()) + .setHeader("eventType", event.getEventType()); + + // version이 있으면 헤더에 추가 + if (event.getVersion() != null) { + messageBuilder.setHeader("version", event.getVersion()); + } + + var message = messageBuilder.build(); + + // Kafka로 비동기 발행 (콜백에서 상태 업데이트) + kafkaTemplate.send(event.getTopic(), message) + .whenComplete((result, ex) -> handleSendResult(event, result, ex)); + } catch (Exception e) { + log.error("Kafka 이벤트 발행 실패: eventId={}, topic={}", + event.getEventId(), event.getTopic(), e); + throw new RuntimeException("Kafka 이벤트 발행 실패", e); + } + } + + /** + * Kafka 전송 결과를 처리합니다. + */ + private void handleSendResult(OutboxEvent event, SendResult+ * 테스트 가능성을 위해 Thread.sleep을 추상화합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface DelayProvider { + + /** + * 지정된 시간만큼 대기합니다. + * + * @param duration 대기 시간 + * @throws InterruptedException 인터럽트 발생 시 + */ + void delay(Duration duration) throws InterruptedException; +} diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentEventPublisherImpl.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentEventPublisherImpl.java new file mode 100644 index 000000000..dfdfca597 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentEventPublisherImpl.java @@ -0,0 +1,39 @@ +package com.loopers.infrastructure.payment; + +import com.loopers.domain.payment.PaymentEvent; +import com.loopers.domain.payment.PaymentEventPublisher; +import lombok.RequiredArgsConstructor; +import org.springframework.context.ApplicationEventPublisher; +import org.springframework.stereotype.Component; + +/** + * PaymentEventPublisher 인터페이스의 구현체. + *+ * Spring ApplicationEventPublisher를 사용하여 결제 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class PaymentEventPublisherImpl implements PaymentEventPublisher { + + private final ApplicationEventPublisher applicationEventPublisher; + + @Override + public void publish(PaymentEvent.PaymentCompleted event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(PaymentEvent.PaymentFailed event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(PaymentEvent.PaymentRequested event) { + applicationEventPublisher.publishEvent(event); + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewayClient.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewayClient.java new file mode 100644 index 000000000..cf6e1b2d6 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewayClient.java @@ -0,0 +1,84 @@ +package com.loopers.infrastructure.payment; + +import org.springframework.cloud.openfeign.FeignClient; +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.RequestParam; + +/** + * PG 결제 게이트웨이 FeignClient. + *+ * CircuitBreaker, Bulkhead가 적용되어 있습니다. + *
+ *+ * Bulkhead 패턴: + *
+ * Retry 정책: + *
+ * 설계 근거: + *
+ * 도메인 계층의 PaymentGateway 인터페이스를 구현합니다. + * 인프라 관심사(FeignClient 호출, 예외 처리)를 도메인 모델로 변환합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class PaymentGatewayImpl implements PaymentGateway { + + private final PaymentGatewayClient paymentGatewayClient; + private final PaymentGatewaySchedulerClient paymentGatewaySchedulerClient; + private final PaymentGatewayMetrics metrics; + + /** + * PG 결제 요청을 전송합니다. + * + * @param request 결제 요청 값 객체 + * @return 결제 요청 결과 + */ + @Override + @CircuitBreaker(name = "pgCircuit", fallbackMethod = "fallback") + public PaymentRequestResult requestPayment(PaymentRequest request) { + PaymentGatewayDto.PaymentRequest dtoRequest = toDto(request); + PaymentGatewayDto.ApiResponse+ * PG 서버 오류, 타임아웃, Fallback 등의 이벤트를 Prometheus 메트릭으로 기록합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class PaymentGatewayMetrics { + + private final MeterRegistry meterRegistry; + + /** + * PG 서버 오류(5xx) 발생 횟수를 기록합니다. + * + * @param clientName 클라이언트 이름 (paymentGatewayClient, paymentGatewaySchedulerClient) + * @param status HTTP 상태 코드 + */ + public void recordServerError(String clientName, int status) { + meterRegistry.counter( + "payment.gateway.server.error", + "client", clientName, + "status", String.valueOf(status) + ).increment(); + } + + /** + * PG 타임아웃 발생 횟수를 기록합니다. + * + * @param clientName 클라이언트 이름 + */ + public void recordTimeout(String clientName) { + meterRegistry.counter( + "payment.gateway.timeout", + "client", clientName + ).increment(); + } + + /** + * PG 클라이언트 오류(4xx) 발생 횟수를 기록합니다. + * + * @param clientName 클라이언트 이름 + * @param status HTTP 상태 코드 + */ + public void recordClientError(String clientName, int status) { + meterRegistry.counter( + "payment.gateway.client.error", + "client", clientName, + "status", String.valueOf(status) + ).increment(); + } + + /** + * Fallback 호출 횟수를 기록합니다. + * + * @param clientName 클라이언트 이름 + */ + public void recordFallback(String clientName) { + meterRegistry.counter( + "payment.gateway.fallback", + "client", clientName + ).increment(); + } + + /** + * PG 결제 요청 성공 횟수를 기록합니다. + * + * @param clientName 클라이언트 이름 + */ + public void recordSuccess(String clientName) { + meterRegistry.counter( + "payment.gateway.request.success", + "client", clientName + ).increment(); + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewaySchedulerClient.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewaySchedulerClient.java new file mode 100644 index 000000000..01451ab62 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/payment/PaymentGatewaySchedulerClient.java @@ -0,0 +1,69 @@ +package com.loopers.infrastructure.payment; + +import org.springframework.cloud.openfeign.FeignClient; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.RequestHeader; +import org.springframework.web.bind.annotation.RequestParam; + +/** + * PG 결제 게이트웨이 FeignClient (스케줄러 전용). + *+ * 스케줄러에서 사용하는 조회 API에 Retry를 적용합니다. + *
+ *+ * Retry 정책: + *
+ * 설계 근거: + *
+ * 스케줄러에서 사용하며, Retry가 적용됩니다. + *
+ * + * @param userId 사용자 ID (X-USER-ID 헤더) + * @param transactionKey 트랜잭션 키 + * @return 결제 상세 정보 + */ + @GetMapping("/{transactionKey}") + PaymentGatewayDto.ApiResponse+ * 스케줄러에서 사용하며, Retry가 적용됩니다. + *
+ * + * @param userId 사용자 ID (X-USER-ID 헤더) + * @param orderId 주문 ID + * @return 주문별 결제 목록 + */ + @GetMapping + PaymentGatewayDto.ApiResponse+ * Spring ApplicationEventPublisher를 사용하여 상품 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ *+ * 표준 패턴: + *
+ * JpaRepository를 확장하여 기본 CRUD 기능을 제공합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface ProductJpaRepository extends JpaRepository+ * SELECT ... FOR UPDATE를 사용하여 동시성 제어를 보장합니다. + *
+ *+ * Lock 전략: + *
+ * 동작 원리: + *
+ * 비동기 집계 스케줄러에서 사용됩니다. + *
+ * + * @return 모든 상품 ID 목록 + */ + @Query("SELECT p.id FROM Product p") + List+ * Spring Data JPA를 활용하여 Product 엔티티의 + * 영속성 작업을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class ProductRepositoryImpl implements ProductRepository { + private final ProductJpaRepository productJpaRepository; + + /** + * {@inheritDoc} + */ + @Override + public Product save(Product product) { + return productJpaRepository.save(product); + } + + /** + * {@inheritDoc} + */ + @Override + public Optional+ * Materialized View에 저장된 상품 랭킹 데이터를 조회합니다. + *
+ */ +@Slf4j +@Repository +@Transactional(readOnly = true) +public class ProductRankRepositoryImpl implements ProductRankRepository { + + @PersistenceContext + private EntityManager entityManager; + + @Override + public List+ * 콜백이 오지 않은 PENDING 상태의 주문들을 주기적으로 조회하여 + * PG 시스템의 결제 상태 확인 API를 통해 상태를 복구합니다. + *
+ *+ * 동작 원리: + *
+ * 설계 근거: + *
+ * 레이어 위치 근거: + *
+ * 1분마다 실행되어 PENDING 상태인 주문들을 조회하고, + * 각 주문에 대해 PG 결제 상태 확인 API를 호출하여 상태를 복구합니다. + *
+ *+ * 처리 전략: + *
+ * 주기적으로 랭킹 결과를 스냅샷으로 저장하여, Redis 장애 시 Fallback으로 사용할 수 있도록 합니다. + *
+ *+ * 설계 원칙: + *
+ * 주기 선택 근거: + *
+ * 1시간마다 실행되어 오늘의 랭킹을 스냅샷으로 저장합니다. + *
+ */ + @Scheduled(fixedRate = 3600000) // 1시간마다 (3600000ms = 1시간) + public void saveRankingSnapshot() { + LocalDate today = LocalDate.now(ZoneId.of("UTC")); + try { + // 상위 100개 랭킹을 스냅샷으로 저장 (대부분의 사용자가 상위 100개 이내만 조회) + // Redis가 정상일 때만 스냅샷 저장 (예외 발생 시 스킵) + RankingService.RankingsResponse rankings = rankingService.getRankingsFromRedis(today, 0, 100); + + rankingSnapshotService.saveSnapshot(today, rankings); + + log.debug("랭킹 스냅샷 저장 완료: date={}, itemCount={}", today, rankings.items().size()); + } catch (org.springframework.dao.DataAccessException e) { + log.warn("Redis 장애로 인한 랭킹 스냅샷 저장 실패: date={}, error={}", today, e.getMessage()); + // Redis 장애 시 스냅샷 저장 스킵 (다음 스케줄에서 재시도) + } catch (Exception e) { + log.warn("랭킹 스냅샷 저장 실패: date={}", today, e); + // 스냅샷 저장 실패는 다음 스케줄에서 재시도 + } + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/PointEventPublisherImpl.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/PointEventPublisherImpl.java new file mode 100644 index 000000000..5bed86f2e --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/PointEventPublisherImpl.java @@ -0,0 +1,35 @@ +package com.loopers.infrastructure.user; + +import com.loopers.domain.user.PointEvent; +import com.loopers.domain.user.PointEventPublisher; +import lombok.RequiredArgsConstructor; +import org.springframework.context.ApplicationEventPublisher; +import org.springframework.stereotype.Component; + +/** + * PointEventPublisher 인터페이스의 구현체. + *+ * Spring ApplicationEventPublisher를 사용하여 포인트 이벤트를 발행합니다. + * DIP를 준수하여 도메인 인터페이스를 구현합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@Component +@RequiredArgsConstructor +public class PointEventPublisherImpl implements PointEventPublisher { + + private final ApplicationEventPublisher applicationEventPublisher; + + @Override + public void publish(PointEvent.PointUsed event) { + applicationEventPublisher.publishEvent(event); + } + + @Override + public void publish(PointEvent.PointUsedFailed event) { + applicationEventPublisher.publishEvent(event); + } +} + diff --git a/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/UserJpaRepository.java b/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/UserJpaRepository.java new file mode 100644 index 000000000..a69a17925 --- /dev/null +++ b/apps/commerce-api/src/main/java/com/loopers/infrastructure/user/UserJpaRepository.java @@ -0,0 +1,81 @@ +package com.loopers.infrastructure.user; + +import com.loopers.domain.user.User; +import jakarta.persistence.LockModeType; +import org.springframework.data.jpa.repository.JpaRepository; +import org.springframework.data.jpa.repository.Lock; +import org.springframework.data.jpa.repository.Query; +import org.springframework.data.repository.query.Param; + +import java.util.Optional; + +/** + * User 엔티티를 위한 Spring Data JPA 리포지토리. + *+ * JpaRepository를 확장하여 기본 CRUD 기능과 + * 사용자 ID 기반 조회 기능을 제공합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +public interface UserJpaRepository extends JpaRepository+ * SELECT ... FOR UPDATE를 사용하여 동시성 제어를 보장합니다. + *
+ *+ * Lock 전략: + *
+ * 동작 원리: + *
+ * SELECT ... FOR UPDATE를 사용하여 동시성 제어를 보장합니다. + *
+ *+ * Lock 전략: + *
+ * Spring Data JPA를 활용하여 User 엔티티의 + * 영속성 작업을 처리합니다. + *
+ * + * @author Loopers + * @version 1.0 + */ +@RequiredArgsConstructor +@Component +public class UserRepositoryImpl implements UserRepository { + private final UserJpaRepository userJpaRepository; + + /** + * {@inheritDoc} + */ + @Override + public User save(User user) { + return userJpaRepository.save(user); + } + + /** + * {@inheritDoc} + */ + @Override + public User findByUserId(String userId) { + return userJpaRepository.findByUserId(userId).orElse(null); + } + + /** + * {@inheritDoc} + */ + @Override + public User findByUserIdForUpdate(String userId) { + return userJpaRepository.findByUserIdForUpdate(userId).orElse(null); + } + + /** + * {@inheritDoc} + */ + @Override + public User findById(Long id) { + return userJpaRepository.findById(id).orElse(null); + } + + /** + * {@inheritDoc} + */ + @Override + public User findByIdForUpdate(Long id) { + return userJpaRepository.findByIdForUpdate(id).orElse(null); + } +} diff --git a/apps/commerce-api/src/main/java/com/loopers/interfaces/api/ApiControllerAdvice.java b/apps/commerce-api/src/main/java/com/loopers/interfaces/api/ApiControllerAdvice.java index 20b2809c8..7f2948f2a 100644 --- a/apps/commerce-api/src/main/java/com/loopers/interfaces/api/ApiControllerAdvice.java +++ b/apps/commerce-api/src/main/java/com/loopers/interfaces/api/ApiControllerAdvice.java @@ -9,6 +9,8 @@ import org.springframework.http.ResponseEntity; import org.springframework.http.converter.HttpMessageNotReadableException; import org.springframework.web.bind.MissingServletRequestParameterException; +import org.springframework.web.bind.MissingRequestHeaderException; +import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException; @@ -19,16 +21,47 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Collectors; - +import java.util.stream.Stream; + +/** + * 전역 API 예외 처리 핸들러. + *+ * 애플리케이션 전역에서 발생하는 예외를 가로채어 + * 일관된 형식의 에러 응답을 생성합니다. + *
+ * + *