---
source: mes_react/src/ATOMIC_DESIGN_SYSTEM.md
section: React 아키텍처 분석
created: 2025-11-12
bp_mes_phase: Phase A - Step A.1
related:
  - react_dev_guidelines_summary.md
  - react_screen_spec_summary.md
  - api_item_analysis_summary.md
tags: [react, atomic-design, components, architecture]
---

# React Atomic Design 시스템 요약 (v2.0)

**분석일:** 2025-11-12
**원본 문서:** 1,548줄 (mes_react/src/ATOMIC_DESIGN_SYSTEM.md)
**핵심 발견:** Atomic Design 기반 컴포넌트 재구성 계획, 중복 컴포넌트 통합 전략

---

## Executive Summary

### 🎯 주요 목표

**Atomic Design 시스템 도입으로 재사용성과 유지보수성 향상:**
- 기존 30+ 페이지 컴포넌트를 체계적으로 재구성
- shadcn/ui 53개 컴포넌트를 Atoms로 활용
- 중복 컴포넌트 85% 감소 (BOM 3개→1개, Quote 3개→1개 등)
- 코드 재사용성 향상으로 개발 속도 50% 증가 예상

**계층 구조:**
```
Atoms (원자) - 기본 UI 요소 (shadcn/ui 53개)
  ↓
Molecules (분자) - 2개 이상 Atoms 조합 (SearchBar, StatCard, FormField 등)
  ↓
Organisms (유기체) - 복잡한 조합 (PageHeader, DataTable, FormSection 등)
  ↓
Templates (템플릿) - 페이지 레이아웃 (List, Form, Dashboard, Tabbed)
  ↓
Pages (페이지) - 실제 데이터 + 비즈니스 로직 (30+ 컴포넌트)
```

---

## 핵심 구조 및 컴포넌트

### 1. Atoms (원자) - shadcn/ui 53개

**기존 위치:** `components/ui/`
**특징:** 더 이상 분해 불가능한 기본 UI 요소

**주요 컴포넌트:**
- button.tsx, input.tsx, label.tsx, badge.tsx
- card.tsx, checkbox.tsx, select.tsx, textarea.tsx
- dialog.tsx, table.tsx, tabs.tsx
- 총 53개 shadcn/ui 컴포넌트 (수정 금지)

**추가 권장 Atoms:**
- Icon.tsx (Lucide Icons 래퍼)
- Loading.tsx (로딩 스피너)
- Avatar.tsx (이미 존재)

---

### 2. Molecules (분자) - 새로 생성

**특징:** 2개 이상의 Atoms 조합, 단순한 역할 수행

#### 2.1 SearchBar
```typescript
// Input + Icon 조합
<SearchBar
  value={searchTerm}
  onChange={setSearchTerm}
  placeholder="검색..."
/>
```

#### 2.2 StatCard (단일 통계 카드)
```typescript
<StatCard
  label="Total Users"
  value={150}
  icon={Users}
  iconColor="text-blue-600"
  trend={{ value: "+12%", isPositive: true }}
/>
```

#### 2.3 FormField (라벨 + 입력 + 에러)
```typescript
<FormField
  label="사용자명"
  value={username}
  onChange={setUsername}
  required
  error={errors.username}
/>
```

#### 2.4 FilterButton
```typescript
<FilterButton
  onClick={handleFilterClick}
  active={isFilterActive}
/>
```

#### 2.5 StatusBadge
```typescript
<StatusBadge status="진행중" />
// 상태: 대기, 진행중, 완료, 취소, 반려
```

---

### 3. Organisms (유기체) - 복잡한 조합

**기존 위치:** `components/common/`
**특징:** 독립적인 기능을 가진 복잡한 컴포넌트

#### 3.1 PageHeader (개선)
```typescript
<PageHeader
  title="품목 관리"
  description="품목 정보를 관리합니다"
  icon={Package}
  breadcrumbs={[
    { label: "Home" },
    { label: "생산관리" },
    { label: "품목관리" }
  ]}
  actions={
    <Button><Plus />추가</Button>
  }
/>
```

**구성 요소:**
- 아이콘 (모바일에서 숨김)
- 제목 + 설명
- Breadcrumbs (선택)
- 액션 버튼 영역

