---
task_id: task-1951
type: plan
scope: system
created: 2026-04-18
updated: 2026-04-22
status: in-progress
devlop_by: task-1953 (2026-04-19, 경쟁사 대응+데이터/분석+마케팅/GTM 3건 디벨롭), task-1985 (2026-04-20, task-1969~1983 완료 반영), task-2000 (2026-04-20, 전수 재점검 — OB-1~3 main 반영 확인), task-2003 (2026-04-20, task-1996~2002 반영), task-2008 (2026-04-20, task-2004~2007 반영 — MW/TST/G4/RC/D4 체크), task-2013 (2026-04-20, task-2009~2011 반영 + 완료율 집계), task-2019 (2026-04-20, task-2011~2016 반영 — RC-5~6 완료 체크 + 완료율 갱신), task-2025 (2026-04-20, task-2017/2018/2020 반영 — DA-1~11 + CF-1~2 체크 + 완료율 65.3%), task-2027 (2026-04-20, task-2022~2024 반영 — CF-3~4 + OB-4~7 + DA-12~16 체크 + 완료율 71.6%), task-2036 (2026-04-20, task-2034/2035 반영 — 코드 유실 주석 + 운영 게이트 8건 점검 + 완료율 74.4%), task-2038 (2026-04-21, task-2036~2037 반영 — PL-1~7 재구현 완료 + G-CF-1/2 + G-DA-1 체크 + 완료율 79.2%), task-2102 (2026-04-22, 베타 UX 개선 31건 전체 반영 — BUX-1~31 추가 + 완료율 77.1%)
---

# 인슈로(InsuRo) 시스템 계획서

**task**: task-1951
**목표**: 인슈로 서비스를 상용화 가능한 최종 버전으로 완성. 보안 취약점 제거, 결제 연동, 콘텐츠 작성 세분화, 인포키워드/AI 자동화/인슈위키 기능 구현.
**승인**: 에이전트 미팅 합의 (2026-04-18, Cycle 1~2 완료)
**근거**: memory/meetings/2026-04-18-insuro-final-version-plan.md, memory/research/insuro-page-audit.md, memory/research/insuro-vision-strategy.md

---

## 1. 프로젝트 개요

### 서비스 정의
- 보험설계사 대상 AI 마케팅 플랫폼
- 기술 스택: Vite + React + TypeScript + Tailwind CSS + Shadcn/ui + Supabase + FastAPI(Python)
- 42개 라우트 (30개 완성, 5개 부분완성, 3개 스텁, 4개 관리자)

### 핵심 목적
1. **가족(지점 식구들) 역량 강화** — 1차 사용자에게 AI 기반 마케팅/영업 도구 제공
2. **플랜 차별화 → 비용 충당** — 5단계 플랜으로 수익 모델 구축
3. **리쿠르팅 유도** — "우리 가족이 되고 싶다" → 가입 문의

### 히든 목적
- 설계사들에게 실질적 기능 제공
- 인슈위키, 인포키워드 등 "우리 조직 구성원만 사용 가능한 최고수준 노하우 기능" 노출 (사용 불가)
- "이 기능 쓰고 싶으면 우리 가족이 되세요" → 리쿠르팅 문의

---

## 2. 플랜별 기능 매트릭스

### 무료 (일반 보험설계사)
- 콘텐츠 생성: 블로그 1채널, 월 5회, Gemini Flash (Haiku급)
- 프리셋: "블로그용" 1종만
- 도구: 계산기만 (3개 무료)
- CRM: 없음
- 목적: 회원 유입 + 맛보기 → "이게 되네?" 성공 경험

### 프로 (관심 있는 설계사)
- 콘텐츠 생성: 5채널 전체, 월 100회, Gemini Pro (Sonnet급)
- 프리셋: "블로그용 / SNS용 / 제안서용" 3종 + 고급 옵션 (어투, GEO, SEO)
- 도구: 전체 (계산기, 보험사 전산, 외부 사이트)
- CRM (세부 분화):
  - 고객 목록/CRUD: ✅
  - 파이프라인 DnD: ✅
  - 메신저 실시간 채팅: ✅
  - CRM 대시보드 통계: ✅
  - AI 고객 분석: ❌ (프리미엄)
  - Push 알림: ❌ (프리미엄)
- 키워드 분석: 기본
- 목적: "돈 쓸 만하다" 체감

### 프리미엄 (100명 한정)
- 콘텐츠 생성: 무제한, 최상위 모델 (Opus/Gemini Pro급)
- CRM (세부 분화):
  - 프로 전체 기능: ✅
  - AI 고객 분석: ✅
  - Push 알림: ✅
- 키워드 분석: 전체 공개
- 노하우 가이드: 월 2건 공개
- 커뮤니티 단톡방 접근
- Threads 자동 포스팅
- "잔여 OO석" 실시간 카운터 (FOMO)
- 목적: 희소성 + 커뮤니티 가치

### 엔터프라이즈 (조직/지점 단위)
- 프리미엄 전체 + 조직 관리 기능
- 멀티 사용자 관리
- 사용량 리포트
- (추후 상세 정의)

### 히든 (가족 전용)
- 전체 기능 + 관리자 권한
- 인포키워드: 정보성 키워드 분석 알고리즘
- AI 포스팅 자동화: 전체 파이프라인 (ThreadAuto + 티스토리 + 네이버 AI원스탑)
- 인슈위키: 전체 열람 + 기여 가능
- 서울대보험쌤 노하우 템플릿 RAW
- 접근: DB 수동 플래그 (시스템에 히든 플랜 UI 없음, 제이회장님 직접 부여)
- 목적: 가족 역량 극대화

---

## 3. 핵심 기능 상세

### A. 콘텐츠 작성 기능 세분화

#### 현재 상태
- /generate: SSE 스트리밍 AI 콘텐츠 생성 (Edge Function 기반)
- 5개 채널: 네이버 블로그, 티스토리, 인스타그램, Threads, 유튜브&릴스
- 이미지 생성 기능 포함

#### 변경 사항
1. **LLM 모델 플랜별 차별화**
   - 서버사이드 allowlist로 플랜→모델 매핑 강제
   - 클라이언트 파라미터 무시 (보안)
   - 무료=Gemini Flash, 프로=Gemini Pro, 프리미엄/히든=Opus/Gemini Pro 1.5
2. **프리셋 기반 2단계 UI**
   - 1단계(기본): "블로그용 / SNS용 / 제안서용" 3개 프리셋 버튼
   - 2단계(고급): "직접 설정" 토글 → 어투 선택, GEO 모드, 키워드 자동 삽입, SEO 최적화 레벨, 이미지 자동 생성
   - 잠긴 옵션: LockedFeatureOverlay 공용 컴포넌트로 블러+CTA
3. **채널 제한**
   - 무료: 1채널 (네이버 블로그만)
   - 프로 이상: 5채널 전체
4. **사용량 제한 (서버사이드 집행)**
   - usage_tracking 테이블로 월별 생성 횟수 관리
   - 한도 초과 시 429 → PlanUpgradeDialog 자동 트리거
   - 원자적 카운터: `UPDATE SET count = count + 1`

### B. 인포키워드 기능

#### 개요
- 정보성 키워드 분석 — 서울대보험쌤만의 키워드 전략
- 최상위 플랜(프리미엄/히든)에서만 활용 가능

#### 구현 방향
1. **메뉴 노출**: 분석&도구 탭 하위에 배치, 잠금 아이콘 포함
2. **잠금 UI**: 정적 스크린샷 블러 + "프리미엄 가족만 사용 가능" + 30초 소개 영상 CTA
3. **백엔드**: 비동기 작업 (FastAPI BackgroundTasks → DB 캐싱)
   - `POST /api/keywords/analyze` → job_id 반환
   - `GET /api/keywords/result/{job_id}` → 폴링
