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. 보안 스킴

```yaml
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** (사용자 생성)
```json
{
  "name": "string",       // 필수
  "email": "string",      // 필수
  "password": "string",   // 필수
  "user_id": "string",    // 선택
  "phone": "string",      // 선택
  "roles": ["string"]     // 선택
}
```

**성공 응답 (201):**
```json
{
  "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 이슈 가능성

**구현 방식:**
```typescript
// 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 변경:**
```php
// 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');
```

**프론트엔드는 기존 설계 그대로:**
```typescript
// 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으로 진행
```typescript
// 장점: 현재 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: 세션 쿠키로 진행 (권장)
```typescript
// 장점: 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 테스트:**
```bash
# 로그인
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..."
```

**세션 쿠키 테스트:**
```bash
# 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 설정