sam-docs/system/react-component-architecture.md

# React 컴포넌트 아키텍처 현황

> **작성일**: 2026-03-12
> **상태**: 현황 분석 완료
> **관련 문서**: [react-structure.md](react-structure.md) — 전체 프로젝트 구조

---

## 1. 개요

### 1.1 목적

SAM React 프로젝트의 컴포넌트 아키텍처 현황을 기록한다. Atomic Design 폴더 구조를 채택했으나 **실제 계층적 의존성은 부분적으로만 작동**하고 있으며, 이 문서는 현실과 이상의 차이를 정리하여 신규 화면 개발 시 올바른 패턴을 참고하도록 한다.

### 1.2 기술 스택

| 계층 | 기술 | 설명 |
|------|------|------|
| UI 프리미티브 | Radix UI (13개 패키지) | 접근성 기반 헤드리스 컴포넌트 |
| 스타일 | shadcn/ui + Tailwind CSS v4 + CVA | 프로젝트 맞춤 커스터마이징 |
| 폼 | React Hook Form + Zod | 타입 안전한 검증 |
| 상태 | Zustand 5 + Immer | 전역 상태 (persist) |
| 아이콘 | Lucide React (550+) | |
| 차트 | Recharts v3 | |
| 에디터 | Tiptap | 리치텍스트 |
| 테마 | CSS 변수 + Zustand | light / dark / senior 3종 |

---

## 2. 폴더 구조

```
src/components/
├── ui/          ← shadcn/ui 프리미티브 (60개)
│                  Button, Input, Select, Dialog, DatePicker,
│                  CurrencyInput, PhoneInput, FileDropzone 등
│
├── atoms/       ← Atomic Design 원자 (3개)
│                  BadgeSm, TabChip, ScrollableButtonGroup
│
├── molecules/   ← Atomic Design 분자 (13개)
│                  FormField, StatusBadge, MobileCard,
│                  DateRangeSelector, StandardDialog 등
│
├── organisms/   ← Atomic Design 유기체 (14개)
│                  PageLayout, PageHeader, DataTable,
│                  StatCards, EmptyState, SearchFilter 등
│
├── templates/   ← 페이지 템플릿 (5개, 2개 미사용)
│                  UniversalListPage, IntegratedDetailTemplate,
│                  IntegratedListTemplateV2
│
├── layout/      ← 전역 레이아웃
│                  Sidebar, CommandMenuSearch, HeaderFavoritesBar
│
├── business/    ← 대시보드
├── accounting/  ← 회계 도메인
├── hr/          ← 인사 도메인
├── approval/    ← 전자결재 도메인
├── items/       ← 품목 도메인
├── production/  ← 생산 도메인
├── ... (도메인별 ~600개)
│
└── common/      ← 공통 (DataTable 독립 구현)
```

---

## 3. 실제 의존성 분석

### 3.1 이상 vs 현실

```
[이상적 Atomic Design]
Page → Templates → Organisms → Molecules → Atoms → ui/

[실제 구조]
Page ──→ Templates ──────────────────────→ ui/  (직접)
     ├─→ Organisms ──────────────────────→ ui/  (직접)
     ├─→ Molecules ──────────────────────→ ui/  (직접)
     └─→ ui/ ────────────────────────────→ ui/  (직접)

계층 간 연결:
  atoms → molecules:  2/13만 사용 (17%)
  molecules → organisms:  0회 (완전 단절)
  organisms → templates:  2회만 (PageLayout, PageHeader)
```

### 3.2 Import 비율 (전체 2,186회)

| 대상 | 횟수 | 비율 | 평가 |
|------|------|------|------|
| **ui/ 직접** | 1,831회 | **83.7%** | 압도적 |
| templates | 192회 | 8.8% | 핵심 2개 템플릿 |
| organisms | 148회 | 6.8% | PageLayout/MobileCard 중심 |
| molecules | 45회 | 2.1% | FormField/StatusBadge 중심 |
| atoms | 15회 | 0.7% | 거의 미사용 |

### 3.3 계층별 ui/ 의존

| 계층 | ui/ import 횟수 | atoms/molecules/organisms import | 비고 |
|------|----------------|--------------------------------|------|
| templates | 25회+ | 4회 | ui/ 직접 의존 |
| organisms | 25회+ | 0회 | molecules 완전 미사용 |
| molecules | 28회+ | 2회 (atoms) | 대부분 ui/ 직접 |
| 도메인 코드 | 1,700회+ | ~300회 | 83% ui/ 직접 |

---

## 4. 핵심 컴포넌트 사용 현황

