Story: 크레딧 정기결제 연동

메타

항목	값
Story ID	E-07-S-06
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	0원 결제 (빌링키만 유지), 카드 결제 생략

AC-03: FIFO 차감

항목	내용
Given	여러 건의 크레딧이 있을 때
When	차감이 발생하면
Then	만료일이 가까운 크레딧부터 차감된다

AC-04: 결제 실패 시 크레딧 유지

항목	내용
Given	정기결제가 실패했을 때
When	재시도 대기 상태이면
Then	크레딧은 차감되지 않고 유지된다

---

태스크 분해

Task 1: 정기결제 로직 수정

• [ ] 1.1: 결제 전 크레딧 잔액 조회
• [ ] 1.2: 크레딧 차감 금액 계산
  • 차감액 = min(크레딧 잔액, 결제 금액)
  • 최종 결제 = 결제 금액 - 차감액
• [ ] 1.3: 0원 결제 분기 처리
  • 최종 결제 = 0원이면 카드 결제 API 호출 생략
  • 빌링키만 유지

Task 2: 크레딧 차감 처리

• [ ] 2.1: FIFO 차감 로직
  • expiresAt 오름차순 정렬
  • 순차적으로 차감
• [ ] 2.2: CreditTransaction 기록
  • type: USE
  • paymentId 연결
• [ ] 2.3: 크레딧 잔액 업데이트

Task 3: orderName 생성

• [ ] 3.1: 정기결제 상품명 생성
  • 크레딧 없음: "장사왕 PRO10 (2월)"
  • 크레딧 차감: "장사왕 PRO10 (2월)" (금액만 다름)
  • 전액 크레딧: "장사왕 PRO10 (2월) - 크레딧 결제"

Task 4: 결제 실패 처리

• [ ] 4.1: 결제 실패 시 크레딧 미차감
  • 결제 성공 시에만 USE 트랜잭션 생성
• [ ] 4.2: 재시도 시 동일 로직 적용

---

개발 노트

정기결제 플로우

[정기결제일 도달]
        ↓
[보유 크레딧 확인]
        ↓
[크레딧 차감 계산]
        ↓
    ┌───────┴───────┐
최종 > 0원        최종 = 0원
    ↓                 ↓
[카드 결제 시도]    [결제 생략]
    ↓                 ↓
    ┌───┴───┐        [크레딧 차감]
  성공      실패      [구독 갱신]
    ↓         ↓
[크레딧 차감] [크레딧 유지]
[구독 갱신]  [재시도 대기]

예시

보유 크레딧: 21,000원 (3건 추천)
정기결제: 110,000원

계산:
- 크레딧 차감: 21,000원
- 최종 결제: 89,000원
- 카드 결제 실행: 89,000원

---

이벤트 로깅

이벤트	파라미터
credit_used	user_id, amount, payment_id
recurring_payment_with_credit	user_id, credit_amount, final_amount
full_credit_payment	user_id, credit_amount

---

생성일: 2026-01-20