#### 3.2 DataTable (신규 - 공통 테이블)
```typescript
<DataTable
  columns={[
    { key: "code", label: "품목코드" },
    { key: "name", label: "품목명" },
    { key: "status", label: "상태", render: (v) => <StatusBadge status={v} /> }
  ]}
  data={items}
  keyField="id"
  onRowClick={handleRowClick}
  pagination={{
    currentPage: 1,
    totalPages: 10,
    onPageChange: setPage
  }}
/>
```

**특징:**
- 제네릭 타입으로 타입 안정성
- 커스텀 렌더러 지원
- 페이지네이션 내장
- 로딩/빈 상태 자동 처리

#### 3.3 MobileCardList (신규)
```typescript
<MobileCardList
  data={items}
  keyField="id"
  renderCard={(item) => ({
    title: item.name,
    subtitle: item.contact,
    fields: [
      { label: "코드", value: item.code },
      { label: "연락처", value: item.phone }
    ],
    actions: [
      { label: "수정", onClick: () => handleEdit(item) },
      { label: "삭제", onClick: () => handleDelete(item) }
    ]
  })}
/>
```

#### 3.4 FormSection (신규 - 접이식 섹션)
```typescript
<FormSection
  title="기본 정보"
  collapsible
  defaultOpen={true}
>
  <div className="grid grid-cols-2 gap-4">
    <FormField label="이름" value={name} onChange={setName} />
    <FormField label="이메일" value={email} onChange={setEmail} />
  </div>
</FormSection>
```

---

### 4. Templates (템플릿) - 페이지 레이아웃

**새로 생성할 Templates:**

#### 4.1 ListPageTemplate
```typescript
<ListPageTemplate
  // Header
  title="거래처 관리"
  description="거래처 정보를 관리합니다"
  icon={Building}
  actions={<Button><Plus />추가</Button>}

  // Stats
  stats={[
    { label: "전체", value: 150, icon: Building },
    { label: "활성", value: 120, icon: CheckCircle }
  ]}

  // Search & Filter
  searchValue={searchTerm}
  onSearchChange={setSearchTerm}
  filterButton
  onFilterClick={handleFilter}

  // Data
  data={customers}
  keyField="id"
  columns={[...]}
  renderMobileCard={(item) => ({...})}

  // Empty State
  emptyTitle="등록된 거래처가 없습니다"
  emptyAction={{ label: "첫 거래처 등록", onClick: handleNew }}

  // Pagination
  pagination={{...}}
/>
```

**자동 제공 기능:**
- 반응형 레이아웃 (데스크톱 테이블 / 모바일 카드)
- 검색 및 필터링
- 통계 카드
- 빈 상태 표시
- 페이지네이션

#### 4.2 FormPageTemplate
```typescript
<FormPageTemplate
  title="거래처 등록"
  icon={Building}
  sections={[
    {
      title: "기본 정보",
      content: <BasicInfoForm />
    },
    {
      title: "담당자 정보",
      collapsible: true,
      content: <ContactInfoForm />
    }
  ]}
  onSave={handleSave}
  onCancel={handleCancel}
  saving={isSaving}
/>
```

#### 4.3 DashboardTemplate
```typescript
<DashboardTemplate
  title="영업 대시보드"
  icon={Briefcase}
  stats={[
    { label: "월 매출", value: "₩1,234,567", icon: DollarSign }
  ]}
  sections={[
    {
      title: "최근 견적",
      content: <RecentQuotes />,
      span: "full"
    },
    {
      title: "매출 추이",
      content: <SalesChart />
    }
  ]}
  quickActions={[
    {
      label: "견적 작성",
      description: "새 견적서 작성",
      icon: FileText,
      onClick: handleNewQuote
    }
  ]}
/>
```

#### 4.4 TabbedPageTemplate
```typescript
<TabbedPageTemplate
  title="주문 관리"
  icon={ShoppingCart}
  actions={<Button>주문 등록</Button>}
  tabs={[
    {
      id: "orders",
      label: "주문 목록",
      icon: List,
      content: <OrderList />
    },
    {
      id: "production",
      label: "생산 현황",
      icon: Factory,
      content: <ProductionStatus />
    }
  ]}
/>
```

---

## 중복 컴포넌트 통합 계획

### 통합 대상 (85% 코드 감소)

#### 1. BOM 관리 (3개 → 1개)
**통합 전:**
- BOMManagement.tsx
- BOMManagementEnhanced.tsx
- BOMManagementPage.tsx

**통합 후:** `BOMManagement.tsx` (Enhanced 버전 기반)
**예상 효과:** 코드 70% 감소, 유지보수 비용 80% 절감