4. **서버사이드 접근 제어**: `@require_plan(min_level="premium")` 데코레이터

### C. AI 자동화 기능

#### 개요
- ThreadAuto 통합: Threads 자동 포스팅
- 티스토리: 콘텐츠 작성 + 자동 업로드
- 네이버: AI원스탑까지만 (자동 업로드 미포함)
- 스케줄링, 배치 실행

#### 구현 방향
1. **UI**: AutomationStepper 컴포넌트 (워크플로우 단계 시각화)
2. **채널 연동**: OAuth 토큰 관리 (AES-256-GCM 암호화)
3. **백엔드**: FastAPI 전담 (외부 API 연동, 긴 작업)
   - `POST /api/content/publish` — 채널별 발행
   - `POST /api/channels/connect` — OAuth 연동
4. **Phase 4에 배치**: 핵심 서비스 안정화 후 착수

### D. 인슈위키 기능

#### 개요
- "가족만 사용 가능한 보험 지식 위키"
- 소개만 하고 링크 따로 구현
- 메뉴 노출 → 클릭 시 가입 문의 또는 소개 페이지

#### 구현 방향
1. **소개 페이지**: 헤드카피 + 위키 콘텐츠 목록(제목만) + 첫 2문장 미리보기(블러) + 가족 문의 CTA
2. **성과 대시보드 FOMO**: "이번 주 인슈위키 활용 설계사 평균 블로그 유입량: X회" 실시간 노출
3. **위키 기여 랭킹** (Phase 3+): 설계사별 기여도 포인트 → 플랜 크레딧 전환
4. **네비게이션**: 안내&설정 탭 하위에 배치
5. **기여 랭킹 프론트엔드**: WikiRankingSection 컴포넌트 + useWikiRankings 훅 구현 완료 (task-1975). InsuWikiIntro 페이지에 통합.

### E. CRM 대화 자동 요약 시스템 (task-1963 설계, task-1964 구현)

#### 개요
- 보험 설계사-고객 채팅 종료 후 자동 요약 생성
- 680줄 설계 문서(task-1963) 기반 MVP 구현
- 벡터 검색 제외, 키워드 검색만 MVP

#### 구현 사항
1. **DB**: conversation_summaries, summary_topics 테이블 + RLS + 인덱스
2. **API 3종**:
   - POST /summarize — 대화 요약 생성 (AI 호출)
   - GET /summaries — 고객별 요약 히스토리 조회
   - GET /summaries/search — 키워드 검색
3. **UI**: 
   - CrmMessenger "상담 종료" 버튼 (트리거)
   - SummaryTab (요약 히스토리, 검색, 태그 Badge, 페이지네이션)
4. **트리거**: 종료 버튼 + 타임아웃 백업 (설계에 포함, MVP는 버튼만)

#### 현재 상태
- main 브랜치 반영 완료 (task-1964 머지)
- conversation_summaries/summary_topics 테이블, 요약 API 3종, SummaryTab UI 모두 main에 존재

---

## 4. 통합 아키텍처

### 콘텐츠 팩토리 파이프라인 (task-1952 디벨롭)
```
인슈위키(D) → 키워드 선정(B) → 콘텐츠 자동 생성(A) → 멀티채널 배포(C)
```
- 단계별 독립 사용 가능하되, 연결 시 원클릭 워크플로우 제공
- **MVP 범위**: D→B→A 3단계만 원클릭, C는 "미리보기 후 수동 발행"으로 대체
- **C 자동화 도입 조건**: AI 신뢰도 ≥0.92 & 편집자 승인률 3주 연속 ≥95%
- 파일럿: 1개 카테고리(FAQ형) 한정 → 4주 모니터링 후 확대
- 롤백 트리거: 오류율 >2% 즉시 중단

#### 단계별 입출력 인터페이스 (Pydantic 스키마 계약, v1)
- **D 출력**: `WikiKnowledge(topic: str, keywords: list[str], summary: str)`
- **B 입력**: WikiKnowledge → **B 출력**: `KeywordSet(primary: str, secondary: list[str], volume: int)`
- **A 입력**: KeywordSet → **A 출력**: `ContentDraft(title: str, body: str, seo_meta: dict, images: list[str])`
- **C 입력**: ContentDraft → **C 출력**: `PublishResult(channel: str, url: str, status: str)`
- 스키마 `pii=True` 어노테이션 → 로그 자동 마스킹

#### 중간 저장/재시도 메커니즘
- `pipeline_runs` 테이블: 단계별 스냅샷 저장
- 비동기 작업 큐: Celery/ARQ, 상태 머신 `PENDING → RUNNING → SUCCESS / FAILED`
- 재시도: 지수 백오프(최대 3회)
- 부분 롤백 전략: A 결과 보존, C 실패만 `FAILED` 마킹 → 재발행 큐 이동

#### 배치 실행 스케줄러
- cron 기반 예약 실행
- Phase 4 후반: Strangler Fig 패턴으로 이벤트 드리븐 전환 검토

#### 진입 UI
- 진입점: "콘텐츠 만들기" 버튼 1개
- 단계 라벨: "준비 중 → 키워드 분석 → 초안 생성 → 채널 발행"
- AutomationStepper 확장 + Supabase Realtime 실시간 상태 (폴백: 5s 폴링, 지수 백오프 최대 60s)

### 역할 분담 (FastAPI vs Edge Functions)
- **Edge Functions**: 인증, 경량 CRUD, Webhook 수신, SSE 스트리밍 (기존 generate-content 유지)
- **FastAPI**: AI 파이프라인 라우팅, 외부 API 중계 (티스토리/네이버/Threads), 무거운 연산, 키워드 분석

### 서버사이드 플랜 검증 (필수)
- FastAPI 미들웨어: 매 요청마다 DB에서 user_plans 조회 (Redis 캐시 TTL 5분)
- `@require_plan(min_level)` 데코레이터 패턴
- AI 모델: 서버 allowlist로 플랜→모델 매핑 강제
- 크레딧: 트랜잭션 기반 선차감 후 실행

### 비용 차단기 (Cost Circuit Breaker)
- 계정별/일별/월별 비용 상한선 설정
- 임계치 도달 시 자동 차단
- 관리자 알림 트리거

---

## 5. Phase별 구현 계획

### Phase 0: 보안 핫픽스 ✅ 완료 (task-1955)
**DRI**: 개발팀 (Lv.1~2)
**게이트**: Phase 0 완료 승인 없이 Phase 1 진행 금지

| # | 작업 | 레벨 | 상세 |
|---|------|------|------|
| C1 | 테스트 계정 하드코딩 제거 | Lv.1 | AuthForm.tsx |
| C2 | AdminGuide isAdmin 권한 추가 | Lv.1 | AdminGuide.tsx |
| C3 | AdminCrmConfig isAdmin 권한 추가 | Lv.1 | AdminCrmConfig.tsx |
| C4 | CustomerChat 인증 강화 | Lv.2 | 토큰 만료, rate limit |
| M5 | Dashboard 깨진 라우트 수정 | Lv.1 | Dashboard.tsx |
| S1 | H2/H3 스텁에 출시 예정 시기 표시 | Lv.1 | AiOnestop.tsx, AiAutomation.tsx |

### Phase 1: 기반 안정화 ✅ 완료 (task-1956)
**DRI**: 개발팀 (Lv.1~2)

| # | 작업 | 레벨 | 상세 |
|---|------|------|------|
| M4 | Naver API CORS 프록시 | Lv.2 | FastAPI 프록시 엔드포인트 |
| M1 | Supabase 5개 테이블 타입 보완 | Lv.2 | types.ts + supabase gen types |
| M2 | 월 필터 동적화 | Lv.1 | MarketNewsletter, PremiumComparison |
| M3 | AI 호출 방식 통일 (subprocess→API) | Lv.2 | server/ai_parser.py, anu_provider.py (task-1973 완료) |
| H6 | DigitalNamecard 상담 CTA 실동작 | Lv.1 | DigitalNamecard.tsx |
| H7 | /api/ai/generate 스텁 해소 | Lv.2 | server/main.py |
| T1 | 자동화 테스트 인프라 구축 | Lv.2 | 스모크 테스트 스위트 30개 라우트 |
| M6 | `as any` 캐스트 정리 (M1 완료 후) | Lv.2 | Settings, AdminSubscriptions 등 |

