[volume-4] 쿠폰 도메인 구현 및 동시성 제어

[letter333]

4주차에 대한 커밋만 보시려면 이거로 보시는게 더 좋을 것 같습니다.

📌 Summary

• 배경: 커머스 API에 쿠폰 기능이 부재하고, 주문·재고·좋아요 등 핵심 도메인에 동시성 제어가 없어 데이터 정합성 리스크가 존재
• 목표: 쿠폰 도메인 전체 레이어 구현 + 주요 도메인 동시성 제어 + 배송비 자동 계산
• 결과: 쿠폰 Admin/User API 완성, 비관적/낙관적 락 기반 동시성 제어 적용

🧭 Context & Decision

문제 정의

• 현재 동작/제약: 쿠폰 기능 미구현, 동시 요청 시 재고 초과 차감·쿠폰 중복 발급·좋아요 카운트 유실 가능
• 문제(또는 리스크): 플래시 세일 등 동시 트래픽 시 데이터 정합성 보장 불가
• 성공 기준: 모든 동시성 테스트(10~50 스레드) 통과, E2E 테스트 전량 통과

선택지와 결정

동시성 전략

• 고려한 대안:
  • A: 낙관적 락(Optimistic Lock) — 충돌 시 재시도, DB 부하 낮음
  • B: 비관적 락(Pessimistic Lock) — SELECT FOR UPDATE로 직렬화, 충돌 방지
  • C: 원자적 네이티브 UPDATE — JPA 우회, DB 레벨 원자적 연산
• 최종 결정: 도메인별 차등 적용
  • 재고(Product)·쿠폰 발급(Coupon)·주문 취소(Order) → 비관적 락 (높은 경합 + 카운터 불변식, 무거운 부수효과의 fail-fast)
  • 쿠폰 사용(MemberCoupon) → 낙관적 락 (@Version, 낮은 경합(단일 유저 소유) + 단순 상태 전이 + 부수효과 없음)
  • Product·Brand 좋아요 → 원자적 네이티브 UPDATE (like_count = like_count ± 1, JPA 영속성 컨텍스트 우회)
• 트레이드오프: 비관적 락은 동시성 높을수록 대기 시간 증가, 그러나 정합성이 우선. 낙관적 락은 경합이 낮은 도메인에서 락 대기 없이 성능 이점 확보
• 추후 개선 여지: Redis 분산 락 또는 Kafka 기반 비동기 처리로 확장 가능

MemberCoupon 낙관적 락 + Facade 재시도

• 배경: MemberCoupon은 단일 유저만 소유하므로 경합이 거의 없고, 상태 전이(AVAILABLE→USED)만 수행하여 부수효과가 없음
• 구현: @Version 필드로 낙관적 락 적용, OrderFacade.createOrder()에 @retryable로 ObjectOptimisticLockingFailureException 발생 시 최대 3회 재시도
• AOP 순서: @retryable(order=MAX-1)이 @transactional(order=MAX)보다 우선 → 재시도마다 새 트랜잭션 생성, 이전 재고 차감도 롤백
• 멱등성: 재시도 시 쿠폰이 이미 USED면 CoreException("이미 사용된 쿠폰") → 재시도 중단

쿠폰 중복 발급 방지

• 고려한 대안:
  • A: 애플리케이션 레벨 중복 체크 (TOCTOU 취약)
  • B: DB UNIQUE 제약조건 + 비관적 락 이중 방어
• 최종 결정: B — findByIdForUpdate로 수량 체크 후, (memberId, couponId) UNIQUE 제약으로 2차 방어

데드락 방지

• 주문 생성/취소 시 다수 Product 락 획득 → productId 오름차순 정렬로 락 순서 고정

🏗️ Design Overview

변경 범위

• 영향 받는 모듈/도메인: commerce-api (coupon, order, product, brand, like)
• 신규 추가: 쿠폰 도메인 전체 (domain/infrastructure/application/interfaces 4계층), 배송비 계산, 동시성 테스트 9개
• 제거/대체: OrderService.cancelOrder() → OrderFacade로 일원화, dead code 제거

주요 컴포넌트 책임

쿠폰 도메인

• Coupon: 쿠폰 생성/수정/삭제, 할인 계산(FIXED/RATE), 발급 수량 관리
• MemberCoupon: 발급된 쿠폰 상태 관리(AVAILABLE→USED→AVAILABLE), 사용/취소
• CouponValidator: 쿠폰 생성/수정 시 비즈니스 규칙 검증 (유틸리티 클래스)
• CouponFacade: Admin CRUD, 사용자 발급/조회 오케스트레이션
• CouponAdminV1Controller / CouponV1Controller: REST API 엔드포인트

