Epic Spec: E-12 Keyword Analysis (Deep Layer)

메타

항목	값
Epic ID	E-12
Sprint	S52
상태	`approved`
PO 승인일	2026-01-28
담당	수민 (FE), 하록 (BE)

1. WHY: 왜 이 기능이 필요한가?

문제 정의

셀러는 "어떤 키워드가 광고비를 까먹는지" 알고 싶다. 현재는 쿠팡 광고센터 → 엑셀 export → 수동 분석을 해야 하는데, ROAS만 봐서는 진짜 남는 돈을 알 수 없다.

[현재 셀러의 워크플로우]

1. 쿠팡 광고센터 접속
2. 키워드별 데이터 엑셀 export
3. CPC 높고 전환율 낮은 순으로 정렬
4. 제외할 키워드 선택
5. 다시 쿠팡 광고센터로 돌아가서 제외 키워드 등록

→ 번거롭고, ROAS만으로는 "진짜 남는 돈"을 알 수 없음

[쿠팡 광고센터의 한계]

쿠팡: "이 키워드 ROAS 300%입니다"
셀러: "그래서 돈 번 거야 잃은 거야?"
      → 마진율 모르면 판단 불가
      → 마진율 20% 셀러는 ROAS 300%여도 손해
      → 마진율 40% 셀러는 ROAS 300%면 이득

장사왕만의 해자: 순이익 기반 분석

장사왕은 셀러의 **원가(마진율)**를 알고 있다. 따라서 ROAS가 아닌 순이익 기준으로 키워드를 평가할 수 있다.

셀러 질문	쿠팡 광고센터	장사왕 키워드 탭
이 키워드 돈 버나?	ROAS 300%... 좋은 건가?	순이익 -2만원 (빨간색)
검토할 키워드는?	CPC↑ CVR↓ 정렬 (감으로 판단)	순이익 낮은순 정렬 (명확)
광고비 어디로 새나?	광고비 높은순... 근데 매출도 높으면?	광고비 비중↑ + 순이익↓ 조합

핵심 가치 한 줄

"ROAS가 아니라 순이익으로 키워드를 본다"

타겟 사용자: Deep Layer vs Surface Layer

구분	Surface Layer	Deep Layer (키워드 탭)
대상	초보 셀러	숫자 보는 게 익숙한 셀러
원하는 것	"뭐 해야 돼?" (판단)	"데이터 보여줘" (분석)
제공 방식	진단 + 권장 액션	테이블 + 정렬/필터
역할	판단을 대신해줌	데이터 제공, 셀러가 직접 판단

기대 효과

엑셀 export 불필요: 한 화면에서 바로 정렬/분석
순이익 기반 검토: 쿠팡에서 못 보는 "진짜 남는 돈" 확인
Deep Layer 완성도 향상: 4개 탭 중 마지막 미구현 탭 완료

2. WHAT: 상세 요구사항

핵심 기능

#	기능	설명	필수 여부
1	키워드 목록 테이블	캠페인 내 키워드별 성과 지표 표시 (순이익 강조)	필수
2	정렬 기능	순이익/광고비/ROAS 등 정렬	필수
3	페이지네이션	키워드 수가 많을 경우 페이지 분할	필수
4	제외키워드 관리	제외할 키워드 선별 → 클립보드 복사 → 쿠팡 등록 지원	필수

Note: Status Badge (🟢🟡🔴)는 Deep Layer 철학에 맞지 않아 제외. Deep Layer는 판단을 제공하지 않고 데이터만 제공.

비즈니스 로직

로직 1: 키워드별 지표 계산

[표시 지표 - 디자인 화면 기준]

기본 지표:
- 키워드명
- 노출수 (exposureCount)
- 클릭수 (clickCount)
- 광고비 (adCost)
- 광고비 비중 (%) = 해당 키워드 광고비 / 캠페인 총 광고비 × 100
- CPC = 광고비 / 클릭수
- 전환율 (CVR) = 주문수 / 클릭수 × 100
- 주문수 (orders)
- ROAS = 전환매출 / 광고비 × 100
- 광고 순이익 = 전환매출 - 원가 - 광고비×1.1
- 순이익 비중 (%) = 해당 키워드 순이익 / 캠페인 총 순이익 × 100
- 판매수량 (quantity)

