checklist.md

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

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

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

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

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

## 4단계 — React 프론트 연동 (완료)
- [x] 목업 HTML → React 단일 파일 앱(`dashboard.html`, 빌드 도구 없음)
- [x] `/analyze` 연동, 분석 실행 버튼 실동작 (미리보기에서 검증: 카드 3개·클러스터 18행)
- [x] 로딩/에러/캐시 상태 처리, 도넛·인구통계 미충족 시 안내 자리 표시
- 비고: 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단계 — 보조
- [x] 검색 경로: **네이버 자동완성(실제 동시검색) 우선 + 임베딩 추정 폴백** (`autocomplete.py` + `search_path.py`)
      검증: 캠핑용품→자동완성 14노드("네이버 자동완성" 배지), 강아지사료→임베딩 폴백 13노드("임베딩 추정" 배지).
      자동완성은 비공식 엔드포인트(빈약/차단 가능) → 5노드 미만이면 임베딩으로 graceful 대체.
- [x] 인구통계: 데이터랩 검색트렌드 + 앵커("날씨") 정규화로 성별×연령 추정 비중 (`datalab.py` + 프론트 막대)
      **실데이터 검증 완료** — 강아지사료: 여성>남성·고연령>저연령 분포로 의미 있게 출력, 프론트 막대 렌더 확인.
- [x] **Supabase 마이그레이션** — BI 플랫 테이블 3개(analysis_run/cluster/demographic)에 적재
      (`supabase_schema.sql` + `supabase_store.py`). SQLite는 빠른 캐시 유지, Supabase는 통합 분석 저장소.
      검증 완료: 캠핑용품 분석 → run 1행·cluster 19행·demographic 8행 적재 확인. Tableau/Looker 조회 가능.