---
task_id: task-1951
type: context
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, 전수 재점검 결과 기록), task-2003 (2026-04-20, task-1996~2002 결과 기록), task-2013 (2026-04-20, task-2009~2011 반영 + 완료율 최종 집계), task-2025 (2026-04-20, task-2017/2018/2020 반영 — DA-1~11 + CF-1~2 main grep 검증 기록), task-2027 (2026-04-20, task-2022~2025 결과 반영 — CF-3~4 + OB-4~7 + DA-12~16 grep 재점검 기록 + 완료율 71.6%), task-2102 (2026-04-22, 베타 UX 개선 31건 전체 반영 — BUX-1~31 3문서 업데이트)
---

# 인슈로(InsuRo) 시스템 맥락 노트

**task**: task-1951

---

## 1. 결정 근거

### 1-1. Phase 통합 결정: A(콘텐츠 세분화)를 Phase 2에 통합

**결정**: 콘텐츠 작성 세분화(LLM 모델/옵션 차별화)를 별도 Phase로 분리하지 않고 Phase 2(결제 연동)에 통합.

**근거**: 
- 아누(개발실장): "결제와 플랜 분기 로직은 본질적으로 같은 시스템. 플랜 테이블에 LLM 모델명, 토큰 한도, 옵션 플래그를 포함시키면 결제 완료 즉시 기능 해제가 자연스럽게 연동된다."
- 카르티케야(백엔드): "서버사이드 플랜 검증 미들웨어와 AI 모델 allowlist가 결제 시스템과 동일 계층에서 동작해야 정합성이 보장된다."
- 전원 합의(8/8)

**기각된 대안**:
- A를 Phase 1에 포함 → 기각. 결제 시스템 없이 플랜 분기는 테스트 불가.
- A를 별도 Phase 2.5로 분리 → 기각. 관리 포인트 증가, 결제와 분리 시 플랜 동기화 복잡도 급증.

### 1-2. C(AI 자동화)를 Phase 4로 후순위 배치

**결정**: ThreadAuto/티스토리/네이버 자동화를 최후순위(Phase 4)로 배치.

**근거**:
- 아누: "외부 API 의존도가 높고 복잡도 최상. 핵심 서비스 안정화 전 착수하면 리소스 분산."
- 카르티케야: "티스토리/네이버 API는 비공식이거나 변경이 잦다. 발행 실패 재시도 큐 없으면 CS 부담."
- 로키: "외부 플랫폼 토큰 저장 보안이 Phase 2 서버사이드 검증 완성 후에야 안전하다."
- 전원 합의(8/8)

**기각된 대안**:
- C를 Phase 3에 포함 → 기각. AI 코파일럿(킬러 피처)와 자동화를 동시 개발하면 양쪽 다 중단 위험.
- C를 A와 병렬 → 기각. 플랜 기반 채널 제한이 완성되어야 자동화 접근 제어가 가능.

### 1-3. 프리셋 기반 2단계 UI 채택

**결정**: 콘텐츠 작성 옵션을 프리셋 3종(기본) + 직접 설정(고급) 2단계로 제공.

**근거**:
- 락슈미(UX): "보험설계사는 IT 리터러시가 낮다. LLM 모델, GEO, SEO 옵션을 그대로 노출하면 인지 과부하."
- 사라스바티(프론트): "단일 컴포넌트 + 조건부 렌더링이 유지보수에 유리. 플랜별 별도 페이지는 비용 급증."
- 다수결(7/8, 다빈치만 원클릭 파이프라인 우선 제안이나 본 UI와 상충하지 않음)

**기각된 대안**:
- 전체 옵션 한 번에 노출 → 기각. 사용자 이탈 위험.
- 플랜별 완전 다른 UI → 기각. 유지보수 비용 기하급수적 증가.

### 1-4. 인슈위키: 소개 + FOMO 전략

**결정**: 인슈위키를 단순 소개 페이지가 아닌, 성과 대시보드 FOMO + 기여 랭킹 시스템으로 확장.

**근거**:
- 다빈치: "콘텐츠 자체보다 '다른 설계사들이 이미 쓰고 있다는 숫자'가 더 강력한 FOMO. 사람은 기능 설명서를 읽고 전환하지 않는다."
- 락슈미: "'가족 전용'을 배타적이 아닌 열망의 대상으로 포지셔닝해야 한다."
- 다수결(7/8)

**기각된 대안**:
- 완전 잠금(404 리디렉트) → 기각. 존재 자체를 알리는 것이 리쿠르팅 유도에 필수.
- 전체 콘텐츠 공개 → 기각. 히든 플랜의 의미 소멸.

### 1-5. 히든 플랜: DB 수동 플래그

**결정**: 히든 플랜은 시스템 UI에 노출하지 않고, 제이회장님이 DB에 직접 플래그 세팅.

