Sync from GitHub

.streamlit/config.toml

@@ -0,0 +1,14 @@
+[theme]
+primaryColor = "#3B82F6"
+backgroundColor = "#FFFFFF"
+secondaryBackgroundColor = "#F8FAFC"
+textColor = "#1E293B"
+font = "sans serif"
+
+[server]
+headless = true
+enableCORS = false
+enableXsrfProtection = true
+
+[client]
+showSidebarNavigation = false

.streamlit/secrets.toml.example

@@ -0,0 +1,7 @@
+# Streamlit Cloud Secrets Template
+# Copy this to Streamlit Cloud Dashboard > App Settings > Secrets
+
+# Optional: Default API settings
+[api]
+base_url = "https://chainshift-service-api.vercel.app"
+# api_key = "sk_live_xxx"  # Optional: pre-fill API key

Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+EXPOSE 7860
+ENV STREAMLIT_SERVER_PORT=7860
+ENV STREAMLIT_SERVER_ADDRESS=0.0.0.0
+CMD ["streamlit", "run", "app.py"]

README.md

@@ -0,0 +1,8 @@
+---
+title: ChainShift Sentiment Dashboard
+emoji: 📊
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+---

app.py

@@ -0,0 +1,77 @@
+"""ChainShift Brand Risk Monitoring Dashboard v10.0.
+
+Feature Plugin Architecture: 새 기능 = features/ 디렉토리 생성 → 자동 등록.
+"""
+
+import streamlit as st
+
+from core.styles import DASHBOARD_CSS
+from sidebar import render_sidebar
+from registry import discover_features
+
+
+# =============================================================================
+# Page Config
+# =============================================================================
+
+st.set_page_config(
+    page_title="ChainShift Dashboard",
+    page_icon="⚡",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+st.markdown(DASHBOARD_CSS, unsafe_allow_html=True)
+
+st.title("ChainShift")
+st.caption("AI 검색 플랫폼에서 브랜드가 어떻게 언급되고 인용되는지 분석합니다")
+
+
+# =============================================================================
+# Sidebar (인증 + 캠페인 선택)
+# =============================================================================
+
+sidebar_result = render_sidebar()
+if not sidebar_result:
+    st.stop()
+
+auth_info, selected_campaign_id, selected_campaign_display = sidebar_result
+
+
+# =============================================================================
+# Feature Discovery + Rendering
+# =============================================================================
+
+features = discover_features()
+
+if not features:
+    st.error("등록된 Feature가 없습니다. features/ 디렉토리를 확인하세요.")
+    st.stop()
+
+# Base context shared by all features
+base_ctx = {
+    "api_key": auth_info.get("api_key"),
+    "access_token": auth_info.get("access_token"),
+    "campaign_id": selected_campaign_id,
+    "campaign_name": selected_campaign_display,
+    "user_email": auth_info.get("email"),
+}
+
+# Create tabs from discovered features
+tab_labels = [f"{f['config']['icon']} {f['config']['name']}" for f in features]
+tabs = st.tabs(tab_labels)
+
+for tab, feature in zip(tabs, features):
+    with tab:
+        try:
+            feature["module"].render(base_ctx)
+        except Exception as e:
+            st.error(f"{feature['config']['name']} 로딩 실패: {e}")
+
+
+# =============================================================================
+# Footer
+# =============================================================================
+
+st.markdown("---")
+st.caption("ChainShift v10.0")

components/__init__.py

@@ -0,0 +1,31 @@
+"""Dashboard UI components."""
+
+from .cards import (
+    render_nudge_card,
+    render_brand_card,
+    render_verification_item,
+    render_polarity_item,
+)
+from .expanders import (
+    render_nudge_expander,
+    render_feedback_section,
+    render_llm_verification_section,
+)
+from .metrics import (
+    render_kpi_row,
+    render_verification_stats,
+    render_polarity_stats,
+)
+
+__all__ = [
+    "render_nudge_card",
+    "render_brand_card",
+    "render_verification_item",
+    "render_polarity_item",
+    "render_nudge_expander",
+    "render_feedback_section",
+    "render_llm_verification_section",
+    "render_kpi_row",
+    "render_verification_stats",
+    "render_polarity_stats",
+]

components/cards.py

@@ -0,0 +1,188 @@
+"""Dashboard card components."""
+
+import html
+import streamlit as st
+
+from core.charts import CONFIDENCE_TIER_COLORS
+from core.styles import TIER_BORDER_COLORS
+from core.utils import get_confidence_tier, truncate_text, format_brands_list
+
+
+def render_nudge_card(
+    item: dict,
+    tier: str,
+    emoji: str,
+    tier_desc: str,
+    confidence: float,
+) -> None:
+    """Render nudge candidate card with summary info.
+
+    Args:
+        item: Nudge candidate data dict
+        tier: Confidence tier (HIGH/MEDIUM/LOW)
+        emoji: Tier emoji
+        tier_desc: Tier description
+        confidence: Confidence score (0-1)
+    """
+    cej_stage = item.get("cej_depth2") or item.get("cej_depth1") or "N/A"
+    platform = item.get("platform", "N/A")
+
+    in_house = item.get("in_house_brands", [])
+    mentioned = item.get("mentioned_brands", [])
+
+    question = item.get("question_content", "")
+    answer = item.get("answer_preview", "")
+
+    tier_color = CONFIDENCE_TIER_COLORS.get(tier, "#6B7280")
+    border_color = TIER_BORDER_COLORS.get(tier, "#6B7280")
+
+    question_display = html.escape(truncate_text(question, 200))
+    answer_short = html.escape(truncate_text(answer, 150))
+    in_house_display = html.escape(format_brands_list(in_house))
+    mentioned_display = html.escape(format_brands_list(mentioned))
+
+    header_html = f"""
+    <div style="border: 2px solid {border_color}; border-radius: 12px; padding: 16px; margin: 12px 0; background: #FAFAFA;">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px;">
+            <span style="background: #E0E7FF; padding: 4px 12px; border-radius: 20px; font-size: 13px;">
+                📍 CEJ: <strong>{cej_stage}</strong>
+            </span>
+            <span style="background: {tier_color}; color: white; padding: 4px 12px; border-radius: 20px; font-size: 13px;" title="{tier_desc}">
+                {emoji} 답변 전체: {tier} ({confidence:.0%})
+            </span>
+        </div>
+        <div style="background: #F0F9FF; border-left: 4px solid #3B82F6; padding: 10px; margin-bottom: 10px; border-radius: 0 8px 8px 0;">
+            <div style="font-size: 11px; color: #3B82F6; margin-bottom: 2px;">💬 질문</div>
+            <div style="font-size: 14px;">{question_display}</div>
+        </div>
+        <div style="font-size: 13px; color: #6B7280; margin-bottom: 8px;">{answer_short}...</div>
+        <div style="display: flex; gap: 12px; flex-wrap: wrap; font-size: 12px; color: #6B7280;">
+            <span>🏷️ <strong>{in_house_display}</strong></span>
+            <span>📢 {mentioned_display}</span>
+            <span>🖥️ {platform}</span>
+        </div>
+    </div>
+    """
+    st.markdown(header_html, unsafe_allow_html=True)
+
+
+def render_brand_card(
+    brand_name: str,
+    brand_type: str,
+    sentiment_data: dict,
+) -> None:
+    """Render brand mention card.
+
+    Args:
+        brand_name: Brand name
+        brand_type: 'in_house' or 'competitor'
+        sentiment_data: Dict with sentiment, confidence, count
+    """
+    sentiment = sentiment_data.get("sentiment", "neutral")
+    confidence = sentiment_data.get("confidence", 0)
+    mention_count = sentiment_data.get("count", 0)
+
+    type_badge = "🏠 자사" if brand_type == "in_house" else "🏢 경쟁사"
+    type_bg = "#DBEAFE" if brand_type == "in_house" else "#FEE2E2"
+
+    sentiment_colors = {
+        "positive": "#10B981",
+        "negative": "#EF4444",
+        "neutral": "#6B7280",
+    }
+    sent_color = sentiment_colors.get(sentiment, "#6B7280")
+    sentiment_ko = {"positive": "긍정", "negative": "부정", "neutral": "중립"}.get(sentiment, sentiment)
+
+    card_html = f"""
+    <div style="border: 1px solid #E5E7EB; border-radius: 8px; padding: 12px; margin: 8px 0; background: white;">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px;">
+            <span style="font-weight: 600; font-size: 15px;">{html.escape(brand_name)}</span>
+            <span style="background: {type_bg}; padding: 2px 8px; border-radius: 12px; font-size: 11px;">{type_badge}</span>
+        </div>
+        <div style="display: flex; gap: 12px; font-size: 12px;">
+            <span style="background: {sent_color}; color: white; padding: 2px 8px; border-radius: 4px;">{sentiment_ko}</span>
+            <span>신뢰도: {confidence:.0%}</span>
+            <span>언급: {mention_count}회</span>
+        </div>
+    </div>
+    """
+    st.markdown(card_html, unsafe_allow_html=True)
+
+
+def render_verification_item(item: dict, is_false_positive: bool = True) -> None:
+    """Render LLM verification item info (used inside expander).
+
+    Args:
+        item: Verification result dict
+        is_false_positive: True for FP, False for TN
+    """
+    st.markdown(f"**질문**: {item.get('question_content', 'N/A')}")
+    st.markdown(f"**답변 미리보기**: {item.get('answer_preview', 'N/A')}")
+    st.markdown("---")
+
+    info_col1, info_col2, info_col3 = st.columns(3)
+    with info_col1:
+        st.markdown(f"**플랫폼**: {item.get('platform', 'N/A')}")
+        st.markdown(f"**CEJ**: {item.get('cej_depth1', 'N/A')} / {item.get('cej_depth2', 'N/A')}")
+    with info_col2:
+        st.markdown(f"**1차 판정**: {item.get('routing_tier', 'N/A')}")
+        st.markdown(f"**1차 감성**: {item.get('overall_polarity', 'N/A')}")
+    with info_col3:
+        llm_conf = item.get('llm_confidence', 0) or 0
+        st.markdown(f"**LLM 신뢰도**: {llm_conf:.1%}")
+        st.markdown(f"**LLM 조정 Tier**: {item.get('llm_adjusted_tier', 'N/A')}")
+
+    # LLM reasoning
+    if item.get('llm_reasoning'):
+        st.markdown("**LLM 판단 근거**:")
+        if is_false_positive:
+            st.info(item.get('llm_reasoning'))
+        else:
+            st.warning(item.get('llm_reasoning'))
+
+    # Evidence spans
+    if item.get('llm_evidence_spans'):
+        label = "**근거 문장**:" if is_false_positive else "**부정 근거 문장**:"
+        st.markdown(label)
+        for span in (item.get('llm_evidence_spans') or []):
+            st.markdown(f"- _{span}_")
+
+    # Brands
+    in_house = item.get('in_house_brands', []) or []
+    mentioned = item.get('mentioned_brands', []) or []
+    if in_house or mentioned:
+        st.markdown(f"**자사 브랜드**: {', '.join(in_house) if in_house else 'N/A'}")
+        st.markdown(f"**언급 브랜드**: {', '.join(mentioned) if mentioned else 'N/A'}")
+
+
+def render_polarity_item(item: dict) -> None:
+    """Render polarity (sentiment) item info (used inside expander).
+
+    Args:
+        item: Sentiment summary dict
+    """
+    confidence = item.get('overall_confidence', 0) or 0
+
+    st.markdown(f"**질문**: {item.get('question_content', 'N/A')}")
+    st.markdown(f"**답변 미리보기**: {item.get('answer_preview', 'N/A')}")
+    st.markdown("---")
+
+    info_col1, info_col2, info_col3 = st.columns(3)
+    with info_col1:
+        st.markdown(f"**감성**: {item.get('overall_polarity', 'N/A')}")
+        st.markdown(f"**신뢰도**: {confidence:.1%}")
+    with info_col2:
+        st.markdown(f"**플랫폼**: {item.get('platform', 'N/A')}")
+        st.markdown(f"**CEJ**: {item.get('cej_depth1', 'N/A')} / {item.get('cej_depth2', 'N/A')}")
+    with info_col3:
+        tier = item.get('routing_tier', 'N/A')
+        st.markdown(f"**라우팅 Tier**: {tier}")
+        emotion = item.get('dominant_emotion', 'N/A')
+        st.markdown(f"**감정**: {emotion}")
+
+    # Brands
+    in_house = item.get('in_house_brands', []) or []
+    mentioned = item.get('mentioned_brands', []) or []
+    if in_house or mentioned:
+        st.markdown(f"**자사 브랜드**: {', '.join(in_house) if in_house else 'N/A'}")
+        st.markdown(f"**언급 브랜드**: {', '.join(mentioned) if mentioned else 'N/A'}")

components/expanders.py

@@ -0,0 +1,244 @@
+"""Dashboard expander and section components."""
+
+import html
+import streamlit as st
+
+from core.charts import EMOTION_KO
+from core.utils import get_confidence_tier, truncate_text
+
+
+# Content type labels for citations
+CONTENT_TYPE_LABELS = {
+    "EDITORIAL": "📰 에디토리얼",
+    "TUTORIAL_REVIEW": "📝 리뷰/튜토리얼",
+    "COMPARISON": "⚖️ 비교 분석",
+    "RANKED_LIST": "📊 순위 목록",
+    "FORUM_THREAD": "💬 포럼/커뮤니티",
+    "HOMEPAGE": "🏠 홈페이지",
+    "CATALOG": "📦 카탈로그",
+    "DOCUMENTATION": "📚 문서",
+    "FAQ": "❓ FAQ",
+    "WHITEPAPER": "📄 백서",
+    "PRESS_RELEASE": "📢 보도자료",
+    "CASE_STUDY": "💼 사례연구",
+    "PRICING": "💰 가격정보",
+    "DETAIL": "🔍 상세페이지",
+    "DIRECTORY_ENTRY": "📋 디렉토리",
+    "SUBSTITUTE": "🔄 대체제",
+    "OTHERS": "📎 기타",
+}
+
+
+def render_citation(cit: dict) -> None:
+    """Render a single citation item.
+
+    Args:
+        cit: Citation dict with source_url, content_type, page_title
+    """
+    url = cit.get("source_url", "")
+    ctype = cit.get("content_type") or "OTHERS"
+    title = cit.get("page_title") or ""
+    type_label = CONTENT_TYPE_LABELS.get(ctype, f"📎 {ctype}")
+    display_url = url[:50] + "..." if len(url) > 50 else url
+    display_title = f' "{title[:30]}..."' if title and len(title) > 30 else f' "{title}"' if title else ""
+    st.markdown(
+        f'<span style="background: #E0E7FF; color: #3730A3; padding: 2px 6px; '
+        f'border-radius: 4px; font-size: 11px; margin-right: 4px;">{type_label}</span> '
+        f'<a href="{url}" target="_blank">{display_url}</a>{display_title}',
+        unsafe_allow_html=True
+    )
+
+
+def render_nudge_expander(
+    item: dict,
+    answer_id: int | None,
+    index: int,
+    fetch_full_answer_fn,
+    fetch_citations_fn,
+) -> None:
+    """Render nudge candidate expander with full details.
+
+    Args:
+        item: Nudge candidate data dict
+        answer_id: Answer ID for Athena fetch
+        index: Item index for display
+        fetch_full_answer_fn: Function to fetch full answer from Athena
+        fetch_citations_fn: Function to fetch citations (Supabase fallback)
+    """
+    confidence = item.get("overall_confidence", 0) or 0
+    tier, _, _ = get_confidence_tier(confidence)
+    emotion = item.get("dominant_emotion", "N/A")
+    emotion_ko = EMOTION_KO.get(emotion, emotion) if emotion else "N/A"
+    answer = item.get("answer_preview", "")
+    brand_detail = item.get("brand_sentiment_detail", {})
+
+    with st.expander(f"📖 상세 보기 (답변 #{answer_id or index+1})"):
+        # Analysis explanation box
+        st.markdown(f"""
+<div style="background: #FFF7ED; border-left: 4px solid #F59E0B; padding: 12px; margin-bottom: 12px; border-radius: 0 8px 8px 0; font-size: 13px;">
+<strong>📊 분석 결과 해석</strong><br><br>
+<strong>📄 답변 전체 부정 확신도: {confidence:.0%} ({tier})</strong><br>
+답변 전체가 부정적인 톤인지 판단한 점수입니다. (여러 브랜드가 언급되면 혼합됨)<br><br>
+<strong>🔍 브랜드별 부정 확신도</strong> (아래 ABSA 참조)<br>
+특정 브랜드에 대한 언급만 추출하여 그 언급이 부정적인지 판단한 점수입니다.<br>
+<em style="color: #9CA3AF;">예: 답변 전체는 64%(LOW)여도, 특정 브랜드 언급은 91%(HIGH)일 수 있음</em><br><br>
+<strong>답변 톤: {emotion_ko}</strong><br>
+답변 전체의 감정적 분위기입니다.
+</div>
+""", unsafe_allow_html=True)
+
+        # Full answer from Athena
+        st.markdown("**🤖 AI 답변 전문**")
+
+        if answer_id:
+            full_answer_key = f"full_answer_{answer_id}"
+            load_full_key = f"load_full_{answer_id}"
+            if full_answer_key not in st.session_state:
+                st.session_state[full_answer_key] = None
+
+            load_full = st.checkbox(
+                "📥 전체 답변 불러오기",
+                key=load_full_key,
+                value=st.session_state.get(full_answer_key) is not None
+            )
+
+            if load_full and st.session_state.get(full_answer_key) is None:
+                with st.spinner("전체 답변을 가져오는 중..."):
+                    full_content = fetch_full_answer_fn(answer_id)
+                    if isinstance(full_content, str) and len(full_content) > 0:
+                        st.session_state[full_answer_key] = full_content
+                        st.rerun()
+                    else:
+                        # Store empty string to prevent infinite re-fetch loop
+                        st.session_state[full_answer_key] = ""
+
+            cached = st.session_state.get(full_answer_key)
+            display_answer = cached if (isinstance(cached, str) and len(cached) > 0) else answer or "N/A"
+            is_full = isinstance(cached, str) and len(cached) > 0
+            label = "✅ 전체 답변 로드됨" if is_full else f"📄 미리보기 ({len(answer or '')}자)"
+            st.caption(label)
+        else:
+            display_answer = answer or "N/A"
+
+        st.markdown(
+            f'<div style="background: #FEF2F2; padding: 12px; border-radius: 8px; '
+            f'font-size: 14px; white-space: pre-wrap; word-break: break-word; '
+            f'max-height: 400px; overflow-y: auto;">{html.escape(display_answer)}</div>',
+            unsafe_allow_html=True
+        )
+
+        # Brand sentiment detail
+        if brand_detail and isinstance(brand_detail, dict):
+            st.markdown("**🔍 브랜드별 감성 분석 (ABSA) - 브랜드별 부정 확신도**")
+            _render_brand_absa(brand_detail)
+
+        # Citations
+        st.markdown("**🔗 인용 출처 (Citation Sources)**")
+        _render_citations_section(answer_id, item.get("citation_urls", []), fetch_citations_fn)
+
+
+def _render_brand_absa(brand_detail: dict) -> None:
+    """Render brand ABSA results."""
+    in_house_data = brand_detail.get("in_house", {})
+    in_house_absa = in_house_data.get("absa_results", [])
+    for absa in in_house_absa:
+        if isinstance(absa, dict):
+            brand_name = absa.get("brand", "Unknown")
+            sentiment = absa.get("sentiment", "N/A")
+            conf = absa.get("confidence", 0)
+            absa_tier, absa_emoji, _ = get_confidence_tier(conf)
+            sent_color = "#10B981" if sentiment == "positive" else "#EF4444" if sentiment == "negative" else "#6B7280"
+            st.markdown(
+                f'<span style="background: {sent_color}; color: white; padding: 2px 8px; '
+                f'border-radius: 4px; font-size: 12px; margin-right: 8px;">{sentiment}</span> '
+                f'<strong>{brand_name}</strong> (🏠 자사) - {absa_emoji} 브랜드 확신도 {conf:.0%} ({absa_tier})',
+                unsafe_allow_html=True
+            )
+
+    competitor_data = brand_detail.get("competitor", {})
+    competitor_brands = competitor_data.get("brands", [])
+    competitor_absa = competitor_data.get("absa_results", [])
+
+    if competitor_absa:
+        for absa in competitor_absa:
+            if isinstance(absa, dict):
+                brand_name = absa.get("brand", "Unknown")
+                sentiment = absa.get("sentiment", "N/A")
+                conf = absa.get("confidence", 0)
+                absa_tier, absa_emoji, _ = get_confidence_tier(conf)
+                sent_color = "#10B981" if sentiment == "positive" else "#EF4444" if sentiment == "negative" else "#6B7280"
+                st.markdown(
+                    f'<span style="background: {sent_color}; color: white; padding: 2px 8px; '
+                    f'border-radius: 4px; font-size: 12px; margin-right: 8px;">{sentiment}</span> '
+                    f'<strong>{brand_name}</strong> (🏢 경쟁사) - {absa_emoji} 브랜드 확신도 {conf:.0%} ({absa_tier})',
+                    unsafe_allow_html=True
+                )
+    elif competitor_brands:
+        st.markdown(
+            f'<span style="background: #6B7280; color: white; padding: 2px 8px; '
+            f'border-radius: 4px; font-size: 12px;">언급됨</span> '
+            f'<strong>{", ".join(competitor_brands)}</strong> (🏢 경쟁사)',
+            unsafe_allow_html=True
+        )
+
+
+def _render_citations_section(answer_id: int | None, citation_urls: list, fetch_citations_fn) -> None:
+    """Render citations section."""
+    citations_key = f"citations_{answer_id}"
+    if citations_key not in st.session_state:
+        st.session_state[citations_key] = None
+
+    if st.session_state.get(citations_key) is None and answer_id:
+        citations = fetch_citations_fn(answer_id)
+        st.session_state[citations_key] = citations if citations else []
+
+    citations = st.session_state.get(citations_key, [])
+    if citations:
+        if len(citations) <= 5:
+            for cit in citations:
+                render_citation(cit)
+        else:
+            for cit in citations[:5]:
+                render_citation(cit)
+            with st.expander(f"📂 나머지 {len(citations) - 5}개 더 보기"):
+                for cit in citations[5:]:
+                    render_citation(cit)
+    elif citation_urls:
+        if len(citation_urls) <= 5:
+            for url in citation_urls:
+                st.markdown(f"• [{url[:60]}...]({url})" if len(url) > 60 else f"• [{url}]({url})")
+        else:
+            for url in citation_urls[:5]:
+                st.markdown(f"• [{url[:60]}...]({url})" if len(url) > 60 else f"• [{url}]({url})")
+            with st.expander(f"📂 나머지 {len(citation_urls) - 5}개 더 보기"):
+                for url in citation_urls[5:]:
+                    st.markdown(f"• [{url[:60]}...]({url})" if len(url) > 60 else f"• [{url}]({url})")
+    else:
+        st.caption("인용 소스 없음")
+
+
+def render_feedback_section(feedback_stats: dict) -> None:
+    """Render feedback statistics expander section.
+
+    Args:
+        feedback_stats: Dict with feedback counts and accuracy
+    """
+    from .metrics import render_feedback_stats
+
+    fb_total = feedback_stats.get("total_feedback", 0)
+    if fb_total > 0:
+        with st.expander("📝 **피드백 분석** - 사용자 검증 현황", expanded=False):
+            render_feedback_stats(feedback_stats)
+
+
+def render_llm_verification_section(item: dict, is_false_positive: bool = True) -> None:
+    """Render LLM verification item section (used inside expander).
+
+    This is a wrapper that calls render_verification_item from cards module.
+
+    Args:
+        item: Verification result dict
+        is_false_positive: True for FP, False for TN
+    """
+    from .cards import render_verification_item
+    render_verification_item(item, is_false_positive)

components/metrics.py

@@ -0,0 +1,175 @@
+"""Dashboard metrics and KPI components."""
+
+import streamlit as st
+
+
+def render_kpi_row(
+    total_nudge: int,
+    high_count: int,
+    medium_count: int,
+    risk_score: float,
+    citation_total: int,
+) -> None:
+    """Render key metrics row with 5 KPIs.
+
+    Args:
+        total_nudge: Total negative mentions
+        high_count: HIGH tier count
+        medium_count: MEDIUM tier count
+        risk_score: Calculated risk score
+        citation_total: Total citation sources
+    """
+    kpi1, kpi2, kpi3, kpi4, kpi5 = st.columns(5)
+
+    with kpi1:
+        st.metric(
+            label="총 부정 언급",
+            value=f"{total_nudge}건",
+            help="AI가 자사 브랜드를 부정적으로 언급한 답변 수",
+        )
+
+    with kpi2:
+        st.metric(
+            label="🔴 HIGH (즉시 대응)",
+            value=f"{high_count}건",
+            help="≥85% 확신도 - 즉시 대응 권장",
+        )
+
+    with kpi3:
+        st.metric(
+            label="🟡 MEDIUM (검토)",
+            value=f"{medium_count}건",
+            help="70-85% 확신도 - 검토 필요",
+        )
+
+    with kpi4:
+        st.metric(
+            label="리스크 점수",
+            value=f"{risk_score:.1f}",
+            help="HIGH=100%, MEDIUM=50%, LOW=20% 가중 평균",
+        )
+
+    with kpi5:
+        st.metric(
+            label="총 인용 소스",
+            value=f"{citation_total}개",
+            help="AI 답변에서 인용된 총 소스 수",
+        )
+
+
+def render_verification_stats(
+    total_verified: int,
+    false_positives_count: int,
+    true_negatives_count: int,
+) -> None:
+    """Render LLM verification statistics row.
+
+    Args:
+        total_verified: Total verified items
+        false_positives_count: False positive count
+        true_negatives_count: True negative count
+    """
+    stat_col1, stat_col2, stat_col3, stat_col4 = st.columns(4)
+
+    with stat_col1:
+        st.metric("검증 완료", f"{total_verified}건")
+
+    with stat_col2:
+        fp_rate = (false_positives_count / total_verified * 100) if total_verified > 0 else 0
+        st.metric("오탐 (False Positive)", f"{false_positives_count}건", f"{fp_rate:.1f}%")
+
+    with stat_col3:
+        tn_rate = (true_negatives_count / total_verified * 100) if total_verified > 0 else 0
+        st.metric("진음성 (True Negative)", f"{true_negatives_count}건", f"{tn_rate:.1f}%")
+
+    with stat_col4:
+        if total_verified > 0:
+            st.metric("오탐률", f"{fp_rate:.1f}%", delta=None)
+        else:
+            st.metric("오탐률", "N/A")
+
+
+def render_polarity_stats(
+    positive_count: int,
+    neutral_count: int,
+    negative_count: int,
+) -> None:
+    """Render polarity distribution statistics.
+
+    Args:
+        positive_count: Positive sentiment count
+        neutral_count: Neutral sentiment count
+        negative_count: Negative sentiment count
+    """
+    total_answers = positive_count + neutral_count + negative_count
+
+    pol_col1, pol_col2, pol_col3, pol_col4 = st.columns(4)
+
+    with pol_col1:
+        st.metric("전체 분석", f"{total_answers:,}건")
+
+    with pol_col2:
+        pos_rate = (positive_count / total_answers * 100) if total_answers > 0 else 0
+        st.metric("😊 긍정", f"{positive_count:,}건", f"{pos_rate:.1f}%")
+
+    with pol_col3:
+        neu_rate = (neutral_count / total_answers * 100) if total_answers > 0 else 0
+        st.metric("😐 중립", f"{neutral_count:,}건", f"{neu_rate:.1f}%")
+
+    with pol_col4:
+        neg_rate = (negative_count / total_answers * 100) if total_answers > 0 else 0
+        st.metric("😞 부정", f"{negative_count:,}건", f"{neg_rate:.1f}%")
+
+
+def render_feedback_stats(feedback_stats: dict) -> None:
+    """Render feedback statistics row.
+
+    Args:
+        feedback_stats: Dict with feedback counts and accuracy
+    """
+    fb_total = feedback_stats.get("total_feedback", 0)
+    fb_correct = feedback_stats.get("correct_count", 0)
+    fb_wrong = feedback_stats.get("wrong_count", 0)
+    fb_ambiguous = feedback_stats.get("ambiguous_count", 0)
+    accuracy = feedback_stats.get("accuracy_rate", 0)
+
+    fb_col1, fb_col2, fb_col3, fb_col4, fb_col5 = st.columns(5)
+
+    with fb_col1:
+        st.metric(
+            label="총 피드백",
+            value=f"{fb_total}건",
+            help="사용자가 제출한 총 피드백 수",
+        )
+
+    with fb_col2:
+        st.metric(
+            label="👍 정확",
+            value=f"{fb_correct}건",
+            delta=f"{fb_correct/fb_total*100:.0f}%" if fb_total > 0 else None,
+            delta_color="normal",
+            help="정확하다고 평가된 분석 수",
+        )
+
+    with fb_col3:
+        st.metric(
+            label="👎 오류",
+            value=f"{fb_wrong}건",
+            delta=f"{fb_wrong/fb_total*100:.0f}%" if fb_total > 0 else None,
+            delta_color="inverse",
+            help="틀렸다고 평가된 분석 수",
+        )
+
+    with fb_col4:
+        st.metric(
+            label="🤔 애매",
+            value=f"{fb_ambiguous}건",
+            help="판단하기 어려운 경우",
+        )
+
+    with fb_col5:
+        st.metric(
+            label="정확도",
+            value=f"{accuracy:.1f}%",
+            help="정확 / (정확 + 오류) 비율",
+        )

core/__init__.py

@@ -0,0 +1,45 @@
+"""Core infrastructure modules.
+
+Re-exports for backward compatibility and convenience.
+"""
+from .api_client import ChainShiftClient
+from .supabase_client import (
+    get_campaign_overview,
+    get_campaign_date_range,
+    get_false_positives,
+    get_llm_verification_stats,
+    get_polarity_stats,
+    get_answers_by_polarity,
+    get_topic_clusters,
+    get_topic_map_snapshot,
+    get_true_negatives,
+)
+from .athena_client import fetch_full_answer
+from .data_fetchers import get_campaigns
+from .utils import (
+    format_brands_list,
+    get_confidence_tier,
+    get_feedback_reason_label,
+    get_feedback_type_emoji,
+    get_llm_tier_badge,
+    highlight_evidence_spans,
+    truncate_text,
+)
+from .charts import (
+    CONFIDENCE_TIER_COLORS,
+    EMOTION_KO,
+    create_brand_sentiment_chart,
+    create_confidence_tier_pie_chart,
+    create_domain_bar_chart,
+    create_nudge_by_cej_bar_chart,
+    create_platform_bar_chart,
+)
+from .export_utils import render_export_component
+from .job_realtime import (
+    get_active_jobs,
+    get_recent_jobs,
+    format_job_duration,
+    get_status_emoji,
+    get_status_label,
+)
+from .styles import DASHBOARD_CSS, TIER_BORDER_COLORS

core/api_client.py

@@ -0,0 +1,150 @@
+"""ChainShift Gen3 API Client - Nudge Detection Focus.
+
+Domain methods are in mixin files:
+- api_client_sentiment.py: SentimentApiMixin (Gen3, Verification, Keyword)
+- api_client_reports.py: ReportsApiMixin (Reports, Action Items)
+- api_client_hierarchy.py: HierarchyApiMixin (Analysis Jobs, Hierarchy)
+"""
+
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+from dotenv import load_dotenv
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from core.api_client_sentiment import SentimentApiMixin
+from core.api_client_reports import ReportsApiMixin
+from core.api_client_hierarchy import HierarchyApiMixin
+
+load_dotenv()
+
+BASE_URL = os.getenv(
+    "CHAINSHIFT_API_URL",
+    "https://chainshift-service-api.vercel.app"
+)
+API_KEY = os.getenv("CHAINSHIFT_API_KEY", "")
+
+
+def _create_session() -> requests.Session:
+    """Create requests session with retry for transient errors."""
+    session = requests.Session()
+    retry = Retry(
+        total=3,
+        backoff_factor=0.5,
+        status_forcelist=[502, 503, 504],
+    )
+    session.mount("https://", HTTPAdapter(max_retries=retry))
+    session.mount("http://", HTTPAdapter(max_retries=retry))
+    return session
+
+
+class ChainShiftClient(SentimentApiMixin, ReportsApiMixin, HierarchyApiMixin):
+    """Gen3 API client for ChainShift Nudge Detection."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        base_url: str | None = None,
+    ):
+        self.api_key = api_key or API_KEY
+        self.base_url = base_url or BASE_URL
+        self.headers = {"X-API-Key": self.api_key} if self.api_key else {}
+        self._session = _create_session()
+
+    def set_api_key(self, api_key: str):
+        """Set or update API key."""
+        self.api_key = api_key
+        self.headers = {"X-API-Key": self.api_key}
+
+    def _get(self, endpoint: str, params: dict | None = None) -> dict[str, Any]:
+        """Make GET request to API."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._session.get(url, headers=self.headers, params=params, timeout=120)
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, endpoint: str, data: dict | None = None) -> dict[str, Any]:
+        """Make POST request to API."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._session.post(url, headers=self.headers, json=data, timeout=300)
+        response.raise_for_status()
+        return response.json()
+
+    def _patch(self, endpoint: str, data: dict | None = None) -> dict[str, Any]:
+        """Make PATCH request to API."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._session.patch(url, headers=self.headers, json=data, timeout=120)
+        response.raise_for_status()
+        return response.json()
+
+    def _delete(self, endpoint: str) -> dict[str, Any]:
+        """Make DELETE request to API."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._session.delete(url, headers=self.headers, timeout=120)
+        response.raise_for_status()
+        return response.json()
+
+    # ========================================================================
+    # Campaign APIs
+    # ========================================================================
+
+    def get_campaigns(self, page: int = 1, page_size: int = 100) -> dict:
+        """Get list of campaigns."""
+        return self._get("/api/v1/campaigns", {"page": page, "page_size": page_size})
+
+    def get_campaign(self, campaign_id: int) -> dict:
+        """Get campaign details."""
+        return self._get(f"/api/v1/campaigns/{campaign_id}")
+
+    def get_campaign_brands(self, campaign_id: int) -> list[dict]:
+        """Get brands for a campaign."""
+        resp = self._get(f"/api/v1/campaigns/{campaign_id}/brands")
+        return (resp or {}).get("data") or []
+
+    # ========================================================================
+    # Utility Methods
+    # ========================================================================
+
+    @staticmethod
+    def extract_domain(url: str) -> str:
+        """Extract domain from URL."""
+        try:
+            parsed = urlparse(url)
+            return parsed.netloc or url
+        except Exception:
+            return url
+
+    @staticmethod
+    def aggregate_citation_domains(candidates: list[dict]) -> dict[str, int]:
+        """Aggregate citation URLs by domain.
+
+        Returns: {domain: count}
+        """
+        domain_counts: dict[str, int] = {}
+        for candidate in candidates:
+            urls = candidate.get("citation_urls", []) or []
+            for url in urls:
+                domain = ChainShiftClient.extract_domain(url)
+                if domain:
+                    domain_counts[domain] = domain_counts.get(domain, 0) + 1
+        return dict(sorted(domain_counts.items(), key=lambda x: x[1], reverse=True))
+
+    @staticmethod
+    def calculate_risk_score(tier_stats: dict) -> float:
+        """Calculate risk score (0-100) based on confidence tiers.
+
+        Formula: (HIGH * 1.0 + MEDIUM * 0.5 + LOW * 0.2) / total * 100
+        """
+        high = tier_stats.get("HIGH", 0)
+        medium = tier_stats.get("MEDIUM", 0)
+        low = tier_stats.get("LOW", 0)
+        total = high + medium + low
+        if total == 0:
+            return 0.0
+        weighted = high * 1.0 + medium * 0.5 + low * 0.2
+        return min(100.0, (weighted / total) * 100)
+

core/api_client_hierarchy.py

@@ -0,0 +1,102 @@
+"""Hierarchy & Analysis Job API methods for ChainShiftClient.
+
+Mixin class extracted from api_client.py.
+Methods access self._get, self._post from the parent class.
+"""
+from typing import Any
+
+
+class HierarchyApiMixin:
+    """Hierarchy Analysis and Analysis Job APIs."""
+
+    # ========================================================================
+    # Analysis Job APIs
+    # ========================================================================
+
+    def start_analysis_job(self, campaign_id: int, options: dict | None = None) -> dict:
+        """Start a sentiment analysis job. POST /api/v1/sentiment/campaigns/{campaign_id}/run"""
+        body: dict = {}
+        if options:
+            body["options"] = options
+        return self._post(
+            f"/api/v1/sentiment/campaigns/{campaign_id}/run",
+            body,
+        )
+
+    def list_analysis_jobs(
+        self,
+        campaign_id: int | None = None,
+        status: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> dict:
+        """List analysis jobs. GET /api/v1/sentiment/jobs"""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if campaign_id is not None:
+            params["campaign_id"] = campaign_id
+        if status:
+            params["status"] = status
+        return self._get("/api/v1/sentiment/jobs", params)
+
+    def get_analysis_job(self, job_id: str) -> dict:
+        """Get analysis job details. GET /api/v1/sentiment/jobs/{job_id}"""
+        return self._get(f"/api/v1/sentiment/jobs/{job_id}")
+
+    def cancel_analysis_job(self, job_id: str) -> dict:
+        """Cancel a queued or running analysis job. POST /api/v1/sentiment/jobs/{job_id}/cancel"""
+        return self._post(f"/api/v1/sentiment/jobs/{job_id}/cancel")
+
+    # ========================================================================
+    # Hierarchy Analysis APIs
+    # ========================================================================
+
+    def create_hierarchy_job(
+        self,
+        prompt: str,
+        title: str | None = None,
+        processor_config: dict | None = None,
+        settings: dict | None = None,
+    ) -> dict:
+        """Create a hierarchy analysis job. POST /api/v1/hierarchy/jobs"""
+        body: dict = {"prompt": prompt, "processor_config": processor_config or {}}
+        if title:
+            body["title"] = title
+        if settings:
+            body["settings"] = settings
+        return self._post("/api/v1/hierarchy/jobs", body)
+
+    def list_hierarchy_jobs(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        status: str | None = None,
+    ) -> dict:
+        """List hierarchy analysis jobs. GET /api/v1/hierarchy/jobs"""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if status:
+            params["status"] = status
+        return self._get("/api/v1/hierarchy/jobs", params)
+
+    def get_hierarchy_job(self, job_id: str) -> dict:
+        """Get hierarchy job details. GET /api/v1/hierarchy/jobs/{job_id}"""
+        return self._get(f"/api/v1/hierarchy/jobs/{job_id}")
+
+    def get_hierarchy_questions(
+        self,
+        job_id: str,
+        page: int = 1,
+        page_size: int = 50,
+        journey_depth1: str | None = None,
+        export: str | None = None,
+    ) -> dict:
+        """Get questions for a hierarchy job. GET /api/v1/hierarchy/jobs/{job_id}/questions"""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if journey_depth1:
+            params["journey_depth1"] = journey_depth1
+        if export:
+            params["export"] = export
+        return self._get(f"/api/v1/hierarchy/jobs/{job_id}/questions", params)
+
+    def get_hierarchy_question_stats(self, job_id: str) -> dict:
+        """Get question statistics. GET /api/v1/hierarchy/jobs/{job_id}/questions/stats"""
+        return self._get(f"/api/v1/hierarchy/jobs/{job_id}/questions/stats")

core/api_client_reports.py

@@ -0,0 +1,196 @@
+"""Reports & Action Items API methods for ChainShiftClient.
+
+Mixin class extracted from api_client.py.
+Methods access self._get, self._post, self._patch, self._delete, self.base_url from the parent class.
+"""
+
+
+class ReportsApiMixin:
+    """Reports (HTML, data) and Action Items APIs."""
+
+    # ========================================================================
+    # Reports API (HTML Report Generation)
+    # ========================================================================
+
+    def get_report_overview(
+        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/overview"""
+        params = {}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        return self._get(f"/api/v1/reports/{campaign_id}/overview", params or None)
+
+    def get_report_visibility(
+        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/visibility"""
+        params = {}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        return self._get(f"/api/v1/reports/{campaign_id}/visibility", params or None)
+
+    def get_report_citations(
+        self, campaign_id: int, start_date: str | None = None,
+        end_date: str | None = None, limit: int = 30,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/citations"""
+        params: dict = {"limit": limit}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        return self._get(f"/api/v1/reports/{campaign_id}/citations", params)
+
+    def get_report_citation_trends(
+        self, campaign_id: int, start_date: str | None = None,
+        end_date: str | None = None, limit: int = 20,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/citation-trends"""
+        params: dict = {"limit": limit}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        return self._get(f"/api/v1/reports/{campaign_id}/citation-trends", params)
+
+    def get_report_content_types(
+        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/content-types"""
+        params = {}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        return self._get(f"/api/v1/reports/{campaign_id}/content-types", params or None)
+
+    def get_report_sentiment(self, campaign_id: int) -> dict:
+        """GET /api/v1/reports/{campaign_id}/sentiment"""
+        return self._get(f"/api/v1/reports/{campaign_id}/sentiment")
+
+    def get_report_homepage_citations(
+        self, campaign_id: int, start_date: str | None = None,
+        end_date: str | None = None, homepage_urls: str | None = None,
+    ) -> dict:
+        """GET /api/v1/reports/{campaign_id}/homepage-citations"""
+        params = {}
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        if homepage_urls:
+            params["homepage_urls"] = homepage_urls
+        return self._get(f"/api/v1/reports/{campaign_id}/homepage-citations", params or None)
+
+    def generate_html_report(
+        self,
+        campaign_id: int,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        features: list[str] | None = None,
+        enable_insights: bool = False,
+        output_mode: str = "url",
+    ) -> dict:
+        """Generate HTML report. POST /api/v1/reports/{campaign_id}/html"""
+        body: dict = {"output_mode": output_mode, "enable_insights": enable_insights}
+        if start_date:
+            body["start_date"] = start_date
+        if end_date:
+            body["end_date"] = end_date
+        if features:
+            body["features"] = features
+        return self._post(f"/api/v1/reports/{campaign_id}/html", body)
+
+    def build_html_feature(
+        self,
+        campaign_id: int,
+        feature: str,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        enable_insights: bool = False,
+        enable_action_items: bool = False,
+        homepage_urls: list[str] | None = None,
+        period: str = "1w",
+    ) -> dict:
+        """Build a single report feature. POST /api/v1/reports/{campaign_id}/html/build-feature"""
+        body: dict = {"feature": feature, "enable_insights": enable_insights, "period": period}
+        if start_date:
+            body["start_date"] = start_date
+        if end_date:
+            body["end_date"] = end_date
+        if enable_action_items:
+            body["enable_action_items"] = enable_action_items
+        if homepage_urls:
+            body["homepage_urls"] = homepage_urls
+        return self._post(f"/api/v1/reports/{campaign_id}/html/build-feature", body)
+
+    def render_html_report(
+        self,
+        campaign_id: int,
+        features_data: list[dict],
+        title: str | None = None,
+        subtitle: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        enable_insights: bool = False,
+        enable_action_items: bool = False,
+        output_mode: str = "url",
+    ) -> dict:
+        """Assemble and render final HTML report. POST /api/v1/reports/{campaign_id}/html/render"""
+        body: dict = {
+            "features_data": features_data,
+            "output_mode": output_mode,
+            "enable_insights": enable_insights,
+        }
+        if title:
+            body["title"] = title
+        if subtitle:
+            body["subtitle"] = subtitle
+        if start_date:
+            body["start_date"] = start_date
+        if end_date:
+            body["end_date"] = end_date
+        if enable_action_items:
+            body["enable_action_items"] = enable_action_items
+        return self._post(f"/api/v1/reports/{campaign_id}/html/render", body)
+
+    def get_html_report_history(self, campaign_id: int, page: int = 1, page_size: int = 20) -> dict:
+        """Get HTML report history. GET /api/v1/reports/{campaign_id}/html/history"""
+        return self._get(f"/api/v1/reports/{campaign_id}/html/history", {"page": page, "page_size": page_size})
+
+    def get_html_report_detail(self, campaign_id: int, report_id: str) -> dict:
+        """Get HTML report detail. GET /api/v1/reports/{campaign_id}/html/{report_id}"""
+        return self._get(f"/api/v1/reports/{campaign_id}/html/{report_id}")
+
+    # ========================================================================
+    # Action Items APIs (ADR-018 Phase 2)
+    # ========================================================================
+
+    def save_action_items(
+        self,
+        campaign_id: int,
+        items: list[dict],
+        report_id: str | None = None,
+    ) -> dict:
+        """Save action items from report. POST /api/v1/action-items"""
+        body: dict = {"campaign_id": campaign_id, "items": items}
+        if report_id:
+            body["report_id"] = report_id
+        return self._post("/api/v1/action-items", body)
+
+    def update_action_item(self, item_id: str, data: dict) -> dict:
+        """Update action item. PATCH /api/v1/action-items/{item_id}"""
+        return self._patch(f"/api/v1/action-items/{item_id}", data)
+
+    def delete_action_item(self, item_id: str) -> dict:
+        """Delete action item. DELETE /api/v1/action-items/{item_id}"""
+        return self._delete(f"/api/v1/action-items/{item_id}")
+
+    def export_action_item_html(self, item_id: str) -> dict:
+        """Export action item as HTML. GET /api/v1/action-items/{item_id}/export/html"""
+        return self._get(f"/api/v1/action-items/{item_id}/export/html")

core/api_client_sentiment.py

@@ -0,0 +1,279 @@
+"""Sentiment API methods for ChainShiftClient.
+
+Mixin class extracted from api_client.py.
+Methods access self._get, self._post, self._session, self.base_url, self.headers from the parent class.
+"""
+from typing import Any
+
+
+class SentimentApiMixin:
+    """Gen3 Nudge, Brand Mentions, LLM Verification, Feedback, Keyword APIs."""
+
+    # ========================================================================
+    # Gen3 APIs - Nudge Detection
+    # ========================================================================
+
+    def get_nudge_candidates(
+        self,
+        campaign_id: int,
+        page: int = 1,
+        page_size: int = 50,
+        bit_quadrant: str | None = None,
+        platform: str | None = None,
+    ) -> dict:
+        """Get answers flagged for nudge (in-house brand negative mentions).
+
+        Returns:
+            - total_nudge_candidates: int
+            - by_confidence_tier: {HIGH: n, MEDIUM: n, LOW: n}
+            - by_platform: {CHATGPT: n, GOOGLE_AI: n, ...}
+            - by_cej: {AWARENESS_COMPARISON: n, PURCHASE: n, ...}
+            - by_bit_quadrant: {neutral: n, ...}
+            - candidates: list of nudge items
+        """
+        params = {"page": page, "page_size": page_size}
+        if bit_quadrant:
+            params["bit_quadrant"] = bit_quadrant
+        if platform:
+            params["platform"] = platform
+        return self._get(f"/api/v1/sentiment/campaigns/{campaign_id}/nudge-candidates", params)
+
+    def get_brand_mentions(
+        self,
+        campaign_id: int,
+        page: int = 1,
+        page_size: int = 50,
+        brand_type: str | None = None,
+        polarity: str | None = None,
+        llm_verified: str | None = None,
+        brand_name: str | None = None,
+        sort_by: str | None = "analyzed_at",
+        sort_desc: bool = True,
+    ) -> dict:
+        """Get brand mention analysis."""
+        params = {"page": page, "page_size": page_size, "sort_desc": sort_desc}
+        if brand_type:
+            params["brand_type"] = brand_type
+        if polarity:
+            params["polarity"] = polarity
+        if llm_verified:
+            params["llm_verified"] = llm_verified
+        if brand_name:
+            params["brand_name"] = brand_name
+        if sort_by:
+            params["sort_by"] = sort_by
+        return self._get(f"/api/v1/sentiment/campaigns/{campaign_id}/brand-mentions", params)
+
+    def export_brand_mentions(
+        self,
+        campaign_id: int,
+        brand_type: str | None = None,
+        polarity: str | None = None,
+        llm_verified: str | None = None,
+        brand_name: str | None = None,
+        include_full_answers: bool = False,
+    ) -> bytes:
+        """Export brand mentions to Excel."""
+        params = {}
+        if brand_type:
+            params["brand_type"] = brand_type
+        if polarity:
+            params["polarity"] = polarity
+        if llm_verified:
+            params["llm_verified"] = llm_verified
+        if brand_name:
+            params["brand_name"] = brand_name
+        if include_full_answers:
+            params["include_full_answers"] = "true"
+
+        url = f"{self.base_url}/api/v1/sentiment/campaigns/{campaign_id}/brand-mentions/export"
+        response = self._session.get(url, params=params, headers=self.headers, timeout=120)
+        response.raise_for_status()
+        return response.content
+
+    # ========================================================================
+    # LLM Verification & Human Feedback APIs
+    # ========================================================================
+
+    def verify_answer(self, answer_id: int, force: bool = False) -> dict:
+        """Request LLM 2차 검증 for an answer."""
+        return self._post("/api/v1/sentiment/verify", {
+            "answer_id": answer_id,
+            "force": force,
+        })
+
+    def submit_feedback(
+        self,
+        answer_id: int,
+        campaign_id: int,
+        feedback_type: str,
+        corrected_polarity: str | None = None,
+        wrong_reason: str | None = None,
+        comment: str | None = None,
+    ) -> dict:
+        """Submit human feedback for an answer sentiment."""
+        data = {
+            "answer_id": answer_id,
+            "campaign_id": campaign_id,
+            "feedback_type": feedback_type,
+        }
+        if corrected_polarity:
+            data["corrected_polarity"] = corrected_polarity
+        if wrong_reason:
+            data["wrong_reason"] = wrong_reason
+        if comment:
+            data["comment"] = comment
+        return self._post("/api/v1/sentiment/feedback", data)
+
+    def get_feedback_stats(self, campaign_id: int) -> dict:
+        """Get feedback statistics for a campaign."""
+        return self._get(f"/api/v1/sentiment/campaigns/{campaign_id}/feedback/stats")
+
+    def get_full_answers(self, answer_ids: list[int]) -> dict:
+        """Get full answer text for multiple answers."""
+        return self._post("/api/v1/sentiment/answers/full", {"answer_ids": answer_ids})
+
+    def export_nudge_candidates(
+        self,
+        campaign_id: int,
+        include_full_answers: bool = False,
+        include_evidence: bool = True,
+        llm_verified_only: bool = False,
+        platform: str | None = None,
+        llm_is_negative: bool | None = None,
+    ) -> bytes:
+        """Export nudge candidates to Excel."""
+        url = f"{self.base_url}/api/v1/sentiment/campaigns/{campaign_id}/nudge-candidates/export"
+        params = {
+            "include_full_answers": str(include_full_answers).lower(),
+            "include_evidence": str(include_evidence).lower(),
+            "llm_verified_only": str(llm_verified_only).lower(),
+        }
+        if platform:
+            params["platform"] = platform
+        if llm_is_negative is not None:
+            params["llm_is_negative"] = str(llm_is_negative).lower()
+        response = self._session.get(url, headers=self.headers, params=params, timeout=120)
+        response.raise_for_status()
+        return response.content
+
+    # ========================================================================
+    # Keyword Sentiment APIs
+    # ========================================================================
+
+    def start_keyword_analysis(self, campaign_id: int, keywords: list[str]) -> dict:
+        """Start a keyword sentiment analysis job."""
+        return self._post(
+            f"/api/v1/sentiment/campaigns/{campaign_id}/keyword-analysis",
+            {"keywords": keywords},
+        )
+
+    def get_keyword_summary(
+        self,
+        campaign_id: int,
+        keyword: str | None = None,
+        page: int = 1,
+        page_size: int = 50,
+    ) -> dict:
+        """Get keyword sentiment summary with optional filter and pagination."""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if keyword:
+            params["keyword"] = keyword
+        return self._get(f"/api/v1/sentiment/campaigns/{campaign_id}/keyword-summary", params)
+
+    def get_keyword_results(
+        self,
+        campaign_id: int,
+        keyword: str | None = None,
+        sentiment: str | None = None,
+        brand_name: str | None = None,
+        competitor: bool = False,
+        llm_verified: str | None = None,
+        llm_is_negative: bool | None = None,
+        platform: str | None = None,
+        brand_only: bool = False,
+        no_brand: bool = False,
+        page: int = 1,
+        page_size: int = 50,
+    ) -> dict:
+        """Get keyword results with filters."""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if keyword:
+            params["keyword"] = keyword
+        if sentiment:
+            params["sentiment"] = sentiment
+        if brand_name:
+            params["brand_name"] = brand_name
+        if competitor:
+            params["competitor"] = "true"
+        if llm_verified:
+            params["llm_verified"] = llm_verified
+        if llm_is_negative is not None:
+            params["llm_is_negative"] = str(llm_is_negative).lower()
+        if platform:
+            params["platform"] = platform
+        if brand_only:
+            params["brand_only"] = "true"
+        if no_brand:
+            params["no_brand"] = "true"
+        return self._get(
+            f"/api/v1/sentiment/campaigns/{campaign_id}/keyword-results", params
+        )
+
+    def get_keyword_brand_analysis(
+        self,
+        campaign_id: int,
+        keyword: str | None = None,
+        brand_name: str | None = None,
+        competitor: bool = False,
+    ) -> dict:
+        """Get keyword x brand cross analysis."""
+        params: dict[str, Any] = {}
+        if keyword:
+            params["keyword"] = keyword
+        if brand_name:
+            params["brand_name"] = brand_name
+        if competitor:
+            params["competitor"] = "true"
+        return self._get(
+            f"/api/v1/sentiment/campaigns/{campaign_id}/keyword-brand-analysis", params
+        )
+
+    def export_keyword_results(
+        self,
+        campaign_id: int,
+        keyword: str | None = None,
+        sentiment: str | None = None,
+        brand_name: str | None = None,
+        competitor: bool = False,
+        llm_verified: str | None = None,
+        llm_is_negative: bool | None = None,
+        platform: str | None = None,
+        brand_only: bool = False,
+        no_brand: bool = False,
+        format: str = "xlsx",
+    ) -> bytes:
+        """Export keyword results to Excel or CSV with same filters as list endpoint."""
+        params: dict[str, Any] = {"format": format}
+        if keyword:
+            params["keyword"] = keyword
+        if sentiment:
+            params["sentiment"] = sentiment
+        if brand_name:
+            params["brand_name"] = brand_name
+        if competitor:
+            params["competitor"] = "true"
+        if llm_verified:
+            params["llm_verified"] = llm_verified
+        if llm_is_negative is not None:
+            params["llm_is_negative"] = str(llm_is_negative).lower()
+        if platform:
+            params["platform"] = platform
+        if brand_only:
+            params["brand_only"] = "true"
+        if no_brand:
+            params["no_brand"] = "true"
+        url = f"{self.base_url}/api/v1/sentiment/campaigns/{campaign_id}/keyword-results/export"
+        response = self._session.get(url, params=params, headers=self.headers, timeout=120)
+        response.raise_for_status()
+        return response.content

core/athena_client.py

@@ -0,0 +1,331 @@
+"""Standalone Athena client for dashboard.
+
+Uses requests + AWS SigV4 to query Athena directly. No dependency on
+app/ modules — compatible with HuggingFace Space deployment.
+
+Public API:
+  - fetch_full_answer(answer_id) -> str | None
+  - fetch_full_answers_batch(answer_ids) -> dict[int, str]
+  - query_athena(sql, params) -> list[dict]
+  - is_athena_configured() -> bool
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import uuid
+from datetime import datetime, timezone, date as date_type
+from pathlib import Path
+
+import requests
+from dotenv import load_dotenv
+
+# Load environment variables (project root, APP_ENV-aware)
+_project_root = Path(__file__).parent.parent.parent.parent
+_app_env = os.environ.get("APP_ENV")
+if _app_env:
+    _candidates = [f".env.{_app_env}", ".env.dev", ".env.prod"]
+else:
+    _candidates = [".env.dev", ".env.prod"]
+for _env_name in _candidates:
+    _env_path = _project_root / _env_name
+    if _env_path.exists():
+        load_dotenv(_env_path, override=True)
+        break
+
+# ---------------------------------------------------------------------------
+# Config from env vars (HuggingFace Secrets compatible)
+# ---------------------------------------------------------------------------
+
+_ACCESS_KEY_ID = os.environ.get("ATHENA_ACCESS_KEY_ID", "")
+_SECRET_ACCESS_KEY = os.environ.get("ATHENA_SECRET_ACCESS_KEY", "")
+_REGION = os.environ.get("ATHENA_REGION", "ap-northeast-2")
+_DATABASE = os.environ.get("ATHENA_DATABASE", "fde-chainshift-prod")
+_S3_OUTPUT = os.environ.get("ATHENA_S3_OUTPUT", "s3://chainshift-prod-rds-snapshots/athena-results/")
+
+# ---------------------------------------------------------------------------
+# AWS SigV4 signing
+# ---------------------------------------------------------------------------
+
+_ALGORITHM = "AWS4-HMAC-SHA256"
+
+
+def _sign(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+
+def _get_signature_key(secret: str, date_stamp: str, region: str, service: str) -> bytes:
+    k_date = _sign(("AWS4" + secret).encode("utf-8"), date_stamp)
+    k_region = _sign(k_date, region)
+    k_service = _sign(k_region, service)
+    return _sign(k_service, "aws4_request")
+
+
+def _sigv4_headers(action: str, body: str) -> dict[str, str]:
+    """Build SigV4-signed headers for an Athena API call."""
+    now = datetime.now(timezone.utc)
+    amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+    date_stamp = now.strftime("%Y%m%d")
+    region = _REGION
+    service = "athena"
+    host = f"athena.{region}.amazonaws.com"
+
+    payload_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    canonical_headers = (
+        f"content-type:application/x-amz-json-1.1\n"
+        f"host:{host}\n"
+        f"x-amz-date:{amz_date}\n"
+        f"x-amz-target:AmazonAthena.{action}\n"
+    )
+    signed_headers = "content-type;host;x-amz-date;x-amz-target"
+    canonical_request = (
+        f"POST\n/\n\n"
+        f"{canonical_headers}\n{signed_headers}\n{payload_hash}"
+    )
+
+    credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"
+    string_to_sign = (
+        f"{_ALGORITHM}\n{amz_date}\n{credential_scope}\n"
+        f"{hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()}"
+    )
+
+    signing_key = _get_signature_key(_SECRET_ACCESS_KEY, date_stamp, region, service)
+    signature = hmac.new(signing_key, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    authorization = (
+        f"{_ALGORITHM} Credential={_ACCESS_KEY_ID}/{credential_scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+
+    return {
+        "Content-Type": "application/x-amz-json-1.1",
+        "Host": host,
+        "X-Amz-Date": amz_date,
+        "X-Amz-Target": f"AmazonAthena.{action}",
+        "Authorization": authorization,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Athena API helpers
+# ---------------------------------------------------------------------------
+
+_POLL_INTERVAL = 1.0
+_POLL_TIMEOUT = 120.0
+
+
+def _athena_api_call(action: str, body: dict) -> dict:
+    """POST to the Athena JSON API and return parsed response."""
+    payload = json.dumps(body)
+    url = f"https://athena.{_REGION}.amazonaws.com/"
+    headers = _sigv4_headers(action, payload)
+
+    resp = requests.post(url, data=payload, headers=headers, timeout=30)
+    if resp.status_code != 200:
+        raise RuntimeError(
+            f"Athena {action} failed ({resp.status_code}): {resp.text}"
+        )
+    return resp.json()
+
+
+def _start_query(sql: str) -> str:
+    """Submit a query and return the QueryExecutionId."""
+    body: dict = {
+        "QueryString": sql,
+        "ClientRequestToken": str(uuid.uuid4()),
+        "QueryExecutionContext": {"Database": _DATABASE},
+        "ResultConfiguration": {"OutputLocation": _S3_OUTPUT},
+    }
+    result = _athena_api_call("StartQueryExecution", body)
+    return result["QueryExecutionId"]
+
+
+def _wait_for_query(query_id: str, timeout: float | None = None) -> None:
+    """Poll until the query completes or times out."""
+    deadline = time.monotonic() + (timeout or _POLL_TIMEOUT)
+    while time.monotonic() < deadline:
+        result = _athena_api_call(
+            "GetQueryExecution", {"QueryExecutionId": query_id},
+        )
+        state = result["QueryExecution"]["Status"]["State"]
+        if state == "SUCCEEDED":
+            return
+        if state in ("FAILED", "CANCELLED"):
+            reason = result["QueryExecution"]["Status"].get(
+                "StateChangeReason", "unknown"
+            )
+            raise RuntimeError(f"Athena query {state}: {reason}")
+        time.sleep(_POLL_INTERVAL)
+
+    raise TimeoutError(f"Athena query {query_id} timed out after {_POLL_TIMEOUT}s")
+
+
+def _convert_value(raw: str | None, athena_type: str) -> object:
+    """Convert a string value from Athena to the appropriate Python type."""
+    if raw is None:
+        return None
+    athena_type = athena_type.lower()
+    if athena_type in ("integer", "int", "bigint", "smallint", "tinyint"):
+        return int(raw)
+    if athena_type in ("double", "float", "decimal", "real"):
+        return float(raw)
+    if athena_type == "boolean":
+        return raw.lower() == "true"
+    if athena_type == "date":
+        return date_type.fromisoformat(raw)
+    return raw
+
+
+def _get_results(query_id: str) -> list[dict]:
+    """Fetch all result pages and return as list[dict]."""
+    rows: list[dict] = []
+    next_token: str | None = None
+
+    while True:
+        body: dict = {"QueryExecutionId": query_id, "MaxResults": 1000}
+        if next_token:
+            body["NextToken"] = next_token
+
+        result = _athena_api_call("GetQueryResults", body)
+        result_set = result["ResultSet"]
+
+        columns = result_set["ResultSetMetadata"]["ColumnInfo"]
+        col_names = [c["Name"] for c in columns]
+        col_types = [c["Type"] for c in columns]
+
+        data_rows = result_set.get("Rows", [])
+        start = 1 if not next_token and data_rows else 0
+
+        for row in data_rows[start:]:
+            values = row.get("Data", [])
+            record: dict = {}
+            for i, col_name in enumerate(col_names):
+                if i < len(values):
+                    cell = values[i]
+                    raw = cell.get("VarCharValue")
+                    record[col_name] = _convert_value(raw, col_types[i])
+                else:
+                    record[col_name] = None
+            rows.append(record)
+
+        next_token = result.get("NextToken")
+        if not next_token:
+            break
+
+    return rows
+
+
+# ---------------------------------------------------------------------------
+# Parameter substitution
+# ---------------------------------------------------------------------------
+
+def _substitute_params(sql: str, params: dict) -> str:
+    """Replace %(name)s placeholders with escaped values."""
+    def _replace(match: re.Match) -> str:
+        name = match.group(1)
+        if name not in params:
+            raise KeyError(f"Parameter '{name}' not found in params dict")
+        val = params[name]
+        if val is None:
+            return "NULL"
+        if isinstance(val, (int, float)):
+            return str(val)
+        escaped = str(val).replace("'", "''")
+        return f"'{escaped}'"
+
+    return re.sub(r"%\((\w+)\)s", _replace, sql)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def is_athena_configured() -> bool:
+    """Check if Athena credentials are configured."""
+    return bool(_ACCESS_KEY_ID and _SECRET_ACCESS_KEY and _S3_OUTPUT)
+
+
+def query_athena(
+    sql: str,
+    params: dict | None = None,
+    timeout: float | None = None,
+) -> list[dict]:
+    """Execute Athena SQL and return results as list of dicts.
+
+    Args:
+        sql: SQL query string. Use %(name)s for parameter placeholders.
+        params: Optional dict of parameters for the query.
+        timeout: Max seconds to wait for query completion.
+
+    Returns:
+        List of dicts (one per row), column names as keys.
+    """
+    if not is_athena_configured():
+        raise ValueError("Athena credentials not configured")
+
+    if params:
+        sql = _substitute_params(sql, params)
+
+    query_id = _start_query(sql)
+    _wait_for_query(query_id, timeout=timeout)
+    return _get_results(query_id)
+
+
+# ---------------------------------------------------------------------------
+# Dashboard-specific functions
+# ---------------------------------------------------------------------------
+
+def fetch_full_answer(answer_id: int) -> str | None:
+    """Fetch full answer content from Athena answers table.
+
+    Args:
+        answer_id: The answer ID to fetch
+
+    Returns:
+        Full answer content or None if not found
+    """
+    if not is_athena_configured():
+        print(f"[Athena] Not configured, cannot fetch answer {answer_id}")
+        return None
+
+    try:
+        rows = query_athena(
+            "SELECT content FROM answers WHERE id = %(answer_id)s AND deleted_at IS NULL",
+            {"answer_id": answer_id},
+        )
+        return rows[0]["content"] if rows else None
+    except Exception as e:
+        print(f"[Athena Error] Failed to fetch answer {answer_id}: {e}")
+        return None
+
+
+def fetch_full_answers_batch(answer_ids: list[int]) -> dict[int, str]:
+    """Fetch multiple full answers from Athena in a single query.
+
+    Args:
+        answer_ids: List of answer IDs to fetch
+
+    Returns:
+        Dict mapping answer_id to content
+    """
+    if not answer_ids:
+        return {}
+
+    if not is_athena_configured():
+        print("[Athena] Not configured, cannot fetch answers batch")
+        return {}
+
+    try:
+        # Athena doesn't support array params like PostgreSQL's ANY(%s).
+        # Use IN clause with comma-separated IDs (all integers, safe).
+        ids_str = ", ".join(str(int(aid)) for aid in answer_ids)
+        rows = query_athena(
+            f"SELECT id, content FROM answers WHERE id IN ({ids_str}) AND deleted_at IS NULL",
+        )
+        return {row["id"]: row["content"] for row in rows if row.get("content")}
+    except Exception as e:
+        print(f"[Athena Error] Failed to fetch answers batch: {e}")
+        return {}

core/charts.py

@@ -0,0 +1,361 @@
+"""Chart components for Gen3 Nudge Detection Dashboard."""
+
+import plotly.graph_objects as go
+import pandas as pd
+
+
+# =============================================================================
+# Color Constants
+# =============================================================================
+
+CONFIDENCE_TIER_COLORS = {
+    "HIGH": "#EF4444",    # Red
+    "MEDIUM": "#F59E0B",  # Amber
+    "LOW": "#10B981",     # Green
+}
+
+PLATFORM_COLORS = {
+    "CHATGPT": "#10A37F",
+    "GOOGLE_AI": "#4285F4",
+    "GOOGLE_OVERVIEW": "#34A853",
+    "PERPLEXITY": "#6366F1",
+    "GEMINI": "#8B5CF6",
+    "BING": "#00A4EF",
+    "CLAUDE": "#D97706",
+}
+
+POLARITY_COLORS = {
+    "positive": "#10B981",
+    "negative": "#EF4444",
+    "neutral": "#6B7280",
+}
+
+# English to Korean emotion mapping
+EMOTION_KO = {
+    "admiration": "감탄",
+    "amusement": "재미",
+    "anger": "분노",
+    "annoyance": "짜증",
+    "approval": "인정",
+    "caring": "배려",
+    "confusion": "혼란",
+    "curiosity": "호기심",
+    "desire": "욕구",
+    "disappointment": "실망",
+    "disapproval": "반대",
+    "disgust": "혐오",
+    "embarrassment": "당혹",
+    "excitement": "흥분",
+    "fear": "두려움",
+    "gratitude": "감사",
+    "grief": "슬픔",
+    "joy": "기쁨",
+    "love": "사랑",
+    "nervousness": "불안",
+    "optimism": "낙관",
+    "pride": "자부심",
+    "realization": "깨달음",
+    "relief": "안도",
+    "remorse": "후회",
+    "sadness": "슬픔",
+    "surprise": "놀라움",
+    "neutral": "중립",
+    "trust": "신뢰",
+    "anticipation": "기대",
+    "interest": "관심",
+    "satisfaction": "만족",
+    "frustration": "좌절",
+    "hope": "희망",
+    "worry": "걱정",
+}
+
+# CEJ Korean labels
+CEJ_LABELS = {
+    "VERIFICATION": "검증 질문",
+    "INFORMATION_DISCOVERY": "정보 탐색",
+    "HOW_TO": "사용법",
+    "WHERE_TO_BUY": "구매처",
+    "RECOMMENDATION": "추천 요청",
+    "SIDE_EFFECT": "부작용",
+    "MARKET_TRENDS": "시장 동향",
+    "RESULT_EFFECTIVENESS": "효과/결과",
+    "COMPARISON": "비교",
+    "INGREDIENT": "성분",
+    "AWARENESS_COMPARISON": "인지/비교",
+    "PURCHASE": "구매",
+    "POST_PURCHASE": "구매 후",
+}
+
+
+# =============================================================================
+# Gen3 Nudge Charts
+# =============================================================================
+
+def create_confidence_tier_pie_chart(tier_stats: dict) -> go.Figure:
+    """Create pie chart for confidence tier distribution (HIGH/MEDIUM/LOW)."""
+    if not tier_stats:
+        return go.Figure()
+
+    labels = list(tier_stats.keys())
+    values = list(tier_stats.values())
+    colors = [CONFIDENCE_TIER_COLORS.get(k, "#6B7280") for k in labels]
+
+    label_map = {
+        "HIGH": "🔴 HIGH",
+        "MEDIUM": "🟡 MEDIUM",
+        "LOW": "🟢 LOW",
+    }
+    display_labels = [label_map.get(k, k) for k in labels]
+
+    fig = go.Figure(data=[go.Pie(
+        labels=display_labels,
+        values=values,
+        marker=dict(colors=colors),
+        hole=0.4,
+        textinfo="percent+value",
+        textposition="outside",
+    )])
+
+    fig.update_layout(
+        title="",
+        showlegend=True,
+        legend=dict(orientation="h", yanchor="bottom", y=-0.2, xanchor="center", x=0.5),
+        margin=dict(t=20, b=60, l=20, r=20),
+        height=280,
+    )
+
+    return fig
+
+
+def create_platform_bar_chart(platform_stats: dict) -> go.Figure:
+    """Create horizontal bar chart for platform distribution."""
+    if not platform_stats:
+        return go.Figure()
+
+    sorted_items = sorted(platform_stats.items(), key=lambda x: x[1], reverse=True)
+    platforms = [item[0] for item in sorted_items]
+    counts = [item[1] for item in sorted_items]
+    colors = [PLATFORM_COLORS.get(p, "#6B7280") for p in platforms]
+
+    fig = go.Figure(data=[
+        go.Bar(
+            y=platforms,
+            x=counts,
+            orientation="h",
+            marker_color=colors,
+            text=[f"{c}건" for c in counts],
+            textposition="auto",
+        )
+    ])
+
+    fig.update_layout(
+        title="",
+        xaxis_title="넛지 후보 수",
+        yaxis=dict(autorange="reversed"),
+        margin=dict(t=20, b=40, l=100, r=20),
+        height=max(200, len(platforms) * 35),
+    )
+
+    return fig
+
+
+def create_nudge_by_cej_bar_chart(cej_counts: dict) -> go.Figure:
+    """Create horizontal bar chart for nudge distribution by CEJ stage."""
+    if not cej_counts:
+        return go.Figure()
+
+    sorted_items = sorted(cej_counts.items(), key=lambda x: x[1], reverse=True)
+    cej_stages = [item[0] for item in sorted_items]
+    counts = [item[1] for item in sorted_items]
+
+    display_labels = [CEJ_LABELS.get(cej, cej) for cej in cej_stages]
+
+    fig = go.Figure(data=[
+        go.Bar(
+            y=display_labels,
+            x=counts,
+            orientation="h",
+            marker_color="#6366F1",
+            text=[f"{c}건" for c in counts],
+            textposition="auto",
+        )
+    ])
+
+    fig.update_layout(
+        title="",
+        xaxis_title="넛지 후보 수",
+        yaxis=dict(autorange="reversed"),
+        margin=dict(t=20, b=40, l=100, r=20),
+        height=max(200, len(cej_stages) * 35),
+    )
+
+    return fig
+
+
+def create_brand_sentiment_chart(brands: list[dict]) -> go.Figure:
+    """Create horizontal stacked bar chart for brand sentiment comparison."""
+    if not brands:
+        return go.Figure()
+
+    # Sort by total mentions
+    sorted_brands = sorted(brands, key=lambda x: x.get("total_mentions", 0), reverse=True)[:10]
+
+    brand_names = []
+    for b in sorted_brands:
+        name = b.get("brand_name", "Unknown")
+        brand_type = b.get("brand_type", "")
+        prefix = "🏠 " if brand_type == "IN_HOUSE" else "🏢 "
+        brand_names.append(f"{prefix}{name}")
+
+    positive_rates = [b.get("positive_rate", 0) for b in sorted_brands]
+    negative_rates = [b.get("negative_rate", 0) for b in sorted_brands]
+    neutral_rates = [100 - p - n for p, n in zip(positive_rates, negative_rates)]
+
+    fig = go.Figure()
+
+    fig.add_trace(go.Bar(
+        y=brand_names,
+        x=positive_rates,
+        name="긍정",
+        orientation="h",
+        marker_color="#10B981",
+        text=[f"{v:.1f}%" for v in positive_rates],
+        textposition="inside",
+    ))
+
+    fig.add_trace(go.Bar(
+        y=brand_names,
+        x=neutral_rates,
+        name="중립",
+        orientation="h",
+        marker_color="#E5E7EB",
+        text=[f"{v:.1f}%" for v in neutral_rates],
+        textposition="inside",
+    ))
+
+    fig.add_trace(go.Bar(
+        y=brand_names,
+        x=negative_rates,
+        name="부정",
+        orientation="h",
+        marker_color="#EF4444",
+        text=[f"{v:.1f}%" for v in negative_rates],
+        textposition="inside",
+    ))
+
+    fig.update_layout(
+        title="",
+        barmode="stack",
+        xaxis_title="비율 (%)",
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+        margin=dict(t=50, b=50, l=150, r=20),
+        height=max(300, len(sorted_brands) * 40),
+        yaxis=dict(autorange="reversed"),
+    )
+
+    return fig
+
+
+def create_domain_bar_chart(domain_counts: dict) -> go.Figure:
+    """Create horizontal bar chart for citation domain distribution."""
+    if not domain_counts:
+        return go.Figure()
+
+    # Take top 15 domains
+    sorted_items = list(domain_counts.items())[:15]
+    domains = [item[0] for item in sorted_items]
+    counts = [item[1] for item in sorted_items]
+
+    # Truncate long domain names
+    display_domains = [d[:40] + "..." if len(d) > 40 else d for d in domains]
+
+    fig = go.Figure(data=[
+        go.Bar(
+            y=display_domains,
+            x=counts,
+            orientation="h",
+            marker_color="#3B82F6",
+            text=[f"{c}회" for c in counts],
+            textposition="auto",
+        )
+    ])
+
+    fig.update_layout(
+        title="",
+        xaxis_title="인용 횟수",
+        yaxis=dict(autorange="reversed"),
+        margin=dict(t=20, b=40, l=200, r=20),
+        height=max(300, len(sorted_items) * 30),
+    )
+
+    return fig
+
+
+def create_bit_quadrant_chart(bit_stats: dict) -> go.Figure:
+    """Create bar chart for BIT quadrant distribution."""
+    if not bit_stats:
+        return go.Figure()
+
+    BIT_LABELS = {
+        "neutral": "중립",
+        "product_satisfaction": "제품 만족",
+        "unmet_expectations": "기대 미충족",
+        "brand_trust": "브랜드 신뢰",
+    }
+
+    sorted_items = sorted(bit_stats.items(), key=lambda x: x[1], reverse=True)
+    quadrants = [BIT_LABELS.get(item[0], item[0]) for item in sorted_items]
+    counts = [item[1] for item in sorted_items]
+
+    colors = ["#6366F1", "#8B5CF6", "#A855F7", "#D946EF"]
+
+    fig = go.Figure(data=[
+        go.Bar(
+            x=quadrants,
+            y=counts,
+            marker_color=colors[:len(quadrants)],
+            text=[f"{c}건" for c in counts],
+            textposition="outside",
+        )
+    ])
+
+    fig.update_layout(
+        title="",
+        yaxis_title="넛지 후보 수",
+        margin=dict(t=20, b=50, l=50, r=20),
+        height=280,
+    )
+
+    return fig
+
+
+def create_emotion_distribution_chart(emotion_stats: dict) -> go.Figure:
+    """Create bar chart for emotion distribution in nudge candidates."""
+    if not emotion_stats:
+        return go.Figure()
+
+    sorted_items = sorted(emotion_stats.items(), key=lambda x: x[1], reverse=True)[:8]
+    emotions = [EMOTION_KO.get(item[0], item[0]) for item in sorted_items]
+    counts = [item[1] for item in sorted_items]
+
+    colors = ["#6366F1", "#8B5CF6", "#A855F7", "#D946EF", "#EC4899", "#F43F5E", "#F97316", "#FBBF24"]
+
+    fig = go.Figure(data=[
+        go.Bar(
+            x=emotions,
+            y=counts,
+            marker_color=colors[:len(emotions)],
+            text=[f"{c}건" for c in counts],
+            textposition="outside",
+        )
+    ])
+
+    fig.update_layout(
+        title="",
+        yaxis_title="넛지 후보 수",
+        xaxis_tickangle=-30,
+        margin=dict(t=20, b=80, l=50, r=20),
+        height=280,
+    )
+
+    return fig

core/data_fetchers.py

@@ -0,0 +1,71 @@
+"""캐시된 API 데이터 페처.
+
+Streamlit cache를 활용한 API 호출 함수들.
+"""
+import streamlit as st
+
+from .api_client import ChainShiftClient
+
+
+@st.cache_data(ttl=300)
+def get_campaigns(api_key: str = "", access_token: str = ""):
+    """Fetch all campaigns with pagination and caching."""
+    client = ChainShiftClient(api_key=api_key or None, access_token=access_token or None)
+    all_items: list[dict] = []
+    page = 1
+    while True:
+        resp = client.get_campaigns(page=page, page_size=100)
+        items = resp.get("data", {}).get("items", [])
+        all_items.extend(items)
+        total = resp.get("data", {}).get("total", 0)
+        if len(all_items) >= total or not items:
+            break
+        page += 1
+    return {"data": {"items": all_items, "total": len(all_items)}}
+
+
+@st.cache_data(ttl=60)
+def get_nudge_candidates(
+    api_key: str = "",
+    campaign_id: int = 0,
+    page: int = 1,
+    page_size: int = 50,
+    platform: str | None = None,
+    confidence_tier: str | None = None,
+    access_token: str = "",
+):
+    """Fetch nudge candidates (in-house brand negative mentions)."""
+    client = ChainShiftClient(api_key=api_key or None, access_token=access_token or None)
+    return client.get_nudge_candidates(
+        campaign_id,
+        page=page,
+        page_size=page_size,
+        platform=platform if platform and platform != "전체" else None,
+    )
+
+
+@st.cache_data(ttl=60)
+def get_brand_mentions(
+    api_key: str = "",
+    campaign_id: int = 0,
+    brand_type: str | None = None,
+    polarity: str | None = None,
+    access_token: str = "",
+):
+    """Fetch brand mention analysis."""
+    client = ChainShiftClient(api_key=api_key or None, access_token=access_token or None)
+    return client.get_brand_mentions(
+        campaign_id,
+        brand_type=brand_type if brand_type and brand_type != "전체" else None,
+        polarity=polarity if polarity and polarity != "전체" else None,
+    )
+
+
+@st.cache_data(ttl=60)
+def get_feedback_stats(api_key: str = "", campaign_id: int = 0, access_token: str = ""):
+    """Fetch feedback statistics for a campaign."""
+    try:
+        client = ChainShiftClient(api_key=api_key or None, access_token=access_token or None)
+        return client.get_feedback_stats(campaign_id)
+    except Exception:
+        return None

core/export_utils.py

@@ -0,0 +1,216 @@
+"""
+Export Utilities - 통합 내보내기 컴포넌트
+
+공통 내보내기 기능을 제공합니다:
+- CSV/Excel 변환
+- 필터링 옵션
+- 전체 답변 포함 옵션
+"""
+
+import pandas as pd
+import streamlit as st
+from io import BytesIO
+from typing import Callable
+
+from .supabase_client import get_sentiment_data_for_export
+from .athena_client import fetch_full_answers_batch
+
+# openpyxl 설치 여부 확인 (Excel export용)
+try:
+    import openpyxl
+    EXCEL_AVAILABLE = True
+except ImportError:
+    EXCEL_AVAILABLE = False
+
+
+# LLM 검증 상태 라벨 (용어 통일)
+LLM_STATUS_LABELS = {
+    "all": "전체",
+    "verified": "검증완료",
+    "false_positive": "오탐 (부정→비부정)",  # 부정 아님
+    "true_negative": "정탐 (부정 확정)",      # 부정 확정
+    "unverified": "미검증",
+}
+
+POLARITY_LABELS = {
+    "all": "전체",
+    "negative": "부정",
+    "positive": "긍정",
+    "neutral": "중립",
+}
+
+
+def prepare_dataframe_for_export(
+    data: list[dict],
+    include_full_answers: bool = False,
+) -> pd.DataFrame:
+    """데이터를 DataFrame으로 변환하고 내보내기용으로 정리합니다.
+
+    Args:
+        data: 내보낼 데이터 리스트
+        include_full_answers: 전체 답변 포함 여부
+
+    Returns:
+        정리된 DataFrame
+    """
+    if not data:
+        return pd.DataFrame()
+
+    df = pd.DataFrame(data)
+
+    # 리스트 컬럼을 문자열로 변환
+    list_columns = ['in_house_brands', 'mentioned_brands', 'llm_evidence_spans']
+    for col in list_columns:
+        if col in df.columns:
+            df[col] = df[col].apply(
+                lambda x: ', '.join(x) if isinstance(x, list) else str(x) if x else ''
+            )
+
+    # 컬럼 순서 정리 - answer_full을 answer_preview 다음에 배치
+    if 'answer_full' in df.columns and 'answer_preview' in df.columns:
+        cols = list(df.columns)
+        cols.remove('answer_full')
+        idx = cols.index('answer_preview') + 1
+        cols.insert(idx, 'answer_full')
+        df = df[cols]
+
+    return df
+
+
+def export_to_csv(df: pd.DataFrame) -> bytes:
+    """DataFrame을 CSV 바이트로 변환합니다."""
+    return df.to_csv(index=False).encode('utf-8-sig')
+
+
+def export_to_excel(df: pd.DataFrame) -> bytes | None:
+    """DataFrame을 Excel 바이트로 변환합니다.
+
+    Returns:
+        Excel 바이트 데이터, 또는 openpyxl이 없으면 None
+    """
+    if not EXCEL_AVAILABLE:
+        return None
+    output = BytesIO()
+    with pd.ExcelWriter(output, engine='openpyxl') as writer:
+        df.to_excel(writer, index=False, sheet_name='Data')
+    return output.getvalue()
+
+
+def render_export_component(
+    campaign_id: int,
+    key_prefix: str,
+    title: str = "📥 데이터 내보내기",
+    show_polarity_filter: bool = True,
+    show_llm_filter: bool = True,
+    default_polarity: str = "negative",
+    default_llm_status: str = "all",
+    in_house_only: bool = True,
+):
+    """통합 내보내기 컴포넌트를 렌더링합니다.
+
+    Args:
+        campaign_id: 캠페인 ID
+        key_prefix: Streamlit 위젯 키 접두사 (중복 방지)
+        title: 섹션 제목
+        show_polarity_filter: 감정 필터 표시 여부
+        show_llm_filter: LLM 상태 필터 표시 여부
+        default_polarity: 기본 감정 필터 값
+        default_llm_status: 기본 LLM 상태 필터 값
+        in_house_only: 자사 브랜드만 필터링
+    """
+    with st.expander(title, expanded=False):
+        # 필터 옵션
+        filter_col1, filter_col2 = st.columns(2)
+
+        with filter_col1:
+            if show_polarity_filter:
+                polarity_options = list(POLARITY_LABELS.keys())
+                polarity_labels = list(POLARITY_LABELS.values())
+                default_idx = polarity_options.index(default_polarity) if default_polarity in polarity_options else 0
+                selected_polarity = st.selectbox(
+                    "감정 필터",
+                    options=polarity_options,
+                    format_func=lambda x: POLARITY_LABELS[x],
+                    index=default_idx,
+                    key=f"{key_prefix}_polarity"
+                )
+            else:
+                selected_polarity = default_polarity
+
+        with filter_col2:
+            if show_llm_filter:
+                llm_options = list(LLM_STATUS_LABELS.keys())
+                default_idx = llm_options.index(default_llm_status) if default_llm_status in llm_options else 0
+                selected_llm_status = st.selectbox(
+                    "LLM 검증 상태",
+                    options=llm_options,
+                    format_func=lambda x: LLM_STATUS_LABELS[x],
+                    index=default_idx,
+                    key=f"{key_prefix}_llm_status"
+                )
+            else:
+                selected_llm_status = default_llm_status
+
+        # 내보내기 옵션
+        opt_col1, opt_col2 = st.columns(2)
+        with opt_col1:
+            include_full_answers = st.checkbox(
+                "전체 답변 포함",
+                value=False,
+                help="Athena에서 전체 답변을 가져옵니다 (파일 크기 증가)",
+                key=f"{key_prefix}_full_answers"
+            )
+        with opt_col2:
+            include_evidence = st.checkbox(
+                "LLM 근거 포함",
+                value=False,
+                help="LLM 판단 근거(reasoning, evidence_spans)를 포함합니다",
+                key=f"{key_prefix}_evidence"
+            )
+
+        st.markdown("---")
+
+        # 다운로드 버튼
+        btn_col1, btn_col2, btn_col3 = st.columns([1, 1, 2])
+
+        # 데이터 가져오기
+        data = get_sentiment_data_for_export(
+            campaign_id=campaign_id,
+            polarity=selected_polarity if selected_polarity != "all" else None,
+            llm_status=selected_llm_status if selected_llm_status != "all" else None,
+            in_house_only=in_house_only,
+            include_full_answers=include_full_answers,
+            include_evidence=include_evidence,
+        )
+
+        if data:
+            df = prepare_dataframe_for_export(data, include_full_answers)
+            count = len(df)
+
+            with btn_col1:
+                csv_data = export_to_csv(df)
+                st.download_button(
+                    label=f"📥 CSV ({count}건)",
+                    data=csv_data,
+                    file_name=f"campaign_{campaign_id}_export_{count}건.csv",
+                    mime="text/csv",
+                    key=f"{key_prefix}_csv_download"
+                )
+
+            with btn_col2:
+                if EXCEL_AVAILABLE:
+                    excel_data = export_to_excel(df)
+                    st.download_button(
+                        label=f"📥 Excel ({count}건)",
+                        data=excel_data,
+                        file_name=f"campaign_{campaign_id}_export_{count}건.xlsx",
+                        mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                        key=f"{key_prefix}_excel_download"
+                    )
+                else:
+                    st.caption("Excel: openpyxl 필요")
+
+            with btn_col3:
+                st.caption(f"총 {count}건 | 필터: {POLARITY_LABELS.get(selected_polarity, '전체')} / {LLM_STATUS_LABELS.get(selected_llm_status, '전체')}")
+        else:
+            st.info("내보낼 데이터가 없습니다.")

core/job_realtime.py

@@ -0,0 +1,264 @@
+"""Sentiment Analysis Job 실시간 모니터링 (Phase 4.1)
+
+Usage:
+    from job_realtime import get_active_jobs, get_job_by_id
+
+    # 실행 중인 Job 목록
+    jobs = get_active_jobs(campaign_id=27)
+
+    # 특정 Job 상세
+    job = get_job_by_id("abc-123")
+
+Note:
+    Streamlit은 WebSocket을 직접 지원하지 않으므로,
+    st.rerun() 또는 st.cache_data(ttl=5)로 폴링 방식 사용
+"""
+
+import os
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+import streamlit as st
+from supabase import create_client, Client
+from dotenv import load_dotenv
+
+# Load environment variables (project root)
+_project_root = Path(__file__).parent.parent.parent.parent
+for _env_name in (".env.dev", ".env.prod"):
+    _env_path = _project_root / _env_name
+    if _env_path.exists():
+        load_dotenv(_env_path, override=True)
+        break
+
+
+@lru_cache()
+def _get_client() -> Client:
+    """Supabase 클라이언트 (캐시됨)"""
+    url = os.environ.get("SUPABASE_URL", "")
+    key = os.environ.get("SUPABASE_SERVICE_KEY", "")
+    if not url or not key:
+        raise ValueError("Missing SUPABASE_URL or SUPABASE_SERVICE_KEY")
+    return create_client(url, key)
+
+
+JobStatus = Literal["queued", "running", "completed", "failed", "cancelled"]
+
+
+@st.cache_data(ttl=5)
+def get_active_jobs(campaign_id: int | None = None, limit: int = 10) -> list[dict]:
+    """실행 중이거나 대기 중인 Job 목록 조회
+
+    Args:
+        campaign_id: 특정 캠페인만 필터링 (None이면 전체)
+        limit: 최대 결과 수
+
+    Returns:
+        Job 목록 (최신순 정렬)
+    """
+    client = _get_client()
+    query = client.table("sentiment_analysis_jobs").select(
+        "id, campaign_id, status, progress, message, "
+        "total_answers, processed_answers, nudge_candidates, "
+        "created_at, started_at, completed_at, error_message"
+    ).in_("status", ["queued", "running"])
+
+    if campaign_id:
+        query = query.eq("campaign_id", campaign_id)
+
+    query = query.order("created_at", desc=True).limit(limit)
+    result = query.execute()
+    return result.data or []
+
+
+@st.cache_data(ttl=5)
+def get_recent_jobs(
+    campaign_id: int | None = None,
+    status: JobStatus | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """최근 Job 목록 조회 (히스토리용)
+
+    Args:
+        campaign_id: 특정 캠페인만 필터링
+        status: 특정 상태만 필터링
+        limit: 최대 결과 수
+
+    Returns:
+        Job 목록 (최신순 정렬)
+    """
+    client = _get_client()
+    query = client.table("sentiment_analysis_jobs").select(
+        "id, campaign_id, status, progress, message, "
+        "total_answers, processed_answers, nudge_candidates, "
+        "created_at, started_at, completed_at, error_message"
+    )
+
+    if campaign_id:
+        query = query.eq("campaign_id", campaign_id)
+    if status:
+        query = query.eq("status", status)
+
+    query = query.order("created_at", desc=True).limit(limit)
+    result = query.execute()
+    return result.data or []
+
+
+def get_job_by_id(job_id: str) -> dict | None:
+    """특정 Job 상세 조회
+
+    Args:
+        job_id: Job ID
+
+    Returns:
+        Job 정보 또는 None
+    """
+    client = _get_client()
+    result = client.table("sentiment_analysis_jobs").select(
+        "id, campaign_id, status, progress, message, "
+        "total_answers, processed_answers, nudge_candidates, "
+        "created_at, started_at, completed_at, error_message"
+    ).eq("id", job_id).execute()
+    return result.data[0] if result.data else None
+
+
+def format_job_duration(job: dict) -> str:
+    """Job 소요 시간 포맷팅
+
+    Args:
+        job: Job 정보 dict
+
+    Returns:
+        "2시간 15분" 형태의 문자열
+    """
+    started_at = job.get("started_at")
+    completed_at = job.get("completed_at")
+
+    if not started_at:
+        return "-"
+
+    try:
+        # ISO 문자열 파싱
+        if isinstance(started_at, str):
+            start = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+        else:
+            start = started_at
+
+        if completed_at:
+            if isinstance(completed_at, str):
+                end = datetime.fromisoformat(completed_at.replace("Z", "+00:00"))
+            else:
+                end = completed_at
+        else:
+            end = datetime.now(timezone.utc)
+
+        seconds = int((end - start).total_seconds())
+
+        if seconds < 60:
+            return f"{seconds}초"
+        elif seconds < 3600:
+            return f"{seconds // 60}분"
+        else:
+            hours = seconds // 3600
+            minutes = (seconds % 3600) // 60
+            if minutes > 0:
+                return f"{hours}시간 {minutes}분"
+            return f"{hours}시간"
+    except Exception:
+        return "-"
+
+
+def get_status_emoji(status: str) -> str:
+    """Job 상태 이모지 반환"""
+    return {
+        "queued": "🟡",
+        "running": "🔵",
+        "completed": "🟢",
+        "failed": "🔴",
+        "cancelled": "⚪",
+    }.get(status, "⚪")
+
+
+def get_status_label(status: str) -> str:
+    """Job 상태 한글 라벨 반환"""
+    return {
+        "queued": "대기 중",
+        "running": "실행 중",
+        "processing": "처리 중",
+        "completed": "완료",
+        "failed": "실패",
+        "cancelled": "취소됨",
+    }.get(status, status)
+
+
+# ============================================================================
+# Hierarchy Analysis Jobs (hierarchy_analysis_jobs table)
+# ============================================================================
+
+_HIERARCHY_FIELDS = (
+    "id, user_id, prompt, title, status, progress, current_step, "
+    "created_at, started_at, completed_at, error_message"
+)
+
+_HIERARCHY_STEP_LABELS: dict[str, str] = {
+    "prompt_enhancement": "프롬프트 분석",
+    "query_generation": "쿼리 생성",
+    "keyword_data": "키워드 수집",
+    "hierarchy_generation": "계층 구조 생성",
+    "search_volume": "검색량 조회",
+    "question_generation": "질문 생성",
+    "ratio_supplement": "비율 보정",
+    "finalization": "최종 저장",
+    "done": "완료",
+}
+
+
+def get_hierarchy_step_label(step: str | None) -> str:
+    """Hierarchy 파이프라인 스텝 한글 라벨 반환"""
+    if not step:
+        return "대기 중"
+    return _HIERARCHY_STEP_LABELS.get(step, step)
+
+
+def get_active_hierarchy_jobs(user_id: str | None = None, limit: int = 5) -> list[dict]:
+    """실행 중이거나 대기 중인 Hierarchy Job 목록 (Supabase 직접 쿼리)
+
+    Args:
+        user_id: 사용자 ID로 필터링 (None이면 전체)
+        limit: 최대 결과 수
+    """
+    client = _get_client()
+    query = (
+        client.table("hierarchy_analysis_jobs")
+        .select(_HIERARCHY_FIELDS)
+        .in_("status", ["queued", "processing"])
+    )
+    if user_id:
+        query = query.eq("user_id", user_id)
+    query = query.order("created_at", desc=True).limit(limit)
+    result = query.execute()
+    return result.data or []
+
+
+def get_recent_hierarchy_jobs(
+    user_id: str | None = None,
+    status: str | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """최근 Hierarchy Job 이력 조회
+
+    Args:
+        user_id: 사용자 ID로 필터링
+        status: 특정 상태만 필터링
+        limit: 최대 결과 수
+    """
+    client = _get_client()
+    query = client.table("hierarchy_analysis_jobs").select(_HIERARCHY_FIELDS)
+    if user_id:
+        query = query.eq("user_id", user_id)
+    if status:
+        query = query.eq("status", status)
+    query = query.order("created_at", desc=True).limit(limit)
+    result = query.execute()
+    return result.data or []

core/styles.py

@@ -0,0 +1,93 @@
+"""CSS Styles for Streamlit Dashboard.
+
+Uses ChainShift Brand Colors (2026 Design System).
+Primary: Electric Indigo (#5041FF)
+Accent: Neo Aqua (#00D5B5)
+"""
+
+# ============================================================================
+# Brand Colors (synced with app/core/brand.py)
+# ============================================================================
+INDIGO_700 = "#5041FF"  # Primary
+INDIGO_800 = "#3E32CC"  # Primary Dark
+INDIGO_100 = "#E5E2FF"  # Primary Light BG
+AQUA_600 = "#00D5B5"    # Accent
+AQUA_100 = "#B8FFF6"    # Accent Light BG
+POSITIVE = "#10B981"    # Green
+NEGATIVE = "#EF4444"    # Red
+NEUTRAL = "#6B7280"     # Gray
+WARNING = "#F59E0B"     # Amber
+
+DASHBOARD_CSS = f"""
+<style>
+    .insight-card {{
+        background: linear-gradient(135deg, {INDIGO_800} 0%, {INDIGO_700} 100%);
+        padding: 20px;
+        border-radius: 12px;
+        color: white;
+        margin-bottom: 20px;
+    }}
+    .metric-positive {{ color: {POSITIVE}; font-weight: bold; }}
+    .metric-negative {{ color: {NEGATIVE}; font-weight: bold; }}
+    .metric-neutral {{ color: {NEUTRAL}; }}
+    .highlight-box {{
+        background: {AQUA_100};
+        border-left: 4px solid {AQUA_600};
+        padding: 15px;
+        margin: 10px 0;
+        border-radius: 0 8px 8px 0;
+    }}
+    .warning-box {{
+        background: #FEF2F2;
+        border-left: 4px solid {NEGATIVE};
+        padding: 15px;
+        margin: 10px 0;
+        border-radius: 0 8px 8px 0;
+    }}
+    .info-box {{
+        background: {INDIGO_100};
+        border-left: 4px solid {INDIGO_700};
+        padding: 15px;
+        margin: 10px 0;
+        border-radius: 0 8px 8px 0;
+    }}
+    .big-number {{
+        font-size: 48px;
+        font-weight: bold;
+        line-height: 1;
+        color: {INDIGO_700};
+    }}
+    .filter-section {{
+        background: #F8FAFC;
+        padding: 15px;
+        border-radius: 8px;
+        margin-bottom: 15px;
+    }}
+    /* Primary button style */
+    .stButton > button {{
+        background-color: {INDIGO_700};
+        color: white;
+        border: none;
+    }}
+    .stButton > button:hover {{
+        background-color: {INDIGO_800};
+    }}
+</style>
+"""
+
+# Tier color mapping for nudge candidates
+TIER_BORDER_COLORS = {
+    "HIGH": NEGATIVE,
+    "MEDIUM": WARNING,
+    "LOW": POSITIVE,
+}
+
+# Chart colors for Streamlit charts (plotly, altair)
+CHART_COLORS = [
+    INDIGO_700,   # Primary
+    AQUA_600,     # Accent
+    "#9585FF",    # Indigo 500
+    "#3DF1E7",    # Aqua 400
+    "#3E32CC",    # Indigo 800
+    "#06A68D",    # Aqua 700
+]

core/supabase_action_items.py

@@ -0,0 +1,206 @@
+"""Supabase action items & reports queries.
+
+Module-level functions extracted from supabase_client.py.
+All functions use get_supabase_client() from the parent module.
+"""
+import streamlit as st
+
+
+def get_action_items(
+    campaign_id: int,
+    status: str | None = None,
+    category: str | None = None,
+    page: int = 1,
+    page_size: int = 50,
+    order_by: str = "created_at",
+    desc: bool = True,
+) -> tuple[list[dict], int]:
+    """Get action items for a campaign with filters and sorting.
+
+    Args:
+        order_by: Column to sort by (created_at, priority, category, status)
+        desc: True for descending, False for ascending
+
+    Returns (items, total_count).
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+        query = (
+            client.table("action_items")
+            .select(
+                "id, campaign_id, trigger_rule_id, category, priority, label, "
+                "evidence, llm_recommendation, status, assignee_email, "
+                "created_at, completed_at",
+                count="planned",
+            )
+            .eq("campaign_id", campaign_id)
+        )
+        if status:
+            query = query.eq("status", status)
+        if category:
+            query = query.eq("category", category)
+
+        offset = (page - 1) * page_size
+        query = (
+            query.order(order_by, desc=desc)
+            .range(offset, offset + page_size - 1)
+        )
+        result = query.execute()
+        return result.data or [], result.count or 0
+    except Exception:
+        return [], 0
+
+
+@st.cache_data(ttl=60)
+def get_action_item_stats(campaign_id: int) -> dict:
+    """Get action item stats via RPC (COUNT FILTER pattern)."""
+    _empty = {"pending": 0, "in_progress": 0, "completed": 0, "archived": 0, "total": 0}
+    try:
+        from core.supabase_client import get_supabase_client
+
+        client = get_supabase_client()
+        result = client.rpc(
+            "get_action_item_stats", {"p_campaign_id": campaign_id}
+        ).execute()
+        data = result.data
+        if isinstance(data, list) and data:
+            data = data[0]
+        if isinstance(data, str):
+            import json
+            data = json.loads(data)
+        return data if isinstance(data, dict) else _empty
+    except Exception:
+        return _empty
+
+
+def update_action_item_status(item_id: str, new_status: str) -> bool:
+    """Update action item status. Returns True on success."""
+    try:
+        from core.supabase_client import get_supabase_client
+
+        client = get_supabase_client()
+        result = (
+            client.table("action_items")
+            .update({"status": new_status})
+            .eq("id", item_id)
+            .execute()
+        )
+        return bool(result.data)
+    except Exception:
+        return False
+
+
+def delete_action_item(item_id: str) -> bool:
+    """Delete action item. Returns True on success."""
+    try:
+        from core.supabase_client import get_supabase_client
+
+        client = get_supabase_client()
+        result = (
+            client.table("action_items")
+            .delete()
+            .eq("id", item_id)
+            .execute()
+        )
+        return bool(result.data)
+    except Exception:
+        return False
+
+
+def save_action_items_batch(
+    campaign_id: int,
+    user_id: str,
+    items: list[dict],
+    report_id: str | None = None,
+) -> dict:
+    """Save action items with dedup (check existing active items).
+
+    Args:
+        campaign_id: Campaign ID
+        user_id: User UUID
+        items: List of dicts with trigger_rule_id, category, priority, label, evidence
+        report_id: Optional report UUID
+
+    Returns:
+        {"created": N, "skipped": N}
+    """
+    try:
+        from core.supabase_client import get_supabase_client
+
+        client = get_supabase_client()
+
+        # Batch dedup check: single query instead of N queries
+        trigger_ids = [item["trigger_rule_id"] for item in items]
+        existing_result = (
+            client.table("action_items")
+            .select("trigger_rule_id")
+            .eq("campaign_id", campaign_id)
+            .in_("trigger_rule_id", trigger_ids)
+            .in_("status", ["pending", "in_progress"])
+            .execute()
+        )
+        existing_set = {r["trigger_rule_id"] for r in (existing_result.data or [])}
+
+        rows_to_insert = []
+        skipped = 0
+        for item in items:
+            if item["trigger_rule_id"] in existing_set:
+                skipped += 1
+                continue
+            rows_to_insert.append({
+                "campaign_id": campaign_id,
+                "user_id": user_id,
+                "report_id": report_id,
+                "trigger_rule_id": item["trigger_rule_id"],
+                "category": item["category"],
+                "priority": item["priority"],
+                "label": item["label"],
+                "evidence": item.get("evidence"),
+                "llm_recommendation": item.get("llm_recommendation"),
+                "status": "pending",
+            })
+
+        created = 0
+        if rows_to_insert:
+            client.table("action_items").insert(rows_to_insert).execute()
+            created = len(rows_to_insert)
+
+        return {"created": created, "skipped": skipped}
+    except Exception as e:
+        return {"created": 0, "skipped": 0, "error": str(e)}
+
+
+def get_campaign_date_range(campaign_id: int) -> tuple[str, str] | None:
+    """Get first and last data dates for a campaign via RPC (single query).
+
+    Returns:
+        Tuple of (first_date, last_date) as strings, or None if no data
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    result = client.rpc("get_campaign_date_range_agg", {"p_campaign_id": campaign_id}).execute()
+
+    data = result.data
+    # PostgREST may wrap json return as [dict] or dict
+    if isinstance(data, list) and data:
+        data = data[0]
+    if isinstance(data, dict) and data.get("first_date") and data.get("last_date"):
+        return (data["first_date"], data["last_date"])
+    return None
+
+
+def get_report_history_count(campaign_id: int) -> int:
+    """Get total count of generated HTML reports for a campaign."""
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    result = (
+        client.table("html_reports")
+        .select("id", count="planned")
+        .eq("campaign_id", campaign_id)
+        .execute()
+    )
+    return result.count or 0

core/supabase_client.py

@@ -0,0 +1,76 @@
+"""Supabase client for dashboard - direct queries for LLM verification data.
+
+Domain queries are in separate modules:
+- supabase_sentiment.py: Overview, LLM verification, polarity
+- supabase_research.py: Topic clusters, cross-model analysis
+- supabase_action_items.py: Action items CRUD, reports, date range
+"""
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from supabase import create_client, Client
+from dotenv import load_dotenv
+
+# Load environment variables (project root)
+_project_root = Path(__file__).parent.parent.parent.parent
+for _env_name in (".env.dev", ".env.prod"):
+    _env_path = _project_root / _env_name
+    if _env_path.exists():
+        load_dotenv(_env_path, override=True)
+        break
+
+
+@lru_cache()
+def get_supabase_client() -> Client:
+    """Create Supabase client for unified database.
+
+    Uses service_role key (bypasses RLS) because the dashboard is an
+    internal admin tool that needs cross-campaign analytics.
+    DO NOT use this client in user-facing API routes.
+    """
+    url = os.environ.get("SUPABASE_URL", "")
+    key = os.environ.get("SUPABASE_SERVICE_KEY", "")
+    if not url or not key:
+        raise ValueError("Missing SUPABASE_URL or SUPABASE_SERVICE_KEY")
+    return create_client(url, key)
+
+
+# ============================================================================
+# Re-exports for backward compatibility
+# All consumers import from core.supabase_client — these re-exports
+# ensure existing imports continue to work unchanged.
+# ============================================================================
+
+# Sentiment / Overview / LLM Verification
+from core.supabase_sentiment import (  # noqa: E402, F401
+    get_campaign_overview,
+    get_llm_verification_stats,
+    get_false_positives,
+    get_true_negatives,
+    get_llm_verified_for_export,
+    get_sentiment_data_for_export,
+    get_answers_by_polarity,
+    get_polarity_stats,
+)
+
+# Research / Topics
+from core.supabase_research import (  # noqa: E402, F401
+    get_topic_clusters,
+    get_topic_map_snapshot,
+    get_cross_model_analysis,
+    get_gap_scores,
+    find_cross_model_pair,
+)
+
+# Action Items / Reports
+from core.supabase_action_items import (  # noqa: E402, F401
+    get_action_items,
+    get_action_item_stats,
+    update_action_item_status,
+    delete_action_item,
+    save_action_items_batch,
+    get_campaign_date_range,
+    get_report_history_count,
+)

core/supabase_research.py

@@ -0,0 +1,153 @@
+"""Supabase research queries — topic clusters, cross-model analysis.
+
+Module-level functions extracted from supabase_client.py.
+All functions use get_supabase_client() from the parent module.
+"""
+
+
+def get_topic_clusters(campaign_id: int, source: str | None = None) -> list[dict]:
+    """Fetch topic clusters with scores for a campaign, optionally filtered by source.
+
+    Returns:
+        List of cluster dicts sorted by opportunity_score DESC.
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    query = (
+        client.table("topic_clusters")
+        .select(
+            "id, cluster_label, fanout_count, unique_questions, "
+            "attention_score, citation_density, opportunity_score, "
+            "sample_fanouts, top_sources, source"
+        )
+        .eq("campaign_id", campaign_id)
+    )
+    if source:
+        query = query.eq("source", source)
+    result = query.order("opportunity_score", desc=True).execute()
+    return result.data or []
+
+
+def get_topic_map_snapshot(campaign_id: int, source: str | None = None) -> dict | None:
+    """Fetch latest UMAP 2D coordinates for visualization.
+
+    Returns:
+        Dict with coordinates and algorithm_params, or None.
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    result = (
+        client.table("topic_map_snapshots")
+        .select("coordinates, algorithm_params")
+        .eq("campaign_id", campaign_id)
+        .order("created_at", desc=True)
+        .execute()
+    )
+    if not result.data:
+        return None
+    if source:
+        for snap in result.data:
+            params = snap.get("algorithm_params") or {}
+            if params.get("source") == source:
+                return snap
+        return None
+    return result.data[0]
+
+
+def get_cross_model_analysis(
+    campaign_chatgpt: int,
+    campaign_gemini: int,
+) -> dict | None:
+    """Fetch cross-model analysis summary (NMI, match count).
+
+    Returns:
+        Dict with nmi_score, total_matched_topics, algorithm_params, or None.
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    result = (
+        client.table("cross_model_analysis")
+        .select("nmi_score, total_matched_topics, algorithm_params, created_at")
+        .eq("campaign_chatgpt", campaign_chatgpt)
+        .eq("campaign_gemini", campaign_gemini)
+        .limit(1)
+        .execute()
+    )
+    return result.data[0] if result.data else None
+
+
+def get_gap_scores(
+    campaign_chatgpt: int,
+    campaign_gemini: int,
+) -> list[dict]:
+    """Fetch cross-model topic matches with GapScore and quadrant.
+
+    Returns:
+        List of match dicts with cluster labels, sorted by gap_score DESC.
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    result = (
+        client.table("cross_model_topic_matches")
+        .select(
+            "id, chatgpt_cluster_id, gemini_cluster_id, "
+            "match_score, label_similarity, centroid_similarity, "
+            "demand_percentile, supply_percentile, gap_score, quadrant"
+        )
+        .eq("campaign_chatgpt", campaign_chatgpt)
+        .eq("campaign_gemini", campaign_gemini)
+        .not_.is_("gap_score", "null")
+        .order("gap_score", desc=True)
+        .execute()
+    )
+    matches = result.data or []
+
+    # Enrich with cluster labels (batch query instead of N+1)
+    if matches:
+        chatgpt_ids = [m["chatgpt_cluster_id"] for m in matches]
+        gemini_ids = [m["gemini_cluster_id"] for m in matches]
+        all_ids = list(set(chatgpt_ids + gemini_ids))
+
+        label_map = {}
+        label_result = (
+            client.table("topic_clusters")
+            .select("id, cluster_label")
+            .in_("id", all_ids)
+            .execute()
+        )
+        for row in (label_result.data or []):
+            label_map[row["id"]] = row.get("cluster_label", "")
+
+        for m in matches:
+            m["chatgpt_label"] = label_map.get(m["chatgpt_cluster_id"], "")
+            m["gemini_label"] = label_map.get(m["gemini_cluster_id"], "")
+
+    return matches
+
+
+def find_cross_model_pair(campaign_id: int) -> dict | None:
+    """Find cross-model analysis pair containing this campaign_id.
+
+    Checks both chatgpt and gemini sides so the sidebar only needs one ID.
+
+    Returns:
+        Dict with campaign_chatgpt, campaign_gemini, nmi_score,
+        total_matched_topics, or None if no pair exists.
+    """
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    resp = (
+        client.table("cross_model_analysis")
+        .select("campaign_chatgpt, campaign_gemini, nmi_score, total_matched_topics")
+        .or_(f"campaign_chatgpt.eq.{campaign_id},campaign_gemini.eq.{campaign_id}")
+        .limit(1)
+        .execute()
+    )
+    if resp.data:
+        return resp.data[0]
+    return None

core/supabase_sentiment.py

@@ -0,0 +1,373 @@
+"""Supabase sentiment queries — overview, LLM verification, polarity.
+
+Module-level functions extracted from supabase_client.py.
+All functions use get_supabase_client() from the parent module.
+"""
+import logging
+import streamlit as st
+
+logger = logging.getLogger(__name__)
+
+
+def get_campaign_overview(campaign_id: int) -> dict:
+    """Get comprehensive overview stats for a campaign via single RPC call.
+
+    Uses get_campaign_overview_agg() RPC which performs COUNT(*) FILTER
+    in a single table scan instead of 6 separate count queries.
+
+    Returns:
+        Dict with total_answers, in_house_negative_count, llm_verified_total,
+        llm_verified_in_house, llm_pending, llm_confirmed_negative.
+        Returns zeroed dict on DB error for graceful degradation.
+    """
+    from core.supabase_client import get_supabase_client
+
+    _empty = {
+        "total_answers": 0,
+        "in_house_negative_count": 0,
+        "llm_verified_total": 0,
+        "llm_verified_in_house": 0,
+        "llm_pending": 0,
+        "llm_confirmed_negative": 0,
+    }
+    try:
+        client = get_supabase_client()
+        result = client.rpc(
+            "get_campaign_overview_agg", {"p_campaign_id": campaign_id}
+        ).execute()
+        data = result.data
+        # RPC may return list-wrapped or JSON string depending on PostgREST
+        if isinstance(data, list) and data:
+            data = data[0]
+        if isinstance(data, str):
+            import json
+            data = json.loads(data)
+        return data if (isinstance(data, dict) and data) else _empty
+    except Exception:
+        return _empty
+
+
+def get_llm_verification_stats(
+    campaign_id: int,
+    in_house_only: bool = True,
+) -> dict:
+    """Get LLM verification statistics via single RPC (avoids VIEW timeout).
+
+    Uses get_campaign_sentiment_stats RPC — one table scan with COUNT FILTER.
+
+    Args:
+        campaign_id: Campaign ID
+        in_house_only: If True, only count in-house brand negatives (default)
+
+    Returns:
+        Dict with total_verified, false_positives, true_negatives counts
+    """
+    from core.supabase_client import get_supabase_client
+
+    _empty = {"total_verified": 0, "false_positives": 0, "true_negatives": 0}
+    try:
+        client = get_supabase_client()
+        result = client.rpc(
+            "get_campaign_sentiment_stats", {"p_campaign_id": campaign_id}
+        ).execute()
+        stats = result.data or {}
+        if isinstance(stats, list) and stats:
+            stats = stats[0]
+        if isinstance(stats, str):
+            import json
+            stats = json.loads(stats)
+        if not isinstance(stats, dict):
+            return _empty
+
+        if in_house_only:
+            return {
+                "total_verified": stats.get("in_house_llm_verified", 0),
+                "false_positives": stats.get("in_house_llm_false_pos", 0),
+                "true_negatives": stats.get("in_house_llm_true_neg", 0),
+            }
+        return {
+            "total_verified": stats.get("llm_verified", 0),
+            "false_positives": stats.get("llm_false_positive", 0),
+            "true_negatives": stats.get("llm_true_negative", 0),
+        }
+    except Exception:
+        return _empty
+
+
+@st.cache_data(ttl=60)
+def get_false_positives(
+    campaign_id: int,
+    page: int = 1,
+    page_size: int = 50,
+    in_house_only: bool = True,
+) -> tuple[list[dict], int]:
+    """Get false positive items via RPC (avoids VIEW timeout).
+
+    Returns:
+        Tuple of (items list, total count)
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+        result = client.rpc("get_nudge_export_data", {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": in_house_only,
+            "p_llm_verified_only": True,
+            "p_llm_is_negative": False,
+            "p_limit": 50000,
+        }).execute()
+        data = result.data or {}
+        rows = data.get("rows", []) if isinstance(data, dict) else []
+        total = data.get("total", len(rows)) if isinstance(data, dict) else len(rows)
+
+        # Sort by llm_verified_at DESC (RPC sorts by analyzed_at)
+        rows.sort(key=lambda r: r.get("llm_verified_at") or "", reverse=True)
+
+        # Client-side pagination
+        offset = (page - 1) * page_size
+        return rows[offset:offset + page_size], total
+    except Exception as e:
+        logger.warning("get_false_positives failed for campaign %s: %s", campaign_id, e)
+        return [], 0
+
+
+@st.cache_data(ttl=60)
+def get_true_negatives(
+    campaign_id: int,
+    page: int = 1,
+    page_size: int = 50,
+    in_house_only: bool = True,
+) -> tuple[list[dict], int]:
+    """Get true negative items via RPC (avoids VIEW timeout).
+
+    Returns:
+        Tuple of (items list, total count)
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+        result = client.rpc("get_nudge_export_data", {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": in_house_only,
+            "p_llm_verified_only": True,
+            "p_llm_is_negative": True,
+            "p_limit": 50000,
+        }).execute()
+        data = result.data or {}
+        rows = data.get("rows", []) if isinstance(data, dict) else []
+        total = data.get("total", len(rows)) if isinstance(data, dict) else len(rows)
+
+        # Sort by llm_verified_at DESC (RPC sorts by analyzed_at)
+        rows.sort(key=lambda r: r.get("llm_verified_at") or "", reverse=True)
+
+        # Client-side pagination
+        offset = (page - 1) * page_size
+        return rows[offset:offset + page_size], total
+    except Exception as e:
+        logger.warning("get_true_negatives failed for campaign %s: %s", campaign_id, e)
+        return [], 0
+
+
+def get_llm_verified_for_export(
+    campaign_id: int,
+    is_negative: bool,
+    in_house_only: bool = True,
+    include_full_answers: bool = False,
+) -> list[dict]:
+    """Get all LLM verified items for export via single RPC (avoids VIEW timeout).
+
+    Returns:
+        List of items with optional full answer text
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+        result = client.rpc("get_nudge_export_data", {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": in_house_only,
+            "p_llm_verified_only": True,
+            "p_llm_is_negative": is_negative,
+            "p_limit": 50000,
+        }).execute()
+        data = result.data or {}
+        items = data.get("rows", []) if isinstance(data, dict) else []
+
+        # Fetch full answers from Athena if requested
+        if include_full_answers and items:
+            from .athena_client import fetch_full_answers_batch
+            answer_ids = [item["answer_id"] for item in items if item.get("answer_id")]
+            if answer_ids:
+                full_answers = fetch_full_answers_batch(answer_ids)
+                for item in items:
+                    aid = item.get("answer_id")
+                    if aid and aid in full_answers:
+                        item["answer_full"] = full_answers[aid]
+                    else:
+                        item["answer_full"] = item.get("answer_preview", "")
+
+        return items
+    except Exception as e:
+        logger.warning("get_llm_verified_for_export failed for campaign %s: %s", campaign_id, e)
+        return []
+
+
+def get_sentiment_data_for_export(
+    campaign_id: int,
+    polarity: str | None = None,
+    llm_status: str | None = None,
+    in_house_only: bool = True,
+    include_full_answers: bool = False,
+    include_evidence: bool = False,
+) -> list[dict]:
+    """Export sentiment data via RPC (avoids VIEW timeout on large campaigns).
+
+    Uses get_nudge_export_data RPC with inline CTE — WHERE campaign_id
+    is applied before DISTINCT ON, enabling index scan instead of full
+    VIEW materialization.
+
+    Args:
+        campaign_id: Campaign ID
+        polarity: Polarity filter ('negative', 'positive', 'neutral', None=all)
+        llm_status: LLM status filter ('verified', 'false_positive', 'true_negative', 'unverified', None=all)
+        in_house_only: In-house brand filter
+        include_full_answers: Include full answer text from Athena
+        include_evidence: Include LLM evidence fields
+
+    Returns:
+        Filtered data list
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+
+        # Map llm_status to RPC parameters
+        llm_verified_only = llm_status in ("verified", "false_positive", "true_negative")
+        llm_is_negative = None
+        if llm_status == "true_negative":
+            llm_is_negative = True
+        elif llm_status == "false_positive":
+            llm_is_negative = False
+
+        params = {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": in_house_only,
+            "p_llm_verified_only": llm_verified_only,
+            "p_llm_is_negative": llm_is_negative,
+            "p_limit": 50000,
+        }
+
+        result = client.rpc("get_nudge_export_data", params).execute()
+        data = result.data or {}
+        if isinstance(data, dict):
+            items = data.get("rows", []) or []
+        else:
+            items = data if isinstance(data, list) else []
+
+        # Apply polarity filter (kept client-side for simplicity)
+        if polarity:
+            items = [item for item in items if item.get("overall_polarity") == polarity]
+
+        # Apply unverified filter (RPC only supports verified=True)
+        if llm_status == "unverified":
+            items = [item for item in items if not item.get("llm_verified")]
+
+        if include_full_answers and items:
+            from .athena_client import fetch_full_answers_batch
+            answer_ids = [item["answer_id"] for item in items if item.get("answer_id")]
+            if answer_ids:
+                full_answers = fetch_full_answers_batch(answer_ids)
+                for item in items:
+                    aid = item.get("answer_id")
+                    if aid and aid in full_answers:
+                        item["answer_full"] = full_answers[aid]
+                    else:
+                        item["answer_full"] = item.get("answer_preview", "")
+
+        return items
+    except Exception as e:
+        logger.warning("get_sentiment_data_for_export failed for campaign %s: %s", campaign_id, e)
+        return []
+
+
+@st.cache_data(ttl=60)
+def get_answers_by_polarity(
+    campaign_id: int,
+    polarity: str,
+    page: int = 1,
+    page_size: int = 50,
+    in_house_only: bool = False,
+) -> tuple[list[dict], int]:
+    """Get answers filtered by polarity via RPC (avoids VIEW timeout).
+
+    Returns:
+        Tuple of (items list, total count)
+    """
+    from core.supabase_client import get_supabase_client
+
+    try:
+        client = get_supabase_client()
+        offset = (page - 1) * page_size
+
+        params: dict = {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": False,
+            "p_polarity": polarity,
+            "p_offset": offset,
+            "p_limit": page_size,
+        }
+        if in_house_only:
+            params["p_has_in_house_brands"] = True
+
+        result = client.rpc("get_nudge_export_data", params).execute()
+        data = result.data or {}
+        rows = data.get("rows", []) if isinstance(data, dict) else []
+        total = data.get("total", len(rows)) if isinstance(data, dict) else len(rows)
+
+        return rows, total
+    except Exception as e:
+        logger.warning("get_answers_by_polarity failed for campaign %s: %s", campaign_id, e)
+        return [], 0
+
+
+def get_polarity_stats(campaign_id: int, in_house_only: bool = False) -> dict:
+    """Get polarity distribution via single RPC (avoids VIEW timeout).
+
+    Uses get_campaign_sentiment_stats RPC — one table scan with COUNT FILTER.
+
+    Returns:
+        Dict with positive, neutral, negative counts
+    """
+    from core.supabase_client import get_supabase_client
+
+    _empty = {"positive": 0, "neutral": 0, "negative": 0}
+    try:
+        client = get_supabase_client()
+        result = client.rpc(
+            "get_campaign_sentiment_stats", {"p_campaign_id": campaign_id}
+        ).execute()
+        stats = result.data or {}
+        if isinstance(stats, list) and stats:
+            stats = stats[0]
+        if isinstance(stats, str):
+            import json
+            stats = json.loads(stats)
+        if not isinstance(stats, dict):
+            return _empty
+
+        if in_house_only:
+            return {
+                "positive": stats.get("in_house_positive", 0),
+                "neutral": stats.get("in_house_neutral", 0),
+                "negative": stats.get("in_house_negative_polarity", 0),
+            }
+        return {
+            "positive": stats.get("positive", 0),
+            "neutral": stats.get("neutral", 0),
+            "negative": stats.get("negative", 0),
+        }
+    except Exception:
+        return _empty

core/utils.py

@@ -0,0 +1,143 @@
+"""Utility functions for Gen3 Nudge Detection Dashboard."""
+
+# Confidence tier thresholds
+CONFIDENCE_HIGH_THRESHOLD = 0.85
+CONFIDENCE_MEDIUM_THRESHOLD = 0.70
+
+
+def get_confidence_tier(confidence: float | None) -> tuple[str, str, str]:
+    """Get confidence tier info for nudge candidates.
+
+    Returns:
+        Tuple of (tier, emoji, description)
+    """
+    if confidence is None:
+        return "LOW", "🟢", "오탐 가능성"
+    if confidence >= CONFIDENCE_HIGH_THRESHOLD:
+        return "HIGH", "🔴", "확실한 넛지 대상"
+    elif confidence >= CONFIDENCE_MEDIUM_THRESHOLD:
+        return "MEDIUM", "🟡", "검토 필요"
+    return "LOW", "🟢", "오탐 가능성"
+
+
+def truncate_text(text: str | None, max_length: int, suffix: str = "...") -> str:
+    """Truncate text to max_length with suffix."""
+    if not text:
+        return "N/A"
+    if len(text) <= max_length:
+        return text
+    return text[:max_length] + suffix
+
+
+def format_brands_list(brands: list[str] | None) -> str:
+    """Format list of brands for display."""
+    if not brands:
+        return "N/A"
+    return ", ".join(brands)
+
+
+def highlight_evidence_spans(text: str, evidence_spans: list[dict] | None) -> str:
+    """Highlight evidence spans in text using HTML.
+
+    Args:
+        text: Full answer text
+        evidence_spans: List of evidence span dicts with text, start, end, type
+
+    Returns:
+        HTML string with highlighted spans
+    """
+    if not evidence_spans or not text:
+        return text or ""
+
+    # Sort spans by start position (descending) to avoid index shifting
+    sorted_spans = sorted(
+        [s for s in evidence_spans if s.get("text")],
+        key=lambda s: s.get("start", 0) if s.get("start") is not None else -1,
+        reverse=True,
+    )
+
+    result = text
+    for span in sorted_spans:
+        span_text = span.get("text", "")
+        span_type = span.get("type", "negative")
+        start = span.get("start")
+        end = span.get("end")
+
+        # Color by type
+        color_map = {
+            "negative": "#FF6B6B",
+            "positive": "#51CF66",
+            "neutral": "#748FFC",
+            "comparison": "#FAB005",
+            "hallucination": "#ADB5BD",
+            "category_general": "#9775FA",
+        }
+        color = color_map.get(span_type, "#ADB5BD")
+
+        mark_style = f'background-color: {color}; padding: 2px 4px; border-radius: 3px;'
+
+        mark_style = f'background-color: {color}; padding: 2px 4px; border-radius: 3px;'
+
+        if start is not None and end is not None and 0 <= start < end <= len(result):
+            # Use exact positions
+            before = result[:start]
+            highlighted = f'<mark style="{mark_style}">{result[start:end]}</mark>'
+            after = result[end:]
+            result = before + highlighted + after
+        elif span_text and span_text in result:
+            # Fallback: find text in result
+            highlighted = f'<mark style="{mark_style}">{span_text}</mark>'
+            result = result.replace(span_text, highlighted, 1)
+        elif span_text and "..." in span_text:
+            # Ellipsis fallback: LLM truncated the evidence with "..."
+            # Split into fragments and highlight each one found in the text
+            fragments = [f.strip() for f in span_text.split("...") if f.strip()]
+            for frag in fragments:
+                if frag in result:
+                    highlighted = f'<mark style="{mark_style}">{frag}</mark>'
+                    result = result.replace(frag, highlighted, 1)
+
+    return result
+
+
+def get_llm_tier_badge(adjusted_tier: str | None, is_negative: bool | None) -> tuple[str, str]:
+    """Get badge info for LLM verification result.
+
+    Returns:
+        Tuple of (badge_text, badge_color)
+    """
+    if adjusted_tier is None:
+        return "미검증", "gray"
+
+    if adjusted_tier == "NONE" or is_negative is False:
+        return "✅ 오탐 (False Positive)", "green"
+
+    tier_map = {
+        "HIGH": ("🔴 부정 확인 (HIGH)", "red"),
+        "MEDIUM": ("🟡 부정 확인 (MEDIUM)", "orange"),
+        "LOW": ("🟢 부정 확인 (LOW)", "blue"),
+    }
+    return tier_map.get(adjusted_tier, ("확인됨", "gray"))
+
+
+def get_feedback_reason_label(reason: str | None) -> str:
+    """Get human-readable label for feedback wrong_reason."""
+    reason_labels = {
+        "actually_positive": "실제로는 긍정적인 내용입니다",
+        "actually_neutral": "실제로는 중립적인 내용입니다",
+        "wrong_evidence": "근거 문장이 잘못 추출되었습니다",
+        "context_missing": "맥락이 빠져서 오해가 있습니다",
+        "wrong_brand": "브랜드가 잘못 인식되었습니다",
+        "other": "기타",
+    }
+    return reason_labels.get(reason, reason or "")
+
+
+def get_feedback_type_emoji(feedback_type: str | None) -> str:
+    """Get emoji for feedback type."""
+    emoji_map = {
+        "correct": "👍",
+        "wrong": "👎",
+        "ambiguous": "🤔",
+    }
+    return emoji_map.get(feedback_type, "")

features/__init__.py

@@ -0,0 +1,4 @@
+"""Feature plugins package.
+
+각 하위 디렉토리에 FEATURE_CONFIG + render(base_ctx)가 있으면 자동 등록됨.
+"""

features/action_items/__init__.py

@@ -0,0 +1,24 @@
+"""액션아이템 Feature Plugin.
+
+API: /api/v1/action-items
+ADR-018 Phase 2: DB 상태관리
+독립 트리거 분석: 리포트 없이 직접 트리거 평가 → 저장
+"""
+import streamlit as st
+
+from . import overview
+
+FEATURE_CONFIG = {
+    "key": "action_items",
+    "name": "액션아이템",
+    "icon": "✅",
+    "description": "트리거 분석 + 액션아이템 관리 (상태 추적, 담당자 배정)",
+    "api_base": "/api/v1/action-items",
+    "order": 4,
+}
+
+
+def render(base_ctx):
+    """액션아이템 feature 렌더링."""
+    st.caption("14개 트리거 규칙으로 신호를 탐지하고 액션아이템으로 관리합니다")
+    overview.render(base_ctx)

features/action_items/analysis.py

@@ -0,0 +1,131 @@
+"""Trigger analysis section — date picker, run, preview, save.
+
+Separated from overview.py so that CRUD operations work even when
+trigger_rules module is unavailable (e.g., standalone HuggingFace Space).
+"""
+from datetime import date, timedelta
+
+import streamlit as st
+
+from core.supabase_client import (
+    get_campaign_date_range,
+    save_action_items_batch,
+)
+from .triggers import TRIGGERS_AVAILABLE
+from .utils import priority_level, CATEGORY_CONFIG
+
+
+def render_analysis_section(campaign_id: int, base_ctx: dict):
+    """Render trigger analysis: date picker, run button, preview, save."""
+    with st.expander("🔍 트리거 분석 실행", expanded=True):
+        if not TRIGGERS_AVAILABLE:
+            st.info(
+                "트리거 분석 기능을 사용할 수 없습니다. "
+                "전체 프로젝트 환경에서만 지원됩니다."
+            )
+            return
+
+        # Date range
+        date_range = get_campaign_date_range(campaign_id)
+        if not date_range:
+            st.info("캠페인 데이터가 아직 동기화되지 않았습니다.")
+            return
+
+        _, last_date_str = date_range
+        last_date = date.fromisoformat(last_date_str)
+        default_start = last_date - timedelta(days=6)
+
+        date_cols = st.columns(2)
+        with date_cols[0]:
+            start_date = st.date_input(
+                "시작일",
+                value=default_start,
+                key="ai_trigger_start",
+            )
+        with date_cols[1]:
+            end_date = st.date_input(
+                "종료일",
+                value=last_date,
+                key="ai_trigger_end",
+            )
+
+        if st.button("🔍 분석 실행", key="ai_run_triggers", type="primary", use_container_width=True):
+            with st.spinner("14개 트리거 규칙을 평가 중..."):
+                try:
+                    from .triggers import evaluate_triggers
+
+                    results = evaluate_triggers(
+                        campaign_id,
+                        start_date.isoformat(),
+                        end_date.isoformat(),
+                    )
+                    st.session_state["ai_trigger_results"] = results
+                except Exception as e:
+                    st.error(f"분석 오류: {e}")
+                    return
+
+        # Show results if available
+        results = st.session_state.get("ai_trigger_results")
+        if results is None:
+            return
+
+        if not results:
+            st.success("모든 지표가 정상 범위입니다. 탐지된 신호가 없습니다.")
+            return
+
+        st.markdown(f"**{len(results)}개 신호 탐지됨**")
+
+        # Preview cards
+        for item in results:
+            p_label, p_color, p_bg = priority_level(item["priority"])
+            cat_cfg = CATEGORY_CONFIG.get(item["category"], {"color": "#666", "icon": "📌"})
+            st.markdown(f"""
+            <div style="background:#FAFAFA;border:1px solid #E5E7EB;border-radius:8px;
+                        padding:12px;margin-bottom:8px;border-left:3px solid {p_color}">
+                <div style="display:flex;gap:8px;align-items:center;margin-bottom:6px">
+                    <span style="background:{p_bg};color:{p_color};padding:1px 8px;
+                          border-radius:10px;font-size:11px;font-weight:600">{p_label}</span>
+                    <span style="font-size:11px;color:{cat_cfg['color']}">{cat_cfg['icon']} {item['category']}</span>
+                </div>
+                <div style="font-size:14px;font-weight:600;color:#1F2937;margin-bottom:4px">{item['label']}</div>
+                <div style="font-size:12px;color:#6B7280">{item.get('evidence', '')}</div>
+            </div>
+            """, unsafe_allow_html=True)
+
+        # Save button
+        if st.button("💾 액션아이템으로 저장", key="ai_save_triggers", use_container_width=True):
+            _save_trigger_results(campaign_id, results, base_ctx)
+
+
+def _save_trigger_results(campaign_id: int, results: list[dict], base_ctx: dict):
+    """Save trigger analysis results as action items."""
+    try:
+        from core.supabase_client import get_supabase_client
+
+        user_client = get_supabase_client()
+        key_result = (
+            user_client.table("api_keys")
+            .select("user_id")
+            .limit(1)
+            .execute()
+        )
+        user_id = str(key_result.data[0]["user_id"]) if key_result.data else "unknown"
+
+        result = save_action_items_batch(
+            campaign_id=campaign_id,
+            user_id=user_id,
+            items=results,
+        )
+
+        created = result.get("created", 0)
+        skipped = result.get("skipped", 0)
+        if result.get("error"):
+            st.error(f"저장 오류: {result['error']}")
+        elif created > 0:
+            st.success(f"✅ {created}개 저장 완료 (중복 {skipped}개 스킵)")
+            st.session_state.pop("ai_trigger_results", None)
+            st.rerun()
+        else:
+            st.info(f"모든 항목이 이미 존재합니다 ({skipped}개 스킵)")
+    except Exception as e:
+        st.error(f"저장 실패: {e}")

features/action_items/overview.py

@@ -0,0 +1,339 @@
+"""Action Items overview — card-based UI with stats, filters, and inline editing."""
+import re
+from datetime import date, timedelta
+
+import streamlit as st
+
+from core.supabase_client import (
+    get_action_items,
+    get_action_item_stats,
+    update_action_item_status,
+    delete_action_item,
+    get_campaign_date_range,
+)
+from .analysis import render_analysis_section
+from .trend_charts import (
+    render_visibility_trend,
+    render_citation_type_trend,
+    render_negative_rate_trend,
+    render_action_items_history,
+)
+from .utils import (
+    STATUS_CONFIG,
+    STATUS_OPTIONS,
+    STATUS_LABELS,
+    CATEGORY_CONFIG,
+    priority_level,
+)
+
+
+def _render_stats(stats: dict):
+    """Render stats summary bar."""
+    total = stats.get("total", 0)
+    pending = stats.get("pending", 0)
+    in_progress = stats.get("in_progress", 0)
+    completed = stats.get("completed", 0)
+
+    if total == 0:
+        return
+
+    cols = st.columns(4)
+    items = [
+        ("pending", "대기", pending),
+        ("in_progress", "진행 중", in_progress),
+        ("completed", "완료", completed),
+        ("archived", "보관", stats.get("archived", 0)),
+    ]
+    for col, (key, label, count) in zip(cols, items):
+        cfg = STATUS_CONFIG[key]
+        col.markdown(f"""
+        <div style="background:{cfg['bg']};border-radius:10px;padding:16px;text-align:center;
+                    border-left:4px solid {cfg['color']}">
+            <div style="font-size:28px;font-weight:700;color:{cfg['color']}">{count}</div>
+            <div style="font-size:13px;color:#6B7280;margin-top:2px">{cfg['emoji']} {label}</div>
+        </div>
+        """, unsafe_allow_html=True)
+
+    # Progress bar
+    if total > 0:
+        done_pct = completed / total * 100
+        active_pct = in_progress / total * 100
+        st.markdown(f"""
+        <div style="margin:12px 0 4px 0">
+            <div style="display:flex;height:8px;border-radius:4px;overflow:hidden;background:#F3F4F6">
+                <div style="width:{done_pct}%;background:#10b981"></div>
+                <div style="width:{active_pct}%;background:#f59e0b"></div>
+            </div>
+            <div style="display:flex;justify-content:space-between;font-size:11px;color:#9ca3af;margin-top:4px">
+                <span>완료 {done_pct:.0f}%</span>
+                <span>전체 {total}건</span>
+            </div>
+        </div>
+        """, unsafe_allow_html=True)
+
+
+def _render_empty_state():
+    """Render friendly empty state."""
+    st.markdown("""
+    <div style="text-align:center;padding:60px 20px;color:#9ca3af">
+        <div style="font-size:48px;margin-bottom:12px">📋</div>
+        <div style="font-size:18px;font-weight:600;color:#6B7280;margin-bottom:8px">
+            액션아이템이 없습니다
+        </div>
+        <div style="font-size:14px">
+            위의 분석 실행 버튼으로 트리거를 평가하고 저장해보세요
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+
+
+def _render_card(item: dict, idx: int, base_ctx: dict | None = None):
+    """Render a single action item card."""
+    item_id = item["id"]
+    current_status = item.get("status", "pending")
+    priority = item.get("priority", 50)
+    category = item.get("category", "")
+    label = item.get("label", "")
+    evidence = item.get("evidence") or ""
+    llm_rec = item.get("llm_recommendation") or ""
+    created = (item.get("created_at") or "")[:10]
+
+    p_label, p_color, p_bg = priority_level(priority)
+    cat_cfg = CATEGORY_CONFIG.get(category, {"color": "#666", "icon": "📌"})
+
+    # Card header HTML
+    st.markdown(f"""
+    <div style="background:white;border:1px solid #E5E7EB;border-radius:12px;
+                padding:20px;margin-bottom:4px;border-left:4px solid {p_color}">
+        <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:10px">
+            <div style="display:flex;gap:8px;align-items:center">
+                <span style="background:{p_bg};color:{p_color};padding:2px 10px;
+                      border-radius:12px;font-size:12px;font-weight:600">{p_label} {priority}</span>
+                <span style="background:{cat_cfg['color']}15;color:{cat_cfg['color']};padding:2px 10px;
+                      border-radius:12px;font-size:12px">{cat_cfg['icon']} {category}</span>
+            </div>
+            <span style="font-size:11px;color:#9ca3af">{created}</span>
+        </div>
+        <div style="font-size:15px;font-weight:600;color:#1F2937;margin-bottom:6px;line-height:1.4">
+            {label}
+        </div>
+        {"<div style='font-size:13px;color:#6B7280;margin-bottom:6px;line-height:1.5'>" + evidence[:200] + ("..." if len(evidence) > 200 else "") + "</div>" if evidence else ""}
+        {"<div style='background:#EFF6FF;border-radius:8px;padding:10px;font-size:13px;color:#1D4ED8;margin-bottom:4px'>💡 " + llm_rec + "</div>" if llm_rec else ""}
+    </div>
+    """, unsafe_allow_html=True)
+
+    # Interactive controls (Streamlit widgets, can't be inside HTML)
+    ctrl_cols = st.columns([2, 1, 1, 1])
+    with ctrl_cols[0]:
+        new_status = st.selectbox(
+            "상태",
+            options=STATUS_OPTIONS,
+            index=STATUS_OPTIONS.index(current_status),
+            format_func=lambda s: STATUS_LABELS.get(s, s),
+            key=f"ai_st_{item_id}",
+            label_visibility="collapsed",
+        )
+        if new_status != current_status:
+            if update_action_item_status(item_id, new_status):
+                st.rerun()
+
+    with ctrl_cols[1]:
+        assignee = item.get("assignee_email") or ""
+        if assignee:
+            st.caption(f"👤 {assignee.split('@')[0]}")
+
+    with ctrl_cols[2]:
+        export_key = f"ai_export_html_{item_id}"
+        cached = st.session_state.get(export_key)
+        if cached:
+            st.download_button(
+                "📥 다운로드",
+                data=b'\xef\xbb\xbf' + cached["content"].encode("utf-8"),
+                file_name=cached["file_name"],
+                mime="text/html; charset=utf-8",
+                key=f"ai_dl_{item_id}",
+                use_container_width=True,
+            )
+        else:
+            if st.button("📄 HTML", key=f"ai_export_{item_id}", type="secondary"):
+                with st.spinner("HTML 생성 중..."):
+                    try:
+                        from core.api_client import ChainShiftClient
+                        ctx = base_ctx or {}
+                        client = ChainShiftClient(
+                            api_key=ctx.get("api_key"),
+                            access_token=ctx.get("access_token"),
+                        )
+                        resp = client.export_action_item_html(item_id)
+                        data = resp.get("data", {})
+                        html_content = data.get("html_content", "") if isinstance(data, dict) else ""
+                        if html_content:
+                            safe_label = re.sub(r'[^\w\-]', '_', (label or "action_item")[:30])
+                            st.session_state[export_key] = {
+                                "content": html_content,
+                                "file_name": f"{safe_label}_{item_id[:8]}.html",
+                            }
+                            st.rerun()
+                        else:
+                            st.error("HTML 생성 결과가 비어있습니다.")
+                    except Exception as e:
+                        st.error(f"HTML 생성 실패: {e}")
+
+    with ctrl_cols[3]:
+        if st.button("🗑️ 삭제", key=f"ai_del_{item_id}", type="secondary"):
+            if delete_action_item(item_id):
+                st.rerun()
+
+
+def _render_trend_section(campaign_id: int):
+    """Render trigger metric trend charts in an expander."""
+    with st.expander("📊 지표 추이", expanded=False):
+        # Reuse existing date range from session state
+        start_date = st.session_state.get("ai_trigger_start")
+        end_date = st.session_state.get("ai_trigger_end")
+
+        if not start_date or not end_date:
+            date_range = get_campaign_date_range(campaign_id)
+            if not date_range:
+                st.info("캠페인 데이터가 아직 동기화되지 않았습니다.")
+                return
+            _, last_date_str = date_range
+            last_date = date.fromisoformat(last_date_str)
+            end_date = last_date
+            start_date = last_date - timedelta(days=13)
+
+        s = str(start_date)
+        e = str(end_date)
+
+        col1, col2 = st.columns(2)
+        with col1:
+            render_visibility_trend(campaign_id, s, e)
+        with col2:
+            render_citation_type_trend(campaign_id, s, e)
+
+        col3, col4 = st.columns(2)
+        with col3:
+            render_negative_rate_trend(campaign_id, s, e)
+        with col4:
+            render_action_items_history(campaign_id)
+
+
+PAGE_SIZE = 10
+
+
+def render(base_ctx):
+    """Render action items overview with card-based UI."""
+    campaign_id = base_ctx.get("campaign_id")
+    if not campaign_id:
+        st.warning("캠페인을 선택해주세요.")
+        return
+
+    # ── Stats ──
+    stats = get_action_item_stats(campaign_id)
+    _render_stats(stats)
+
+    st.markdown("")  # spacer
+
+    # ── Trigger Analysis ──
+    render_analysis_section(campaign_id, base_ctx)
+
+    # ── Trend Charts ──
+    _render_trend_section(campaign_id)
+
+    st.markdown("---")
+
+    # ── Filters ──
+    filter_cols = st.columns([1, 1, 1])
+    with filter_cols[0]:
+        status_filter = st.selectbox(
+            "상태 필터",
+            options=["전체"] + [STATUS_LABELS[s] for s in STATUS_OPTIONS],
+            index=0,
+            key="ai_status_filter",
+        )
+    with filter_cols[1]:
+        cat_options = ["전체"] + list(CATEGORY_CONFIG.keys())
+        category_filter = st.selectbox(
+            "카테고리 필터",
+            options=cat_options,
+            index=0,
+            key="ai_category_filter",
+        )
+    with filter_cols[2]:
+        SORT_OPTIONS = {
+            "최신순": ("created_at", True),
+            "오래된순": ("created_at", False),
+            "우선순위 높은순": ("priority", True),
+            "우선순위 낮은순": ("priority", False),
+        }
+        sort_choice = st.selectbox(
+            "정렬",
+            options=list(SORT_OPTIONS.keys()),
+            index=0,
+            key="ai_sort",
+        )
+        sort_col, sort_desc = SORT_OPTIONS[sort_choice]
+
+    # Resolve filter values
+    selected_status = None
+    if status_filter != "전체":
+        for k, v in STATUS_LABELS.items():
+            if v == status_filter:
+                selected_status = k
+                break
+
+    selected_category = None if category_filter == "전체" else category_filter
+
+    # ── Pagination state ──
+    page_key = "ai_page"
+    if page_key not in st.session_state:
+        st.session_state[page_key] = 1
+    current_page = st.session_state[page_key]
+
+    # ── Fetch items ──
+    items, total = get_action_items(
+        campaign_id,
+        status=selected_status,
+        category=selected_category,
+        page=current_page,
+        page_size=PAGE_SIZE,
+        order_by=sort_col,
+        desc=sort_desc,
+    )
+
+    if not items and current_page == 1:
+        _render_empty_state()
+        return
+
+    total_pages = max(1, -(-total // PAGE_SIZE))  # ceil division
+    st.caption(f"총 **{total}**건 · 페이지 {current_page}/{total_pages}")
+
+    # ── Card grid (2 columns) ──
+    for i in range(0, len(items), 2):
+        cols = st.columns(2)
+        for col_idx, col in enumerate(cols):
+            item_idx = i + col_idx
+            if item_idx < len(items):
+                with col:
+                    _render_card(items[item_idx], item_idx, base_ctx)
+
+    # ── Pagination controls ──
+    if total_pages > 1:
+        st.markdown("")
+        nav_cols = st.columns([1, 2, 1])
+        with nav_cols[0]:
+            if current_page > 1:
+                if st.button("← 이전", key="ai_prev", use_container_width=True):
+                    st.session_state[page_key] = current_page - 1
+                    st.rerun()
+        with nav_cols[1]:
+            st.markdown(
+                f"<div style='text-align:center;color:#9ca3af;padding:8px'>"
+                f"{current_page} / {total_pages}</div>",
+                unsafe_allow_html=True,
+            )
+        with nav_cols[2]:
+            if current_page < total_pages:
+                if st.button("다음 →", key="ai_next", use_container_width=True):
+                    st.session_state[page_key] = current_page + 1
+                    st.rerun()

features/action_items/trend_charts.py

@@ -0,0 +1,329 @@
+"""Trigger metric trend charts — Plotly mini charts for action items dashboard."""
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date, timedelta
+
+import plotly.graph_objects as go
+import streamlit as st
+
+CHART_HEIGHT = 260
+MINI_LAYOUT = dict(
+    margin=dict(t=30, b=40, l=50, r=20),
+    height=CHART_HEIGHT,
+    legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    xaxis=dict(tickformat="%m/%d"),
+)
+
+
+def _get_client():
+    from core.supabase_client import get_supabase_client
+    return get_supabase_client()
+
+
+@st.cache_data(ttl=120)
+def _fetch_visibility_data(campaign_id: int, start_date: str, end_date: str) -> list[dict]:
+    """Cached fetch for visibility trend data."""
+    client = _get_client()
+    try:
+        result = (
+            client.table("report_visibility_daily")
+            .select("task_date, brand_name, brand_type, visibility_pct")
+            .eq("campaign_id", campaign_id)
+            .gte("task_date", start_date)
+            .lte("task_date", end_date)
+            .order("task_date")
+            .execute()
+        )
+        return result.data or []
+    except Exception:
+        return []
+
+
+@st.cache_data(ttl=120)
+def _fetch_citation_type_data(campaign_id: int, start_date: str, end_date: str) -> list[dict]:
+    """Cached fetch for citation type trend data."""
+    client = _get_client()
+    try:
+        result = (
+            client.table("report_source_daily")
+            .select("task_date, source_host_type, citation_count")
+            .eq("campaign_id", campaign_id)
+            .eq("agg_level", "host")
+            .gte("task_date", start_date)
+            .lte("task_date", end_date)
+            .order("task_date")
+            .execute()
+        )
+        return result.data or []
+    except Exception:
+        return []
+
+
+@st.cache_data(ttl=120)
+def _fetch_negative_rate_data(campaign_id: int, start_date: str, end_date: str) -> list[dict]:
+    """Cached fetch for negative sentiment rate data."""
+    client = _get_client()
+    try:
+        result = client.rpc("get_nudge_export_data", {
+            "p_campaign_id": campaign_id,
+            "p_in_house_only": False,
+            "p_date_from": f"{start_date}T00:00:00+00:00",
+            "p_date_to": f"{_next_day(end_date)}T00:00:00+00:00",
+            "p_limit": 10000,
+        }).execute()
+        data = result.data or {}
+        return data.get("rows", []) if isinstance(data, dict) else []
+    except Exception:
+        return []
+
+
+@st.cache_data(ttl=120)
+def _fetch_action_items_history(campaign_id: int) -> list[dict]:
+    """Cached fetch for action items history data."""
+    client = _get_client()
+    try:
+        result = (
+            client.table("action_items")
+            .select("created_at, completed_at, status")
+            .eq("campaign_id", campaign_id)
+            .order("created_at")
+            .limit(5000)
+            .execute()
+        )
+        return result.data or []
+    except Exception:
+        return []
+
+
+# ============================================================================
+# Chart 1: Visibility trend (own brand vs competitor average)
+# ============================================================================
+
+def render_visibility_trend(campaign_id: int, start_date: str, end_date: str):
+    """Show daily own-brand vs competitor average visibility."""
+    rows = _fetch_visibility_data(campaign_id, start_date, end_date)
+
+    if not rows:
+        st.info("가시성 데이터가 없습니다.")
+        return
+
+    # Group by date: own avg, competitor avg
+    own_by_date: dict[str, list[float]] = defaultdict(list)
+    comp_by_date: dict[str, list[float]] = defaultdict(list)
+
+    for r in rows:
+        d = r["task_date"]
+        pct = r.get("visibility_pct", 0)
+        if r.get("brand_type") == "PRIMARY":
+            own_by_date[d].append(pct)
+        else:
+            comp_by_date[d].append(pct)
+
+    dates = sorted(set(list(own_by_date.keys()) + list(comp_by_date.keys())))
+    own_avgs = [
+        sum(own_by_date[d]) / len(own_by_date[d]) if own_by_date.get(d) else None
+        for d in dates
+    ]
+    comp_avgs = [
+        sum(comp_by_date[d]) / len(comp_by_date[d]) if comp_by_date.get(d) else None
+        for d in dates
+    ]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=dates, y=own_avgs,
+        mode="lines+markers", name="자사",
+        line=dict(color="#3B82F6", width=2),
+        marker=dict(size=5),
+    ))
+    fig.add_trace(go.Scatter(
+        x=dates, y=comp_avgs,
+        mode="lines+markers", name="경쟁사 평균",
+        line=dict(color="#EF4444", width=2, dash="dash"),
+        marker=dict(size=5),
+    ))
+    fig.update_layout(
+        title=dict(text="자사 vs 경쟁사 가시성", font=dict(size=13)),
+        yaxis_title="Visibility %",
+        **MINI_LAYOUT,
+    )
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+
+# ============================================================================
+# Chart 2: Citation type trend (OFFICIAL % + top channel concentration)
+# ============================================================================
+
+def render_citation_type_trend(campaign_id: int, start_date: str, end_date: str):
+    """Show daily OFFICIAL citation % and top channel concentration."""
+    rows = _fetch_citation_type_data(campaign_id, start_date, end_date)
+
+    if not rows:
+        st.info("인용 데이터가 없습니다.")
+        return
+
+    # Group by date
+    by_date: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    for r in rows:
+        d = r["task_date"]
+        ht = r.get("source_host_type") or "UNKNOWN"
+        by_date[d][ht] += r.get("citation_count", 0)
+
+    dates = sorted(by_date.keys())
+    official_pcts = []
+    top_channel_pcts = []
+
+    for d in dates:
+        type_counts = by_date[d]
+        total = sum(type_counts.values())
+        if total > 0:
+            official_pcts.append(round(type_counts.get("OFFICIAL", 0) / total * 100, 1))
+            max_count = max(type_counts.values())
+            top_channel_pcts.append(round(max_count / total * 100, 1))
+        else:
+            official_pcts.append(0)
+            top_channel_pcts.append(0)
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=dates, y=official_pcts,
+        mode="lines+markers", name="OFFICIAL %",
+        line=dict(color="#7C3AED", width=2),
+        marker=dict(size=5),
+    ))
+    fig.add_trace(go.Scatter(
+        x=dates, y=top_channel_pcts,
+        mode="lines+markers", name="Top 채널 %",
+        line=dict(color="#F59E0B", width=2, dash="dot"),
+        marker=dict(size=5),
+    ))
+    # Threshold lines
+    fig.add_hline(y=10, line_dash="dash", line_color="#EF4444", opacity=0.5,
+                  annotation_text="OFFICIAL 10%", annotation_position="bottom right")
+    fig.add_hline(y=50, line_dash="dash", line_color="#F97316", opacity=0.5,
+                  annotation_text="집중 50%", annotation_position="top right")
+    fig.update_layout(
+        title=dict(text="인용 유형 추이", font=dict(size=13)),
+        yaxis_title="%",
+        **MINI_LAYOUT,
+    )
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+
+# ============================================================================
+# Chart 3: Negative sentiment rate trend
+# ============================================================================
+
+def render_negative_rate_trend(campaign_id: int, start_date: str, end_date: str):
+    """Show daily in-house brand negative sentiment rate."""
+    rows = _fetch_negative_rate_data(campaign_id, start_date, end_date)
+
+    if not rows:
+        st.info("감성 분석 데이터가 없습니다.")
+        return
+
+    if len(rows) >= 10000:
+        st.warning("감성 데이터가 10,000건을 초과하여 일부만 표시됩니다. 기간을 좁혀보세요.")
+
+    # Group by date
+    total_by_date: dict[str, int] = defaultdict(int)
+    neg_by_date: dict[str, int] = defaultdict(int)
+
+    for r in rows:
+        d = (r.get("analyzed_at") or "")[:10]
+        if not d:
+            continue
+        total_by_date[d] += 1
+        if r.get("overall_polarity") == "negative":
+            neg_by_date[d] += 1
+
+    dates = sorted(total_by_date.keys())
+    neg_rates = [
+        round(neg_by_date.get(d, 0) / total_by_date[d] * 100, 1) if total_by_date[d] > 0 else 0
+        for d in dates
+    ]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=dates, y=neg_rates,
+        mode="lines+markers", name="부정 비율",
+        line=dict(color="#EF4444", width=2),
+        marker=dict(size=5),
+        fill="tozeroy",
+        fillcolor="rgba(239,68,68,0.1)",
+    ))
+    fig.add_hline(y=30, line_dash="dash", line_color="#F97316", opacity=0.5,
+                  annotation_text="경고 30%", annotation_position="top right")
+    fig.update_layout(
+        title=dict(text="부정 감성 비율 추이", font=dict(size=13)),
+        yaxis_title="부정 %",
+        **MINI_LAYOUT,
+    )
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+
+# ============================================================================
+# Chart 4: Action items history (created vs completed per week)
+# ============================================================================
+
+def render_action_items_history(campaign_id: int):
+    """Show weekly created vs completed action items."""
+    rows = _fetch_action_items_history(campaign_id)
+
+    if not rows:
+        st.info("액션아이템 이력이 없습니다.")
+        return
+
+    # Group by ISO week
+    created_by_week: dict[str, int] = defaultdict(int)
+    completed_by_week: dict[str, int] = defaultdict(int)
+
+    for r in rows:
+        c_date = (r.get("created_at") or "")[:10]
+        if c_date:
+            week = _iso_week_label(c_date)
+            created_by_week[week] += 1
+
+        if r.get("status") == "completed" and r.get("completed_at"):
+            d_date = r["completed_at"][:10]
+            week = _iso_week_label(d_date)
+            completed_by_week[week] += 1
+
+    weeks = sorted(set(list(created_by_week.keys()) + list(completed_by_week.keys())))
+    created_vals = [created_by_week.get(w, 0) for w in weeks]
+    completed_vals = [completed_by_week.get(w, 0) for w in weeks]
+
+    fig = go.Figure()
+    fig.add_trace(go.Bar(
+        x=weeks, y=created_vals, name="생성",
+        marker_color="#6366F1",
+    ))
+    fig.add_trace(go.Bar(
+        x=weeks, y=completed_vals, name="완료",
+        marker_color="#10B981",
+    ))
+    fig.update_layout(
+        title=dict(text="주별 액션아이템 생성/완료", font=dict(size=13)),
+        barmode="group",
+        yaxis_title="건수",
+        **MINI_LAYOUT,
+    )
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+
+# ============================================================================
+# Helpers
+# ============================================================================
+
+def _next_day(date_str: str) -> str:
+    """Return next day as ISO string (for half-open TIMESTAMPTZ filter)."""
+    d = date.fromisoformat(date_str)
+    return (d + timedelta(days=1)).isoformat()
+
+
+def _iso_week_label(date_str: str) -> str:
+    """Convert date string to 'MM/DD' label of the week's Monday."""
+    d = date.fromisoformat(date_str)
+    monday = d - timedelta(days=d.weekday())
+    return monday.strftime("%m/%d")