로직 2: 데이터 소스

sql

-- CoupangAdKeywordDaily 테이블
SELECT
  keyword,
  SUM(exposureCount) as impressions,
  SUM(clickCount) as clicks,
  SUM(adCost) as spend,
  SUM(orders) as orders,
  SUM(quantity) as quantity,
  SUM(conversionAmount) as revenue
FROM CoupangAdKeywordDaily
WHERE vendorId = ?
  AND campaignId = ?
  AND adDate BETWEEN ? AND ?
GROUP BY keyword
ORDER BY adCost DESC;

로직 3: 정렬 옵션

[정렬 기준]
- 순이익 낮은순 (기본값) - 검토가 필요한 키워드부터
- 광고비 높은순 - 비용 기여 큰 키워드부터
- ROAS 낮은순
- 노출수 높은순
- 클릭수 높은순

로직 4: 컬럼 우선순위

우선순위	컬럼	이유
P0	순이익	핵심 차별화. 양수=파랑, 음수=빨강 색상 강조
P0	광고비	비용 규모 파악
P0	광고비 비중 (%)	전체 대비 비중
P1	ROAS	기존에 익숙한 지표 (참고용)
P1	CPC	입찰가 조정 판단 기준
P1	전환율 (CVR)	키워드 품질 판단
P2	노출수, 클릭수, 주문수, 판매량	상세 분석용

로직 5: 제외키워드 관리

[로컬 탭 구조]
┌──────────────────────────────────┐
│ [전체 키워드] │ [제외 키워드]     │
└──────────────────────────────────┘

[전체 키워드 탭]
- 모든 키워드 표시
- 제외키워드로 등록된 키워드에 "제외" 뱃지 표시
- 멀티셀렉트 → "제외키워드 등록" 버튼

[제외 키워드 탭]
- 제외키워드로 등록된 키워드만 표시
- 멀티셀렉트 → "복사하기" 버튼 → 클립보드에 쉼표(,) join 복사
- 멀티셀렉트 → "삭제" 버튼 → 제외키워드에서 해제

[사용자 플로우: 제외키워드 쿠팡 등록]

1. 장사왕 키워드 탭 진입
2. 순이익 낮은순 정렬
3. 검토 필요한 키워드 분석
4. 제외할 키워드 멀티셀렉트
5. "제외키워드 등록" 클릭
6. 제외키워드 탭 이동
7. 등록할 키워드 멀티셀렉트
8. "복사하기" 클릭 → 클립보드에 "키워드1,키워드2,키워드3" 복사
9. 쿠팡 광고센터 이동 (외부)
10. 해당 캠페인의 제외키워드 등록 화면에서 붙여넣기

Note: 제외키워드 데이터는 장사왕 DB에 저장. 쿠팡 API 연동 아님 (수동 등록 지원).

로직 6: 셀러 의사결정 프레임워크 (참고)

Deep Layer는 판단을 제공하지 않음. 아래는 셀러가 스스로 적용하는 분석 프레임워크.

순이익	광고비 비중	의미	셀러 검토 포인트
➕ 흑자	높음	수익 기여 큼	유지
➕ 흑자	낮음	수익 기여하나 규모 작음	확대 검토
➖ 적자	높음	비용 기여 큼	메인 키워드인가? 아니면 제거?
➖ 적자	낮음	비용 기여 작음	관찰 or 제거

중요: 적자 = 나쁜 것이 아님. 적자 = 검토 필요.

예시: "생수" 키워드가 적자여도 메인 키워드라 빼면 노출 자체가 안 됨 → 유지 판단 가능

사용자 시나리오

시나리오 1: 검토 필요한 키워드 파악

1. 셀러가 캠페인 상세 페이지에서 "키워드" 탭 클릭
2. 기본 정렬 "순이익 낮은순"으로 검토 필요한 키워드가 상단에 표시
3. "봄 신상품" 키워드: 순이익 -5만원, 광고비 15만원
4. 셀러 판단: "이건 메인 키워드니까 유지하고, 입찰가만 조정하자"
5. "여름특가" 키워드: 순이익 -3만원, 광고비 8만원
6. 셀러 판단: "이건 롱테일 키워드인데 적자네. 제외하자"