### Phase 2: 결제 연동 + A(콘텐츠 세분화) — Phase 2A ✅ 완료 (task-1957), Phase 2B(Stripe) 보류
**DRI**: 개발팀 (Lv.2~4)

| # | 작업 | 레벨 | 상세 |
|---|------|------|------|
| H1 | Stripe 결제 연동 | Lv.4 | Checkout + Webhook + 플랜 동기화 |
| P1 | subscription_plans 시드 데이터 5단계 정렬 | Lv.2 | Basic 제거, 프리미엄/히든 추가 |
| P2 | 서버사이드 플랜 검증 미들웨어 | Lv.3 | require_plan 데코레이터, DB 조회 |
| P3 | AI 모델 서버 allowlist | Lv.2 | 플랜→모델 매핑 강제 |
| P4 | 사용량 제한 서버사이드 집행 | Lv.2 | usage_tracking 테이블 + 429 응답 |
| P5 | 채널 제한 구현 | Lv.2 | 무료=1채널, 프로=5채널 |
| A1 | 콘텐츠 작성 프리셋 UI | Lv.2 | 3종 프리셋 + 고급 옵션 토글 |
| A2 | LockedFeatureOverlay 공용 컴포넌트 | Lv.2 | 블러+CTA 재사용 컴포넌트 |
| A3 | FeatureGate 선언적 컴포넌트 | Lv.2 | planFeatureMap.ts 기반 분기 |
| A4 | PlanUpgradeDialog 플랜명 정렬 | Lv.1 | DB 업데이트로 자동 반영 |
| F1 | Free 사용자 AI 맛보기 (월 5회) | Lv.2 | 첫 1건 제한 없음 → 이후 제한 |

### Phase 3: 기능 완성 + B(인포키워드) + D(인슈위키) ✅ 완료 (task-1958)
**DRI**: 개발팀 (Lv.2~3)

| # | 작업 | 레벨 | 상세 |
|---|------|------|------|
| H5 | CrmPipeline DnD (dnd-kit) | Lv.2 | CrmPipeline.tsx |
| K1 | AI 코파일럿 상담 | Lv.3 | CRM 메신저 + AI 분석 사이드패널 |
| B1 | 인포키워드 잠금 메뉴 UI | Lv.2 | 블러 스크린샷 + CTA |
| B2 | 인포키워드 백엔드 (비동기 분석) | Lv.3 | FastAPI BackgroundTasks |
| B3 | 인포키워드 서버사이드 접근 제어 | Lv.2 | @require_plan(premium) |
| D1 | 인슈위키 소개 페이지 | Lv.2 | 헤드카피 + 미리보기(블러) + CTA |
| D2 | 인슈위키 성과 대시보드 FOMO | Lv.2 | 실시간 유입량 카운터 |
| D3 | 인슈위키 기여 랭킹 시스템 설계 | Lv.2 | 포인트 → 크레딧 전환 |
| P6 | CRM 페이지 PlanGuard 적용 (프로 이상) | Lv.2 | AuthGuard + PlanGuard 분리 |
| P7 | 100명 한정 프리미엄 트랜잭션 잠금 | Lv.2 | SELECT FOR UPDATE |

### Phase 4: 확장 + C(AI 자동화) — 대부분 완료 (task-1959~1960, task-1969~1983, task-1996~1999), D4 미착수
**DRI**: TBD (최소 3개 팀 병렬 권장)

| # | 작업 | 레벨 | 상세 |
|---|------|------|------|
| H4 | KeywordAnalysis 3탭 완성 | Lv.3 | 또는 /generate 통합 |
| C1 | ThreadAuto 통합 | Lv.3 | Threads 자동 포스팅 |
| C2 | 티스토리 자동 업로드 | Lv.3 | 콘텐츠 작성 + 발행 |
| C3 | 네이버 AI원스탑 | Lv.2 | 자동 업로드 미포함 |
| C4 | 스케줄링/배치 실행 | Lv.2 | cron 기반 예약 포스팅 |
| C5 | AutomationStepper UI | Lv.2 | 워크플로우 시각화 |
| C6 | OAuth 토큰 관리 | Lv.3 | AES-256-GCM 암호화 |
| C7 | 콘텐츠 팩토리 파이프라인 통합 | Lv.3 | D→B→A→C 원클릭 워크플로우 |

**→ task-1960에서 MVP 구현 완료 (D→B→A 3단계, C는 수동 발행)**
**→ task-1969~1983: 전수조사 적발 수정, subprocess→asyncio 전환, E2E 테스트 20건, 위키 랭킹 프론트, Lovable 의존성 제거, Supabase Native Auth 확인, 모바일 최적화, keyword_jobs DB 이관, 랭킹 RPC 전환**
**→ task-1996~1999: TST/UX 게이트 PASS(task-1996), API/DB/컴포넌트 문서화 완료(task-1997), Lighthouse 성능 최적화(task-1998), 보안 침투 테스트 G4-1 PASS(task-1999)**

| T2 | 성능 최적화 + 통합 테스트 | Lv.2 | Lighthouse 90+, E2E |
| D4 | 프로덕션 최종 배포 + 모니터링 | Lv.2 | 인프라 설정 |

---

## 6. DB 스키마 추가 테이블

### 신규 테이블
- **user_plans**: user_id, plan_type(enum), started_at, expires_at, stripe_subscription_id, is_active
- **usage_tracking**: user_id, month, generation_count, channel_count (월별 집계)
- **content_generations**: id, user_id, prompt, model_used, token_count, result, channel_target, published_at
- **keyword_jobs**: id, user_id, keyword, status(enum), result_json, created_at — Supabase 테이블 이관 완료 (task-1983, 인메모리→DB)
- **channel_connections**: user_id, platform(enum), access_token_encrypted, refresh_token_encrypted, expires_at
- **payments**: user_id, stripe_event_id, amount, currency, status, created_at
- **wiki_contributions**: user_id, content_id, contribution_type, points, created_at

### 기존 테이블 활용
- **threads_tokens**: 이미 설계됨 (threads-feature-spec.md)
- **threads_posts**: 이미 설계됨
- **contents**: channel='threads' + content_type 컬럼 활용
- **feature_definitions**: 카테고리 확장 (model, channel, knowhow)

---

## 7. API 엔드포인트 추가

### 신규 FastAPI 엔드포인트
- `POST /api/content/generate` — 플랜별 모델 분기 + SSE 스트리밍
- `GET /api/content/history` — 사용자별 생성 이력
- `POST /api/content/publish` — 멀티채널 발행
- `GET /api/keywords/analyze` — 인포키워드 분석 (비동기)
- `GET /api/keywords/result/{job_id}` — 분석 결과 폴링
- `POST /api/payments/checkout` — Stripe Checkout 세션
- `POST /api/payments/webhook` — Stripe 웹훅 수신
- `GET /api/plans/current` — 현재 플랜 조회
- `POST /api/channels/connect` — 외부 채널 OAuth 연동

### 기존 수정
- `/api/insuro/ai/generate` → 신규 `/api/content/generate`로 대체 후 deprecated
- 전체 엔드포인트에 rate limiting 미들웨어 추가

---

## 8. 위임 계획