features/action_items/triggers.py

@@ -0,0 +1,158 @@
+"""Independent trigger evaluation module — queries Supabase directly.
+
+Evaluates 14 trigger rules against cached report data:
+- Rules 1-2: report_visibility_daily (visibility gap, decline)
+- Rules 3, 5: report_source_daily (official citation, channel concentration)
+- Rule 4: answer_sentiment_latest VIEW (negative spike)
+- Rules 6-9: report_source_daily channel groups (editorial/ugc/reference/owned)
+- Rules 10-12: report_source_brand_daily (coverage gap, format gap, share gap)
+- Rules 13-14: answer_sentiment_latest VIEW question types (trust/risk, decision)
+
+No API dependency — all data comes from Supabase tables that
+sync-worker syncs daily at 08:00 KST.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import date, timedelta
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _find_project_root() -> str | None:
+    """Find project root by locating scripts/shared/trigger_rules.py.
+
+    Traverses parent directories instead of hardcoding parents[N]
+    to handle varying deployment paths (local dev, HuggingFace Space, Docker).
+    """
+    current = Path(__file__).resolve().parent
+    for parent in current.parents:
+        if (parent / "scripts" / "shared" / "trigger_rules.py").exists():
+            return str(parent)
+    return None
+
+
+_project_root = _find_project_root()
+if _project_root and _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
+
+# Graceful import: trigger rules may not be available in standalone
+# dashboard deployments (e.g., HuggingFace Space without full repo).
+_TRIGGERS_AVAILABLE = False
+try:
+    from scripts.shared.trigger_rules import (  # noqa: E402
+        TRIGGER_RULES,
+        CHANNEL_GROUPS,
+        _avg_visibility_by_brand,
+        _is_primary,
+        _rule_visibility_gap,
+        _rule_visibility_decline,
+        _rule_official_low_citation,
+        _rule_negative_spike,
+        _rule_channel_concentration,
+        _rule_channel_type_low,
+        _rule_gap_coverage,
+        _rule_gap_format,
+        _rule_gap_share,
+        _rule_question_trust_risk,
+        _rule_question_decision,
+        _fetch_visibility,
+        _fetch_source_types,
+        _fetch_brand_sentiments,
+        _fetch_source_content_types,
+        _fetch_source_brand_mix,
+        _fetch_question_type_stats,
+    )
+    _TRIGGERS_AVAILABLE = True
+except (ImportError, ModuleNotFoundError) as e:
+    logger.warning("trigger_rules not available (standalone dashboard?): %s", e)
+    TRIGGER_RULES = {}
+    CHANNEL_GROUPS = {}
+
+# Re-export all shared symbols so existing imports keep working
+__all__ = [
+    "TRIGGER_RULES",
+    "CHANNEL_GROUPS",
+    "TRIGGERS_AVAILABLE",
+    "evaluate_triggers",
+]
+
+TRIGGERS_AVAILABLE = _TRIGGERS_AVAILABLE
+
+
+def evaluate_triggers(
+    campaign_id: int,
+    start_date: str,
+    end_date: str,
+) -> list[dict]:
+    """Evaluate all trigger rules and return action items (max 14).
+
+    Args:
+        campaign_id: Campaign ID
+        start_date: Start date (YYYY-MM-DD)
+        end_date: End date (YYYY-MM-DD)
+
+    Returns:
+        List of action item dicts sorted by priority descending.
+
+    Raises:
+        RuntimeError: If trigger rules module is not available.
+    """
+    if not _TRIGGERS_AVAILABLE:
+        raise RuntimeError(
+            "트리거 분석을 사용할 수 없습니다. "
+            "scripts/shared/trigger_rules.py가 필요합니다."
+        )
+
+    from core.supabase_client import get_supabase_client
+
+    client = get_supabase_client()
+    items: list[dict] = []
+
+    # ── Data collection ──
+    visibility = _fetch_visibility(client, campaign_id, start_date, end_date)
+    source_types = _fetch_source_types(client, campaign_id, start_date, end_date)
+
+    # ── Rule 1: visibility_gap — own brand < competitor average ──
+    items.extend(_rule_visibility_gap(visibility))
+
+    # ── Rule 2: visibility_decline — delta <= -3pp vs prior period ──
+    period_days = (date.fromisoformat(end_date) - date.fromisoformat(start_date)).days + 1
+    prior_end = date.fromisoformat(start_date) - timedelta(days=1)
+    prior_start = prior_end - timedelta(days=period_days - 1)
+    prior_visibility = _fetch_visibility(
+        client, campaign_id, prior_start.isoformat(), prior_end.isoformat(),
+    )
+    items.extend(_rule_visibility_decline(visibility, prior_visibility))
+
+    # ── Rule 3: official_low_citation — OFFICIAL < 10% ──
+    items.extend(_rule_official_low_citation(source_types))
+
+    # ── Rule 4: negative_spike — in-house negative > 30% ──
+    brand_sentiments = _fetch_brand_sentiments(client, campaign_id, visibility)
+    items.extend(_rule_negative_spike(brand_sentiments))
+
+    # ── Rule 5: channel_concentration — single channel > 50% ──
+    items.extend(_rule_channel_concentration(source_types))
+
+    # ── Rules 6-9: channel type rules ──
+    for channel_name in CHANNEL_GROUPS:
+        items.extend(_rule_channel_type_low(source_types, channel_name))
+
+    # ── Rules 10-12: gap rules ──
+    source_brand_mix = _fetch_source_brand_mix(client, campaign_id, start_date, end_date)
+    content_types = _fetch_source_content_types(client, campaign_id, start_date, end_date)
+
+    items.extend(_rule_gap_coverage(source_brand_mix))
+    items.extend(_rule_gap_format(content_types))
+    items.extend(_rule_gap_share(source_brand_mix))
+
+    # ── Rules 13-14: question type rules ──
+    question_stats = _fetch_question_type_stats(client, campaign_id)
+    items.extend(_rule_question_trust_risk(question_stats))
+    items.extend(_rule_question_decision(question_stats, source_types))
+
+    items.sort(key=lambda x: x["priority"], reverse=True)
+    return items[:14]

features/action_items/utils.py

@@ -0,0 +1,44 @@
+"""Action Items utility functions — status/priority/category styling."""
+
+STATUS_CONFIG = {
+    "pending": {"emoji": "🔴", "label": "대기", "color": "#ff6b6b", "bg": "#FEE2E2"},
+    "in_progress": {"emoji": "🟡", "label": "진행", "color": "#f59e0b", "bg": "#FEF3C7"},
+    "completed": {"emoji": "🟢", "label": "완료", "color": "#10b981", "bg": "#D1FAE5"},
+    "archived": {"emoji": "⚪", "label": "보관", "color": "#9ca3af", "bg": "#F3F4F6"},
+}
+
+STATUS_OPTIONS = ["pending", "in_progress", "completed", "archived"]
+STATUS_LABELS = {k: f"{v['emoji']} {v['label']}" for k, v in STATUS_CONFIG.items()}
+
+CATEGORY_CONFIG = {
+    "플랫폼최적화": {"color": "#4361ee", "icon": "🌐"},
+    "채널전략": {"color": "#3a0ca3", "icon": "📡"},
+    "SEO강화": {"color": "#7209b7", "icon": "🔎"},
+    "감성관리": {"color": "#f72585", "icon": "💬"},
+    "콘텐츠개선": {"color": "#4cc9f0", "icon": "📝"},
+    "부정감성대응": {"color": "#e63946", "icon": "🛡️"},
+}
+
+# Legacy alias
+CATEGORY_COLORS = {k: v["color"] for k, v in CATEGORY_CONFIG.items()}
+
+
+def priority_level(priority: int) -> tuple[str, str, str]:
+    """Return (label, color, bg) based on priority score."""
+    if priority >= 80:
+        return "긴급", "#dc2626", "#FEE2E2"
+    if priority >= 60:
+        return "높음", "#f59e0b", "#FEF3C7"
+    if priority >= 40:
+        return "보통", "#3b82f6", "#DBEAFE"
+    return "낮음", "#9ca3af", "#F3F4F6"
+
+
+def status_emoji(status: str) -> str:
+    """Return emoji for status."""
+    return STATUS_CONFIG.get(status, {}).get("emoji", "❓")
+
+
+def status_label(status: str) -> str:
+    """Return localized label for status."""
+    return STATUS_CONFIG.get(status, {}).get("label", status)

features/hierarchy/__init__.py

@@ -0,0 +1,41 @@
+"""계층 분석 Feature Plugin.
+
+API: /api/v1/hierarchy
+ADR-017: Hierarchy Generator Python Migration
+"""
+import streamlit as st
+
+from . import request, monitor
+
+FEATURE_CONFIG = {
+    "key": "hierarchy",
+    "name": "계층 분석",
+    "icon": "🔗",
+    "description": "키워드 기반 소비자 여정 계층 분석 및 질문 생성",
+    "api_base": "/api/v1/hierarchy",
+    "order": 5,
+}
+
+
+def render(base_ctx):
+    """계층 분석 feature 렌더링."""
+    st.caption("키워드를 입력하면 소비자 여정(CEJ) 기반으로 계층 구조를 분석하고 질문을 생성합니다")
+
+    tabs = st.tabs([
+        "📝 분석 요청",
+        "⏳ 진행 현황",
+        "📋 분석 결과",
+    ])
+
+    tab_renderers = [
+        ("분석 요청", request.render),
+        ("진행 현황", monitor.render_active),
+        ("분석 결과", monitor.render_history),
+    ]
+
+    for tab, (label, renderer) in zip(tabs, tab_renderers):
+        with tab:
+            try:
+                renderer(base_ctx)
+            except Exception as e:
+                st.error(f"{label} 로딩 실패: {e}")

features/hierarchy/monitor.py

@@ -0,0 +1,208 @@
+"""계층 분석 진행 현황 + 분석 결과 탭.
+
+진행 현황: Supabase 직접 쿼리 (Vercel timeout 회피)
+분석 결과: API 호출 (질문 데이터)
+"""
+import streamlit as st
+import pandas as pd
+
+from core.api_client import ChainShiftClient
+from core.job_realtime import (
+    get_active_hierarchy_jobs,
+    get_recent_hierarchy_jobs,
+    get_hierarchy_step_label,
+    format_job_duration,
+    get_status_emoji,
+    get_status_label,
+)
+
+
+# ============================================================================
+# 진행 현황 탭
+# ============================================================================
+
+def render_active(base_ctx: dict):
+    """진행 현황 탭 렌더링."""
+    st.markdown("##### ⏳ 진행 현황")
+    st.caption("대기 중이거나 처리 중인 계층 분석 Job을 확인합니다")
+
+    if st.button("🔄 새로고침", key="hier:refresh_active"):
+        st.rerun()
+
+    try:
+        active_jobs = get_active_hierarchy_jobs(limit=5)
+    except Exception as e:
+        st.warning(f"Job 목록 로드 실패: {e}")
+        active_jobs = []
+
+    if not active_jobs:
+        st.info("현재 진행 중인 계층 분석 Job이 없습니다.")
+        return
+
+    for job in active_jobs:
+        _render_active_card(job)
+
+
+def _render_active_card(job: dict):
+    """활성 Job 카드 렌더링."""
+    progress = job.get("progress", 0)
+    status = job.get("status", "")
+    step = job.get("current_step")
+    step_label = get_hierarchy_step_label(step)
+    status_emoji = get_status_emoji(status)
+    status_label = get_status_label(status)
+    duration = format_job_duration(job)
+    prompt = job.get("prompt", "")
+    title = job.get("title") or prompt[:30]
+
+    st.markdown(f"""
+    <div style="background: linear-gradient(135deg, #EDE9FE 0%, #F5F3FF 100%);
+                border-radius: 12px; padding: 20px; margin-bottom: 16px;
+                border: 1px solid #C4B5FD;">
+        <div style="display: flex; justify-content: space-between; align-items: center;">
+            <div>
+                <span style="font-size: 28px;">{status_emoji}</span>
+                <span style="font-size: 18px; font-weight: bold; margin-left: 8px;">{title}</span>
+            </div>
+            <div style="text-align: right;">
+                <div style="font-size: 32px; font-weight: bold; color: #6D28D9;">{progress}%</div>
+                <div style="font-size: 12px; color: #6B7280;">소요시간: {duration}</div>
+            </div>
+        </div>
+        <div style="margin-top: 12px; font-size: 14px; color: #374151;">
+            {status_label} &middot; {step_label}
+        </div>
+        <div style="margin-top: 4px; font-size: 12px; color: #6B7280;">
+            키워드: {prompt}
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+
+    st.progress(progress / 100)
+
+
+# ============================================================================
+# 분석 결과 탭
+# ============================================================================
+
+def render_history(base_ctx: dict):
+    """분석 결과 탭 렌더링."""
+    st.markdown("##### 📋 분석 결과")
+    st.caption("완료된 계층 분석 Job 이력과 결과를 확인합니다")
+
+    if st.button("🔄 새로고침", key="hier:refresh_history"):
+        st.rerun()
+
+    try:
+        jobs = get_recent_hierarchy_jobs(limit=20)
+    except Exception as e:
+        st.warning(f"Job 이력 로드 실패: {e}")
+        jobs = []
+
+    if not jobs:
+        st.info("아직 계층 분석 이력이 없습니다.")
+        return
+
+    # Job 이력 테이블
+    rows = []
+    for j in jobs:
+        status = j.get("status", "")
+        emoji = get_status_emoji(status)
+        label = get_status_label(status)
+        duration = format_job_duration(j)
+        rows.append({
+            "상태": f"{emoji} {label}",
+            "제목": j.get("title") or "-",
+            "키워드": j.get("prompt", "")[:30],
+            "진행률": f"{j.get('progress', 0)}%",
+            "소요시간": duration,
+            "생성일": (j.get("created_at") or "")[:19].replace("T", " "),
+            "ID": (j.get("id") or "")[:8],
+        })
+
+    st.dataframe(pd.DataFrame(rows), use_container_width=True, hide_index=True)
+
+    # 완료된 Job expander: 질문 통계 + 샘플
+    completed_jobs = [j for j in jobs if j.get("status") == "completed"]
+    if not completed_jobs:
+        return
+
+    st.markdown("---")
+    st.markdown("###### 완료된 분석 상세")
+
+    if not base_ctx.get("api_key") and not base_ctx.get("access_token"):
+        st.caption("질문 상세 보기는 인증이 필요합니다.")
+        return
+
+    client = ChainShiftClient(
+        api_key=base_ctx.get("api_key"),
+        access_token=base_ctx.get("access_token"),
+    )
+
+    for job in completed_jobs[:5]:
+        job_id = job["id"]
+        title = job.get("title") or job.get("prompt", "")[:30]
+        created = (job.get("created_at") or "")[:10]
+
+        with st.expander(f"{title} ({created})", expanded=False):
+            _render_job_detail(client, job_id)
+
+
+def _render_job_detail(client: ChainShiftClient, job_id: str):
+    """완료된 Job 상세: 질문 통계 + 샘플 질문."""
+    # 질문 통계
+    try:
+        stats_resp = client.get_hierarchy_question_stats(job_id)
+        stats = (stats_resp or {}).get("data") or {}
+    except Exception as e:
+        st.warning(f"통계 로드 실패: {e}")
+        stats = {}
+
+    if stats:
+        total = stats.get("total_questions", 0)
+        brand_count = stats.get("brand_mention_count", 0)
+        persona_count = stats.get("persona_included_count", 0)
+
+        col1, col2, col3 = st.columns(3)
+        with col1:
+            st.metric("총 질문", f"{total:,}개")
+        with col2:
+            st.metric("브랜드 포함", f"{brand_count:,}개")
+        with col3:
+            st.metric("페르소나 적용", f"{persona_count:,}개")
+
+        # 여정별 분포
+        by_depth1 = stats.get("by_journey_depth1") or {}
+        if by_depth1:
+            st.markdown("**여정 유형별 분포**")
+            depth1_labels = {
+                "awareness_comparison": "인지/비교",
+                "purchase": "구매",
+                "post_purchase": "구매 후",
+            }
+            depth1_rows = [
+                {"여정": depth1_labels.get(k, k), "질문 수": v}
+                for k, v in by_depth1.items()
+            ]
+            st.dataframe(
+                pd.DataFrame(depth1_rows),
+                use_container_width=True,
+                hide_index=True,
+            )
+
+    # 샘플 질문 10개
+    try:
+        q_resp = client.get_hierarchy_questions(job_id, page=1, page_size=10)
+        questions = ((q_resp or {}).get("data") or {}).get("items") or []
+    except Exception:
+        questions = []
+
+    if questions:
+        st.markdown("**샘플 질문 (최대 10개)**")
+        for i, q in enumerate(questions, 1):
+            journey = q.get("journey_depth2", "")
+            question_text = q.get("question", "")
+            brand = " 🏷️" if q.get("brand_mention") else ""
+            st.markdown(f"{i}. [{journey}] {question_text}{brand}")
+    elif stats:
+        st.caption("질문 데이터가 아직 없습니다.")

