# task-1070.1: GEO 분석 도구 3개 개발

## 배경
task-1067.1에서 GA4 MCP + GEO 전략 분석 결과, 3개 Python 도구가 필요하다고 판단됨.
리쿠르팅 마케팅 v2.0 캠페인의 Phase 3(효과측정)에서 사용될 도구들이다.

## 참조 문서
- GEO 분석 보고서: `/home/jay/workspace/memory/reports/task-1067.1.md` (섹션 4.3, 4.4 참조)
- 캠페인 체크리스트: `/home/jay/workspace/memory/specs/recruiting-campaign-checklist.md`

## 디렉토리 구조
```
/home/jay/workspace/tools/geo-analytics/
├── keyword_cluster.py      # TF-IDF + K-Means 검색어 클러스터링
├── aio_tracker.py          # AI 유입 Before/After 성과 추적
├── conversion_tracker.py   # AI 유입 전환 역추적
├── config.py               # 공통 설정 (GA4 Property ID, 인증 등)
├── requirements.txt        # 의존성
├── tests/
│   ├── test_keyword_cluster.py
│   ├── test_aio_tracker.py
│   └── test_conversion_tracker.py
└── README.md               # 사용법
```

## 도구 1: keyword_cluster.py

### 기능
GA4 검색어 데이터를 TF-IDF 벡터화 + K-Means 알고리즘으로 자동 클러스터링

### 인터페이스
```bash
# CSV 파일 입력
python3 keyword_cluster.py --input queries.csv --clusters 5 --output report.json

# 직접 키워드 입력
python3 keyword_cluster.py --keywords "보험료 계산,보험 종류,보험 가입" --clusters 3

# GA4 API 연동 (GA4 MCP 설정 후)
python3 keyword_cluster.py --ga4 --property-id 123456 --date-range 30d --clusters 5
```

### 출력
```json
{
  "clusters": [
    {
      "id": 0,
      "label": "LEARNING",
      "representative_keyword": "보험 종류",
      "keywords": ["보험 종류", "보험 뜻", "보험이란"],
      "size": 12,
      "pillar_document_suggestion": "InsuWiki 보험 가이드"
    }
  ],
  "total_keywords": 50,
  "silhouette_score": 0.65
}
```

### 구현 요구사항
- `scikit-learn` (TF-IDF, K-Means)
- 한글 형태소 분석: `konlpy` 또는 간단한 공백 토크나이저 (konlpy 설치 불가 시 공백 기반)
- CSV/JSON 입력 지원
- GA4 API 연동은 옵셔널 (config.py의 GOOGLE_APPLICATION_CREDENTIALS 설정 시만)
- 5개 보험 도메인 클러스터 프리셋: COST(보험료/비용), LEARNING(보험 이해), PROCESS(가입 절차), TRUST(신뢰/추천), INVESTMENT(연금/투자)
- silhouette_score로 클러스터 품질 평가

## 도구 2: aio_tracker.py

### 기능
AI 검색엔진별 유입 트래픽의 Before/After 변화를 자동 계산

### 인터페이스
```bash
# 기본: 이번 주 vs 지난 주
python3 aio_tracker.py --property-id 123456

# 기간 지정
python3 aio_tracker.py --property-id 123456 --before "2026-03-01:2026-03-15" --after "2026-03-16:2026-03-31"

# CSV 수동 입력 (GA4 API 없이)
python3 aio_tracker.py --before-csv before.csv --after-csv after.csv

# 리포트 저장
python3 aio_tracker.py --property-id 123456 --output /home/jay/workspace/memory/reports/weekly-aio-2026-03-26.md
```

### 출력 (마크다운 리포트)
```markdown
# AIO 성과 리포트 (2026-03-26)

## AI 유입 트래픽 변화
| 소스 | Before | After | 변화율 |
|------|--------|-------|--------|
| ChatGPT | 120 | 185 | +54.2% |
| Perplexity | 45 | 72 | +60.0% |
| Gemini | 30 | 41 | +36.7% |
| Claude | 15 | 23 | +53.3% |
| 네이버 AIO | 200 | 310 | +55.0% |

## 체류 시간 변화
...
```