### 4.1 고빈도 컴포넌트 (TOP 10)

| 순위 | 컴포넌트 | 계층 | 사용 횟수 | 역할 |
|------|---------|------|---------|------|
| 1 | `FormField` | molecules | 216회 | Label + Input 통합 |
| 2 | `UniversalListPage` | templates | 214회 | 목록 페이지 전체 |
| 3 | `IntegratedDetailTemplate` | templates | 182회 | 상세/폼 페이지 전체 |
| 4 | `MobileCard` | molecules+organisms | 172+129회 | 모바일 카드 |
| 5 | `StatusBadge` | molecules | 125회 | 상태 뱃지 |
| 6 | `PageLayout` | organisms | 67회 | 페이지 래퍼 |
| 7 | `BadgeSm` | atoms | 63회 | 소형 뱃지 |
| 8 | `PageHeader` | organisms | 56회 | 페이지 헤더 |
| 9 | `ListMobileCard` | organisms | 50회 | 모바일 목록 카드 |
| 10 | `DateRangeSelector` | molecules | 45회 | 날짜 범위 필터 |

### 4.2 미사용 컴포넌트

| 컴포넌트 | 계층 | 비고 |
|---------|------|------|
| `ListPageTemplate` | templates | 0회 — `UniversalListPage`로 대체됨 |
| `ResponsiveFormTemplate` | templates | 0회 — `IntegratedDetailTemplate`로 대체됨 |

### 4.3 저사용 컴포넌트 (5회 미만)

| 컴포넌트 | 계층 | 사용 횟수 |
|---------|------|---------|
| `FormActions` | organisms | 4회 |
| `ScreenVersionHistory` | organisms | 4회 |

---

## 5. 실제 페이지 개발 패턴

### 5.1 목록 페이지 (90%+ 사용 패턴)

```tsx
// 실제 도메인 코드 패턴
import { UniversalListPage } from '@/components/templates/UniversalListPage';
import { StatusBadge } from '@/components/molecules';
import { MobileCard } from '@/components/organisms/MobileCard';
import { Button } from '@/components/ui/button';
import { Dialog } from '@/components/ui/dialog';
```

`UniversalListPage`가 내부적으로 테이블, 페이지네이션, 검색 필터, 모바일 대응을 모두 포함한다.

### 5.2 상세/폼 페이지 (90%+ 사용 패턴)

```tsx
import { IntegratedDetailTemplate } from '@/components/templates/IntegratedDetailTemplate';
import { FormField } from '@/components/molecules/FormField';
import { Input } from '@/components/ui/input';
import { Select } from '@/components/ui/select';
```

`IntegratedDetailTemplate`이 내부적으로 DetailField, DetailSection, DetailGrid, DetailActions 등 9개 하위 컴포넌트를 자체 포함한다.

### 5.3 도메인 폴더 내부 구조

```
src/components/accounting/BillManagement/
├── BillManagementClient.tsx    ← 메인 컴포넌트
├── actions.ts                  ← Server Action (API 호출)
├── types.ts                    ← TypeScript 타입
├── billConfig.ts               ← 설정, 필터 옵션
└── modals/                     ← 하위 모달 컴포넌트
```

---

## 6. ui/ 컴포넌트 목록 (shadcn/ui 기반, 60개)

### 6.1 기본 UI

| 컴포넌트 | 설명 |
|---------|------|
| `button` | 6개 variant (default/destructive/outline/secondary/ghost/link), 4개 size |
| `input` | HTML input 래퍼, aria-invalid 지원 |
| `label` | HTML label 래퍼 |
| `card` | Card/CardHeader/CardTitle/CardContent/CardFooter |
| `badge` | 5개 variant |
| `alert` | Alert/AlertTitle/AlertDescription |
| `skeleton` | 로딩 스켈레톤 |

### 6.2 폼 입력

| 컴포넌트 | 설명 |
|---------|------|
| `checkbox` | Radix UI Checkbox |
| `radio-group` | Radix UI RadioGroup |
| `select` | Radix UI Select (검색 없음) |
| `switch` | Radix UI Switch |
| `slider` | Radix UI Slider |
| `date-picker` | 날짜 선택 |
| `date-range-picker` | 날짜 범위 |
| `date-time-picker` | 날짜+시간 |
| `file-input` | 파일 선택 |
| `file-dropzone` | 드래그앤드롭 파일 |
| `image-upload` | 이미지 업로드 |
| `multi-select-combobox` | 다중 선택 콤보박스 |
| `searchable-select` | 검색 가능 셀렉트 |

