8f939d3609
- _index.md: 문서 목록 및 버전 관리 - 01~09: 아키텍처, API패턴, 컴포넌트, 폼, 스타일, 인증, 대시보드, 컨벤션 - 10: 문서 API 연동 스펙 (api-specs에서 이관) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
141 lines
5.3 KiB
Markdown
141 lines
5.3 KiB
Markdown
# 01. 프로젝트 아키텍처
|
|
|
|
> **대상**: 프론트엔드/백엔드/기획자
|
|
> **버전**: 1.0.0
|
|
> **최종 수정**: 2026-03-09
|
|
|
|
---
|
|
|
|
## 1. 기술 스택
|
|
|
|
| 영역 | 기술 | 버전 |
|
|
|------|------|------|
|
|
| 프레임워크 | Next.js (App Router) | 15.x |
|
|
| 런타임 | React | 19.x |
|
|
| 언어 | TypeScript | strict mode |
|
|
| UI 컴포넌트 | shadcn/ui (Radix UI 기반) | - |
|
|
| 스타일링 | Tailwind CSS | 4.x |
|
|
| 폼 관리 | react-hook-form + Zod | - |
|
|
| 상태관리 | React hooks (useState/useCallback/useMemo) | - |
|
|
| 토스트/알림 | sonner | - |
|
|
| 국제화 | next-intl | - |
|
|
| 모바일 | Capacitor (하이브리드 앱) | - |
|
|
| 백엔드 API | PHP Laravel (별도 프로젝트) | 12.x |
|
|
|
|
---
|
|
|
|
## 2. 프로젝트 특성
|
|
|
|
- **폐쇄형 ERP 시스템**: 인증 필수, SEO 불필요, 오히려 노출 방지
|
|
- **모든 페이지 Client Component**: `'use client'` 필수 (서버 컴포넌트 사용 금지)
|
|
- **이유**: HttpOnly 쿠키 기반 인증 → 서버 컴포넌트에서 쿠키 수정(토큰 갱신) 불가
|
|
|
|
---
|
|
|
|
## 3. 디렉토리 구조
|
|
|
|
```
|
|
src/
|
|
├── app/ # Next.js App Router
|
|
│ ├── [locale]/ # 다국어 라우팅 (ko, en)
|
|
│ │ ├── (protected)/ # 인증 필수 영역
|
|
│ │ │ ├── layout.tsx # AuthenticatedLayout (사이드바/헤더)
|
|
│ │ │ ├── accounting/ # 회계 도메인
|
|
│ │ │ ├── hr/ # 인사 도메인
|
|
│ │ │ ├── production/ # 생산 도메인
|
|
│ │ │ ├── orders/ # 영업/주문 도메인
|
|
│ │ │ ├── business/ # 경영/대시보드
|
|
│ │ │ └── dev/ # 개발 도구 (운영 비활성)
|
|
│ │ └── (auth)/ # 비인증 영역 (로그인 등)
|
|
│ └── api/
|
|
│ └── proxy/[...path]/ # API 프록시 (HttpOnly 쿠키 처리)
|
|
│
|
|
├── components/
|
|
│ ├── atoms/ # 최소 단위 (ScrollableButtonGroup 등)
|
|
│ ├── molecules/ # 조합 단위 (FormField 등)
|
|
│ ├── organisms/ # 페이지 구성 블록 (PageHeader, DataTable 등)
|
|
│ ├── templates/ # 페이지 레이아웃 틀
|
|
│ │ ├── UniversalListPage/ # 리스트 페이지 템플릿 (59+ 페이지 사용)
|
|
│ │ └── IntegratedDetailTemplate/ # 상세/폼 페이지 템플릿
|
|
│ ├── ui/ # shadcn/ui 기본 컴포넌트
|
|
│ └── {domain}/ # 도메인별 비즈니스 컴포넌트
|
|
│ ├── accounting/ # 회계 (입금, 출금, 전표 등)
|
|
│ ├── hr/ # 인사
|
|
│ ├── production/ # 생산
|
|
│ ├── orders/ # 영업
|
|
│ └── business/ # CEO 대시보드 등
|
|
│
|
|
├── hooks/ # 커스텀 훅
|
|
├── lib/
|
|
│ ├── api/ # API 통신 유틸리티 (핵심)
|
|
│ ├── utils/ # 범용 유틸리티
|
|
│ └── dashboard-invalidation.ts # 대시보드 갱신 시스템
|
|
│
|
|
├── middleware.ts # 인증/보안/봇 차단 미들웨어
|
|
└── types/ # 전역 타입 정의
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 컴포넌트 계층 구조
|
|
|
|
```
|
|
atoms → molecules → organisms → templates → pages
|
|
```
|
|
|
|
| 계층 | 역할 | 예시 |
|
|
|------|------|------|
|
|
| **atoms** | HTML 확장, 단일 기능 | ScrollableButtonGroup, PhoneInput |
|
|
| **molecules** | atom 조합, 재사용 폼 필드 | FormField (Label+Input 통합) |
|
|
| **organisms** | 페이지 구성 블록 | PageHeader, DataTable, SearchableSelectionModal |
|
|
| **templates** | 페이지 뼈대 (config 기반) | UniversalListPage, IntegratedDetailTemplate |
|
|
| **pages** | app/ 라우트 + 도메인 컴포넌트 | page.tsx → {Domain}Component |
|
|
|
|
---
|
|
|
|
## 5. 데이터 흐름
|
|
|
|
```
|
|
[사용자 액션]
|
|
↓
|
|
[컴포넌트] → useCallback/useState
|
|
↓
|
|
[Server Action] ('use server')
|
|
↓
|
|
[executeServerAction / executePaginatedAction]
|
|
↓
|
|
[serverFetch → authenticatedFetch]
|
|
↓
|
|
[/api/proxy/...path] (Next.js API Route)
|
|
↓
|
|
[PHP Laravel Backend /api/v1/...]
|
|
```
|
|
|
|
- 컴포넌트에서 직접 `fetch()` 금지
|
|
- 모든 데이터 요청은 Server Action → API 프록시 → 백엔드 경로
|
|
- 인증 토큰은 HttpOnly 쿠키에 저장, 프록시에서 자동 주입
|
|
|
|
---
|
|
|
|
## 6. 관련 프로젝트
|
|
|
|
| 프로젝트 | 경로 | 역할 |
|
|
|---------|------|------|
|
|
| sam-react-prod | sam-next/sma-next-project/sam-react-prod | Next.js 프론트엔드 (현재) |
|
|
| sam-api | sam-api/sam-api | PHP Laravel 백엔드 API |
|
|
| sam-design | sam-design/sam-design | React 디자인 시스템 (레거시) |
|
|
| sam-docs | sam-docs | 프로젝트 문서 (현재 문서) |
|
|
|
|
---
|
|
|
|
## 7. 주요 설계 결정
|
|
|
|
| 결정 | 이유 |
|
|
|------|------|
|
|
| Client Component Only | 폐쇄형 ERP, 쿠키 수정 필요 |
|
|
| API Proxy Pattern | HttpOnly 쿠키 보안 유지 |
|
|
| Config-Driven Templates | 59+ 리스트 페이지 일관성 |
|
|
| Server Actions | 타입 안전 + 쿠키 접근 가능 |
|
|
| Tailwind + shadcn/ui | 빠른 개발 + 일관된 디자인 |
|
|
| Zod (신규 폼만) | 기존 폼 안정성 유지하면서 점진 적용 |
|