features/hierarchy/request.py

@@ -0,0 +1,221 @@
+"""계층 분석 요청 탭.
+
+5단계 설정 폼 → ProcessorConfig 매핑 → API 호출.
+"""
+import streamlit as st
+
+from core.api_client import ChainShiftClient
+
+# 17 Journey Types across 3 depth1 groups
+_JOURNEY_GROUPS: dict[str, list[tuple[str, str]]] = {
+    "인지/비교 (Awareness & Comparison)": [
+        ("verification", "사실확인"),
+        ("market_trends", "최신 트렌드"),
+        ("preparation", "준비/필요"),
+        ("timing", "시기/타이밍"),
+        ("review_experience", "리뷰/경험"),
+        ("information_discovery", "정보탐색/개념"),
+        ("result_effectiveness", "효과/결과"),
+        ("recommendation", "구매추천"),
+        ("comparison", "구매추천(비교)"),
+        ("problem_solving", "문제해결"),
+        ("difference_pros_cons", "차이점/장단점"),
+    ],
+    "구매 (Purchase)": [
+        ("pricing", "비용/가격"),
+        ("promotion_benefits", "프로모션/할인/혜택"),
+        ("where_to_buy", "구매처"),
+    ],
+    "구매 후 (Post-Purchase)": [
+        ("howto", "제품/서비스 how-to"),
+        ("refund_customer_service", "환불 A/S"),
+        ("side_effect", "부작용"),
+    ],
+}
+
+_PRODUCT_TYPES = ["product", "service", "brand"]
+_MODELS = ["gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro", "gemini-2.5-flash"]
+_AGE_OPTIONS = ["10대", "20대", "30대", "40대", "50대", "60대 이상"]
+_GENDER_OPTIONS = ["여성", "남성"]
+_TRAIT_OPTIONS = ["가성비중시", "프리미엄선호", "트렌드민감", "실용주의"]
+
+
+def render(base_ctx: dict):
+    """분석 요청 폼 렌더링."""
+    st.markdown("##### 📝 계층 분석 요청")
+    st.caption("키워드와 분석 조건을 설정하고 분석을 시작합니다")
+
+    if not base_ctx.get("api_key") and not base_ctx.get("access_token"):
+        st.warning("인증 정보가 설정되지 않았습니다.")
+        return
+
+    client = ChainShiftClient(
+        api_key=base_ctx.get("api_key"),
+        access_token=base_ctx.get("access_token"),
+    )
+
+    # ── Step 1: 입력 분석 ──
+    st.markdown("###### 1. 입력 분석")
+    col1, col2 = st.columns([3, 1])
+    with col1:
+        raw_text = st.text_input(
+            "분석 키워드",
+            key="hier:raw_text",
+            placeholder="예: 강아지 사료, 여행 가방, 전기차 보험",
+        )
+    with col2:
+        product_type = st.selectbox(
+            "제품 유형",
+            _PRODUCT_TYPES,
+            key="hier:product_type",
+        )
+
+    title = st.text_input(
+        "분석 제목 (선택)",
+        key="hier:title",
+        placeholder="분석 결과 구분용 제목",
+    )
+
+    # ── Step 2: 여정 유형 ──
+    st.markdown("---")
+    st.markdown("###### 2. 소비자 여정 유형")
+    st.caption("분석에 포함할 여정 유형을 선택하세요 (기본: 구매추천)")
+
+    selected_journeys: list[str] = []
+    for group_label, types in _JOURNEY_GROUPS.items():
+        with st.expander(group_label, expanded=(group_label.startswith("인지"))):
+            for code, label in types:
+                default = code == "recommendation"
+                if st.checkbox(
+                    label,
+                    value=default,
+                    key=f"hier:cej:{code}",
+                ):
+                    selected_journeys.append(code)
+
+    # ── Step 3: 페르소나 (선택) ──
+    st.markdown("---")
+    st.markdown("###### 3. 페르소나 설정 (선택)")
+
+    use_persona = st.checkbox("페르소나 적용", key="hier:use_persona")
+    persona_ages: list[str] = []
+    persona_gender: str | None = None
+    persona_trait: str | None = None
+
+    if use_persona:
+        col1, col2, col3 = st.columns(3)
+        with col1:
+            persona_ages = st.multiselect("연령대", _AGE_OPTIONS, key="hier:ages")
+        with col2:
+            gender_sel = st.selectbox(
+                "성별", ["선택 안함"] + _GENDER_OPTIONS, key="hier:gender",
+            )
+            persona_gender = gender_sel if gender_sel != "선택 안함" else None
+        with col3:
+            trait_sel = st.selectbox(
+                "소비 성향", ["선택 안함"] + _TRAIT_OPTIONS, key="hier:trait",
+            )
+            persona_trait = trait_sel if trait_sel != "선택 안함" else None
+
+    # ── Step 4: 브랜드 컨텍스트 (선택) ──
+    st.markdown("---")
+    st.markdown("###### 4. 브랜드 컨텍스트 (선택)")
+
+    brand_mention = st.checkbox(
+        "질문에 브랜드 포함",
+        key="hier:brand_mention",
+        help="활성화하면 생성된 질문에 브랜드명이 포함됩니다",
+    )
+    own_brands_input = ""
+    if brand_mention:
+        own_brands_input = st.text_input(
+            "자사 브랜드 (쉼표 구분)",
+            key="hier:own_brands",
+            placeholder="브랜드A, 브랜드B",
+        )
+
+    # ── Step 5: 분석 설정 ──
+    st.markdown("---")
+    st.markdown("###### 5. 분석 설정")
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        model = st.selectbox("AI 모델", _MODELS, key="hier:model")
+    with col2:
+        questions_per_kw = st.number_input(
+            "키워드당 질문 수",
+            min_value=5,
+            max_value=100,
+            value=25,
+            step=5,
+            key="hier:qpk",
+        )
+    with col3:
+        max_nodes = st.number_input(
+            "최대 노드 수",
+            min_value=10,
+            max_value=500,
+            value=100,
+            step=10,
+            key="hier:max_nodes",
+        )
+
+    # ── Submit ──
+    st.markdown("---")
+
+    can_submit = bool(raw_text and raw_text.strip() and selected_journeys)
+    if not raw_text or not raw_text.strip():
+        st.info("분석 키워드를 입력하세요.")
+    elif not selected_journeys:
+        st.info("최소 1개의 여정 유형을 선택하세요.")
+
+    if st.button(
+        "▶️ 분석 시작",
+        type="primary",
+        key="hier:submit",
+        disabled=not can_submit,
+    ):
+        keyword = raw_text.strip()
+        own_brands = [b.strip() for b in own_brands_input.split(",") if b.strip()] if own_brands_input else []
+
+        processor_config = {
+            "version": "1.0",
+            "inputAnalysis": {
+                "rawText": keyword,
+                "primaryKeyword": keyword,
+                "productType": product_type,
+                "locationCode": 2410,
+                "languageCode": "ko",
+            },
+            "brandContext": {
+                "brandMention": brand_mention,
+                "ownBrands": own_brands,
+            },
+            "selectedJourneyTypes": selected_journeys,
+            "persona": {
+                "attributes": {
+                    "ages": persona_ages,
+                    "gender": persona_gender,
+                    "trait": persona_trait,
+                },
+            },
+            "modifiers": [],
+        }
+        settings = {
+            "model": model,
+            "questionsPerKeyword": questions_per_kw,
+            "maxNodes": max_nodes,
+            "outputLanguage": "ko",
+        }
+
+        try:
+            client.create_hierarchy_job(
+                prompt=keyword,
+                title=title.strip() if title else None,
+                processor_config=processor_config,
+                settings=settings,
+            )
+            st.success("분석 Job이 생성되었습니다! '진행 현황' 탭에서 확인하세요.")
+            st.rerun()
+        except Exception as e:
+            st.error(f"분석 시작 실패: {e}")

