sam-docs/frontend/v1/00-onboarding.md

00. 신규 합류자 온보딩 가이드

대상: 프로젝트에 새로 합류하는 개발자 (시니어 포함) 버전: 1.0.0 최종 수정: 2026-03-20 읽는 시간: 15분

---

1. SAM ERP 한눈에 보기

SAM은 멀티테넌트 폐쇄형 ERP 시스템입니다. 인증된 사용자만 접근 가능하며, 테넌트(고객사)별로 필요한 모듈만 활성화됩니다.

┌─────────────────────────────────────────────────────────┐
│  SAM ERP Platform                                       │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │  공통 ERP (~165 페이지)                           │    │
│  │  회계 | 영업 | 인사 | 결재 | 게시판 | 설정       │    │
│  │  고객센터 | 기준정보 | 자재/재고 | 출고/배송      │    │
│  └─────────────────────────────────────────────────┘    │
│                                                         │
│  ┌──────────────────┐  ┌──────────────────────────┐    │
│  │  경동 MES (~27p)  │  │  주일 건설 (~48p)         │    │
│  │  생산관리         │  │  시공/프로젝트            │    │
│  │  품질관리         │  │  입찰/계약                │    │
│  └──────────────────┘  │  기성관리                 │    │
│                         └──────────────────────────┘    │
│  ┌──────────────────┐                                   │
│  │  옵션 모듈        │                                   │
│  │  차량관리         │                                   │
│  └──────────────────┘                                   │
└─────────────────────────────────────────────────────────┘

---

2. 테넌트 구조

현재 3개 테넌트가 운영됩니다.

테넌트	업종	전용 모듈	특징
경동	셔터 제조 (MES)	생산, 품질	작업지시/실적, 설비관리, QMS
주일	건설 시공	건설/프로젝트	현장관리, 입찰, 기성
(신규)	일반	공통만	공통 ERP 기능만 사용

테넌트별 접근 제어

로그인 → 백엔드가 해당 테넌트의 메뉴 목록 반환
       → PermissionGate가 화이트리스트로 접근 제어
       → 메뉴에 없는 페이지 = 접근 불가 (URL 직접 입력도 차단)

경동 유저: 회계, 영업, 생산, 품질 등 접근 가능 / 건설 차단
주일 유저: 회계, 영업, 건설 등 접근 가능 / 생산, 품질 차단

상세: v1/12-permission-whitelist.md

---

3. 기술 스택

영역	기술
프레임워크	Next.js 15 (App Router)
런타임	React 19
언어	TypeScript (strict)
UI	shadcn/ui (Radix UI) + Tailwind CSS 4
상태관리	Zustand
폼	react-hook-form + Zod
백엔드	PHP Laravel 12 (별도 프로젝트)
모바일	Capacitor (하이브리드 앱)

핵심 제약

• 모든 페이지 Client Component: 'use client' 필수 (HttpOnly 쿠키 인증 때문)
• Server Component 사용 금지: SEO 불필요 + 쿠키 수정 불가
• API 호출은 반드시 프록시: /api/proxy/ 또는 Server Action 경유

---

4. 프로젝트 구조

sam_project/
├── sam-next/sam-react-prod/    ← 프론트엔드 (현재 프로젝트)
├── sam-api/sam-api/            ← 백엔드 (PHP Laravel)
├── sam-design/sam-design/      ← 디자인 시스템
└── sam-docs/                   ← 프로젝트 문서

프론트엔드 디렉토리