#### 2. Quote 관리 (3개 → 1개)
**통합 전:**
- QuoteManagement.tsx
- QuoteManagement3.tsx (List + Write)
- QuoteSimulation.tsx

**통합 후:** `QuoteManagement.tsx` (QuoteManagement3 기반)
**특징:** List/Write 분리, Simulation 하위 기능

#### 3. Item 관리 (5개 → 1개)
**통합 전:**
- ItemManagement.tsx (이미 PageLayout 적용 ✅)
- ItemManagementPage.tsx
- ItemManagementForm.tsx
- ItemManagementList.tsx
- ItemRegistration.tsx

**통합 후:** `ItemManagement.tsx` (현재 버전 유지)
**상태:** 이미 완성도 높음

#### 4. Inspection (3개 → 1개)
**통합 전:**
- IncomingInspection.tsx
- IncomingInspectionManagement.tsx

**통합 후:** `IncomingInspectionManagement.tsx`

#### 5. Dashboard (개선)
**대상:**
- SalesDashboard.tsx
- ProductionDashboard.tsx
- QualityDashboard.tsx
- MaterialDashboard.tsx
- PurchaseDashboard.tsx
- AccountingDashboard.tsx

**개선 방법:** `DashboardTemplate` 사용
**예상 효과:** 코드 중복 90% 제거, 패턴 통일

---

## 마이그레이션 전략 (4단계)

### Phase 1: 디렉토리 구조 재구성 (Week 1)

**작업 내용:**
1. `components/ui/` → `components/atoms/` 이동
2. `components/molecules/` 생성 및 컴포넌트 작성:
   - SearchBar
   - StatCard
   - FormField
   - FilterButton
   - StatusBadge
3. `components/common/` → `components/organisms/` 이동
4. 새로운 Organisms 추가:
   - DataTable
   - MobileCardList
   - FormSection

**산출물:** 새로운 폴더 구조 완성

---

### Phase 2: 템플릿 생성 (Week 2)

**작업 내용:**
1. `components/templates/` 폴더 생성
2. 4개 템플릿 작성:
   - ListPageTemplate
   - FormPageTemplate
   - DashboardTemplate
   - TabbedPageTemplate
3. `components/hooks/` 폴더 생성
4. Custom Hooks 작성:
   - useTableData (검색, 정렬, 필터링)
   - useFormValidation
   - usePagination
   - useSearch

**산출물:** 재사용 가능한 템플릿 및 훅

---

### Phase 3: 중복 컴포넌트 통합 (Week 3-4)

**우선순위:**
1. BOM 관리 통합
2. Quote 관리 통합
3. Item 관리 통합 (검증)
4. Inspection 관리 통합
5. Code/Lot/InspectionStandard 관리 통합

**검증 기준:**
- 기존 기능 100% 유지
- 코드 품질 개선
- 테스트 커버리지 80% 이상

---

### Phase 4: 페이지 리팩토링 (Week 5-8)

**우선순위 1: 핵심 페이지**
- CustomerManagement
- OrderManagement (✅ 완료)
- ItemManagement (✅ 완료)

**우선순위 2: 자주 사용하는 페이지**
- ReceivingManagement
- ShippingManagement
- PurchaseOrderManagement

**우선순위 3: 나머지 페이지**
- 모든 Dashboard 페이지
- 모든 Management 페이지

**체크리스트:**
- [ ] 적절한 Template 선택
- [ ] PageHeader 사용
- [ ] StatCards 사용
- [ ] DataTable/MobileCardList 사용
- [ ] 공통 molecules 사용
- [ ] Custom hooks 사용
- [ ] TypeScript 타입 정의
- [ ] 반응형 디자인 확인
- [ ] 테스트 작성

---

## Custom Hooks

### useTableData
```typescript
const {
  data,           // 정렬/필터링된 데이터
  loading,
  searchTerm,
  setSearchTerm,
  sortConfig,
  setSortConfig,
  refresh
} = useTableData(initialData);
```

**기능:**
- 검색 (모든 필드 대상)
- 정렬 (ASC/DESC)
- 데이터 새로고침

### usePagination
```typescript
const {
  currentPage,
  totalPages,
  paginatedData,  // 현재 페이지 데이터
  goToPage,
  nextPage,
  prevPage
} = usePagination(data, itemsPerPage);
```

**기능:**
- 페이지 분할
- 페이지 이동
- 총 페이지 수 계산

---

## 성능 최적화

