c309ac479f
- 법인차량 관리 3개 페이지 (차량등록, 운행일지, 정비이력) - MES 데이터 정합성 분석 보고서 v1/v2 - sam-docs 프론트엔드 기술문서 v1 (9개 챕터) - claudedocs 가이드/테스트URL 업데이트
91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
# 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/*` | 큰 기능/실험적 작업 |
|