Loopers-dev-lab · SukheeChoi · Apr 1, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -22,6 +22,15 @@
 
 ---
 
+## 트래픽 규모 전제
+
+- 이 프로젝트는 **쿠팡, 무신사급 대규모 트래픽 이커머스**를 위한 설계를 적용하는 프로젝트이다
+- 모든 설계 결정(배치 주기, 테이블 정리 전략, 스레드 풀, 커넥션 풀 등)은 대규모 트래픽 기준으로 검토한다
+- "현재 단일 인스턴스니까 괜찮다"가 아니라, **스케일아웃 시에도 안전한 구조**를 기본으로 설계한다
+- 산술 근거 제시 시 피크 트래픽 기준으로 계산한다
+
+---
+
 ## 도메인 & 객체 설계 전략
 
 ### Entity / VO / Domain Service 구분

diff --git a/apps/commerce-api/build.gradle.kts b/apps/commerce-api/build.gradle.kts
@@ -2,6 +2,7 @@ dependencies {
     // add-ons
     implementation(project(":modules:jpa"))
     implementation(project(":modules:redis"))
+    implementation(project(":modules:kafka"))
     implementation(project(":supports:jackson"))
     implementation(project(":supports:logging"))
     implementation(project(":supports:monitoring"))

diff --git a/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponFacade.java b/apps/commerce-api/src/main/java/com/loopers/application/coupon/CouponFacade.java
@@ -1,15 +1,19 @@
 package com.loopers.application.coupon;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.loopers.domain.coupon.*;
 import com.loopers.support.error.CoreException;
 import com.loopers.support.error.ErrorType;
 import lombok.RequiredArgsConstructor;
+import org.springframework.kafka.core.KafkaTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
 import java.time.Clock;
 import java.time.ZonedDateTime;
 import java.util.List;
+import java.util.Map;
 
 @Service
 @RequiredArgsConstructor
@@ -18,6 +22,9 @@ public class CouponFacade {
 
     private final CouponRepository couponRepository;
     private final CouponIssueRepository couponIssueRepository;
+    private final CouponIssueRequestRepository couponIssueRequestRepository;
+    private final KafkaTemplate<Object, Object> kafkaTemplate;
+    private final ObjectMapper objectMapper;
     private final Clock clock;
 
     // ── Admin: 쿠폰 템플릿 CRUD ──
@@ -130,6 +137,40 @@ public void restoreCoupon(Long couponIssueId) {
         couponIssue.cancelUse(ZonedDateTime.now(clock));
     }
 
+    // ── 대고객: 선착순 쿠폰 발급 요청 ──
+
+    @Transactional
+    public CouponIssueRequest requestCouponIssue(Long couponId, Long memberId) {
+        Coupon coupon = couponRepository.findById(couponId)
+            .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "쿠폰을 찾을 수 없습니다."));
+
+        ZonedDateTime now = ZonedDateTime.now(clock);
+        if (now.isAfter(coupon.getExpiredAt())) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "만료된 쿠폰은 발급 요청할 수 없습니다.");
+        }
+
+        CouponIssueRequest request = couponIssueRequestRepository.save(
+            CouponIssueRequest.create(couponId, memberId));
+
+        try {
+            String payload = objectMapper.writeValueAsString(Map.of(
+                "requestId", request.getId(),
+                "couponId", couponId,
+                "memberId", memberId
+            ));
+            kafkaTemplate.send("coupon-issue-requests", String.valueOf(couponId), payload);
+        } catch (JsonProcessingException e) {
+            throw new RuntimeException("쿠폰 발급 요청 페이로드 직렬화 실패", e);
+        }
+
+        return request;
+    }
+
+    public CouponIssueRequest getIssueRequest(Long requestId) {
+        return couponIssueRequestRepository.findById(requestId)
+            .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "쿠폰 발급 요청을 찾을 수 없습니다."));
+    }
+
     public ZonedDateTime now() {
         return ZonedDateTime.now(clock);
     }

diff --git a/apps/commerce-api/src/main/java/com/loopers/application/event/ProductViewKafkaPublisher.java b/apps/commerce-api/src/main/java/com/loopers/application/event/ProductViewKafkaPublisher.java
@@ -0,0 +1,40 @@
+package com.loopers.application.event;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.loopers.domain.event.ProductViewedEvent;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.kafka.core.KafkaTemplate;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+import java.util.Map;
+import java.util.UUID;
+
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class ProductViewKafkaPublisher {
+
+    private final KafkaTemplate<Object, Object> kafkaTemplate;
+    private final ObjectMapper objectMapper;
+
+    @Async("eventExecutor")
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
+    public void handle(ProductViewedEvent event) {
+        try {
+            String payload = objectMapper.writeValueAsString(Map.of(
+                "eventId", UUID.randomUUID().toString(),
+                "eventType", "PRODUCT_VIEWED",
+                "productId", event.productId(),
+                "memberId", event.memberId()
+            ));
+            kafkaTemplate.send("catalog-events", String.valueOf(event.productId()), payload);
+        } catch (JsonProcessingException e) {
+            log.warn("조회수 이벤트 Kafka 발행 실패 — productId={}", event.productId(), e);
+        }
+    }
+}
diff --git a/apps/commerce-api/src/main/java/com/loopers/application/like/LikeFacade.java b/apps/commerce-api/src/main/java/com/loopers/application/like/LikeFacade.java
@@ -1,5 +1,8 @@
 package com.loopers.application.like;
 