→ 같은 적자 키워드여도 비즈니스 맥락에 따라 셀러가 다르게 판단

시나리오 2: 확대 기회 키워드 발견

1. 셀러가 정렬을 "순이익 높은순"으로 변경
2. "여름 원피스" 키워드: 순이익 +8만원, 광고비 비중 5%
3. 셀러: "흑자인데 광고비 비중이 낮네? 더 밀어볼까?"
4. 입찰가를 올려서 노출 확대 검토

시나리오 3: 기존 엑셀 워크플로우 대체

Before:
1. 쿠팡 광고센터 → 엑셀 export
2. 원가 데이터 붙이기
3. 순이익 계산 컬럼 추가
4. 정렬해서 분석

After:
1. 장사왕 키워드 탭 진입
2. 순이익 낮은순 정렬 (이미 되어있음)
3. 바로 분석 시작

3. HOW: 플로우 & 화면

페이지 구조

[캠페인 상세 - 키워드 탭]
┌─────────────────────────────────────────────────────────────────┐
│ 🔝 Header (GNB)                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│ ← 캠페인 목록 | 2025 봄 시즌 기획전                               │
│                                                                  │
│ 기간: [2025.03.11 ~ 2025.04.10]                [조회] [↻]       │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [개요] [검색/비검색] [옵션] [키워드✓]                         │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [전체 키워드] [제외 키워드]                    ← 로컬 탭      │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 정렬: [순이익 낮은순 ▼]    [제외키워드 등록]  🔍 키워드 검색 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │☑│키워드  │상태│노출수│클릭│광고비│광고비%│CPC│전환율│주문│...│ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │☑│봄신상  │제외│ 907 │ 80 │15,107│ 24.6%│189│ 4.69%│  4 │...│ │
│ │☐│봄원피스│    │ 887 │ 864│10,844│ 17.6%│ 13│ 4.86%│  5 │...│ │
│ │☑│여름신상│    │ 307 │ 55 │10,197│ 16.6%│185│ 0.05%│  2 │...│ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ [◀ 1 2 3 4 5 ▶]                              10 | 20 | 50 | 100 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

[제외 키워드 탭]
┌─────────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ [전체 키워드] [제외 키워드✓]                                  │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 2개 선택됨              [복사하기] [제외 해제]               │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │☑│키워드    │등록일      │노출수│클릭│광고비│순이익│...      │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │☑│봄신상    │2025.03.20 │ 907 │ 80 │15,107│-4,891│...      │ │
│ │☑│여름특가  │2025.03.22 │ 307 │ 55 │10,197│-5,891│...      │ │
│ │☐│할인세일  │2025.03.25 │ 120 │ 12 │ 2,400│  -891│...      │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ 💡 복사하기 클릭 시 "봄신상,여름특가"가 클립보드에 복사됩니다.   │
│    쿠팡 광고센터 > 캠페인 > 제외키워드 등록에서 붙여넣기 하세요. │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

디자인 요청사항

항목	내용
디자인 화면	`~/Downloads/deep-layer-keyword-tab.png` 참고
톤앤매너	기존 Deep Layer 캠페인 상세 테이블과 동일
컬러	순이익 양수=파랑, 음수=빨강
담당	차봉희 이사님

4. EDGE: 예외 & 엣지 케이스

데이터 예외

상황	처리 방법
키워드 데이터 없음	"등록된 키워드가 없습니다" 표시
기간 내 데이터 0건	"선택한 기간에 키워드 데이터가 없습니다" 안내
원가 미입력	ROAS만 표시, 순이익은 "-" 또는 "원가 입력 필요"
클릭 0 (CPC 계산 불가)	CPC = "-" 표시
광고비 0 (ROAS 계산 불가)	ROAS = "-" 표시

사용자 예외

