장사왕 스프린트 대시보드

테마

Story: 추천인 관리 UI ​

메타 ​

항목값
Story IDE-02-S-07
EpicE-02 어드민 강화
상태draft
우선순위P2
규모M
담당 개발자FE (수민님)

사용자 스토리 ​

As a 운영팀 관리자, I want 어드민에서 추천인 현황을 확인하고 관리하는 UI, So that 추천 프로그램을 모니터링하고 부정 사용을 방지할 수 있다.

수락 기준 (Acceptance Criteria) ​

AC-01: 추천 현황 목록 화면 ​

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

UI 요소:

┌─────────────────────────────────────────────────────────────────┐
│ 추천인 관리                                                      │
├─────────────────────────────────────────────────────────────────┤
│ 필터: [상태 ▼]      정렬: [결제 수 ▼]                            │
├─────────────────────────────────────────────────────────────────┤
│ 코드            │ 추천인      │ 가입  │ 연동  │ 결제  │ 상태    │
├─────────────────┼─────────────┼───────┼───────┼───────┼─────────┤
│ SELLER-ABC123   │ 맛있는가게  │ 15    │ 8     │ 5     │ 🟢 활성 │
│ SELLER-DEF456   │ 신선마트    │ 10    │ 6     │ 3     │ 🟢 활성 │
│ SELLER-GHI789   │ 행복상점    │ 50    │ 2     │ 0     │ 🔴 비활성│
├─────────────────────────────────────────────────────────────────┤
│                      [< 1 2 3 >]                                │
└─────────────────────────────────────────────────────────────────┘

상세 스펙:

  • 필터: 상태(전체/활성/비활성)
  • 정렬: 가입 수, 연동 수, 결제 수, 생성일
  • 행 클릭 → 상세 화면
  • 이상 징후 표시: 가입 대비 결제율 극단적 낮은 경우 하이라이트

AC-02: 추천 코드 상세 화면 ​

항목내용
Given목록에서 추천 코드 클릭
When상세 화면 로드
Then코드 정보 + 피추천인 목록 표시

UI 요소:

┌─────────────────────────────────────────────────────────────────┐
│ ← 목록  SELLER-ABC123                              [비활성화]   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ 추천인: 맛있는가게 (12345)                                      │
│ 상태: 🟢 활성                                                   │
│ 생성일: 2026-01-01                                              │
│                                                                 │
│ ─── 실적 요약 ───                                               │
│ 총 가입: 15명  |  연동 완료: 8명  |  결제 완료: 5명              │
│ 전환율: 가입→연동 53% | 연동→결제 63%                           │
│                                                                 │
│ ─── 피추천인 목록 ───                                           │
├─────────────────────────────────────────────────────────────────┤
│ 사업장      │ 상태      │ 가입일   │ 연동일   │ 결제일   │ 리워드│
├─────────────┼───────────┼──────────┼──────────┼──────────┼───────┤
│ 김셀러상점  │ 결제완료  │ 01/15    │ 01/16    │ 01/20    │ ✅    │
│ 박셀러마트  │ 연동완료  │ 01/18    │ 01/19    │ -        │ ✅    │
│ 이셀러가게  │ 가입완료  │ 01/25    │ -        │ -        │ -     │
├─────────────────────────────────────────────────────────────────┤
│                      [< 1 2 >]                                  │
└─────────────────────────────────────────────────────────────────┘

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

항목내용
Given상세 화면에서 활성 코드
When[비활성화] 버튼 클릭
Then확인 모달 → 비활성화 완료

확인 모달:

┌─────────────────────────────────────┐
│ 추천 코드 비활성화                    │
├─────────────────────────────────────┤
│                                     │
│ SELLER-ABC123 코드를 비활성화합니다.  │
│                                     │
│ • 신규 추천이 불가능해집니다          │
│ • 기존 추천 관계는 유지됩니다         │
│ • 나중에 재활성화할 수 있습니다       │
│                                     │
│           [취소]  [비활성화]         │
└─────────────────────────────────────┘

AC-04: 추천 관계 상세 모달 ​

항목내용
Given피추천인 목록에서 행 클릭
When클릭
Then추천 관계 상세 모달 표시

UI 요소:

┌─────────────────────────────────────┐
│ 추천 관계 상세                [X]   │
├─────────────────────────────────────┤
│                                     │
│ 추천인: 맛있는가게 (12345)           │
│ 피추천인: 김셀러상점 (67890)         │
│ 추천 코드: SELLER-ABC123            │
│                                     │
│ ─── 진행 상태 ───                    │
│ ✅ 가입: 2026-01-15 10:30           │
│ ✅ 연동: 2026-01-16 14:20           │
│ ✅ 결제: 2026-01-20 09:15           │
│                                     │
│ ─── 리워드 지급 ───                  │
│ ✅ 연동 리워드: 7,000원 지급완료     │
│ ✅ 결제 리워드: 7,000원 지급완료     │
│                                     │
│                        [닫기]        │
└─────────────────────────────────────┘

태스크 분해 ​

Task 1: 추천 현황 목록 페이지 AC-01 ​

  • [ ] 1.1: 추천 관리 페이지 라우팅
  • [ ] 1.2: 목록 테이블 컴포넌트
  • [ ] 1.3: 필터 + 정렬 컴포넌트
  • [ ] 1.4: 페이지네이션
  • [ ] 1.5: API 연동

Task 2: 추천 코드 상세 페이지 AC-02 ​

  • [ ] 2.1: 상세 페이지 라우팅 (/admin/referrals/:code)
  • [ ] 2.2: 코드 정보 + 실적 요약 표시
  • [ ] 2.3: 피추천인 목록 테이블
  • [ ] 2.4: API 연동

Task 3: 비활성화 기능 AC-03 ​

  • [ ] 3.1: 비활성화 확인 모달
  • [ ] 3.2: 비활성화 API 연동
  • [ ] 3.3: 상태 갱신

Task 4: 추천 관계 상세 모달 AC-04 ​

  • [ ] 4.1: 상세 모달 컴포넌트
  • [ ] 4.2: API 연동

Task 5: 마무리 ​

  • [ ] 5.1: 에러 처리, 로딩 상태
  • [ ] 5.2: PR 생성

Dev Notes (AI Agent 최적화) ​

영향 받는 소스 트리 ​

src/
├── app/
│   └── admin/
│       └── referrals/
│           ├── page.tsx                 # 🆕 목록 페이지
│           ├── [code]/
│           │   └── page.tsx             # 🆕 상세 페이지
│           └── components/
│               ├── ReferralTable.tsx    # 🆕 목록 테이블
│               ├── RefereeList.tsx      # 🆕 피추천인 목록
│               ├── DeactivateModal.tsx  # 🆕 비활성화 모달
│               └── RelationModal.tsx    # 🆕 관계 상세 모달
├── hooks/
│   └── admin/
│       └── useReferrals.ts              # 🆕 추천인 API 훅
└── types/
    └── admin/
        └── referral.ts                  # 🆕 타입 정의

충돌 감지 ​

항목상태설명
기존 코드 충돌✅ 없음신규 페이지
라우팅 충돌✅ 없음/admin/referrals 신규

의존성 ​

의존설명상태
E-02-S-06추천인 관리 API선행 필요

Dev Agent Record ​

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

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

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

장사왕 Product Team

© 2026 장사왕