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

Laravel API 요구사항 체크리스트

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

📋 필수 API 엔드포인트

1. CSRF 토큰 발급

GET /sanctum/csrf-cookie

응답:

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

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

---

2. 로그인

POST /api/login
Content-Type: application/json

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

성공 응답 (200):

{
  "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):

{
  "message": "The provided credentials are incorrect.",
  "errors": {
    "email": ["The provided credentials are incorrect."]
  }
}

필요 정보:

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

---

3. 회원가입

POST /api/register
Content-Type: application/json

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

성공 응답 (201):

{
  "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):

{
  "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. 현재 사용자 정보

GET /api/user
Cookie: laravel_session=xxx

성공 응답 (200):

{
  "id": 1,
  "name": "John Doe",
  "email": "user@example.com",
  "role": "user",
  "permissions": ["read", "write"],
  "created_at": "2024-01-01T00:00:00.000000Z"
}

인증 실패 (401):

{
  "message": "Unauthenticated."
}

필요 정보:

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

---

5. 로그아웃

POST /api/logout
Cookie: laravel_session=xxx

성공 응답 (200):

{
  "message": "로그아웃 성공"
}

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

---

6. 비밀번호 재설정 (선택적)

POST /api/forgot-password
Content-Type: application/json

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

성공 응답 (200):

{
  "message": "비밀번호 재설정 링크가 이메일로 전송되었습니다."
}

---

🔧 Laravel 설정 확인 사항

1. Sanctum 설정 (config/sanctum.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)

'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)

'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)

# 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 + 로그인 플로우

# 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: 회원가입 플로우

# 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 객체 구조

interface User {
  id: number;
  name: string;
  email: string;
  // 추가 필드?
  role?: string;
  permissions?: string[];
  avatar?: string;
  created_at: string;
  updated_at: string;
}

4. 에러 응답 형식

interface ApiError {
  message: string;
  errors?: Record<string, string[]>;  // Validation errors
}

5. 회원가입 필수 필드

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 프론트엔드 대기 항목

• 인증 설계 완료
• 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 설정