features/reports/__init__.py

@@ -0,0 +1,25 @@
+"""리포트 Feature Plugin.
+
+API: /api/v1/reports
+"""
+import streamlit as st
+
+from . import overview, summary
+
+FEATURE_CONFIG = {
+    "key": "reports",
+    "name": "리포트",
+    "icon": "📝",
+    "description": "Feature별 미리보기, HTML/CSV 다운로드, 전체 리포트 생성",
+    "api_base": "/api/v1/reports",
+    "order": 2,
+}
+
+
+def render(base_ctx):
+    """리포트 feature 렌더링."""
+    # Summary card
+    summary.render_summary(base_ctx)
+
+    # Main content - delegates to overview which has all sub-tabs
+    overview.render(base_ctx)

features/reports/full_report.py

@@ -0,0 +1,325 @@
+"""전체 리포트 생성 탭."""
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import pandas as pd
+import requests
+import streamlit as st
+import streamlit.components.v1 as components
+
+from core.api_client import ChainShiftClient
+
+
+def _build_one(
+    api_key: str,
+    campaign_id: int,
+    feat_key: str,
+    start_date: str,
+    end_date: str,
+    enable_insights: bool,
+    homepage_urls: list[str] | None,
+) -> tuple[str, dict | None, str | None]:
+    """Worker thread — st.* 호출 금지. 독립 HTTP 클라이언트로 feature 빌드."""
+    try:
+        thread_client = ChainShiftClient(api_key=api_key)
+        result = thread_client.build_html_feature(
+            campaign_id=campaign_id,
+            feature=feat_key,
+            start_date=start_date,
+            end_date=end_date,
+            enable_insights=enable_insights,
+            enable_action_items=True,
+            homepage_urls=homepage_urls if feat_key == "homepage-citations" else None,
+        )
+        return feat_key, result, None
+    except Exception as e:
+        return feat_key, None, str(e)
+
+
+@st.cache_data(ttl=60)
+def _fetch_report_history(
+    campaign_id: int, page: int = 1, page_size: int = 20,
+    _api_key: str = "", _access_token: str = "",
+) -> dict:
+    """Cached fetch for HTML report history."""
+    client = ChainShiftClient(api_key=_api_key or None, access_token=_access_token or None)
+    return client.get_html_report_history(campaign_id, page=page, page_size=page_size)
+
+
+AVAILABLE_FEATURES = [
+    ("overview", "1. 가시성 분석 개요"),
+    ("visibility", "2. AI 검색 가시성"),
+    ("citations", "3. 인용 출처 분석"),
+    ("citation-trends", "4. 인용 출처 시계열"),
+    ("content-types", "5. 콘텐츠 유형"),
+    ("sentiment", "6. 브랜드 감정"),
+    ("homepage-citations", "7. 홈페이지 인용률"),
+]
+
+
+def render(client: ChainShiftClient, base_ctx: dict, start_date: str, end_date: str):
+    """전체 리포트 생성 섹션."""
+    st.markdown("#### 📄 전체 HTML 리포트 생성")
+    st.caption("7개 Feature를 포함한 통합 HTML 리포트를 생성합니다. LLM 인사이트로 컨설턴트 톤의 분석을 추가할 수 있습니다.")
+
+    with st.expander("⚙️ 리포트 옵션", expanded=True):
+        st.markdown("**포함할 Feature 선택**")
+        selected_features = []
+        col1, col2 = st.columns(2)
+        for i, (feat_key, feat_label) in enumerate(AVAILABLE_FEATURES):
+            with col1 if i < 4 else col2:
+                if st.checkbox(feat_label, value=True, key=f"reports:full_feat_{feat_key}"):
+                    selected_features.append(feat_key)
+
+        st.markdown("---")
+
+        enable_insights = st.checkbox(
+            "🤖 LLM 인사이트 생성",
+            value=True,
+            help="Gemini API를 사용하여 컨설턴트 톤의 분석 인사이트를 추가합니다 (생성 시간 증가)",
+        )
+
+        st.text_area(
+            "Homepage URLs (줄바꿈 구분, 선택)",
+            help="홈페이지 인용률 분석에 사용할 URL 목록",
+            key="reports:homepage_urls_input",
+            height=80,
+        )
+
+    # Parse homepage URLs from text area
+    homepage_urls_raw = st.session_state.get("reports:homepage_urls_input", "")
+    homepage_urls = [u.strip() for u in homepage_urls_raw.splitlines() if u.strip()] or None
+
+    # Feature display name lookup
+    _feat_display = dict(AVAILABLE_FEATURES)
+
+    if st.button("🚀 전체 리포트 생성", key="reports:generate_html_btn", type="primary", disabled=not selected_features):
+        campaign_id = base_ctx["campaign_id"]
+        total = len(selected_features)
+        progress_bar = st.progress(0, text="리포트 생성 준비 중...")
+        status_container = st.container()
+
+        built_features: list[dict] = []
+        skipped_features: list[str] = []
+        total_build_ms = 0
+
+        # Phase 1: Build features in parallel (I/O-bound HTTP calls)
+        with ThreadPoolExecutor(max_workers=total) as executor:
+            futures = {
+                executor.submit(
+                    _build_one, client.api_key, campaign_id, feat_key,
+                    start_date, end_date, enable_insights, homepage_urls,
+                ): feat_key
+                for feat_key in selected_features
+            }
+            completed = 0
+            for future in as_completed(futures):
+                feat_key = futures[future]
+                feat_label = _feat_display.get(feat_key, feat_key)
+                completed += 1
+                fk, result, error = future.result()
+                if error:
+                    skipped_features.append(feat_key)
+                    with status_container:
+                        st.caption(f"  {feat_label} 실패: {error}")
+                elif result and result.get("success"):
+                    feat_resp = result["data"]
+                    built_features.append(feat_resp["feature_data"])
+                    build_ms = feat_resp.get("build_time_ms", 0)
+                    total_build_ms += build_ms
+                    insight_tag = " +인사이트" if feat_resp.get("insights_generated") else ""
+                    with status_container:
+                        st.caption(f"  {feat_label} ({build_ms/1000:.1f}s{insight_tag})")
+                else:
+                    skipped_features.append(feat_key)
+                    with status_container:
+                        st.caption(f"  {feat_label} 건너뜀")
+                progress_bar.progress(
+                    completed / (total + 1),
+                    text=f"({completed}/{total}) 빌드 완료...",
+                )
+
+        # Restore original feature order for rendering
+        feat_order = {k: i for i, k in enumerate(selected_features)}
+        built_features.sort(key=lambda f: feat_order.get(f.get("feature_id", ""), 99))
+
+        if not built_features:
+            progress_bar.empty()
+            st.error("모든 Feature 생성에 실패했습니다.")
+        else:
+            # Phase 2: Render final report
+            progress_bar.progress(
+                total / (total + 1),
+                text="HTML 리포트 조립 중...",
+            )
+            try:
+                render_result = client.render_html_report(
+                    campaign_id=campaign_id,
+                    features_data=built_features,
+                    start_date=start_date,
+                    end_date=end_date,
+                    enable_insights=enable_insights,
+                    enable_action_items=True,
+                    output_mode="url",
+                )
+
+                if render_result.get("success"):
+                    data = render_result.get("data") or {}
+                    if not isinstance(data, dict):
+                        progress_bar.empty()
+                        st.error("리포트 렌더링 실패: 서버 응답이 비정상입니다.")
+                    else:
+                        render_ms = data.get("generation_time_ms", 0)
+
+                        # Download HTML from Supabase Storage URL directly.
+                        # url mode avoids Vercel 4.5MB response body limit.
+                        html_content = ""
+                        html_url = data.get("html_url") or ""
+                        if html_url:
+                            try:
+                                dl_resp = requests.get(html_url, timeout=30)
+                                dl_resp.raise_for_status()
+                                dl_resp.encoding = "utf-8"
+                                html_content = dl_resp.text
+                            except Exception as dl_err:
+                                st.warning(f"HTML 다운로드 실패, URL 링크로 대체: {dl_err}")
+
+                        if not html_url and not html_content:
+                            progress_bar.empty()
+                            st.error("리포트 렌더링 실패: 스토리지 URL이 반환되지 않았습니다.")
+                        else:
+                            # Persist results in session_state for rerun survival
+                            st.session_state["full_report_result"] = {
+                                "html_content": html_content,
+                                "html_url": html_url,
+                                "report_id": data.get("report_id", "")[:8],
+                                "features_generated": data.get("features_generated", []),
+                                "file_size_kb": round(data.get("file_size_bytes", 0) / 1024, 1),
+                                "total_sec": round((total_build_ms + render_ms) / 1000, 1),
+                                "insights_generated": data.get("insights_generated", False),
+                                "skipped_features": skipped_features,
+                                "campaign_id": campaign_id,
+                                "start_date": start_date,
+                                "end_date": end_date,
+                            }
+                            progress_bar.empty()
+                            st.rerun()
+                else:
+                    progress_bar.empty()
+                    st.error("리포트 렌더링 실패: " + str(render_result.get("error", "Unknown error")))
+
+            except Exception as e:
+                progress_bar.empty()
+                st.error(f"리포트 렌더링 오류: {e}")
+    elif not selected_features:
+        st.warning("최소 1개 이상의 Feature를 선택하세요.")
+
+    # ── Results display (persists across reruns via session_state) ──
+    report_state = st.session_state.get("full_report_result")
+    if report_state:
+        html_content = report_state["html_content"]
+        report_id = report_state["report_id"]
+        features_generated = report_state["features_generated"]
+        file_size_kb = report_state["file_size_kb"]
+        total_sec = report_state["total_sec"]
+        skipped = report_state["skipped_features"]
+        r_campaign_id = report_state["campaign_id"]
+        r_start = report_state["start_date"]
+        r_end = report_state["end_date"]
+
+        if skipped:
+            st.warning(f"일부 Feature를 건너뛰고 리포트를 생성했습니다: {', '.join(skipped)}")
+        st.success("리포트가 생성되었습니다!")
+
+        st.markdown(f"""
+        <div style="background: linear-gradient(135deg, #E5E2FF 0%, #F0FDFA 100%);
+                    padding: 20px; border-radius: 12px; margin: 16px 0;">
+            <h4 style="margin: 0 0 12px 0; color: #2B239B;">리포트 생성 완료</h4>
+            <p style="margin: 8px 0;"><strong>Report ID:</strong> {report_id}...</p>
+            <p style="margin: 8px 0;"><strong>Features:</strong> {len(features_generated)}개 ({len(skipped)}개 건너뜀)</p>
+            <p style="margin: 8px 0;"><strong>파일 크기:</strong> {file_size_kb} KB</p>
+            <p style="margin: 8px 0;"><strong>생성 시간:</strong> {total_sec}초</p>
+            <p style="margin: 8px 0;"><strong>LLM 인사이트:</strong> {'포함' if report_state.get('insights_generated') else '미포함'}</p>
+        </div>
+        """, unsafe_allow_html=True)
+
+        html_url = report_state.get("html_url", "")
+
+        if html_content:
+            col_open, col_download, col_clear = st.columns(3)
+            with col_open:
+                if html_url:
+                    st.link_button("새 창에서 보기", html_url, use_container_width=True)
+                else:
+                    st.button("새 창에서 보기", disabled=True, use_container_width=True, key="reports:open_disabled")
+            with col_download:
+                file_name = f"AI_가시성_리포트_{r_campaign_id}_{r_start}_{r_end}.html"
+                st.download_button(
+                    label="HTML 다운로드",
+                    data=b'\xef\xbb\xbf' + html_content.lstrip('\ufeff').encode("utf-8"),
+                    file_name=file_name,
+                    mime="text/html; charset=utf-8",
+                    use_container_width=True,
+                    key="reports:full_report_download",
+                )
+            with col_clear:
+                if st.button("초기화", key="reports:clear_result", use_container_width=True):
+                    del st.session_state["full_report_result"]
+                    st.rerun()
+
+            with st.expander("리포트 미리보기", expanded=False):
+                components.html(html_content, height=800, scrolling=True)
+        elif html_url:
+            # Fallback: HTML download failed, show direct link
+            col_link, col_clear = st.columns(2)
+            with col_link:
+                st.link_button("리포트 열기 (외부 링크)", html_url, use_container_width=True)
+            with col_clear:
+                if st.button("초기화", key="reports:clear_result", use_container_width=True):
+                    del st.session_state["full_report_result"]
+                    st.rerun()
+
+    st.markdown("---")
+
+    # Report History
+    st.markdown("##### 📋 생성 이력")
+    try:
+        history_result = _fetch_report_history(
+            base_ctx["campaign_id"],
+            _api_key=base_ctx.get("api_key", ""),
+            _access_token=base_ctx.get("access_token", ""),
+        )
+        if history_result.get("success"):
+            history_data = history_result["data"]
+            reports = history_data.get("items", [])
+            total = history_data.get("total", 0)
+
+            if reports:
+                st.markdown(f"총 **{total}**건의 리포트가 생성되었습니다.")
+
+                history_rows = []
+                for r in reports:
+                    status_emoji = "✅" if r.get("status") == "completed" else "❌"
+                    features = r.get("features_included", [])
+                    file_size_kb = round(r.get("file_size_bytes", 0) / 1024, 1)
+                    history_rows.append({
+                        "생성일": r.get("created_at", "")[:16].replace("T", " "),
+                        "상태": f"{status_emoji}",
+                        "Features": f"{len(features)}/{len(AVAILABLE_FEATURES)}",
+                        "기간": f"{r.get('start_date', '?')} ~ {r.get('end_date', '?')}",
+                        "크기": f"{file_size_kb} KB",
+                        "링크": r.get("html_url") or "-",
+                    })
+
+                df = pd.DataFrame(history_rows)
+                st.dataframe(
+                    df,
+                    use_container_width=True,
+                    hide_index=True,
+                    column_config={
+                        "링크": st.column_config.LinkColumn("링크", display_text="열기"),
+                    },
+                )
+            else:
+                st.info("아직 생성된 리포트가 없습니다.")
+    except Exception as e:
+        st.warning(f"이력 로드 실패: {e}")

