Story: 추천인 코드 시스템

메타

항목	값
Story ID	E-07-S-04
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	추천인과 피추천인 관계가 기록된다

AC-04: 어뷰징 방지

항목	내용
Given	추천 코드로 가입 시도 시
When	자기 추천, 기존 가입자, 동일 IP 초과면
Then	가입은 허용하되 추천 관계는 무효 처리

---

태스크 분해

Task 1: 데이터 모델

• [ ] 1.1: ReferralCode 테이블

  - id, code, ownerId
  - totalReferrals, activatedReferrals, paidReferrals
  - isActive, createdAt

• [ ] 1.2: Referral 테이블 (추천 관계)

  - id, referralCodeId, referrerId, refereeId
  - status (PENDING/ACTIVATED/PAID)
  - activatedAt, paidAt, createdAt

• [ ] 1.3: 추천 코드 유니크 인덱스

Task 2: API 개발

• [ ] 2.1: GET /users/me/referral-code - 내 추천 코드
• [ ] 2.2: GET /referral-codes/validate?code={code} - 코드 검증
• [ ] 2.3: POST /signup - 추천 코드 파라미터 추가
• [ ] 2.4: GET /users/me/referrals - 내 추천 현황

Task 3: 추천 코드 생성 로직

• [ ] 3.1: 코드 형식: SELLER-
• [ ] 3.2: 첫 결제 완료 시 자동 생성
• [ ] 3.3: 코드 충돌 시 재생성

Task 4: 어뷰징 방지

• [ ] 4.1: 자기 추천 검사 (이메일/전화번호)
• [ ] 4.2: 기존 가입 이력 검사
• [ ] 4.3: 동일 IP 24시간 내 3건 초과 시 검토 대기

---

개발 노트

추천 코드 구조

interface ReferralCode {
  id: string;
  code: string;                    // 예: SELLER-ABC123
  ownerId: string;

  // 통계
  totalReferrals: number;          // 총 추천 수 (가입)
  activatedReferrals: number;      // 활성화 수 (몰연동)
  paidReferrals: number;           // 결제 완료 수

  isActive: boolean;
  createdAt: Date;
}

URL 파라미터 방식

추천 링크: https://jangsawang.com/signup?ref=SELLER-ABC123

- 클릭 시 쿠키/세션에 저장
- 가입 완료 시까지 유지
- 가입 폼에 자동 채워짐 (수정 불가)

---

이벤트 로깅

이벤트	파라미터
referral_code_created	user_id, referral_code
referral_code_validated	code, is_valid
referral_signup	referral_code, referrer_id, referee_id
referral_invalid	reason (self_referral/existing_user/ip_limit)

---

생성일: 2026-01-20