### 1. Code Splitting (지연 로딩)
```typescript
// 페이지 단위 lazy load
const CustomerManagement = lazy(() => import("./pages/sales/CustomerManagement"));

<Suspense fallback={<LoadingSpinner />}>
  <CustomerManagement />
</Suspense>
```

### 2. Tree Shaking
```typescript
// ❌ 전체 import
import * as Icons from "lucide-react";

// ✅ 필요한 것만 import
import { User, Settings, Mail } from "lucide-react";
```

### 3. Memoization
```typescript
// 컴포넌트 memoization
export const StatCard = memo(function StatCard({ label, value }: Props) {
  // ...
});

// 값 memoization
const filteredData = useMemo(() => {
  return data.filter(item => item.status === "active");
}, [data]);

// 콜백 memoization
const handleClick = useCallback(() => {
  console.log("clicked");
}, []);
```

---

## 파일 크기 비교

### 통합 전 vs 통합 후

| 모듈 | 통합 전 | 통합 후 | 감소율 |
|------|---------|---------|--------|
| BOM 관리 | 3개 파일 (2,500줄) | 1개 파일 (850줄) | **66%** |
| Quote 관리 | 3개 파일 (2,800줄) | 1개 파일 (1,000줄) | **64%** |
| Item 관리 | 5개 파일 (3,200줄) | 1개 파일 (800줄) | **75%** |
| Dashboard | 6개 파일 (4,500줄) | 6개 파일 (1,200줄) | **73%** |
| **총계** | **17개 파일 (13,000줄)** | **9개 파일 (3,850줄)** | **70%** |

---

## 예상 효과

### 정량적 효과

| 지표 | Before | After | 개선율 |
|------|--------|-------|--------|
| 중복 컴포넌트 | 17개 | 2개 | **88% 감소** |
| 총 코드 라인 | 13,000줄 | 3,850줄 | **70% 감소** |
| 새 페이지 개발 시간 | 2일 | 4시간 | **75% 단축** |
| 유지보수 비용 | 100% | 30% | **70% 절감** |
| 컴포넌트 재사용률 | 20% | 80% | **300% 향상** |

### 정성적 효과

**✅ 개발 효율:**
- 템플릿으로 신규 페이지 개발 속도 4배 향상
- 공통 컴포넌트로 일관성 확보
- 타입 안정성으로 버그 50% 감소

**✅ 유지보수:**
- 중앙 집중식 수정으로 변경 파급효과 최소화
- 코드 리뷰 시간 60% 단축
- 온보딩 시간 70% 단축

**✅ 품질:**
- 일관된 UI/UX
- 접근성 기본 준수
- 반응형 디자인 자동 적용

---

## 롤백 계획

### Git 브랜치 전략
```
main              # 현재 안정 버전
├── develop       # 마이그레이션 진행
├── feature/atomic-design-phase1  # Phase 1
├── feature/atomic-design-phase2  # Phase 2
└── feature/atomic-design-phase3  # Phase 3
```

### 단계별 커밋
- 각 컴포넌트 통합 시 커밋
- 문제 발생 시 해당 커밋으로 롤백

### 병렬 운영
- 기존 컴포넌트 유지
- 새 컴포넌트를 _v2 suffix로 생성
- 검증 후 기존 컴포넌트 교체

---

## 핵심 원칙

### 1. 재사용성
- 모든 컴포넌트는 재사용 가능하도록 설계
- Props로 다양한 케이스 대응

### 2. 일관성
- 디자인 시스템 준수
- 명명 규칙 통일

### 3. 확장성
- 새로운 기능 추가가 쉽도록 구조화
- 컴포넌트 조합으로 복잡한 UI 구성

### 4. 유지보수성
- 코드 중복 최소화
- 명확한 책임 분리 (SRP)

### 5. 성능
- 불필요한 리렌더링 방지
- 코드 스플리팅

---

## 다음 단계

### 즉시 시작
1. Phase 1: 디렉토리 구조 재구성
2. Molecules 컴포넌트 개발
3. Organisms 컴포넌트 개발

### 단계적 진행
1. 템플릿 개발
2. Custom Hooks 개발
3. 중복 컴포넌트 통합
4. 페이지 리팩토링

### 검증 및 배포
1. 단위 테스트
2. 통합 테스트
3. E2E 테스트
4. Storybook 문서화

---

**문서 버전:** v1.0 요약본
**작성일:** 2025-11-12 (BP-MES Phase A.1)
**다음 문서:** react_dev_guidelines_summary.md