features/reports/overview.py

@@ -0,0 +1,220 @@
+"""리포트 탭.
+
+Feature별 미리보기, HTML/CSV 다운로드, 전체 리포트 생성.
+"""
+from datetime import datetime, timedelta
+
+import streamlit as st
+
+from core.api_client import ChainShiftClient
+from core.supabase_client import get_campaign_date_range
+
+from .utils import render_feature_section
+from . import full_report
+
+
+# Period presets: (label, days or None for "all")
+PERIOD_PRESETS = [
+    ("최근 1일", 1),
+    ("최근 7일", 7),
+    ("최근 30일", 30),
+    ("최근 90일", 90),
+    ("최근 180일", 180),
+    ("전체 기간", None),
+    ("직접 선택", -1),
+]
+
+
+def render(base_ctx: dict):
+    """리포트 탭 렌더링."""
+    st.markdown("##### 리포트")
+    st.caption("기간별 AI 가시성 분석 리포트를 생성하고, HTML로 다운로드할 수 있습니다.")
+
+    # Get campaign date range for presets
+    campaign_date_range = get_campaign_date_range(base_ctx["campaign_id"])
+    if campaign_date_range:
+        first_date_str, last_date_str = campaign_date_range
+        first_date = datetime.strptime(first_date_str, "%Y-%m-%d")
+        last_date = datetime.strptime(last_date_str, "%Y-%m-%d")
+        total_days = (last_date - first_date).days + 1
+    else:
+        first_date = datetime.now() - timedelta(days=30)
+        last_date = datetime.now()
+        first_date_str = first_date.strftime("%Y-%m-%d")
+        last_date_str = last_date.strftime("%Y-%m-%d")
+        total_days = 31
+
+    # Period selection
+    start_date_str, end_date_str = _render_period_selector(
+        first_date, last_date, first_date_str, last_date_str, total_days
+    )
+
+    # Show selected period info
+    selected_days = (datetime.strptime(end_date_str, "%Y-%m-%d") - datetime.strptime(start_date_str, "%Y-%m-%d")).days + 1
+    st.caption(f"📅 선택된 기간: **{start_date_str} ~ {end_date_str}** ({selected_days}일)")
+
+    st.markdown("---")
+
+    # 4 Sub-tabs for Features + 1 for Full Report
+    report_tab_summary, report_tab_visibility, report_tab_citation, report_tab_full = st.tabs([
+        "📊 Executive Summary",
+        "👁️ Visibility & Content",
+        "🔗 Citation Analysis",
+        "📄 전체 리포트",
+    ])
+
+    client = ChainShiftClient(api_key=base_ctx.get("api_key"), access_token=base_ctx.get("access_token"))
+
+    # Tab 1: Executive Summary
+    with report_tab_summary:
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="overview",
+            title="가시성 개요",
+            description="AI 플랫폼별 브랜드 노출 현황과 핵심 지표",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+    # Tab 2: Visibility & Content
+    with report_tab_visibility:
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="visibility",
+            title="플랫폼별 가시성",
+            description="ChatGPT, Gemini 등 AI 플랫폼별 자사 vs 경쟁사 노출 비교",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="content-types",
+            title="콘텐츠 유형 분포",
+            description="AI가 인용하는 콘텐츠 유형 (블로그, 뉴스, 공식 사이트 등)",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="sentiment",
+            title="브랜드 감정 분석",
+            description="브랜드별 긍정/부정/중립 감정 분포",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+    # Tab 3: Citation Analysis
+    with report_tab_citation:
+
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="citations",
+            title="인용 출처 순위",
+            description="AI 답변에서 가장 많이 인용되는 도메인과 출처",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="citation-trends",
+            title="인용 추이",
+            description="시간에 따른 인용 출처 변화 트렌드",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+        render_feature_section(
+            client=client,
+            campaign_id=base_ctx["campaign_id"],
+            feature_key="homepage-citations",
+            title="홈페이지 인용률",
+            description="자사 홈페이지가 AI 답변에 직접 인용되는 비율",
+            start_date=start_date_str,
+            end_date=end_date_str,
+            api_key=base_ctx.get("api_key") or "",
+            access_token=base_ctx.get("access_token") or "",
+        )
+
+    # Tab 4: Full Report
+    with report_tab_full:
+        full_report.render(client, base_ctx, start_date_str, end_date_str)
+
+
+def _render_period_selector(
+    first_date: datetime,
+    last_date: datetime,
+    first_date_str: str,
+    last_date_str: str,
+    total_days: int,
+) -> tuple[str, str]:
+    """기간 선택 UI 렌더링. (start_date, end_date) 반환."""
+    col_period, col_date1, col_date2 = st.columns([1.5, 1, 1])
+
+    with col_period:
+        period_options = [label for label, _ in PERIOD_PRESETS]
+        selected_period = st.selectbox(
+            "분석 기간",
+            options=period_options,
+            index=5,  # Default to "전체 기간"
+            key="reports:period_select",
+            help=f"캠페인 데이터: {first_date_str} ~ {last_date_str} (총 {total_days}일)",
+        )
+
+    period_idx = period_options.index(selected_period)
+    _, period_days = PERIOD_PRESETS[period_idx]
+
+    if period_days == -1:  # Custom selection
+        with col_date1:
+            report_start = st.date_input(
+                "시작일",
+                value=first_date,
+                min_value=first_date,
+                max_value=last_date,
+                key="reports:start_date",
+            )
+        with col_date2:
+            report_end = st.date_input(
+                "종료일",
+                value=last_date,
+                min_value=first_date,
+                max_value=last_date,
+                key="reports:end_date",
+            )
+        return str(report_start), str(report_end)
+    elif period_days is None:  # All data
+        with col_date1:
+            st.text_input("시작일", value=first_date_str, disabled=True, key="reports:start_display")
+        with col_date2:
+            st.text_input("종료일", value=last_date_str, disabled=True, key="reports:end_display")
+        return first_date_str, last_date_str
+    else:  # Preset days
+        end_date = last_date
+        start_date = max(first_date, end_date - timedelta(days=period_days - 1))
+        start_date_str = start_date.strftime("%Y-%m-%d")
+        end_date_str = end_date.strftime("%Y-%m-%d")
+        with col_date1:
+            st.text_input("시작일", value=start_date_str, disabled=True, key="reports:start_display")
+        with col_date2:
+            st.text_input("종료일", value=end_date_str, disabled=True, key="reports:end_display")
+        return start_date_str, end_date_str

