checklist.md

checklist — 검색 인텐트 분석 대시보드

목표: 사용자가 키워드를 입력하면 실시간으로 검색 인텐트를 분석하는 React 웹 서비스. 방식: 온디맨드 + 캐싱. 백엔드 Python(FastAPI), 프론트 React.

1단계 — 백엔드 골격 + 네이버 실시간 (완료)

• naver_collector.py → fetch_keywords() 재사용 (시드 하드코딩 제거)
• analyzer.py — 원시 df → Overview 집계 (총검색량·경쟁분포·중앙값·상위 키워드)
• cache.py — SQLite 캐시 (키워드+날짜 단위, 재조회 즉시 반환)
• api.py — FastAPI GET /analyze?keyword= 엔드포인트
• 로컬 실행 + 임의 키워드 검증 (골프 0.36s, 강아지사료 0.22s, 캐시 재조회 0.00s)

2단계 — 의미 클러스터링 (완료)

• sentence-transformers + umap-learn + hdbscan 설치
• S-BERT → UMAP(5D) → HDBSCAN(leaf) 파이프라인 (clusterer.py)
• 노이즈(-1) 필터링, 그룹별 검색량 집계, /analyze에 연결
• 검증: 캠핑용품 37개 클러스터(의자/지갑/캠핑테이블/야전침대/난로류 등 의미 군집화 확인)
• 2.5 시드 관련성 필터 (filter_by_relevance, 임계값 0.35) — 계산기 등 197개 제거, 총 검색량 4.13M→2.34M, 단일 노이즈 지배 해소. (슬리퍼·샌들 등 경계어는 잔존 — 후속 정제 여지)

3단계 — 의도 분류 묶음 (Claude Haiku 4.5) — 완료

• 클러스터 단위 의도 분류(정보/거래/내비/혼합) — 1회 호출로 묶음
• 도넛 비중 + 의도 배지
• 테마형 그룹명 생성("캠핑 텐트"·"야전침대 및 침낭" 등)
• SMB 마케팅 액션 제안 생성 (차박 번들 전략 등 실데이터 인사이트)
• 검증: 캠핑용품 — 도넛·테마·제안 모두 출력, 비용 키워드당 11.7원
• 클러스터 단위 관련성 필터(평균 0.45 컷) — 백팩·샌들·가디건 등 패션 군집 제거. 효과: 클러스터 27→19, 거래형 비중 1,021,575→464,120, 상위 테마 전부 캠핑 용품으로 정화. (가방류 0.518는 캠핑 인접어라 잔존 — 임베딩상 완전 분리는 불가, 허용)

4단계 — React 프론트 연동 (완료)

• 목업 HTML → React 단일 파일 앱(dashboard.html, 빌드 도구 없음)
• /analyze 연동, 분석 실행 버튼 실동작 (미리보기에서 검증: 카드 3개·클러스터 18행)
• 로딩/에러/캐시 상태 처리, 도넛·인구통계 미충족 시 안내 자리 표시
• 비고: Babel standalone 기본이 automatic JSX runtime이라 import 구문이 끼어 렌더가 죽음 → classic runtime을 명시 지정해 컴파일·실행하는 방식으로 해결

실행 방법

1. 백엔드: cd keyword && python -m uvicorn api:app --port 8000
2. 프론트: cd keyword && python -m http.server 5500 → 브라우저에서 http://127.0.0.1:5500/dashboard.html

5단계 — 보조

• 검색 경로: 네이버 자동완성(실제 동시검색) 우선 + 임베딩 추정 폴백 (autocomplete.py + search_path.py) 검증: 캠핑용품→자동완성 14노드("네이버 자동완성" 배지), 강아지사료→임베딩 폴백 13노드("임베딩 추정" 배지). 자동완성은 비공식 엔드포인트(빈약/차단 가능) → 5노드 미만이면 임베딩으로 graceful 대체.
• 인구통계: 데이터랩 검색트렌드 + 앵커("날씨") 정규화로 성별×연령 추정 비중 (datalab.py + 프론트 막대) 실데이터 검증 완료 — 강아지사료: 여성>남성·고연령>저연령 분포로 의미 있게 출력, 프론트 막대 렌더 확인.
• Supabase 마이그레이션 — BI 플랫 테이블 3개(analysis_run/cluster/demographic)에 적재 (supabase_schema.sql + supabase_store.py). SQLite는 빠른 캐시 유지, Supabase는 통합 분석 저장소. 검증 완료: 캠핑용품 분석 → run 1행·cluster 19행·demographic 8행 적재 확인. Tableau/Looker 조회 가능.