# {PROJECT_NAME} SaaS PRD

> 이 문서가 법. 여기 없으면 안 만듦. 여기 있으면 반드시 만듦.
>
> 작성일: {DATE}
> 버전: 1.0

---

## 1. 한 줄 요약

**[타겟 사용자]**를 위한 **[핵심 가치]** SaaS

예시: "1인 창업자를 위한 랜딩 페이지 빌더 SaaS"

---

## 2. 문제 정의

### 2.1 현재 문제

| 문제 | 심각도 | 현재 해결책 |
|------|--------|-------------|
| [문제 1] | 높음/중간/낮음 | [기존에 어떻게 해결하나?] |
| [문제 2] | | |

### 2.2 우리의 해결책

[이 SaaS가 어떻게 해결하나?]

---

## 3. 타겟 사용자

### 3.1 주요 사용자 (Primary)
- **누구**: [예: 1인 창업자, 소규모 팀]
- **특징**: [예: 기술 지식 부족, 비용에 민감]
- **목표**: [예: 빠르게 MVP 런칭]

### 3.2 페르소나
- **이름**: [예: 김창업]
- **직업**: [예: 사이드 프로젝트 운영자]
- **Pain Point**: [예: 개발자 고용 비용 부담]
- **Goal**: [예: 코드 없이 서비스 런칭]

---

## 4. 핵심 기능

### P0 (Must Have) - 없으면 출시 불가

| 기능 | 설명 | 완료 조건 |
|------|------|-----------|
| 회원가입/로그인 | 이메일 + 소셜 (Google, GitHub) | OAuth 플로우 동작 |
| 결제 연동 | Stripe/Paddle 구독 결제 | 결제 → 플랜 활성화 |
| 대시보드 | 핵심 기능 접근 UI | 로그인 후 진입 |
| [핵심 기능 1] | [설명] | [완료 조건] |
| [핵심 기능 2] | [설명] | [완료 조건] |

### P1 (Should Have) - 출시 후 1주 내

| 기능 | 설명 | 완료 조건 |
|------|------|-----------|
| 설정 페이지 | 프로필, 알림, 결제 관리 | 설정 변경 저장 |
| 빌링 포털 | 구독 관리, 인보이스 | Stripe 포털 연동 |
| [기능 1] | [설명] | [완료 조건] |

### P2 (Nice to Have) - 추후 검토

| 기능 | 설명 | 비고 |
|------|------|------|
| 팀 기능 | 멀티 유저 | v2에서 |
| API 제공 | 외부 연동 | 요청 시 |

---

## 5. Constraints (AI 경계)

### ALWAYS (무조건 실행)
- [ ] 모든 사용자 입력 검증
- [ ] 결제 관련 모든 트랜잭션 로깅
- [ ] Webhook 서명 검증 필수
- [ ] 에러 발생 시 사용자 친화적 메시지
- [ ] 민감 데이터 암호화 (비밀번호, 토큰)

### ASK FIRST (확인 후 실행)
- [ ] 가격/플랜 변경
- [ ] DB 스키마 변경
- [ ] 결제 로직 수정
- [ ] 이메일 템플릿 변경

### NEVER (절대 금지)
- [ ] **스펙에 없는 기능 구현**
- [ ] 하드코딩된 API 키/시크릿
- [ ] 결제 금액 클라이언트에서 결정
- [ ] Webhook 서명 검증 생략
- [ ] 사용자 비밀번호 평문 저장
- [ ] 테스트 없이 결제 코드 배포

### Out of Scope (이번 버전에서 안 함)
- 팀/멀티테넌트 - 이유: v2에서
- 모바일 앱 - 이유: 웹 우선
- 다국어 - 이유: 영어/한국어만

---

## 6. 가격 구조

### 6.1 플랜 정의

| 플랜 | 가격 | 제한 | 대상 |
|------|------|------|------|
| Free | $0 | [제한 1], [제한 2] | 체험 |
| Pro | $XX/월 | 무제한 | 개인 |
| Team | $XX/user/월 | 무제한 + 협업 | 팀 |

### 6.2 결제 플로우

```
가입 → Free 시작
   ↓
한계 도달 (예: 3개 프로젝트)
   ↓
업그레이드 CTA
   ↓
Stripe Checkout
   ↓
Webhook 수신 → DB 업데이트
   ↓
Pro 활성화
```

### 6.3 결제 실패 처리

| 단계 | 시점 | 액션 |
|------|------|------|
| 1차 알림 | 즉시 | 이메일 + 인앱 알림 |
| 2차 알림 | +3일 | 이메일 + 기능 제한 경고 |
| 다운그레이드 | +7일 | Free로 전환 |

---

## 7. 화면 구조

### 7.1 사이트맵

```
/                     # 랜딩 페이지
├── /login            # 로그인
├── /signup           # 회원가입
├── /pricing          # 가격표
├── /dashboard        # 대시보드 (로그인 필요)
│   ├── /dashboard/[기능1]
│   └── /dashboard/[기능2]
├── /settings         # 설정
│   ├── /settings/profile
│   ├── /settings/billing
│   └── /settings/notifications
└── /404              # 에러 페이지
```

### 7.2 상태별 UI

| 화면 | 로딩 | 빈 상태 | 에러 |
|------|------|---------|------|
| 대시보드 | 스켈레톤 | "시작하기" CTA | 재시도 버튼 |
| 설정 | 스피너 | - | 인라인 에러 |
| 결제 | 전체 로딩 | - | 명확한 에러 + 지원 링크 |