동시성 제어

• ProductService.decreaseStock/increaseStock: ID-only 비관적 락 → 재고 변경
• MemberCouponService.issueCoupon: 비관적 락 + UNIQUE 제약 이중 방어
• MemberCouponService.useCoupon: @Version 낙관적 락으로 이중 사용 방지 (비관적 락에서 전환)
• OrderFacade.createOrder: @retryable로 낙관적 락 실패 시 전체 재시도 (재고 차감 포함 롤백 후 새 TX)
• OrderFacade.cancelOrder/changeOrderStatusForAdmin: 주문 행 비관적 락 → 재고 복구 + 쿠폰 취소
• Product·Brand 좋아요: 원자적 네이티브 UPDATE (like_count = like_count ± 1)

주문 개선

• Order: 상태 머신(canCancel/canTransitionTo), 배송비 자동 계산(5만원 이상 무료)
• OrderFacade.restoreStockAndCancelCoupon(): 취소 시 재고+쿠폰 복구 공통 메서드

🔁 Flow Diagram

쿠폰 발급 Flow (동시성 제어 포함)

sequenceDiagram
  autonumber
  participant Client
  participant CouponFacade
  participant MemberCouponService
  participant CouponRepository
  participant MemberCouponRepository
  participant DB

  Client->>CouponFacade: POST /api/v1/coupons/{id}/issue
  CouponFacade->>MemberCouponService: issueCoupon(couponId, memberId)
  MemberCouponService->>CouponRepository: findByIdForUpdate(couponId)
  CouponRepository->>DB: SELECT id FOR UPDATE
  DB-->>CouponRepository: locked row
  MemberCouponService->>MemberCouponService: coupon.issue() (수량 체크 + 증가)
  MemberCouponService->>CouponRepository: save(coupon)
  MemberCouponService->>MemberCouponRepository: save(memberCoupon)
  Note over MemberCouponRepository,DB: UNIQUE(memberId, couponId) 중복 방어
  MemberCouponRepository-->>MemberCouponService: saved
  MemberCouponService-->>CouponFacade: MemberCoupon
  CouponFacade-->>Client: 발급 완료

Loading

주문 생성 Flow (낙관적 락 + @retryable 재시도)

sequenceDiagram
  autonumber
  participant Client
  participant OrderFacade
  participant ProductService
  participant MemberCouponService
  participant OrderService
  participant DB

  Client->>OrderFacade: POST /api/v1/orders
  Note over OrderFacade: @Retryable (max 3회, ObjectOptimisticLockingFailureException)
  Note over OrderFacade: @Transactional (재시도마다 새 TX)

  loop 상품별 (productId 오름차순)
    OrderFacade->>ProductService: decreaseStock(productId, optionId, qty)
    ProductService->>DB: SELECT id FOR UPDATE → 재고 차감
  end

  alt 쿠폰 사용 요청 있음
    OrderFacade->>MemberCouponService: useCoupon(memberCouponId)
    MemberCouponService->>DB: SELECT (낙관적 락, @Version 체크)
    alt 버전 충돌
      DB-->>MemberCouponService: ObjectOptimisticLockingFailureException
      MemberCouponService-->>OrderFacade: 예외 전파
      Note over OrderFacade: TX 롤백 (재고 차감 포함) → 재시도
    else 쿠폰 이미 USED
      MemberCouponService-->>OrderFacade: CoreException("이미 사용된 쿠폰")
      Note over OrderFacade: 재시도 중단 (비즈니스 예외)
    else 성공
      MemberCouponService->>DB: UPDATE status=USED, version+1
    end
  end

  OrderFacade->>OrderService: createOrder(order)
  OrderService->>DB: INSERT order
  OrderFacade-->>Client: 주문 완료

Loading

주문 취소 Flow

sequenceDiagram
  autonumber
  participant Client
  participant OrderFacade
  participant OrderService
  participant ProductService
  participant MemberCouponService
  participant DB

  Client->>OrderFacade: DELETE /api/v1/orders/{id}
  OrderFacade->>OrderService: getOrderForUpdate(orderId)
  OrderService->>DB: SELECT ... FOR UPDATE (주문 락)
  OrderFacade->>OrderFacade: order.cancel()
  loop 상품별 (productId 오름차순)
    OrderFacade->>ProductService: increaseStock(productId, optionId, qty)
    ProductService->>DB: SELECT id FOR UPDATE → 재고 복구
  end
  OrderFacade->>MemberCouponService: cancelCouponUsage(orderId)
  OrderFacade->>OrderService: saveOrder(order)
  OrderFacade-->>Client: 취소 완료

Loading

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: af7ff3b2-a208-4c3e-bf47-0f8f9d1da69a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}