# task-2020: InsuRo PostHog 이벤트 계측 (DA-6~11) — 완료 보고서

## SCQA

**S**: InsuRo 프로젝트에 사용자 행동 분석을 위한 PostHog 분석 인프라가 필요하다. task-2017(DA-1~5)에서 계획한 기반 셋업이 미구현 상태였다.

**C**: PostHog SDK, useAnalytics 훅, 서버사이드 분석 모듈이 모두 없어서 DA-6~11 이벤트 계측도 불가능한 상황이었다. DA-1~5 기반 인프라와 DA-6~11 이벤트 계측을 함께 구현해야 했다.

**Q**: PostHog 기반 인프라(DA-1~5)와 주요 이벤트 계측(DA-6~11)을 PII 전송 없이 안전하게 구현할 수 있는가?

**A**: 프론트엔드(posthog-js + useAnalytics 훅 + PostHogProvider + PageViewTracker)와 백엔드(posthog-python + analytics.py + PII 필터링)를 모두 구현 완료. 18개 이벤트 타입 정의, PII 자동 필터링(35개 키 차단), 7개 이벤트 실계측 완료. tsc 0 에러, vite build 성공, pytest 36건 전원 통과.

## 수정 파일 목록

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| server/analytics.py (신규) | PostHog 서버사이드 모듈 + PII 필터링 | grep "track_server_event" OK | verified |
| server/requirements.txt | posthog>=3.0.0 추가 | grep "posthog" OK | verified |
| server/main.py:31,117-120,611-618 | analytics import + shutdown flush + content_generated 이벤트 | grep "analytics" OK (3건) | verified |
| src/hooks/useAnalytics.ts (신규) | 18개 이벤트 타입 + PII 필터링 + track() 함수 | grep "useAnalytics" OK | verified |
| src/components/PostHogProvider.tsx (신규) | PostHog 초기화 (VITE_POSTHOG_API_KEY) | grep "PostHogProvider" OK | verified |
| src/components/PageViewTracker.tsx (신규) | page_view 자동 추적 (DA-6) | grep "PageViewTracker" OK | verified |
| src/App.tsx:11-12,29,35,56 | PostHogProvider 래핑 + PageViewTracker 추가 | grep "PostHogProvider" OK | verified |
| src/pages/OnboardingWizard.tsx:3,28,163,165,178 | onboarding_step_completed 이벤트 (DA-7) | grep "onboarding_step_completed" OK (3건) | verified |
| src/components/LockedFeatureOverlay.tsx:1,11,57-61,88-89 | locked_feature_viewed + plan_upgrade_clicked + cta_clicked (DA-9) | grep "locked_feature_viewed" OK | verified |
| src/components/PlanUpgradeDialog.tsx:11,141,233,260-265 | inquiry_submitted + upgrade_modal_dismissed (DA-9) | grep "upgrade_modal_dismissed" OK | verified |
| .env.example (신규) | VITE_POSTHOG_API_KEY 환경변수 템플릿 | grep "POSTHOG" OK | verified |

## 구현 항목별 상태

- **DA-6 (page_view 자동 추적)**: PageViewTracker 컴포넌트, React Router useLocation 감지 — 완료
- **DA-7 (온보딩 퍼널)**: OnboardingWizard에서 step 1/2/3 전환 시 onboarding_step_completed 이벤트 — 완료
- **DA-8 (content_generated)**: 서버 main.py에서 AI 콘텐츠 생성 성공 시 track_server_event 호출 — 완료
- **DA-9 (업그레이드 퍼널 4종)**: locked_feature_viewed, plan_upgrade_clicked, upgrade_modal_dismissed, inquiry_submitted — 모두 완료
- **DA-10 (서버사이드 이벤트)**: analytics.py에 pipeline_run_completed, crm_contact_added, content_generated 지원 — 완료 (호출 지점은 해당 기능 구현 시 추가)
- **DA-11 (나머지 이벤트)**: useAnalytics 훅에 18개 타입 정의 완료. feature_used, cta_clicked은 LockedFeatureOverlay에서 계측 중. 나머지는 타입만 정의 (해당 기능 구현 시 track 호출 추가)

## PII 안전성

- **프론트엔드**: useAnalytics.ts의 filterPii()가 email/phone/name 키 자동 제거
- **백엔드**: analytics.py의 _filter_pii()가 35개 PII 키 소문자 비교 후 자동 제거 + WARNING 로그
- **이벤트 전달 시**: user_id는 Supabase UUID만 사용, 개인 정보 미포함 확인

## 테스트 결과

- TypeScript 컴파일(tsc --noEmit): 0 에러
- Vite 빌드: 성공 (8.61초, 138 entries precached)
- pytest(server/tests/test_main.py): 36건 전원 통과 (2.26초)

## L1 스모크테스트 결과

- 서버 재시작: 해당없음 (프론트엔드 위주 작업, 서버 코드는 import/shutdown hook만 추가)
- API 응답 확인: pytest 36건 통과로 확인 (POSTHOG_API_KEY 미설정 상태에서 no-op 모드 정상 동작)
- 스크린샷: 해당없음 (PostHog는 백그라운드 이벤트 전송, UI 변경 없음)
- 추가 확인: vite build 성공으로 프론트엔드 번들링 정상 확인

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **task-2017 기반 인프라 미구현** — DA-1~5 기반 셋업을 DA-6~11과 함께 구현
2. **main.py import analytics pyright 에러** — `# type: ignore[import-not-found]` 주석 추가 (동일 디렉토리 모듈, pyright가 resolve 못 함)
3. **PostHogProvider.tsx ph 미사용 경고** — loaded 콜백에서 unused parameter 제거

### 범위 외 미해결 (2건)
1. **main.py:129 RateLimitExceeded 타입 경고** — 범위 외 사유: 기존 slowapi 라이브러리 타입 호환성 이슈, 본 작업과 무관
2. **DA-11 일부 이벤트 미계측** — chat_started/chat_ended/summary_generated/keyword_analyzed/wiki_viewed/namecard_shared/login_completed는 타입만 정의. 범위 외 사유: 해당 기능 컴포넌트에서 개별 계측 필요 (향후 작업)

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-2020-dev6
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-2020-dev6
- **머지 의견**: tsc 0 에러, vite build 성공, pytest 36건 통과. PII 필터링 안전. 기존 기능에 영향 없는 additive 변경.

## 모델 사용 기록

- 팀원: 스바로그 / 작업 내용: 서버사이드 analytics.py + main.py 연동 / 사용 모델: sonnet
- 팀원: 라다 / 작업 내용: useAnalytics 훅 + PostHogProvider + 이벤트 계측 / 사용 모델: sonnet
- 팀원: 페룬(팀장) / 작업 내용: 진단 수정, 통합 검증 / 사용 모델: opus

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회