src/
├── app/[locale]/(protected)/   # 라우트 (도메인별 폴더)
│   ├── accounting/             #   회계
│   ├── sales/                  #   영업
│   ├── hr/                     #   인사
│   ├── approval/               #   결재
│   ├── production/             #   생산 (경동 전용)
│   ├── quality/                #   품질 (경동 전용)
│   ├── construction/           #   건설 (주일 전용)
│   ├── dashboard/              #   CEO 대시보드
│   └── settings/               #   설정
│
├── components/                 # 컴포넌트 (계층 구조)
│   ├── ui/                     #   atoms (shadcn/ui)
│   ├── molecules/              #   molecules (FormField, DateRangeSelector 등)
│   ├── organisms/              #   organisms (PageLayout, IntegratedListTemplateV2 등)
│   ├── templates/              #   templates (UniversalListPage 등)
│   ├── {domain}/               #   도메인별 비즈니스 컴포넌트
│   └── document-system/        #   모듈 경계 넘는 공유 컴포넌트
│
├── stores/                     # Zustand 전역 상태
├── hooks/                      # 커스텀 훅
├── lib/                        # 유틸리티, API 래퍼
├── modules/                    # 모듈 시스템 (테넌트 분리)
└── contexts/                   # React Context (Permission 등)

---

5. 전역 상태 (Zustand Stores)

스토어	역할	지속성
authStore	로그인 유저, 테넌트, 역할 정보	localStorage
menuStore	사이드바 메뉴 목록, 활성 메뉴, 접힘 상태	localStorage
permissionStore	메뉴별 권한 매트릭스 (view/create/update/delete)	메모리
masterDataStore	기준정보 캐시 (품목, 공정 등)	메모리
themeStore	테마 설정	localStorage
useUIStore	UI 상태 (사이드바 너비 등)	메모리
useItemMasterStore	품목 마스터 폼 상태	메모리
favoritesStore	즐겨찾기 메뉴	localStorage
useCalendarScheduleStore	캘린더 일정	메모리
useTableColumnStore	테이블 컬럼 설정 (표시/숨김)	localStorage

---

6. 라우팅 패턴

페이지 모드 (mode 쿼리파라미터)

/sales/order-management        → 목록 (기본)
/sales/order-management?mode=new → 등록 폼
/sales/order-management/123    → 상세 (view)
/sales/order-management/123?mode=edit → 수정 폼

• 별도 /new, /edit 경로 사용 금지
• 목록과 등록을 같은 page.tsx에서 mode로 분기

페이지 유형

유형	컴포넌트	특징
목록	UniversalListPage	검색, 페이지네이션, 컬럼 설정, 모바일 카드
상세/폼	Card + FormField	sticky 하단 액션 바, 모드별 분기
대시보드	섹션 기반	모듈별 조건부 렌더링

---

7. 도메인 맵

공통 ERP (모든 테넌트)

회계 (accounting/)
├── 매출/매입 관리
├── 입출금 관리
├── 세금계산서
├── 거래처 원장
├── 경조사비/접대비
└── 일보/결산

영업 (sales/)
├── 견적/수주 관리
├── 단가 관리
├── 생산지시 (공유 API)
└── 거래처 관리

인사 (hr/)
├── 직원 관리
├── 근태/출결
├── 급여/휴가
└── 인사 이력

결재 (approval/)
├── 기안/수신/참조
└── 결재 양식 관리

기준정보 (master-data/)
├── 품목 마스터
├── 공정 관리
└── 단가 테이블

자재/재고 (material/, stocks/)
├── 입고 관리
├── 재고 현황
└── 재고 생산

출고/배송 (outbound/)
├── 출하 관리
└── 차량 배차

경동 전용 (셔터 제조 MES)

생산 (production/)
├── 작업지시
├── 작업실적
├── 작업자 화면
└── 생산 대시보드

품질 (quality/)
├── 설비 관리/점검/수리
├── 검사 관리
├── QMS (문서관리)
└── 성적서/작업일지

주일 전용 (건설 시공)

건설 (construction/)
├── 수주/현장 관리
├── 프로젝트 관리
│   ├── 계약/실행예산
│   ├── 입찰 관리
│   ├── 시공 관리
│   └── 인력 현황
└── 기성 관리

---

8. 데이터 흐름