features/reports/summary.py

@@ -0,0 +1,31 @@
+"""리포트 Feature 요약 카드."""
+import streamlit as st
+
+from core.supabase_client import get_campaign_date_range, get_report_history_count
+
+
+def render_summary(base_ctx: dict):
+    """리포트 요약 카드."""
+    campaign_id = base_ctx["campaign_id"]
+    date_range = get_campaign_date_range(campaign_id)
+    report_count = get_report_history_count(campaign_id)
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        if date_range:
+            days = _calc_days(date_range[0], date_range[1])
+            st.metric("데이터 수집 기간", f"{days}일", help=f"{date_range[0]} ~ {date_range[1]}")
+        else:
+            st.metric("데이터 수집 기간", "N/A")
+    with col2:
+        st.metric("생성된 리포트", f"{report_count}건")
+    with col3:
+        st.metric("분석 항목", "가시성 / 인용 / 감정 / 콘텐츠")
+
+
+def _calc_days(start: str, end: str) -> int:
+    """두 날짜 문자열 간 일수 계산."""
+    from datetime import datetime
+    d1 = datetime.strptime(start, "%Y-%m-%d")
+    d2 = datetime.strptime(end, "%Y-%m-%d")
+    return (d2 - d1).days + 1

features/reports/utils.py

