sam-react-prod/sam-docs/frontend/v1/01-project-structure.md

프로젝트 구조 및 파일 배치 규칙

디렉토리 구조

src/
├── app/                          # Next.js App Router
│   ├── [locale]/                 # i18n (ko, en, ja)
│   │   ├── (auth)/               # 인증 페이지 (로그인 등)
│   │   │   └── login/
│   │   ├── (protected)/          # 보호된 라우트 (인증 필수)
│   │   │   ├── accounting/       # 회계
│   │   │   ├── approval/         # 전자결재
│   │   │   ├── board/            # 게시판
│   │   │   ├── construction/     # 시공
│   │   │   ├── customer-center/  # 고객센터
│   │   │   ├── dashboard/        # 대시보드
│   │   │   ├── hr/               # 인사
│   │   │   ├── master-data/      # 기준정보
│   │   │   ├── material/         # 자재
│   │   │   ├── outbound/         # 출고
│   │   │   ├── production/       # 생산
│   │   │   ├── quality/          # 품질
│   │   │   ├── reports/          # 리포트
│   │   │   ├── sales/            # 영업
│   │   │   ├── settings/         # 설정
│   │   │   ├── [...slug]/        # catch-all (미구현 메뉴)
│   │   │   └── layout.tsx        # 보호 레이아웃
│   │   ├── layout.tsx            # 루트 레이아웃 (i18n)
│   │   └── page.tsx              # / → /dashboard 리다이렉트
│   └── api/                      # API Routes
│       ├── proxy/[...path]/      # HttpOnly 쿠키 프록시
│       ├── auth/                 # 인증 엔드포인트
│       └── pdf/generate/         # PDF 생성
├── components/
│   ├── ui/                       # 기본 UI 컴포넌트 (shadcn/ui 기반)
│   ├── molecules/                # 조합 컴포넌트 (FormField, StatusBadge 등)
│   ├── organisms/                # 페이지 구성 블록 (PageHeader, DataTable 등)
│   ├── templates/                # 페이지 템플릿 (IntegratedListTemplateV2 등)
│   ├── layout/                   # 레이아웃 컴포넌트 (Sidebar, Header 등)
│   └── {domain}/                 # 도메인별 컴포넌트
│       ├── accounting/
│       ├── hr/
│       ├── production/
│       ├── quality/
│       └── ...
├── hooks/                        # 공통 Hooks
├── layouts/                      # AuthenticatedLayout
├── lib/                          # 유틸리티
│   ├── api/                      # API 통신 유틸리티
│   ├── auth/                     # 인증 유틸리티
│   ├── formatters.ts             # 포맷팅 함수
│   ├── print-utils.ts            # 인쇄 유틸리티
│   └── utils.ts                  # 기본 유틸리티 (cn 등)
├── stores/                       # Zustand 스토어
├── i18n/                         # 국제화 설정
├── types/                        # 공통 타입 정의
└── styles/                       # 글로벌 스타일

컴포넌트 계층

ui/          → 원자 컴포넌트 (Button, Input, Select ...)
molecules/   → 조합 컴포넌트 (FormField = Label + Input + Error)
organisms/   → 페이지 빌딩 블록 (PageHeader, DataTable, SearchFilter ...)
templates/   → 페이지 전체 템플릿 (IntegratedListTemplateV2)
{domain}/    → 도메인 전용 컴포넌트 (AccountingForm, QualityReport ...)

파일 배치 규칙

도메인 컴포넌트

src/components/{domain}/
├── {Feature}List.tsx          # 목록 컴포넌트
├── {Feature}Detail.tsx        # 상세/수정/등록 컴포넌트
├── {Feature}Modal.tsx         # 모달 컴포넌트
└── actions.ts                 # Server Actions

페이지 파일

src/app/[locale]/(protected)/{domain}/{feature}/
├── page.tsx                   # 목록 + mode=new 분기
├── [id]/
│   └── page.tsx               # 상세 + mode=edit 분기
└── actions.ts                 # (또는 components/{domain}/actions.ts)

Server Actions 위치

• 우선: src/components/{domain}/actions.ts (도메인별)
• 대안: src/app/[locale]/(protected)/{domain}/{feature}/actions.ts (페이지별)

파일 네이밍

유형	네이밍	예시
컴포넌트	PascalCase	VendorDetail.tsx
페이지	page.tsx (Next.js 규칙)	page.tsx
Server Action	actions.ts	actions.ts
유틸리티	kebab-case	query-params.ts
Hook	camelCase + use 접두사	useColumnSettings.ts
타입	types.ts 또는 인라인	types.ts
스키마	schema.ts	schema.ts

신규 파일 생성 전 체크리스트

• 유사 컴포넌트가 이미 있는지 organisms/, molecules/ 확인
• 같은 도메인에 재사용 가능한 컴포넌트 확인
• dev/component-registry 페이지에서 검색
• 공통 UI 컴포넌트(ui/)로 해결 가능한지 확인