---

## 8. 기술 스택

### 8.1 프론트엔드

| 구분 | 선택 | 이유 |
|------|------|------|
| 프레임워크 | Next.js / Remix | SSR + 라우팅 |
| 스타일링 | Tailwind | 빠른 개발 |
| 상태관리 | Zustand / Jotai | 간단함 |

### 8.2 백엔드

| 구분 | 선택 | 이유 |
|------|------|------|
| 인증 | Supabase Auth / Clerk | 소셜 로그인 쉬움 |
| DB | Supabase / PlanetScale | 서버리스 |
| 결제 | Stripe / Paddle | 글로벌 결제 |

### 8.3 인프라

| 구분 | 선택 | 이유 |
|------|------|------|
| 호스팅 | Vercel / Railway | 쉬운 배포 |
| 이메일 | Resend / SendGrid | 트랜잭션 이메일 |
| 모니터링 | Sentry | 에러 추적 |

---

## 9. 데이터 모델

### 9.1 테이블 정의

#### users
| 컬럼 | 타입 | 설명 | 제약 |
|------|------|------|------|
| id | uuid | PK | NOT NULL |
| email | varchar(255) | 이메일 | UNIQUE, NOT NULL |
| name | varchar(100) | 이름 | NOT NULL |
| avatar_url | varchar(500) | 프로필 이미지 | |
| created_at | timestamp | 생성일 | DEFAULT now() |

#### subscriptions
| 컬럼 | 타입 | 설명 | 제약 |
|------|------|------|------|
| id | uuid | PK | NOT NULL |
| user_id | uuid | FK → users | NOT NULL |
| stripe_customer_id | varchar(255) | Stripe 고객 ID | |
| stripe_subscription_id | varchar(255) | Stripe 구독 ID | |
| plan | varchar(50) | free/pro/team | DEFAULT 'free' |
| status | varchar(50) | active/canceled/past_due | |
| current_period_end | timestamp | 현재 기간 종료 | |

#### [핵심 엔티티]
| 컬럼 | 타입 | 설명 | 제약 |
|------|------|------|------|

---

## 10. API 설계

### 10.1 인증 엔드포인트

| Method | Endpoint | 설명 | 인증 |
|--------|----------|------|------|
| POST | /auth/signup | 회원가입 | 불필요 |
| POST | /auth/login | 로그인 | 불필요 |
| POST | /auth/logout | 로그아웃 | 필요 |
| GET | /auth/me | 현재 사용자 | 필요 |

### 10.2 결제 엔드포인트

| Method | Endpoint | 설명 | 인증 |
|--------|----------|------|------|
| POST | /api/checkout | Checkout 세션 생성 | 필요 |
| POST | /api/portal | 빌링 포털 URL | 필요 |
| POST | /webhook/stripe | Stripe Webhook | Stripe 서명 |

### 10.3 핵심 기능 엔드포인트

| Method | Endpoint | 설명 | 인증 |
|--------|----------|------|------|
| GET | /api/[리소스] | 목록 | 필요 |
| POST | /api/[리소스] | 생성 | 필요 |
| PUT | /api/[리소스]/:id | 수정 | 필요 |
| DELETE | /api/[리소스]/:id | 삭제 | 필요 |

---

## 11. 결제 체크리스트

### Stripe 연동

- [ ] Stripe 계정 생성 + API 키 설정
- [ ] Products/Prices 생성 (테스트 + 프로덕션)
- [ ] Checkout 세션 생성 로직
- [ ] Webhook 엔드포인트 구현
- [ ] Webhook 서명 검증
- [ ] 이벤트 처리 (checkout.session.completed, invoice.paid, etc.)
- [ ] Customer Portal 연동
- [ ] 테스트 모드 결제 테스트
- [ ] 프로덕션 테스트

### 결제 실패 처리

- [ ] invoice.payment_failed 핸들링
- [ ] customer.subscription.deleted 핸들링
- [ ] 재시도 로직 (Stripe 자동 재시도 + 알림)
- [ ] Grace period 구현

---

## 12. 완료 체크리스트

### 기능
- [ ] 회원가입/로그인 동작
- [ ] 결제 플로우 동작
- [ ] 핵심 기능 동작
- [ ] 설정 페이지 동작

### 품질
- [ ] 테스트 커버리지 > 80%
- [ ] Lighthouse > 80점
- [ ] 에러 모니터링 설정

### 보안
- [ ] 인증 토큰 안전하게 저장
- [ ] Webhook 서명 검증
- [ ] 민감 데이터 암호화
- [ ] HTTPS 적용

### 결제
- [ ] 테스트 결제 성공
- [ ] 프로덕션 결제 성공
- [ ] 환불 처리 테스트
- [ ] 결제 실패 알림 동작

---

## 13. 마일스톤

| 단계 | 내용 | 완료 조건 |
|------|------|-----------|
| M1 | 인증 + 기본 UI | 로그인/가입 동작 |
| M2 | 핵심 기능 | [핵심 기능] 동작 |
| M3 | 결제 연동 | Stripe 결제 동작 |
| M4 | 설정 + 빌링 | 구독 관리 동작 |
| M5 | 배포 | 프로덕션 배포 |

---

## 변경 로그

| 날짜 | 버전 | 변경 내용 | 작성자 |
|------|------|----------|--------|
| {DATE} | 1.0 | 최초 작성 | |