### 구현 요구사항
- AI 소스 분류: 레퍼러 URL 패턴 매칭
  - ChatGPT: `chat.openai.com`, `chatgpt.com`
  - Perplexity: `perplexity.ai`
  - Gemini: `gemini.google.com`
  - Claude: `claude.ai`
  - 네이버 AIO: `search.naver.com` (ai_overview 파라미터)
  - UTM 기반: `utm_source=ai_*`
- GA4 Data API 연동 (google-analytics-data 패키지, 옵셔널)
- CSV 수동 모드 지원 (GA4 API 없이도 사용 가능)
- 변화율 자동 계산, 마크다운 리포트 생성
- config.py에서 PROPERTY_ID, CREDENTIALS_PATH 로드

## 도구 3: conversion_tracker.py

### 기능
AI 유입 사용자의 전환 퍼널 단계별 드롭오프율 분석

### 인터페이스
```bash
# 기본 퍼널 분석
python3 conversion_tracker.py --property-id 123456 --date-range 30d

# 특정 전환 이벤트
python3 conversion_tracker.py --property-id 123456 --conversion-event consultation_requested

# CSV 수동 입력
python3 conversion_tracker.py --events-csv events.csv --output funnel-report.md
```

### 출력
```json
{
  "funnel": [
    {"stage": "AI 검색 도착", "users": 500, "rate": "100%"},
    {"stage": "콘텐츠 소비", "users": 350, "rate": "70%", "dropoff": "30%"},
    {"stage": "인터랙션", "users": 120, "rate": "24%", "dropoff": "65.7%"},
    {"stage": "전환(상담 신청)", "users": 25, "rate": "5%", "dropoff": "79.2%"}
  ],
  "ai_source_breakdown": {
    "ChatGPT": {"arrivals": 180, "conversions": 12, "cvr": "6.7%"},
    "Perplexity": {"arrivals": 120, "conversions": 8, "cvr": "6.7%"}
  },
  "insights": [
    "최대 이탈 지점: 인터랙션 → 전환 (79.2% 드롭오프)",
    "최고 전환 소스: ChatGPT (CVR 6.7%)"
  ]
}
```

### 구현 요구사항
- GA4 Data API 연동 (옵셔널)
- CSV 수동 모드 지원
- 7단계 퍼널: 도착 → 콘텐츠 소비 → 인터랙션 → 관심 → 전환 → 재방문 → 추천
- AI 소스별 분석 (aio_tracker.py의 소스 분류 로직 공유 → config.py에 정의)
- 드롭오프율 자동 계산
- 인사이트 자동 생성 (최대 이탈 지점, 최고 전환 소스)

## 공통 요구사항

### config.py
```python
# GA4 설정 (옵셔널)
GA4_PROPERTY_ID = os.environ.get("GA4_PROPERTY_ID", "")
GOOGLE_APPLICATION_CREDENTIALS = os.environ.get(
    "GOOGLE_APPLICATION_CREDENTIALS",
    os.path.expanduser("~/.claude/credentials/ga4-agent.json")
)

# AI 소스 분류 패턴
AI_SOURCES = {
    "ChatGPT": ["chat.openai.com", "chatgpt.com"],
    "Perplexity": ["perplexity.ai"],
    "Gemini": ["gemini.google.com"],
    "Claude": ["claude.ai"],
    "네이버 AIO": ["search.naver.com"],
}
```

### requirements.txt
```
scikit-learn>=1.3.0
google-analytics-data>=0.18.0  # 옵셔널
pandas>=2.0.0
```

### 테스트
- 각 도구별 테스트 파일 작성 (pytest)
- CSV 수동 모드 테스트 (GA4 API 없이 동작 확인)
- TDD(RED→GREEN) 사이클로 개발
- 보험 도메인 샘플 데이터로 테스트

### 주의사항
- GA4 API 의존성은 모두 옵셔널 — API 없이도 CSV 입력으로 동작해야 함
- fact_db.md에 없는 수치 생성 금지 (테스트 데이터는 명시적으로 "샘플 데이터"로 표기)
- 모듈화: 200줄 이하/파일, 함수 분리
- config.py에 하드코딩된 키/시크릿 절대 금지

## 산출물
- 3개 Python 도구 + config.py + requirements.txt
- 3개 테스트 파일
- README.md
- 보고서: `memory/reports/task-1070.1.md`