# Component Tier 정의

> SAM 프로젝트의 컴포넌트 계층(tier) 기준 정의.
> 새 컴포넌트 작성 시 어디에 배치할지 판단하는 기준 문서.

## Tier 구조 요약

```
ui          원시 빌딩블록 (HTML 래퍼, 단일 기능)
  ↓ 조합
atoms       최소 단위 UI 조각 (ui 1~2개 조합)
  ↓ 조합
molecules   의미 있는 UI 패턴 (atoms/ui 여러 개 조합)
  ↓ 조합
organisms   페이지 섹션 단위 (molecules/atoms 조합, 레이아웃 포함)
  ↓ 사용
domain      도메인별 비즈니스 컴포넌트 (organisms/molecules 사용)
```

## Tier별 정의

### ui (원시 빌딩블록)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/ui/` |
| 역할 | HTML 요소를 감싼 최소 단위. 스타일링 + 접근성만 담당 |
| 특징 | 비즈니스 로직 없음, 범용적, Radix UI 래퍼 포함 |
| 예시 | Button, Input, Select, Badge, Dialog, DatePicker, EmptyState |
| 판단 기준 | "이 컴포넌트가 다른 프로젝트에 그대로 복사해도 동작하는가?" → Yes면 ui |

### atoms (최소 UI 조각)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/atoms/` |
| 역할 | ui 1~2개를 조합한 작은 패턴. 단일 목적 |
| 특징 | props 2~5개, 상태 관리 최소 |
| 예시 | BadgeSm, TabChip, ScrollableButtonGroup |
| 판단 기준 | "ui 하나로는 부족하지만, 독립적인 의미 단위인가?" → Yes면 atoms |

### molecules (의미 있는 UI 패턴)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/molecules/` |
| 역할 | atoms/ui 여러 개를 조합하여 하나의 기능 패턴을 구성 |
| 특징 | Label + Input + Error 같은 조합, 내부 상태 가능 |
| 예시 | FormField, StatusBadge, DateRangeSelector, StandardDialog, TableActions |
| 판단 기준 | "여러 ui/atoms의 조합이고, 재사용 가능한 패턴인가?" → Yes면 molecules |

### organisms (페이지 섹션)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/organisms/` |
| 역할 | 페이지의 독립적인 섹션. molecules/atoms를 조합하여 레이아웃 포함 |
| 특징 | 데이터 테이블, 검색 필터, 폼 섹션 등 페이지 구성 단위 |
| 예시 | DataTable, PageHeader, StatCards, FormSection, SearchableSelectionModal |
| 판단 기준 | "페이지에서 하나의 영역으로 독립 가능한가?" → Yes면 organisms |

### common (공용 페이지/레이아웃)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/common/` |
| 역할 | 에러 페이지, 권한 없음 페이지 등 전역 공통 화면 |
| 특징 | 라우터 사용, 전체 페이지 레이아웃 |
| 예시 | AccessDenied, EmptyPage, ServerErrorPage |
| 판단 기준 | "전체 화면을 차지하는 공통 페이지인가?" → Yes면 common |

### layout (레이아웃 구조)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/layout/` |
| 역할 | 앱 전체 레이아웃 골격 (사이드바, 헤더, 네비게이션) |
| 예시 | AuthenticatedLayout, Sidebar, TopNav |

### dev (개발 도구)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/dev/` |
| 역할 | 개발 환경 전용 도구 (프로덕션 미포함) |
| 예시 | DevToolbar |

### domain (도메인 비즈니스)
| 항목 | 기준 |
|------|------|
| 위치 | `src/components/{도메인명}/` (hr, sales, accounting 등) |
| 역할 | 특정 도메인의 비즈니스 로직이 포함된 컴포넌트 |
| 특징 | API 호출, 도메인 타입, 비즈니스 규칙 포함 |
| 예시 | EmployeeManagement, OrderRegistration, BillDetail |
| 판단 기준 | "특정 도메인에서만 사용되는가?" → Yes면 domain |

## 자주 혼동되는 케이스

| 상황 | 올바른 tier | 이유 |
|------|-------------|------|
| EmptyState (프리셋/variant 있음) | **ui** | 범용 빌딩블록, 비즈니스 로직 없음 |
| StatusBadge (icon/dot/색상 커스텀) | **molecules** | Badge + BadgeSm 조합, DataTable 연동 |
| ConfirmDialog (삭제/저장 확인) | **ui** | AlertDialog 래퍼, 범용적 |
| StandardDialog (범용 컨테이너) | **molecules** | Dialog + Header + Footer 조합 패턴 |
| DataTable (정렬/페이지네이션/선택) | **organisms** | 페이지 섹션 단위, 다수 하위 컴포넌트 |
| SearchableSelectionModal | **organisms** | 검색+선택 완결 기능, 독립 섹션 |

## 중복 방지 규칙

1. **새 컴포넌트 작성 전**: 같은 이름/기능이 다른 tier에 이미 있는지 확인
2. **ui에 이미 있으면**: molecules/organisms에 동일 컴포넌트 만들지 않음. 필요하면 ui를 확장
3. **re-export 허용**: organisms/index.ts에서 ui 컴포넌트를 re-export 가능 (편의성)
4. **확인(Confirm) 다이얼로그**: `ui/confirm-dialog.tsx` 하나만 사용 (52개 파일 사용 중)

## StatusBadge 역할 구분

이름이 같지만 tier와 용도가 다른 두 컴포넌트. **둘 다 유지**.

### `ui/status-badge.tsx` — 범용 상태 배지

| 항목 | 내용 |
|------|------|
| import | `import { StatusBadge } from '@/components/ui/status-badge'` |
| 용도 | `createStatusConfig`와 연동하는 **config 기반** 상태 표시 |
| API | `children` 또는 `status + config` 자동 라벨/스타일 |
| 특화 기능 | `mode` (badge/text), `ConfiguredStatusBadge` 제네릭 |
| 사용 예시 | 템플릿/유틸과 연동하는 범용 상태 표시 |

```tsx
// config 기반 사용
<StatusBadge status="pending" config={APPROVAL_STATUS_CONFIG} />

// children 기반 사용
<StatusBadge variant="success">완료</StatusBadge>
```

### `molecules/StatusBadge.tsx` — DataTable 특화 배지

| 항목 | 내용 |
|------|------|
| import | `import { StatusBadge } from '@/components/molecules/StatusBadge'` |
| 용도 | DataTable 셀에서 상태를 **아이콘/도트와 함께** 표시 |
| API | `label` 필수, `variant`로 색상 지정 |
| 특화 기능 | `icon` (LucideIcon), `showDot`, 커스텀 `bgColor/textColor/borderColor` |
| 기반 | Badge + BadgeSm 조합 (size="sm"일 때 BadgeSm으로 자동 전환) |

```tsx
// DataTable 셀 렌더링
<StatusBadge label="승인완료" variant="success" showDot />
<StatusBadge label="긴급" variant="danger" icon={AlertCircle} />
```

### 선택 기준

| 상황 | 사용할 컴포넌트 |
|------|----------------|
| `createStatusConfig` 결과와 연동 | **ui** StatusBadge |
| DataTable 컬럼 셀 렌더링 | **molecules** StatusBadge |
| 아이콘이나 도트가 필요한 배지 | **molecules** StatusBadge |
| 단순 텍스트 상태 표시 (badge/text 모드) | **ui** StatusBadge |