[컴포넌트] → Server Action (또는 fetch /api/proxy/...)
                │
                ↓
         [authenticatedFetch]
                │
                ├── 정상 → 데이터 반환
                ├── 401 → 자동 토큰 갱신 → 재시도
                └── 실패 → 로그인 페이지 이동

Server Action 위치: src/components/{domain}/actions.ts
URL 빌더: buildApiUrl('/api/v1/path', { search, page })

---

9. 모듈 분리 현황

코드 아키텍처 레벨에서 공통 ERP와 테넌트 전용 코드의 경계를 관리합니다.

단계	상태	내용
Phase 0	완료	공통 -> 테넌트 import 의존성 해소
Phase 1	완료	모듈 레지스트리 + useModules() 훅
Phase 2	완료	CEO 대시보드 모듈화 (섹션/API 최적화)
Phase 3	완료	검증 스크립트 + 경계 문서 (MODULE.md)
화이트리스트	완료	PermissionGate 화이트리스트 전환

모듈 경계 규칙

허용: 테넌트 → 공통 import (production → ui/)
금지: 공통 → 테넌트 import (approval → production/)
금지: 테넌트 간 import (production → construction/)

공유 필요 시: document-system/ 또는 lib/api/ 래퍼 경유

검증: scripts/verify-module-separation.sh

---

10. 향후 로드맵

v1 (현재) ──── 모듈 분리 완료, 권한 화이트리스트
    │
v2 (진행) ──── 백엔드에서 모듈/페이지 정보 JSON API 제공
    │            useModules() 내부를 API 호출로 교체
    │
v3 (목표) ──── JSON 스키마 기반 동적 페이지 조립
                 테넌트 추가 = 어드민 설정만 → 코드 변경 0줄

상세: v2/01-dynamic-multi-tenant-page-system.md

---

11. 문서 읽기 순서

첫째 날: 전체 구조 파악

순서	문서	핵심
1	이 문서 (00-onboarding)	시스템 전체 그림
2	01-architecture	기술 스택, 디렉토리 구조
3	07-auth-flow	인증/토큰 흐름
4	12-permission-whitelist	접근 제어

둘째 날: 개발 패턴 익히기

순서	문서	핵심
5	02-api-pattern	API 호출 방법
6	03-component-design	컴포넌트 계층
7	04-common-components	UniversalListPage 등 사용법
8	05-form-pattern	폼 패턴 (Zod, FormField)

셋째 날: 세부 규칙

순서	문서	핵심
9	06-styling-guide	Tailwind, 색상
10	08-dashboard-system	대시보드 아키텍처
11	09-conventions	네이밍, Git 규칙

---

12. Git 브랜치 전략

main ────── 배포용 (검증된 것만, 기능별 squash merge)
  │
develop ─── 평소 작업 (자유롭게 커밋)
  │
feature/* ─ 큰 기능/실험적 작업 시 사용

• develop에서 자유롭게 작업
• main에는 기능별 squash merge (cherry-pick + 정리)
• main 직접 push 금지

---

13. 개발 환경 셋업

# 1. 의존성 설치
npm install

# 2. 환경변수 (.env.local)
# 팀원에게 받거나 sam-docs 참고

# 3. 개발 서버
npm run dev

# 4. 접속
http://localhost:3000

주요 명령어

명령어	용도
npm run dev	개발 서버
npm run build	프로덕션 빌드
npx tsc --noEmit	타입 체크

---

14. 자주 하는 실수

실수	올바른 방법
Server Component 사용	'use client' 필수
localStorage 직접 접근	typeof window 가드 필요
API 직접 fetch	Server Action 또는 /api/proxy/ 사용
/new, /edit 라우트 생성	?mode=new, ?mode=edit 쿼리 사용
DatePicker 2개 직접 조합	DateRangeSelector 사용
Label + Input 수동 조합	FormField molecule 사용
공통에서 테넌트 코드 import	document-system/ 래퍼 경유