Story: 쿠폰 목록/상세/이력 API

메타

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

---

사용자 스토리

As a 운영팀 관리자, I want 쿠폰 목록을 조회하고 상세 정보와 사용 이력을 확인, So that 프로모션 현황을 파악하고 의사결정할 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 쿠폰 목록 조회

항목	내용
Given	관리자가 어드민에 로그인한 상태
When	쿠폰 관리 메뉴에 진입
Then	전체 쿠폰 목록이 페이지네이션으로 표시됨

상세 스펙:

• 페이지당 20건 (조정 가능)
• 정렬: 생성일 최신순 (기본)
• 필터: 상태(활성/비활성), 유형(FIXED/PERCENT/TRIAL_EXT), 기간
• 검색: 쿠폰 코드, 설명

응답 필드:

{
  items: [{
    id, code, type, description,
    discountAmount, discountPercent, trialDays,
    startDate, endDate,
    activeYn, usedCount, maxUsageTotal,
    createdAt
  }],
  pagination: { page, size, total, totalPages }
}

AC-02: 쿠폰 상세 조회

항목	내용
Given	쿠폰 목록에서 특정 쿠폰 선택
When	쿠폰 상세 조회 요청
Then	쿠폰 전체 정보 + 사용 통계가 표시됨

상세 스펙:

• 쿠폰 전체 필드 반환
• 사용 통계 포함:
  • 총 사용 횟수
  • 총 할인 금액
  • 최근 사용일

응답 필드:

{
  coupon: {
    id, code, type, description,
    discountAmount, discountPercent, maxDiscount, trialDays,
    minAmount, startDate, endDate,
    maxUsageTotal, maxUsagePerUser,
    applicablePlans, firstOnlyYn,
    activeYn, usedCount,
    createdAt, updatedAt
  },
  stats: {
    totalUsageCount,
    totalDiscountAmount,
    lastUsedAt
  }
}

AC-03: 쿠폰 사용 이력 조회

항목	내용
Given	쿠폰 상세 화면에서
When	사용 이력 탭 클릭
Then	해당 쿠폰의 사용 이력 목록이 표시됨

상세 스펙:

• 페이지당 20건
• 정렬: 사용일 최신순
• 필터: 상태(APPLIED/COMPLETED/CANCELLED)

응답 필드:

{
  items: [{
    id, couponId,
    bizId, bizName,  // 사업장 정보 조인
    totalAmount, discountAmount, amount,
    status,
    appliedAt, completedAt, canceledAt
  }],
  pagination: { page, size, total, totalPages }
}

AC-04: 존재하지 않는 쿠폰 조회

항목	내용
Given	삭제되었거나 존재하지 않는 쿠폰 ID
When	상세/이력 조회 요청
Then	404 Not Found 응답

---

태스크 분해

Task 1: 쿠폰 목록 API AC-01

• [ ] 1.1: GET /admin/coupons 엔드포인트 생성
• [ ] 1.2: 페이지네이션 로직 구현 (page, size)
• [ ] 1.3: 필터 로직 구현 (activeYn, type, startDate~endDate)
• [ ] 1.4: 검색 로직 구현 (code, description LIKE)
• [ ] 1.5: 정렬 로직 구현 (sortBy, sortOrder)

Task 2: 쿠폰 상세 API AC-02

• [ ] 2.1: GET /admin/coupons/:id 엔드포인트 생성
• [ ] 2.2: 쿠폰 전체 필드 조회
• [ ] 2.3: 사용 통계 집계 쿼리 (CouponUsage 테이블)
• [ ] 2.4: 404 처리 로직

Task 3: 쿠폰 사용 이력 API AC-03

• [ ] 3.1: GET /admin/coupons/:id/usages 엔드포인트 생성
• [ ] 3.2: CouponUsage + Biz 조인 쿼리
• [ ] 3.3: 페이지네이션 및 필터 로직
• [ ] 3.4: 404 처리 (쿠폰 존재 여부)

Task 4: 테스트 작성 AC-01, AC-02, AC-03, AC-04

• [ ] 4.1: 목록 API 단위 테스트 (필터, 페이지네이션)
• [ ] 4.2: 상세 API 단위 테스트 (통계 포함)
• [ ] 4.3: 이력 API 단위 테스트
• [ ] 4.4: 404 케이스 테스트

Task 5: 마무리

• [ ] 5.1: API 문서화 (Swagger/OpenAPI)
• [ ] 5.2: 코드 리뷰 준비
• [ ] 5.3: PR 생성

---

Dev Notes (AI Agent 최적화)

아키텍처 패턴

항목	내용
사용할 패턴	Repository Pattern + Service Layer
참고 구현	기존 어드민 API 패턴 참고
피해야 할 것	Controller에 비즈니스 로직 직접 작성

영향 받는 소스 트리

src/
├── admin/
│   ├── coupon/
│   │   ├── coupon.admin.controller.ts  # 🆕 신규 생성
│   │   ├── coupon.admin.service.ts     # 🆕 신규 생성
│   │   └── dto/
│   │       ├── coupon-list.dto.ts      # 🆕 신규 생성
│   │       └── coupon-detail.dto.ts    # 🆕 신규 생성
│   └── admin.module.ts                 # 수정 (coupon 모듈 등록)
├── coupon/
│   └── coupon.repository.ts            # 수정 (어드민용 메서드 추가)
└── tests/
    └── admin/
        └── coupon.admin.spec.ts        # 🆕 신규 생성

기술 스택

항목	사용 기술	버전
프레임워크	NestJS	기존 버전
ORM	Prisma	기존 버전
인증	기존 Admin Guard	-

테스트 기준

유형	필요 여부	대상/시나리오
단위 테스트	✅	Service 메서드
통합 테스트	✅	API 엔드포인트
E2E 테스트	❌	-

충돌 감지

항목	상태	설명
기존 코드 충돌	✅ 없음	신규 어드민 API
API 계약 변경	✅ 없음	신규 엔드포인트
DB 스키마 변경	✅ 없음	기존 테이블 사용
환경 변수 변경	✅ 없음	-

---

References

출처	경로/링크	참조 섹션
Epic Spec	.context/sprints/s53/epic-specs/E-02.md	쿠폰 API 설계
테이블 스키마	S52 E-07 DDL	Coupon, CouponUsage
기존 어드민	src/admin/	패턴 참고

---

이벤트 로깅

이벤트명	트리거	파라미터	GA4 여부
-	어드민 내부 기능, GA4 로깅 불필요	-	❌

---

Dev Agent Record

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

---

핸드오프 전 체크리스트

문맥 & 요구사항

• [x] 사용자 스토리가 명확한가?
• [x] 수락 기준이 Given-When-Then 형식인가?
• [x] 모든 엣지 케이스가 정의되었는가?

재해 예방

• [x] 기존 코드에 유사 기능 확인했는가?
• [x] 충돌 감지 항목에 ⚠️가 없는가?
• [x] 라이브러리 버전 호환성 확인했는가?

AI Agent 최적화

• [x] Dev Notes가 충분히 상세한가?
• [x] References가 정확한가?
• [x] 태스크 분해가 구체적인가?

최종 점검

• [x] 이벤트 로깅이 정의되었는가? (해당 없음)
• [ ] 상태가 ready-for-dev로 설정되었는가?

---

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

---

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