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로부터 보호된 경로 차단

차단 대상

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)

# 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)

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);

---

🚀 주요 라이브러리

{
  "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. 라우트 설정 추가 (선택사항):

   // src/lib/api/auth/auth-config.ts
   protectedRoutes: [
     ...
     '/new-page'
   ]
   

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

---

새 번역 키 추가

1. 모든 언어 파일에 키 추가:

   // 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. 컴포넌트에서 사용:

   const t = useTranslations('newFeature');
   
   <h1>{t('title')}</h1>
   <p>{t('description')}</p>
   

---

API 호출 패턴

// 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