### 개발팀 배분 (최적)
- **백엔드 팀**: Phase 0~2 보안/결제/플랜 검증 + Phase 3 인포키워드 백엔드
- **프론트엔드 팀**: Phase 1 라우트 완성 + Phase 2 콘텐츠 UI + Phase 3 잠금 UI/인슈위키
- **AI/자동화 팀**: Phase 4 AI 자동화 전담 (ThreadAuto, 티스토리, 네이버)
- **기획/콘텐츠팀**: 인슈위키 콘텐츠 작성 (Phase 2부터 선행 착수)

### 일정 견적
- Phase 0: 1~2주
- Phase 1: 2~3주
- Phase 2: 3~4주
- Phase 3: 3~4주
- Phase 4: 4~6주
- **총: 13~19주 (약 3.5~5개월)**, 3개 팀 병렬 기준

---

## 9. 보안 게이트 (Phase별)

### Phase 0~1 (배포 차단 조건)
- CRITICAL 4건 전부 해결
- 서버사이드 플랜 검증 미들웨어 구현
- AI 모델 allowlist 서버 적용
- Rate limiting 전 AI 엔드포인트 적용

### Phase 2 (결제 보안)
- OAuth 토큰 암호화 저장 (AES-256-GCM)
- 크레딧 시스템 서버사이드 (선차감 패턴)
- 감사 로그(Audit Log) 전 AI 호출 적용
- Stripe Webhook 서명 검증

### Phase 3 (기능 보안)
- 인포키워드 API 응답에서 권한 외 데이터 필드 완전 제거
- 100명 한정 트랜잭션 잠금 (SELECT FOR UPDATE)
- 인슈위키 콘텐츠 접근 제어 (쿼리 레벨)

### Phase 4 (자동화 보안)
- 침투 테스트 (플랜 우회 5가지 시나리오)
- 다중 계정 탐지
- 프롬프트 인젝션 방어
- 자동 포스팅 콘텐츠 무결성 검증

---

## 10. 검증 기준

- Phase 0: 보안 4건 수정 확인 (grep 검증 + 브라우저 접근 테스트)
- Phase 1: 타입 에러 0건 (pyright/tsc), CORS 테스트 통과, `as any` 0건
- Phase 2: Stripe 테스트 모드 결제 성공, 플랜 자동 전환, 서버사이드 검증 통과
- Phase 3: 인포키워드 잠금/해제 동작, AI 코파일럿 실시간 분석, 인슈위키 페이지 렌더링
- Phase 4: ThreadAuto 자동 포스팅 성공, 콘텐츠 팩토리 E2E, Lighthouse 90+

---

## 11. 온보딩 플로우 설계 (task-1952 디벨롭)

### Aha Moment 정의
"AI가 내 대신 블로그 글을 써줬다!" — 가입 후 5분 내 첫 가치 경험

### 온보딩 플로우
1. **가입 완료** → 빈 대시보드 금지 (Empty State 절대 금지)
2. **3단계 위자드** (프로그레스 바 1/3 → 2/3 → 완료)
   - 1단계: 프리셋 선택 (블로그용/SNS용/제안서용) — 카드 UI, 탭 1번
   - 2단계: 최소 입력 (고객명 + 상품명 2필드만)
   - 3단계: AI 결과 확인 + "카카오톡으로 바로 공유" 버튼
3. **Show-First 온보딩** (A/B 테스트): 샘플 결과 먼저 보여주고 "내 고객명으로 바꿔볼까요?" 유도
   - 신규 유입 50%에 적용, 2주 후 완료율·D7 잔존율로 판정
   - 판정 기준: 완료율 +5%p 이상 시 전환
   - 조기 종료 조건: 완료율 -10%p 시 중단

### 이탈 방지
- 이메일 인증 미완료 → 핵심 기능 차단
- 리마인드: 24시간 1회, 총 3회 상한
- 미완료 시 Push 리마인드 (Capacitor/PWA 병행)

### DB 설계
- `profiles.onboarding_step` ENUM: `NULL (DEFAULT) → SIGNED_UP → FIRST_CONTENT_STARTED → FIRST_CONTENT_DONE → CONVERTED`
- NULL=레거시/미가입, SIGNED_UP=가입완료(BEFORE INSERT trigger 자동 설정), CONVERTED=온보딩 완료/기존사용자
- 기존 사용자는 migration(20260420100000)으로 CONVERTED 일괄 설정 완료
- `useOnboardingRedirect.ts`: SIGNED_UP + isNewUser(1시간 이내) 조건으로만 온보딩 리다이렉트 — NULL은 스킵
- 이탈 지점 측정: PostHog 퍼널 (단계별 이탈률)

### F1 통합
- 온보딩 AI 호출 = F1 기능과 동일 로직 공유 (중복 구현 금지)
- 온보딩 생성 = F1 월 5회 카운터 1회 차감
- 경량 모드: 응답속도 ≤1.5s, 정확도 ≥85% (미달 시 자동 F1 전환)

### Phase 배치
- **Phase 1**: 위자드 UI + 목업 결과 (샘플 출력)
- **Phase 2**: 실제 AI 연동 (F1과 통합)

---

## 12. 모바일/PWA 전략 (task-1952 디벨롭)

### 전략: PWA 유지 + Capacitor 점진적 강화 (2단계)

#### Phase M1 (1~3개월): PWA 완성도 강화
- 오프라인 캐싱 (Service Worker 최적화)
- Web Push 알림 완성
- 홈화면 설치 유도 배너
- FA 실사용 데이터 확보 (스토어 미등록)

#### Phase M2 (4~6개월): Android 앱스토어 우선 출시
- Capacitor 네이티브 래퍼 기술 스택 확정
- 카메라 명함 스캔 (`@capacitor/camera` + `@capacitor-mlkit/barcode-scanning`)
- 생체인증 (`@capacitor/biometric-auth`)
- 보안 스토리지 (`@capacitor/secure-storage`)
- FCM Push 알림 (Web Push → FCM 전환)
- Android 앱스토어 배포

#### iOS 대응
- Apple 금융앱 인허가 서류 착수: 즉시 (로키 기술 서류 + 외부 법무)
- 심사 기간 8주 버퍼 반영
- Android 출시 후 6개월 이후 재평가

### 모바일 UX 우선순위
- 한 손 조작, 터치 타겟 최소 48px
- FA 핵심 플로우: 고객 제안서 열람, 명함 스캔, CRM 빠른 메모
- MobileBottomNav 유지, 오프라인 캐싱 적용

### 주의
- PWA + 네이티브 이중 구조 장기 유지 불가 — Capacitor 단일 경로로 전환
- B2B 엔터프라이즈 비중 ≥30% 확인 시 MDM 도입 검토 (2주 내 데이터 집계)

---

## 13. 리쿠르팅 전환 CTA 구체화 (task-1952 디벨롭)

### CTA 문구 A/B/C 테스트 후보
- **(A) 직접형**: "TOP사업단 가족만 사용하는 기능입니다 — 지금 문의하기"
- **(B) 질문형**: "이 기능, 저만 못 쓰는 건가요? → 합류 상담 신청"
- **(C) 성과형**: "월 ○건 계약을 만드는 노하우, 지금 잠겨 있습니다"

### CTA 노출 정책
- 세션당 최대 2회 상한
- 동일 기능 중복 노출 금지
- 동일 유저 24시간 쿨다운
- A/B/C 무작위 배정, 최소 유의 샘플 n ≥ 200/변형

### 행동 기반 엔도우먼트 CTA 트리거
- 조건 3개 중 2개 충족 시 발동:
  1. 핵심 기능 3회 이상 사용
  2. 서비스 7일 이상 접속
  3. 비교 페이지 2회 이상 방문

### 잠금 기능 클릭 시 플로우
1. LockedFeatureOverlay CTA 변형 (props 주입 + CMS 오버라이드 가능)
2. "TOP사업단 가족이 되면 이 기능을 사용할 수 있습니다" + 문의 버튼
3. 모달 우선, 3회 이상 클릭 시 토스트로 전환 (피로도 감소)

