# task-2024: InsuRo PostHog KPI 대시보드 (DA-12~16) — 완료 보고서

## SCQA

**S**: InsuRo 프로젝트에 PostHog 분석 인프라(DA-1~5)와 이벤트 계측(DA-6~11)이 구현되었으나, 수집된 이벤트를 시각화하는 KPI 대시보드와 자동 집계 파이프라인이 없는 상태다.

**C**: PostHog 클라우드에서 대시보드를 직접 설정할 수도 있지만, 팀 내부 어드민이 Supabase 데이터 기반으로 핵심 KPI를 한눈에 볼 수 있는 내부 대시보드가 필요하다. 또한 PostHog webhook → Supabase 저장 → 일별 집계 자동화 파이프라인이 없어 수동 분석에 의존하고 있다.

**Q**: PostHog 이벤트를 Supabase에 자동 수집하고, 일별 집계를 통해 11개 핵심 KPI를 내부 어드민 대시보드에서 실시간 확인할 수 있는가?

**A**: DA-12~16 전체 구현 완료. (1) `/admin/analytics` 페이지에 11개 KPI 위젯 + 온보딩 퍼널(DA-12/14), (2) PostHog KPI/리텐션/퍼널 설정 가이드 문서(DA-13/14), (3) `posthog-webhook` Edge Function(DA-15), (4) `analytics_events` + `analytics_daily_summary` 테이블 + `refresh_analytics_daily_summary()` 함수 + pg_cron 스케줄(DA-16). vite build 성공(8.93s, 141 entries), pytest 74건(33 analytics + 41 main) 전체 PASS.

## 구현 내역

### DA-12: PostHog 핵심 KPI 대시보드
- `src/pages/AdminAnalytics.tsx` 신규 생성: 11개 KPI 위젯 (DAU/WAU/MAU, 콘텐츠 생성, 온보딩 완료율, 업그레이드 전환율, 페이지뷰, CRM 연락처, 파이프라인 완료, 일간 문의)
- `src/config/routes.ts`: `/admin/analytics` 라우트 등록 (adminOnly, BarChart3 아이콘)
- `analytics_daily_summary` 테이블 미존재 시 graceful fallback

### DA-13: 코호트 리텐션 분석 가이드
- `docs/posthog-kpi-dashboard-guide.md` 신규 생성 (551줄)
- PostHog Retention 기능 D1/D7/D30 설정 방법, 벤치마크, 해석 가이드

### DA-14: 온보딩 퍼널 대시보드
- AdminAnalytics 페이지에 온보딩 퍼널 섹션 포함 (Step 1→2→3 바 차트 + 이탈률)
- PostHog Funnel 설정 가이드 (가이드 문서 섹션 3)

### DA-15: PostHog Webhook → Supabase Edge Function
- `supabase/functions/posthog-webhook/index.ts` 신규 생성
- Authorization 헤더 검증 (POSTHOG_WEBHOOK_SECRET)
- 9개 이벤트 수신 → analytics_events 테이블 저장
- 특정 이벤트 추가 액션 (inquiry_submitted 알림, plan_upgrade_clicked 전환 추적)

### DA-16: Materialized View + pg_cron 집계
- `supabase/migrations/20260420500000_analytics_kpi_tables.sql`:
  - `analytics_events` 테이블 + 3개 인덱스
  - `analytics_daily_summary` 테이블
  - RLS 정책 (admin 읽기, service_role 쓰기)
  - `refresh_analytics_daily_summary()` PL/pgSQL 함수 (UPSERT)
  - pg_cron 스케줄 (매일 KST 01:00 전날 집계, pg_cron 미설치 시 graceful skip)

