Story: 추천인 관리 API

메타

항목	값
Story ID	E-02-S-06
Epic	E-02 어드민 강화
상태	draft
우선순위	P2
규모	S
담당 개발자	BE (하록님)

---

사용자 스토리

As a 운영팀 관리자, I want 추천인 현황을 조회하고 부정 사용 코드를 비활성화, So that 추천 프로그램을 건전하게 운영할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 추천 현황 목록 조회

항목	내용
Given	관리자가 추천인 관리 메뉴 진입
When	페이지 로드
Then	추천인별 실적 목록 표시

응답 필드:

{
  items: [{
    code: string,            // SELLER-XXXXXX
    bizId: number,
    bizName: string,         // 추천인 사업장명
    totalReferrals: number,  // 총 추천 수
    activeCount: number,     // 연동 완료 수
    paidReferrals: number,   // 결제 완료 수
    activeYn: boolean,       // 코드 활성 상태
    createdAt: string
  }],
  pagination: { page, size, total, totalPages }
}

필터/정렬:

• 상태: 전체/활성/비활성
• 정렬: 총 추천 수, 결제 수, 생성일

AC-02: 추천 코드 상세 조회

항목	내용
Given	특정 추천 코드 선택
When	상세 조회 요청
Then	코드 정보 + 피추천인 목록 반환

응답 필드:

{
  code: {
    code, bizId, bizName,
    totalReferrals, activeCount, paidReferrals,
    activeYn, createdAt
  },
  referees: [{          // 피추천인 목록
    refereeId: number,
    refereeBizName: string,
    status: string,     // JOINED, LINKED, PAID
    signedUpAt, storeLinkedAt, paidAt,
    storeRewardYn, payRewardYn  // 리워드 지급 여부
  }]
}

AC-03: 추천 코드 비활성화

항목	내용
Given	활성 상태의 추천 코드
When	비활성화 요청
Then	코드가 비활성화되어 신규 추천 불가

상세 스펙:

• activeYn = false 설정
• 기존 추천 관계 유지 (리워드 지급은 계속)
• 재활성화 가능

AC-04: 추천 관계 상세 조회

항목	내용
Given	특정 추천 관계 ID
When	상세 조회 요청
Then	추천인-피추천인 관계 상세 정보 반환

응답 필드:

{
  id: number,
  referrer: { bizId, bizName },   // 추천인
  referee: { bizId, bizName },    // 피추천인
  referralCode: string,
  status: string,
  signedUpAt, storeLinkedAt, paidAt,
  storeRewardYn, payRewardYn,
  storeRewardAmount, payRewardAmount  // 지급된 리워드 금액
}

AC-05: 추천 코드 재활성화

항목	내용
Given	비활성 상태의 추천 코드
When	재활성화 요청
Then	코드가 활성화되어 신규 추천 가능

상세 스펙:

• activeYn = true 설정
• 부정 사용 확인 후 관리자 판단 하에 재활성화

---

태스크 분해

Task 1: 추천 현황 목록 API AC-01

• [ ] 1.1: GET /admin/referrals 엔드포인트 생성
• [ ] 1.2: ReferralCode + Biz 조인 쿼리
• [ ] 1.3: 페이지네이션 + 필터 + 정렬

Task 2: 추천 코드 상세 API AC-02

• [ ] 2.1: GET /admin/referrals/codes/:code 엔드포인트 생성
• [ ] 2.2: 코드 정보 + Referral 목록 조인
• [ ] 2.3: 404 처리

Task 3: 추천 코드 비활성화 API AC-03

• [ ] 3.1: POST /admin/referrals/codes/:code/deactivate 엔드포인트 생성
• [ ] 3.2: activeYn = false 업데이트
• [ ] 3.3: 404 처리

Task 4: 추천 코드 재활성화 API AC-05

• [ ] 4.1: POST /admin/referrals/codes/:code/activate 엔드포인트 생성
• [ ] 4.2: activeYn = true 업데이트
• [ ] 4.3: 404 처리
• [ ] 4.4: 이미 활성화된 경우 처리 (멱등성)

Task 5: 추천 관계 상세 API AC-04

• [ ] 5.1: GET /admin/referrals/:id 엔드포인트 생성
• [ ] 5.2: Referral + 양쪽 Biz 조인
• [ ] 5.3: 404 처리

Task 6: 테스트 작성

• [ ] 6.1: 각 API 단위 테스트
• [ ] 6.2: 404 케이스 테스트

Task 7: 마무리

• [ ] 7.1: API 문서화
• [ ] 7.2: PR 생성

---

Dev Notes (AI Agent 최적화)

영향 받는 소스 트리

src/
├── admin/
│   └── referral/
│       ├── referral.admin.controller.ts  # 🆕 신규 생성
│       ├── referral.admin.service.ts     # 🆕 신규 생성
│       └── dto/
│           └── referral-list.dto.ts      # 🆕 신규 생성
└── tests/
    └── admin/
        └── referral.admin.spec.ts        # 🆕 신규 생성

충돌 감지

항목	상태	설명
기존 코드 충돌	✅ 없음	신규 어드민 API
DB 스키마 변경	✅ 없음	기존 테이블 사용

---

References

출처	경로/링크	참조 섹션
Epic Spec	.context/sprints/s53/epic-specs/E-02.md	추천인 API 설계
테이블 스키마	S52 E-07 DDL	ReferralCode, Referral

---

Dev Agent Record

항목	값
생성 Agent	Claude Opus 4.5
생성일	2026-01-27
마지막 수정	2026-01-27
검증자	-

---

검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -

---

생성일: 2026-01-27마지막 수정: 2026-01-27