# 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');
{t('title')}
{t('description')}
```
---
### 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