sam-react-prod/claudedocs/api/[REF] api-requirements.md

# Laravel API 요구사항 체크리스트

프론트엔드 인증 구현을 위해 백엔드에서 준비해야 할 API 목록입니다.

## 📋 필수 API 엔드포인트

### 1. CSRF 토큰 발급
```http
GET /sanctum/csrf-cookie
```

**응답:**
```
Set-Cookie: XSRF-TOKEN=xxx; Path=/; HttpOnly
Status: 204 No Content
```

**용도:** 로그인/회원가입 전에 CSRF 토큰 획득

---

### 2. 로그인
```http
POST /api/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}
```

**성공 응답 (200):**
```json
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "created_at": "2024-01-01T00:00:00.000000Z"
  },
  "message": "로그인 성공"
}

Set-Cookie: laravel_session=xxx; Path=/; HttpOnly; SameSite=Lax
```

**실패 응답 (422):**
```json
{
  "message": "The provided credentials are incorrect.",
  "errors": {
    "email": ["The provided credentials are incorrect."]
  }
}
```

**필요 정보:**
- ✅ 응답에 user 객체 포함 여부?
- ✅ user 객체 구조 (어떤 필드들 포함?)
- ✅ 세션 쿠키 이름 (laravel_session?)

---

### 3. 회원가입
```http
POST /api/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "password123",
  "password_confirmation": "password123"
}
```

**성공 응답 (201):**
```json
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "created_at": "2024-01-01T00:00:00.000000Z"
  },
  "message": "회원가입 성공"
}

Set-Cookie: laravel_session=xxx; Path=/; HttpOnly; SameSite=Lax
```

**Validation 실패 (422):**
```json
{
  "message": "The email has already been taken.",
  "errors": {
    "email": ["The email has already been taken."],
    "password": ["The password must be at least 8 characters."]
  }
}
```

**필요 정보:**
- ✅ 회원가입 필수 필드? (name, email, password만?)
- ✅ 추가 필드 필요? (phone, company, etc.)
- ✅ 비밀번호 규칙? (최소 8자? 특수문자 필수?)
- ✅ 이메일 인증 필요? (즉시 로그인 vs 이메일 확인 후)

---

### 4. 현재 사용자 정보
```http
GET /api/user
Cookie: laravel_session=xxx
```

**성공 응답 (200):**
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "user@example.com",
  "role": "user",
  "permissions": ["read", "write"],
  "created_at": "2024-01-01T00:00:00.000000Z"
}
```

**인증 실패 (401):**
```json
{
  "message": "Unauthenticated."
}
```

**필요 정보:**
- ✅ user 객체 전체 구조
- ✅ role/permission 시스템 사용 여부?
- ✅ 추가 사용자 정보 (profile, settings 등)

---

### 5. 로그아웃
```http
POST /api/logout
Cookie: laravel_session=xxx
```

**성공 응답 (200):**
```json
{
  "message": "로그아웃 성공"
}

Set-Cookie: laravel_session=; expires=Thu, 01 Jan 1970 00:00:00 GMT
```

---

### 6. 비밀번호 재설정 (선택적)
```http
POST /api/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}
```

**성공 응답 (200):**
```json
{
  "message": "비밀번호 재설정 링크가 이메일로 전송되었습니다."
}
```

---

## 🔧 Laravel 설정 확인 사항

### 1. Sanctum 설정 (config/sanctum.php)
```php
'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:3000,::1'
)),
```

**확인 필요:**
- ✅ Next.js 개발 서버 도메인 포함? (localhost:3000)
- ✅ 프로덕션 도메인 설정?

---

### 2. CORS 설정 (config/cors.php)
```php
'paths' => ['api/*', 'sanctum/csrf-cookie'],
'supports_credentials' => true,
'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],
'allowed_methods' => ['*'],
'allowed_headers' => ['*'],
'exposed_headers' => [],
'max_age' => 0,
```

**확인 필요:**
- ✅ `supports_credentials` = true?
- ✅ `allowed_origins`에 Next.js URL 포함?

---

### 3. 세션 설정 (config/session.php)
```php
'driver' => env('SESSION_DRIVER', 'file'),
'lifetime' => 120,
'expire_on_close' => false,
'encrypt' => false,
'http_only' => true,
'same_site' => 'lax',
'secure' => env('SESSION_SECURE_COOKIE', false),
'domain' => env('SESSION_DOMAIN'),
```

**확인 필요:**
- ✅ `http_only` = true?
- ✅ `same_site` = 'lax'?
- ✅ `domain` 설정 (개발: null, 프로덕션: .yourdomain.com)
- ✅ 세션 쿠키 이름? (기본: laravel_session)

---

### 4. 환경 변수 (.env)
```env
# Frontend URL
FRONTEND_URL=http://localhost:3000

# Sanctum
SANCTUM_STATEFUL_DOMAINS=localhost:3000

# Session
SESSION_DOMAIN=localhost
SESSION_SECURE_COOKIE=false  # 개발: false, 프로덕션: true

