data-requirements.md

# 검색 인텐트 분석기 — 데이터 요구사항 정리

> MVP 목업(`search_intent_mvp_dashboard.html`)을 실제 통합 대시보드로 만들기 위한
> 데이터 정의 문서. 구현 전 데이터 소스·스키마를 먼저 확정하는 것이 목적이다.

## 1. 화면 컴포넌트 → 필요 데이터 매핑

| # | 화면 블록 | 필요 데이터 (원천 단위) | 1차 소스 | 확보 |
|---|---|---|---|---|
| 1 | 총 검색량 카드 | 키워드별 PC/모바일 월 검색량 | 네이버 검색광고 API | ✅ |
| 2 | 경쟁강도 카드 | 키워드별 경쟁정도 지수 (CPC는 보류) | 네이버 검색광고 API | ✅ |
| 3 | 인텐트 그룹 수 카드 | 클러스터 개수, 분류 키워드 수 | 파생 | ✅ |
| 4 | 의도 비중 도넛 | 키워드별 의도 라벨 | AI 분류(Claude Haiku 4.5) | ✅ |
| 5 | 인구통계 막대 | 시드별 성별×연령 검색 비율(상대지수) | 네이버 데이터랩 | ⚠️ |
| 6 | 클러스터링 테이블 | 클러스터명, 대표 키워드셋, 그룹 검색량, 대표 의도 | 파생(S-BERT+HDBSCAN) | ✅ |
| 7 | 검색 경로 네트워크 | 키워드 간 연결, 연관도, 깊이 | 연관검색어/자동완성 기반 **추정** | ⚠️ |

## 2. 데이터 소스 현실성 점검

### 네이버 검색광고 API — ✅ 광고 집행 불필요
- 검색광고 계정 무료 생성 → 광고비 0원으로 키워드도구 API(`RelKwdStat`) 호출 가능.
- 제공: 연관키워드, **월간 검색수(PC/모바일 분리)**, 경쟁정도(낮음/중간/높음),
  평균 클릭수·클릭률, 평균 노출 광고수.
- ❌ 미제공: **CPC(평균 입찰가)는 키워드도구가 직접 주지 않음.** 별도 입찰가 추정 API 필요 +
  광고 이력 없으면 품질 낮음 → MVP는 **CPC 대신 경쟁정도 지수**를 카드 지표로 사용.

### 구글 Ads API (Keyword Planner) — ⚠️ 반쪽 데이터
- 계정 생성 무료이나 두 가지 벽:
  1. Developer Token 승인 필요 (운영 데이터 호출 시).
  2. **광고비 미지출 시 검색량이 정확 수치가 아니라 구간값(예: "1만~10만")으로만 제공됨.**
     정확한 월 검색수를 받으려면 활성 캠페인 + 광고비 지출이 사실상 전제.
- → 광고비 없으면 검색량을 **구간값 보조 지표**로만 활용.

### 무료 보강 소스
- **네이버 데이터랩**: 연령·성별·기기 트렌드. **절대량 아님, 0~100 상대지수.** 그룹 내 비율로만 표시.
- **구글 트렌드**: 상대지수만.

### 순차 검색 경로(7번) — 핵심 제약
- 개인 단위 클릭스트림(A 검색 후 B 검색)은 네이버·구글 모두 **외부 미제공.** SMB가 살 수 없음.
- 대안: **연관검색어 / 자동완성 / 함께 많이 본 키워드**로 연결망을 추정.
  - "연관도 76%"는 실제 전환율이 아니라 **임베딩 코사인 유사도 또는 동시출현 빈도**로 재정의.
  - depth는 시드 키워드로부터의 그래프 거리로 계산.

## 3. 권장 소스 구성 (SMB 초저비용 MVP)

```
주력  : 네이버 검색광고 API   → 검색량 · 경쟁정도
보조  : 네이버 데이터랩       → 연령/성별/기기 (상대지수)
보조  : 구글 트렌드 / Ads     → 상대지수 · 검색량 구간값
파생  : Claude Haiku 4.5      → 의도 분류
파생  : S-BERT + HDBSCAN      → 의미 클러스터 · 경로 추정
```

## 4. 결측치·이상치 처리 (수집 시점 선처리)

- **검색량 마스킹**: 네이버는 검색량 1,000 미만을 `< 10`으로 마스킹 → `NULL` 대신 하한 대체값 +
  `is_masked` 플래그 보존.
- **CPC 0/결측**: 광고 미집행 키워드 제외 (포함 시 단가 왜곡). MVP는 CPC 자체를 보류.
- **검색량 이상치**: 시즌 폭증 키워드가 평균 왜곡 → 카드 지표는 평균 대신 **중앙값/IQR 클리핑**.
- **클러스터 노이즈**: HDBSCAN `-1`은 `is_noise=true`로 보관하되 집계·화면에서 제외.
- **데이터랩 정규화**: 상대지수라 채널 간 합산 불가 → 성별/연령은 **그룹 내 비율로만** 표시.

## 5. 통합 대시보드 연동

- 모든 테이블에 `seed_keyword`(또는 `seed_id`)를 키로 두고 대시보드는 이 값으로 필터.
- 수집을 배치(주 1회)로 돌리고 `collected_date` 스냅샷을 누적하면 "전월 대비 %" 추세 자동 계산.
- 대용량 적재 시 `chunksize=20,000` 배치 insert.

## 6. 미결정 사항

1. 검색 경로(7번)를 "추정 경로"로 대체할지, 블록 보류할지.
2. 구글 Ads 구간값 데이터를 포함할지, 네이버 단일 소스로 시작할지.