### 6.3 한국형 입력 (자동 포맷팅)

| 컴포넌트 | 포맷 | 용도 |
|---------|------|------|
| `phone-input` | `010-1234-5678` | 전화번호 |
| `business-number-input` | `123-45-67890` | 사업자등록번호 |
| `personal-number-input` | `123456-7890123` | 주민번호 |
| `account-number-input` | 은행별 포맷 | 계좌번호 |
| `card-number-input` | `1234 5678 9012 3456` | 카드번호 |
| `currency-input` | `1,234,567` | 금액 (천단위) |
| `quantity-input` | 정수 | 수량 |
| `number-input` | 소수점 | 숫자 |

### 6.4 오버레이/피드백

| 컴포넌트 | 설명 |
|---------|------|
| `dialog` | Radix UI Dialog |
| `alert-dialog` | 확인/취소 다이얼로그 |
| `drawer` | Vaul 드로어 |
| `sheet` | 사이드 패널 |
| `popover` | Radix UI Popover |
| `tooltip` | Radix UI Tooltip |
| `dropdown-menu` | Radix UI DropdownMenu |
| `confirm-dialog` | 커스텀 확인 다이얼로그 |
| `command` | cmdk 커맨드 팔레트 |
| `loading-spinner` | 스피너 |
| `progress` | Radix UI Progress |
| `sonner` | 토스트 알림 |

### 6.5 레이아웃/데이터

| 컴포넌트 | 설명 |
|---------|------|
| `table` | HTML table 래퍼 |
| `tabs` | Radix UI Tabs |
| `accordion` | Radix UI Accordion |
| `collapsible` | Radix UI Collapsible |
| `scroll-area` | Radix UI ScrollArea |

---

## 7. 테마 시스템

### 7.1 3가지 테마

| 테마 | 클래스 | 특징 |
|------|--------|------|
| Light | `:root` (기본) | 밝은 배경, 표준 글자 크기 |
| Dark | `.dark` | 어두운 배경, 밝은 글자 |
| Senior | `.senior` | 큰 글자(18px), 높은 대비, 굵은 폰트 |

### 7.2 CSS 변수 체계

```css
:root {
  --primary: #3B82F6;        /* 주 색상 */
  --destructive: #EF4444;    /* 위험/삭제 */
  --background: #FAFAFA;     /* 배경 */
  --card: #FFFFFF;            /* 카드 배경 */
  --border: #E2E8F0;         /* 테두리 */
  /* 60+ 색상 변수 */
}

.dark { --background: #0F172A; --primary: #60A5FA; ... }
.senior { --font-size: 18px; --font-weight-medium: 600; ... }
```

### 7.3 Tailwind variant

```css
@variant dark (&:is(.dark *));
@variant senior (&:is(.senior *));
```

코드에서 `dark:bg-slate-800 senior:text-lg` 형태로 사용한다.

### 7.4 상태 관리

```
Zustand (themeStore) → document.documentElement.className 변경
                     → localStorage persist (새로고침 유지)
```

---

## 8. 모바일 반응형 전략

### 8.1 자동 전환

| 뷰포트 | 표시 방식 |
|--------|----------|
| 768px 이상 (md:) | `DataTable` (테이블) |
| 768px 미만 | `MobileCard` / `ListMobileCard` (카드 목록) |

### 8.2 핵심 모바일 컴포넌트

| 컴포넌트 | 용도 | 사용 횟수 |
|---------|------|---------|
| `MobileCard` (molecules) | 필터/정보 카드 | 172회 |
| `MobileCard` (organisms) | 상세 조회 카드 | 129회 |
| `ListMobileCard` | 목록 카드 | 50회 |
| `MobileFilter` | 모바일 필터 | 14회 |

### 8.3 iOS Safe Area

```css
:root {
  --safe-area-inset-top: env(safe-area-inset-top, 0px);
  --safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
}
```

Capacitor 기반 모바일 앱 대응이 포함되어 있다.

---

## 9. 폼 패턴

### 9.1 신규 폼 (권장 패턴)

```tsx
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const schema = z.object({
  name: z.string().min(1, '필수'),
  amount: z.number().min(0),
  status: z.enum(['active', 'inactive']),
});

type FormData = z.infer<typeof schema>;

export function MyForm() {
  const form = useForm<FormData>({
    resolver: zodResolver(schema),
    defaultValues: { name: '', amount: 0, status: 'active' },
  });
  return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
}
```

### 9.2 CVA 기반 variant 시스템

