sam-react-prod/sam-docs/frontend/v1/00-overview.md

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

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

---

목차

문서	내용
00-overview.md	프로젝트 개요 및 기술 스택 (이 문서)
01-project-structure.md	디렉토리 구조 및 파일 배치 규칙
02-routing-and-pages.md	라우팅, 페이지 모드, 레이아웃
03-authentication.md	인증 흐름, HttpOnly 쿠키, API 프록시
04-server-actions.md	Server Action 패턴, API 통신 유틸리티
05-common-components.md	공통 컴포넌트 (organisms, molecules, templates)
06-ui-components.md	UI 컴포넌트 카탈로그
07-hooks.md	공통 Hooks
08-utilities.md	유틸리티 함수 (포맷터, URL 빌더, 인쇄 등)
09-coding-conventions.md	코딩 컨벤션 및 필수 규칙
10-module-separation.md	멀티테넌트 모듈 분리 아키텍처
11-page-patterns.md	페이지 패턴 (리스트, 상세/폼, 검색 모달)
12-form-validation.md	폼 검증 (Zod 스키마, 트러블슈팅)
13-mobile-patterns.md	모바일 반응형 패턴
14-error-handling.md	에러 핸들링 (ApiError, Next.js 에러 파일)
15-deployment.md	배포 가이드 (Vercel)

---

프로젝트 개요

프로젝트: 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. 컴포넌트 재사용 - 새 컴포넌트 전 기존 컴포넌트 검색 필수

개발 환경

# 로컬 개발 서버
npm run dev

# 타입 체크
npx tsc --noEmit

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

브랜치 전략

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