SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
85bc6e2f08bbc6e71d522ad0e06fc8fbc7e78b3d
sam-docs/frontend/v1/00-onboarding.md
유병철 a05ef0b0a8 docs: 온보딩 가이드 + 권한 화이트리스트 문서 추가 
- 00-onboarding: 신규 합류자 가이드 (시스템 개요, 도메인 맵, 읽기 순서)
- 12-permission-whitelist: PermissionGate 화이트리스트 접근 제어
- _index.md: 문서 목록 업데이트
- v2/01: 관련 문서 참조 추가

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 14:33:21 +09:00

386 lines
13 KiB
Markdown
Raw Blame History

# 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](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](../v2/01-dynamic-multi-tenant-page-system.md)
---
## 11. 문서 읽기 순서
### 첫째 날: 전체 구조 파악
| 순서 | 문서 | 핵심 |
|------|------|------|
| 1 | 이 문서 (00-onboarding) | 시스템 전체 그림 |
| 2 | [01-architecture](01-architecture.md) | 기술 스택, 디렉토리 구조 |
| 3 | [07-auth-flow](07-auth-flow.md) | 인증/토큰 흐름 |
| 4 | [12-permission-whitelist](12-permission-whitelist.md) | 접근 제어 |
### 둘째 날: 개발 패턴 익히기
| 순서 | 문서 | 핵심 |
|------|------|------|
| 5 | [02-api-pattern](02-api-pattern.md) | API 호출 방법 |
| 6 | [03-component-design](03-component-design.md) | 컴포넌트 계층 |
| 7 | [04-common-components](04-common-components.md) | UniversalListPage 등 사용법 |
| 8 | [05-form-pattern](05-form-pattern.md) | 폼 패턴 (Zod, FormField) |
### 셋째 날: 세부 규칙
| 순서 | 문서 | 핵심 |
|------|------|------|
| 9 | [06-styling-guide](06-styling-guide.md) | Tailwind, 색상 |
| 10 | [08-dashboard-system](08-dashboard-system.md) | 대시보드 아키텍처 |
| 11 | [09-conventions](09-conventions.md) | 네이밍, Git 규칙 |
---
## 12. Git 브랜치 전략
```
main ────── 배포용 (검증된 것만, 기능별 squash merge)
│
develop ─── 평소 작업 (자유롭게 커밋)
│
feature/* ─ 큰 기능/실험적 작업 시 사용
```
- develop에서 자유롭게 작업
- main에는 기능별 squash merge (cherry-pick + 정리)
- main 직접 push 금지
---
## 13. 개발 환경 셋업
```bash
# 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/` 래퍼 경유 |
Reference in New Issue View Git Blame Copy Permalink