# {PROJECT_NAME} PRD

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

---

## 1. 한 줄 요약

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

예시: "바쁜 직장인을 위한 간편 식단 관리 웹앱"

---

## 2. 문제 정의

### 2.1 현재 문제

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

### 2.2 우리의 해결책

[이 앱이 어떻게 해결하나?]

---

## 3. 타겟 사용자

### 3.1 주요 사용자 (Primary)
- **누구**: [예: 20-30대 직장인]
- **특징**: [예: 시간이 없음, 모바일 선호]
- **목표**: [예: 건강한 식단을 쉽게 관리하고 싶음]

### 3.2 부가 사용자 (Secondary)
- **누구**: [예: 헬스 트레이너]
- **목표**: [예: 고객 식단 관리]

---

## 4. 핵심 기능

### P0 (Must Have) - 없으면 출시 불가
| 기능 | 설명 | 완료 조건 |
|------|------|-----------|
| 회원가입/로그인 | 소셜 로그인 (Google, Kakao) | 로그인 후 대시보드 진입 |
| [기능 2] | [설명] | [완료 조건] |
| [기능 3] | [설명] | [완료 조건] |

### P1 (Should Have) - 출시 후 1주 내
| 기능 | 설명 | 완료 조건 |
|------|------|-----------|
| [기능 1] | [설명] | [완료 조건] |

### P2 (Nice to Have) - 추후 검토
| 기능 | 설명 | 비고 |
|------|------|------|
| [기능 1] | [설명] | [언제 할지] |

---

## 5. Constraints (AI 경계) ⚠️

> **이 섹션은 필수입니다. AI가 임의로 판단하지 않도록 명시적으로 작성하세요.**

### ✅ ALWAYS (무조건 실행)
- [ ] 모든 사용자 입력 검증 (빈 값, 형식, 길이)
- [ ] 모든 API 응답에 적절한 HTTP 상태 코드
- [ ] 에러 발생 시 로깅 (console.error 아님, 로깅 시스템)
- [ ] 커밋 전 테스트 실행
- [ ] TypeScript strict 모드

### ⚠️ ASK FIRST (확인 후 실행)
- [ ] DB 스키마 변경
- [ ] 새 의존성 추가
- [ ] 인증/권한 로직 수정
- [ ] API 엔드포인트 추가/삭제
- [ ] 환경 변수 추가

### 🚫 NEVER (절대 금지)
- [ ] **스펙(이 문서)에 없는 기능 구현**
- [ ] 하드코딩된 시크릿/API 키
- [ ] console.log 프로덕션 배포
- [ ] any 타입 사용 (unknown 사용)
- [ ] 테스트 없이 커밋
- [ ] 에러 무시 (catch 후 아무것도 안 함)
- [ ] 사용자 입력 직접 SQL/HTML 삽입

### ❌ Out of Scope (이번 버전에서 안 함)
<!-- 명시하지 않으면 AI가 "당연히 필요하겠지"라고 추가할 수 있음 -->
- [기능 X] - 이유: [왜 안 하는지]
- [기능 Y] - 이유: [왜 안 하는지]
- 다국어 지원 - 이유: v2에서
- 다크모드 - 이유: 우선순위 낮음

---

## 6. Edge Cases (필수) ⚠️

> **각 기능당 최소 3개의 엣지 케이스를 정의하세요.**

### 6.1 회원가입/로그인

| 상황 | 입력 | 예상 결과 |
|------|------|----------|
| 빈 이메일 | "" | 에러: "이메일을 입력하세요" |
| 잘못된 형식 | "abc" | 에러: "올바른 이메일 형식이 아닙니다" |
| 이미 가입된 이메일 | "exist@test.com" | 에러: "이미 가입된 이메일입니다" |
| 비밀번호 너무 짧음 | "123" | 에러: "8자 이상 입력하세요" |
| 소셜 로그인 취소 | 취소 버튼 | 로그인 페이지로 복귀, 에러 없음 |
| 네트워크 끊김 | 요청 중 오프라인 | 에러: "네트워크 연결을 확인하세요" + 재시도 버튼 |

### 6.2 [기능 2]

| 상황 | 입력 | 예상 결과 |
|------|------|----------|
| [상황 1] | [입력] | [결과] |
| [상황 2] | [입력] | [결과] |
| [상황 3] | [입력] | [결과] |

### 6.3 [기능 3]

| 상황 | 입력 | 예상 결과 |
|------|------|----------|
| [상황 1] | [입력] | [결과] |
| [상황 2] | [입력] | [결과] |
| [상황 3] | [입력] | [결과] |

---

## 7. 화면 구조

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

### 7.2 상태별 UI

| 화면 | 로딩 | 빈 상태 | 에러 |
|------|------|---------|------|
| 대시보드 | 스켈레톤 | "아직 데이터가 없어요" + CTA | "불러오기 실패" + 재시도 |
| 목록 | 스켈레톤 3줄 | "항목이 없어요" + 추가 버튼 | 인라인 에러 |

---

## 8. 기술 스택

### 8.1 프론트엔드
| 구분 | 선택 | 이유 |
|------|------|------|
| 프레임워크 | React / Next.js / Vue | [선택 이유] |
| 스타일링 | Tailwind / CSS Modules | [선택 이유] |
| 상태관리 | Zustand / Redux / Pinia | [선택 이유] |

