analyzer.py

# 네이버 원시 키워드 df를 대시보드 Overview용 집계 결과로 변환하는 모듈
import pandas as pd


def build_overview(keyword: str, df: pd.DataFrame) -> dict:
    # 원시 df → 카드/테이블용 집계 dict 반환
    if df.empty:
        return {
            "keyword": keyword,
            "keyword_count": 0,
            "total_search_volume": 0,
            "competition_breakdown": {},
            "top_keywords": [],
            "note": "연관 키워드가 없습니다. 키워드를 확인하세요.",
        }

    df = df.copy()
    df["total_volume"] = df["search_volume_pc"].fillna(0) + df["search_volume_mobile"].fillna(0)

    return {
        "keyword": keyword,
        "keyword_count": int(len(df)),
        # 총 검색량은 합계. 단 느슨하게 연관된 범용 키워드가 섞여 있어,
        # 정밀 집계는 2단계 클러스터링 노이즈 필터링 후로 미룬다.
        "total_search_volume": int(df["total_volume"].sum()),
        "median_volume_per_keyword": int(df["total_volume"].median()),
        "competition_breakdown": df["competition_idx"].value_counts().to_dict(),
        "masked_count": int(df["is_masked"].sum()),
        "top_keywords": (
            df.nlargest(10, "total_volume")[
                ["keyword", "search_volume_pc", "search_volume_mobile",
                 "total_volume", "competition_idx"]
            ].to_dict(orient="records")
        ),
    }