# task-621: 인슈로 플랜 관리 고도화

## 프로젝트 경로
`/home/jay/projects/InsuRo/`

## 기술 스택
- React 18 + TypeScript + Vite
- shadcn-ui (Radix UI) + Tailwind CSS
- Supabase (PostgreSQL + Edge Functions)
- TanStack Query

## 전체 목표
인슈로 관리자 페이지 플랜 관리를 5개 플랜(무료/베이직/프로/맥스/히든) 체계로 개편하고, 기능 매트릭스 UI + 토큰제 + 플랜별 AI 모델 선택 + 아누 시스템 연동을 구현한다.

---

## Phase 1: 플랜 구조 변경 + 기능 매트릭스 UI

### 1-1. DB 마이그레이션
- `subscription_plans` 테이블 데이터 변경:
  - Enterprise → **맥스(Max)** 이름 변경
  - **히든(Hidden)** 플랜 신규 추가 (is_public=false, is_active=true)
  - 5개 플랜 정렬: 무료(1) → 베이직(2) → 프로(3) → 맥스(4) → 히든(5)
- 마이그레이션 파일: `supabase/migrations/` 아래에 생성

### 1-2. 타입/훅 업데이트
- `src/hooks/use-user-plan.ts`:
  - PlanTier 타입에 "Max", "Hidden" 추가
  - isPremium 로직에 Max, Hidden 포함
  - isMax, isHidden 플래그 추가
- Supabase 타입 파일 업데이트 (필요시)

### 1-3. AdminSubscriptions.tsx 매트릭스 UI 개편
- 현재: 플랜별 카드 형태
- 변경: **행(기능) × 열(플랜) 매트릭스 테이블**
  - 행: `feature_definitions` 테이블에서 동적 로드, 카테고리별 그룹핑
  - 열: 무료 / 베이직 / 프로 / 맥스 / 히든
  - 셀:
    - Boolean 타입 → 체크박스 (Switch)
    - Number 타입 → 숫자 입력 (Input)
  - 변경 시 해당 플랜의 `features` JSONB 업데이트
  - "저장" 버튼으로 일괄 저장 또는 변경 즉시 저장 (UX 판단)
- 기능 추가/수정 기능은 기존 유지 (별도 탭 또는 매트릭스 아래)
- 카테고리별 섹션 구분: 메뉴 접근 / AI 토큰 / 수량 제한 / 조직

### 1-4. PlanGuard 업데이트
- requiredPlan에 "max", "hidden" 지원
- 플랜 계층 순서: free < basic < pro < max (hidden은 별도)

### 참조 파일
- `/home/jay/projects/InsuRo/src/pages/AdminSubscriptions.tsx` — 현재 관리 페이지
- `/home/jay/projects/InsuRo/src/hooks/use-user-plan.ts` — 플랜 훅
- `/home/jay/projects/InsuRo/src/components/PlanGuard.tsx` — 접근 제어
- `/home/jay/projects/InsuRo/supabase/combined-migration.sql` — DB 스키마 참조

---

## Phase 2: 토큰제 + 플랜별 AI 모델

### 2-1. 토큰 관련 DB 테이블 생성
```sql
-- 플랜별 토큰 설정
plan_token_config (
  id UUID PRIMARY KEY,
  plan_id UUID REFERENCES subscription_plans(id),
  monthly_token_quota INTEGER NOT NULL,  -- 월간 토큰 할당량 (-1=무제한)
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
)

-- 기능별 토큰 소비 설정
feature_token_costs (
  id UUID PRIMARY KEY,
  feature_key TEXT NOT NULL,  -- feature_definitions.key 참조
  model_tier TEXT NOT NULL,   -- 'haiku', 'sonnet', 'opus' 등
  token_cost INTEGER NOT NULL, -- 1회 사용 시 토큰 소비량
  created_at TIMESTAMPTZ
)

-- 사용자별 토큰 잔액
user_tokens (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id),
  remaining_tokens INTEGER NOT NULL,
  quota_reset_at TIMESTAMPTZ NOT NULL,  -- 다음 리셋 일시
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
)

-- 토큰 사용 로그
token_usage_log (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id),
  feature_key TEXT NOT NULL,
  model_used TEXT NOT NULL,
  tokens_consumed INTEGER NOT NULL,
  created_at TIMESTAMPTZ
)
```
- RLS 정책: 사용자는 자기 토큰/로그만 조회, 관리자는 전체
- 월 초 자동 리셋: Supabase cron 또는 Edge Function