```tsx
import { cva } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center gap-2 rounded-md',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground',
        destructive: 'bg-destructive text-white',
        outline: 'border bg-background',
        ghost: 'hover:bg-accent',
      },
      size: {
        default: 'h-9 px-4 py-2',
        sm: 'h-8 px-3',
        lg: 'h-10 px-6',
        icon: 'size-9',
      },
    },
  }
);
```

---

## 10. 신규 화면 개발 가이드

### 10.1 목록 페이지 작성 시

```
1. UniversalListPage 사용 (목록 90%+ 커버)
2. 도메인 폴더에 actions.ts, types.ts, config.ts 분리
3. StatusBadge로 상태 표시
4. MobileCard 렌더 함수 정의 (모바일 대응)
5. 추가 UI는 ui/ 에서 직접 import
```

### 10.2 상세/폼 페이지 작성 시

```
1. IntegratedDetailTemplate 사용 (상세/폼 90%+ 커버)
2. FormField로 Label + Input 조합 (일관성)
3. Zod 스키마 정의 (검증)
4. 추가 UI는 ui/ 에서 직접 import
```

### 10.3 Import 우선순위

```
1순위: templates (UniversalListPage, IntegratedDetailTemplate)
2순위: molecules (FormField, StatusBadge, DateRangeSelector)
3순위: organisms (PageLayout, PageHeader, EmptyState)
4순위: ui/ (Button, Dialog, Input 등 프리미티브)
```

> atoms는 현재 3개뿐이므로 필요 시 ui/에서 직접 사용한다.

### 10.4 하지 말 것

```
❌ ListPageTemplate 사용 (dead code — UniversalListPage 사용)
❌ ResponsiveFormTemplate 사용 (dead code — IntegratedDetailTemplate 사용)
❌ 새 atoms 만들기 (ui/ 컴포넌트로 충분)
❌ 도메인 코드에서 다른 도메인 컴포넌트 import
```

---

## 11. 현황 평가 요약

### 11.1 잘 작동하는 부분

| 항목 | 설명 |
|------|------|
| **2개 핵심 템플릿** | `UniversalListPage`(214회) + `IntegratedDetailTemplate`(182회)가 전체 페이지의 90%+ 커버 |
| **shadcn/ui 기반 ui/** | 60개 프리미티브가 일관된 디자인 시스템 제공 |
| **고빈도 molecules** | `FormField`(216회), `StatusBadge`(125회)가 폼/상태 표시 표준화 |
| **모바일 대응** | MobileCard 기반 자동 전환 |
| **테마 시스템** | light/dark/senior 3종 CSS 변수 기반 |
| **한국형 입력** | 전화번호, 사업자번호, 계좌번호 등 자동 포맷팅 |

### 11.2 개선이 필요한 부분

| 항목 | 현상 | 영향 |
|------|------|------|
| **계층 간 의존성 붕괴** | organisms가 molecules를 0회 사용 | Atomic Design 의미 퇴색 |
| **atoms 유명무실** | 3개만 존재, ui/ 60개에 비해 극소 | 계층 존재 이유 불분명 |
| **ui/ 과의존** | 전체 import의 83.7% | 추상화 효과 없음 |
| **Dead code** | ListPageTemplate, ResponsiveFormTemplate 미사용 | 혼란 유발 |
| **index.ts 비일관** | atoms/templates는 index.ts 미사용 | import 패턴 불통일 |

### 11.3 결론

**실제 아키텍처는 "Templates + UI Components" 2계층 구조**이다.

```
실제 작동 구조:

Layer 1 — 페이지 템플릿 (2개가 전체 지배)
  ├── UniversalListPage        ← 목록 페이지
  └── IntegratedDetailTemplate ← 상세/폼 페이지

Layer 2 — UI 프리미티브 (shadcn/ui)
  └── ui/ 60개 컴포넌트       ← 모든 곳에서 직접 사용

보조 — molecules (FormField, StatusBadge 등 고빈도 유틸)
보조 — organisms (PageLayout, PageHeader, MobileCard)
```

Atomic Design 폴더명(atoms/molecules/organisms/templates)은 유지되어 있으나, 실제 개발 시에는 **templates → ui/ 직접 사용** 패턴을 따르는 것이 현실적이다.

---

## 관련 문서

- [React 프론트엔드 구조](react-structure.md) — 프로젝트 규모, 도메인, 아키텍처 패턴
- [API 서버 구조](api-structure.md) — API 서버 구조
- [MNG 관리자 패널 구조](mng-structure.md) — MNG 구조

---

**최종 업데이트**: 2026-03-12