테마
Story: 쿠폰 관리 UI
메타
| 항목 | 값 |
|---|---|
| Story ID | E-02-S-03 |
| Epic | E-02 어드민 강화 |
| 상태 | draft |
| 우선순위 | P0 |
| 규모 | L |
| 담당 개발자 | FE (수민님) |
사용자 스토리
As a 운영팀 관리자, I want 어드민에서 쿠폰을 직접 관리하는 UI, So that 개발팀 요청 없이 프로모션을 즉시 실행할 수 있다.
수락 기준 (Acceptance Criteria)
AC-01: 쿠폰 목록 화면
| 항목 | 내용 |
|---|---|
| Given | 쿠폰 관리 메뉴 진입 |
| When | 페이지 로드 |
| Then | 쿠폰 목록이 테이블로 표시됨 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ 쿠폰 관리 [+ 쿠폰 생성] │
├─────────────────────────────────────────────────────────────────┤
│ 필터: [상태 ▼] [유형 ▼] [기간 📅~📅] 검색: [코드/설명____] │
├─────────────────────────────────────────────────────────────────┤
│ 코드 │ 유형 │ 할인 │ 기간 │ 사용 │ 상태 │
├────────────┼────────┼──────────┼────────────────┼───────┼───────┤
│ WELCOME100 │ 정액 │ 100원 │ 01/01~01/31 │ 45/∞ │ 🟢 │
│ SAVE10 │ 정률 │ 10% │ 01/15~02/15 │ 12/50 │ 🟢 │
│ TRIAL7 │ 체험 │ 7일 연장 │ 01/01~12/31 │ 3/10 │ 🔴 │
├─────────────────────────────────────────────────────────────────┤
│ [< 1 2 3 4 5 >] │
└─────────────────────────────────────────────────────────────────┘상세 스펙:
- 필터: 상태(전체/활성/비활성), 유형(전체/정액/정률/체험연장), 기간
- 검색: 코드, 설명 동시 검색
- 정렬: 컬럼 헤더 클릭으로 정렬
- 페이지네이션: 20건/페이지
- 상태 뱃지: 🟢 활성, 🔴 비활성
- 행 클릭 → 상세 화면 이동
AC-02: 쿠폰 생성 폼
| 항목 | 내용 |
|---|---|
| Given | [+ 쿠폰 생성] 버튼 클릭 |
| When | 생성 모달/페이지 표시 |
| Then | 쿠폰 생성 폼이 표시됨 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ 쿠폰 생성 [X] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 쿠폰 코드 * [WELCOME100_______] │
│ │
│ 쿠폰 유형 * (●) 정액 할인 ( ) 정률 할인 ( ) 무료체험 연장 │
│ │
│ ─── 정액 할인 선택 시 ─── │
│ 할인 금액 * [1000] 원 │
│ │
│ ─── 정률 할인 선택 시 ─── │
│ 할인율 * [10] % │
│ 최대 할인 [5000] 원 (선택) │
│ │
│ ─── 무료체험 연장 선택 시 ─── │
│ 연장 일수 * [7] 일 │
│ │
│ ─── 공통 ─── │
│ 설명 [신규 가입 환영 쿠폰_______________] │
│ 사용 기간 * [2026-01-01] ~ [2026-01-31] │
│ 최소 결제금액 [0] 원 │
│ 총 사용 횟수 [100] 회 (비워두면 무제한) │
│ 인당 사용 [1] 회 │
│ 적용 플랜 [전체 ▼] │
│ 첫 결제만 [ ] 첫 결제에만 사용 가능 │
│ │
│ [취소] [생성하기] │
└─────────────────────────────────────────────────────────────────┘상세 스펙:
- 유형 선택 시 해당 필드만 표시 (조건부 렌더링)
- 실시간 유효성 검증 (코드 형식, 날짜 등)
- 코드 중복 검사 (blur 시 API 호출 또는 생성 시)
- 필수 필드 표시 (*)
AC-03: 쿠폰 상세/수정 화면
| 항목 | 내용 |
|---|---|
| Given | 목록에서 쿠폰 행 클릭 |
| When | 상세 화면 로드 |
| Then | 쿠폰 정보 + 수정 폼 + 사용 이력 표시 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ ← 목록 WELCOME100 [비활성화] [저장] │
├─────────────────────────────────────────────────────────────────┤
│ [정보] [사용 이력] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 쿠폰 코드 WELCOME100 (수정 불가) │
│ 쿠폰 유형 정액 할인 (수정 불가) │
│ 할인 금액 100원 (수정 불가) │
│ │
│ 설명 [신규 가입 환영 쿠폰_______________] │
│ 종료일 [2026-01-31] (연장만 가능) │
│ 총 사용 횟수 [150] 회 (기존 100, 증가만 가능) │
│ 인당 사용 [1] 회 │
│ 상태 (●) 활성 ( ) 비활성 │
│ │
│ ─── 사용 통계 ─── │
│ 총 사용 45회 │
│ 총 할인액 4,500원 │
│ 최근 사용 2026-01-26 15:30 │
│ │
└─────────────────────────────────────────────────────────────────┘상세 스펙:
- 수정 불가 필드: 읽기 전용 표시 + 툴팁 설명
- 수정 가능 필드: 입력 폼
- 비활성화 버튼: 확인 모달 후 실행
- 탭 전환: 정보 / 사용 이력
AC-04: 사용 이력 탭
| 항목 | 내용 |
|---|---|
| Given | 상세 화면에서 [사용 이력] 탭 클릭 |
| When | 탭 전환 |
| Then | 해당 쿠폰 사용 이력 테이블 표시 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ [정보] [사용 이력] │
├─────────────────────────────────────────────────────────────────┤
│ 필터: [상태 ▼] │
├─────────────────────────────────────────────────────────────────┤
│ 사업장 │ 결제금액 │ 할인금액 │ 실결제 │ 상태 │ 일시 │
├─────────────┼───────────┼──────────┼──────────┼────────┼────────┤
│ 맛있는가게 │ 9,900원 │ 100원 │ 9,800원 │ 완료 │ 01/26 │
│ 신선마트 │ 9,900원 │ 100원 │ 9,800원 │ 완료 │ 01/25 │
│ 행복상점 │ 9,900원 │ 100원 │ - │ 취소 │ 01/24 │
├─────────────────────────────────────────────────────────────────┤
│ [< 1 2 3 >] │
└─────────────────────────────────────────────────────────────────┘AC-05: 에러 처리
| 항목 | 내용 |
|---|---|
| Given | API 에러 발생 (중복 코드, 유효성 등) |
| When | 생성/수정 시도 |
| Then | 토스트 또는 인라인 에러 메시지 표시 |
태스크 분해
Task 1: 쿠폰 목록 페이지 AC-01
- [ ] 1.1: 쿠폰 목록 페이지 라우팅 설정
- [ ] 1.2: 목록 테이블 컴포넌트 구현
- [ ] 1.3: 필터 컴포넌트 (상태, 유형, 기간)
- [ ] 1.4: 검색 컴포넌트
- [ ] 1.5: 페이지네이션 컴포넌트
- [ ] 1.6: API 연동 (React Query)
Task 2: 쿠폰 생성 폼 AC-02
- [ ] 2.1: 생성 모달/페이지 컴포넌트
- [ ] 2.2: 유형별 조건부 렌더링
- [ ] 2.3: 폼 유효성 검증 (react-hook-form + zod)
- [ ] 2.4: 생성 API 연동
- [ ] 2.5: 성공/에러 토스트
Task 3: 쿠폰 상세/수정 화면 AC-03
- [ ] 3.1: 상세 페이지 라우팅 (
/admin/coupons/:id) - [ ] 3.2: 상세 정보 + 통계 표시
- [ ] 3.3: 수정 폼 (제한 필드 처리)
- [ ] 3.4: 비활성화 확인 모달
- [ ] 3.5: 수정/비활성화 API 연동
Task 4: 사용 이력 탭 AC-04
- [ ] 4.1: 탭 컴포넌트 구현
- [ ] 4.2: 사용 이력 테이블
- [ ] 4.3: 필터 및 페이지네이션
- [ ] 4.4: 이력 API 연동
Task 5: 에러 처리 및 UX AC-05
- [ ] 5.1: 토스트 알림 시스템
- [ ] 5.2: 인라인 에러 메시지
- [ ] 5.3: 로딩 상태 처리
- [ ] 5.4: 빈 상태 처리 (데이터 없음)
Task 6: 마무리
- [ ] 6.1: 반응형 대응 (필요시)
- [ ] 6.2: 접근성 검토
- [ ] 6.3: PR 생성
Dev Notes (AI Agent 최적화)
아키텍처 패턴
| 항목 | 내용 |
|---|---|
| 사용할 패턴 | 기존 어드민 페이지 구조 따름 |
| 참고 구현 | 기존 어드민 목록/상세 페이지 |
| 피해야 할 것 | 새로운 UI 패턴 도입 (일관성 유지) |
영향 받는 소스 트리
src/
├── app/
│ └── admin/
│ └── coupons/
│ ├── page.tsx # 🆕 목록 페이지
│ ├── [id]/
│ │ └── page.tsx # 🆕 상세 페이지
│ └── components/
│ ├── CouponTable.tsx # 🆕 목록 테이블
│ ├── CouponForm.tsx # 🆕 생성/수정 폼
│ ├── CouponFilters.tsx # 🆕 필터
│ └── UsageHistory.tsx # 🆕 사용 이력
├── hooks/
│ └── admin/
│ └── useCoupons.ts # 🆕 쿠폰 API 훅
└── types/
└── admin/
└── coupon.ts # 🆕 타입 정의기술 스택
| 항목 | 사용 기술 | 버전 |
|---|---|---|
| 프레임워크 | Next.js | 기존 버전 |
| 상태관리 | React Query | 기존 버전 |
| 폼 관리 | react-hook-form + zod | 기존 버전 |
| UI 컴포넌트 | 기존 디자인 시스템 | - |
충돌 감지
| 항목 | 상태 | 설명 |
|---|---|---|
| 기존 코드 충돌 | ✅ 없음 | 신규 페이지 |
| 라우팅 충돌 | ✅ 없음 | /admin/coupons 신규 |
| 컴포넌트 충돌 | ✅ 없음 | 신규 컴포넌트 |
References
| 출처 | 경로/링크 | 참조 섹션 |
|---|---|---|
| Epic Spec | .context/sprints/s53/epic-specs/E-02.md | UI 설계 |
| BE API | E-02-S-01, E-02-S-02 | API 스펙 |
| 기존 어드민 | src/app/admin/ | 패턴 참고 |
의존성
| 의존 | 설명 | 상태 |
|---|---|---|
| E-02-S-01 | 쿠폰 목록/상세/이력 API | 선행 필요 |
| E-02-S-02 | 쿠폰 생성/수정/비활성화 API | 선행 필요 |
Dev Agent Record
| 항목 | 값 |
|---|---|
| 생성 Agent | Claude Opus 4.5 |
| 생성일 | 2026-01-27 |
| 마지막 수정 | 2026-01-27 |
| 검증자 | - |
검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -
생성일: 2026-01-27마지막 수정: 2026-01-27