테마
E-02: 어드민 강화
담당: 하록님 (수민님) 상태: 설계 중 우선순위: P0
WHY (왜 필요한가?)
현재 문제
S52에서 쿠폰/추천인/크레딧 시스템이 구축되었지만, 운영 인터페이스가 없음.
[현재 프로모션 운영 플로우]
1. 마케팅팀: "신규 가입자 100원 쿠폰 만들어주세요"
2. 개발팀: DB 직접 INSERT
3. 마케팅팀: "쿠폰 사용 현황 알려주세요"
4. 개발팀: DB 쿼리 후 엑셀로 전달
→ 개발팀 병목, 프로모션 민첩성 저하운영 자립 필요성
| 상황 | 현재 | 목표 |
|---|---|---|
| 쿠폰 생성 | 개발팀 요청 | 어드민에서 직접 |
| 쿠폰 수정/중지 | 개발팀 요청 | 어드민에서 직접 |
| 사용 현황 조회 | DB 쿼리 요청 | 어드민에서 직접 |
| CS 크레딧 지급 | 개발팀 요청 | 어드민에서 직접 |
| 추천 현황 조회 | DB 쿼리 요청 | 어드민에서 직접 |
전략적 의미
- 개발팀 리소스 확보: 반복 운영 업무에서 해방 → 핵심 개발에 집중
- 프로모션 민첩성: 마케팅팀이 즉시 실행 가능
- CS 대응 속도: 크레딧 보상 즉시 처리 가능
- 데이터 접근성: 운영팀이 직접 현황 파악
WHAT (무엇을 만드는가?)
핵심 요구사항 (우선순위순)
1. 쿠폰 관리 (P0)
| 기능 | 설명 |
|---|---|
| 쿠폰 목록 조회 | 전체 쿠폰 리스트 + 필터/검색 |
| 쿠폰 상세 조회 | 개별 쿠폰 정보 + 사용 통계 |
| 쿠폰 생성 | 코드, 유형, 할인 정보, 조건 설정 |
| 쿠폰 수정 | 기간, 사용 횟수, 활성화 상태 변경 |
| 쿠폰 비활성화 | 즉시 사용 중지 (삭제 대신) |
| 사용 이력 조회 | 누가, 언제, 얼마 할인 받았는지 |
2. 크레딧 관리 (P1)
| 기능 | 설명 |
|---|---|
| 잔액 조회 | 특정 사업장 크레딧 잔액 |
| 크레딧 지급 | CS 보상, 프로모션 크레딧 발급 |
| 거래 이력 조회 | EARN/USE/EXPIRE 등 전체 이력 |
3. 추천인 관리 (P2)
| 기능 | 설명 |
|---|---|
| 추천 현황 조회 | 추천인별 실적 (가입/연동/결제) |
| 추천 코드 관리 | 코드 비활성화 (부정 사용 대응) |
| 추천 관계 조회 | 추천인-피추천인 관계 확인 |
적용 범위
- 어드민 전용: 일반 사용자에게 노출 안 됨
- 권한 관리: 역할별 접근 제어 (추후 확장)
HOW (어떻게 구현하는가?)
관련 테이블 (S52 E-07에서 구축)
[쿠폰]
Coupon
├── code, type (FIXED/PERCENT/TRIAL_EXT)
├── discountAmount, discountPercent, maxDiscount, trialDays
├── minAmount, startDate, endDate
├── maxUsageTotal, maxUsagePerUser
├── applicablePlans (JSON), firstOnlyYn
├── activeYn, usedCount
└── description
CouponUsage
├── couponId, bizId, paymentId
├── totalAmount, discountAmount, amount
├── status (APPLIED/COMPLETED/CANCELLED)
└── appliedAt, completedAt, canceledAt
[크레딧]
CreditBalance
├── bizId, balance
├── totalEarned, totalUsed, totalExpired
└── timestamps
CreditLedger
├── bizId, type (EARN/USE/EXPIRE/REFUND/HOLD/CANCEL)
├── amount, balanceAfter
├── reason, referralId, paymentId
├── expireAt, usedAmount, expiredAmount, consumedYn
└── timestamps
[추천인]
ReferralCode
├── code (SELLER-XXXXXX)
├── bizId
├── totalReferrals, activeCount, paidReferrals
└── activeYn
Referral
├── referrerId, refereeId, referralCode
├── status (JOINED/LINKED/PAID)
├── signedUpAt, storeLinkedAt, paidAt
└── storeRewardYn, payRewardYnAPI 설계 (어드민용)
쿠폰 API
| Endpoint | Method | 설명 |
|---|---|---|
/admin/coupons | GET | 쿠폰 목록 (페이지네이션 + 필터) |
/admin/coupons/:id | GET | 쿠폰 상세 + 사용 통계 |
/admin/coupons | POST | 쿠폰 생성 |
/admin/coupons/:id | PATCH | 쿠폰 수정 |
/admin/coupons/:id/deactivate | POST | 쿠폰 비활성화 |
/admin/coupons/:id/usages | GET | 쿠폰 사용 이력 |
크레딧 API
| Endpoint | Method | 설명 |
|---|---|---|
/admin/credits/balance/:bizId | GET | 잔액 조회 |
/admin/credits/grant | POST | 크레딧 지급 |
/admin/credits/deduct | POST | 크레딧 차감/취소 |
/admin/credits/ledger/:bizId | GET | 거래 이력 |
추천인 API
| Endpoint | Method | 설명 |
|---|---|---|
/admin/referrals | GET | 추천 현황 목록 |
/admin/referrals/codes/:code | GET | 추천 코드 상세 |
/admin/referrals/codes/:code/deactivate | POST | 코드 비활성화 |
/admin/referrals/codes/:code/activate | POST | 코드 재활성화 |
/admin/referrals/:id | GET | 추천 관계 상세 |
사업장 API
| Endpoint | Method | 설명 |
|---|---|---|
/admin/biz/search | GET | 사업장 검색 |
/admin/biz/:bizId | GET | 사업장 상세 조회 |
UI 설계 (어드민)
[어드민 메뉴 구조]
프로모션 관리
├── 쿠폰 관리
│ ├── 쿠폰 목록 (테이블 + 필터)
│ ├── 쿠폰 생성 (폼)
│ └── 쿠폰 상세 (정보 + 사용 이력)
├── 크레딧 관리
│ ├── 잔액 조회 (검색)
│ ├── 크레딧 지급 (폼)
│ └── 거래 이력 (테이블)
└── 추천인 관리
├── 추천 현황 (테이블)
├── 추천 코드 관리
└── 추천 관계 조회EDGE (예외/엣지 케이스)
| 케이스 | 처리 방안 |
|---|---|
| 사용 중인 쿠폰 삭제 | 삭제 대신 비활성화만 허용 |
| 중복 쿠폰 코드 | 코드 유니크 검증 (DB UK 활용) |
| 과거 날짜 쿠폰 생성 | startDate 검증 (현재 이후만) |
| 크레딧 마이너스 지급 | 금액 양수 검증 |
| 존재하지 않는 bizId | 사업장 존재 여부 검증 |
| 비활성화된 추천 코드 재활성화 | 허용 (관리자 판단) |
검증 계획
| 항목 | 검증 방법 |
|---|---|
| 쿠폰 CRUD | 생성 → 수정 → 사용 → 비활성화 플로우 |
| 크레딧 지급 | 지급 → 잔액 확인 → 이력 확인 |
| 추천 현황 | 실제 데이터로 정합성 확인 |
| 동시성 | 여러 관리자 동시 수정 시 충돌 처리 |
성공 기준 (KR2)
| 지표 | 목표 |
|---|---|
| 프로모션 운영 자립도 | 개발팀 의존 0건 |
| 쿠폰 생성~사용 리드타임 | 당일 처리 가능 |
| CS 크레딧 지급 리드타임 | 즉시 처리 가능 |
의존성
| 의존 | 설명 |
|---|---|
| S52 E-07 | 쿠폰/추천인/크레딧 테이블 구축 완료 |
| 어드민 프레임워크 | 기존 어드민 페이지 구조 활용 |
| 권한 관리 | 기본 admin 권한 사용 (추후 세분화) |
Story 목록
| Story ID | 제목 | 영역 | 규모 | 우선순위 | 상태 |
|---|---|---|---|---|---|
| E-02-S-01 | 쿠폰 목록/상세/이력 API | BE | M | P0 | draft |
| E-02-S-02 | 쿠폰 생성/수정/비활성화 API | BE | M | P0 | draft |
| E-02-S-03 | 쿠폰 관리 UI | FE | L | P0 | draft |
| E-02-S-04 | 크레딧 관리 API (지급/차감) | BE | S | P1 | draft |
| E-02-S-05 | 크레딧 관리 UI | FE | M | P1 | draft |
| E-02-S-06 | 추천인 관리 API | BE | S | P2 | draft |
| E-02-S-07 | 추천인 관리 UI | FE | M | P2 | draft |
| E-02-S-08 | 사업장 검색 API | BE | S | P1 | draft |
의존성 그래프
[공통]
E-02-S-08 (사업장 검색 BE) ──┬──→ E-02-S-03 (쿠폰 FE)
├──→ E-02-S-05 (크레딧 FE)
└──→ E-02-S-07 (추천인 FE)
[P0 쿠폰]
E-02-S-01 (BE 조회) ──┬──→ E-02-S-03 (FE)
E-02-S-02 (BE CUD) ──┘
[P1 크레딧]
E-02-S-04 (BE) ─────────→ E-02-S-05 (FE)
[P2 추천인]
E-02-S-06 (BE) ─────────→ E-02-S-07 (FE)참고 자료
- S52 E-07 DDL:
~/Downloads/DDL_E-07_쿠폰추천인시스템_20260122.sql - S52 Track 7 컨텍스트:
.context/sprints/s52/tracks/track-07/context.md - 전략 문서:
.context/global/strategy.md
생성일: 2026-01-27최종 수정: 2026-01-27