상황	처리 방법
비검색 광고만 운영 (키워드 없음)	"이 캠페인은 키워드 광고가 없습니다" 안내
모바일 접속	수평 스크롤 또는 핵심 컬럼만 표시

제외키워드 예외

상황	처리 방법
제외키워드 0개	제외 키워드 탭에 "등록된 제외키워드가 없습니다" 안내
이미 제외 등록된 키워드 재등록 시도	무시 (중복 등록 방지)
복사할 키워드 미선택	"복사하기" 버튼 비활성화

시스템 예외

상황	처리 방법
API 타임아웃	"잠시 후 다시 시도해주세요" + 재시도 버튼
키워드 수 1000개+	페이지네이션 필수, 초기 로딩 최적화

5. 성공 지표

이 에픽의 성공 기준

지표	Before	Target	측정 방법
키워드 탭 진입률	0% (미구현)	≥ 30%	GA4 (캠페인 상세 진입 유저 중)
키워드 탭 체류 시간	-	측정 (기준선)	GA4

GA4 이벤트 정의

이벤트명	트리거	파라미터
`view_keyword_tab`	키워드 탭 진입	campaign_id, keyword_count, tab_type (all/excluded)
`sort_keyword_list`	정렬 변경	sort_by, sort_order
`add_excluded_keyword`	제외키워드 등록	campaign_id, keyword_count
`copy_excluded_keyword`	제외키워드 복사	campaign_id, keyword_count
`remove_excluded_keyword`	제외키워드 해제	campaign_id, keyword_count

6. 의존성 & 제약

기술 의존성

의존 항목	상태	비고
CoupangAdKeywordDaily 테이블	✅ 확인됨	키워드별 일별 데이터
키워드 목록 API	⏳ 개발 필요	BE 신규 개발
기존 캠페인 상세 UI	✅ 존재	탭 구조 stub 있음

제약 조건

레포: sellerking-web-monolith (메인 앱)
기존 UI: AdsCampaign 컴포넌트의 Keywords 탭 (현재 미구현)
경로: frontend/src/pages/AdsCampaign/Keywords/

참고 파일

frontend/src/pages/AdsCampaign/
├── index.tsx                    # 탭 구조 정의
├── Keywords/                    # 키워드 탭 (미구현)
│   └── (구현 필요)

7. 스토리 목록

Story ID	제목	규모	우선순위	담당	상태
E-12-S-01	키워드 목록 API 개발	M	P0	BE	ready-for-dev
E-12-S-02	키워드 테이블 UI 구현 (순이익 강조)	M	P0	FE	backlog
E-12-S-03	정렬/페이지네이션 기능	S	P0	FE	backlog
E-12-S-04	GA4 이벤트 트래킹	S	P1	FE	backlog
E-12-S-05	제외키워드 관리 API	S	P0	BE	backlog
E-12-S-06	제외키워드 관리 UI	M	P0	FE	backlog

Story Point 추정

규모	Story	합계
M (2pt)	S-01, S-02, S-06	6
S (1pt)	S-03, S-04, S-05	3
총합		9 SP

8. QA 체크리스트

기능 테스트

키워드 탭 진입

[ ] 캠페인 상세에서 "키워드" 탭 클릭 시 키워드 목록 표시
[ ] 탭 전환 시 데이터 정상 로딩

키워드 목록

[ ] 캠페인 내 모든 키워드 표시
[ ] 컬럼: 키워드, 노출수, 클릭, 광고비, 광고비%, CPC, 전환율, 주문, ROAS, 순이익, 순이익%, 판매량
[ ] 숫자 포맷 정상 (천 단위 콤마, %, 원 등)

정렬 기능

[ ] 순이익 낮은순 (기본값)
[ ] 광고비 높은순/낮은순
[ ] ROAS 낮은순/높은순
[ ] 노출수 높은순/낮은순

페이지네이션

[ ] 10/20/50/100개 선택 가능
[ ] 페이지 이동 정상 동작
[ ] 총 키워드 수 표시

계산 로직 테스트