**근거**:
- 로키(Devil's Advocate, 2026-03-14 미팅): "히든을 시스템에서 빼고 DB에 직접 플래그 세팅 — 코드 복잡도 0, 유출 리스크 0. 가족 수가 적으므로 수동 관리 충분."
- 전원 합의(8/8, 2026-03-14 미팅에서 확정)

### 1-6. 서버사이드 플랜 검증 필수

**결정**: 모든 플랜 체크는 서버사이드(API Route)에서 강제. 프론트엔드 PlanGuard는 UX용이지 보안용이 아님.

**근거**:
- 로키: "PlanGuard 클라이언트만이면 1초에 뚫린다. DevTools로 10초 우회 가능."
- 로키(2026-03-13 미팅): "프론트엔드 전용 제한은 보안이 아님. 난독화일 뿐."
- 마아트: "서버사이드 검증 없이 출시하면 플랜 차별화 전체가 무너진다."
- 전원 합의(8/8)

### 1-7. 비용 차단기(Cost Circuit Breaker) 패턴

**결정**: 계정별/일별/월별 비용 상한선 + 자동 차단 메커니즘 도입.

**근거**:
- 로키: "기술적 해킹보다 경제적 공격이 더 현실적. 무료 계정 대량 생성으로 API 비용만 폭증시키는 시나리오."
- 카르티케야: "악의적 계정 대량 생성 시 비용 급증. rate limiting + 이메일 인증 + abuse detection 필수."
- 다수결(7/8)

### 1-8. 결제 시스템 선택: Stripe

**결정**: 결제 인프라로 Stripe를 선택.

**근거**:
- 구독 관리 기능 내장: Stripe Billing이 플랜 업/다운그레이드, 비례 배분(proration), 청구 주기 관리를 기본 제공하여 자체 구현 비용 제거
- 개발자 경험(DX) 우수: Webhook 기반 이벤트 아키텍처, 테스트 모드, CLI, 공식 Python/TypeScript SDK 완비
- 해외 확장 대비: 향후 해외 보험설계사 시장 진출 시 135+ 통화 지원으로 추가 결제 시스템 도입 불필요
- Supabase/FastAPI 스택 정합성: Edge Functions에서 Stripe SDK 직접 호출 가능, Webhook→Edge Function→DB 업데이트 파이프라인이 자연스러운 구조

**대안 비교**:
- **토스페이먼츠(포트원)**: 국내 결제 수단(카드/계좌이체/간편결제) 커버리지 최고이나, 구독 관리 기능 미비(직접 구현 필요), 해외 확장 한계
- **Paddle**: 구독 관리+세금 처리 올인원이나, 한국 원화 결제 미지원(2026-04 기준), 한국 사업자 등록 절차 복잡

**리스크 및 대응**:
- 한국 원화 결제 수수료(3.4%+₩400): 초기 사용자 수 적어 비용 감내 가능. 월 결제액 1억 초과 시 토스페이먼츠 병행 검토
- 한국 사업자 지원 범위: Stripe Atlas 불필요(국내 사업자 직접 등록). Stripe Connect는 Phase 5+ 재평가
- 간편결제(카카오페이/네이버페이) 미지원: 보험설계사 타깃은 카드/계좌이체 결제 비중 높아 초기에는 영향 미미. 프로 전환율 < 3% 시 간편결제 도입 검토

### 1-9. usage_tracking 테이블 설계

**결정**: 사용량 추적을 별도 usage_tracking 테이블로 분리, DB 원자적 카운터로 구현, 월별 리셋 적용.

**근거**:

1. **별도 테이블 vs users 컬럼 확장**:
   - users 테이블에 generation_count 컬럼 추가하면 스키마 단순하지만, 월별 리셋 시 전체 users UPDATE 필요 (수만 건)
   - 별도 테이블은 (user_id, month) 복합키로 월별 자동 파티셔닝. 히스토리 보존 + 리셋 로직 = 단순히 새 월 row insert
   - 쿼리 패턴 분리: 인증(users 자주 조회)과 사용량(생성 시점에만 조회)을 물리적으로 분리하여 lock 경합 감소

2. **DB 카운터 vs Redis 카운터**:
   - Redis: 속도 우수(1ms 미만)하나, 영속성 보장 어려움(장애 시 카운터 소실 → 무료 사용자가 무한 생성 가능)
   - DB 카운터(`UPDATE SET count = count + 1`): Supabase PostgreSQL의 MVCC로 원자성 보장. 응답시간 5~10ms로 AI 생성 요청(수 초) 대비 무시할 수 있는 오버헤드
   - 판단: 정확성 > 속도. 결제에 영향을 미치는 카운터이므로 영속성 필수

3. **월별 리셋 로직**:
   - pg_cron으로 매월 1일 00:00 UTC에 새 month 파티션 자동 생성
   - 이전 월 데이터는 삭제하지 않음 (사용 패턴 분석용 보존)
   - 리셋 = "현재 월 row 없음" → 첫 요청 시 INSERT (count=1), 이후 UPDATE (count = count + 1)

4. **동시성 제어**:
   - PostgreSQL의 `UPDATE ... SET count = count + 1` 은 row-level lock으로 동시 요청 시에도 정확한 카운트 보장
   - 동일 사용자의 동시 AI 생성 요청(탭 복수 열기 등)에서도 race condition 없음
   - 한도 초과 판정: `SELECT count FROM usage_tracking WHERE user_id = $1 AND month = $2` → 한도 비교 → 초과 시 429 반환. SELECT→UPDATE 사이 gap은 최악 케이스 1건 초과 허용(acceptable trade-off)

### 1-10. pipeline_runs 상태 머신 및 비동기 작업 큐 설계

**결정**: 콘텐츠 팩토리 파이프라인을 상태 머신 기반 pipeline_runs 테이블 + Celery/ARQ 비동기 큐 + 지수 백오프 3회 재시도로 구현.

**근거**:

1. **상태 머신 선택 사유**:
   - 파이프라인이 D→B→A→C 4단계 순차 실행이므로, 각 단계의 진행/성공/실패를 명시적으로 추적해야 부분 실패 시 재시도 지점 파악 가능
   - 상태: `PENDING → RUNNING → SUCCESS / FAILED` + 단계별 스냅샷(current_stage, stage_result_json)
   - 대안 "이벤트 소싱": 완전한 이벤트 로그를 쌓는 방식은 추적성 극대화이나, MVP 단계에서 복잡도 과잉. Phase 4 후반 Strangler Fig 전환 시 점진적 도입

2. **Celery/ARQ vs subprocess vs Supabase Edge Function 비교**:
   - **subprocess**: 현재 ai_parser.py가 subprocess 방식이나, 장시간 실행(30초+) 시 FastAPI worker 블로킹 + 재시도/모니터링 불가 + OOM 킬 시 상태 소실
   - **Supabase Edge Function**: 실행 시간 제한(150초 Deno Deploy), 메모리 제한(256MB), 장시간 파이프라인에 부적합. 경량 Webhook 수신용으로만 적합
   - **Celery/ARQ**: 독립 worker 프로세스로 FastAPI와 분리. 재시도·타임아웃·모니터링(Flower/ARQ Dashboard) 내장. Redis 브로커로 작업 큐 영속화
   - ARQ 선호 사유: Python 네이티브 async, Redis만 의존(RabbitMQ 불필요), 경량. Celery는 기능 풍부하나 설정 복잡도 높음. 최종 선택은 구현 Phase에서 PoC 후 확정

3. **재시도 전략(지수 백오프 3회) 근거**:
   - 1회 재시도: 일시적 네트워크 오류, LLM API 일시 과부하(429) 대응
   - 지수 백오프(5s → 25s → 125s): 외부 API(LLM, 티스토리, 네이버)의 rate limit 복구 시간 고려. 고정 간격은 동일 시점 재시도 집중(thundering herd) 유발
   - 3회 상한: 3회 실패 = 구조적 문제(인증 만료, API 스펙 변경 등). 무한 재시도는 비용 낭비 + 큐 적체. 3회 초과 시 FAILED 마킹 → 관리자 알림
   - 멱등성 보장: 각 단계의 output을 stage_result_json에 저장하여, 재시도 시 이전 단계 결과를 재사용(중복 실행 방지)

---

## 2. 3 Step Why 검증

### 1st Why: "왜 이 설계가 필요한가?"
인슈로가 상용화 가능한 서비스가 되려면 (1) 보안 취약점 해소, (2) 결제/플랜 시스템, (3) 차별화 기능이 필수다. 현재 CRITICAL 4건, 결제 미구현, 스텁 3개가 존재하며, 이를 체계적으로 해결하는 Phase별 계획이 없으면 무질서한 개발로 품질이 저하된다.

### 2nd Why: "왜 Phase 순서(보안→안정화→결제+A→기능+B+D→확장+C)가 최선인가?"
- 보안이 먼저인 이유: 결제 시스템을 보안 취약점 위에 구축하면 금융 사고 위험
- 안정화가 결제 전인 이유: 타입 누락, `as any`, CORS 문제가 해소되어야 결제 로직의 안정성 확보
- A가 결제와 동시인 이유: 플랜→모델 매핑이 결제 테이블의 핵심 컬럼
- B+D가 A 후인 이유: 잠금/해제 로직이 서버사이드 플랜 검증에 의존
- C가 최후인 이유: 외부 API 의존도 최대, 핵심 서비스 불안정 시 리소스 분산 위험

### 3rd Why: "왜 이 순서가 다른 대안보다 나은가?"
- 대안 1 "기능 먼저, 보안 나중" → 기각: 보안 사고 시 서비스 신뢰도 붕괴, 결제 연동 불가
- 대안 2 "모든 기능 동시 개발" → 기각: 리소스 분산, 의존성 충돌, 머지 충돌 급증
- 대안 3 "C(자동화) 먼저" → 기각: 외부 API 불안정으로 MVP 일정 리스크 극대화
- **현 순서의 장점**: 각 Phase 완료가 다음 Phase의 전제조건을 충족하는 waterfall 구조로, 위험 전파를 차단

### A-B-C 논리적 일관성 검증: PASS
- A(필요성) → B(순서 최적화) → C(대안 비교 우위)가 논리적으로 일관됨

---

## 3. Devil's Advocate 결과

### DA-1: 로키 (보안)
**공격**: "프론트엔드 잠금만으로는 1초에 뚫린다. CSS 블러는 DevTools에서 해제된다."
**대응**: 서버사이드 검증 필수 + 잠금 콘텐츠는 API 응답에서 데이터 자체를 미전송
**판정**: 수용 (설계에 반영)

### DA-2: 하누만 (테스트)
**공격**: "5개 플랜 × N개 기능 매트릭스로 테스트 케이스 3배 증가. 수동 QA 감당 불가."
**대응**: Phase 1에 자동화 테스트 인프라 구축 포함
**판정**: 수용 (T1 작업으로 추가)

### DA-3: 마아트 (품질)
**공격**: "기존 기술부채(as any, 타입 누락, subprocess) 해결 없이 신규 기능은 품질 방치."
**대응**: Phase 1에 기술부채 해소 포함 (M1, M3, M6)
**판정**: 수용 (Phase 순서에 반영)

### DA-4: 카르티케야 (백엔드)
**공격**: "LLM 비용 폭주 리스크. 무료 계정 대량 생성 시 비용 급증."
**대응**: 비용 차단기 패턴 + 이메일 인증 + abuse detection
**판정**: 수용 (설계에 반영)

---

## 4. 비관습적 대안 판정

### 비관습 1: 콘텐츠 팩토리 파이프라인 (다빈치)
**제안**: A~D를 개별 탭이 아닌 D→B→A→C 원클릭 워크플로우로 통합
**판정**: 부분 채택. Phase 4에서 파이프라인 통합 구현. Phase 2~3에서는 각 기능 독립 구현 후 연결.
**사유**: 파이프라인 전체를 한 번에 구현하면 복잡도 폭발. 독립 구현 → 연결이 안전.

### 비관습 2: 누수 전략 — 콘텐츠 워터마크 (다빈치)
**제안**: 잠금 대신 콘텐츠를 흘려보내되, 워터마크로 출처를 각인
**판정**: 부분 채택. Phase 4 이후 검토. 현재는 잠금+맛보기 전략으로 진행.
**사유**: 워터마크 구현 비용 대비 효과 불확실. 먼저 잠금으로 전환율 측정 후 비교.

### 비관습 3: 위키 기여 랭킹 (다빈치)
**제안**: 설계사별 기여도 포인트 → 플랜 크레딧 전환 → 네트워크 효과
**판정**: 채택. Phase 3 D3 작업으로 포함.
**사유**: 플라이휠 효과가 인슈로의 장기 경쟁력 원천. 구현 복잡도 중간.

### 비관습 4: 성과 대시보드 FOMO (다빈치)
**제안**: 인슈위키 활용 설계사들의 실시간 성과 숫자 노출
**판정**: 채택. Phase 3 D2 작업으로 포함.
**사유**: 텍스트 설명보다 숫자가 전환에 효과적이라는 마케팅 심리학 근거.

---

## 5. Temporal Interrogation (시간적 심문)

### 6개월 후 이 결정을 후회할 이유
1. C(AI 자동화)를 Phase 4로 미룬 사이 경쟁사가 자동화 기능을 먼저 출시할 수 있음
   → 대응: Phase 4를 병렬 팀으로 조기 착수 가능하도록 어댑터 패턴으로 설계
2. 프리셋 UI가 고착화되어 사용자가 고급 옵션을 모를 수 있음
   → 대응: 프리셋 3회 사용 후 넛지 "이번엔 고급 설정을 써볼까요?" 1회 노출
3. 100명 한정 프리미엄이 빠르게 차면 대기자 관리 부재로 잠재 고객 이탈
   → 대응: Phase 3에 대기자 명단 기본 구현 포함 (이메일 수집)

### 1년 후 이 결정을 후회할 이유
1. DB 수동 플래그 히든 플랜이 가족 수 증가 시 관리 부담
   → 대응: 가족 수 50명 초과 시 관리자 UI 구현 검토 (Phase 5)
2. FastAPI + Edge Functions 이중 구조의 운영 복잡도
   → 대응: 중장기적으로 FastAPI 단일화 또는 Edge Functions 완전 이관 검토

---

## 6. 참조 자료

- 전수조사: `memory/research/insuro-page-audit.md`
- 비전 전략: `memory/research/insuro-vision-strategy.md`
- 최종 계획서: `memory/plans/insuro-final/plan.md`
- 2026-04-18 미팅 기록: `memory/meetings/2026-04-18-insuro-final-version-plan.md`
- Threads 기능 스펙: `memory/plans/insuro/threads-feature-spec.md`
- UX 플랜 플로우: `memory/meetings/2026-03-13-insuro-ux-plan-flow.md`
- 플랜 전략: `memory/meetings/2026-03-14-insuro-plan-strategy.md`
- task-1963 설계 문서: `memory/reports/task-1963.md` (680줄 대화 요약 시스템 설계)
- task-1964 구현 보고서: `memory/reports/task-1964.md`
- task-1962 DnD 테스트 + FAIL 수정 보고서: `memory/reports/task-1962.md`
- task-1969 전수조사 수정 보고서: `memory/reports/task-1969.md`
- task-1973 subprocess→asyncio 전환 보고서: `memory/reports/task-1973.md`
- task-1974 E2E 테스트 보고서: `memory/reports/task-1974.md`
- task-1975 위키 랭킹 프론트엔드 보고서: `memory/reports/task-1975.md`
- task-1979 Lovable AI Gateway 제거 보고서: `memory/reports/task-1979.md`
- task-1980 Lovable Auth→Supabase 전환 보고서: `memory/reports/task-1980.md`
- task-1981 모바일 최적화 보고서: `memory/reports/task-1981.md`
- task-1982 비로그인 접근 차단 확인 보고서: `memory/reports/task-1982.md`
- task-1983 잔여 3건 수정 보고서: `memory/reports/task-1983.md`

---

## 7. 주의사항

### CRITICAL
1. **보안 CRITICAL 4건 미해결 상태에서 결제 연동 금지** — Phase 0 완료가 hard dependency
2. **프론트엔드 PlanGuard는 UX용이지 보안용이 아님** — 서버사이드 검증 반드시 구현
3. **AI 모델 파라미터는 클라이언트에서 절대 제어 불가** — 서버 allowlist 강제

### HIGH
4. premiumOnly 미완성 디자인은 의도적 전략 — 건드리지 말 것
5. 히든 플랜은 시스템 UI에 완전 숨김 — API 응답에서도 is_public=false 필터링
6. 인슈위키 "가족" 워딩은 플랜명이 아닌 소속 개념으로만 사용
7. 외부 플랫폼 API(티스토리/네이버)는 비공식이거나 변경 잦음 — 어댑터 패턴 필수
8. 블러 처리는 CSS filter가 아닌 정적 스크린샷 이미지 사용 — DevTools 우회 방지

### MEDIUM
9. 번들 사이즈 증가 — 라우트 기반 코드 스플리팅(React.lazy) 필수
10. FOMO 카운터 동시 접속 정합성 — Supabase Realtime 브로드캐스트와 낙관적 업데이트 충돌 처리
11. Capacitor 환경 키보드 겹침 — visualViewport API 회피 로직

---

## 8. 에이전트 미팅 참석자 및 합의 수준

| 참석자 | 역할 | 모델 | 핵심 기여 |
|--------|------|------|----------|
| 카르티케야 | 백엔드 | Opus | API/DB 설계, 비용 리스크 식별 |
| 사라스바티 | 프론트엔드 | Opus | 컴포넌트 설계, FeatureGate/LockedFeatureOverlay |
| 락슈미 | UX/UI | Opus | 프리셋 UI, 사용자 여정, 잠금 UX 패턴 |
| 하누만 | QA/테스터 | Opus | 테스트 매트릭스, E2E 시나리오, 회귀 위험 |
| 로키 | 레드팀 | Opus | STRIDE 분석, 플랜 우회 5가지, DA |
| 마아트 | QC | Opus | 코드 품질 기준, Red Flag 3건, 아키텍처 일관성 |
| 다빈치 | 비관습적사고 | Opus | 콘텐츠 팩토리, 누수 전략, FOMO 대시보드 |
| 아누 | 개발실장 | Opus | Phase 통합, 팀 배분, 일정 견적 |

---

## 9. task-1952 디벨롭 결정 근거 (2026-04-18, Cycle 1~3 전원합의)

### 9-1. CRM 기능 세부 플랜 분화: 점진적 접근

**결정**: Phase 3 현행 유지 → Phase 4 인프라 구축 → Phase 5 AI분석/Push 우선 분리

**근거**:
- 아누: "한 번에 6개 기능 분화는 과합. 인프라 먼저 구축하고 데이터 드리븐으로 분리 대상 결정"
- 로키(DA): "프론트 FeatureGate만으로는 API 직접 호출 무임승차 — 서버사이드 require_feature 필수"
- 하누만: "5플랜×6기능=30케이스 — planFeatureMap.ts SSoT + 파라미터화 테스트 필수"
- 락슈미: "잠금 UX 혼란 대응 — 미리보기 모드(읽기전용 집계 통계만)"
- 다빈치: "Feature Flag 서버 도입 → Q4 Unleash 자체 호스팅" → 부분 채택
- 전원 합의(8/8)

**기각된 대안**:
- 한 번에 6개 분화 즉시 적용 → 기각: 테스트 폭발, 서버 인프라 미준비
- Feature Flag 즉시 도입 → 보류→Q4: 현재 planFeatureMap 정적 방식으로 충분, PoC 선행

### 9-2. 모바일/PWA: PWA 유지 + Capacitor 점진 강화

**결정**: Phase M1(PWA 완성도) → Phase M2(Android Capacitor 우선) → iOS 후순위

**근거**:
- 하누만: "PWA+네이티브 이중 유지 = 테스트 2배 → 단일 경로 선택 권고"
- 로키(DA): "Apple 금융앱 인허가 서류 요구 리스크 → iOS 연기"
- 사라스바티: "iOS Safari PWA 제한(카메라, 백그라운드 푸시) → Capacitor 현실적"
- 락슈미: "앱스토어 등록이 FA 신뢰도 향상에 기여" (iOS 지연 이견 기록)
- 다빈치: "MDM 엔터프라이즈 배포" → 보류 (B2B 비중 데이터 확보 후)
- 전원 합의(8/8)

**기각된 대안**:
- 즉시 양쪽 동시 개발 → 기각: 리소스 낭비, MVP 단계에서 PWA 충분
- PWA + Web API 조합(앱스토어 우회) → 기각: FA 신뢰도 한계

### 9-3. 온보딩: Show-First + 3단계 위자드 + F1 통합

**결정**: Phase 1 위자드 UI(목업) → Phase 2 F1 AI 연동

**근거**:
- 다빈치: "Show-First 온보딩 — 결과 먼저 보여주고 역방향 입력" → 부분 채택 (A/B 테스트로 검증)
- 마아트: "F1과 동일 AI 호출 로직 공유 필수 — 중복 구현 금지"
- 로키(DA): "이메일 인증 미완료 차단, 리마인드 24시간 1회/총 3회 상한" → 전원 수용
- 락슈미: "고객명+상품명 2필드만, 선택지 최소화"
- 전원 합의(8/8)

**기각된 대안**:
- 강제 역방향 흐름 → 기각: 입력 동기 저하 우려
- 온보딩 전용 AI API 별도 구현 → 기각: F1과 카운터 이중화 위험

### 9-4. 리쿠르팅 CTA: A/B/C 3안 + 세션당 2회 상한

**결정**: CTA 3종 동시 테스트, 행동 기반 엔도우먼트 트리거, KPI 15%/30%

**근거**:
- 로키(DA): "잠금 과다 노출 → '기능 절반 막힌 앱' 인식 → 세션당 2회 상한" → 전원 수용
- 다빈치: "엔도우먼트 효과 — 30초 체험 후 저장 시 합류 제안" → 부분 채택 (행동 기반 트리거로 변경)
- 락슈미: CTA 3안 — A(직접형), B(질문형), C(성과형) 제안
- 아누: "KPI 명확 설정: 클릭→문의 15%, 문의→합류 30%"
- 전원 합의(8/8)

### 9-5. 콘텐츠 팩토리 파이프라인: MVP D→B→A + Pydantic 스키마

**결정**: MVP는 D→B→A 3단계, C는 수동 발행. Pydantic 계약 v1 고정.

**근거**:
- 아누: "MVP 범위 축소 — C(자동 업로드)는 미리보기 후 수동 발행"
- 마아트: "단계간 인터페이스를 Pydantic 스키마로 명시, v1 고정, 하위호환 마이그레이션"
- 로키(DA): "부분 롤백 — A 결과 보존, C 실패만 재발행" → 전원 수용
- 다빈치: "이벤트 드리븐 아키텍처" → 부분 채택 (MVP는 Celery/ARQ, Phase 4 후반 Strangler Fig 전환)
- 전원 합의(8/8)

---

## 10. task-1952 3 Step Why 검증

### 1st Why: "왜 이 5건의 디벨롭이 필요한가?"
기존 3문서(task-1951)는 전체 아키텍처와 Phase 순서를 확립했으나, CRM 세부 분화·모바일 전략·온보딩·리쿠르팅 CTA·파이프라인의 구체적 설계가 "있음/없음" 또는 "Phase N에서 처리" 수준으로만 기술되어 있어, 실제 구현 시 모호성이 높고 의사결정 지연이 발생할 위험이 있다.

### 2nd Why: "왜 이 접근(점진적 분화, PWA 우선, Show-First, 행동 기반 CTA, MVP 축소)이 최선인가?"
- 점진적 분화: 인프라 없이 기능 분화하면 서버사이드 검증 누락 → 보안 사고
- PWA 우선: Apple 인허가 리스크와 이중 구조 유지 비용 회피
- Show-First: 보험설계사의 낮은 IT 리터러시에 대응, 빈 화면 공포 해소
- 행동 기반 CTA: 과다 노출 이탈 방지 + 자연스러운 전환 유도
- MVP 축소: 외부 API 의존 자동화를 안정성 검증 후 도입

### 3rd Why: "왜 이것이 다른 대안보다 나은가?"
- 즉시 전체 분화 vs 점진적: 30케이스 테스트 폭발 방지, 데이터 드리븐 판단 가능
- 즉시 양플랫폼 vs PWA 우선: MVP 단계 리소스 집중, 검증 후 확장
- Explain-First vs Show-First: 행동경제학 근거(엔도우먼트 효과), A/B 테스트로 실증
- 시간 기반 CTA vs 행동 기반: 사용자 맥락 반영, 이탈 리스크 감소
- 전체 자동화 vs MVP 축소: 신뢰도 미검증 자동화의 품질 사고 방지

### A-B-C 논리적 일관성: PASS

---

## 11. task-1952 DA 결과

### DA-5: CRM 프론트 잠금만으로 충분한가 (로키)
**공격**: "FeatureGate만으로는 API 직접 호출 무임승차"
**대응**: require_feature 서버사이드 데코레이터 병행 필수
**판정**: 수용

### DA-6: 앱스토어 심사 인허가 리스크 (로키)
**공격**: "Apple 금융앱 인허가 서류 요구 — 리젝션 시 일정 지연"
**대응**: iOS 연기, Android 우선, 인허가 착수는 즉시 (병행)
**판정**: 수용

### DA-7: CTA 과다 노출 이탈 (로키)
**공격**: "잠금 노출 과다 → 기능 절반 막힌 앱 인식 → 사용자 이탈"
**대응**: 세션당 2회 상한, 동일 기능 중복 금지, 24시간 쿨다운
**판정**: 수용

### DA-8: 무료 계정 온보딩 남용 (로키)
**공격**: "이메일 인증 미완료 계정으로 AI 리소스 남용"
**대응**: 이메일 인증 미완료 시 핵심 기능 차단
**판정**: 수용

---

## 12. task-1952 비관습적 대안 판정

### 비관습 5: Show-First 온보딩 (다빈치)
**제안**: 결과 먼저 보여주고 역방향 입력 유도
**판정**: 부분 채택 (A/B 테스트로 검증, 강제 역방향은 기각)

### 비관습 6: Feature Flag 서버 Unleash (다빈치)
**제안**: 외부 Feature Flag 서버로 런타임 on/off 제어
**판정**: 부분 채택 (Q4 Unleash 자체 호스팅 도입, Q3까지 현행 유지)

### 비관습 7: 이벤트 드리븐 파이프라인 (다빈치)
**제안**: Supabase DB 트리거 → Edge Function 리액티브 흐름
**판정**: 부분 채택 (MVP는 Celery/ARQ, Phase 4 후반 Strangler Fig 전환)

### 비관습 8: 엔도우먼트 CTA (다빈치)
**제안**: 30초 체험 후 저장 시 합류 제안
**판정**: 부분 채택 (행동 기반 트리거로 변경, 시간 트리거 기각)

### 비관습 9: MDM 엔터프라이즈 배포 (다빈치)
**제안**: 앱스토어 대신 MDM 직접 배포
**판정**: 보류 (B2B 비중 데이터 확보 후 재검토)

### 비관습 10: 바이럴 루프 메커니즘 (다빈치)
**제안**: 초대 코드 공유로 잠금 해제
**판정**: 보류 (현재 사용자 기반 부족, Phase 5 이후)

---

## 13. task-1953 디벨롭 결정 근거 (2026-04-19)

### 13-1. 경쟁사 대응 전략 수립

**결정**: 경쟁사별 강점/약점 분석 + 인슈로 경쟁 우위 5가지 + 방어/공격 전략 수립

**근거**:
- 시장 리서치 결과: 보험다모아·카카오페이·보맵은 모두 소비자 대상(D2C). 설계사 전용 AI 마케팅 플랫폼은 시장 공백.
- 토스보험파트너 2025.12 종료로 설계사 3,000명+ 이탈 — 인슈로가 유일한 대안 포지션.
- 보험사 내부 AI는 폐쇄형으로 소속사 변경 시 자산 소멸 — 인슈로의 "소속사 독립성" 차별화.
- 경쟁 우위: (1) 유일한 설계사 전용 플랫폼 (2) 인포키워드+인슈위키 (3) 소속사 독립성 (4) 커뮤니티 (5) 히든 플랜 리쿠르팅

### 13-2. PostHog 분석 도구 선정

**결정**: A/B 테스트 + 이벤트 분석 인프라로 PostHog 선정 (Mixpanel, 자체 구현 대비)

**근거**:
- 비용: PostHog 무료 100만 이벤트/월 vs Mixpanel 무료 20만/월 — 초기 비용 0원
- 올인원: 이벤트 분석 + Feature Flags + A/B 실험 + 세션 리플레이 단일 SDK (Mixpanel은 Feature Flags/세션 리플레이 별도 도구 필요)
- 엔지니어 친화: Supabase/FastAPI 스택과 문화적 정합성, SQL 직접 쿼리, 오픈소스
- Python SDK: FastAPI 서버사이드 이벤트 직접 전송 가능

**기각된 대안**:
- Mixpanel: PM 친화적 UI이나, Feature Flags/세션 리플레이 별도 도구 필요 → 벤더 분산 + 비용
- 자체 구현(Supabase): 단순 집계 가능하나, 코호트 분석·퍼널·A/B 통계 직접 구현 시 수백 시간 소요

### 13-3. 마케팅/GTM 3단계 전략

**결정**: 비공개 베타 → 얼리 액세스 → 공개 론칭의 3단계 GTM 프레임워크

**근거**:
- 보험설계사 타깃 특성: IT 리터러시 낮음 → 가족/지인 네트워크 기반 신뢰 구축 우선
- 채널 전략: SNS(서울대보험쌤 팔로워), 단톡방(실사용 후기 공유), 네이버 카페(정보성 콘텐츠), 가족 추천(디지털 명함 연계)
- 100명 한정 프리미엄: FOMO + 얼리버드 할인 + 대기자 명단 시스템
- KPI: CPA < 30,000원, LTV/CAC > 3, 프로 전환율 15%

---

## 14. task-1953 3 Step Why 검증

### 1st Why: "왜 경쟁사 대응 + 데이터/분석 + 마케팅/GTM 전략이 필요한가?"
기존 3문서(task-1951/1952)는 기술 아키텍처와 제품 기능을 상세히 정의했으나, (1) 경쟁 환경에서 인슈로가 왜 이겨야 하는가의 논리, (2) 사용자 행동을 측정하고 개선하는 데이터 인프라, (3) 실제 사용자를 어떻게 획득하고 전환하는가의 GTM 전략이 빠져 있었다. 최고의 제품도 마케팅·분석·경쟁 전략 없이는 시장에서 실패한다.

### 2nd Why: "왜 이 접근(경쟁 우위 5가지, PostHog, 3단계 GTM)이 최선인가?"
- 경쟁 우위 5가지는 단순 기능 비교가 아닌 구조적 해자(moat) — 네트워크 효과, 데이터 자산 축적, 히든 플랜의 고유 리쿠르팅 루프
- PostHog: 초기 비용 0원 + 올인원(4개 도구 통합) + 엔지니어 문화 정합성 → 스타트업 최적 선택
- 3단계 GTM: 보험설계사의 신뢰 기반 의사결정 특성(동료 추천에 민감, 광고 불신) → 커뮤니티 침투 전략이 전통 광고보다 CAC 효율 극대화

### 3rd Why: "왜 이것이 다른 대안보다 나은가?"
- 대안 1 "기능 우위만으로 승부": 기각 — 후발주자가 기능 복제 시 방어 불가. 네트워크 효과 + 데이터 락인이 진정한 해자.
- 대안 2 "Mixpanel + LaunchDarkly + FullStory 조합": 기각 — 3개 벤더 × 각각 월 비용 = 초기 단계에서 비용 낭비 + 통합 복잡도.
- 대안 3 "대규모 광고 캠페인(페이드 미디어)": 기각 — 보험설계사는 동료 추천에 의존하는 신뢰 기반 타깃. CPA 높고 리텐션 낮은 유입.
- **현 전략의 장점**: 경쟁 우위(구조적 해자) + 데이터(PostHog 올인원) + GTM(커뮤니티 침투)가 각각 독립적이면서 상호 강화하는 플라이휠 구조.

### A-B-C 논리적 일관성: PASS

---

## 15. task-1964 CRM 대화 자동 요약 시스템 결정 근거 (2026-04-19~20)

### 15-1. 벡터 검색 제외, 키워드 검색만 MVP

**결정**: 대화 요약 검색을 벡터 유사도 검색 없이 키워드 텍스트 검색만으로 MVP 구현.

**근거**:
- 설계 문서(task-1963, 680줄)에서 벡터 검색은 Phase 2로 분류
- 벡터 DB(pgvector) 설치/운영 복잡도 → MVP 단계에서 과잉
- 키워드 검색만으로 설계사의 과거 상담 내용 검색 니즈 충족 가능
- 추후 사용 패턴 데이터 축적 후 벡터 검색 도입 여부 판단

### 15-2. 요약 트리거: 종료 버튼 + 타임아웃 백업

**결정**: 설계사가 "상담 종료" 버튼 클릭 시 요약 생성. 타임아웃 백업 트리거는 설계에 포함하되 MVP는 버튼만 구현.

**근거**:
- 설계사가 상담 종료 시점을 명시적으로 결정하는 것이 요약 품질에 유리
- 타임아웃 트리거: 30분 무활동 시 자동 요약 (설계 문서에 정의)
- MVP에서 타임아웃은 백엔드 cron/스케줄러 필요 → 구현 복잡도 증가 → 후순위

### 15-3. 발견된 이슈와 해결

| 이슈 | 원인 | 해결 방법 |
|------|------|-----------|
| DB 컬럼명 불일치 (structured_data vs structured) | API와 migration 간 네이밍 불일치 | 전수 검색하여 `structured`로 통일 |
| sender_type vs role | conversation_messages 실제 컬럼명 다름 | `sender_type`으로 수정 |
| summary_period_start/end 누락 | NOT NULL 필드 API insert 미포함 | 필드 추가 완료 |
| customer_activities 컬럼명 불일치 | reference_id/metadata vs related_id/detail/title | 실제 스키마 기준으로 수정 |

### 15-4. 현재 상태 및 미해결 사항

- **구현 완료**: conversation_summaries 테이블, 요약 API 3종, 상담 종료 버튼, SummaryTab
- **main 미반영**: 별도 브랜치(task/task-1964-dev1)에 구현됨. main 통합 필요
- **미구현**: 타임아웃 백업 트리거, 벡터 검색, 요약 품질 평가 메트릭

---

## 16. task-1969~1983 주요 결정사항 (2026-04-20)

### 16-1. Lovable→Supabase/Gemini 전환 (task-1979, task-1980)

**결정**: Lovable 프로젝트 의존성을 완전 제거하고, AI Gateway를 자체 API key 기반 Google Gemini로 전환. Auth는 Supabase Native OAuth 유지 확인.

**근거**:
- InsuRo가 Lovable에서 독립 완료되었으나 AI 기능이 `ai.gateway.lovable.dev`에 여전히 의존 → 서비스 안정성 리스크
- Lovable Auth(`@lovable.dev/cloud-auth-js`)도 이미 Supabase Native OAuth로 전환 완료된 상태
- 기본 AI provider를 Google Gemini로 설정하여 자체 API key 기반 운영 가능

### 16-2. subprocess→asyncio 완전 전환 (task-1973)

**결정**: anu_provider.py의 `subprocess.run` + `anyio.to_thread.run_sync` 중간 상태를 `asyncio.create_subprocess_exec`로 완전 전환.

**근거**:
- subprocess.run은 동기 블로킹 호출로 스레드풀 오버헤드 발생
- 타임아웃 시 프로세스 미종료 → 리소스 누수 위험 (Gemini PR 리뷰에서 HIGH 지적)
- asyncio native로 전환하여 `process.kill() + await process.wait()` 패턴으로 좀비 프로세스 방지

### 16-3. keyword_jobs 인메모리→Supabase 이관 (task-1983)

**결정**: 인메모리 dict `_keyword_jobs`를 Supabase `keyword_jobs` 테이블로 이관.

**근거**:
- 서버 재시작 시 진행 중인 분석 job 정보 유실 (Gemini PR 리뷰 HIGH)
- RLS 정책 포함한 migration으로 보안 강화
- Supabase CRUD로 전환하여 상태 영속화

### 16-4. 위키 랭킹 Python→RPC 전환 (task-1983)

**결정**: Python-side score_map 합산을 Supabase RPC SQL 함수로 전환.

**근거**:
- 전체 테이블 fetch + Python 합산은 O(N) 성능 저하 (Gemini MEDIUM)
- SQL GROUP BY + SUM + ORDER BY로 DB 레벨에서 처리하여 네트워크/메모리 효율 개선

### 16-5. 에이전트 미팅 품질 게이트 합의

**참조**: task-1967+1 전수조사에서 체크리스트 [x] 항목의 적발률 34%(16/47)가 발견됨. 이에 따라 "보고서만 믿지 않고 코드 grep으로 실존 확인 후 체크"하는 품질 게이트 합의가 도출됨. task-1985에서 이 원칙을 적용하여 3문서 업데이트를 수행.

---

## 17. task-2000 전수 재점검 결과 (2026-04-20)

### 17-1. main 코드 grep 기반 신규 체크 항목

**결정**: task-1992 머지 완료 후 main에 반영된 모든 기능에 대해 grep 전수 재점검 실시.

**검증 결과 요약**:

| 항목 | main 존재 | 조치 |
|------|-----------|------|
| CS-1~3 (대화 요약) | ✅ 전부 존재 | [x] 유지 확인 |
| OB-1 (OnboardingWizard) | ✅ pages/OnboardingWizard.tsx + routes.ts | [ ] → [x] 변경 |
| OB-2 (Empty State 제거) | ✅ useOnboardingRedirect.ts + DashboardLayout 리다이렉트 | [ ] → [x] 변경 |
| OB-3 (onboarding_step ENUM) | ✅ migration 존재 | [ ] → [x] 변경 |
| SEC-1 (require_plan) | ✅ 17개 엔드포인트 적용 | [ ] → [x] 변경 |
| SEC-2 (rate_limit) | ✅ slowapi 6개 적용 (스텁 4개 제외) | [ ] → [x] 변경 |
| SEC-3 (감사 로그) | ✅ token_usage_log 4개 지점 | [ ] → [x] 변경 |
| SEC-4 (비용 차단기) | ✅ check_cost_circuit_breaker 4개 지점 | [ ] → [x] 변경 |
| UX-1 (모바일 반응형) | ✅ Tailwind 42개 + MobileBottomNav | [ ] → [x] 변경 |
| UX-3 (서버 미전송) | ✅ 403 반환 + 필드 제거 | [ ] → [x] 변경 |
| Lovable 제거 | ✅ main에서 0건 | 확인 완료 |
| Auth (Supabase OAuth) | ✅ signInWithOAuth | 확인 완료 |
| 모바일 최적화 | ✅ viewport-fit=cover + 터치 타겟 | 확인 완료 |

**미완료 확인 항목**:
- TST-3 (`as any` 34개 존재) — M6 이후 신규 추가 여부 확인 필요
- TST-4 (CI 파이프라인) — .github/workflows/ 미존재
- UX-2 (세션당 2회 상한) — RC-2 미구현

---

## 18. task-1996~2002 주요 결정사항 (2026-04-20)

### 18-1. 테스트/UX 게이트 전수 통과 (task-1996)

**결과**:
- TST-1(30개 라우트 스모크 30/30), TST-2(tsc 에러 0건), TST-3(신규 as any 0건) 전부 PASS
- UX-1(모바일 반응형), UX-2(세션당 2회 제한), UX-3(DevTools 우회 불가) 전부 PASS
- UX-2 구현: LockedFeatureOverlay.tsx에 sessionStorage 기반 세션당 최대 2회 업그레이드 다이얼로그 → 3회차부터 토스트 대체
- pytest 191건 전체 통과

### 18-2. API/DB/컴포넌트 문서화 완료 (task-1997)

**결과**: DOC-1~3 전부 완료
- api-reference.md: 1010줄, 25개 엔드포인트 전수 문서화
- db-schema.md: 1055줄, 34+ 테이블, 45개 마이그레이션 반영
- components.md: 215줄, 8개 컴포넌트 Props 문서화

**발견 사항**:
- wiki_contributions 테이블은 마이그레이션 파일에 CREATE TABLE이 없고 main.py 주석에만 DDL 존재 — 문서에 "마이그레이션 외 정의" 주석 표기

### 18-3. Lighthouse 성능 최적화 (task-1998)

**결과**: G4-7 달성 기반 구축
- Kakao SDK defer 속성 추가로 파서 차단 제거
- recharts(399KB), framer-motion(120KB), supabase(171KB) 별도 청크 분리 — 초기 번들 ~691KB 감소
- 이미지에 loading="lazy" + width/height + decoding="async" 적용
- robots.txt에 Sitemap URL 추가

### 18-4. 보안 침투 테스트 전체 PASS (task-1999)

**결과**: G4-1 침투 5시나리오 전부 PASS
- 시나리오1~5: 무료→프로 API 직접 호출(403), 모델 변조(403), 사용량 초과(429), 히든 전용 파이프라인(403), OAuth 토큰 암호화 왕복
- SEC-1: require_plan 21건 적용 확인 (전 AI 엔드포인트 커버)
- SEC-4: 비용 차단기 전용 테스트 3건 추가 — 임계치 초과(503)/미만(200)/DB장애(200) 검증

### 18-5. 온보딩 DEFAULT NULL 변경 (task-2001, task-2002)

**결정**: onboarding_step DEFAULT를 'SIGNED_UP'에서 NULL로 변경하고, BEFORE INSERT trigger로 신규 가입 시 SIGNED_UP 자동 설정

**근거**:
- task-2001 원인: DEFAULT 'SIGNED_UP'이 기존 사용자에게도 적용 → 전원 온보딩 리다이렉트 버그
- 해결 1단계(task-2001): 기존 사용자를 CONVERTED로 일괄 업데이트 + isNewUser(1시간) 안전장치
- 해결 2단계(task-2002): DEFAULT NULL로 변경 + BEFORE INSERT trigger 추가
- 정합성 매트릭스: NULL=레거시/비정상→스킵, SIGNED_UP=가입완료→온보딩, FIRST_CONTENT_DONE/CONVERTED=완료→스킵

**참조 보고서**:
- task-1996 보고서: `memory/reports/task-1996.md`
- task-1997 보고서: `memory/reports/task-1997.md`
- task-1998 보고서: `memory/reports/task-1998.md`
- task-1999 보고서: `memory/reports/task-1999.md`
- task-2001 보고서: `memory/reports/task-2001.md`
- task-2002 보고서: `memory/reports/task-2002.md`

---

## 19. task-2009~2011 반영 + 최종 완료율 집계 (2026-04-20)

### 19-1. RC-3~4 main 반영 확인 (task-2009)

**검증 결과**:
- RC-3: behaviorTracker.ts(3조건 추적), useBehaviorCta.ts(훅), LockedFeatureOverlay 통합 — main grep 확인
- RC-4: recruiting_inquiry 테이블(migration), POST /api/insuro/recruiting/inquiry, GET /funnel, recruitingFunnel.ts — main grep 확인

### 19-2. CP-1~2 main 반영 확인 (task-2010)

**검증 결과**:
- CP-1: ComparisonSection.tsx — Intro.tsx에서 import 및 렌더링 확인 (이전 task-2008에서 이미 [x])
- CP-2: DifferentiationSection.tsx — Intro.tsx에서 import 및 렌더링 확인 (이전 task-2008에서 이미 [x])

### 19-3. E2E 검증 결과 (task-2011)

**검증 결과**: 7/7 플로우 PASS
- 로그인 페이지 렌더링, 인증 가드(13개 라우트), 온보딩 리다이렉트, 대시보드 메뉴(6개), CRM 기능(3개), 잠금 기능(LockedFeatureOverlay+PlanGuard), 모바일 반응형(MobileBottomNav)
- 콘솔 에러: 0건
- 스크린샷 22개 캡처: memory/screenshots/insuro-e2e/

### 19-4. task-2012 (RC-5~6) 상태

**상태**: 보고서 미존재 → 미완료로 판정. checklist에서 [ ] 유지.

### 19-5. 최종 완료율

전수 grep 재점검 결과, Phase 0~4 핵심 기능은 거의 완성. 미완료 항목은 대부분 장기/보류 카테고리 (Stripe 결제, Capacitor 앱, PostHog 분석 인프라, CRM 세부 분화, 콘텐츠 파이프라인 고도화).

---

## 20. task-2017/2018/2020 main grep 전수 재점검 (2026-04-20)

### 20-1. PostHog 분석 기반 셋업 DA-1~5 (task-2017)

**검증 결과**:
- DA-1: .env.example에 VITE_POSTHOG_API_KEY/HOST 존재 (merge conflict marker 잔존 — App.tsx/analytics.py와 함께 해소 필요)
- DA-2: posthog-js ^1.369.3 package.json 등록 ✅, PostHogProvider App.tsx 구현 존재 (merge conflict 영향)
- DA-3: useAnalytics.ts 18개 이벤트 타입 + PII strip ✅ (정상)
- DA-4: server/analytics.py track_server_event + _strip_pii + _filter_pii ✅ (merge conflict marker 잔존)
- DA-5: docs/pii-analytics-guidelines.md ✅ (정상)

### 20-2. PostHog 이벤트 계측 DA-6~11 (task-2020)

**검증 결과**:
- DA-6: PageViewTracker.tsx 컴포넌트 ✅, App.tsx 통합은 merge conflict 해소 후 동작
- DA-7: OnboardingWizard 3단계 onboarding_step_completed ✅ (정상)
- DA-8: server/main.py L661 content_generated 서버사이드 이벤트 ✅ (정상)
- DA-9: 4종 이벤트(locked_feature_viewed, plan_upgrade_clicked, upgrade_modal_dismissed, inquiry_submitted) ✅ (정상)
- DA-10: analytics.py pipeline_run_completed/crm_contact_added 지원 (merge conflict 내 존재, 호출 지점은 해당 기능 구현 시 추가)
- DA-11: 18개 타입 정의 + cta_clicked 호출 ✅. feature_used 등 7개는 타입만 정의 (해당 기능 구현 시 track 추가)

### 20-3. CRM 기능 분화 인프라 CF-1~2 (task-2018)

**검증 결과**:
- CF-1: require_feature(feature_key) 함수 (server/main.py L382) + PLAN_FEATURE_MAP 12개 항목 (L214~227) ✅
- CF-2: planFeatureMap.ts crm_* 6개 항목 + use-feature-access.ts useFeatureAccess 훅 + FeatureGate.tsx re-export ✅

### 20-4. merge conflict 미해소 파일 목록

main 브랜치에 merge conflict marker가 잔존하는 파일 4건:
1. `.env.example` — task-2017과 task-2020 충돌
2. `src/App.tsx` — PostHogProvider 래핑 방식 충돌
3. `server/analytics.py` — 함수 중복 정의 충돌
4. `server/tests/test_analytics.py` — 테스트 충돌

⚠️ 이 4건은 DA 체크리스트 자체의 구현 완료 판정에는 영향 없으나 (코드 자체는 존재), 빌드 가능 상태를 위해 별도 task로 conflict 해소 필요.

---

## 21. task-2022~2024 결과 반영 + v9 grep 재점검 (2026-04-20)

### 21-1. task-2022 (CF-3~4) grep 검증 결과

**검증 결과**:
- CF-3: server/tests/test_plan_feature_parameterize.py ✅ (pytest 39건 PASSED) + tests/plan-feature-matrix.test.ts ✅ (vitest 36건 PASSED). planFeatureMap.ts SSoT 기반 파라미터화 테스트 전수 존재.
- CF-4: src/hooks/use-preview-mode.ts ✅ + src/components/crm/PreviewGuard.tsx ✅. Free→preview 모드 전환, PII 마스킹 적용.

### 21-2. task-2023 (OB-4~7) grep 검증 결과

**검증 결과**:
- OB-4: POST /api/insuro/onboarding/ab-assign ✅ + GET /api/insuro/onboarding/ab-metrics ✅. profiles.ab_test_group 필드 저장, 50% 무작위 배정.
- OB-5: POST /api/insuro/onboarding/ai-generate ✅. onboarding_ai_generate feature_key로 F1 카운터 차감.
- OB-6: POST /api/insuro/onboarding/check-remind ✅ + onboarding_reminds 테이블 INSERT ✅.
- OB-7: useAnalytics.ts에 onboarding_funnel_enter / onboarding_funnel_drop 타입 추가 ✅ + useOnboardingRedirect.ts에서 실제 track('onboarding_funnel_enter') 호출 ✅.

### 21-3. task-2024 (DA-12~16) grep 검증 결과

**검증 결과**:
- DA-12: src/pages/AdminAnalytics.tsx ✅ (417줄). KpiCard 컴포넌트 기반 11개 KPI 위젯 렌더링. routes.ts에서 lazy import.
- DA-13: docs/posthog-kpi-dashboard-guide.md ✅ (551줄). D1/D7/D30 코호트 리텐션 분석 가이드 포함.
- DA-14: AdminAnalytics.tsx 내 온보딩 퍼널 섹션 ✅. onboarding_step1/2/3 필드 기반 Step 1→2, Step 2→3 이탈률 계산.
- DA-15: supabase/functions/posthog-webhook/index.ts ✅ Edge Function 구현 완료.
- DA-16: supabase/migrations/20260420500000_analytics_kpi_tables.sql ✅. analytics_events + analytics_daily_summary 테이블 + pg_cron 매일 01:00 KST 집계 스케줄.

### 21-4. 완료율 갱신

- 이전 (task-2025): 115 [x] / 61 [ ] = 65.3%
- 신규 체크 +11건: CF-3,4 + OB-4,5,6,7 + DA-12,13,14,15,16
- 갱신 (task-2027): 126 [x] / 50 [ ] = 71.6%

---

## 22. 베타 UX 개선 31건 결정 근거 (task-2102, 2026-04-22)

### 22-1. 마이페이지 섹션 재구성 — 대안 C 확정 (brainstorming 결과)

**결정**: 마이페이지 레이아웃을 Hero(간소화)→사용량→명함→최근활동 순서로 재구성. Hero Card 미니스탯 4개 삭제, 플랜 비교 테이블은 /plan 페이지로 이동. 84줄 삭제 + 9줄 추가.

**근거**:
- brainstorming에서 대안 A(현행 유지), B(탭 분리), C(분리 유지+중복 제거) 3안 검토
- 대안 C 확정: 사용량 섹션과 Hero 미니스탯이 동일 정보를 중복 표시하고 있어 사용량 섹션만 남기고 Hero는 간소화
- 플랜 비교는 /plan 페이지가 이미 상세하게 제공하므로 마이페이지에서 제거하여 정보 과부하 해소

**기각된 대안**:
- 대안 A(현행 유지) → 기각: 중복 정보로 인한 사용자 혼란 미해결
- 대안 B(탭 분리) → 기각: 마이페이지 단일 스크롤이 보험설계사 사용 패턴에 적합

### 22-2. 플랜&구독 Phase 분리 — 결제 UI는 "준비 중" 모달

**결정**: 결제 CTA 클릭 시 실제 카드 입력 폼 대신 "결제 시스템 준비 중" 모달 표시. 결제사(토스/포트원) 계약 완료 후 실제 연동.

**근거**:
- Agent 미팅 합의: 카드 정보 입력 폼을 사전에 생성하면 보안 리스크 + 사용자 신뢰 훼손
- 로키(DA 반론): "결제사 미계약 상태에서 카드 입력 폼을 노출하면 법적 이슈 + 허위 결제 UI 인식 리스크"
- 현재 Phase에서는 기능 안정화에 집중, 결제는 비즈니스 결정 완료 후 별도 Phase로 진행

### 22-3. 잔여석 카운터 서버사이드 검증

**결정**: useRemainingSeats() 훅의 잔여석 데이터를 Supabase 서버사이드에서 검증. 하드코딩 폴백(73석)을 0으로 수정하고, API 실패 시 카운터 자체를 숨김 처리.

**근거**:
- task-2098에서 확인: 기존 하드코딩 73석은 실제 데이터와 괴리 발생 가능
- API 실패 시 잘못된 숫자 노출보다 카운터 숨김이 신뢰도에 유리
- FOMO 전략 일관성: 허위 숫자는 마케팅 신뢰도를 훼손

### 22-4. AI 토큰/모델 파이프라인 정상 확인

**결정**: AI 토큰 항목과 모델 등급 동적 연동이 기존 코드에서 이미 정상 작동함을 확인. 수정 불필요.

**근거**:
- task-2098 코드 검증 결과:
  - 토큰: DB seed → AdminSubscriptions → plan_features → Pricing 테이블 전체 파이프라인 연결 확인
  - 모델: DB seed → AdminSubscriptions → plan_ai_models → Pricing 전체 파이프라인 연결 확인
  - 무료=haiku(기본AI), 베이직/프로=sonnet(고급AI), 맥스/히든=opus(최고급AI)
- 의미: 플랜별 AI 모델 차별화가 이미 서버사이드까지 완전히 동적 연동되어 있어 plan.md 3.A절의 설계가 코드에 정확히 반영됨

### 22-5. 주요 진행중 이슈 (3건)

| 이슈 | 태스크 | 원인 (추정) | 상태 |
|------|--------|------------|------|
| 네이버 검색량 조회 오류 | task-2101 | API 연결/응답 파싱 문제 | 수정 중 |
| AI 주제 추천 실패 | task-2100 | 추천 API 미연결 또는 프롬프트 구성 문제 | 코드 분석 중 |
| 콘텐츠 생성 실패 (failed to fetch) | task-2099 | Edge Function 또는 AI API 연결 실패 | 수정 중 |

### 22-6. 미착수 작업 분류 기준

**분류 원칙**:
- **Phase 3 즉시 착수 가능**: BUX-23(면책 디자인), BUX-24(AI 모델 레이아웃), BUX-30(시작가이드 dismiss), BUX-31(시작가이드 스텝 교체) — 단독 수정 가능, 의존성 없음
- **Phase 3 설계 필요**: BUX-20(서브세션 재구성), BUX-22(인포키워드 연동), BUX-27(UX 혼란 해소) — 기존 설계 의도 확인 후 재검토 필요
- **Phase 3 인프라 의존**: BUX-15(결제 UI), BUX-28(인슈위키+메디스캔 메뉴), BUX-29(메디스캔 페이지) — 관리자모드 동적 연동 + 플랜 관리 필요