### 전환 퍼널
잠금 클릭 → 소개 페이지 → 문의 → 상담 → 합류

### 인슈위키 성과 대시보드 FOMO
- "이번 달 TOP사업단 활용 횟수 1,247회" 실시간 카운터
- 상승 그래프 병치 (박탈감이 아닌 소속 욕구 자극)
- Supabase Realtime 구독

### KPI
- 1차: 잠금 클릭 → 문의 전환율 **15%**
- 2차: 문의 → 합류율 **30%**
- 4주 후 데이터 기반 최적 변형 단일화

### DB
- `recruting_inquiry` 테이블: user_id, feature_name, timestamp, status
- 전환 퍼널 이벤트 로그 수집

### CTA 텍스트 CMS 관리
- 마케팅팀 직접 수정 가능 (개발 배포 불필요)
- 변경 이력 로그 의무화 + 주 1회 개발팀 리뷰
- 구조 변경만 승인 필요, 텍스트는 즉시 반영

---

## 14. CRM 기능 세부 플랜 분화 (task-1952 디벨롭)

### 현행 → 변경
- **현행**: CRM 전체가 Pro 이상 PlanGuard로 통합
- **변경**: Phase 3 현행 유지 → Phase 4 인프라 → Phase 5 AI분석/Push 분리

### CRM 기능별 플랜 매핑
| CRM 기능 | 무료 | 프로 | 프리미엄 | 히든 |
|----------|------|------|----------|------|
| 고객 목록/CRUD | ❌ | ✅ | ✅ | ✅ |
| 파이프라인 DnD | ❌ | ✅ | ✅ | ✅ |
| 메신저 실시간 채팅 | ❌ | ✅ | ✅ | ✅ |
| CRM 대시보드 통계 | ❌ | ✅ | ✅ | ✅ |
| AI 고객 분석 | ❌ | ❌ | ✅ | ✅ |
| Push 알림 | ❌ | ❌ | ✅ | ✅ |

### 구현 방안
- **서버사이드**: `require_feature(feature_key)` 데코레이터 (require_plan 확장)
- **프론트엔드**: `<FeatureGate feature="crm_pipeline">` + `useFeatureAccess(featureKey)` 훅
- **설정**: `planFeatureMap.ts`에 `crm_*` 프리픽스 통일, CI 동기화

### 미리보기 모드 (잠금 UX)
- 허용: 대시보드 집계 통계, 보고서, 알림 설정
- 불허: 결제, 계약, 개인정보 수정
- PII 필드 완전 마스킹 유지
- 목록은 분기별 리뷰

### Feature Flag 서버
- Q3까지 현행 유지 (planFeatureMap.ts 정적 방식)
- Q4: 오픈소스 Unleash 자체 호스팅 도입
- 인터페이스 추상화하여 교체 가능 구조 설계

### Phase 배치
- Phase 3: 현행 유지 (CRM 전체 Pro 가드)
- Phase 4: require_feature 데코레이터 + FeatureGate 훅 인프라 구축
- Phase 5: AI 고객 분석 + Push 알림 (프리미엄) 우선 분리

### 테스트
- 5플랜 × 6기능 = 30케이스 파라미터화 테스트
- planFeatureMap.ts를 SSoT(단일 진실 공급원)로 자동 생성

---

### Lovable 의존성 제거 현황 (task-1979, task-1980)
- **AI Gateway**: `ai.gateway.lovable.dev` 의존성 완전 제거. AdminAIConfig.tsx에서 lovable provider 옵션/모델/URL/조건분기 제거. 기본 provider를 Google Gemini로 전환.
- **Auth**: `@lovable.dev/cloud-auth-js` 의존성 제거 완료. Supabase Native OAuth(`supabase.auth.signInWithOAuth`)로 전환 확인.
- **잔존 참조**: AdminAIConfig.tsx에서 AI provider 선택지로서의 lovable 참조는 worktree에서 제거 완료(main 미반영). package.json에서 `@lovable` 참조 0건.

### 모바일 최적화 현황 (task-1981)
- viewport-fit=cover 메타태그 추가 (iPhone notch 대응)
- 버튼 터치 타겟 44px(h-11) 적용
- Vite manualChunks: vendor(164KB)/ui(108KB)/query(37KB) 코드 스플리팅
- Capacitor appId/appName 교정 (com.insuro.hotline / 인슈로 핫라인)
- 파트너 로고 lazy loading 적용
- ⚠️ worktree(task-1981-dev7)에서 완료, main 미반영

## 15. 베타 UX 개선 Phase (task-2102, 31건)

**근거**: 2026-04-22 베타 테스트 UX 리뷰에서 도출된 31건의 개선 사항. Agent 미팅 합의에 따라 Phase 1(완료), Phase 2(진행중), Phase 3(미착수)로 분류.

### Phase 1: 완료 (17건) — 2026-04-22

#### 가이드 페이지 (3건)
| # | 작업 | 상태 | 완료 태스크 | 상세 |
|---|------|------|------------|------|
| BUX-1 | 가이드 목차 카테고리 제목 디자인 모던화 | ✅ 완료 | task-2092 | font-mono 10px → 13px 세미볼드 + primary 컬러 + accent 바 |
| BUX-2 | 가이드 본문 카테고리 배지 누락 + 디자인 개선 | ✅ 완료 | task-2093 | tag fallback(카테고리 label), SectionLabel 모던 pill 형태 |
| BUX-3 | 가이드 본문 스텝 표시 통일 (①②③) | ✅ 완료 | task-2093 | ArrowRight → StepBadge 통일 |

#### 마이페이지 (4건)
| # | 작업 | 상태 | 완료 태스크 | 상세 |
|---|------|------|------------|------|
| BUX-4 | 플랜 비교에 현재 플랜 하이라이트 | ✅ 완료 확인 | task-2098 | renderCtaButton() isCurrent/isHigher 분기 + bg-primary/5 "현재" Badge |
| BUX-5 | 디지털 명함 — 링크복사 + 설정 진입 UX | ✅ 완료 확인 | task-2096 | Copy 버튼(clipboard + toast) + "명함 설정" 버튼(/settings 이동) |
| BUX-6 | 마이페이지 — 상단/사용량/플랜비교 중복 정리 | ✅ 완료 | task-2096 | Hero Card 미니스탯 삭제, 플랜 비교 테이블 삭제(/plan 이동) |
| BUX-7 | 마이페이지 — 섹션 배치 재구성 | ✅ 완료 | task-2096 | 최종: Hero(간소화)→사용량→명함→최근활동. 대안 C 확정 (brainstorming) |

#### 개인설정 (4건)
| # | 작업 | 상태 | 완료 태스크 | 상세 |
|---|------|------|------------|------|
| BUX-8 | 프로필 기본정보에 전화번호/이메일 추가 | ✅ 완료 | task-2094 | profiles 테이블 phone_number/email 컬럼 + Settings.tsx 입력 필드 |
| BUX-9 | 콘텐츠 설정 CPA/프롬프트 적용 예시 미리보기 | ✅ 완료 | task-2095 | 콘텐츠 설정 탭 하단 실시간 프리뷰 영역 |
| BUX-10 | 콘텐츠 설정 CPA placeholder 변경 | ✅ 완료 | task-2095 | "예: 네이버예약" → "예: 카톡상담하기" + 오픈카톡 URL |
| BUX-11 | 개인설정 '구독' 서브탭 삭제 | ✅ 완료 | task-2094 | 플랜&구독 페이지 별도 존재하므로 중복 탭 제거 |

