# {PROJECT_NAME} API PRD

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

---

## 1. 한 줄 요약

**[서비스/클라이언트]**를 위한 **[핵심 기능]** REST API

예시: "프론트엔드 앱을 위한 사용자 인증 및 데이터 관리 API"

---

## 2. 문제 정의

### 2.1 현재 문제

| 문제 | 심각도 | 현재 해결책 |
|------|--------|-------------|
| [문제 1] | 높음/중간/낮음 | [기존 방식] |

### 2.2 이 API의 해결책

[이 API가 어떻게 해결하는지]

---

## 3. API 소비자

### 3.1 주요 클라이언트
- **누구**: [예: 웹 프론트엔드]
- **환경**: [예: 브라우저, React]
- **요구사항**: [예: 빠른 응답, JSON 형식]

### 3.2 부가 클라이언트
- **누구**: [예: 모바일 앱]
- **특이사항**: [예: 네트워크 불안정, 오프라인 지원 필요]

---

## 4. 엔드포인트 정의

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

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

### P1 (Should Have)

| Method | Endpoint | 설명 | 인증 | 에러 |
|--------|----------|------|------|------|
| [METHOD] | [경로] | [설명] | [인증] | [에러] |

### P2 (Nice to Have)

| Method | Endpoint | 설명 | 비고 |
|--------|----------|------|------|
| [METHOD] | [경로] | [설명] | [추후 검토] |

---

## 5. Constraints (AI 경계)

### ALWAYS (무조건 실행)
- [ ] 모든 입력 검증 (타입, 길이, 형식)
- [ ] 모든 응답에 적절한 HTTP 상태 코드
- [ ] 에러 발생 시 구조화된 로깅
- [ ] Rate Limiting 적용
- [ ] 인증 미들웨어 적용

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

### NEVER (절대 금지)
- [ ] **스펙에 없는 엔드포인트 구현**
- [ ] 하드코딩된 시크릿/API 키
- [ ] SQL 직접 작성 (ORM 사용)
- [ ] 에러 무시 (catch 후 빈 응답)
- [ ] 사용자 입력 직접 쿼리 삽입

### Out of Scope
- [기능 X] - 이유: v2에서
- GraphQL - 이유: REST로 충분

---

## 6. 요청/응답 형식

### 6.1 공통 응답 형식

**성공**
```json
{
  "success": true,
  "data": { ... }
}
```

**에러**
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "사용자 친화적 메시지",
    "field": "필드명 (검증 에러 시)"
  }
}
```

### 6.2 에러 코드 목록

| 코드 | HTTP | 상황 | 메시지 |
|------|------|------|--------|
| AUTH_REQUIRED | 401 | 토큰 없음 | "로그인이 필요합니다" |
| INVALID_TOKEN | 401 | 토큰 만료/잘못됨 | "다시 로그인해주세요" |
| INVALID_INPUT | 400 | 입력 오류 | [필드별 메시지] |
| NOT_FOUND | 404 | 리소스 없음 | "찾을 수 없습니다" |
| CONFLICT | 409 | 중복 | "이미 존재합니다" |
| RATE_LIMITED | 429 | 요청 과다 | "잠시 후 다시 시도하세요" |
| INTERNAL_ERROR | 500 | 서버 오류 | "잠시 후 다시 시도해주세요" |

---

## 7. 데이터 모델

### 7.1 테이블 정의

#### users
| 컬럼 | 타입 | 설명 | 제약 |
|------|------|------|------|
| id | uuid | PK | NOT NULL |
| email | varchar(255) | 이메일 | UNIQUE, NOT NULL |
| password_hash | varchar(255) | 비밀번호 해시 | NOT NULL |
| created_at | timestamp | 생성일 | DEFAULT now() |
| updated_at | timestamp | 수정일 | DEFAULT now() |

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

---

## 8. 기술 스택

| 구분 | 선택 | 이유 |
|------|------|------|
| 런타임 | Node / Python / Go | [이유] |
| 프레임워크 | Express / FastAPI / Gin | [이유] |
| DB | PostgreSQL / MySQL | [이유] |
| 인증 | JWT / Session | [이유] |
| 문서화 | OpenAPI / Swagger | [이유] |

---

## 9. 비기능 요구사항

### 9.1 성능
| 항목 | 목표 | 측정 |
|------|------|------|
| API 응답 (p95) | < 200ms | APM |
| 처리량 | > 100 req/s | 부하 테스트 |
| 가용성 | 99.9% | 모니터링 |

### 9.2 보안
- [ ] HTTPS 필수
- [ ] SQL Injection 방지 (ORM)
- [ ] Rate Limiting
- [ ] CORS 설정
- [ ] Helmet (보안 헤더)

---

## 10. 완료 체크리스트

### 기능
- [ ] P0 엔드포인트 전체 동작
- [ ] 모든 에러 응답 형식 통일
- [ ] 인증 플로우 완료

### 품질
- [ ] 테스트 커버리지 > 80%
- [ ] OpenAPI 스펙 작성
- [ ] 부하 테스트 통과

### 보안
- [ ] 모든 입력 검증됨
- [ ] SQL Injection 방지됨
- [ ] Rate Limiting 적용됨

---

## 변경 로그

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