# CORS
```

**확인 필요:**
- ✅ FRONTEND_URL 설정?
- ✅ SANCTUM_STATEFUL_DOMAINS 설정?

---

## 📝 API 테스트 시나리오

### 테스트 1: CSRF + 로그인 플로우
```bash
# 1. CSRF 토큰 획득
curl -X GET http://localhost:8000/sanctum/csrf-cookie \
  -H "Accept: application/json" \
  -c cookies.txt

# 2. 로그인
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -b cookies.txt \
  -c cookies.txt \
  -d '{"email":"test@test.com","password":"password123"}'

# 3. 사용자 정보 확인
curl -X GET http://localhost:8000/api/user \
  -H "Accept: application/json" \
  -b cookies.txt
```

### 테스트 2: 회원가입 플로우
```bash
# 1. CSRF 토큰
curl -X GET http://localhost:8000/sanctum/csrf-cookie \
  -c cookies.txt

# 2. 회원가입
curl -X POST http://localhost:8000/api/register \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -c cookies.txt \
  -d '{
    "name":"New User",
    "email":"new@test.com",
    "password":"password123",
    "password_confirmation":"password123"
  }'
```

---

## 🎯 프론트엔드에서 필요한 정보

### 1. API Base URL
```
개발: http://localhost:8000
프로덕션: https://api.yourdomain.com
```

### 2. 세션 쿠키 이름
```
기본: laravel_session
커스텀: ___?
```

### 3. User 객체 구조
```typescript
interface User {
  id: number;
  name: string;
  email: string;
  // 추가 필드?
  role?: string;
  permissions?: string[];
  avatar?: string;
  created_at: string;
  updated_at: string;
}
```

### 4. 에러 응답 형식
```typescript
interface ApiError {
  message: string;
  errors?: Record<string, string[]>;  // Validation errors
}
```

### 5. 회원가입 필수 필드
```typescript
interface RegisterData {
  name: string;
  email: string;
  password: string;
  password_confirmation: string;
  // 추가 필드?
  phone?: string;
  company?: string;
}
```

---

## ✅ 체크리스트

### Laravel 백엔드 준비 사항

- [ ] Sanctum 패키지 설치 및 설정
- [ ] CORS 설정 완료
- [ ] 세션 설정 확인 (http_only, same_site)
- [ ] API 엔드포인트 구현
  - [ ] GET /sanctum/csrf-cookie
  - [ ] POST /api/login
  - [ ] POST /api/register
  - [ ] GET /api/user
  - [ ] POST /api/logout
- [ ] Validation 규칙 정의
- [ ] 에러 응답 형식 통일
- [ ] 로컬 테스트 (curl 또는 Postman)

### Next.js 프론트엔드 대기 항목

- [x] 인증 설계 완료
- [ ] API 구조 확인 후 구현 시작
  - [ ] lib/auth/sanctum.ts
  - [ ] lib/auth/auth-config.ts
  - [ ] middleware.ts 업데이트
  - [ ] 로그인 페이지
  - [ ] 회원가입 페이지
  - [ ] 인증 테스트

---

## 📞 다음 단계

**백엔드 개발자에게 전달:**
1. 이 문서의 API 엔드포인트 구현
2. 위의 curl 테스트로 동작 확인
3. 다음 정보 공유:
   - API Base URL
   - User 객체 구조
   - 회원가입 필수 필드
   - 세션 쿠키 이름 (변경한 경우)

**정보 받으면 즉시 시작:**
1. Sanctum 클라이언트 구현
2. 로그인/회원가입 페이지
3. Middleware 인증 로직 추가
4. 통합 테스트

---

## 🔍 테스트 계획

### Phase 1: API 연동 테스트
1. CSRF 토큰 획득 확인
2. 로그인 성공/실패 케이스
3. 회원가입 Validation
4. 세션 쿠키 저장 확인

### Phase 2: Middleware 테스트
1. 비로그인 상태 → /dashboard 접근 → /login 리다이렉트
2. 로그인 상태 → /dashboard 접근 → 페이지 표시
3. 로그인 상태 → /login 접근 → /dashboard 리다이렉트
4. 로그아웃 → 쿠키 삭제 확인

### Phase 3: 통합 테스트
1. 회원가입 → 자동 로그인 → 대시보드
2. 로그인 → 페이지 새로고침 → 세션 유지
3. 로그아웃 → 보호된 페이지 접근 → 차단

---

**API 준비되면 바로 알려주세요! 🚀**

---

## 관련 파일

### 프론트엔드
- `src/lib/api/client.ts` - 통합 HTTP 클라이언트
- `src/lib/api/auth/sanctum-client.ts` - Sanctum 클라이언트
- `src/lib/api/auth/auth-config.ts` - 인증 설정 (라우트, URL)
- `src/middleware.ts` - 인증 미들웨어
- `src/app/[locale]/(auth)/login/page.tsx` - 로그인 페이지
- `src/app/[locale]/(auth)/signup/page.tsx` - 회원가입 페이지

### 설정 파일
- `.env.local` - 환경 변수 (API URL, API Key)
- `next.config.ts` - Next.js 설정