sam-react-prod/docs/[IMPL-2025-11-07] auth-guard-usage.md

# Auth Guard Hook 사용 가이드

## 개요

`useAuthGuard()` Hook은 보호된 페이지에 인증 검증과 브라우저 캐시 방지 기능을 제공합니다.

## 기능

1. **실시간 인증 확인**: 페이지 로드 시 서버에 인증 상태 확인
2. **뒤로가기 보호**: 로그아웃 후 브라우저 뒤로가기 시 캐시된 페이지 접근 차단
3. **자동 리다이렉트**: 인증 실패 시 자동으로 로그인 페이지로 이동

## 사용 방법

### 기본 사용

보호가 필요한 모든 페이지에 Hook을 추가하세요:

```tsx
"use client";

import { useAuthGuard } from '@/hooks/useAuthGuard';

export default function ProtectedPage() {
  // 🔒 인증 보호 및 브라우저 캐시 방지
  useAuthGuard();

  return (
    <div>
      {/* 보호된 컨텐츠 */}
    </div>
  );
}
```

### 적용 예시

#### Dashboard 페이지
```tsx
// src/app/[locale]/dashboard/page.tsx
"use client";

import { useAuthGuard } from '@/hooks/useAuthGuard';

export default function Dashboard() {
  useAuthGuard(); // 한 줄만 추가하면 끝!

  return <div>Dashboard Content</div>;
}
```

#### Profile 페이지
```tsx
// src/app/[locale]/profile/page.tsx
"use client";

import { useAuthGuard } from '@/hooks/useAuthGuard';

export default function Profile() {
  useAuthGuard();

  return <div>Profile Content</div>;
}
```

#### Settings 페이지
```tsx
// src/app/[locale]/settings/page.tsx
"use client";

import { useAuthGuard } from '@/hooks/useAuthGuard';

export default function Settings() {
  useAuthGuard();

  return <div>Settings Content</div>;
}
```

## 적용이 필요한 페이지

다음 페이지들에 `useAuthGuard()` Hook을 적용해야 합니다:

### 필수 적용 페이지
- ✅ `/dashboard` - 이미 적용됨
- ⏳ `/profile` - 적용 필요
- ⏳ `/settings` - 적용 필요
- ⏳ `/admin/*` - 모든 관리자 페이지
- ⏳ `/tenant/*` - 모든 테넌트 관리 페이지
- ⏳ `/users/*` - 사용자 관리 페이지
- ⏳ `/reports/*` - 리포트 페이지
- ⏳ `/analytics/*` - 분석 페이지
- ⏳ `/inventory/*` - 재고 관리 페이지
- ⏳ `/finance/*` - 재무 관리 페이지
- ⏳ `/hr/*` - 인사 관리 페이지
- ⏳ `/crm/*` - CRM 페이지

### 적용 불필요 페이지
- ❌ `/login` - 게스트 전용
- ❌ `/signup` - 게스트 전용
- ❌ `/forgot-password` - 게스트 전용

## 동작 방식

### 1. 페이지 로드 시
```
페이지 컴포넌트 마운트
    ↓
useAuthGuard() 실행
    ↓
/api/auth/check 호출 (HttpOnly 쿠키 검증)
    ↓
인증 성공 → 페이지 표시
인증 실패 → /login으로 리다이렉트
```

### 2. 뒤로가기 시 (브라우저 캐시)
```
브라우저 뒤로가기
    ↓
pageshow 이벤트 감지
    ↓
event.persisted === true? (캐시된 페이지인가?)
    ↓
Yes → window.location.reload() (새로고침)
    ↓
useAuthGuard() 재실행
    ↓
인증 확인 → 쿠키 없음 → /login 리다이렉트
```

## 내부 구현

`src/hooks/useAuthGuard.ts`:

```typescript
export function useAuthGuard() {
  const router = useRouter();

  useEffect(() => {
    // 1. 인증 확인
    const checkAuth = async () => {
      const response = await fetch('/api/auth/check');
      if (!response.ok) {
        router.replace('/login');
      }
    };

    checkAuth();

    // 2. 브라우저 캐시 방지
    const handlePageShow = (event: PageTransitionEvent) => {
      if (event.persisted) {
        window.location.reload();
      }
    };

    window.addEventListener('pageshow', handlePageShow);

    return () => {
      window.removeEventListener('pageshow', handlePageShow);
    };
  }, [router]);
}
```

## API 엔드포인트

### GET /api/auth/check

**목적**: HttpOnly 쿠키를 통한 인증 상태 확인

**요청:**
```http
GET /api/auth/check HTTP/1.1
Cookie: user_token=...
```

**응답 (인증 성공):**
```json
{
  "authenticated": true
}
```
Status: `200 OK`