[ ] CPC = 광고비 / 클릭수
[ ] CVR = 주문수 / 클릭수 × 100
[ ] ROAS = 전환매출 / 광고비 × 100
[ ] 순이익 = 전환매출 - 원가 - 광고비×1.1
[ ] 광고비 비중 = 키워드 광고비 / 캠페인 총 광고비 × 100
[ ] 순이익 비중 = 키워드 순이익 / 캠페인 총 순이익 × 100

제외키워드 기능 테스트

전체 키워드 탭

[ ] 제외키워드 등록된 키워드에 "제외" 뱃지 표시
[ ] 멀티셀렉트 → "제외키워드 등록" 버튼 활성화
[ ] 제외키워드 등록 성공 시 뱃지 표시 업데이트

제외 키워드 탭

[ ] 제외키워드만 표시
[ ] 멀티셀렉트 → "복사하기" 버튼 활성화
[ ] 복사하기 클릭 → 클립보드에 쉼표(,)로 구분된 키워드 복사
[ ] 멀티셀렉트 → "제외 해제" 버튼 활성화
[ ] 제외 해제 성공 시 목록에서 제거 + 전체 키워드 탭 뱃지 해제

엣지 케이스 테스트

[ ] 키워드 0개 → "등록된 키워드가 없습니다"
[ ] 클릭 0 → CPC "-"
[ ] 광고비 0 → ROAS "-"
[ ] 원가 미입력 → 순이익 "-"
[ ] 키워드 100개+ → 페이지네이션 정상 동작
[ ] 제외키워드 0개 → "등록된 제외키워드가 없습니다"
[ ] 이미 제외된 키워드 재등록 시도 → 무시 (중복 방지)

체크리스트

PO 승인 전 체크

[x] 문제 정의가 명확한가?
[x] 비즈니스 로직이 구체적인가?
[x] 와이어프레임/플로우가 있는가?
[x] 엣지 케이스가 정의되었는가?
[x] 성공 지표가 측정 가능한가?
[x] 기술 의존성이 확인되었는가?

승인

항목	확인
PO 승인	✅
승인일	2026-01-28
비고	스프린트 연장으로 추가된 에픽. 순이익 기반 분석이 핵심 차별화.

변경 이력

날짜	변경 내용	담당
2026-01-28	Epic Spec 초안 작성	Oscar
2026-01-28	WHY 섹션 상세화: 순이익 기반 분석 가치 정의, 의사결정 프레임워크 추가, Status Badge 제외 (Deep Layer 철학), 기본 정렬 순이익 낮은순으로 변경	Simon

작성일: 2026-01-28최종 수정: 2026-01-28 (Simon - 가치 정의 상세화)

Epic Spec: E-12 Keyword Analysis (Deep Layer) ​

메타 ​

1. WHY: 왜 이 기능이 필요한가? ​

문제 정의 ​

장사왕만의 해자: 순이익 기반 분석 ​

핵심 가치 한 줄 ​

타겟 사용자: Deep Layer vs Surface Layer ​

기대 효과 ​

2. WHAT: 상세 요구사항 ​

핵심 기능 ​

비즈니스 로직 ​

로직 1: 키워드별 지표 계산 ​

로직 2: 데이터 소스 ​

로직 3: 정렬 옵션 ​

로직 4: 컬럼 우선순위 ​

로직 5: 제외키워드 관리 ​

로직 6: 셀러 의사결정 프레임워크 (참고) ​

사용자 시나리오 ​

3. HOW: 플로우 & 화면 ​

페이지 구조 ​

디자인 요청사항 ​

4. EDGE: 예외 & 엣지 케이스 ​

데이터 예외 ​

사용자 예외 ​

제외키워드 예외 ​

시스템 예외 ​

5. 성공 지표 ​

이 에픽의 성공 기준 ​

GA4 이벤트 정의 ​

6. 의존성 & 제약 ​

기술 의존성 ​

제약 조건 ​

참고 파일 ​

7. 스토리 목록 ​

Story Point 추정 ​

8. QA 체크리스트 ​

기능 테스트 ​

계산 로직 테스트 ​

제외키워드 기능 테스트 ​

엣지 케이스 테스트 ​

체크리스트 ​

PO 승인 전 체크 ​

승인 ​

변경 이력 ​