### 2-2. 플랜별 AI 모델 선택
- `plan_ai_models` 테이블 또는 features JSONB에 포함:
  ```
  plan_ai_models (
    id UUID PRIMARY KEY,
    plan_id UUID REFERENCES subscription_plans(id),
    feature_key TEXT NOT NULL,  -- 어떤 AI 기능에 적용
    model_tier TEXT NOT NULL,   -- 'haiku', 'sonnet', 'opus'
    model_name TEXT,            -- 구체적 모델명 (선택)
    created_at TIMESTAMPTZ
  )
  ```
- 기본 모델 매핑 예시:
  - 무료: haiku
  - 베이직: sonnet
  - 프로: sonnet
  - 맥스: opus
  - 히든: opus

### 2-3. 관리자 UI
- AdminSubscriptions 매트릭스에 "토큰 설정" 탭/섹션 추가:
  - 플랜별 월간 토큰 할당량 설정
  - 기능별 × 모델별 토큰 소비량 설정
  - 플랜별 AI 모델 선택 드롭다운
- 토큰 소비율 예시 표시 (관리자가 직관적으로 이해할 수 있도록)

### 2-4. 사용자 UI
- 대시보드 또는 마이페이지에 잔여 토큰 표시
- AI 기능 사용 시 토큰 잔액 확인 → 부족 시 업그레이드 유도
- 토큰 사용 이력 조회 (마이페이지)

### 참조 파일
- `/home/jay/projects/InsuRo/src/pages/AdminAIConfig.tsx` — AI 설정
- `/home/jay/projects/InsuRo/supabase/functions/_shared/ai-provider.ts` — AI 엔진 추상화

---

## Phase 3: 아누 시스템 연동 + 플랜 안내 페이지

### 3-1. AI Provider 모듈화 (아누 시스템 경로)
- `supabase/functions/_shared/ai-provider.ts` 수정:
  - 새 Provider 추가: `anu-system` (아누 시스템 직접 호출)
  - 인터페이스 추상화:
    ```typescript
    interface AIProviderRequest {
      prompt: string;
      model_tier: string;  // 플랜에서 결정된 모델
      feature_key: string;
      user_id: string;
    }

    interface AIProvider {
      generate(req: AIProviderRequest): Promise<AIProviderResponse>;
    }
    ```
  - 아누 시스템 Provider: 리눅스 서버 HTTP 호출
  - 나중에 외부 API Provider로 전환 가능한 구조
- AI 호출 플로우:
  ```
  사용자 요청 → 플랜 확인 → 모델 결정 → 토큰 차감 → AI Provider 호출 → 응답
  ```

### 3-2. 아누 시스템 수신 엔드포인트
- `/home/jay/projects/InsuRo/server/` 또는 별도 경로에:
  - 인슈로→아누 시스템 요청을 받는 API 엔드포인트
  - 인증 (API Key 기반)
  - 모델 라우팅 (model_tier에 따라 Haiku/Sonnet/Opus)
  - 응답 반환
- **모듈화 핵심**: Provider 인터페이스만 바꾸면 아누→외부 API 전환 가능

### 3-3. Pricing.tsx 동적 개편
- 현재: 하드코딩된 2개 플랜 비교
- 변경:
  - DB에서 활성+공개 플랜 동적 로드 (히든 제외, 4개만 표시)
  - 관리자가 매트릭스에서 체크한 기능이 **자동으로 안내 페이지에 반영**
  - 4열 비교 테이블 (무료/베이직/프로/맥스)
  - 기능 행: feature_definitions에서 카테고리별 그룹
  - 셀: Boolean → ✓/✗, Number → 숫자 표시
  - 토큰 할당량 표시
  - AI 모델 등급 표시 (예: "기본 AI" / "고급 AI" / "최고급 AI")
  - 가격 표시 (월간/연간 토글 유지)
- CTA: 각 플랜별 "시작하기" 버튼

### 3-4. PlanUpgradeDialog 업데이트
- 5개 플랜 체계 반영
- 토큰 정보 표시
- AI 모델 등급 안내

### 참조 파일
- `/home/jay/projects/InsuRo/src/pages/Pricing.tsx` — 안내 페이지
- `/home/jay/projects/InsuRo/src/components/PlanUpgradeDialog.tsx` — 업그레이드 다이얼로그
- `/home/jay/projects/InsuRo/supabase/functions/_shared/ai-provider.ts` — AI Provider

---

## 공통 규칙
- InsuRo 프로젝트는 `/home/jay/projects/InsuRo/`에 위치 (workspace 아님!)
- Supabase 마이그레이션은 `supabase/migrations/` 아래에 타임스탬프 prefix로 생성
- 기존 컴포넌트/훅 스타일과 일관성 유지 (shadcn-ui, TanStack Query)
- RLS 정책 반드시 설정
- TypeScript strict mode 준수

## 보고서
- 경로: `/home/jay/workspace/memory/reports/task-621.{phase}.md`
- 완료: `bash /home/jay/workspace/scripts/finish-task.sh task-621.{phase}`