sam-react-prod/docs/[REF] project-context.md

# SAM React 프로젝트 컨텍스트

> **중요**: 이 파일은 모든 세션에서 가장 먼저 읽어야 하는 프로젝트 개요 문서입니다.

## 📋 프로젝트 개요

**프로젝트 명**: SAM React (Multi-tenant ERP System)
**기술 스택**: Next.js 15 (App Router) + TypeScript + Tailwind CSS
**백엔드**: Laravel PHP API (https://api.5130.co.kr)
**인증 방식**: JWT Bearer Token (Cookie 저장)
**다국어**: 한국어(ko), 영어(en), 일본어(ja)

---

## 🎯 핵심 기능

### 1. 다국어 지원 (i18n)
- **라이브러리**: next-intl v4
- **기본 언어**: 한국어(ko)
- **지원 언어**: ko, en, ja
- **URL 구조**:
  - 기본 언어: `/dashboard` (로케일 표시 안함)
  - 다른 언어: `/en/dashboard`, `/ja/dashboard`
- **자동 감지**: Accept-Language 헤더, 쿠키

**주요 파일**:
```
src/i18n/config.ts          # 언어 설정
src/i18n/request.ts         # 메시지 로딩
src/messages/*.json         # 번역 파일
```

---

### 2. 인증 시스템 (Authentication)

#### 인증 방식
**현재 사용**: JWT Bearer Token + Cookie 저장
- Login → Token 발급 → Cookie에 저장 (`user_token`)
- Middleware에서 Cookie 확인
- API 호출 시 Authorization 헤더 자동 추가

**지원 방식** (3가지):
1. **Bearer Token** (Primary): `user_token` 쿠키
2. **Sanctum Session** (Legacy): `laravel_session` 쿠키
3. **API Key** (Server-to-Server): `X-API-KEY` 헤더

#### API 엔드포인트
```
POST /api/v1/login          # 로그인
POST /api/v1/logout         # 로그아웃
GET  /api/user              # 사용자 정보
```

#### 주요 파일
```
src/lib/api/auth/auth-config.ts    # 라우트 설정
src/lib/api/auth/types.ts          # 타입 정의
src/lib/api/client.ts              # HTTP Client
src/middleware.ts                  # 인증 체크
src/app/api/auth/*                 # API Routes
```

---

### 3. Route 보호 (Route Protection)

#### 라우트 분류
**Protected Routes** (인증 필요):
- `/dashboard`, `/admin`, `/tenant`, `/settings`, `/users`, `/reports`
- 기타 모든 경로 (guestOnlyRoutes, publicRoutes 제외)

**Guest-only Routes** (로그인 시 접근 불가):
- `/login`, `/register`

**Public Routes** (누구나 접근 가능):
- `/` (홈), `/about`, `/contact`

#### 동작 방식
```
Middleware 체크 순서:
1. Bot Detection → 봇이면 403
2. 정적 파일 체크 → 정적이면 Skip
3. 인증 체크 (3가지 방식)
4. Guest-only 체크 → 로그인 상태면 /dashboard로
5. Public 체크 → Public이면 통과
6. Protected 체크 → 비로그인이면 /login으로
7. i18n 처리
```

---

### 4. Bot 차단 (Bot Detection)

#### 목적
- ERP 시스템 보안 강화
- Crawler/Spider로부터 보호된 경로 차단

#### 차단 대상
```typescript
BOT_PATTERNS = [
  /bot/i, /crawler/i, /spider/i, /scraper/i,
  /curl/i, /wget/i, /python-requests/i,
  /headless/i, /puppeteer/i, /playwright/i
]
```

#### 차단 경로
- `/dashboard`, `/admin`, `/api`, `/tenant` 등
- Public 경로(`/`, `/login`)는 bot 허용

---

### 5. 테마 시스템

**기능**: 다크모드/라이트모드 전환
**구현**: Context API + localStorage

**주요 파일**:
```
src/contexts/ThemeContext.tsx
src/components/ThemeSelect.tsx
```

---

## 📁 프로젝트 구조

```
sam-react-prod/
├─ src/
│  ├─ app/[locale]/
│  │  ├─ (protected)/          # 보호된 라우트 그룹
│  │  │  ├─ layout.tsx         # AuthGuard Layout
│  │  │  └─ dashboard/
│  │  │     └─ page.tsx
│  │  ├─ login/page.tsx
│  │  ├─ signup/page.tsx
│  │  ├─ page.tsx              # 홈
│  │  └─ layout.tsx            # 루트 레이아웃
│  │
│  ├─ components/
│  │  ├─ auth/
│  │  │  ├─ LoginPage.tsx
│  │  │  └─ SignupPage.tsx
│  │  ├─ ui/                   # Shadcn UI 컴포넌트
│  │  ├─ ThemeSelect.tsx
│  │  ├─ LanguageSelect.tsx
│  │  └─ NavigationMenu.tsx
│  │
│  ├─ lib/
│  │  ├─ api/
│  │  │  ├─ client.ts          # HTTP Client
│  │  │  └─ auth/
│  │  │     ├─ auth-config.ts
│  │  │     └─ types.ts
│  │  ├─ validations/
│  │  │  └─ auth.ts            # Zod 스키마
│  │  └─ utils.ts
│  │
│  ├─ contexts/
│  │  └─ ThemeContext.tsx
│  │
│  ├─ hooks/
│  │  └─ useAuthGuard.ts
│  │
│  ├─ i18n/
│  │  ├─ config.ts
│  │  └─ request.ts
│  │
│  ├─ messages/
│  │  ├─ ko.json
│  │  ├─ en.json
│  │  └─ ja.json
│  │
│  └─ middleware.ts            # 통합 Middleware
│
├─ claudedocs/                 # 프로젝트 문서
│  ├─ 00_INDEX.md             # 문서 인덱스
│  ├─ project-context.md      # 이 파일
│  └─ ...
│
├─ .env.local                  # 환경 변수 (실제 값)
├─ .env.example                # 환경 변수 템플릿
├─ package.json
├─ next.config.ts
├─ tsconfig.json
└─ tailwind.config.ts
```

---

## 🔧 환경 설정

### 필수 환경 변수 (.env.local)

```env
# API Configuration
NEXT_PUBLIC_API_URL=https://api.5130.co.kr
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000

# API Key (서버 사이드 전용 - 절대 공개 금지!)
API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```

### Next.js 설정 (next.config.ts)

```typescript
import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts');

const nextConfig: NextConfig = {
  turbopack: {}, // Next.js 15 + next-intl 필수 설정
};

export default withNextIntl(nextConfig);
```

---

## 🚀 주요 라이브러리

```json
{
  "dependencies": {
    "next": "^15.5.6",
    "react": "19.2.0",
    "next-intl": "^4.4.0",
    "react-hook-form": "^7.66.0",
    "zod": "^4.1.12",
    "@radix-ui/react-*": "^2.x",
    "tailwindcss": "^4",
    "lucide-react": "^0.552.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1"
  }
}
```

---

## 📝 일반적인 작업 패턴

### 새 보호된 페이지 추가

1. **페이지 파일 생성**:
   ```
   src/app/[locale]/(protected)/new-page/page.tsx
   ```

2. **라우트 설정 추가** (선택사항):
   ```typescript
   // src/lib/api/auth/auth-config.ts
   protectedRoutes: [
     ...
     '/new-page'
   ]
   ```

3. **자동으로 인증 체크 적용됨** (Middleware가 처리)

---

### 새 번역 키 추가

1. **모든 언어 파일에 키 추가**:
   ```json
   // src/messages/ko.json
   {
     "newFeature": {
       "title": "새 기능",
       "description": "설명"
     }
   }

   // src/messages/en.json
   {
     "newFeature": {
       "title": "New Feature",
       "description": "Description"
     }
   }

   // src/messages/ja.json
   {
     "newFeature": {
       "title": "新機能",
       "description": "説明"
     }
   }
   ```

2. **컴포넌트에서 사용**:
   ```typescript
   const t = useTranslations('newFeature');

   <h1>{t('title')}</h1>
   <p>{t('description')}</p>
   ```

---

### API 호출 패턴

```typescript
// src/lib/api/client.ts 사용
import { apiClient } from '@/lib/api/client';

// GET 요청
const data = await apiClient.get('/api/endpoint');

// POST 요청
const result = await apiClient.post('/api/endpoint', {
  key: 'value'
});
```

---

## ⚠️ 중요 주의사항

### 1. 환경 변수 보안
- ❌ `API_KEY`에 절대 `NEXT_PUBLIC_` 붙이지 말 것!
- ✅ `.env.local`은 Git에 커밋 금지 (.gitignore 포함됨)
- ✅ `.env.example`만 템플릿으로 관리

### 2. Middleware 주의사항
- Middleware는 **서버 사이드**에서 실행됨
- `localStorage` 접근 불가
- `console.log`는 **터미널**에 출력됨 (브라우저 콘솔 아님)

### 3. Route Protection 규칙
- **기본 정책**: 모든 페이지는 인증 필요
- **예외**: `publicRoutes`, `guestOnlyRoutes`에 명시된 경로만
- `/` 경로 주의: 정확히 일치할 때만 public

### 4. i18n 사용 시
- 모든 언어 파일에 동일한 키 추가 필수
- Link 사용 시 로케일 포함: `/${locale}/path`
- 날짜/숫자는 `useFormatter` 훅 사용

---

## 🐛 알려진 이슈 및 해결 방법

### 1. Middleware 인증 체크 안됨
**증상**: 로그인 안해도 보호된 페이지 접근 가능
**원인**: `isPublicRoute()` 함수의 `'/'` 매칭 버그
**해결**: `middleware-issue-resolution.md` 참고

### 2. Next.js 15 + next-intl 에러
**증상**: Middleware 컴파일 에러
**원인**: `turbopack` 설정 누락
**해결**: `next.config.ts`에 `turbopack: {}` 추가

---

## 📚 문서 참고 순서

새 세션 시작 시 권장 읽기 순서:

1. **이 파일** (`project-context.md`) - 프로젝트 전체 개요
2. **`00_INDEX.md`** - 상세 문서 인덱스
3. **작업할 기능의 관련 문서** - 인덱스에서 검색

### 주요 문서 빠른 링크

| 작업 | 문서 |
|------|------|
| 다국어 작업 | `i18n-usage-guide.md` |
| 인증 관련 | `jwt-cookie-authentication-final.md` |
| 라우트 보호 | `route-protection-architecture.md` |
| 폼 검증 | `form-validation-guide.md` |
| API 통합 | `authentication-implementation-guide.md` |
| Middleware 수정 | `middleware-issue-resolution.md` |

---

## 🔄 최근 변경 사항

### 2025-11-10
- 테마 선택 및 언어 선택 기능 추가
- 다국어 지원 구현 완료
- Git branch: `feature/theme-language-selector`

### 2025-11-07
- Middleware 인증 문제 해결
- JWT Cookie 인증 방식 확정
- Bot 차단 기능 구현

### 2025-11-06
- i18n 설정 완료 (ko, en, ja)
- 프로젝트 초기 구조 설정

---

## 💡 개발 팁

### 디버깅
- **Middleware 로그**: 터미널 확인 (브라우저 콘솔 아님)
- **인증 상태**: 브라우저 개발자 도구 → Application → Cookies → `user_token` 확인
- **API 요청**: Network 탭에서 Authorization 헤더 확인

### 성능
- 서버 컴포넌트 우선 사용 (클라이언트 번들 크기 감소)
- 정적 파일은 Middleware에서 조기 리턴
- API 응답 캐싱 고려

### 보안
- 민감한 데이터는 서버 컴포넌트에서만 처리
- API Key는 절대 클라이언트에 노출 금지
- CORS 설정 확인 (Laravel 측)

---

## 📞 문제 발생 시

1. **이 파일 다시 읽기**
2. **`00_INDEX.md`에서 관련 문서 찾기**
3. **`middleware-issue-resolution.md` 참고** (인증 관련 이슈)
4. **Git 히스토리 확인** (`git log`, `git diff`)

---

**마지막 업데이트**: 2025-11-10
**작성자**: Claude Code
**프로젝트 저장소**: sam-react-prod