## 수정 파일별 검증 상태

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| src/pages/AdminAnalytics.tsx (신규) | 11개 KPI 위젯 + 온보딩 퍼널 | grep "analytics_daily_summary" OK | verified |
| src/config/routes.ts:78,423-430 | AdminAnalytics lazy import + 라우트 등록 | grep "AdminAnalytics" OK (2건) | verified |
| src/App.tsx | 머지 충돌 해결 (PostHogProvider + PageViewTracker) | grep "PostHogProvider" OK | verified |
| server/analytics.py | 머지 충돌 해결 (task-2020-dev6 버전 채택) | grep "flush_analytics" OK | verified |
| server/tests/test_analytics.py | 머지 충돌 해결 (33개 테스트, task-2020-dev6 버전) | pytest 33 passed | verified |
| supabase/functions/posthog-webhook/index.ts (신규) | PostHog webhook 수신 Edge Function | grep "POSTHOG_WEBHOOK" OK | verified |
| supabase/migrations/20260420500000_analytics_kpi_tables.sql (신규) | KPI 테이블/함수/cron | grep "analytics_daily_summary" OK | verified |
| docs/posthog-kpi-dashboard-guide.md (신규) | KPI/리텐션/퍼널 설정 가이드 (551줄) | grep "리텐션" OK (35건) | verified |

## 테스트 결과

- **pytest (analytics)**: `server/tests/test_analytics.py` — 33 passed (0.10s)
- **pytest (main 회귀)**: `server/tests/test_main.py` — 41 passed (2.27s)
- **Vite build**: 성공 (8.93s, 141 precache entries)
- **TypeScript**: tsc --noEmit --skipLibCheck 에러 0건

## L1 스모크테스트 결과

- 서버 재시작: 성공 (Vite dev server 5173 포트)
- API 응답 확인: 해당없음 (프론트엔드 페이지 + 마이그레이션 작업)
- 스크린샷: /admin/analytics 접속 → 로그인 페이지 리다이렉트 확인 (AuthGuard 정상 동작). 경로: memory/reports/task-2024-screenshot.png
- 빌드 에러: 0건
- 콘솔 에러: 0건

## 발견 이슈 및 해결

### 자체 해결 (4건)
1. **server/analytics.py 머지 충돌** — task-2017과 task-2020 브랜치 간 충돌. task-2020-dev6 버전(포괄적 PII 필터 28개 키) 채택하여 해결
2. **src/App.tsx 머지 충돌** — PostHogProvider import 충돌. task-2020-dev6 버전(커스텀 PostHogProvider 컴포넌트 + PageViewTracker) 채택
3. **server/tests/test_analytics.py 머지 충돌** — 4개 vs 33개 테스트. 포괄적인 task-2020-dev6 버전(33개 테스트) 채택
4. **AdminAnalytics 컬럼명 불일치** — 프론트엔드에서 `.order("date")` 사용 vs 마이그레이션의 `summary_date` 컬럼. summary_date로 통일

### 범위 외 미해결 (1건)
1. **main 브랜치 머지 충돌** — worktree finish 시 main과 conflict 발생. 범위 외 사유: 기존 task-2017/task-2020 브랜치 머지 잔여 충돌. 아누 판단으로 PR 기반 머지 필요

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-2024-dev4
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-2024-dev4
- **머지 의견**: pytest 74건 전체 PASS, vite build 성공, 머지 충돌 3건 모두 해결. main과의 sync conflict는 기존 브랜치 잔여 충돌이므로 수동 머지 또는 충돌 해결 후 머지 필요.

## 모델 사용 기록

- 팀원: 사라스바티 / 작업 내용: DA-12/14 AdminAnalytics 페이지 + routes.ts 수정 / 사용 모델: sonnet
- 팀원: 카르티케야 / 작업 내용: DA-15/16 PostHog webhook Edge Function + SQL 마이그레이션 / 사용 모델: sonnet
- 팀원: 락슈미 / 작업 내용: DA-13/14 PostHog KPI/리텐션/퍼널 설정 가이드 문서 / 사용 모델: sonnet
- 팀장: 비슈누 / 작업 내용: 머지 충돌 해결 3건, 컬럼명 정합성 수정, 통합 검증 / 사용 모델: opus

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


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


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


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


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


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


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


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


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


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


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