Story: 크레딧 시스템

메타

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

---

사용자 스토리

As a 추천인,
I want 피추천인의 활동에 따라 크레딧을 받고 싶다,
So that 다음 결제 시 할인받을 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 크레딧 적립 (1단계 - 몰연동)

항목	내용
Given	피추천인이 몰연동을 완료했을 때
When	연동 완료 이벤트가 발생하면
Then	추천인에게 3,500원 크레딧이 적립된다

AC-02: 크레딧 적립 (2단계 - 결제)

항목	내용
Given	피추천인이 첫 결제를 완료했을 때
When	결제 완료 이벤트가 발생하면
Then	추천인에게 3,500원 크레딧이 추가 적립된다

AC-03: 크레딧 만료

항목	내용
Given	크레딧이 적립된 후
When	12개월이 지나면
Then	해당 크레딧이 자동 만료된다

AC-04: 크레딧 조회

항목	내용
Given	마이페이지에서
When	크레딧 잔액을 조회하면
Then	총 잔액과 만료 예정 내역이 표시된다

---

태스크 분해

Task 1: 데이터 모델

• [ ] 1.1: ReferralCredit 테이블

  - id, userId, balance
  - createdAt, updatedAt

• [ ] 1.2: CreditTransaction 테이블

  - id, creditId, type (EARN/USE/EXPIRE)
  - amount, referralId, reason
  - expiresAt, createdAt

Task 2: API 개발

• [ ] 2.1: GET /users/me/credits - 크레딧 잔액 조회
• [ ] 2.2: GET /users/me/credits/transactions - 적립/사용 이력
• [ ] 2.3: GET /users/me/credits/expiring - 만료 예정 내역
• [ ] 2.4: POST /credits/earn - 크레딧 적립 (내부용)

Task 3: 적립 로직

• [ ] 3.1: 몰연동 완료 이벤트 리스너
  • 추천인 확인 → 3,500원 적립
  • Referral status: PENDING → ACTIVATED
• [ ] 3.2: 첫 결제 완료 이벤트 리스너
  • 추천인 확인 → 3,500원 추가 적립
  • Referral status: ACTIVATED → PAID

Task 4: 만료 처리

• [ ] 4.1: 만료 배치 (매일 00:00)
  • 적립일 + 12개월 지난 크레딧 만료
  • CreditTransaction.type = EXPIRE
• [ ] 4.2: 만료 예정 조회 (D-30, D-7)

---

개발 노트

크레딧 데이터 모델

interface ReferralCredit {
  id: string;
  userId: string;
  balance: number;              // 현재 잔액
}

interface CreditTransaction {
  id: string;
  type: 'EARN' | 'USE' | 'EXPIRE';
  amount: number;
  referralId?: string;          // 추천 관련 적립 시
  reason: string;               // 적립/사용 사유
  expiresAt: Date;              // 만료일 (적립일 + 12개월)
  createdAt: Date;
}

2단계 보상 구조

피추천인 가입 → 보상 없음 (어뷰징 방지)
     ↓
피추천인 몰연동 → 추천인 +3,500원
     ↓
피추천인 첫결제 → 추천인 +3,500원

총 보상: 7,000원/건

FIFO 차감

• 오래된 크레딧부터 사용
• 만료 전에 자연스럽게 소진

---

이벤트 로깅

이벤트	파라미터
credit_earned	user_id, amount, reason, referral_id
referral_activated	referral_code, credit_amount
referral_paid	referral_code, credit_amount
credit_expired	user_id, amount

---

생성일: 2026-01-20