+import com.loopers.domain.event.DomainEventPublisher;
+import com.loopers.domain.event.LikeCreatedEvent;
+import com.loopers.domain.event.LikeRemovedEvent;
 import com.loopers.domain.like.Like;
 import com.loopers.domain.like.LikeRepository;
 import com.loopers.domain.product.ProductRepository;
@@ -10,6 +13,7 @@
 import org.springframework.transaction.annotation.Transactional;
 
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 @Service
@@ -19,6 +23,7 @@ public class LikeFacade {
 
     private final LikeRepository likeRepository;
     private final ProductRepository productRepository;
+    private final DomainEventPublisher domainEventPublisher;
 
     @Transactional
     public void addLike(Long memberId, Long productId) {
@@ -30,7 +35,10 @@ public void addLike(Long memberId, Long productId) {
         }
 
         likeRepository.save(new Like(memberId, productId));
-        productRepository.incrementLikeCount(productId);
+
+        domainEventPublisher.publish("catalog", String.valueOf(productId),
+            "LIKE_CREATED", Map.of("productId", productId, "memberId", memberId),
+            new LikeCreatedEvent(productId, memberId));
     }
 
     @Transactional
@@ -41,7 +49,10 @@ public void removeLike(Long memberId, Long productId) {
         }
 
         likeRepository.delete(likeOpt.get());
-        productRepository.decrementLikeCount(productId);
+
+        domainEventPublisher.publish("catalog", String.valueOf(productId),
+            "LIKE_REMOVED", Map.of("productId", productId, "memberId", memberId),
+            new LikeRemovedEvent(productId, memberId));
     }
 
     public List<Like> getLikesByMemberId(Long memberId) {

diff --git a/apps/commerce-api/src/main/java/com/loopers/application/order/OrderFacade.java b/apps/commerce-api/src/main/java/com/loopers/application/order/OrderFacade.java
@@ -4,6 +4,10 @@
 import com.loopers.application.coupon.CouponFacade;
 import com.loopers.domain.brand.Brand;
 import com.loopers.domain.brand.BrandRepository;
+import com.loopers.domain.event.DomainEventPublisher;
+import com.loopers.domain.event.OrderCancelledEvent;
+import com.loopers.domain.event.OrderCreatedEvent;
+import com.loopers.domain.event.OrderItemSnapshot;
 import com.loopers.domain.order.Order;
 import com.loopers.domain.order.OrderItem;
 import com.loopers.domain.order.OrderRepository;
@@ -32,6 +36,7 @@ public class OrderFacade {
     private final ProductRepository productRepository;
     private final BrandRepository brandRepository;
     private final CouponFacade couponFacade;
+    private final DomainEventPublisher domainEventPublisher;
 
     @Transactional
     public Order createOrder(Long memberId, List<OrderItemRequest> itemRequests) {
@@ -109,6 +114,16 @@ public Order createOrder(Long memberId, List<OrderItemRequest> itemRequests, Lon
             couponFacade.linkCouponToOrder(resolvedCouponIssueId, order.getId());
         }
 
+        // 8. Outbox INSERT + 이벤트 발행
+        List<OrderItemSnapshot> eventItems = order.getItems().stream()
+            .map(item -> new OrderItemSnapshot(item.getProductId(), item.getQuantity(), item.getProductPrice()))
+            .toList();
+
+        domainEventPublisher.publish("order", String.valueOf(order.getId()),
+            "ORDER_CREATED",
+            Map.of("orderId", order.getId(), "memberId", memberId, "items", eventItems),
+            new OrderCreatedEvent(order.getId(), memberId, eventItems));
+
         return order;
     }
 
@@ -152,6 +167,16 @@ public void cancelOrder(Long orderId, Long memberId) {
         if (order.getCouponIssueId() != null) {
             couponFacade.restoreCoupon(order.getCouponIssueId());
         }
+
+        // Outbox INSERT + 이벤트 발행
+        List<OrderItemSnapshot> eventItems = order.getItems().stream()
+            .map(item -> new OrderItemSnapshot(item.getProductId(), item.getQuantity(), item.getProductPrice()))
+            .toList();
+
+        domainEventPublisher.publish("order", String.valueOf(orderId),
+            "ORDER_CANCELLED",
+            Map.of("orderId", orderId, "memberId", memberId, "items", eventItems),
+            new OrderCancelledEvent(orderId, memberId, eventItems));
     }
 
     public List<Order> getOrdersByMemberId(Long memberId, ZonedDateTime startAt, ZonedDateTime endAt) {

diff --git a/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentRecoveryService.java b/apps/commerce-api/src/main/java/com/loopers/application/payment/PaymentRecoveryService.java
@@ -1,16 +1,13 @@
 package com.loopers.application.payment;
 
-import com.loopers.domain.coupon.CouponIssue;
-import com.loopers.domain.coupon.CouponIssueRepository;
+import com.loopers.application.coupon.CouponFacade;
+import com.loopers.application.product.ProductFacade;
 import com.loopers.domain.order.Order;
 import com.loopers.domain.order.OrderItem;
 import com.loopers.domain.order.OrderRepository;
 import com.loopers.domain.payment.*;
-import com.loopers.domain.product.Product;
-import com.loopers.domain.product.ProductRepository;
 import com.loopers.infrastructure.pg.PgPaymentStatusResponse;
 import com.loopers.infrastructure.pg.PgRouter;
-import com.loopers.infrastructure.redis.StockReservationRedisRepository;
 import com.loopers.support.error.CoreException;
 import com.loopers.support.error.ErrorType;
 import lombok.RequiredArgsConstructor;
@@ -30,7 +27,7 @@
  *   <li>CallbackInbox에 원본 저장 (RECEIVED)</li>
  *   <li>조건부 UPDATE로 Payment 상태 전이</li>
  *   <li>SUCCESS → Order.pay() + Inbox PROCESSED</li>
- *   <li>FAILED → 재고 복원(Redis INCR + DB) + 쿠폰 복원 + Inbox PROCESSED</li>
+ *   <li>FAILED → 재고 복원(ProductFacade) + 쿠폰 복원(CouponFacade) + Inbox PROCESSED</li>
  * </ol>
  *
  * <p>Polling Hybrid: PENDING/UNKNOWN 상태 결제건을 주기적으로 PG 확인</p>
@@ -44,11 +41,11 @@
 public class PaymentRecoveryService {
 
     private final PaymentRepository paymentRepository;
+    private final PaymentStatusHistoryRepository historyRepository;
     private final CallbackInboxRepository callbackInboxRepository;
     private final OrderRepository orderRepository;
-    private final ProductRepository productRepository;
-    private final CouponIssueRepository couponIssueRepository;
-    private final StockReservationRedisRepository stockRedisRepository;
+    private final ProductFacade productFacade;
+    private final CouponFacade couponFacade;
     private final PgRouter pgRouter;
 
     /**
@@ -102,6 +99,10 @@ private void processPaymentTransition(PaymentModel payment, String pgStatus, Cal
             return;
         }
 
+        // 상태 전이 이력 기록
+        historyRepository.save(PaymentStatusHistory.create(
+            payment.getId(), payment.getStatus(), targetStatus, "CALLBACK", null));
+
         // 상태 전이 성공
         if (targetStatus == PaymentStatus.PAID) {
             handlePaymentSuccess(payment);
@@ -127,23 +128,16 @@ private void handlePaymentFailure(PaymentModel payment) {
         Order order = orderRepository.findById(payment.getOrderId()).orElse(null);
         if (order == null) return;
 
-        // 재고 복원 (Redis INCR + DB)
+        // 재고 복원 → ProductFacade 위임
         for (OrderItem item : order.getItems()) {
-            stockRedisRepository.increase(item.getProductId(), item.getQuantity());
-            productRepository.findById(item.getProductId()).ifPresent(product -> {
-                product.increaseStock(item.getQuantity());
-                productRepository.save(product);
-            });
+            productFacade.restoreStock(item.getProductId(), item.getQuantity());
         }
         log.info("재고 복원 완료: orderId={}", order.getId());
 
-        // 쿠폰 복원
+        // 쿠폰 복원 → CouponFacade 위임
         if (order.getCouponIssueId() != null) {
-            couponIssueRepository.findById(order.getCouponIssueId()).ifPresent(couponIssue -> {
-                couponIssue.cancelUse(ZonedDateTime.now());
-                couponIssueRepository.save(couponIssue);
-                log.info("쿠폰 복원 완료: couponIssueId={}", couponIssue.getId());
-            });
+            couponFacade.restoreCoupon(order.getCouponIssueId());
+            log.info("쿠폰 복원 완료: couponIssueId={}", order.getCouponIssueId());
         }
     }
 
@@ -219,6 +213,8 @@ private void pollPgStatus(PaymentModel payment) {
                     int affected = paymentRepository.updateStatusConditionally(
                         payment.getId(), PaymentStatus.PAID, allowedStatuses);
                     if (affected > 0) {
+                        historyRepository.save(PaymentStatusHistory.create(
+                            payment.getId(), payment.getStatus(), PaymentStatus.PAID, "POLLING", null));
                         handlePaymentSuccess(payment);
                         log.info("Polling 복구 성공: paymentId={}, → PAID", payment.getId());
                     }
@@ -227,6 +223,9 @@ private void pollPgStatus(PaymentModel payment) {
                     int affected = paymentRepository.updateStatusConditionally(
                         payment.getId(), PaymentStatus.FAILED, allowedStatuses);
                     if (affected > 0) {
+                        historyRepository.save(PaymentStatusHistory.create(
+                            payment.getId(), payment.getStatus(), PaymentStatus.FAILED,
+                            "POLLING", pgStatus.reason()));
                         handlePaymentFailure(payment);
                         log.info("Polling 복구: paymentId={}, → FAILED (reason={})",
                             payment.getId(), pgStatus.reason());