Story: 쿠폰 데이터 모델 및 API

메타

항목	값
Story ID	E-07-S-01
Epic	E-07 쿠폰 & 추천인 코드
상태	ready-for-dev
우선순위	P0
규모	M
담당 개발자	BE

---

사용자 스토리

As a 시스템,
I want 쿠폰 데이터를 저장하고 관리하고 싶다,
So that 결제 시 쿠폰 할인을 적용할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 쿠폰 생성

항목	내용
Given	어드민이 쿠폰을 생성할 때
When	필수 정보(코드, 유형, 할인 정보)를 입력하면
Then	쿠폰이 생성되고 코드 중복 검사가 수행된다

AC-02: 쿠폰 유효성 검증

항목	내용
Given	사용자가 쿠폰 코드를 입력할 때
When	유효성 검사를 수행하면
Then	유효기간, 사용 횟수, 적용 조건이 검증된다

AC-03: 쿠폰 사용 처리

항목	내용
Given	결제가 성공했을 때
When	쿠폰이 적용된 결제이면
Then	쿠폰 사용 기록이 저장되고 usedCount가 증가한다

---

태스크 분해

Task 1: 데이터 모델

• [ ] 1.1: Coupon 테이블 생성

  - id, code, type (FIXED/PERCENT/TRIAL_EXT)
  - discountAmount, discountPercent, maxDiscountAmount
  - trialDays, minPaymentAmount
  - validFrom, validUntil
  - maxUsageTotal, maxUsagePerUser
  - applicablePlans (JSON), isFirstPaymentOnly
  - isActive, usedCount

• [ ] 1.2: CouponUsage 테이블 생성 (사용 이력)

  - id, couponId, userId, paymentId, usedAt

• [ ] 1.3: 쿠폰 코드 유니크 인덱스

Task 2: API 개발

• [ ] 2.1: POST /admin/coupons - 쿠폰 생성
• [ ] 2.2: GET /coupons/validate?code={code} - 쿠폰 검증
• [ ] 2.3: POST /coupons/{id}/use - 쿠폰 사용 처리
• [ ] 2.4: GET /users/me/coupons - 내 보유 쿠폰 목록

Task 3: 비즈니스 로직

• [ ] 3.1: 쿠폰 할인 금액 계산 로직
  • FIXED: discountAmount 그대로
  • PERCENT: 원가 × discountPercent, maxDiscountAmount 적용
  • TRIAL_EXT: trialDays 반환
• [ ] 3.2: 쿠폰 적용 조건 검증
  • 유효기간, 사용 횟수, 최소 금액, 첫결제 전용

---

개발 노트

쿠폰 유형 정의

interface Coupon {
  id: string;
  code: string;                    // 예: FIRST100, HALF50
  type: 'FIXED' | 'PERCENT' | 'TRIAL_EXT';

  // 할인 정보
  discountAmount?: number;         // 정액 할인
  discountPercent?: number;        // 정률 할인 (0-100)
  maxDiscountAmount?: number;      // 정률 최대 할인액
  trialDays?: number;              // 무료 체험 연장 일수

  // 사용 조건
  minPaymentAmount?: number;
  validFrom: Date;
  validUntil: Date;
  maxUsageTotal?: number;          // null = 무제한
  maxUsagePerUser: number;         // 기본: 1

  // 적용 범위
  applicablePlans: string[];       // 빈 배열 = 전체
  isFirstPaymentOnly: boolean;

  // 상태
  isActive: boolean;
  usedCount: number;
}

---

이벤트 로깅

이벤트	파라미터
coupon_created	coupon_code, coupon_type, discount_amount
coupon_validated	coupon_code, is_valid, validation_reason
coupon_applied	coupon_code, discount_amount

---

생성일: 2026-01-20