**응답 (인증 실패):**
```json
{
  "error": "Not authenticated",
  "authenticated": false
}
```
Status: `401 Unauthorized`

## 테스트 시나리오

### 시나리오 1: 정상 접근
1. 로그인 상태로 `/dashboard` 접근
2. ✅ 페이지 정상 표시
3. 콘솔 로그 없음 (정상 동작)

### 시나리오 2: 비로그인 접근
1. 로그아웃 상태로 `/dashboard` URL 직접 입력
2. ✅ 즉시 `/login`으로 리다이렉트
3. 콘솔: "⚠️ 인증 실패: 로그인 페이지로 이동"

### 시나리오 3: 로그아웃 후 뒤로가기
1. `/dashboard` 접속 (로그인 상태)
2. Logout 버튼 클릭 → `/login` 이동
3. 브라우저 뒤로가기 버튼 클릭
4. ✅ 캐시된 페이지 감지 → 새로고침 → `/login` 리다이렉트
5. 콘솔: "🔄 캐시된 페이지 감지: 새로고침"

### 시나리오 4: 다른 탭에서 로그아웃
1. 탭 A: `/dashboard` 접속 (로그인 상태)
2. 탭 B: 같은 브라우저에서 로그아웃
3. 탭 A: 페이지 새로고침 또는 다른 페이지 이동
4. ✅ 인증 확인 실패 → `/login` 리다이렉트

## Middleware와의 관계

| 보안 레이어 | 역할 | 타이밍 |
|-----------|------|--------|
| **Middleware** | 서버 사이드 경로 보호 | 모든 요청 전 |
| **useAuthGuard** | 클라이언트 사이드 보호 | 페이지 마운트 시 |

### 왜 둘 다 필요한가?

**Middleware만 있으면?**
- ❌ 브라우저 뒤로가기 캐시 문제 해결 안됨
- ❌ 실시간 인증 상태 변경 감지 안됨

**useAuthGuard만 있으면?**
- ❌ URL 직접 접근 시 보호 지연 (컴포넌트 마운트 후)
- ❌ 서버 사이드 렌더링 보호 안됨

**둘 다 있으면:**
- ✅ 서버 + 클라이언트 이중 보호
- ✅ 브라우저 캐시 문제 해결
- ✅ 실시간 인증 상태 동기화

## 성능 고려사항

### API 호출 최소화
- `useAuthGuard`는 페이지 마운트 시 1회만 호출
- 페이지 이동 시마다 다시 실행됨 (의도된 동작)

### 사용자 경험
- 인증 확인은 비동기로 처리되어 UI 블로킹 없음
- 인증 실패 시 `router.replace()` 사용 (뒤로가기 히스토리 오염 방지)

## 문제 해결

### 문제: Hook이 작동하지 않음
**원인:** 페이지가 Server Component로 되어 있음
**해결:** 파일 상단에 `"use client";` 추가

### 문제: 무한 리다이렉트
**원인:** `/login` 페이지에도 Hook 적용됨
**해결:** 게스트 전용 페이지에는 Hook 사용 금지

### 문제: 뒤로가기 시 여전히 페이지 보임
**원인:** `pageshow` 이벤트 리스너 미등록
**해결:** Hook이 올바르게 import되었는지 확인

## 향후 개선 사항

### 1. 토큰 검증 추가
현재는 토큰 존재 여부만 확인하지만, 향후 PHP 백엔드에 토큰 유효성 검증 추가 가능:

```typescript
// /api/auth/check 개선
const response = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/v1/verify`, {
  headers: { 'Authorization': `Bearer ${token}` }
});
```

### 2. 자동 새로고침 주기
장시간 페이지 유지 시 주기적 인증 확인:

```typescript
useEffect(() => {
  const interval = setInterval(checkAuth, 5 * 60 * 1000); // 5분마다
  return () => clearInterval(interval);
}, []);
```

### 3. 세션 만료 경고
토큰 만료 임박 시 사용자에게 알림:

```typescript
if (expiresIn < 5 * 60 * 1000) {
  showToast('세션이 곧 만료됩니다. 다시 로그인해주세요.');
}
```

## 요약

✅ **적용 완료:**
- Dashboard 페이지

⏳ **적용 필요:**
- 다른 모든 보호된 페이지들

📝 **사용법:**
```tsx
import { useAuthGuard } from '@/hooks/useAuthGuard';

export default function Page() {
  useAuthGuard(); // 이 한 줄만 추가!
  return <div>Content</div>;
}
```

🔒 **보안 효과:**
- 브라우저 캐시 악용 방지
- 실시간 인증 상태 동기화
- 로그아웃 후 완전한 페이지 접근 차단