테마
Story: 크레딧 관리 UI
메타
| 항목 | 값 |
|---|---|
| Story ID | E-02-S-05 |
| Epic | E-02 어드민 강화 |
| 상태 | draft |
| 우선순위 | P1 |
| 규모 | M |
| 담당 개발자 | FE (수민님) |
사용자 스토리
As a CS팀/운영팀 관리자, I want 어드민에서 크레딧을 조회하고 지급하는 UI, So that CS 보상을 즉시 처리할 수 있다.
수락 기준 (Acceptance Criteria)
AC-01: 크레딧 관리 메인 화면
| 항목 | 내용 |
|---|---|
| Given | 크레딧 관리 메뉴 진입 |
| When | 페이지 로드 |
| Then | 사업장 검색 + 크레딧 지급 폼 표시 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ 크레딧 관리 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ─── 사업장 검색 ─── │
│ │
│ 사업장 검색 [사업장명 또는 ID 입력____] [검색] │
│ │
│ ─── 검색 결과 (사업장 선택 후 표시) ─── │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 맛있는가게 (ID: 12345) [선택] │ │
│ │ 현재 잔액: 7,000원 │ │
│ │ 총 적립: 10,000원 / 총 사용: 3,000원 / 만료: 0원 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ─── 크레딧 지급 (사업장 선택 후 활성화) ─── │
│ │
│ 지급 금액 * [1000] 원 │
│ 지급 사유 * [CS 보상 - 연동 오류 불편____] │
│ 만료일 [2026-04-27] (기본 90일 후) │
│ │
│ [지급하기] │
│ │
└─────────────────────────────────────────────────────────────────┘AC-02: 사업장 검색
| 항목 | 내용 |
|---|---|
| Given | 사업장명 또는 ID 입력 |
| When | 검색 버튼 클릭 |
| Then | 매칭되는 사업장 목록 표시 (최대 10건) |
상세 스펙:
- 사업장명 부분 검색 (LIKE)
- bizId 정확히 일치
- 검색 결과에 현재 잔액 표시
- 사업장 선택 시 상세 정보 로드
AC-03: 크레딧 지급
| 항목 | 내용 |
|---|---|
| Given | 사업장 선택 + 지급 정보 입력 |
| When | [지급하기] 버튼 클릭 |
| Then | 확인 모달 → 지급 완료 → 잔액 갱신 |
확인 모달:
┌─────────────────────────────────────┐
│ 크레딧 지급 확인 │
├─────────────────────────────────────┤
│ │
│ 대상: 맛있는가게 (12345) │
│ 금액: 1,000원 │
│ 사유: CS 보상 - 연동 오류 불편 │
│ 만료: 2026-04-27 │
│ │
│ 지급하시겠습니까? │
│ │
│ [취소] [지급 확정] │
└─────────────────────────────────────┘AC-04: 거래 이력 조회
| 항목 | 내용 |
|---|---|
| Given | 사업장 선택 상태 |
| When | [거래 이력] 탭 또는 버튼 클릭 |
| Then | 해당 사업장의 크레딧 거래 이력 표시 |
UI 요소:
┌─────────────────────────────────────────────────────────────────┐
│ 거래 이력 - 맛있는가게 (12345) [닫기] │
├─────────────────────────────────────────────────────────────────┤
│ 필터: [전체 ▼] │
├─────────────────────────────────────────────────────────────────┤
│ 유형 │ 금액 │ 잔액 │ 사유 │ 일시 │
├────────┼────────────┼───────────┼───────────────────┼──────────┤
│ 적립 │ +1,000원 │ 7,000원 │ CS 보상 │ 01/27 │
│ 사용 │ -3,000원 │ 6,000원 │ 결제 차감 │ 01/26 │
│ 적립 │ +7,000원 │ 9,000원 │ 추천인 리워드 │ 01/25 │
│ 적립 │ +2,000원 │ 2,000원 │ 가입 환영 │ 01/20 │
├─────────────────────────────────────────────────────────────────┤
│ [< 1 2 >] │
└─────────────────────────────────────────────────────────────────┘AC-05: 에러 처리
| 항목 | 내용 |
|---|---|
| Given | 지급 실패 (사업장 없음, 금액 오류 등) |
| When | API 에러 응답 |
| Then | 토스트 에러 메시지 표시 |
태스크 분해
Task 1: 크레딧 관리 페이지 AC-01
- [ ] 1.1: 크레딧 관리 페이지 라우팅
- [ ] 1.2: 레이아웃 구성 (검색 + 상세 + 지급)
- [ ] 1.3: 상태 관리 (선택된 사업장)
Task 2: 사업장 검색 AC-02
- [ ] 2.1: 검색 입력 컴포넌트
- [ ] 2.2: 검색 결과 목록 컴포넌트
- [ ] 2.3: 사업장 검색 API 연동 (기존 어드민 API 활용)
- [ ] 2.4: 사업장 선택 시 잔액 API 호출
Task 3: 크레딧 지급 폼 AC-03
- [ ] 3.1: 지급 폼 컴포넌트
- [ ] 3.2: 유효성 검증 (금액 > 0, 사유 필수)
- [ ] 3.3: 확인 모달 컴포넌트
- [ ] 3.4: 지급 API 연동
- [ ] 3.5: 성공 시 잔액 갱신
Task 4: 거래 이력 AC-04
- [ ] 4.1: 거래 이력 모달/패널 컴포넌트
- [ ] 4.2: 이력 테이블 + 필터
- [ ] 4.3: 페이지네이션
- [ ] 4.4: 이력 API 연동
Task 5: 에러 처리 및 UX AC-05
- [ ] 5.1: 토스트 알림
- [ ] 5.2: 로딩 상태
- [ ] 5.3: 빈 상태 처리
Task 6: 마무리
- [ ] 6.1: PR 생성
Dev Notes (AI Agent 최적화)
영향 받는 소스 트리
src/
├── app/
│ └── admin/
│ └── credits/
│ ├── page.tsx # 🆕 크레딧 관리 페이지
│ └── components/
│ ├── BizSearch.tsx # 🆕 사업장 검색
│ ├── CreditInfo.tsx # 🆕 잔액 정보
│ ├── GrantForm.tsx # 🆕 지급 폼
│ └── LedgerModal.tsx # 🆕 거래 이력
├── hooks/
│ └── admin/
│ └── useCredits.ts # 🆕 크레딧 API 훅
└── types/
└── admin/
└── credit.ts # 🆕 타입 정의충돌 감지
| 항목 | 상태 | 설명 |
|---|---|---|
| 기존 코드 충돌 | ✅ 없음 | 신규 페이지 |
| 라우팅 충돌 | ✅ 없음 | /admin/credits 신규 |
의존성
| 의존 | 설명 | 상태 |
|---|---|---|
| E-02-S-04 | 크레딧 관리 API | 선행 필요 |
| 사업장 검색 API | 기존 어드민 API | 확인 필요 |
Dev Agent Record
| 항목 | 값 |
|---|---|
| 생성 Agent | Claude Opus 4.5 |
| 생성일 | 2026-01-27 |
| 마지막 수정 | 2026-01-27 |
| 검증자 | - |
검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -
생성일: 2026-01-27마지막 수정: 2026-01-27