#### 플랜&구독 (6건)
| # | 작업 | 상태 | 완료 태스크 | 상세 |
|---|------|------|------------|------|
| BUX-12 | 이벤트 배너 좌우 배치 + 글자 확대 | ✅ 완료 | task-2097 | 할인 배너+잔여석 카운터 1카드 통합, text-xs→text-sm |
| BUX-13 | 73석 동적 숫자 확인 | ✅ 완료 | task-2098 | useRemainingSeats() 서버사이드 검증, 폴백 73→0, API 실패 시 카운터 숨김 |
| BUX-14 | 현재 플랜 동적 하이라이트 + 업그레이드 CTA | ✅ 완료 확인 | task-2097 | renderCtaButton() "현재 플랜"/"시작하기" 분기 |
| BUX-16 | FAQ 보강 (4개 → 9개) | ✅ 완료 | task-2097 | 세금계산서/팀구매/데이터보안/AI저작권/결제수단 추가 |
| BUX-17 | 세부내용 폰트 50% 확대 | ✅ 완료 | task-2097 | 기능비교 테이블 13곳 text-xs→text-sm |
| BUX-18 | AI 토큰 항목 코드 검증 | ✅ 완료 | task-2098 | 데이터 파이프라인 정상. 무료=100, 베이직=500, 프로=2000, 맥스/히든=무제한 |
| BUX-19 | AI 모델 등급 동적 연동 | ✅ 완료 | task-2098 | AdminSubscriptions→plan_ai_models→Pricing 정상. 무료=haiku, 베이직/프로=sonnet, 맥스/히든=opus |

### Phase 2: 진행중 (3건)

| # | 작업 | 상태 | 진행 태스크 | 상세 |
|---|------|------|------------|------|
| BUX-21 | 네이버 검색량 조회 기능 오류 | 🔄 진행중 | task-2101 | 키워드 검색 시 에러, 대시보드 네이버블로그탭 API 활용 |
| BUX-25 | AI 주제 추천 실패 | 🔄 진행중 | task-2100 | 클릭 시 실패 → 코드 재분석 중 |
| BUX-26 | 콘텐츠 생성 실패 (failed to fetch) | 🔄 진행중 | task-2099 | API 연결 오류 수정 중 |

### Phase 3: 미착수 (11건)

#### 가이드 페이지 (1건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-31 | 시작가이드 API 키 등록 스텝 제거 → 개인설정 유도 | ⬜ 미착수 | 시작가이드 팝업에서 API 키 등록 스텝 삭제, "안내&설정→개인설정" 유도로 교체 |

#### 마이페이지 (1건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-30 | 시작가이드 팝업 "오늘은 이만보기" 기능 | ⬜ 미착수 | localStorage 날짜 저장, 당일 재표시 안 함 |

#### 플랜&구독 (1건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-15 | 결제 UI/플로우 구현 | ⬜ 미착수 | Agent 미팅 합의: "결제 시스템 준비 중" 모달 (카드 입력 폼 생성 금지). 토스/포트원 계약 후 연동 |

#### AI 마케팅 — AI 키워드 분석 (2건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-20 | 서브세션 재구성 + 구글 트렌드 분리 | ⬜ 미착수 | 3탭→5개 서브세션(네이버 검색량/구글 트렌드/인포키워드/상위노출/메인노출) |
| BUX-22 | 정보성 키워드(인포키워드) 구현 | ⬜ 미착수 | 아누 시스템 인포키워드 연동, 관리자 접근관리 토글, 플랜별 접근 제어 |

#### AI 마케팅 — AI 콘텐츠 작성 (3건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-23 | 면책 안내 디자인 개선 | ⬜ 미착수 | 주황 경고 박스 → 프로페셔널 디자인 개선 |
| BUX-24 | AI 모델 선택 레이아웃 상하→좌우 + 플랜별 동적 차별화 | ⬜ 미착수 | 좌우 카드형 배치, 플랜별 사용 가능 모델 동적 연동 |
| BUX-27 | "콘텐츠 유형 빠른 선택" vs "채널+주제+생성" UX 혼란 해소 | ⬜ 미착수 | 두 영역 차이 불명확, 원래 설계 의도 파악 후 UX 재검토 |

#### 분석&도구 (2건)
| # | 작업 | 상태 | 상세 |
|---|------|------|------|
| BUX-28 | 인슈위키 + 메디스캔 메뉴 추가 | ⬜ 미착수 | 분석&도구 좌측 메뉴 추가, 가이드 목차 위치 이동, 히든 플랜 전용 on/off 동적 연동 |
| BUX-29 | 메디스캔 페이지 초기 구현 | ⬜ 미착수 | 안내/소개 페이지 생성, 관리자모드 플랜 관리 on/off 동적 연동 |

---

## 16. 범위 제외 (의도적)

- premiumOnly 미완성 디자인 (맥스플랜 유도 의도 — 건드리지 말 것)
- 엔터프라이즈 플랜 상세 정의 (추후)
- 노하우 콘텐츠 제작 파이프라인 (콘텐츠팀 관할)
- 네이버 블로그 자동 업로드 (AI원스탑까지만)
- 바이럴 루프 메커니즘 (Phase 5 이후 재검토, 현재 사용자 기반 부족)

---

## 16. 경쟁사 대응 전략 (task-1953 디벨롭)

### 경쟁 환경 분석 요약

현재 국내 보험 테크 시장은 두 축으로 나뉜다. **소비자 직접 채널(D2C)** — 보험다모아·카카오페이보험·보맵 등이 소비자의 자가 비교·가입을 유도하며 설계사를 우회하는 방향 — 과 **내부 전용 AI 시스템** — 개별 보험사가 소속 설계사만을 위해 폐쇄적으로 운영하는 도구 — 이 양 극단을 형성한다.

결정적으로, **독립·GA 소속 설계사를 위한 범용 AI 마케팅 플랫폼은 공백 상태**다. 토스보험파트너(설계사 외부 지원 플랫폼)가 2025년 12월 종료되면서, 외부 플랫폼을 통해 역량을 키우려던 수천 명의 설계사가 대안 없이 시장에 남겨졌다. 인슈로는 이 공백을 정면으로 겨냥한다.

### 경쟁사별 강점·약점·인슈로 차별화 포인트

| 경쟁사 | 타깃 | 핵심 강점 | 결정적 약점 | 인슈로 차별화 포인트 |
|--------|------|-----------|-------------|----------------------|
| 보험다모아 | 소비자 | 공공기관 신뢰, 가격 투명성 | 설계사 지원 전무, UI 낙후 | 설계사 전용 AI 콘텐츠·CRM — 완전히 다른 레이어 |
| 카카오페이보험 | 소비자 | 카카오톡 트래픽, 간편결제 | 소액/단순 상품, 설계사 도구 없음 | 복잡한 보험 상품 AI 콘텐츠 생성 — 대면 영업 지원 |
| 토스보험파트너 | (종료) 설계사 | 앱 생태계, 데이터 | **2025.12 종료**, 내부 전용 전환 | 이탈 설계사 3,000명+ 흡수 기회 — 유일한 대안 |
| 보맵 | 소비자 | UX 우수, 건강데이터 연계 | "설계사 없어도 된다" 포지셔닝 | 설계사를 강화하는 정반대 가치 제안 |
| 보험사 내부 AI | 소속 설계사 | 자사 데이터 통합, 심사 연계 | 폐쇄형, 타사 전환 시 사용 불가 | 회사 불문 범용 플랫폼 — 자산이 설계사에게 귀속 |

### 왜 보험설계사가 인슈로를 써야 하는가 — 경쟁 우위 5가지

1. **설계사만을 위해 설계된 유일한 AI 마케팅 플랫폼** — 보험다모아·카카오·보맵은 소비자 향, 보험사 AI는 소속사 울타리 안. 인슈로는 설계사의 영업 프로세스(콘텐츠 생성→고객관리→지식 축적)를 위해 만들어졌다.