@@ -0,0 +1,469 @@
+"""리포트 탭 공통 유틸리티.
+
+Feature별 미리보기, HTML 생성, CSV 변환 등 공통 함수.
+"""
+import io
+import csv
+
+import pandas as pd
+import requests
+import streamlit as st
+import streamlit.components.v1 as components
+
+from core.api_client import ChainShiftClient
+
+
+def render_feature_section(
+    client: ChainShiftClient,
+    campaign_id: int,
+    feature_key: str,
+    title: str,
+    description: str,
+    start_date: str,
+    end_date: str,
+    api_key: str = "",
+    access_token: str = "",
+):
+    """단일 Feature 섹션 렌더링."""
+    html_state_key = f"html_content_{feature_key}_{campaign_id}"
+    insights_key = f"insights_enabled_{feature_key}_{campaign_id}"
+
+    with st.container(border=True):
+        # Header
+        c1, c2 = st.columns([4, 1])
+        with c1:
+            st.markdown(f"**{title}**")
+            st.caption(description)
+
+        # Preview Section (Lazy loaded)
+        with st.expander(f"👁️ 미리보기", expanded=False):
+            try:
+                result = get_report_feature_data(api_key, campaign_id, feature_key, start_date, end_date, access_token=access_token)
+                if result.get("success"):
+                    data = result.get("data", {})
+                    render_feature_preview(feature_key, data)
+                else:
+                    st.warning(f"데이터 로드 실패: {result.get('error', 'Unknown')}")
+            except Exception as e:
+                st.error(f"미리보기 오류: {e}")
+
+        # LLM Insights checkbox
+        enable_insights = st.checkbox(
+            "🤖 LLM 인사이트 포함",
+            value=st.session_state.get(insights_key, True),
+            key=f"insights_cb_{feature_key}",
+            help="컨설턴트 톤의 분석 코멘트를 추가합니다",
+        )
+        st.session_state[insights_key] = enable_insights
+
+        # Generated HTML display section
+        if html_state_key in st.session_state:
+            html_data = st.session_state[html_state_key]
+            html_content = html_data.get("content", "")
+            html_url = html_data.get("url", "")
+
+            st.success(f"✅ HTML 리포트 생성 완료" + (" (LLM 인사이트 포함)" if html_data.get("insights") else ""))
+
+            if html_content:
+                # Action buttons
+                col_open, col_dl, col_csv, col_reset = st.columns(4)
+
+                with col_open:
+                    if html_url:
+                        st.link_button("🔗 새 창에서 보기", html_url, use_container_width=True)
+                    else:
+                        st.button("🔗 새 창에서 보기", disabled=True, use_container_width=True, key=f"html_open_{feature_key}_disabled")
+
+                with col_dl:
+                    st.download_button(
+                        label="📥 HTML 다운로드",
+                        data=b'\xef\xbb\xbf' + html_content.lstrip('\ufeff').encode("utf-8"),
+                        file_name=f"{feature_key}_{campaign_id}_{start_date}_{end_date}.html",
+                        mime="text/html; charset=utf-8",
+                        use_container_width=True,
+                        key=f"html_dl_{feature_key}",
+                    )
+
+                with col_csv:
+                    try:
+                        result = get_report_feature_data(api_key, campaign_id, feature_key, start_date, end_date, access_token=access_token)
+                        if result.get("success"):
+                            csv_data = convert_report_data_to_csv(feature_key, result.get("data", {}))
+                            st.download_button(
+                                label="📊 CSV 다운로드",
+                                data=csv_data.encode("utf-8-sig"),
+                                file_name=f"{feature_key}_{campaign_id}_{start_date}_{end_date}.csv",
+                                mime="text/csv",
+                                use_container_width=True,
+                                key=f"csv_{feature_key}_post",
+                            )
+                        else:
+                            st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_post_disabled")
+                    except Exception:
+                        st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_post_error")
+
+                with col_reset:
+                    if st.button("🔄 다시 생성", key=f"html_reset_{feature_key}", use_container_width=True):
+                        del st.session_state[html_state_key]
+                        st.rerun()
+
+                # Inline preview
+                with st.expander("👁️ HTML 미리보기", expanded=False):
+                    components.html(html_content, height=500, scrolling=True)
+
+            elif html_url:
+                # Fallback: HTML download failed, show direct link
+                col_link, col_csv, col_reset = st.columns(3)
+                with col_link:
+                    st.link_button("🔗 리포트 열기 (외부 링크)", html_url, use_container_width=True)
+                with col_csv:
+                    try:
+                        result = get_report_feature_data(api_key, campaign_id, feature_key, start_date, end_date, access_token=access_token)
+                        if result.get("success"):
+                            csv_data = convert_report_data_to_csv(feature_key, result.get("data", {}))
+                            st.download_button(
+                                label="📊 CSV 다운로드",
+                                data=csv_data.encode("utf-8-sig"),
+                                file_name=f"{feature_key}_{campaign_id}_{start_date}_{end_date}.csv",
+                                mime="text/csv",
+                                use_container_width=True,
+                                key=f"csv_{feature_key}_fallback",
+                            )
+                        else:
+                            st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_fallback_disabled")
+                    except Exception:
+                        st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_fallback_error")
+                with col_reset:
+                    if st.button("🔄 다시 생성", key=f"html_reset_{feature_key}", use_container_width=True):
+                        del st.session_state[html_state_key]
+                        st.rerun()
+
+        else:
+            # Generate button
+            col_html, col_csv = st.columns(2)
+
+            with col_html:
+                if st.button(f"📄 HTML 생성", key=f"html_{feature_key}", use_container_width=True):
+                    spinner_text = "HTML 생성 중..." + (" (LLM 인사이트 포함)" if enable_insights else "")
+                    with st.spinner(spinner_text):
+                        try:
+                            # Use url mode to avoid Vercel 4.5MB response limit.
+                            # Download HTML from Supabase Storage directly.
+                            result_url = client.generate_html_report(
+                                campaign_id=campaign_id,
+                                start_date=start_date,
+                                end_date=end_date,
+                                features=[feature_key],
+                                enable_insights=enable_insights,
+                                output_mode="url",
+                            )
+                            if result_url.get("success"):
+                                data = result_url.get("data") or {}
+                                html_url = data.get("html_url", "") if isinstance(data, dict) else ""
+                                html_content = ""
+                                if html_url:
+                                    try:
+                                        dl_resp = requests.get(html_url, timeout=30)
+                                        dl_resp.raise_for_status()
+                                        dl_resp.encoding = "utf-8"
+                                        html_content = dl_resp.text
+                                    except Exception as dl_err:
+                                        st.warning(f"HTML 다운로드 실패, URL 링크로 대체: {dl_err}")
+                                if not html_url and not html_content:
+                                    st.error("HTML 생성 실패: 스토리지 URL이 반환되지 않았습니다.")
+                                else:
+                                    st.session_state[html_state_key] = {
+                                        "content": html_content,
+                                        "url": html_url,
+                                        "insights": enable_insights,
+                                    }
+                                    st.rerun()
+                            else:
+                                st.error("HTML 생성 실패: " + str(result_url.get("error", "Unknown")))
+                        except Exception as e:
+                            st.error(f"오류: {e}")
+
+            with col_csv:
+                try:
+                    result = get_report_feature_data(api_key, campaign_id, feature_key, start_date, end_date, access_token=access_token)
+                    if result.get("success"):
+                        csv_data = convert_report_data_to_csv(feature_key, result.get("data", {}))
+                        st.download_button(
+                            label="📊 CSV 다운로드",
+                            data=csv_data.encode("utf-8-sig"),
+                            file_name=f"{feature_key}_{campaign_id}_{start_date}_{end_date}.csv",
+                            mime="text/csv",
+                            use_container_width=True,
+                            key=f"csv_{feature_key}",
+                        )
+                    else:
+                        st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_disabled")
+                except Exception:
+                    st.button("📊 CSV 다운로드", disabled=True, use_container_width=True, key=f"csv_{feature_key}_error")
+
+
+def render_feature_preview(feature_key: str, data: dict):
+    """Feature별 미리보기 시각화."""
+    if feature_key == "overview":
+        cols = st.columns(4)
+        with cols[0]:
+            st.metric("총 질문 수", data.get("total_tasks", 0))
+        with cols[1]:
+            st.metric("총 답변 수", data.get("total_answers", 0))
+        with cols[2]:
+            st.metric("가시성", f"{data.get('overall_visibility_pct', 0):.1f}%")
+        with cols[3]:
+            dr = data.get("date_range", {})
+            period = f"{dr.get('start', '?')} ~ {dr.get('end', '?')}"
+            st.metric("분석 기간", period[:20])
+
+    elif feature_key == "visibility":
+        platforms = data.get("platforms", [])
+        if platforms:
+            rows = []
+            for p in platforms:
+                for b in p.get("brands", []):
+                    rows.append({
+                        "플랫폼": p.get("platform", ""),
+                        "브랜드": b.get("brand_name", ""),
+                        "가시성 (%)": b.get("visibility_pct", 0),
+                    })
+            if rows:
+                df = pd.DataFrame(rows)
+                st.dataframe(df, use_container_width=True, hide_index=True)
+        else:
+            st.info("플랫폼 데이터 없음")
+
+    elif feature_key == "citations":
+        sources = data.get("sources", [])[:10]
+        if sources:
+            df = pd.DataFrame(sources)
+            cols = [c for c in ["source_host_url", "total_citations", "pct_of_total"] if c in df.columns]
+            if cols:
+                st.dataframe(df[cols], use_container_width=True, hide_index=True)
+        else:
+            st.info("인용 데이터 없음")
+
+    elif feature_key == "citation-trends":
+        sources = data.get("sources", [])
+        if sources:
+            rows = []
+            for s in sources:
+                for pt in s.get("trend", []):
+                    rows.append({
+                        "date": pt.get("task_date", ""),
+                        "source": s.get("source_host_url", ""),
+                        "citations": pt.get("citation_count", 0),
+                    })
+            if rows:
+                df = pd.DataFrame(rows)
+                pivot = df.pivot_table(index="date", columns="source", values="citations", aggfunc="sum").fillna(0)
+                st.line_chart(pivot)
+        else:
+            st.info("시계열 데이터 없음")
+
+    elif feature_key == "content-types":
+        types = data.get("content_types", [])
+        if types:
+            df = pd.DataFrame(types)
+            if "content_type" in df.columns and "total_citations" in df.columns:
+                st.bar_chart(df.set_index("content_type")["total_citations"])
+        else:
+            st.info("콘텐츠 유형 데이터 없음")
+
+    elif feature_key == "sentiment":
+        in_house = data.get("in_house_brands", [])
+        competitor = data.get("competitor_brands", [])
+
+        if in_house:
+            st.markdown("**🏢 자사 브랜드**")
+            df_ih = pd.DataFrame(in_house)
+            cols_ih = ["brand_name", "total_mentions", "positive_rate", "negative_rate"]
+            cols_ih = [c for c in cols_ih if c in df_ih.columns]
+            if cols_ih:
+                st.dataframe(df_ih[cols_ih], use_container_width=True, hide_index=True)
+
+        if competitor:
+            st.markdown("**🎯 경쟁사 브랜드**")
+            df_comp = pd.DataFrame(competitor)
+            cols_comp = ["brand_name", "total_mentions", "positive_rate", "negative_rate"]
+            cols_comp = [c for c in cols_comp if c in df_comp.columns]
+            if cols_comp:
+                st.dataframe(df_comp[cols_comp], use_container_width=True, hide_index=True)
+
+        if not in_house and not competitor:
+            brands = data.get("brands", [])
+            if brands:
+                df = pd.DataFrame(brands)
+                cols = [c for c in ["brand_name", "brand_type", "positive_rate", "negative_rate"] if c in df.columns]
+                if cols:
+                    st.dataframe(df[cols], use_container_width=True, hide_index=True)
+            else:
+                st.info("감정 분석 데이터 없음")
+
+    elif feature_key == "homepage-citations":
+        daily_data = data.get("daily_data", [])[:10]
+        if daily_data:
+            rows = []
+            for day in daily_data:
+                for entry in day.get("entries", []):
+                    rows.append({
+                        "날짜": day.get("task_date", ""),
+                        "플랫폼": entry.get("platform", ""),
+                        "인용 횟수": entry.get("citation_count", 0),
+                    })
+            if rows:
+                df = pd.DataFrame(rows)
+                st.dataframe(df, use_container_width=True, hide_index=True)
+        else:
+            st.info("홈페이지 인용 데이터 없음")
+
+
+@st.cache_data(ttl=300)
+def get_report_feature_data(
+    api_key: str,
+    campaign_id: int,
+    feature: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    access_token: str = "",
+):
+    """Fetch report feature data with caching."""
+    client = ChainShiftClient(api_key=api_key or None, access_token=access_token or None)
+
+    if feature == "overview":
+        return client.get_report_overview(campaign_id, start_date, end_date)
+    elif feature == "visibility":
+        return client.get_report_visibility(campaign_id, start_date, end_date)
+    elif feature == "citations":
+        return client.get_report_citations(campaign_id, start_date, end_date, limit=50)
+    elif feature == "citation-trends":
+        return client.get_report_citation_trends(campaign_id, start_date, end_date)
+    elif feature == "content-types":
+        return client.get_report_content_types(campaign_id, start_date, end_date)
+    elif feature == "sentiment":
+        return client.get_report_sentiment(campaign_id)
+    elif feature == "homepage-citations":
+        return client.get_report_homepage_citations(campaign_id, start_date, end_date)
+    else:
+        return {"success": False, "error": f"Unknown feature: {feature}"}
+
+
+def convert_report_data_to_csv(feature: str, data: dict) -> str:
+    """Convert report feature data to CSV format."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+
+    if feature == "overview":
+        dr = data.get("date_range", {})
+        writer.writerow(["항목", "값"])
+        writer.writerow(["캠페인 ID", data.get("campaign_id", "")])
+        writer.writerow(["분석 기간", f"{dr.get('start', '')} ~ {dr.get('end', '')}"])
+        writer.writerow(["총 질문 수", data.get("total_tasks", 0)])
+        writer.writerow(["총 답변 수", data.get("total_answers", 0)])
+        writer.writerow(["가시성 비율 (%)", data.get("overall_visibility_pct", 0)])
+
+    elif feature == "visibility":
+        writer.writerow(["플랫폼", "브랜드", "유형", "가시성 (%)", "브랜드 언급 수", "총 답변 수"])
+        for platform in data.get("platforms", []):
+            for brand in platform.get("brands", []):
+                writer.writerow([
+                    platform.get("platform", ""),
+                    brand.get("brand_name", ""),
+                    brand.get("brand_type", ""),
+                    brand.get("visibility_pct", 0),
+                    brand.get("brand_mentions", 0),
+                    platform.get("total_answers", 0),
+                ])
+
+    elif feature == "citations":
+        writer.writerow(["도메인", "유형", "인용 횟수", "답변 언급 수", "비율 (%)"])
+        for item in data.get("sources", []):
+            writer.writerow([
+                item.get("source_host_url", ""),
+                item.get("source_host_type", ""),
+                item.get("total_citations", 0),
+                item.get("total_answer_mentions", 0),
+                item.get("pct_of_total", 0),
+            ])
+
+    elif feature == "citation-trends":
+        writer.writerow(["인용 출처", "유형", "날짜", "인용 횟수", "답변 언급 수", "비율 (%)"])
+        for source in data.get("sources", []):
+            host = source.get("source_host_url", "")
+            host_type = source.get("source_host_type", "")
+            for point in source.get("trend", []):
+                writer.writerow([
+                    host,
+                    host_type,
+                    point.get("task_date", ""),
+                    point.get("citation_count", 0),
+                    point.get("answer_mention_count", 0),
+                    point.get("citation_pct", 0),
+                ])
+
+    elif feature == "content-types":
+        writer.writerow(["콘텐츠 유형", "인용 횟수", "답변 언급 수", "비율 (%)"])
+        for item in data.get("content_types", []):
+            writer.writerow([
+                item.get("content_type", ""),
+                item.get("total_citations", 0),
+                item.get("total_answer_mentions", 0),
+                item.get("pct_of_total", 0),
+            ])
+
+    elif feature == "sentiment":
+        writer.writerow(["브랜드", "유형", "총 멘션", "긍정 %", "부정 %", "중립 %"])
+
+        for item in data.get("in_house_brands", []):
+            t = item.get("total_mentions", 0)
+            neutral = round(item.get("neutral_count", 0) / t * 100, 1) if t > 0 else 0.0
+            writer.writerow([
+                item.get("brand_name", ""),
+                "자사",
+                t,
+                f"{item.get('positive_rate', 0):.1f}",
+                f"{item.get('negative_rate', 0):.1f}",
+                f"{neutral:.1f}",
+            ])
+
+        for item in data.get("competitor_brands", []):
+            t = item.get("total_mentions", 0)
+            neutral = round(item.get("neutral_count", 0) / t * 100, 1) if t > 0 else 0.0
+            writer.writerow([
+                item.get("brand_name", ""),
+                "경쟁사",
+                item.get("total_mentions", 0),
+                f"{item.get('positive_rate', 0):.1f}",
+                f"{item.get('negative_rate', 0):.1f}",
+                f"{neutral:.1f}",
+            ])
+
+        if not data.get("in_house_brands") and not data.get("competitor_brands"):
+            for item in data.get("brands", []):
+                pos = item.get("positive_rate", item.get("positive", 0))
+                neg = item.get("negative_rate", item.get("negative", 0))
+                neutral = 100 - pos - neg
+                writer.writerow([
+                    item.get("brand_name", item.get("name", "")),
+                    item.get("brand_type", item.get("type", "")),
+                    item.get("total_mentions", 0),
+                    f"{pos:.1f}",
+                    f"{neg:.1f}",
+                    f"{neutral:.1f}",
+                ])
+
+    elif feature == "homepage-citations":
+        writer.writerow(["날짜", "플랫폼", "인용 출처", "인용 횟수", "답변 언급 수"])
+        for day in data.get("daily_data", []):
+            task_date = day.get("task_date", "")
+            for entry in day.get("entries", []):
+                writer.writerow([
+                    task_date,
+                    entry.get("platform", ""),
+                    entry.get("source_host_url", ""),
+                    entry.get("citation_count", 0),
+                    entry.get("answer_mention_count", 0),
+                ])
+
+    return output.getvalue()

features/research/__init__.py

@@ -0,0 +1,189 @@
+"""토픽 인텔리전스 Feature Plugin.
+
+API: /api/v1/research
+ADR-013 Phase 4 + ADR-014 Phase 3 (Multi-Model UX).
+"""
+import streamlit as st
+
+from core.supabase_client import (
+    get_topic_clusters, get_topic_map_snapshot, find_cross_model_pair,
+)
+from . import topic_map, opportunities, distribution, guide, summary
+from .cross_model import render_cross_model
+from .content_actions import render_content_actions
+from .keyword_suggest import render_keyword_suggestions
+from .unified_scoring import render_unified_scoring
+
+FEATURE_CONFIG = {
+    "key": "research",
+    "name": "토픽 인텔리전스",
+    "icon": "🔬",
+    "description": "AI가 어떤 토픽에 관심을 갖고 있는지, 어디에 콘텐츠 기회가 있는지 분석",
+    "api_base": "/api/v1/research",
+    "order": 3,
+}
+
+# Source configs: label, description, help text
+SOURCE_OPTIONS = {
+    "전체": {
+        "source": None,
+        "desc": "ChatGPT + Gemini 전체 토픽을 통합하여 분석합니다.",
+        "fanout_label": "Fanout/Citation",
+        "frame": "all",
+    },
+    "ChatGPT (Demand)": {
+        "source": "chatgpt",
+        "desc": "소비자가 AI에게 **무엇을 물어보는지** 분석합니다. ChatGPT의 sub-query 분해 데이터 기반.",
+        "fanout_label": "Fanout",
+        "frame": "demand",
+    },
+    "Gemini (Supply)": {
+        "source": "gemini",
+        "desc": "AI가 **무엇을 근거로 답변하는지** 분석합니다. Gemini의 citation quote 데이터 기반.",
+        "fanout_label": "Citation",
+        "frame": "supply",
+    },
+}
+
+
+def render(base_ctx):
+    """토픽 인텔리전스 feature 렌더링."""
+    campaign_id = base_ctx["campaign_id"]
+
+    st.caption("AI가 어떤 토픽에 관심을 갖고 있는지, 어디에 콘텐츠 기회가 있는지 분석합니다.")
+
+    # --- Model Selector ---
+    selected = st.radio(
+        "분석 모델",
+        list(SOURCE_OPTIONS.keys()),
+        horizontal=True,
+        key="research:model_selector",
+        help="ChatGPT는 소비자 검색 의도(Demand), Gemini는 AI 인용 근거(Supply)를 나타냅니다.",
+    )
+    source_cfg = SOURCE_OPTIONS[selected]
+    source = source_cfg["source"]
+
+    st.caption(source_cfg["desc"])
+
+    # Education expander
+    with st.expander("어떻게 작동하나요?", expanded=False):
+        if source_cfg["frame"] == "demand":
+            st.markdown("""
+**ChatGPT Demand 분석**
+
+ChatGPT는 사용자 질문을 8-15개의 세부 질문(fanout)으로 분해하여 Bing에서 검색합니다.
+이 fanout 패턴을 분석하면 **소비자가 AI에게 무엇을 물어보는지** 파악할 수 있습니다.
+
+```
+사용자 질문 → ChatGPT가 8-15개 sub-query 생성 → Bing 검색 → 답변 합성
+                    ↓
+              sub-query 클러스터링 → Demand 토픽
+```
+""")
+        elif source_cfg["frame"] == "supply":
+            st.markdown("""
+**Gemini Supply 분석**
+
+Gemini는 답변 시 웹 콘텐츠에서 직접 문장을 추출(extractive summarization)하여 인용합니다.
+인용 패턴을 분석하면 **AI가 어떤 콘텐츠를 근거로 선택하는지** 파악할 수 있습니다.
+
+```
+사용자 질문 → Gemini 검색 판단 → Google Search → 2000단어 예산 내 인용 추출
+                    ↓
+              citation quote 클러스터링 → Supply 토픽
+```
+""")
+        else:
+            st.markdown("""
+AI 모델이 사용자 질문에 답변할 때, 내부적으로 여러 개의 세부 질문(추가 질문)을
+만들어 조사합니다. 이 추가 질문들을 분석하면 **AI가 어떤 주제에 관심을 갖고 있는지**,
+어떤 분야에서 **경쟁이 치열한지**를 파악할 수 있습니다.
+
+**데이터 흐름:**
+```
+사용자 질문 → AI가 추가 질문 생성 → 답변 작성 → 출처 인용
+                    ↓
+              유사한 추가 질문끼리 묶기 (클러스터링)
+                    ↓
+              각 토픽의 점수 계산
+              · AI 관심도: AI가 이 주제를 얼마나 자주 물어보는가
+              · 경쟁 밀도: 이 주제에 얼마나 많은 출처가 인용되는가
+              · 기회 점수: 관심은 높지만 경쟁이 낮은 영역
+```
+
+자세한 내용은 **"분석 가이드"** 탭을 참조하세요.
+""")
+
+    clusters = get_topic_clusters(campaign_id, source=source)
+
+    if not clusters:
+        if source:
+            st.warning(f"{selected} 데이터가 없습니다. 해당 모델의 클러스터링을 먼저 실행하세요.")
+        else:
+            st.warning("토픽 클러스터 데이터가 없습니다. 클러스터링을 먼저 실행하세요.")
+        return
+
+    snapshot = get_topic_map_snapshot(campaign_id, source=source)
+
+    # Summary metrics
+    summary.render_summary(clusters, frame=source_cfg["frame"])
+
+    st.markdown("---")
+
+    # Cross-model pair (one DB call, reused across tabs)
+    pair = find_cross_model_pair(campaign_id)
+
+    # Build tab list — Unified Scoring only in "전체" mode with pair
+    tab_names = [
+        "🗺️ 토픽 맵",
+        "🎯 기회 영역",
+        "📊 토픽 분포",
+        "🔀 Cross-Model",
+        "💡 콘텐츠 가이드",
+        "🔑 키워드 추천",
+    ]
+    show_unified = source_cfg["frame"] == "all" and pair is not None
+    if show_unified:
+        tab_names.append("⚖️ Unified Score")
+    tab_names.append("📖 분석 가이드")
+
+    tabs = st.tabs(tab_names)
+    idx = 0
+
+    with tabs[idx]:
+        topic_map.render_topic_map(clusters, snapshot, frame=source_cfg["frame"])
+    idx += 1
+
+    with tabs[idx]:
+        opportunities.render_opportunities(clusters, frame=source_cfg["frame"])
+    idx += 1
+
+    with tabs[idx]:
+        distribution.render_distribution(clusters, frame=source_cfg["frame"])
+    idx += 1
+
+    with tabs[idx]:
+        if pair:
+            render_cross_model(base_ctx, pair)
+        else:
+            st.info("이 캠페인에 대한 Cross-Model 분석이 아직 없습니다.")
+    idx += 1
+
+    with tabs[idx]:
+        if pair:
+            render_content_actions(base_ctx, pair)
+        else:
+            st.info("Cross-Model 분석 완료 후 콘텐츠 가이드를 사용할 수 있습니다.")
+    idx += 1
+
+    with tabs[idx]:
+        render_keyword_suggestions(clusters, frame=source_cfg["frame"])
+    idx += 1
+
+    if show_unified:
+        with tabs[idx]:
+            render_unified_scoring(base_ctx, pair)
+        idx += 1
+
+    with tabs[idx]:
+        guide.render_data_flow()

features/research/content_actions.py

@@ -0,0 +1,217 @@
+"""콘텐츠 액션 가이드 (R-5).
+
+GapScore OPPORTUNITY 토픽 기반 콘텐츠 제작 제안.
+Cross-Model 분석 데이터를 활용하여 구체적 액션 아이템 생성.
+"""
+
+import streamlit as st
+import pandas as pd
+
+from core.supabase_client import get_gap_scores, get_topic_clusters
+
+
+# Content strategy templates per quadrant
+STRATEGY_TEMPLATES = {
+    "OPPORTUNITY": {
+        "priority": "🔴 높음",
+        "action": "콘텐츠 제작",
+        "detail": (
+            "사용자가 자주 검색하지만 AI가 인용할 만한 콘텐츠가 부족합니다. "
+            "이 토픽에 대한 전문 콘텐츠를 제작하면 AI 답변에 인용될 확률이 높습니다."
+        ),
+        "tactics": [
+            "FAQ 페이지에 이 토픽 관련 질문-답변 추가",
+            "통계/데이터 포함 — AI 인용 확률 +41% (GEO 연구)",
+            "30-50단어 자기 완결형 답변 문단 포함 (Answer Capsule)",
+            "Schema Markup 추가 — AI 인용 확률 2.5배 증가",
+        ],
+    },
+    "SATURATED": {
+        "priority": "🟡 중간",
+        "action": "차별화 강화",
+        "detail": (
+            "수요와 공급 모두 높은 경쟁 토픽입니다. "
+            "기존 콘텐츠와 차별화된 전문성이나 고유 데이터가 필요합니다."
+        ),
+        "tactics": [
+            "자체 연구 데이터/케이스 스터디 추가",
+            "기존 인용 소스 분석 → 빠진 각도(angle) 발굴",
+            "E-E-A-T 신호 강화 (저자 전문성, 인용 출처 명시)",
+            "비교표/데이터 시각화로 정보 밀도 높이기",
+        ],
+    },
+    "LATENT_AUTHORITY": {
+        "priority": "🟢 낮음",
+        "action": "유지 + 모니터링",
+        "detail": (
+            "이미 AI에 인용되고 있지만 검색 수요가 낮습니다. "
+            "기존 콘텐츠를 유지하며 수요 변화를 모니터링하세요."
+        ),
+        "tactics": [
+            "기존 인용 콘텐츠의 최신 업데이트 유지",
+            "Demand 증가 추세 감지 시 콘텐츠 확장",
+            "인용되는 구체적 문장/구절 파악 → 강화",
+        ],
+    },
+    "NICHE": {
+        "priority": "⚪ 관망",
+        "action": "선택적 실험",
+        "detail": (
+            "수요와 공급 모두 낮은 틈새 영역입니다. "
+            "시장이 성장하면 선점 효과를 볼 수 있습니다."
+        ),
+        "tactics": [
+            "낮은 비용으로 기본 콘텐츠 마련 (선점)",
+            "관련 키워드 트렌드 모니터링",
+        ],
+    },
+}
+
+
+def render_content_actions(base_ctx: dict, pair: dict):
+    """Render content action guide based on GapScore analysis."""
+    campaign_chatgpt = pair["campaign_chatgpt"]
+    campaign_gemini = pair["campaign_gemini"]
+
+    st.caption(
+        "Demand-Supply Gap 분석 결과를 기반으로 **구체적 콘텐츠 전략**을 제안합니다."
+    )
+
+    matches = get_gap_scores(campaign_chatgpt, campaign_gemini)
+    if not matches:
+        st.warning("GapScore 데이터가 없습니다.")
+        return
+
+    # Fetch cluster details for sample_fanouts and top_sources
+    chatgpt_clusters = get_topic_clusters(campaign_chatgpt, source="chatgpt")
+    gemini_clusters = get_topic_clusters(campaign_gemini, source="gemini")
+
+    chatgpt_map = {c["id"]: c for c in chatgpt_clusters}
+    gemini_map = {c["id"]: c for c in gemini_clusters}
+
+    # --- Overview: Quadrant distribution ---
+    quadrant_counts = {}
+    for m in matches:
+        q = m.get("quadrant", "NICHE")
+        quadrant_counts[q] = quadrant_counts.get(q, 0) + 1
+
+    opp_count = quadrant_counts.get("OPPORTUNITY", 0)
+    sat_count = quadrant_counts.get("SATURATED", 0)
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.metric("콘텐츠 제작 필요", f"{opp_count}개 토픽",
+                   help="OPPORTUNITY: Demand 높음 + Supply 낮음")
+    with col2:
+        st.metric("차별화 필요", f"{sat_count}개 토픽",
+                   help="SATURATED: Demand 높음 + Supply 높음")
+    with col3:
+        st.metric("총 분석 토픽", f"{len(matches)}개")
+
+    st.markdown("---")
+
+    # --- Priority Action List ---
+    st.markdown("### 우선 액션 리스트")
+    st.caption("GapScore 순으로 정렬. OPPORTUNITY 토픽이 최우선입니다.")
+
+    # Summary table
+    rows = []
+    for i, m in enumerate(matches, 1):
+        q = m.get("quadrant", "NICHE")
+        strategy = STRATEGY_TEMPLATES.get(q, STRATEGY_TEMPLATES["NICHE"])
+        rows.append({
+            "순위": i,
+            "토픽 (Demand)": (m.get("chatgpt_label") or "")[:35],
+            "토픽 (Supply)": (m.get("gemini_label") or "")[:35],
+            "GapScore": f"{float(m.get('gap_score', 0)):.4f}",
+            "Quadrant": q.replace("_", " ").title(),
+            "액션": strategy["action"],
+            "우선순위": strategy["priority"],
+        })
+
+    df = pd.DataFrame(rows)
+    st.dataframe(df, use_container_width=True, hide_index=True)
+
+    st.markdown("---")
+
+    # --- Detailed Action Cards for Top OPPORTUNITY topics ---
+    opportunity_matches = [m for m in matches if m.get("quadrant") == "OPPORTUNITY"]
+
+    if opportunity_matches:
+        st.markdown("### OPPORTUNITY 토픽 상세 가이드")
+        st.caption(
+            "콘텐츠 제작 ROI가 가장 높은 토픽입니다. "
+            "사용자가 자주 묻지만 AI가 인용할 콘텐츠가 부족합니다."
+        )
+
+        for i, m in enumerate(opportunity_matches[:10], 1):
+            chatgpt_label = m.get("chatgpt_label", "Unknown")
+            gap = float(m.get("gap_score") or 0)
+            demand = float(m.get("demand_percentile") or 0)
+            supply = float(m.get("supply_percentile") or 0)
+
+            chatgpt_detail = chatgpt_map.get(m["chatgpt_cluster_id"], {})
+            gemini_detail = gemini_map.get(m["gemini_cluster_id"], {})
+
+            with st.expander(f"#{i} {chatgpt_label} (GapScore: {gap:.4f})", key=f"research:opp_action:{m['id']}"):
+                left, right = st.columns(2)
+
+                with left:
+                    st.markdown("**Gap 분석**")
+                    st.write(f"- Demand (ChatGPT): {demand:.0%}")
+                    st.write(f"- Supply (Gemini): {supply:.0%}")
+                    st.write(f"- Gap: Demand {demand:.0%} vs Supply {supply:.0%}")
+
+                    # Sample fanouts = what users ask
+                    samples = chatgpt_detail.get("sample_fanouts") or []
+                    if samples:
+                        st.markdown("**사용자가 묻는 질문들:**")
+                        for s in samples[:5]:
+                            st.write(f"  - {s}")
+
+                with right:
+                    st.markdown("**콘텐츠 전략**")
+                    strategy = STRATEGY_TEMPLATES["OPPORTUNITY"]
+                    st.info(strategy["detail"])
+
+                    st.markdown("**구체적 실행 항목:**")
+                    for tactic in strategy["tactics"]:
+                        st.write(f"- {tactic}")
+
+                    # Show Gemini citation examples if available
+                    gemini_samples = gemini_detail.get("sample_fanouts") or []
+                    if gemini_samples:
+                        st.markdown("**AI가 현재 인용하는 문구 예시:**")
+                        for s in gemini_samples[:3]:
+                            st.write(f"  > {s}")
+                        st.caption("이런 형태의 문장을 콘텐츠에 포함하세요.")
+
+                    # Show top sources if available
+                    top_sources = gemini_detail.get("top_sources")
+                    if top_sources and isinstance(top_sources, list):
+                        domains = [s.get("host_url", s.get("url", "")) for s in top_sources[:5]]
+                        if domains:
+                            st.markdown("**현재 AI 인용 출처:**")
+                            for d in domains:
+                                st.write(f"  - {d}")
+                            st.caption("이 출처들이 다루지 않는 각도를 찾으세요.")
+    else:
+        st.success("모든 토픽에 충분한 Supply가 있습니다. 차별화 전략에 집중하세요.")
+
+    # --- SATURATED topics brief ---
+    saturated_matches = [m for m in matches if m.get("quadrant") == "SATURATED"]
+    if saturated_matches:
+        st.markdown("---")
+        st.markdown("### SATURATED 토픽 요약")
+        st.caption("차별화가 필요한 경쟁 토픽입니다.")
+
+        for i, m in enumerate(saturated_matches[:5], 1):
+            label = m.get("chatgpt_label", "Unknown")
+            gap = float(m.get("gap_score", 0))
+
+            with st.expander(f"#{i} {label} (GapScore: {gap:.4f})", key=f"research:sat_action:{m['id']}"):
+                strategy = STRATEGY_TEMPLATES["SATURATED"]
+                st.info(strategy["detail"])
+                st.markdown("**실행 항목:**")
+                for tactic in strategy["tactics"]:
+                    st.write(f"- {tactic}")

features/research/cross_model.py

@@ -0,0 +1,652 @@
+"""Cross-Model Quadrant Matrix + Convergence Analysis (ADR-014 Phase 3).
+
+Demand (ChatGPT fanout) vs Supply (Gemini citation) gap analysis.
+Scatter plot + GapScore Top 10 + Convergence (Venn, matched/unmatched topics).
+"""
+
+import statistics
+
+import streamlit as st
+import pandas as pd
+import plotly.graph_objects as go
+
+from core.supabase_client import (
+    get_cross_model_analysis, get_gap_scores, get_topic_clusters,
+)
+
+
+# Quadrant colors matching ADR-014 spec
+QUADRANT_COLORS = {
+    "OPPORTUNITY": "#10B981",       # Green
+    "SATURATED": "#3B82F6",         # Blue
+    "LATENT_AUTHORITY": "#F59E0B",  # Amber
+    "NICHE": "#9CA3AF",             # Gray
+}
+
+QUADRANT_LABELS = {
+    "OPPORTUNITY": "Opportunity",
+    "SATURATED": "Saturated",
+    "LATENT_AUTHORITY": "Latent Authority",
+    "NICHE": "Niche",
+}
+
+QUADRANT_ACTIONS = {
+    "OPPORTUNITY": "사용자 관심이 높지만 인용 콘텐츠가 부족합니다. "
+                   "이 주제에 전문 콘텐츠를 제작하면 AI 답변에 인용될 가능성이 높습니다.",
+    "SATURATED": "수요와 공급 모두 높은 경쟁 영역입니다. "
+                 "차별화된 전문성이나 고유 데이터로 기존 콘텐츠와 차별화하세요.",
+    "LATENT_AUTHORITY": "이미 인용되고 있지만 검색 수요는 낮습니다. "
+                        "기존 콘텐츠를 활용하여 브랜드 권위를 강화하세요.",
+    "NICHE": "수요와 공급 모두 낮은 틈새 영역입니다. "
+             "시장 변화를 모니터링하며 기회가 커지면 진입을 검토하세요.",
+}
+
+
+def render_cross_model(base_ctx: dict, pair: dict):
+    """Render cross-model quadrant matrix UI.
+
+    Args:
+        base_ctx: Dashboard base context with campaign_id etc.
+        pair: Cross-model pair dict from find_cross_model_pair().
+    """
+    campaign_chatgpt = pair["campaign_chatgpt"]
+    campaign_gemini = pair["campaign_gemini"]
+
+    st.caption(
+        "ChatGPT와 Gemini 두 AI 모델의 토픽을 비교하여 "
+        "**콘텐츠 수요-공급 Gap**을 분석합니다."
+    )
+
+    with st.expander("Cross-Model 분석이란?", expanded=False):
+        st.markdown("""
+**왜 두 모델을 비교하나요?**
+
+ChatGPT와 Gemini는 같은 주제에 대해 서로 다른 방식으로 정보를 탐색합니다:
+- **ChatGPT (Demand)**: 사용자 질문을 여러 하위 질문으로 분해하여 검색합니다.
+  AI가 자주 검색하는 토픽 = **사용자 관심이 높은 토픽**
+- **Gemini (Supply)**: 답변에 실제 웹 콘텐츠를 인용합니다.
+  AI가 자주 인용하는 토픽 = **콘텐츠 공급이 충분한 토픽**
+
+**두 신호를 교차 분석**하면, "사람들이 많이 물어보지만 아직 좋은 콘텐츠가 없는 영역"을
+데이터 기반으로 발견할 수 있습니다.
+
+**분석 프로세스:**
+```
+ChatGPT 하위 질문 클러스터링 (Demand 토픽)
+                    ↓
+Gemini 인용 문구 클러스터링 (Supply 토픽)
+                    ↓
+두 모델의 유사 토픽 매칭 (Label + Centroid 유사도)
+                    ↓
+Demand-Supply Gap 계산 → Quadrant 분류
+```
+""")
+
+    # Fetch data
+    analysis = get_cross_model_analysis(campaign_chatgpt, campaign_gemini)
+    matches = get_gap_scores(campaign_chatgpt, campaign_gemini)
+
+    if not analysis or not matches:
+        st.warning("Cross-Model 분석 데이터를 불러올 수 없습니다.")
+        return
+
+    # Fetch clusters for convergence analysis
+    chatgpt_clusters = get_topic_clusters(campaign_chatgpt, source="chatgpt")
+    gemini_clusters = get_topic_clusters(campaign_gemini, source="gemini")
+
+    # --- A) Alignment Overview ---
+    _render_overview(analysis, matches)
+
+    st.markdown("---")
+
+    # --- B) Quadrant Scatter Plot ---
+    _render_scatter(matches)
+
+    st.markdown("---")
+
+    # --- C) GapScore Top 10 ---
+    _render_top_gaps(matches)
+
+    st.markdown("---")
+
+    # --- D) Convergence Analysis (Phase 3.4) ---
+    _render_convergence(
+        analysis, matches, chatgpt_clusters, gemini_clusters,
+    )
+
+
+def _render_overview(analysis: dict, matches: list[dict]):
+    """Render alignment overview metrics."""
+    alignment = float(analysis.get("nmi_score", 0))
+    total_matched = int(analysis.get("total_matched_topics", 0))
+
+    # Count by quadrant
+    quadrant_counts = {}
+    gap_scores = []
+    for m in matches:
+        q = m.get("quadrant", "NICHE")
+        quadrant_counts[q] = quadrant_counts.get(q, 0) + 1
+        gap_scores.append(float(m.get("gap_score", 0)))
+
+    opp_count = quadrant_counts.get("OPPORTUNITY", 0)
+    mean_gap = sum(gap_scores) / len(gap_scores) if gap_scores else 0
+
+    # Color-code alignment
+    if alignment >= 0.8:
+        align_color = "green"
+        align_label = "Strong"
+    elif alignment >= 0.6:
+        align_color = "orange"
+        align_label = "Moderate"
+    else:
+        align_color = "red"
+        align_label = "Weak"
+
+    c1, c2, c3, c4 = st.columns(4)
+    with c1:
+        st.metric(
+            "모델 정합도", f"{alignment:.4f}",
+            help="ChatGPT와 Gemini 토픽 매칭 품질. "
+                 "0.5 이상이면 두 모델이 유사한 주제를 다루고 있어 Gap 분석이 신뢰할 수 있습니다.",
+        )
+        st.caption(f":{align_color}[{align_label}]")
+    with c2:
+        st.metric(
+            "매칭된 토픽", f"{total_matched}쌍",
+            help="두 AI 모델에서 동일한 주제로 매칭된 토픽 쌍 수",
+        )
+    with c3:
+        st.metric(
+            "콘텐츠 기회", f"{opp_count}개",
+            help="Demand 높음 + Supply 낮음인 토픽 수. "
+                 "이 토픽들에 콘텐츠를 만들면 AI 인용 가능성이 높습니다.",
+        )
+    with c4:
+        st.metric(
+            "평균 GapScore", f"{mean_gap:.4f}",
+            help="전체 매칭 토픽의 평균 Demand-Supply Gap. "
+                 "높을수록 전반적으로 콘텐츠 기회가 많음을 의미합니다.",
+        )
+
+
+def _render_scatter(matches: list[dict]):
+    """Render demand vs supply quadrant scatter plot."""
+    st.markdown("""
+**ChatGPT가 자주 검색하는 토픽**(Demand)과 **Gemini가 실제 인용하는 토픽**(Supply)을 매칭하여
+콘텐츠 기회를 시각화합니다. 각 점은 두 AI 모델에서 동일한 주제로 매칭된 토픽 쌍입니다.
+
+| Quadrant | 위치 | 의미 | 전략 |
+|----------|------|------|------|
+| **Opportunity** | 좌상단 | Demand 높음 + Supply 낮음 | 콘텐츠 선점 기회 -- 우선 제작 |
+| **Saturated** | 우상단 | Demand 높음 + Supply 높음 | 차별화 필요 -- 전문성 강화 |
+| **Latent Authority** | 우하단 | Demand 낮음 + Supply 높음 | 이미 인용됨 -- 브랜드 권위 활용 |
+| **Niche** | 좌하단 | Demand 낮음 + Supply 낮음 | 낮은 우선순위 -- 변화 모니터링 |
+""")
+
+    xs, ys, colors, hover_texts, sizes = [], [], [], [], []
+
+    for m in matches:
+        supply = float(m.get("supply_percentile", 0))
+        demand = float(m.get("demand_percentile", 0))
+        quadrant = m.get("quadrant", "NICHE")
+        gap = float(m.get("gap_score", 0))
+        match_score = float(m.get("match_score", 0))
+        chatgpt_label = m.get("chatgpt_label", "")
+        gemini_label = m.get("gemini_label", "")
+
+        xs.append(supply)
+        ys.append(demand)
+        colors.append(QUADRANT_COLORS.get(quadrant, "#9CA3AF"))
+        sizes.append(max(8, min(30, gap * 300)))
+
+        hover_texts.append(
+            f"<b>{chatgpt_label}</b><br>"
+            f"Gemini: {gemini_label}<br>"
+            f"Demand: {demand:.2%}<br>"
+            f"Supply: {supply:.2%}<br>"
+            f"GapScore: {gap:.4f}<br>"
+            f"Match: {match_score:.4f}<br>"
+            f"Quadrant: {QUADRANT_LABELS.get(quadrant, quadrant)}"
+        )
+
+    fig = go.Figure()
+
+    fig.add_trace(go.Scatter(
+        x=xs,
+        y=ys,
+        mode="markers",
+        marker=dict(
+            size=sizes,
+            color=colors,
+            opacity=0.7,
+            line=dict(width=0.5, color="#333"),
+        ),
+        text=hover_texts,
+        hoverinfo="text",
+        showlegend=False,
+    ))
+
+    # Compute actual medians from data (matches quadrant_method=p50_median in gap scorer)
+    demand_median = statistics.median(ys) if len(ys) > 1 else 0.5
+    supply_median = statistics.median(xs) if len(xs) > 1 else 0.5
+
+    fig.add_hline(y=demand_median, line_dash="dash", line_color="#9CA3AF", opacity=0.5)
+    fig.add_vline(x=supply_median, line_dash="dash", line_color="#9CA3AF", opacity=0.5)
+
+    # Quadrant annotations — axes: X=Supply, Y=Demand
+    # OPPORTUNITY:       high demand (top) + low supply (left)  → top-left
+    # SATURATED:         high demand (top) + high supply (right) → top-right
+    # LATENT_AUTHORITY:  low demand (bottom) + high supply (right) → bottom-right
+    # NICHE:             low demand (bottom) + low supply (left)  → bottom-left
+    fig.add_annotation(x=0.05, y=0.95, text="Opportunity",
+                       showarrow=False, font=dict(size=11, color=QUADRANT_COLORS["OPPORTUNITY"]))
+    fig.add_annotation(x=0.95, y=0.95, text="Saturated",
+                       showarrow=False, font=dict(size=11, color=QUADRANT_COLORS["SATURATED"]))
+    fig.add_annotation(x=0.95, y=0.05, text="Latent Authority",
+                       showarrow=False, font=dict(size=11, color=QUADRANT_COLORS["LATENT_AUTHORITY"]))
+    fig.add_annotation(x=0.05, y=0.05, text="Niche",
+                       showarrow=False, font=dict(size=11, color=QUADRANT_COLORS["NICHE"]))
+
+    fig.update_layout(
+        title="Demand vs Supply Quadrant Matrix",
+        xaxis_title="Supply Percentile (Gemini Citation)",
+        yaxis_title="Demand Percentile (ChatGPT Fanout)",
+        xaxis=dict(range=[-0.05, 1.05]),
+        yaxis=dict(range=[-0.05, 1.05]),
+        height=600,
+        template="plotly_white",
+        hoverlabel=dict(bgcolor="white", font_size=12),
+    )
+
+    st.plotly_chart(fig, use_container_width=True, key="cross_model:scatter", config={"displayModeBar": False})
+
+    # Quadrant count summary
+    quadrant_counts = {}
+    for m in matches:
+        q = m.get("quadrant", "NICHE")
+        quadrant_counts[q] = quadrant_counts.get(q, 0) + 1
+
+    q1, q2, q3, q4 = st.columns(4)
+    with q1:
+        st.metric("🟢 Opportunity", f"{quadrant_counts.get('OPPORTUNITY', 0)}개",
+                   help="AI가 자주 검색하지만 인용 콘텐츠가 부족한 토픽. 콘텐츠 선점 기회.")
+    with q2:
+        st.metric("🔵 Saturated", f"{quadrant_counts.get('SATURATED', 0)}개",
+                   help="검색도 많고 인용도 많은 경쟁 토픽. 차별화 전략 필요.")
+    with q3:
+        st.metric("🟡 Latent Authority", f"{quadrant_counts.get('LATENT_AUTHORITY', 0)}개",
+                   help="이미 인용되고 있지만 검색 수요는 낮은 토픽. 브랜드 권위 활용.")
+    with q4:
+        st.metric("⚪ Niche", f"{quadrant_counts.get('NICHE', 0)}개",
+                   help="수요와 공급 모두 낮은 틈새 영역. 변화 모니터링.")
+
+    st.caption(f"Demand Median: {demand_median:.4f} | Supply Median: {supply_median:.4f}")
+
+
+def _render_top_gaps(matches: list[dict]):
+    """Render GapScore Top 10 with detail expanders."""
+    st.markdown("#### GapScore Top 10")
+    st.caption("Demand-Supply Gap이 큰 토픽일수록 콘텐츠 기회가 높습니다.")
+
+    top10 = matches[:10]
+
+    for i, m in enumerate(top10, 1):
+        chatgpt_label = m.get("chatgpt_label", "Unknown")
+        gemini_label = m.get("gemini_label", "Unknown")
+        gap = float(m.get("gap_score", 0))
+        quadrant = m.get("quadrant", "NICHE")
+
+        with st.expander(
+            f"#{i}  {chatgpt_label}  |  GapScore: {gap:.4f}",
+            key=f"cross_model:gap_{m['id']}",
+        ):
+            left, right = st.columns(2)
+
+            with left:
+                demand = float(m.get("demand_percentile") or 0)
+                supply = float(m.get("supply_percentile") or 0)
+                match_score = float(m.get("match_score") or 0)
+
+                st.markdown("**Metrics**")
+                st.write(f"- Demand Percentile: {demand:.2%}")
+                st.write(f"- Supply Percentile: {supply:.2%}")
+                st.write(f"- Match Score: {match_score:.4f}")
+                st.write(f"- ChatGPT Topic: {chatgpt_label}")
+                st.write(f"- Gemini Topic: {gemini_label}")
+
+            with right:
+                q_label = QUADRANT_LABELS.get(quadrant, quadrant)
+                action = QUADRANT_ACTIONS.get(quadrant, "")
+
+                st.markdown("**Quadrant & Action**")
+                st.markdown(f":{_st_color(quadrant)}[**{q_label}**]")
+                st.info(action)
+
+
+def _st_color(quadrant: str) -> str:
+    """Map quadrant to Streamlit markdown color name."""
+    return {
+        "OPPORTUNITY": "green",
+        "SATURATED": "blue",
+        "LATENT_AUTHORITY": "orange",
+        "NICHE": "gray",
+    }.get(quadrant, "gray")
+
+
+# ---------------------------------------------------------------------------
+# Phase 3.4: Convergence Analysis
+# ---------------------------------------------------------------------------
+
+def _render_convergence(
+    analysis: dict,
+    matches: list[dict],
+    chatgpt_clusters: list[dict],
+    gemini_clusters: list[dict],
+):
+    """Render convergence analysis: Venn, matched/unmatched topic lists."""
+    st.markdown("#### 수렴 분석 (Convergence)")
+    st.caption(
+        "ChatGPT(Demand)와 Gemini(Supply) 토픽이 얼마나 겹치는지 분석합니다. "
+        "매칭되지 않은 토픽은 한쪽 모델에서만 나타나는 고유 신호입니다."
+    )
+
+    # Compute matched / unmatched sets
+    matched_chatgpt_ids = {m["chatgpt_cluster_id"] for m in matches}
+    matched_gemini_ids = {m["gemini_cluster_id"] for m in matches}
+
+    all_chatgpt_ids = {c["id"] for c in chatgpt_clusters}
+    all_gemini_ids = {c["id"] for c in gemini_clusters}
+
+    unmatched_chatgpt_ids = all_chatgpt_ids - matched_chatgpt_ids
+    unmatched_gemini_ids = all_gemini_ids - matched_gemini_ids
+
+    n_chatgpt_only = len(unmatched_chatgpt_ids)
+    n_matched = len(matches)
+    n_gemini_only = len(unmatched_gemini_ids)
+    n_total = n_chatgpt_only + n_matched + n_gemini_only
+
+    # --- Venn-style overlap chart ---
+    _render_venn_chart(n_chatgpt_only, n_matched, n_gemini_only)
+
+    # --- Alignment Score gauge ---
+    alignment = float(analysis.get("nmi_score") or 0)
+    _render_alignment_gauge(alignment, n_matched, n_total)
+
+    st.markdown("---")
+
+    # --- Matched topics table ---
+    _render_matched_topics(matches)
+
+    st.markdown("---")
+
+    # --- Unmatched topics per model ---
+    _render_unmatched_topics(
+        chatgpt_clusters, gemini_clusters,
+        unmatched_chatgpt_ids, unmatched_gemini_ids,
+    )
+
+
+def _render_venn_chart(
+    n_chatgpt_only: int, n_matched: int, n_gemini_only: int,
+):
+    """Render Venn-style horizontal stacked bar showing overlap proportions."""
+    n_total = n_chatgpt_only + n_matched + n_gemini_only
+    if n_total == 0:
+        return
+
+    pct_chatgpt = n_chatgpt_only / n_total * 100
+    pct_matched = n_matched / n_total * 100
+    pct_gemini = n_gemini_only / n_total * 100
+
+    fig = go.Figure()
+
+    fig.add_trace(go.Bar(
+        y=["토픽 분포"],
+        x=[pct_chatgpt],
+        name=f"ChatGPT 고유 ({n_chatgpt_only})",
+        orientation="h",
+        marker_color="#3B82F6",
+        text=f"{pct_chatgpt:.0f}%",
+        textposition="inside",
+        hovertemplate=(
+            f"ChatGPT 고유 토픽: {n_chatgpt_only}개<br>"
+            f"비율: {pct_chatgpt:.1f}%<extra></extra>"
+        ),
+    ))
+    fig.add_trace(go.Bar(
+        y=["토픽 분포"],
+        x=[pct_matched],
+        name=f"공통 매칭 ({n_matched})",
+        orientation="h",
+        marker_color="#10B981",
+        text=f"{pct_matched:.0f}%",
+        textposition="inside",
+        hovertemplate=(
+            f"공통 매칭 토픽: {n_matched}개<br>"
+            f"비율: {pct_matched:.1f}%<extra></extra>"
+        ),
+    ))
+    fig.add_trace(go.Bar(
+        y=["토픽 분포"],
+        x=[pct_gemini],
+        name=f"Gemini 고유 ({n_gemini_only})",
+        orientation="h",
+        marker_color="#F59E0B",
+        text=f"{pct_gemini:.0f}%",
+        textposition="inside",
+        hovertemplate=(
+            f"Gemini 고유 토픽: {n_gemini_only}개<br>"
+            f"비율: {pct_gemini:.1f}%<extra></extra>"
+        ),
+    ))
+
+    fig.update_layout(
+        barmode="stack",
+        height=120,
+        margin=dict(l=0, r=0, t=30, b=0),
+        title="토픽 겹침 분포 (Venn)",
+        xaxis=dict(title="비율 (%)", range=[0, 100]),
+        yaxis=dict(visible=False),
+        template="plotly_white",
+        legend=dict(orientation="h", yanchor="bottom", y=-0.5),
+    )
+
+    st.plotly_chart(fig, use_container_width=True, key="cross_model:venn", config={"displayModeBar": False})
+
+    # Summary metrics
+    c1, c2, c3 = st.columns(3)
+    with c1:
+        st.metric(
+            "ChatGPT 고유",
+            f"{n_chatgpt_only}개",
+            help="ChatGPT에서만 발견된 Demand 토픽. "
+                 "소비자가 관심 있지만 Gemini가 아직 인용하지 않는 영역.",
+        )
+    with c2:
+        st.metric(
+            "공통 매칭",
+            f"{n_matched}개",
+            help="두 모델 모두에서 발견된 토픽. "
+                 "Demand와 Supply가 만나는 핵심 영역.",
+        )
+    with c3:
+        st.metric(
+            "Gemini 고유",
+            f"{n_gemini_only}개",
+            help="Gemini에서만 인용되는 Supply 토픽. "
+                 "AI가 근거로 사용하지만 소비자 검색 수요가 낮은 영역.",
+        )
+
+
+def _render_alignment_gauge(alignment: float, n_matched: int, n_total: int):
+    """Render alignment score as a gauge chart with interpretation."""
+    coverage = n_matched / n_total * 100 if n_total > 0 else 0
+
+    fig = go.Figure(go.Indicator(
+        mode="gauge+number",
+        value=alignment,
+        number=dict(suffix="", valueformat=".4f"),
+        gauge=dict(
+            axis=dict(range=[0, 1], tickvals=[0, 0.3, 0.6, 0.8, 1.0]),
+            bar=dict(color="#059669"),
+            steps=[
+                dict(range=[0, 0.3], color="#FEE2E2"),
+                dict(range=[0.3, 0.6], color="#FEF3C7"),
+                dict(range=[0.6, 0.8], color="#D1FAE5"),
+                dict(range=[0.8, 1.0], color="#A7F3D0"),
+            ],
+            threshold=dict(
+                line=dict(color="#059669", width=2),
+                thickness=0.75,
+                value=alignment,
+            ),
+        ),
+        title=dict(text="Alignment Score"),
+    ))
+
+    fig.update_layout(
+        height=250,
+        margin=dict(l=30, r=30, t=50, b=10),
+        template="plotly_white",
+    )
+
+    left, right = st.columns([2, 1])
+    with left:
+        st.plotly_chart(fig, use_container_width=True, key="cross_model:gauge", config={"displayModeBar": False})
+    with right:
+        if alignment >= 0.8:
+            st.success(
+                f"**Strong** — 두 모델이 매우 유사한 토픽을 다루고 있습니다. "
+                f"Gap 분석의 신뢰도가 높습니다."
+            )
+        elif alignment >= 0.6:
+            st.warning(
+                f"**Moderate** — 부분적으로 겹치는 토픽이 있습니다. "
+                f"Gap 분석은 참고용으로 활용하세요."
+            )
+        else:
+            st.error(
+                f"**Weak** — 두 모델의 토픽 유사도가 낮습니다. "
+                f"각 모델의 개별 뷰를 우선 참고하세요."
+            )
+        st.caption(f"토픽 커버리지: {coverage:.1f}% ({n_matched}/{n_total})")
+
+
+def _render_matched_topics(matches: list[dict]):
+    """Render matched topic pairs table with scores."""
+    st.markdown("#### 매칭된 토픽 쌍")
+    st.caption(
+        "두 모델에서 동일한 주제로 매칭된 토픽입니다. "
+        "Match Score가 높을수록 두 토픽의 유사도가 높습니다."
+    )
+
+    rows = []
+    for i, m in enumerate(matches, 1):
+        rows.append({
+            "#": i,
+            "ChatGPT 토픽": (m.get("chatgpt_label") or "")[:35],
+            "Gemini 토픽": (m.get("gemini_label") or "")[:35],
+            "Match Score": f"{float(m.get('match_score') or 0):.4f}",
+            "Label Sim": f"{float(m.get('label_similarity') or 0):.4f}",
+            "Centroid Sim": f"{float(m.get('centroid_similarity') or 0):.4f}",
+            "GapScore": f"{float(m.get('gap_score') or 0):.4f}",
+            "Quadrant": QUADRANT_LABELS.get(m.get("quadrant", "NICHE"), "Niche"),
+        })
+
+    if rows:
+        df = pd.DataFrame(rows)
+        st.dataframe(df, use_container_width=True, hide_index=True)
+
+    # Match quality stats
+    if matches:
+        scores = [float(m.get("match_score") or 0) for m in matches]
+        avg_score = sum(scores) / len(scores)
+        min_score = min(scores)
+        max_score = max(scores)
+        st.caption(
+            f"Match Score — 평균: {avg_score:.4f} | "
+            f"최소: {min_score:.4f} | 최대: {max_score:.4f}"
+        )
+
+
+def _render_unmatched_topics(
+    chatgpt_clusters: list[dict],
+    gemini_clusters: list[dict],
+    unmatched_chatgpt_ids: set,
+    unmatched_gemini_ids: set,
+):
+    """Render unmatched (model-specific) topics."""
+    st.markdown("#### 모델별 고유 토픽")
+    st.caption(
+        "한쪽 모델에서만 나타나는 토픽입니다. "
+        "매칭되지 않은 토픽은 해당 모델 고유의 신호를 나타냅니다."
+    )
+
+    left, right = st.columns(2)
+
+    with left:
+        st.markdown("**ChatGPT 고유 토픽 (Demand Only)**")
+        st.caption(
+            "소비자가 관심 있지만 Gemini가 인용하지 않는 토픽. "
+            "아직 콘텐츠가 부족하여 AI가 근거를 찾지 못하는 영역일 수 있습니다."
+        )
+
+        unmatched_chatgpt = [
+            c for c in chatgpt_clusters if c["id"] in unmatched_chatgpt_ids
+        ]
+        # Sort by opportunity_score DESC (already sorted from DB, but filter may reorder)
+        unmatched_chatgpt.sort(
+            key=lambda c: float(c.get("opportunity_score") or 0), reverse=True,
+        )
+
+        if unmatched_chatgpt:
+            rows = []
+            for c in unmatched_chatgpt[:20]:
+                rows.append({
+                    "토픽": (c.get("cluster_label") or f"Cluster-{c['id'][:8]}")[:30],
+                    "Opportunity": f"{float(c.get('opportunity_score') or 0):.4f}",
+                    "Attention": f"{float(c.get('attention_score') or 0):.4f}",
+                    "Fanouts": c.get("fanout_count", 0),
+                })
+            st.dataframe(
+                pd.DataFrame(rows),
+                use_container_width=True,
+                hide_index=True,
+            )
+            if len(unmatched_chatgpt) > 20:
+                st.caption(f"... 외 {len(unmatched_chatgpt) - 20}개")
+        else:
+            st.info("모든 ChatGPT 토픽이 Gemini와 매칭되었습니다.")
+
+    with right:
+        st.markdown("**Gemini 고유 토픽 (Supply Only)**")
+        st.caption(
+            "AI가 인용하지만 소비자 검색 수요가 낮은 토픽. "
+            "잠재적 권위(Latent Authority) 영역이거나, 향후 수요가 증가할 수 있습니다."
+        )
+
+        unmatched_gemini = [
+            c for c in gemini_clusters if c["id"] in unmatched_gemini_ids
+        ]
+        unmatched_gemini.sort(
+            key=lambda c: float(c.get("opportunity_score") or 0), reverse=True,
+        )
+
+        if unmatched_gemini:
+            rows = []
+            for c in unmatched_gemini[:20]:
+                rows.append({
+                    "토픽": (c.get("cluster_label") or f"Cluster-{c['id'][:8]}")[:30],
+                    "Opportunity": f"{float(c.get('opportunity_score') or 0):.4f}",
+                    "Density": f"{float(c.get('citation_density') or 0):.4f}",
+                    "Citations": c.get("fanout_count", 0),
+                })
+            st.dataframe(
+                pd.DataFrame(rows),
+                use_container_width=True,
+                hide_index=True,
+            )
+            if len(unmatched_gemini) > 20:
+                st.caption(f"... 외 {len(unmatched_gemini) - 20}개")
+        else:
+            st.info("모든 Gemini 토픽이 ChatGPT와 매칭되었습니다.")

features/research/distribution.py

@@ -0,0 +1,186 @@
+"""Attention vs Density 4-Quadrant Scatter.
+
+X-axis: attention_score
+Y-axis: citation_density
+Quadrant lines at median values.
+Point size: fanout_count, hover: cluster_label.
+"""
+
+import statistics
+
+import streamlit as st
+import plotly.graph_objects as go
+
+
+# Quadrant colors
+QUAD_COLORS = {
+    "high_attn_low_density": "#10B981",   # Green - Opportunity
+    "high_attn_high_density": "#3B82F6",  # Blue - Competitive
+    "low_attn_low_density": "#9CA3AF",    # Gray - Niche
+    "low_attn_high_density": "#EF4444",   # Red - Crowded
+}
+
+
+def render_distribution(clusters: list[dict], frame: str = "all"):
+    """Render attention vs density quadrant scatter chart."""
+    scored = [
+        c for c in clusters
+        if c.get("attention_score") is not None
+        and c.get("citation_density") is not None
+    ]
+
+    if not scored:
+        st.info("스코어가 계산된 클러스터가 없습니다.")
+        return
+
+    # 4-Quadrant business interpretation (frame-specific)
+    if frame == "demand":
+        st.markdown("""
+ChatGPT Demand 토픽을 **검색 빈도**(가로축)와 **출처 경쟁**(세로축)로 분류합니다:
+- **Opportunity** (우하단): 검색 빈도 높음 + 경쟁 낮음 → 콘텐츠 선점 기회
+- **Competitive** (우상단): 검색 빈도 높음 + 경쟁 높음 → 차별화 필요
+- **Niche** (좌하단): 검색 빈도 낮음 + 경쟁 낮음 → 틈새 영역
+- **Crowded** (좌상단): 검색 빈도 낮음 + 경쟁 높음 → 포화 영역
+""")
+    elif frame == "supply":
+        st.markdown("""
+Gemini Supply 토픽을 **인용 빈도**(가로축)와 **출처 집중도**(세로축)로 분류합니다:
+- **Opportunity** (우하단): 인용 빈도 높음 + 출처 분산 → 새 출처 진입 기회
+- **Competitive** (우상단): 인용 빈도 높음 + 출처 집중 → 기존 권위자 지배
+- **Niche** (좌하단): 인용 빈도 낮음 + 출처 분산 → 틈새 영역
+- **Crowded** (좌상단): 인용 빈도 낮음 + 출처 집중 → 포화 영역
+""")
+    else:
+        st.markdown("""
+토픽을 **AI 관심도**(가로축)와 **경쟁 밀도**(세로축)로 분류합니다:
+- **Opportunity** (우하단): AI 관심 높음 + 경쟁 낮음 → 콘텐츠 선점 기회
+- **Competitive** (우상단): AI 관심 높음 + 경쟁 높음 → 차별화 필요
+- **Niche** (좌하단): AI 관심 낮음 + 경쟁 낮음 → 틈새 영역
+- **Crowded** (좌상단): AI 관심 낮음 + 경쟁 높음 → 포화 영역
+""")
+
+    attns = [float(c["attention_score"]) for c in scored]
+    densities = [float(c["citation_density"]) for c in scored]
+
+    median_attn = statistics.median(attns)
+    median_density = statistics.median(densities)
+
+    # Classify each point into quadrant
+    xs, ys, sizes, colors, hover_texts = [], [], [], [], []
+    quadrant_counts = {"opportunity": 0, "competitive": 0, "niche": 0, "crowded": 0}
+
+    for c in scored:
+        attn = float(c["attention_score"])
+        density = float(c["citation_density"])
+        fanout_count = c.get("fanout_count", 10)
+        label = c.get("cluster_label") or f"Cluster-{c['id'][:8]}"
+
+        xs.append(attn)
+        ys.append(density)
+        sizes.append(max(5, min(35, fanout_count / 5)))
+
+        if attn >= median_attn and density < median_density:
+            color = QUAD_COLORS["high_attn_low_density"]
+            quad = "Opportunity"
+            quadrant_counts["opportunity"] += 1
+        elif attn >= median_attn and density >= median_density:
+            color = QUAD_COLORS["high_attn_high_density"]
+            quad = "Competitive"
+            quadrant_counts["competitive"] += 1
+        elif attn < median_attn and density < median_density:
+            color = QUAD_COLORS["low_attn_low_density"]
+            quad = "Niche"
+            quadrant_counts["niche"] += 1
+        else:
+            color = QUAD_COLORS["low_attn_high_density"]
+            quad = "Crowded"
+            quadrant_counts["crowded"] += 1
+
+        colors.append(color)
+        opp = float(c.get("opportunity_score", 0) or 0)
+        hover_texts.append(
+            f"<b>{label}</b><br>"
+            f"Attention: {attn:.4f}<br>"
+            f"Density: {density:.4f}<br>"
+            f"Opportunity: {opp:.4f}<br>"
+            f"Fanouts: {fanout_count}<br>"
+            f"Quadrant: {quad}"
+        )
+
+    fig = go.Figure()
+
+    # Data points
+    fig.add_trace(go.Scatter(
+        x=xs,
+        y=ys,
+        mode="markers",
+        marker=dict(
+            size=sizes,
+            color=colors,
+            opacity=0.7,
+            line=dict(width=0.5, color="#333"),
+        ),
+        text=hover_texts,
+        hoverinfo="text",
+        showlegend=False,
+    ))
+
+    # Quadrant lines (add padding to avoid collapse when all values are identical)
+    attn_span = max(attns) - min(attns) or 0.001
+    density_span = max(densities) - min(densities) or 0.1
+    x_range = [min(attns) - attn_span * 0.1, max(attns) + attn_span * 0.1]
+    y_range = [min(densities) - density_span * 0.1, max(densities) + density_span * 0.1]
+
+    fig.add_hline(y=median_density, line_dash="dash", line_color="#9CA3AF", opacity=0.5)
+    fig.add_vline(x=median_attn, line_dash="dash", line_color="#9CA3AF", opacity=0.5)
+
+    # Quadrant labels
+    fig.add_annotation(x=x_range[1], y=y_range[0], text="🟢 Opportunity",
+                       showarrow=False, font=dict(size=11, color=QUAD_COLORS["high_attn_low_density"]))
+    fig.add_annotation(x=x_range[1], y=y_range[1], text="🔵 Competitive",
+                       showarrow=False, font=dict(size=11, color=QUAD_COLORS["high_attn_high_density"]))
+    fig.add_annotation(x=x_range[0], y=y_range[0], text="⚪ Niche",
+                       showarrow=False, font=dict(size=11, color=QUAD_COLORS["low_attn_low_density"]))
+    fig.add_annotation(x=x_range[0], y=y_range[1], text="🔴 Crowded",
+                       showarrow=False, font=dict(size=11, color=QUAD_COLORS["low_attn_high_density"]))
+
+    fig.update_layout(
+        title="Attention vs Citation Density (4-Quadrant)",
+        xaxis_title="Attention Score",
+        yaxis_title="Citation Density",
+        height=600,
+        template="plotly_white",
+        hoverlabel=dict(bgcolor="white", font_size=12),
+    )
+
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+    # Quadrant summary with action guides
+    st.markdown("#### Quadrant 요약")
+    q1, q2, q3, q4 = st.columns(4)
+    with q1:
+        st.metric(
+            "🟢 Opportunity", f"{quadrant_counts['opportunity']}개",
+            help="AI 관심도 높음 + 경쟁 낮음 → 콘텐츠 선점 기회. "
+                 "이 토픽에 대한 전문 콘텐츠를 제작하면 AI 답변에 인용될 가능성이 높습니다.",
+        )
+    with q2:
+        st.metric(
+            "🔵 Competitive", f"{quadrant_counts['competitive']}개",
+            help="AI 관심도 높음 + 경쟁 높음 → 경쟁 치열. "
+                 "차별화된 콘텐츠나 전문성이 필요합니다.",
+        )
+    with q3:
+        st.metric(
+            "⚪ Niche", f"{quadrant_counts['niche']}개",
+            help="AI 관심도 낮음 + 경쟁 낮음 → 틈새 영역. "
+                 "시장이 성장하면 선점 효과를 볼 수 있습니다.",
+        )
+    with q4:
+        st.metric(
+            "🔴 Crowded", f"{quadrant_counts['crowded']}개",
+            help="AI 관심도 낮음 + 경쟁 높음 → 포화 영역. "
+                 "새로운 진출보다 기존 콘텐츠 유지에 집중하세요.",
+        )
+
+    st.caption(f"Median Attention: {median_attn:.4f} | Median Density: {median_density:.4f}")

features/research/guide.py

@@ -0,0 +1,143 @@
+"""분석 가이드 - 토픽 인텔리전스 데이터 흐름 설명.
+
+비기술 사용자를 위한 파이프라인, 점수 계산, 용어, 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(
+            "캠페인별로 클러스터링을 실행할 때 데이터가 갱신됩니다. "
+            "현재는 수동 실행 방식이며, 추후 자동 갱신이 추가될 예정입니다."
+        )

