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

SAM API 분석 결과

API 문서: https://api.5130.co.kr/docs?api-docs-v1.json

🔍 핵심 발견사항

1. 인증 방식

현재 API 문서에서 확인된 인증 방식:

❌ 세션 쿠키 기반 (Sanctum SPA 모드) - 없음
✅ Bearer Token (JWT) 방식
✅ API Key 방식

2. 보안 스킴

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY (추정)

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

사용 패턴:

• 대부분의 엔드포인트: ApiKeyAuth OR BearerAuth
• 두 방식 중 선택 가능

3. User 관련 엔드포인트 (Admin)

POST /api/v1/admin/users (사용자 생성)

{
  "name": "string",       // 필수
  "email": "string",      // 필수
  "password": "string",   // 필수
  "user_id": "string",    // 선택
  "phone": "string",      // 선택
  "roles": ["string"]     // 선택
}

성공 응답 (201):

{
  "id": 1,
  "name": "John Doe",
  "email": "user@example.com",
  "created_at": "2024-01-01T00:00:00Z"
}

에러 응답:

• 409: 이메일 중복
• 400: 필수 파라미터 누락

⚠️ 중요한 발견

인증 엔드포인트가 문서에 없음

현재 문서에서 찾을 수 없는 엔드포인트:

❌ POST /api/auth/login
❌ POST /api/auth/register
❌ POST /api/auth/logout
❌ GET /api/auth/user
❌ POST /api/auth/refresh
❌ GET /sanctum/csrf-cookie

이유:

1. 아직 구성 중이라 문서화 안됨
2. 별도 인증 서버 존재 가능성
3. 다른 경로에 존재 (예: /api/v1/auth/*)

🎯 설계 조정 필요

원래 설계 (Sanctum SPA 모드)

인증: HTTP-only 쿠키
저장: 서버 세션
CSRF: 필요
Middleware: 쿠키 확인

새로운 설계 (Bearer Token 모드)

인증: JWT Bearer Token
저장: localStorage 또는 쿠키
CSRF: 불필요
Middleware: Token 확인 (클라이언트 사이드)

📋 두 가지 시나리오

시나리오 A: Bearer Token (JWT) 방식

장점:

• 현재 API 구조와 일치
• Stateless (서버 세션 불필요)
• 모바일 앱 지원 용이
• API Key 또는 Token 선택 가능

단점:

• XSS 취약 (localStorage 사용 시)
• Token 관리 복잡 (refresh token 등)
• CORS 이슈 가능성

구현 방식:

// 1. 로그인 → JWT 토큰 받기
const { token } = await login(email, password);
localStorage.setItem('token', token);

// 2. API 요청 시 토큰 포함
fetch('/api/endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

// 3. Middleware는 클라이언트에서 체크
// (서버 Middleware에서는 체크 불가)

Middleware 제약:

• Next.js Middleware는 서버사이드 실행
• localStorage 접근 불가
• Token 검증 어려움
• → 클라이언트 가드 컴포넌트 필요

---

시나리오 B: 세션 쿠키 방식 (권장)

장점:

• 서버 Middleware에서 인증 체크 가능
• XSS 방어 (HTTP-only 쿠키)
• CSRF 토큰으로 보안 강화
• 기존 설계 그대로 사용

단점:

• Laravel API 수정 필요
• 세션 관리 필요

필요한 Laravel 변경:

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost:3000')),

// API Routes
Route::post('/login', [AuthController::class, 'login']); // 세션 생성
Route::post('/logout', [AuthController::class, 'logout'])->middleware('auth:sanctum');
Route::get('/user', [AuthController::class, 'user'])->middleware('auth:sanctum');

프론트엔드는 기존 설계 그대로:

// Middleware에서 쿠키 확인
const sessionCookie = request.cookies.get('laravel_session');
if (!sessionCookie) redirect('/login');

---

🤔 권장사항

1차 선택: 백엔드 개발자와 협의 필요

질문할 사항:

Q1. 인증 방식이 정해졌나요?
    A. Bearer Token (JWT)
    B. 세션 쿠키 (Sanctum SPA)
    C. 둘 다 지원

Q2. 로그인/회원가입 API 경로는?
    예: POST /api/v1/auth/login?

Q3. 로그인 응답 형식은?
    A. { token: "xxx" }  // JWT
    B. { user: {...} }   // 세션 + 쿠키

Q4. Token refresh 로직 있나요? (JWT인 경우)

Q5. CORS 설정 완료?
    - Allow Origin: http://localhost:3000
    - Allow Credentials: true (쿠키 사용 시)

2차 선택: 시나리오별 구현 방식

Option A: Bearer Token으로 진행

// 장점: 현재 API 구조 그대로 사용
// 단점: Middleware 인증 체크 불가, 클라이언트 가드 필요

// lib/auth/token-client.ts
class TokenClient {
  async login(email: string, password: string) {
    const { token } = await fetch('/api/v1/auth/login', {
      method: 'POST',
      body: JSON.stringify({ email, password })
    }).then(r => r.json());

    localStorage.setItem('auth_token', token);
  }

  getToken() {
    return localStorage.getItem('auth_token');
  }
}

// components/ProtectedRoute.tsx (클라이언트 가드)
function ProtectedRoute({ children }) {
  const token = localStorage.getItem('auth_token');

  if (!token) {
    redirect('/login');
  }

  return children;
}

Option B: 세션 쿠키로 진행 (권장)

// 장점: Middleware 인증, 보안 강화
// 단점: Laravel API 수정 필요

// 기존 설계 문서 그대로 구현
// claudedocs/authentication-design.md 참고

---

📝 다음 단계

1. 백엔드 개발자와 협의 ✅ 최우선

확인 사항:

• 인증 방식 확정 (JWT vs 세션)
• 로그인/회원가입 API 경로
• 응답 형식
• CORS 설정

2. 협의 결과에 따라

A. Bearer Token 방식:

• Token 클라이언트 구현
• AuthContext (Token 저장/관리)
• 클라이언트 가드 컴포넌트
• API 인터셉터 (Token 자동 추가)

B. 세션 쿠키 방식:

• 기존 설계 그대로 구현
• Sanctum 클라이언트
• Middleware 인증 로직
• 로그인/회원가입 페이지

3. API 테스트

Bearer Token 테스트:

# 로그인
curl -X POST https://api.5130.co.kr/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"password"}'

# 응답 예상
{"token": "eyJhbGciOiJIUzI1NiIs..."}

# 인증 요청
curl -X GET https://api.5130.co.kr/api/v1/user \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

세션 쿠키 테스트:

# CSRF 토큰
curl -X GET https://api.5130.co.kr/sanctum/csrf-cookie -c cookies.txt

# 로그인
curl -X POST https://api.5130.co.kr/api/login \
  -b cookies.txt -c cookies.txt \
  -d '{"email":"test@test.com","password":"password"}'

# 사용자 정보
curl -X GET https://api.5130.co.kr/api/user \
  -b cookies.txt

---

🎯 현재 상태

대기 사항:

1. ✅ API 문서 분석 완료
2. ⏳ 인증 방식 확정 대기
3. ⏳ 실제 로그인 API 경로 확인 대기
4. ⏳ 응답 형식 확인 대기

다음 액션:

• 백엔드 개발자와 인증 방식 협의
• 결정되면 즉시 구현 시작

---

💡 개인적 권장

세션 쿠키 방식 (Sanctum SPA) 추천 이유:

1. 보안: HTTP-only 쿠키로 XSS 방어
2. Middleware 활용: 서버사이드 인증 체크
3. 간단함: CSRF 토큰만 관리하면 됨
4. Laravel 친화적: Sanctum이 기본 제공
5. 우리 설계와 완벽히 일치: 기존 문서 그대로 사용

하지만 최종 결정은 백엔드 아키텍처와 요구사항에 따라야 합니다!

백엔드 개발자에게 이 문서 공유 후 협의 추천 👍

---

관련 파일

프론트엔드

• src/lib/api/client.ts - 통합 HTTP 클라이언트
• src/lib/api/auth/token-storage.ts - Token 저장 관리
• src/lib/api/auth/auth-config.ts - 인증 설정
• src/middleware.ts - 인증 미들웨어
• src/contexts/AuthContext.tsx - 인증 상태 관리

설정 파일

• .env.local - 환경 변수
• next.config.ts - Next.js 설정