### 8.2 백엔드
| 구분 | 선택 | 이유 |
|------|------|------|
| 런타임 | Node / Python / Go | [선택 이유] |
| 프레임워크 | Express / FastAPI / Gin | [선택 이유] |
| DB | PostgreSQL / MySQL / MongoDB | [선택 이유] |
| 인증 | Supabase / Firebase / 직접 구현 | [선택 이유] |

---

## 9. 데이터 모델

### 9.1 테이블 정의

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

#### [테이블 2]
| 컬럼 | 타입 | 설명 | 제약 |
|------|------|------|------|
| | | | |

---

## 10. API 설계

### 10.1 엔드포인트

| Method | Endpoint | 설명 | 인증 | 에러 |
|--------|----------|------|------|------|
| POST | /auth/login | 로그인 | 불필요 | 400, 401 |
| POST | /auth/signup | 회원가입 | 불필요 | 400, 409 |
| GET | /api/[리소스] | 목록 조회 | 필요 | 401, 500 |
| POST | /api/[리소스] | 생성 | 필요 | 400, 401 |

### 10.2 에러 응답 형식
```json
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "이메일 형식이 올바르지 않습니다.",
    "field": "email"
  }
}
```

### 10.3 에러 코드 목록

| 코드 | HTTP | 상황 | 메시지 |
|------|------|------|--------|
| AUTH_REQUIRED | 401 | 토큰 없음 | "로그인이 필요합니다" |
| INVALID_INPUT | 400 | 입력 오류 | [필드별] |
| NOT_FOUND | 404 | 없음 | "찾을 수 없습니다" |
| INTERNAL_ERROR | 500 | 서버 오류 | "잠시 후 다시 시도해주세요" |

---

## 11. Acceptance Criteria (Gherkin) ⚠️

> **각 기능에 대해 정상/실패 시나리오를 모두 작성하세요.**

```gherkin
Feature: 회원가입

Scenario: 정상 회원가입
  Given 신규 사용자가 회원가입 페이지에서
  When 올바른 이메일과 비밀번호를 입력하고 가입 버튼을 클릭하면
  Then 계정이 생성되어야 함
  And 대시보드로 자동 이동해야 함
  And 환영 이메일이 발송되어야 함

Scenario: 중복 이메일로 회원가입 시도
  Given 이미 가입된 이메일 "exist@test.com"으로
  When 회원가입을 시도하면
  Then 계정이 생성되지 않아야 함 (NOT)
  And "이미 가입된 이메일입니다" 에러가 표시되어야 함
  And 이메일 필드에 포커스가 가야 함

Feature: 로그인

Scenario: 정상 로그인
  Given 가입된 사용자 "user@test.com"이
  When 올바른 비밀번호로 로그인하면
  Then 대시보드로 이동해야 함
  And 세션이 생성되어야 함

Scenario: 잘못된 비밀번호로 로그인
  Given 가입된 사용자가
  When 잘못된 비밀번호로 로그인 시도하면
  Then 로그인 되지 않아야 함 (NOT)
  And "비밀번호가 일치하지 않습니다" 표시되어야 함
  And 비밀번호 필드가 초기화되어야 함
  And 로그인 시도 횟수가 증가해야 함

Scenario: 5회 로그인 실패 시 잠금
  Given 4회 로그인 실패한 사용자가
  When 5번째 잘못된 비밀번호로 시도하면
  Then 계정이 15분간 잠겨야 함
  And "계정이 일시 잠금되었습니다. 15분 후 시도하세요" 표시

Feature: [기능 2]

Scenario: [정상 케이스]
  Given [조건]
  When [행동]
  Then [결과]

Scenario: [실패 케이스]
  Given [조건]
  When [행동]
  Then [실패 결과] (NOT)
  And [에러 메시지]
```

---

## 12. 비기능 요구사항

### 12.1 성능 (정량화)
| 항목 | 목표 | 측정 |
|------|------|------|
| 페이지 로드 | < 3초 | Lighthouse |
| API 응답 (p95) | < 500ms | 로그 |
| Lighthouse 점수 | > 80점 | Chrome DevTools |

### 12.2 보안
- [ ] HTTPS 필수
- [ ] SQL Injection 방지 (ORM 사용)
- [ ] XSS 방지 (입력 이스케이프)
- [ ] CORS 설정

---

## 13. 완료 체크리스트 ⚠️

> **이 체크리스트가 모두 완료되어야 "완료"입니다.**

### 기능
- [ ] P0 기능 전체 동작
- [ ] 모든 Edge Case 처리됨
- [ ] 모든 에러 메시지 사용자 친화적

### 품질
- [ ] 테스트 커버리지 > 80%
- [ ] Lighthouse 성능 > 80점
- [ ] TypeScript 에러 0개
- [ ] 콘솔 에러/경고 0개

### 보안
- [ ] 모든 입력 검증됨
- [ ] XSS 방지됨
- [ ] 시크릿 하드코딩 없음
- [ ] HTTPS 적용됨

### 문서
- [ ] README 업데이트됨
- [ ] API 문서 작성됨
- [ ] 변경 로그 작성됨

---

## 14. 마일스톤

| 단계 | 내용 | 완료 조건 |
|------|------|-----------|
| M1 | 기본 구조 + 인증 | 로그인/회원가입 동작 |
| M2 | P0 기능 구현 | [완료 조건] |
| M3 | 테스트 + 버그픽스 | 테스트 통과 |
| M4 | 배포 | 프로덕션 배포 완료 |

---

## 변경 로그

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