# SAM ERP 프론트엔드 개발 가이드

> **대상**: SAM ERP 프론트엔드 신규/기존 개발자
> **최종 업데이트**: 2026-03-13

---

## 목차

| 문서 | 내용 |
|------|------|
| [00-overview.md](./00-overview.md) | 프로젝트 개요 및 기술 스택 (이 문서) |
| [01-project-structure.md](./01-project-structure.md) | 디렉토리 구조 및 파일 배치 규칙 |
| [02-routing-and-pages.md](./02-routing-and-pages.md) | 라우팅, 페이지 모드, 레이아웃 |
| [03-authentication.md](./03-authentication.md) | 인증 흐름, HttpOnly 쿠키, API 프록시 |
| [04-server-actions.md](./04-server-actions.md) | Server Action 패턴, API 통신 유틸리티 |
| [05-common-components.md](./05-common-components.md) | 공통 컴포넌트 (organisms, molecules, templates) |
| [06-ui-components.md](./06-ui-components.md) | UI 컴포넌트 카탈로그 |
| [07-hooks.md](./07-hooks.md) | 공통 Hooks |
| [08-utilities.md](./08-utilities.md) | 유틸리티 함수 (포맷터, URL 빌더, 인쇄 등) |
| [09-coding-conventions.md](./09-coding-conventions.md) | 코딩 컨벤션 및 필수 규칙 |

---

## 프로젝트 개요

```yaml
프로젝트: SAM ERP (통합 자원관리 시스템)
프론트엔드: Next.js 15 (App Router, TypeScript)
백엔드 API: PHP Laravel (sam-api)
특성: 인증 필수 폐쇄형 ERP (SEO 불필요, 크롤링 차단)
```

### 저장소 구조

```
sam_project/
├── sam-next/sma-next-project/sam-react-prod/  # Next.js 프론트엔드 (현재)
├── sam-api/sam-api/                            # PHP Laravel 백엔드 API
├── sam-design/sam-design/                      # React 디자인 시스템
└── sam-hotfix/sam-hotfix/                      # E2E 테스트/핫픽스 관리
```

### 기술 스택

| 카테고리 | 기술 |
|----------|------|
| **프레임워크** | Next.js 15 (App Router, Turbopack) |
| **언어** | TypeScript (strict) |
| **스타일링** | Tailwind CSS |
| **UI 라이브러리** | Radix UI (shadcn/ui 기반) |
| **상태 관리** | Zustand |
| **폼 관리** | react-hook-form + Zod (신규 폼) |
| **차트** | Recharts |
| **국제화** | next-intl (ko, en, ja) |
| **토스트** | Sonner |
| **아이콘** | Lucide React |
| **날짜** | date-fns (한국어 locale) |
| **인증** | HttpOnly Cookie + API Proxy |
| **모바일** | Capacitor (하이브리드 앱) |

### 핵심 원칙

1. **모든 페이지는 Client Component** (`'use client'`) - 폐쇄형 ERP이므로 SEO 불필요, 서버 컴포넌트에서 쿠키 갱신 불가
2. **HttpOnly 쿠키 인증** - JavaScript에서 토큰 접근 불가, API Proxy 필수
3. **mode 쿼리파라미터** - `/new`, `/edit` 별도 경로 대신 `?mode=new`, `?mode=edit` 사용
4. **buildApiUrl 필수** - URL 직접 조립 금지
5. **컴포넌트 재사용** - 새 컴포넌트 전 기존 컴포넌트 검색 필수

### 개발 환경

```bash
# 로컬 개발 서버
npm run dev

# 타입 체크
npx tsc --noEmit

# 빌드 (로컬 확인용)
npm run build
```

### 브랜치 전략

| 브랜치 | 역할 |
|--------|------|
| `develop` | 평소 작업 브랜치 (자유롭게 커밋) |
| `stage` | QA/테스트 환경 |
| `main` | 배포용 (기능별 squash merge) |
| `feature/*` | 큰 기능/실험적 작업 |