결제/크레딧 기능 구현 시 참조할 도메인 스펙. BillingPlan 과금 모델, 가격 정책, 워크플로우를 정의한다.
사용자는 BillingProduct를 구매해 BillingPlan을 활성화한다. 현재 과금 모델은 크레딧 기반(CREDIT)이며, 구독 등 다른 모델로의 전환을 고려한 구조로 설계되어 있다.
결제 솔루션: Paddle. 결제 처리, Checkout UI, 웹훅 이벤트(transaction.completed)를 통한 크레딧 충전을 담당한다.
DB 스키마 · API · 환경변수: @.claude/skills/payments/reference.md
| 상품 | 가격 | 크레딧 |
|---|---|---|
| 기본 | 2,900원 | 300 |
| 프로 | 4,900원 | 500 + 보너스 50 |
| 기능 | 단위 | 크레딧 |
|---|
| 영상 주장 탐지 (STT+번역+요약+주장탐지) | 5분당 | 10 |
| 주장 검증 | 1개당 | 2 |
사용자 → BillingProduct 선택 → Paddle Checkout
→ 결제 완료 → POST /api/webhooks/paddle
→ 서명 검증 + idempotencyKey 중복 체크
→ BillingPlan 생성/갱신 + UserCredit 충전 (CREDIT 모델)
→ BillingTransaction(PURCHASE) 기록
POST /api/fact-check-sessions/{id}/claims)BillingPlan 확인 → CREDIT 모델
↓
FreeQuotaItem(VIDEO_CLAIM_DETECTION) 잔여 있음?
└─ Yes → usedCount 증가, sessionId 기록
└─ No → PricingRule 조회 → 비용 계산 → UserCredit 잔액 확인
→ BillingTransaction(CONSUME) 기록 → 처리 실행
POST /api/fact-check-sessions/{id}/claim-verifications)BillingPlan 확인 → CREDIT 모델
↓
FreeQuotaItem(CLAIM_VERIFICATION) 잔여 있음? (동일 세션)
└─ Yes → usedCount 증가 (최대 10회까지)
└─ No → PricingRule 조회 → 전체 주장 수 × 2크레딧
→ BillingTransaction(CONSUME) 기록 → 검증 실행
paddle-signature 헤더로 Paddle 요청 위변조 방지BillingTransaction.idempotencyKey 유니크 제약으로 중복 충전 방지