2. **인포키워드 + 인슈위키 — 지식이 무기가 되는 구조** — 복잡한 보험 약관/상품 비교를 설계사가 직접 소화해 콘텐츠로 변환. 경쟁사 중 이 기능을 제공하는 곳은 없다. 시간이 지날수록 이탈 비용이 높아진다.

3. **소속사 독립성 — 자산이 설계사에게 귀속** — 보험사 내부 AI는 이직 시 데이터 전체 소멸. 인슈로의 CRM, 콘텐츠 라이브러리, 활동 이력은 설계사 개인 자산이다.

4. **커뮤니티 기반 집단 지성** — 단순 SaaS 툴이 아닌, 성공 사례·노하우·시장 변화를 실시간 공유하는 커뮤니티가 내재화. 경쟁사 어디에도 없는 구조.

5. **히든 플랜 — 가족 생태계와 리쿠르팅의 선순환** — 지점장이 팀원 성장을 확인하고, 신규 설계사 리쿠르팅에 인슈로 자체를 활용. "인슈로를 쓰는 지점에 들어오면 이런 도구를 준다"는 메시지는 채용 경쟁력. 어떤 경쟁사도 복제 불가한 네트워크 효과.

### 경쟁사 대응 전략

#### 방어 전략 — 진입 장벽 구축

- **데이터 잠금 효과(Lock-in) 심화**: 콘텐츠 자산, 고객 히스토리, 커뮤니티 평판이 쌓일수록 이탈 비용 기하급수적 증가. 초기 프리·프로 허들을 낮춰 빠르게 자산 축적 유도.
- **커뮤니티 네트워크 효과**: 설계사 수 증가→정보 질/양 향상→신규 유입 유인 강화. 토스보험파트너 이탈 설계사를 조기 대거 온보딩하여 임계점(Critical Mass)에 빠르게 도달.
- **히든 플랜 지점 단위 계약화**: 개인이 아닌 지점(GA 지사) 단위 계약으로 지점장이 이탈 방지 역할. B2B2C 구조로 방어선 확장.

#### 공격 전략 — 시장 점유율 확대

- **토스보험파트너 이탈 설계사 집중 공략**: "토스파트너에서 인슈로로" 마이그레이션 패키지(데이터 이전 지원, 초기 3개월 프로 무료).
- **보험사 내부 AI 사용자에게 "독립성" 메시지**: "당신의 데이터는 당신 것이어야 합니다" — 소속사 전환이 잦은 경력 설계사층 공략.
- **카카오·보맵 대비 전문성 포지셔닝**: "간단한 보험은 앱으로, 진짜 보험은 전문가에게" — 복잡한 보장 설계·맞춤 설명 콘텐츠 영역에서 사례 중심 홍보.

### 시장 포지셔닝 맵

- **가로축**: 타깃 — 소비자 중심 ↔ 설계사 중심
- **세로축**: 기능 범위 — 단순 비교/가입 ↔ AI 마케팅·역량 강화

```
                    [AI 마케팅·역량 강화]
                            ▲
                            │          ★ 인슈로
                            │       (설계사 전용 AI 마케팅)
    [보험사 내부 AI]         │
    (폐쇄형·소속사 전용)     │
──────────────────────────────────────────────
[소비자 중심]               │       [설계사 중심]
      보맵 ●                │
  카카오페이보험 ●           │
     보험다모아 ●            │
                    [단순 비교·가입]
```

인슈로 포지션: 오른쪽 상단 "설계사 중심 × AI 마케팅·역량 강화" 영역의 **단독 점유자**. 유일한 경쟁 대상은 미래 후발주자이며, 네트워크 효과와 데이터 자산 선점으로 방어.

---

## 17. 데이터/분석 전략 (task-1953 디벨롭)

### 17-A. 사용자 행동 분석 이벤트 설계

모든 이벤트에 공통 속성 자동 첨부: `user_id`(UUID), `session_id`, `timestamp_utc`, `platform`, `app_version`, `plan_type`

#### 이벤트 카탈로그 (18개)

| # | 이벤트명 | 핵심 목적 | 주요 속성 | 활용 KPI |
|---|----------|-----------|-----------|----------|
| 1 | `page_view` | 페이지 유입 추적 | path, referrer, page_title | 페이지별 세션 수 |
| 2 | `feature_used` | 기능 사용률 | feature_name, duration_ms, success | 기능별 WAU |
| 3 | `content_generated` | 핵심 가치 행동 | channel, model_used, token_count, preset_type | 콘텐츠 생성 횟수/유저/월 |
| 4 | `plan_upgrade_clicked` | 전환 퍼널 | current_plan, target_plan, trigger_source | 무료→프로 전환율 |
| 5 | `cta_clicked` | CTA 효율 | cta_type, cta_variant, page, position | CTA 클릭률 |
| 6 | `locked_feature_viewed` | 업셀 기회 | feature_name, plan_required, click_count | 잠금 기능 관심도 |
| 7 | `onboarding_step_completed` | 온보딩 완주율 | step_number, step_name, time_spent_ms, skipped | 온보딩 완료율 |
| 8 | `keyword_analysis_started` | 기능 활성화 | keyword(SHA-256 해시), source | 키워드 분석 횟수/월 |
| 9 | `wiki_content_viewed` | 콘텐츠 소비 | content_id, preview_only, category | 프리뷰 이탈률 |
| 10 | `pipeline_run_completed` | 자동화 사용률 | stages_completed, duration_ms, error_stage | 파이프라인 성공률 |
| 11 | `search_performed` | 탐색 행동 | query_length, result_count, search_scope | 검색→활성 전환 |
| 12 | `content_copy_clicked` | 실제 활용 | content_id, channel | 콘텐츠 재사용률 |
| 13 | `upgrade_modal_dismissed` | 모달 효율 | modal_trigger, seconds_visible | 모달 전환율 |
| 14 | `inquiry_submitted` | 리드 생성 | inquiry_type, trigger_source | 잠금 클릭→문의 전환율 |
| 15 | `session_ended` | 리텐션 신호 | session_duration_ms, pages_visited | 평균 세션 시간 |
| 16 | `error_encountered` | UX 품질 | error_code, feature_context | 에러 발생률 |
| 17 | `preset_selected` | 프리셋 인기도 | preset_type, channel | 프리셋별 사용률 |
| 18 | `crm_contact_added` | CRM 활성화 | contact_source, total_contacts_after | CRM 활성 사용자 수 |

#### PII 보호 원칙
- 이벤트에 이메일/이름/전화번호 미포함 (ESLint 커스텀 룰 강제)
- 키워드는 SHA-256 해시 처리
- user_id는 Supabase auth.uid() UUID만 사용
- PostHog 세션 리플레이 입력 필드 마스킹 활성화
- 원시 이벤트 12개월 후 자동 삭제

### 17-B. A/B 테스트 인프라 선택: PostHog

#### 비교 분석 결과

| 항목 | PostHog | Mixpanel | 자체 구현(Supabase) |
|------|---------|----------|---------------------|
| 비용 | 무료 100만 이벤트/월 | 무료 20만/월, 유료 $20+/월 | 인프라 비용만 |
| 셀프호스팅 | 가능 (Docker/k8s) | 불가 | 해당 없음 |
| Feature Flags | 내장 | 별도 도구 필요 | 직접 구현 |
| 세션 리플레이 | 내장 | 미지원 | 구현 불가 |
| A/B 실험 | 내장 (통계 유의성 자동) | 내장 | 직접 구현 |
| 대시보드 | 엔지니어 친화, SQL 쿼리 | PM 친화, 폴리시드 UI | 완전 커스텀 |
| React/Python SDK | 공식 지원 | 공식 지원 | 직접 구현 |

#### 추천: PostHog (Cloud Free → 성장 시 셀프호스팅)

