Story: 검색/비검색 API 개발

메타

항목	값
Story ID	E-02-S-02
Epic	E-02 Deep Layer
상태	ready-for-dev
우선순위	P0
규모	L
담당 개발자	하록 (BE)

---

사용자 스토리

As a 중수 셀러,
I want 검색 광고와 비검색 광고 성과를 분리해서 보고 싶다,
So that 각 광고 유형별로 최적화 의사결정을 내릴 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 캠페인별 검색/비검색 분리 API

항목	내용
Given	FE에서 캠페인 상세 API를 호출할 때
When	adType 파라미터로 SEARCH 또는 NON_SEARCH를 전달하면
Then	해당 유형의 광고 데이터만 반환된다

AC-02: 검색 광고 - 키워드별 성과

항목	내용
Given	검색 광고 데이터 조회 시
When	API 응답에
Then	키워드별 성과 데이터가 포함된다 (키워드, 광고비, 매출, ROAS)

AC-03: 비검색 광고 - 상품별 성과

항목	내용
Given	비검색 광고 데이터 조회 시
When	API 응답에
Then	상품별 성과 데이터가 포함된다 (상품명, 광고비, 매출, ROAS)

AC-04: 기간 필터 지원

항목	내용
Given	API 호출 시 startDate, endDate 파라미터 전달
When	쿼리 실행 시
Then	해당 기간의 데이터만 집계하여 반환

---

태스크 분해

Task 1: API 엔드포인트 설계

• [ ] 1.1: GET /api/ad-analysis/campaigns/:campaignId?adType=SEARCH&startDate=&endDate=
• [ ] 1.2: Response DTO 정의

Task 2: 검색 광고 쿼리 AC-01, AC-02

• [ ] 2.1: CoupangAdKeywordDaily 테이블에서 keyword IS NOT NULL 필터링
• [ ] 2.2: 키워드별 집계 쿼리 구현

Task 3: 비검색 광고 쿼리 AC-01, AC-03

• [ ] 3.1: keyword IS NULL 필터링
• [ ] 3.2: 상품별 집계 쿼리 구현

Task 4: 기간 필터 AC-04

• [ ] 4.1: 날짜 범위 파라미터 처리
• [ ] 4.2: 인덱스 활용 쿼리 최적화

Task 5: 테스트

• [ ] 5.1: 단위 테스트
• [ ] 5.2: 통합 테스트

---

Dev Notes

데이터 소스

-- 검색 광고 (keyword 존재)
SELECT keyword, SUM(adCost), SUM(conversionAmount), ...
FROM CoupangAdKeywordDaily
WHERE vendorId = ? AND campaignId = ? AND keyword IS NOT NULL
  AND adDate BETWEEN ? AND ?
GROUP BY keyword;

-- 비검색 광고 (keyword NULL)
SELECT productId, productName, SUM(adCost), SUM(conversionAmount), ...
FROM CoupangAdKeywordDaily
WHERE vendorId = ? AND campaignId = ? AND keyword IS NULL
  AND adDate BETWEEN ? AND ?
GROUP BY productId, productName;

영향 받는 소스 트리

sellerking-api/
├── src/
│   ├── ad-analysis/
│   │   ├── ad-analysis.controller.ts    # 엔드포인트 추가
│   │   ├── ad-analysis.service.ts       # 검색/비검색 로직
│   │   └── dto/
│   │       └── campaign-detail.dto.ts   # 🆕 신규
│   └── repositories/
│       └── coupang-ad.repository.ts     # 쿼리 추가

---

생성일: 2026-01-20