# context-notes — 검색 인텐트 분석기

작업 중 내린 결정과 근거 기록.

## 2026-06-25

- **목표**: MVP 목업을 실제 통합 대시보드로 만들기 위한 데이터 요구사항·스키마 확정. 구현은 이후 단계.
- **결정: CPC 카드 → 경쟁정도 지수로 대체.**
  - 근거: 네이버 키워드도구 API가 CPC를 직접 주지 않음. 입찰가 추정 API는 광고 이력 없으면 품질 낮음.
- **결정: 네이버를 주력 소스로.**
  - 근거: 광고비 0원으로도 검색량(PC/모바일)·경쟁정도 확보 가능. 구글 Ads는 광고비 미지출 시
    검색량이 구간값으로만 나와 정확도 낮음.
- **결정: 인구통계는 상대지수(0~100)로만 표시.**
  - 근거: 네이버 데이터랩은 절대 검색량을 주지 않음. 그룹 내 비율로만 의미 있음.
- **결정: 네이버 단일 소스로 시작.**
  - 근거: 구글 Ads는 광고비 미지출 시 검색량이 구간값으로만 나오고 Developer Token 승인 허들도 있어
    MVP 비용 대비 효율이 낮음. 광고 집행 계획 생기면 그때 합류.
- **결정: 임의 키워드 실시간 분석 서비스로.**
  - 근거: 캠핑용품은 파이프라인 검증용 테스트 입력이었을 뿐. 실제 목표는 사용자가 입력한
    아무 키워드나 실시간 분석하는 대시보드.
- **결정: 동작 방식 = 온디맨드 + 캐싱.**
  - 사용자 입력 시 네이버 실시간 호출 + AI 분석, 같은 키워드 재조회는 캐시에서 즉시.
  - 근거: 검색량은 ~1초 실시간 가능하나 AI 분류/클러스터링은 수 초+비용 → 캐싱으로 상쇄.
- **결정: 구현 형태 = React 웹 서비스 + Python(FastAPI) 백엔드.**
- **1차 캐시는 SQLite로 시작, Supabase는 후속 마이그레이션.** (1단계 막힘 방지)
- **결정: 시드 관련성 필터 임계값 0.35.**
  - 근거: 실측 결과 무관어(계산기 0.221·키보드 0.258·지갑 0.226)와 관련어(야전침대 0.664·캠핑의자 0.855)가
    뚜렷이 갈림. 0.35는 명백한 노이즈를 제거하면서 관련어를 보존. 슬리퍼(0.403)·샌들(0.477)은 경계라 잔존.
  - 효과: 단일 키워드 계산기(1.29M)가 총 검색량의 31%를 차지하던 왜곡 해소.
- **결정: 프론트는 빌드 도구 없는 React 단일 파일(`dashboard.html`).**
  - 근거: 목업이 Tailwind+Chart.js라 디자인 재활용. Node/Vite 없이 파일만 열면 동작 → SMB MVP에 적합.
  - 함정 기록: Babel standalone 기본 JSX runtime이 automatic이라 출력에 `import "react/jsx-runtime"`가
    섞여 CDN 클래식 스크립트에서 렌더가 통째로 실패. → classic runtime 명시(`{runtime:"classic"}`)로 컴파일·실행해 해결.
- **상태: 1~2.5·4단계 완료, 미리보기에서 end-to-end 검증.** 3단계(의도 도넛)는 크레딧 충전 시 활성화.
- **결정: 인구통계는 데이터랩 검색트렌드 + 앵커 정규화 방식.**
  - 근거: 데이터랩은 요청마다 독립 정규화라 세그먼트 간 절대 비교 불가. 공통 앵커("날씨")를 같은 요청에
    함께 넣어 키워드/앵커 비율로 정규화를 상쇄 → 비교 가능한 추정 비중 산출. 쇼핑인사이트(정확하나 카테고리 한정) 대신 선택.
  - 한계: 앵커 자체의 인구 분포 편향이 남는 추정치. '절대 비교 아님' 라벨 명시.
  - 자격: developers.naver.com 검색 API Client ID/Secret 필요 (검색광고 키와 별개).
- **완료: 5단계 양쪽(검색경로·인구통계) 실데이터 검증 완료.**
- **결정: 검색 경로 = 네이버 자동완성 우선 + 임베딩 폴백.**
  - 근거: 자동완성은 실제 동시검색 데이터라 목업 "순차 검색 경로" 취지에 부합. 단 완성형 키워드(강아지사료 등)는
    후보 빈약 → 5노드 미만이면 임베딩 추정망으로 폴백. 소스(autocomplete/embedding)를 프론트 배지로 명시.
  - 한계: 자동완성은 비공식 엔드포인트(ac.search.naver.com) — UA 필요, 차단·변경 위험. 검색량은 검색광고 df와 매칭 시만 표시.
  - 평가: 구글보다 네이버 자동완성이 한국 시장에 적합(구글 Trends/Autocomplete는 비공식·한국 데이터 얕음 → 후순위).
- **참고**: 목업의 "Claude 3.5 Haiku" 라벨 → 최신 Haiku 4.5로 교체 권장.