- **비용 효율**: 월 100만 이벤트 무료, 초기 비용 0원
- **올인원**: 이벤트 분석 + Feature Flags + A/B 실험 + 세션 리플레이를 단일 SDK로 해결
- **엔지니어 팀 친화**: Supabase, FastAPI 중심 스택과 문화적 정합성
- **Python SDK**: FastAPI 서버사이드 이벤트(결제, AI 생성 등) 직접 전송 가능
- **점진적 롤아웃**: Feature Flags로 특정 플랜/코호트에만 기능 노출

### 17-C. 전환율/리텐션 KPI 대시보드 설계

| KPI | 정의 | 초기 목표 | 경보 임계값 |
|-----|------|-----------|-------------|
| DAU/MAU 비율 | 스티키니스 지표 | ≥ 20% | < 10% |
| 무료→프로 전환율 | 월 내 업그레이드/전월 무료 유저 | ≥ 5% | < 2% |
| 프로→프리미엄 전환율 | 월 내 업그레이드/전월 프로 유저 | ≥ 8% | < 3% |
| D1 리텐션 | 가입 다음날 재방문율 | ≥ 40% | < 25% |
| D7 리텐션 | 가입 7일 후 재방문율 | ≥ 20% | < 10% |
| D30 리텐션 | 가입 30일 후 재방문율 | ≥ 10% | < 5% |
| 콘텐츠 생성/유저/월 | content_generated 수/MAU | ≥ 8회 | < 3회 |
| 온보딩 완료율 | 최종 단계 완료/가입 | ≥ 60% | < 35% |
| 잠금→문의 전환율 | inquiry/locked_feature_viewed | ≥ 3% | < 1% |
| ARPU | 총 MRR/MAU | 성장 추이 모니터링 | MoM -10% |
| Churn Rate | 전월 유료 중 당월 미활성/취소 | ≤ 5% | > 10% |

### Phase 배치
- **Phase 3**: PostHog 셋업 + 핵심 이벤트 18개 계측 + KPI 대시보드 (DA-1~DA-16)
- **Phase 4**: A/B 테스트 인프라 + 리텐션 분석 + 세션 리플레이 (DA-17~DA-24)

### 17-D. 이벤트 수집 기술 아키텍처

```
브라우저 → posthog-js (useAnalytics 훅) → PostHog Cloud
FastAPI → posthog-python (서버사이드) → PostHog Cloud
PostHog Cloud → Webhook → Supabase Edge Function → analytics_events 테이블
Supabase pg_cron → Materialized View (feature_usage_monthly, retention_cohorts)
```

- 프론트엔드: `posthog-js` + React hooks wrapper (`useAnalytics()`)
- 백엔드: `posthog-python` (결제 완료, AI 생성 등 서버만 알 수 있는 이벤트)
- PII 자동 제외: TypeScript 타입 정의에서 PII 필드 배제 + ESLint 룰 + 서버사이드 필터링

---

## 18. 마케팅/GTM 전략 (task-1953 디벨롭)

### 18-1. Go-To-Market 전략 프레임워크

| 단계 | 명칭 | 기간 | 핵심 목표 |
|---|---|---|---|
| 1단계 | 비공개 베타 | Phase 0~1 (1~5주) | 제품 검증, 내부 피드백 수집 |
| 2단계 | 얼리 액세스 | Phase 2~3 (6~13주) | 초기 사용자 200명, 프리미엄 100석 완판 |
| 3단계 | 공개 론칭 | Phase 4~ (14주~) | 무료 1,000명, 유료 전환 본격화 |

#### 1단계: 비공개 베타
- 가족 10명 비공개 초대, 사용 세션 녹화 + 인터뷰 피드백
- 비포/애프터 스크린샷 10종, 사용 후기 초안 3건 확보

#### 2단계: 얼리 액세스
- 가족 + 지인 50명으로 확장
- Threads/인스타그램 첫 게시 (비포/애프터 시리즈)
- 프리미엄 사전 예약 랜딩 페이지 오픈

#### 3단계: 공개 론칭
- 무료 가입 전면 개방
- 공개 론칭 이벤트: "AI 콘텐츠 생성 7일 챌린지"
- CTA A/B 테스트 본격 가동 → 4주 내 단일화

### 18-2. 채널별 보험 FA 유입 전략

#### A. SNS (Threads / 인스타그램)
- "서울대보험쌤" 계정 기존 팔로워 활용
- 콘텐츠: 비포/애프터 주 2회, "월 100건 콘텐츠 비결" 주 1회, 30초 릴스 주 1회
- Threads 자동 포스팅 기능 자체가 마케팅 소재

#### B. 단톡방 (카카오톡)
- 가족/지인을 통한 단톡방 자연 진입
- 레퍼런스 공유: "이 도구로 20분 작업이 3분" 형태
- 단톡방 전용 초대 코드 → 무료 체험 연결 → 추천 리워드(프로 1개월 무료)

#### C. 보험 커뮤니티
- 네이버 카페: 보험인이야기, 보험설계사 모임 등
- 오프라인 세미나/교육 연계: "디지털 마케팅 무료 교육" + 인슈로 시연
- 참가자 전원 30일 무료 체험 코드

#### D. 기존 고객(가족) 추천
- 추천 인센티브: 가입 시 추천인 프로 1개월 무료, 프리미엄 전환 시 3개월 무료
- 디지털 명함 하단 인슈로 로고 + "AI 마케팅으로 운영 중" 배지 자동 삽입

### 18-3. 100명 프리미엄 모집 전략
- **FOMO**: 실시간 잔여석 카운터, 50석 이하 시 "마감 임박" 배너
- **얼리버드**: 첫 100명 50% 할인 6개월 (선착순 자동 적용)
- **대기자 명단**: 100석 완판 후 이메일 대기 등록 → 이탈자 발생 시 순서대로 초대
- **선발 기준**: AI 콘텐츠 생성 건수, 추천 유입 인원, 커뮤니티 기여도, 피드백 횟수
- **론칭 이벤트**: "AI 콘텐츠 7일 챌린지" — 매일 1건 작성 SNS 인증 → 완주 시 프로 2개월 무료

### 18-4. 론칭 타임라인 + 마일스톤

```
Week  1~5   │ Phase 0~1 │ 비공개 베타     │ 가족 10명, 피드백 수집
Week  6~9   │ Phase 2   │ 얼리 액세스     │ 50명 확장, SNS 시작
Week 10~13  │ Phase 3   │ 프리미엄 모집   │ 단톡방/커뮤니티, FOMO
Week 14~19  │ Phase 4   │ 공개 론칭       │ 무료 개방, SEO 본격화
Week 20~23  │ 론칭 후    │ 데이터 최적화   │ A/B 단일화, 리텐션 분석
```

### 18-5. 마케팅 KPI

| 시점 | 무료 가입 | 프로 전환 | 프리미엄 |
|---|---|---|---|
| Phase 2 종료 | 200명 | - | 사전 예약 중 |
| Phase 3 종료 | - | 50명 | 100명 완판 |
| Phase 4 종료 | 1,000명 | 200명 | 완판 유지 |
| 론칭 3개월 후 | - | DAU 500 | - |

- 프로 전환율(마케팅 퍼널): 15% (잠금 클릭→문의→합류 기준), 월 업그레이드 전환율: ≥5% (17장 KPI와 동일)
- CPA: < 30,000원, LTV/CAC > 3
- D7 리텐션 ≥ 20%, D30 리텐션 ≥ 10% (17장 KPI 기준 단일화), NPS > 50

### 18-6. 리스크 및 대응
- **보험업 규제**: AI 콘텐츠에 "AI 초안 기반" 표기 기능, 금융광고 체크리스트 제공, 법무 자문 계약(Phase 2 이전)
- **경쟁사 진입**: Phase 4 이전 핵심 기능 완성, 커뮤니티 락인, 프리미엄 100명 앰배서더 전환
- **설계사 이탈**: D7/D30 모니터링, 이탈 방지 이메일 3단계 자동화(D+3/D+7/D+14)