# React 프론트엔드 구조 현황

> **최종 갱신**: 2026-02-27
> **기술 스택**: Next.js 15 + React 19 + Tailwind v4 + Zustand 5

---

## 1. 프로젝트 규모

| 항목 | 수량 |
|------|------|
| 페이지 (page.tsx) | 249 |
| Server Actions (actions.ts) | 91 |
| 컴포넌트 (.tsx) | 612 |
| Custom Hooks | 25 |
| Zustand Stores | 13 |
| Lib/유틸리티 | 70 |
| TypeScript 타입 | 7 |
| React Context | 6 |
| i18n 언어 | 3 (ko, en, ja) |

---

## 2. 디렉토리 구조

```
src/
├── app/[locale]/
│   ├── (protected)/       인증 필요 라우트
│   │   ├── accounting/    회계 (32p)
│   │   ├── approval/      전자결재 (5p)
│   │   ├── board/         게시판 (12p)
│   │   ├── company-info/  회사정보
│   │   ├── construction/  시공 (57p)
│   │   ├── customer-center/ 고객센터 (10p)
│   │   ├── dashboard/     대시보드 (5p)
│   │   ├── hr/            인사 (16p)
│   │   ├── master-data/   기준정보 (14p)
│   │   ├── material/      자재 (6p)
│   │   ├── outbound/      출고 (7p)
│   │   ├── production/    생산 (12p)
│   │   ├── quality/       품질 (6p)
│   │   ├── reports/       리포트 (2p)
│   │   ├── sales/         영업 (20p)
│   │   ├── settings/      설정 (20p)
│   │   └── vehicle-management/ 차량 (12p)
│   ├── login/             로그인 (공개)
│   └── signup/            회원가입 (공개)
├── components/
│   ├── ui/                shadcn/ui 프리미티브 (55)
│   ├── atoms/             Atomic Design - 원자 (3)
│   ├── molecules/         Atomic Design - 분자 (11)
│   ├── organisms/         Atomic Design - 유기체 (12)
│   ├── templates/         페이지 템플릿 (13)
│   └── [domain]/          도메인별 컴포넌트 (~532)
├── hooks/                 커스텀 훅 (25)
├── stores/                Zustand 스토어 (13)
├── lib/                   유틸리티, API 레이어 (70)
├── types/                 TypeScript 타입 (7)
├── contexts/              React Context (6)
├── constants/             상수
├── i18n/                  next-intl 설정
├── layouts/               레이아웃
├── messages/              i18n JSON (ko, en, ja)
└── middleware.ts           인증 + i18n 미들웨어
```

---

## 3. 도메인별 페이지 수

| 도메인 | 페이지 | 주요 기능 |
|--------|--------|----------|
| construction | 57 | 시공관리, 계약, 인수인계, 구조검토 |
| accounting | 32 | 매입/매출, 급여, 대출, 경비 |
| sales | 20 | 견적, 수주, 납품, 입찰, 단가 |
| settings | 20 | 사용자, 권한, 메뉴, 기본설정 |
| hr | 16 | 직원, 근태, 휴가, 급여 |
| master-data | 14 | 품목, BOM, 분류 |
| board | 12 | 게시판, 공지, 자유게시판 |
| vehicle-management | 12 | 법인차량, 운행일지, 정비 |
| production | 12 | 작업지시, 공정, 검사 |
| customer-center | 10 | 거래처, 현장, 브리핑 |
| outbound | 7 | 출고, 물류 |
| quality | 6 | 수입검사, LOT, 품질 |
| material | 6 | 자재입고, 재고 |
| dashboard | 5 | 대시보드 (4종) |
| approval | 5 | 전자결재 |

---

## 4. 아키텍처 패턴

### API 연동
- **Server Actions** (`actions.ts`): 페이지와 co-located
- 공유 유틸: `executeServerAction()`, `executePaginatedAction()`, `buildApiUrl()`
- 모든 API 호출은 서버 사이드에서 실행 (클라이언트 직접 호출 없음)

### 인증
- HttpOnly 쿠키 기반 (Next.js API Route를 통한 프록시)
- `NEXT_PUBLIC_AUTH_MODE=sanctum`
- 모든 페이지 `'use client'` (Server Component 미사용)

### 상태관리
- **글로벌**: Zustand (13 stores) + Immer
- **폼**: React Hook Form + Zod
- **서버 상태**: Server Actions (SWR/React Query 미사용)

### 컴포넌트 아키텍처
- **Atomic Design** 적용: atoms → molecules → organisms → templates → pages
- **shadcn/ui** 55개 프리미티브 컴포넌트
- **도메인별 폴더**: `components/[domain]/` (~532개)

### 주요 의존성

| 패키지 | 버전 | 용도 |
|--------|------|------|
| next | 15.5.9 | 프레임워크 |
| react | 19.2.3 | UI |
| tailwindcss | 4.x | 스타일 |
| zustand | 5.0.9 | 상태관리 |
| zod | 4.1.12 | 스키마 검증 |
| react-hook-form | 7.66.0 | 폼 |
| recharts | 3.4.1 | 차트 |
| next-intl | 4.4.0 | i18n |
| @tiptap/* | - | 리치 텍스트 |
| @capacitor/core | 8.0.0 | 모바일 |

---

## 5. 빌드 설정

| 설정 | 값 |
|------|------|
| Turbopack | 활성화 |
| reactStrictMode | false (중복 API 요청 방지) |
| serverActions.bodySizeLimit | 10mb |
| Puppeteer | serverExternalPackages로 분리 |
| PostCSS | @tailwindcss/postcss (v4 방식) |
| Path Alias | `@/*` → `./src/*` |