features/research/keyword_suggest.py

@@ -0,0 +1,195 @@
+"""키워드 추천 (R-6).
+
+클러스터의 sample_fanouts에서 빈도 높은 키워드/n-gram을 추출하여
+콘텐츠 기회가 높은 키워드를 추천합니다.
+"""
+
+import re
+from collections import Counter
+
+import streamlit as st
+import pandas as pd
+
+
+# Common stopwords (English + Korean particles)
+_STOPWORDS = {
+    # English
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "shall", "can", "need", "dare", "ought",
+    "used", "to", "of", "in", "for", "on", "with", "at", "by", "from",
+    "as", "into", "through", "during", "before", "after", "above", "below",
+    "between", "out", "off", "over", "under", "again", "further", "then",
+    "once", "here", "there", "when", "where", "why", "how", "all", "each",
+    "every", "both", "few", "more", "most", "other", "some", "such", "no",
+    "nor", "not", "only", "own", "same", "so", "than", "too", "very",
+    "just", "because", "but", "and", "or", "if", "while", "about", "what",
+    "which", "who", "whom", "this", "that", "these", "those", "am", "it",
+    "its", "my", "your", "his", "her", "our", "their", "me", "him", "us",
+    "them", "i", "you", "he", "she", "we", "they",
+    "best", "top", "vs", "good", "new", "review", "reviews",
+    # Korean particles
+    "의", "에", "를", "을", "이", "가", "은", "는", "로", "으로", "와", "과",
+    "도", "만", "까지", "부터", "에서", "한", "된", "되는", "하는", "있는",
+}
+
+
+def _tokenize(text: str) -> list[str]:
+    """Simple tokenization: lowercase, split on non-alphanumeric (preserving Korean)."""
+    text = text.lower().strip()
+    # Split on whitespace and punctuation, keeping Korean characters
+    tokens = re.findall(r"[a-z0-9\uac00-\ud7af]+", text)
+    return [t for t in tokens if t not in _STOPWORDS and len(t) >= 2]
+
+
+def _extract_ngrams(texts: list[str], n: int = 2) -> Counter:
+    """Extract n-grams from a list of texts."""
+    ngram_counter = Counter()
+    for text in texts:
+        tokens = _tokenize(text)
+        for i in range(len(tokens) - n + 1):
+            ngram = " ".join(tokens[i:i + n])
+            ngram_counter[ngram] += 1
+    return ngram_counter
+
+
+def render_keyword_suggestions(clusters: list[dict], frame: str = "all"):
+    """Render keyword suggestions extracted from cluster sample_fanouts."""
+    # Frame-specific description
+    if frame == "supply":
+        st.caption(
+            "Gemini 인용 문구에서 추출한 키워드입니다. "
+            "AI가 실제로 인용하는 핵심 표현을 파악하여 콘텐츠에 반영하세요."
+        )
+    elif frame == "demand":
+        st.caption(
+            "ChatGPT sub-query에서 추출한 키워드입니다. "
+            "소비자가 AI에게 물어보는 핵심 표현을 파악하여 콘텐츠를 최적화하세요."
+        )
+    else:
+        st.caption(
+            "AI 토픽 클러스터에서 추출한 핵심 키워드입니다. "
+            "빈도가 높을수록 AI가 자주 다루는 표현입니다."
+        )
+
+    # Collect all sample texts
+    all_samples = []
+    cluster_samples = {}  # cluster_label -> samples
+    for c in clusters:
+        samples = c.get("sample_fanouts") or []
+        label = c.get("cluster_label") or "Unknown"
+        opp = float(c.get("opportunity_score", 0) or 0)
+        all_samples.extend(samples)
+        if samples:
+            cluster_samples[label] = {
+                "samples": samples,
+                "opportunity": opp,
+                "fanout_count": c.get("fanout_count", 0),
+            }
+
+    if not all_samples:
+        st.info("클러스터에 샘플 데이터가 없습니다.")
+        return
+
+    # --- Unigram Analysis ---
+    st.markdown("### 단일 키워드 (Unigram)")
+
+    unigram_counter = Counter()
+    for text in all_samples:
+        tokens = _tokenize(text)
+        unigram_counter.update(tokens)
+
+    top_unigrams = unigram_counter.most_common(30)
+
+    if top_unigrams:
+        uni_df = pd.DataFrame(top_unigrams, columns=["키워드", "빈도"])
+        uni_df.index = range(1, len(uni_df) + 1)
+        uni_df.index.name = "순위"
+
+        col1, col2 = st.columns([2, 1])
+        with col1:
+            st.dataframe(uni_df, use_container_width=True)
+        with col2:
+            st.metric("고유 키워드", f"{len(unigram_counter):,}개")
+            st.metric("총 토큰", f"{sum(unigram_counter.values()):,}개")
+            st.metric("분석 텍스트", f"{len(all_samples):,}개")
+
+    st.markdown("---")
+
+    # --- Bigram Analysis ---
+    st.markdown("### 키워드 조합 (Bigram)")
+
+    bigram_counter = _extract_ngrams(all_samples, n=2)
+    top_bigrams = bigram_counter.most_common(20)
+
+    if top_bigrams:
+        bi_df = pd.DataFrame(top_bigrams, columns=["키워드 조합", "빈도"])
+        bi_df.index = range(1, len(bi_df) + 1)
+        bi_df.index.name = "순위"
+        st.dataframe(bi_df, use_container_width=True)
+
+    st.markdown("---")
+
+    # --- Opportunity-Weighted Keywords ---
+    st.markdown("### 기회 가중 키워드")
+    st.caption(
+        "Opportunity Score가 높은 클러스터에서 많이 등장하는 키워드입니다. "
+        "이 키워드를 콘텐츠에 포함하면 AI 노출 기회가 높아집니다."
+    )
+
+    # Weight keywords by cluster opportunity score
+    weighted_counter = Counter()
+    for label, info in cluster_samples.items():
+        opp = info["opportunity"]
+        tokens_in_cluster = Counter()
+        for text in info["samples"]:
+            tokens_in_cluster.update(_tokenize(text))
+        # Weight by opportunity score (normalize by cluster token total to avoid volume bias)
+        total = sum(tokens_in_cluster.values()) or 1
+        for token, count in tokens_in_cluster.items():
+            weighted_counter[token] += (count / total) * opp
+
+    top_weighted = weighted_counter.most_common(20)
+
+    if top_weighted:
+        w_df = pd.DataFrame(top_weighted, columns=["키워드", "가중 점수"])
+        w_df["가중 점수"] = w_df["가중 점수"].apply(lambda x: f"{x:.4f}")
+        w_df.index = range(1, len(w_df) + 1)
+        w_df.index.name = "순위"
+        st.dataframe(w_df, use_container_width=True)
+
+    st.markdown("---")
+
+    # --- Per-Cluster Keyword Breakdown ---
+    st.markdown("### 클러스터별 핵심 키워드")
+    st.caption("각 토픽 클러스터의 대표 키워드입니다. Opportunity Score 순으로 정렬.")
+
+    sorted_clusters = sorted(
+        cluster_samples.items(),
+        key=lambda x: x[1]["opportunity"],
+        reverse=True,
+    )
+
+    for label, info in sorted_clusters[:10]:
+        opp = info["opportunity"]
+        cluster_tokens = Counter()
+        for text in info["samples"]:
+            cluster_tokens.update(_tokenize(text))
+
+        top5 = [kw for kw, _ in cluster_tokens.most_common(5)]
+        keywords_str = ", ".join(top5)
+
+        with st.expander(f"{label} (Opp: {opp:.4f}) — {keywords_str}"):
+            st.write(f"**Fanout/Citation 수:** {info['fanout_count']}")
+            st.write(f"**Opportunity Score:** {opp:.4f}")
+            st.markdown("**Top 키워드:**")
+
+            kw_df = pd.DataFrame(
+                cluster_tokens.most_common(10),
+                columns=["키워드", "빈도"],
+            )
+            st.dataframe(kw_df, use_container_width=True, hide_index=True)
+
+            st.markdown("**샘플 텍스트:**")
+            for s in info["samples"][:3]:
+                st.write(f"- {s}")

features/research/opportunities.py

@@ -0,0 +1,173 @@
+"""기회 영역 랭킹 테이블 + 상세 Expander.
+
+Clusters sorted by opportunity_score DESC.
+Top-10 with expanders showing sample fanouts and top sources.
+v9.0: 비즈니스 해석, percentile, 인용 유무 메시지 추가.
+"""
+
+import statistics
+
+import streamlit as st
+import pandas as pd
+import plotly.graph_objects as go
+
+
+def _get_percentile_rank(value: float, all_values: list[float]) -> int:
+    """Return the percentile rank (0-100) of a value within a list."""
+    if not all_values:
+        return 0
+    count_below = sum(1 for v in all_values if v < value)
+    return int(count_below / len(all_values) * 100)
+
+
+def _interpret_density(density: float, median_density: float) -> str:
+    """Interpret density relative to median."""
+    if density < median_density * 0.5:
+        return "경쟁 낮음"
+    elif density < median_density * 1.5:
+        return "경쟁 보통"
+    return "경쟁 높음"
+
+
+def _interpret_opportunity(opp: float, median_opp: float) -> str:
+    """Interpret opportunity score."""
+    if opp >= median_opp * 1.5:
+        return "기회 큼"
+    elif opp >= median_opp * 0.5:
+        return "기회 보통"
+    return "기회 낮음"
+
+
+def render_opportunities(clusters: list[dict], frame: str = "all"):
+    """Render opportunity ranking table with detail expanders."""
+    scored = [
+        c for c in clusters
+        if c.get("opportunity_score") is not None
+        and c.get("attention_score") is not None
+    ]
+
+    if not scored:
+        st.info("스코어가 계산된 클러스터가 없습니다.")
+        return
+
+    # Sort by opportunity_score DESC
+    scored.sort(key=lambda c: float(c.get("opportunity_score", 0) or 0), reverse=True)
+
+    # Pre-compute statistics for percentile/interpretation
+    all_attns = [float(c.get("attention_score", 0) or 0) for c in scored]
+    all_densities = [float(c.get("citation_density", 0) or 0) for c in scored]
+    all_opps = [float(c.get("opportunity_score", 0) or 0) for c in scored]
+    median_density = statistics.median(all_densities) if all_densities else 0
+    median_opp = statistics.median(all_opps) if all_opps else 0
+
+    # Top metrics
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.metric("스코어링 완료", f"{len(scored)}개 클러스터")
+    with col2:
+        avg_opp = sum(all_opps) / len(all_opps)
+        st.metric("평균 Opportunity", f"{avg_opp:.4f}")
+    with col3:
+        top = scored[0]
+        st.metric("Top 기회 토픽", (top.get("cluster_label") or "N/A")[:25])
+
+    st.markdown("---")
+
+    # Explanation before ranking table (frame-specific)
+    if frame == "demand":
+        st.info(
+            "ChatGPT가 자주 검색하지만 경쟁이 낮은 Demand 토픽입니다.\n\n"
+            "기회 점수가 높을수록, 이 주제에 콘텐츠를 만들면 ChatGPT 검색에 노출될 가능성이 높습니다."
+        )
+    elif frame == "supply":
+        st.info(
+            "Gemini가 자주 인용하지만 출처 경쟁이 낮은 Supply 토픽입니다.\n\n"
+            "기회 점수가 높을수록, 이 주제에 콘텐츠를 만들면 Gemini 답변에 인용될 가능성이 높습니다."
+        )
+    else:
+        st.info(
+            "기회 점수 Top 10 토픽을 상세 분석합니다. "
+            "기회 점수는 **'AI 관심도가 높지만 경쟁(인용 출처)이 적은 토픽'**을 찾아주는 지표입니다.\n\n"
+            "점수가 높을수록 콘텐츠를 만들면 AI에 인용될 가능성이 높습니다."
+        )
+
+    # Ranking table
+    rows = []
+    for i, c in enumerate(scored[:50], 1):
+        rows.append({
+            "순위": i,
+            "토픽": (c.get("cluster_label") or f"Cluster-{c['id'][:8]}")[:40],
+            "Attention": f"{float(c.get('attention_score', 0) or 0):.4f}",
+            "Density": f"{float(c.get('citation_density', 0) or 0):.4f}",
+            "Opportunity": f"{float(c.get('opportunity_score', 0) or 0):.4f}",
+            "Fanouts": c.get("fanout_count", 0),
+        })
+
+    df = pd.DataFrame(rows)
+    st.dataframe(df, use_container_width=True, hide_index=True)
+
+    # Detail expanders for top 10
+    st.markdown("#### Top 10 상세")
+    for i, c in enumerate(scored[:10], 1):
+        label = c.get("cluster_label") or f"Cluster-{c['id'][:8]}"
+        opp = float(c.get("opportunity_score", 0) or 0)
+
+        with st.expander(f"#{i} {label} (Opportunity: {opp:.4f})", key=f"research:opp_detail:{c['id']}"):
+            detail_col1, detail_col2 = st.columns(2)
+
+            with detail_col1:
+                attn = float(c.get("attention_score", 0) or 0)
+                density = float(c.get("citation_density", 0) or 0)
+                attn_pct = _get_percentile_rank(attn, all_attns)
+                density_label = _interpret_density(density, median_density)
+                opp_label = _interpret_opportunity(opp, median_opp)
+
+                st.markdown("**Score 상세**")
+                st.write(f"- Attention: {attn:.4f} (상위 {100 - attn_pct}%)")
+                st.write(f"- Density: {density:.4f} ({density_label})")
+                st.write(f"- Opportunity: {opp:.4f} ({opp_label})")
+                st.write(f"- Fanout 수: {c.get('fanout_count', 0)}")
+                if c.get("unique_questions"):
+                    st.write(f"- 관련 질문 수: {c['unique_questions']}")
+
+            with detail_col2:
+                # Sample fanouts/citations with context
+                samples = c.get("sample_fanouts") or []
+                if samples:
+                    if frame == "supply":
+                        st.markdown("**대표 인용 문구** (Gemini가 실제로 인용한 텍스트):")
+                    else:
+                        st.markdown("**대표 AI 추가 질문** (이 토픽에서 AI가 실제로 생성한 질문들):")
+                    for s in samples[:5]:
+                        st.write(f"- {s}")
+                    if frame == "supply":
+                        st.caption("이런 형태의 콘텐츠를 만들면 Gemini 답변에 인용될 수 있습니다.")
+                    else:
+                        st.caption("이런 질문에 대한 콘텐츠를 만들면 AI 답변에 인용될 수 있습니다.")
+                else:
+                    st.write("샘플 없음")
+
+            # Top sources bar chart
+            top_sources = c.get("top_sources")
+            if top_sources and isinstance(top_sources, list) and len(top_sources) > 0:
+                st.caption("이 토픽에서 AI가 인용한 주요 출처입니다. 여기에 자사 콘텐츠가 없다면 진출 기회입니다.")
+                domains = [s.get("host_url", "unknown") for s in top_sources[:10]]
+                counts = [s.get("count", 0) for s in top_sources[:10]]
+
+                fig = go.Figure(go.Bar(
+                    x=counts,
+                    y=domains,
+                    orientation="h",
+                    marker_color="#059669",
+                ))
+                fig.update_layout(
+                    title="Top 인용 출처",
+                    xaxis_title="인용 수",
+                    yaxis=dict(autorange="reversed"),
+                    height=300,
+                    margin=dict(l=0, r=0, t=30, b=0),
+                    template="plotly_white",
+                )
+                st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+            else:
+                st.info("이 토픽은 아직 AI가 특정 출처를 인용하지 않고 있어, 콘텐츠 선점 기회가 더욱 큽니다.")

features/research/summary.py

@@ -0,0 +1,48 @@
+"""토픽 인텔리전스 Feature 요약 카드."""
+import streamlit as st
+
+
+def render_summary(clusters: list, frame: str = "all"):
+    """토픽 인텔리전스 요약 메트릭.
+
+    Args:
+        clusters: List of cluster dicts.
+        frame: "demand" (ChatGPT), "supply" (Gemini), or "all".
+    """
+    scored = [c for c in clusters if c.get("opportunity_score") is not None]
+
+    # Frame-specific labels
+    if frame == "demand":
+        count_label = "Demand 토픽"
+        volume_label = "총 Fanout"
+        volume_help = "ChatGPT가 사용자 질문을 분해한 세부 질문의 총 수"
+        attn_help = "각 토픽이 전체 ChatGPT 질의에서 차지하는 비중의 평균"
+        top_help = "ChatGPT에서 관심도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"
+    elif frame == "supply":
+        count_label = "Supply 토픽"
+        volume_label = "총 Citation"
+        volume_help = "Gemini가 답변에서 인용한 문구의 총 수"
+        attn_help = "각 토픽이 전체 Gemini 인용에서 차지하는 비중의 평균"
+        top_help = "Gemini에서 인용 빈도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"
+    else:
+        count_label = "총 클러스터"
+        volume_label = "총 Fanout"
+        volume_help = "AI가 사용자 질문을 조사하기 위해 생성한 세부 질문의 총 수"
+        attn_help = "각 토픽이 전체 질의에서 차지하는 비중의 평균"
+        top_help = "AI 관심도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"
+
+    col1, col2, col3, col4 = st.columns(4)
+    with col1:
+        st.metric(
+            count_label, len(clusters),
+            help="유사한 AI 질문/인용들을 묶은 토픽 그룹 수",
+        )
+    with col2:
+        total_fanouts = sum(c.get("fanout_count", 0) for c in clusters)
+        st.metric(volume_label, f"{total_fanouts:,}", help=volume_help)
+    with col3:
+        avg_attn = sum(float(c.get("attention_score", 0) or 0) for c in scored) / len(scored) if scored else 0
+        st.metric("평균 Attention", f"{avg_attn:.4f}", help=attn_help)
+    with col4:
+        top_label = scored[0].get("cluster_label", "N/A") if scored else "N/A"
+        st.metric("Top Opportunity", top_label[:20], help=top_help)

features/research/topic_map.py

@@ -0,0 +1,108 @@
+"""UMAP 토픽 맵 시각화 (Plotly scatter).
+
+snapshot.coordinates: [{cluster_id, x, y, size, label}]
+clusters: [{id, cluster_label, attention_score, citation_density, opportunity_score, fanout_count, ...}]
+"""
+
+import streamlit as st
+import plotly.graph_objects as go
+
+
+def render_topic_map(clusters: list[dict], snapshot: dict | None, frame: str = "all"):
+    """Render UMAP 2D scatter from snapshot coordinates + cluster metadata."""
+    if not snapshot or not snapshot.get("coordinates"):
+        st.info("UMAP 좌표 데이터가 없습니다. 클러스터링 실행 후 생성됩니다.")
+        return
+
+    # Frame-specific guide
+    if frame == "demand":
+        st.markdown("""
+각 점은 하나의 **Demand 토픽** (ChatGPT sub-query 그룹)입니다.
+- **점 크기**: 해당 토픽의 fanout 수 (클수록 소비자가 자주 묻는 토픽)
+- **점 색상**: 기회 점수 (빨강 = 기회 큼, 노랑 = 보통)
+- **가까이 있는 점**: 유사한 검색 의도의 토픽
+""")
+    elif frame == "supply":
+        st.markdown("""
+각 점은 하나의 **Supply 토픽** (Gemini citation quote 그룹)입니다.
+- **점 크기**: 해당 토픽의 인용 수 (클수록 AI가 자주 인용하는 토픽)
+- **점 색상**: 기회 점수 (빨강 = 기회 큼, 노랑 = 보통)
+- **가까이 있는 점**: 유사한 인용 주제의 토픽
+""")
+    else:
+        st.markdown("""
+각 점은 하나의 **토픽**(AI 추가 질문 그룹)입니다.
+- **점 크기**: 해당 토픽의 AI 추가 질문 수 (클수록 AI가 자주 묻는 토픽)
+- **점 색상**: 기회 점수 (빨강 = 기회 큼, 노랑 = 보통)
+- **가까이 있는 점**: 유사한 주제의 토픽
+""")
+
+    count_label = "Citations" if frame == "supply" else "Fanouts"
+    coords = snapshot["coordinates"]
+
+    # Build cluster lookup by id
+    cluster_map = {c["id"]: c for c in clusters}
+
+    # Merge coordinate data with cluster metadata
+    xs, ys, sizes, colors, hover_texts = [], [], [], [], []
+
+    for pt in coords:
+        cid = pt.get("cluster_id")
+        meta = cluster_map.get(cid, {})
+
+        xs.append(pt["x"])
+        ys.append(pt["y"])
+
+        fanout_count = pt.get("size", meta.get("fanout_count", 10))
+        # Normalize size for display (min 5, max 40)
+        norm_size = max(5, min(40, fanout_count / 5))
+        sizes.append(norm_size)
+
+        opp = float(meta.get("opportunity_score", 0) or 0)
+        colors.append(opp)
+
+        label = meta.get("cluster_label") or f"Cluster {pt.get('label', '?')}"
+        attn = float(meta.get("attention_score", 0) or 0)
+        density = float(meta.get("citation_density", 0) or 0)
+
+        hover_texts.append(
+            f"<b>{label}</b><br>"
+            f"Attention: {attn:.4f}<br>"
+            f"Density: {density:.4f}<br>"
+            f"Opportunity: {opp:.4f}<br>"
+            f"{count_label}: {fanout_count}"
+        )
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=xs,
+        y=ys,
+        mode="markers",
+        marker=dict(
+            size=sizes,
+            color=colors,
+            colorscale="YlOrRd",
+            colorbar=dict(title="Opportunity"),
+            opacity=0.7,
+            line=dict(width=0.5, color="#333"),
+        ),
+        text=hover_texts,
+        hoverinfo="text",
+    ))
+
+    fig.update_layout(
+        title="AI 토픽 맵 (UMAP 2D Projection)",
+        xaxis=dict(title="UMAP-1", showgrid=False, zeroline=False),
+        yaxis=dict(title="UMAP-2", showgrid=False, zeroline=False),
+        height=600,
+        template="plotly_white",
+        hoverlabel=dict(bgcolor="white", font_size=12),
+    )
+
+    st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
+
+    # Algorithm params info
+    params = snapshot.get("algorithm_params")
+    if params:
+        with st.expander("분석 설정 (기술 상세)"):
+            st.json(params)

features/research/unified_scoring.py

@@ -0,0 +1,178 @@
+"""Unified Scoring (ADR-014 Phase 4).
+
+Cross-model unified score = weighted average of demand/supply percentiles.
+Displayed in "전체" mode when cross-model pair exists.
+"""
+
+import streamlit as st
+import pandas as pd
+import plotly.graph_objects as go
+
+from core.supabase_client import (
+    get_gap_scores, get_topic_clusters,
+)
+
+
+def render_unified_scoring(base_ctx: dict, pair: dict):
+    """Render unified scoring view combining demand + supply signals.
+
+    Args:
+        base_ctx: Dashboard base context.
+        pair: Cross-model pair dict from find_cross_model_pair().
+    """
+    campaign_chatgpt = pair["campaign_chatgpt"]
+    campaign_gemini = pair["campaign_gemini"]
+
+    matches = get_gap_scores(campaign_chatgpt, campaign_gemini)
+    if not matches:
+        st.info("Unified Scoring에 필요한 Cross-Model 데이터가 없습니다.")
+        return
+
+    # Fetch cluster counts for weight calculation
+    chatgpt_clusters = get_topic_clusters(campaign_chatgpt, source="chatgpt")
+    gemini_clusters = get_topic_clusters(campaign_gemini, source="gemini")
+
+    chatgpt_volume = sum(c.get("fanout_count", 0) for c in chatgpt_clusters)
+    gemini_volume = sum(c.get("fanout_count", 0) for c in gemini_clusters)
+    total_volume = chatgpt_volume + gemini_volume
+
+    # Weight by data volume (ADR-014 spec)
+    w_chatgpt = chatgpt_volume / total_volume if total_volume > 0 else 0.5
+    w_gemini = gemini_volume / total_volume if total_volume > 0 else 0.5
+
+    st.caption(
+        "Demand(ChatGPT)와 Supply(Gemini) 신호를 데이터 볼륨 비례로 통합한 점수입니다."
+    )
+
+    # Weight info
+    c1, c2, c3 = st.columns(3)
+    with c1:
+        st.metric(
+            "Demand 가중치",
+            f"{w_chatgpt:.1%}",
+            help=f"ChatGPT fanout 볼륨: {chatgpt_volume:,}",
+        )
+    with c2:
+        st.metric(
+            "Supply 가중치",
+            f"{w_gemini:.1%}",
+            help=f"Gemini citation 볼륨: {gemini_volume:,}",
+        )
+    with c3:
+        st.metric("매칭 토픽", f"{len(matches)}개")
+
+    st.markdown("---")
+
+    # Compute unified scores
+    scored = []
+    for m in matches:
+        demand_pct = float(m.get("demand_percentile") or 0)
+        supply_pct = float(m.get("supply_percentile") or 0)
+        unified = w_chatgpt * demand_pct + w_gemini * supply_pct
+        scored.append({
+            **m,
+            "unified_score": unified,
+        })
+
+    # Sort by unified score DESC
+    scored.sort(key=lambda x: x["unified_score"], reverse=True)
+
+    # --- Unified Ranking Table ---
+    st.markdown("#### Unified Score 랭킹")
+    st.caption(
+        "두 모델의 신호를 통합한 순위입니다. "
+        "Unified Score가 높을수록 Demand와 Supply 모두에서 중요한 토픽입니다."
+    )
+
+    rows = []
+    for i, s in enumerate(scored, 1):
+        demand_pct = float(s.get("demand_percentile") or 0)
+        supply_pct = float(s.get("supply_percentile") or 0)
+        rows.append({
+            "#": i,
+            "토픽 (ChatGPT)": (s.get("chatgpt_label") or "")[:30],
+            "토픽 (Gemini)": (s.get("gemini_label") or "")[:30],
+            "Unified": f"{s['unified_score']:.4f}",
+            "Demand": f"{demand_pct:.2%}",
+            "Supply": f"{supply_pct:.2%}",
+            "GapScore": f"{float(s.get('gap_score') or 0):.4f}",
+            "Quadrant": s.get("quadrant", "NICHE").replace("_", " ").title(),
+        })
+
+    df = pd.DataFrame(rows)
+    st.dataframe(df, use_container_width=True, hide_index=True)
+
+    st.markdown("---")
+
+    # --- Unified Score Distribution ---
+    st.markdown("#### Unified Score vs GapScore")
+    st.caption(
+        "X축은 통합 중요도(높을수록 두 모델 모두 중요), "
+        "Y축은 기회 크기(높을수록 콘텐츠 제작 ROI가 높음)."
+    )
+
+    _render_unified_scatter(scored)
+
+
+def _render_unified_scatter(scored: list[dict]):
+    """Scatter: Unified Score (x) vs GapScore (y)."""
+    from .cross_model import QUADRANT_COLORS, QUADRANT_LABELS
+
+    xs, ys, colors, hovers, sizes = [], [], [], [], []
+
+    for s in scored:
+        unified = s["unified_score"]
+        gap = float(s.get("gap_score") or 0)
+        quadrant = s.get("quadrant", "NICHE")
+        chatgpt_label = s.get("chatgpt_label", "")
+
+        xs.append(unified)
+        ys.append(gap)
+        colors.append(QUADRANT_COLORS.get(quadrant, "#9CA3AF"))
+        sizes.append(max(8, min(25, unified * 30)))
+        hovers.append(
+            f"<b>{chatgpt_label}</b><br>"
+            f"Unified: {unified:.4f}<br>"
+            f"GapScore: {gap:.4f}<br>"
+            f"Quadrant: {QUADRANT_LABELS.get(quadrant, quadrant)}"
+        )
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=xs,
+        y=ys,
+        mode="markers",
+        marker=dict(
+            size=sizes,
+            color=colors,
+            opacity=0.7,
+            line=dict(width=0.5, color="#333"),
+        ),
+        text=hovers,
+        hoverinfo="text",
+        showlegend=False,
+    ))
+
+    fig.update_layout(
+        title="Unified Score vs GapScore",
+        xaxis_title="Unified Score (통합 중요도)",
+        yaxis_title="GapScore (콘텐츠 기회)",
+        height=450,
+        template="plotly_white",
+        hoverlabel=dict(bgcolor="white", font_size=12),
+    )
+
+    st.plotly_chart(fig, use_container_width=True, key="cross_model:unified_scatter", config={"displayModeBar": False})
+
+    # Insight: Top-right quadrant = high importance + high opportunity
+    high_unified = [s for s in scored if s["unified_score"] > 0.5]
+    high_gap_and_unified = [
+        s for s in high_unified
+        if float(s.get("gap_score") or 0) > 0.05
+    ]
+    if high_gap_and_unified:
+        st.info(
+            f"Unified Score > 0.5 이면서 GapScore가 높은 토픽이 "
+            f"**{len(high_gap_and_unified)}개** 있습니다. "
+            f"이 토픽들은 두 모델 모두에서 중요하면서 콘텐츠 기회도 큰 최우선 영역입니다."
+        )