# GEO Analytics 도구 모음

리쿠르팅 마케팅 v2.0 캠페인 Phase 3(효과측정)용 GEO 분석 도구 3종.

## 설치

```bash
pip install -r requirements.txt
```

> `google-analytics-data`는 옵셔널. GA4 API 연동 시에만 필요.

## 도구 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 (옵셔널)
python3 keyword_cluster.py --ga4 --property-id 123456 --date-range 30d --clusters 5
```

5개 보험 도메인 프리셋(COST, LEARNING, PROCESS, TRUST, INVESTMENT)으로 라벨 자동 할당.

## 도구 2: aio_tracker.py

AI 검색엔진별 유입 트래픽 Before/After 변화 자동 계산.

```bash
# CSV 수동 입력
python3 aio_tracker.py --before-csv before.csv --after-csv after.csv

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

# 리포트 저장
python3 aio_tracker.py --before-csv before.csv --after-csv after.csv --output report.md
```

지원 AI 소스: ChatGPT, Perplexity, Gemini, Claude, 네이버 AIO.

### CSV 포맷 (before.csv / after.csv)

```csv
referrer,sessions
chatgpt.com,120
perplexity.ai,45
```

## 도구 3: conversion_tracker.py

AI 유입 사용자의 전환 퍼널 7단계 드롭오프율 분석.

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

# GA4 API (옵셔널)
python3 conversion_tracker.py --property-id 123456 --date-range 30d
```

7단계 퍼널: AI 검색 도착 → 콘텐츠 소비 → 인터랙션 → 관심 → 전환 → 재방문 → 추천.

### CSV 포맷 (events.csv)

```csv
stage,users,source
AI 검색 도착,500,ChatGPT
콘텐츠 소비,350,ChatGPT
전환,25,ChatGPT
```

`source` 컬럼은 옵셔널. 없으면 전체 퍼널 분석만 수행.

## 공통 설정 (config.py)

- `GA4_PROPERTY_ID`: 환경변수로 GA4 Property ID 설정
- `GOOGLE_APPLICATION_CREDENTIALS`: GA4 인증 파일 경로
- 모든 GA4 연동은 옵셔널 — CSV 입력으로 대체 가능

## 테스트

```bash
python3 -m pytest tests/ -v
```