features/research/guide.py

"""분석 가이드 - 토픽 인텔리전스 데이터 흐름 설명.

비기술 사용자를 위한 파이프라인, 점수 계산, 용어, FAQ.
v9.0 신규. (renamed from data_flow.py)
"""

import streamlit as st


def render_data_flow():
    """토픽 인텔리전스 데이터 흐름 가이드."""

    st.markdown("### 토픽 인텔리전스 분석 가이드")
    st.caption("이 페이지는 토픽 인텔리전스의 작동 방식과 주요 지표를 설명합니다.")

    # 1. Pipeline diagram
    st.markdown("#### 1. 데이터 파이프라인")
    st.markdown("""
```
사용자가 AI에 질문
        ↓
AI가 내부적으로 추가 질문(Fanout) 생성
   예: "best moisturizer for dry skin"
        ↓
AI가 추가 질문별로 웹을 검색하고 출처를 인용
        ↓
AI가 종합하여 최종 답변 작성
```

저희는 이 과정에서 생성된 **추가 질문**과 **인용 출처**를 수집하여 분석합니다.

```
수집된 추가 질문들
        ↓
유사한 질문끼리 자동 그룹화 (클러스터링)
   → 각 그룹 = 하나의 "토픽"
        ↓
각 토픽별 점수 계산
   → AI 관심도, 경쟁 밀도, 기회 점수
        ↓
토픽 맵 / 기회 영역 / 분포 시각화
```
""")

    st.markdown("---")

    # 2. Score explanations
    st.markdown("#### 2. 점수 계산 방법")

    score_col1, score_col2, score_col3 = st.columns(3)

    with score_col1:
        st.markdown("""
**AI 관심도 (Attention)**

해당 토픽의 추가 질문 수가 전체에서
차지하는 비중입니다.

`토픽의 추가 질문 수 / 전체 추가 질문 수`

값이 높을수록 AI가 이 주제에 대해
자주 질문한다는 의미입니다.
""")

    with score_col2:
        st.markdown("""
**경쟁 밀도 (Density)**

해당 토픽에서 AI가 인용하는
평균 출처 수입니다.

값이 높을수록 이미 많은 웹사이트가
이 주제에 대한 콘텐츠를 갖고 있어
경쟁이 치열하다는 의미입니다.
""")

    with score_col3:
        st.markdown("""
**기회 점수 (Opportunity)**

AI 관심도와 경쟁 밀도를 결합한
종합 지표입니다.

`AI 관심도 x (1 - 경쟁 밀도)`

**관심은 높지만 경쟁이 낮은** 영역을
찾아줍니다.
""")

    st.markdown("---")

    # 3. Glossary
    st.markdown("#### 3. 용어 사전")

    glossary = {
        "Fanout (추가 질문)": "AI가 답변을 생성하기 위해 내부적으로 만드는 세부 질문. 예: 사용자가 '좋은 선크림 추천해줘'라고 물으면 AI는 'best sunscreen for sensitive skin', 'sunscreen SPF comparison' 등의 추가 질문을 생성합니다.",
        "Cluster (토픽 그룹)": "유사한 추가 질문들을 AI가 자동으로 묶은 것. 하나의 클러스터 = 하나의 토픽.",
        "Citation (인용 출처)": "AI가 답변에서 참조한 웹 페이지. 특정 도메인이 자주 인용되면 해당 주제의 권위 있는 출처로 인식됨.",
        "UMAP (토픽 맵)": "고차원 데이터를 2D로 투영하여 토픽 간 유사도를 시각적으로 보여주는 기법. 가까운 점 = 유사한 토픽.",
        "Quadrant (4분면)": "AI 관심도와 경쟁 밀도를 기준으로 토픽을 4개 영역으로 분류한 것.",
    }

    for term, definition in glossary.items():
        st.markdown(f"**{term}**")
        st.markdown(f"> {definition}")
        st.markdown("")

    st.markdown("---")

    # 4. FAQ
    st.markdown("#### 4. 자주 묻는 질문")

    with st.expander("왜 Top 10만 상세 분석하나요?"):
        st.markdown(
            "기회 점수 상위 10개 토픽이 실질적으로 콘텐츠 제작 우선순위가 가장 높은 영역입니다. "
            "전체 랭킹 테이블에서는 50위까지 확인할 수 있습니다."
        )

    with st.expander("인용 출처 그래프가 없는 토픽은 무엇인가요?"):
        st.markdown(
            "AI가 해당 토픽에서 아직 특정 웹사이트를 인용하지 않고 있다는 의미입니다. "
            "이는 경쟁자가 거의 없다는 뜻이므로, **콘텐츠 선점 기회가 더욱 큰** 영역입니다."
        )

    with st.expander("점수가 매우 낮은 토픽은 무시해도 되나요?"):
        st.markdown(
            "점수는 전체 토픽 대비 상대적 비중입니다. "
            "예를 들어 481개 토픽 중 하나의 Attention이 0.001이면 전체의 0.1%를 차지하는 것입니다. "
            "절대적으로 낮아 보여도 해당 니치에서는 충분히 의미 있을 수 있습니다."
        )

    with st.expander("토픽 맵에서 점들이 뭉쳐 있으면 무엇을 의미하나요?"):
        st.markdown(
            "서로 가까이 있는 점(토픽)들은 의미적으로 유사한 주제입니다. "
            "뭉쳐 있는 토픽 그룹은 하나의 큰 주제 영역을 나타내며, "
            "이 영역 전체에 대한 종합적인 콘텐츠 전략을 수립하면 효과적입니다."
        )

    with st.expander("데이터는 얼마나 자주 업데이트되나요?"):
        st.markdown(
            "캠페인별로 클러스터링을 실행할 때 데이터가 갱신됩니다. "
            "현재는 수동 실행 방식이며, 추후 자동 갱신이 추가될 예정입니다."
        )