# task-1070.1: GEO 분석 도구 3개 개발 — 완료 보고서

## SCQA

**S**: 리쿠르팅 마케팅 v2.0 캠페인 Phase 3(효과측정)에 필요한 GEO 분석 도구가 task-1067.1 분석 결과로 3개 식별되었다.

**C**: AI 검색엔진(ChatGPT, Perplexity, Gemini, Claude, 네이버 AIO) 유입 트래픽을 측정하고 분석하는 자동화 도구가 없어, 수작업 분석에 의존하고 있었다.

**Q**: TF-IDF 키워드 클러스터링, AI 유입 Before/After 추적, 전환 퍼널 분석을 자동화하는 3개 Python CLI 도구를 개발할 수 있는가?

**A**: 3개 도구 + 공통 설정 + 테스트 107개 전체 통과로 개발 완료. GA4 API는 옵셔널이며 CSV 수동 모드로 즉시 사용 가능. pyright 에러 0건, pytest 107/107 통과.

## 생성 파일 목록

- `/home/jay/workspace/tools/geo-analytics/config.py` — 공통 설정 (AI 소스 패턴, 퍼널 단계, GA4 설정)
- `/home/jay/workspace/tools/geo-analytics/keyword_cluster.py` — TF-IDF + K-Means 검색어 클러스터링
- `/home/jay/workspace/tools/geo-analytics/aio_tracker.py` — AI 유입 Before/After 성과 추적
- `/home/jay/workspace/tools/geo-analytics/conversion_tracker.py` — AI 유입 전환 역추적 (7단계 퍼널)
- `/home/jay/workspace/tools/geo-analytics/requirements.txt` — 의존성
- `/home/jay/workspace/tools/geo-analytics/conftest.py` — pytest 경로 설정
- `/home/jay/workspace/tools/geo-analytics/README.md` — 사용법
- `/home/jay/workspace/tools/geo-analytics/tests/test_keyword_cluster.py` — 37개 테스트
- `/home/jay/workspace/tools/geo-analytics/tests/test_aio_tracker.py` — 35개 테스트
- `/home/jay/workspace/tools/geo-analytics/tests/test_conversion_tracker.py` — 35개 테스트

## 테스트 결과

- pytest: **107 passed**, 17 warnings (sklearn token_pattern 경고, 무해)
- pyright: **0 errors**, 0 warnings
- black/isort: 포매팅 적용 완료

## 도구별 구현 요약

### 1. keyword_cluster.py
- TF-IDF 벡터화 + K-Means 클러스터링
- 5개 보험 도메인 프리셋 라벨 자동 할당 (COST, LEARNING, PROCESS, TRUST, INVESTMENT)
- silhouette_score 품질 평가
- CSV/직접입력/GA4 API(옵셔널) 3가지 입력 모드

### 2. aio_tracker.py
- 5개 AI 소스별 유입 트래픽 Before/After 비교
- 변화율 자동 계산 (before=0 시 "NEW" 표시)
- 마크다운 리포트 생성

### 3. conversion_tracker.py
- 7단계 퍼널(도착→소비→인터랙션→관심→전환→재방문→추천) 드롭오프 분석
- AI 소스별 CVR 분석
- 인사이트 자동 생성 (최대 이탈 지점, 최고/최저 전환 소스)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **TRUST/INVESTMENT 라벨 오분류** — "보험" 토큰이 모든 카테고리에 공통 등장하여 LEARNING 라벨로 편향. `_STOPWORDS = {"보험"}` 도입으로 해결 (keyword_cluster.py:38)
2. **silhouette_score ValueError (k==n_samples)** — sklearn이 `1 < k < n_samples` 조건 요구. 조건부 분기로 k==n 시 0.0 반환 (keyword_cluster.py:115)
3. **pytest import 경로** — QC test_runner가 workspace 루트에서 실행 시 모듈 import 실패. conftest.py 추가하여 sys.path 설정

### 범위 외 미해결 (0건)
없음.

## QC 자동 검증 결과

```json
{
  "task_id": "task-1070.1",
  "overall": "PASS",
  "checks": {
    "pyright_check": "PASS (0 errors)",
    "test_runner": "PASS (107 passed)",
    "style_check": "PASS (black+isort 적용 완료)"
  }
}
```