---
task_id: task-1957
type: plan
scope: task
created: 2026-04-19
updated: 2026-04-19
status: completed
---

# 계획서: task-1957 — 인슈로 Phase 2A: 플랜 시스템 + 콘텐츠 세분화

**task**: task-1957
**목표**: 서버사이드 플랜 검증 미들웨어, AI 모델 allowlist, 사용량 제한, 채널 제한, 프리셋 UI, LockedFeatureOverlay, FeatureGate 컴포넌트, PlanUpgradeDialog 정렬, Free 사용자 AI 맛보기 구현
**승인**: 인슈로 시스템 계획서 (task-1951) 기반
**근거**: memory/plans/insuro-system/plan.md, memory/research/insuro-page-audit.md

---

## 목표

1. 서버사이드(FastAPI)에 플랜 검증 미들웨어(@require_plan) 구현 → 무료 사용자의 Pro 이상 기능 접근 차단
2. AI 모델 서버 allowlist: 플랜별 허용 모델 매핑, 클라이언트 파라미터 조작 방어
3. 사용량 제한(usage_tracking): 월별 사용량 카운터 + 초과 시 429 반환
4. 채널 제한: 무료=1채널(네이버 블로그), 프로=5채널
5. 프리셋 UI: 3종(블로그용/SNS용/제안서용) + 고급 옵션 토글
6. LockedFeatureOverlay 공용 컴포넌트: 반투명 오버레이 + 업그레이드 CTA
7. FeatureGate 선언적 컴포넌트: planFeatureMap.ts 기반
8. PlanUpgradeDialog 플랜명 DB 자동 반영 정렬
9. Free 사용자 AI 맛보기 월 5회

## 범위

### 포함
- P1: subscription_plans 시드 데이터 5단계 정렬 (SQL migration)
- P2: @require_plan 미들웨어 (server/main.py)
- P3: AI 모델 서버 allowlist (server/main.py)
- P4: usage_tracking 서버사이드 집행 (server/main.py)
- P5: 채널 제한 구현 (server/main.py)
- A1: 프리셋 UI (src/pages/Generate.tsx, src/components/GenerateSettingsPanel.tsx)
- A2: LockedFeatureOverlay 공용 컴포넌트 (신규)
- A3: FeatureGate 선언적 컴포넌트 + planFeatureMap.ts (신규)
- A4: PlanUpgradeDialog 플랜명 정렬 (기존 DB 기반 → 자동 반영)
- F1: Free 사용자 AI 맛보기 월 5회

### 제외 (다음 페이즈 이후)
- H1: Stripe 결제 연동 (Phase 2B, Lv.4)
- AU-1: 감사 로그 (별도 task)
- premiumOnly 미완성 디자인

## 위임 계획

- P1(시드 데이터): **스바로그(백엔드)** — SQL migration
- P2(미들웨어): **스바로그(백엔드)** — Lv.3 핵심 로직
- P3(모델 allowlist): **스바로그(백엔드)** — P2 이후 순차
- P4(사용량 제한): **스바로그(백엔드)** — P2 이후 순차
- P5(채널 제한): **스바로그(백엔드)** — P2 이후 순차
- A1(프리셋 UI): **라다(프론트엔드)** — P2 완료 후
- A2(LockedFeatureOverlay): **라다(프론트엔드)** — 독립 작업
- A3(FeatureGate): **라다(프론트엔드)** — A2 이후
- A4(PlanUpgradeDialog): **라다(프론트엔드)** — P1 이후
- F1(맛보기): **스바로그+라다** — P4 이후

## 검증 기준

- P2: `curl -H "Auth: Bearer <free_user_token>" /api/insuro/ai/generate` → 403 (Pro 이상 필요)
- P4: 월 한도 초과 시 429 반환
- A2: LockedFeatureOverlay 렌더링 스크린샷
- A1: 프리셋 3종 선택 UI 확인
- tsc 0 errors