sam-react-prod/claudedocs/architecture/[GUIDE] component-tier-definition.md

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 제네릭
사용 예시	템플릿/유틸과 연동하는 범용 상태 표시

// 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으로 자동 전환)

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

선택 기준

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