# 🎨 SAM MES 아토믹 디자인 시스템 요약

## 📋 개요

SAM MES의 모든 화면은 **아토믹 디자인 시스템**을 기반으로 구축되어 있으며, 재사용 가능한 73개 이상의 공통 컴포넌트로 구성되어 있습니다.

## 🏗️ 구조

### 1. Atoms (원자)
**위치**: `/components/ui/`

가장 기본적인 UI 요소들 (ShadCN 기반)

- Button, Input, Label
- Select, Checkbox, Radio
- Table, Card, Badge
- Dialog, Sheet, Tabs
- 등 43개 컴포넌트

### 2. Molecules (분자)
**위치**: `/components/molecules/`

여러 원자를 조합한 작은 단위 컴포넌트

- SearchBox
- FilterPanel
- ActionButtons
- FormField
- DataRow

### 3. Organisms (유기체)
**위치**: `/components/organisms/`

분자들을 조합한 복잡한 UI 블록

#### 페이지 구성 요소
- `PageLayout` - 전체 페이지 레이아웃
- `PageHeader` - 페이지 상단 헤더 (제목, 설명, 아이콘, 액션)
- `StatCards` - 통계 카드 그리드 (4개 카드)
- `SearchFilter` - 검색 및 필터 영역
- `DataTable` - 데이터 테이블 (정렬, 페이지네이션 지원)
- `EmptyState` - 빈 상태 화면
- `MobileCard` - 모바일 반응형 카드

#### 액션 컴포넌트
- `FormActions` - 폼 하단 액션 (저장, 취소)
- `DetailViewActions` - 상세보기 액션 (수정, 삭제, 뒤로)
- `ListActions` - 목록 액션 (필터, 정렬, 내보내기)
- `TableActionButtons` - 테이블 행 액션 버튼

#### 기타
- `DetailSection` - 상세 정보 섹션
- `FormSection` - 폼 섹션
- `TabViewContainer` - 탭 컨테이너
- `ScreenVersionHistory` - 화면 버전 이력

### 4. Templates (템플릿)
**위치**: `/components/templates/`

페이지 전체 구조를 정의하는 템플릿

#### 기본 템플릿
- `ListPageTemplate` - 목록 페이지
- `FormPageTemplate` - 폼 페이지
- `DetailViewTemplate` - 상세보기 페이지
- `DashboardTemplate` - 대시보드 페이지
- `TabbedPageTemplate` - 탭 기반 페이지

#### **✨ NEW: CRUDPageTemplate**
**품목관리 패턴 기반 범용 CRUD 템플릿**

모든 관리 화면(품목관리, 거래처관리, 현장관리 등)에 적용 가능한 표준 템플릿

**지원 기능:**
- ✅ 목록 → 등록 → 수정 → 상세보기 플로우
- ✅ 검색, 필터링, 통계 카드
- ✅ 폼 검증, 에러 처리
- ✅ 모바일 반응형 (테이블 → 카드)
- ✅ 커스텀 액션, 탭 구성
- ✅ 페이지네이션

## 📐 표준 페이지 포맷

모든 페이지는 다음 순서를 따릅니다:

```
1. 제목 + 서브제목 + 아이콘
2. 대시보드 통계 4개 (StatCards)
3. 검색/필터 (SearchFilter)
4. 컨텐츠 (DataTable / Form / Detail)
```

### 목록 페이지 구조

```tsx
<PageLayout>
  <PageHeader 
    title="품목관리"
    description="제품, 부품, 원자재 관리"
    icon={Package}
    actions={<Button>새로 만들기</Button>}
  />
  
  <StatCards stats={[
    { label: "전체 품목", value: 150, icon: Package },
    { label: "제품", value: 45, icon: Box },
    { label: "부품", value: 80, icon: Wrench },
    { label: "원자재", value: 25, icon: Archive },
  ]} />
  
  <SearchFilter 
    searchValue={searchTerm}
    onSearchChange={setSearchTerm}
    searchPlaceholder="품목코드, 품목명으로 검색..."
  />
  
  <DataTable 
    columns={columns}
    data={filteredData}
    keyField="id"
  />
</PageLayout>
```

## 🎯 CRUDPageTemplate 사용법

### 기본 사용

```tsx
import { CRUDPageTemplate } from "./templates/CRUDPageTemplate";
import { useData } from "./contexts/DataContext";

export function ItemManagement() {
  const { itemMasters, addItemMaster, updateItemMaster, deleteItemMaster } = useData();
  
  const columns = [
    { key: "itemCode", label: "품목코드" },
    { key: "itemName", label: "품목명" },
    { key: "itemType", label: "품목유형" },
  ];
  
  const renderForm = (data, onChange) => (
    <div className="space-y-4">
      <div>
        <Label>품목코드</Label>
        <Input 
          value={data.itemCode || ""} 
          onChange={(e) => onChange("itemCode", e.target.value)} 
        />
      </div>
      <div>
        <Label>품목명</Label>
        <Input 
          value={data.itemName || ""} 
          onChange={(e) => onChange("itemName", e.target.value)} 
        />
      </div>
    </div>
  );
  
  return (
    <CRUDPageTemplate
      title="품목관리"
      description="제품, 부품, 원자재 등록 및 관리"
      icon={Package}
      data={itemMasters}
      columns={columns}
      renderForm={renderForm}
      onCreate={addItemMaster}
      onUpdate={updateItemMaster}
      onDelete={deleteItemMaster}
    />
  );
}
```

### 고급 사용 (통계, 검색, 검증 포함)

```tsx
<CRUDPageTemplate
  title="거래처 관리"
  icon={Building2}
  data={clients}
  columns={columns}
  
  // 통계
  stats={[
    { label: "전체", value: clients.length, icon: Building2 },
    { label: "매출", value: salesCount, icon: TrendingUp },
  ]}
  
  // 검색
  searchPlaceholder="거래처명, 코드로 검색..."
  searchFields={["name", "code", "representative"]}
  
  // 폼
  renderForm={renderForm}
  validateForm={(data) => {
    const errors = {};
    if (!data.name) errors.name = "필수입니다";
    return Object.keys(errors).length > 0 ? errors : null;
  }}
  
  // 상세보기 탭
  detailTabs={[
    { id: "basic", label: "기본정보", render: (item) => <BasicInfo item={item} /> },
    { id: "history", label: "이력", render: (item) => <History item={item} /> },
  ]}
  
  // 액션
  onCreate={handleCreate}
  onUpdate={handleUpdate}
  onDelete={handleDelete}
/>
```

## 📦 적용 가능한 페이지

### ✅ 적용 완료
- 품목관리 (ItemManagement) - **기준 페이지**
- 견적관리 (QuoteManagement)

### 🎯 적용 예정

#### 생산관리
- 모델관리 (ModelManagement)
- 공정관리 (ProcessManagement)
- BOM관리 (BOMManagement)
- 생산지시 (ProductionOrder)

#### 영업/판매
- 거래처관리 (ClientManagement)
- 현장관리 (SiteManagement)
- 수주관리 (OrderManagement)
- 출하관리 (ShippingManagement)

#### 구매/자재
- 공급업체관리 (SupplierManagement)
- 구매품목관리 (PurchaseItemManagement)
- 입고관리 (ReceivingManagement)
- 재고관리 (InventoryManagement)

#### 품질관리
- 검사기준관리 (InspectionStandardManagement)
- 입고검사 (IncomingInspection)
- 공정검사 (ProcessInspection)
- 최종검사 (FinalInspection)

#### 시스템 관리
- 사용자관리 (UserManagement)
- 부서관리 (DepartmentManagement)
- 권한관리 (RoleManagement)
- 코드관리 (CodeManagement)

## 🔧 마이그레이션 가이드

기존 페이지를 CRUDPageTemplate으로 변환하는 방법:

### 1단계: 데이터 준비
```tsx
const { items, addItem, updateItem, deleteItem } = useData();
```

### 2단계: 컬럼 정의
```tsx
const columns: Column<Item>[] = [
  { key: "code", label: "코드" },
  { key: "name", label: "이름" },
];
```

### 3단계: 폼 렌더링
```tsx
const renderForm = (data, onChange, errors) => (
  <div>
    <Label>이름</Label>
    <Input value={data.name || ""} onChange={(e) => onChange("name", e.target.value)} />
    {errors?.name && <p className="text-red-600">{errors.name}</p>}
  </div>
);
```

### 4단계: 템플릿 적용
```tsx
return (
  <CRUDPageTemplate
    title="항목 관리"
    data={items}
    columns={columns}
    renderForm={renderForm}
    onCreate={addItem}
    onUpdate={updateItem}
    onDelete={deleteItem}
  />
);
```

## 📚 참고 문서

- `/components/templates/CRUDPageTemplate.tsx` - 템플릿 소스코드
- `/components/templates/CRUDPageTemplate.guide.md` - 상세 사용 가이드
- `/components/examples/ClientManagementExample.tsx` - 완전한 구현 예시

## 🎨 디자인 토큰

모든 스타일은 `/styles/globals.css`에 정의된 토큰을 사용합니다:

- 색상: `--primary`, `--secondary`, `--accent`
- 간격: `--spacing-xs`, `--spacing-sm`, `--spacing-md`
- 타이포그래피: 자동 적용 (font-size, font-weight 클래스 사용 금지)

## ✨ Best Practices

### DO ✅
- 아토믹 디자인 시스템 컴포넌트 사용
- CRUDPageTemplate으로 표준 CRUD 페이지 구현
- 검색 필드는 `searchFields` prop으로 지정
- 폼 검증은 `validateForm` 함수로 처리
- 모바일 카드는 `renderMobileCard`로 커스터마이즈

### DON'T ❌
- Tailwind의 `text-2xl`, `font-bold` 같은 타이포그래피 클래스 사용 금지
- 직접 `<table>` 태그 사용 금지 → `DataTable` 사용
- 페이지마다 다른 레이아웃 구조 사용 금지
- 검색/필터 UI 직접 구현 금지 → `SearchFilter` 사용

## 🔄 데이터 관리

### 중앙 집중식 데이터 관리
**위치**: `/components/contexts/DataContext.tsx`

모든 데이터는 DataContext에서 관리되며 localStorage에 영속화됩니다.

```tsx
const {
  itemMasters,        // 품목 데이터
  addItemMaster,      // 품목 추가
  updateItemMaster,   // 품목 수정
  deleteItemMaster,   // 품목 삭제
  
  clients,           // 거래처 데이터
  addClient,         // 거래처 추가
  updateClient,      // 거래처 수정
  deleteClient,      // 거래처 삭제
  
  // ... 기타 데이터
} = useData();
```

### 데이터 타입 안전성

모든 데이터는 TypeScript 인터페이스로 타입이 정의되어 있습니다:

```tsx
interface ItemMaster {
  id: string;
  itemCode: string;
  itemName: string;
  itemType: 'FG' | 'PT' | 'SM' | 'RM' | 'CS';
  unit: string;
  // ... 기타 필드
}
```

## 📊 통계

- **총 컴포넌트**: 73개 이상
- **Atoms (UI)**: 43개
- **Organisms**: 15개
- **Templates**: 6개
- **적용된 페이지**: 2개 (품목관리, 견적관리)
- **적용 예정 페이지**: 20개 이상

## 🚀 다음 단계

1. **모든 관리 페이지를 CRUDPageTemplate으로 전환**
   - 우선순위: 거래처관리, 현장관리, 사용자관리
   
2. **고급 기능 추가**
   - 엑셀 내보내기/가져오기
   - 일괄 작업 (선택 삭제, 선택 수정)
   - 고급 필터링
   
3. **성능 최적화**
   - 대용량 데이터 가상 스크롤링
   - 검색 debounce
   - 메모이제이션

## 💡 문의

디자인 시스템 관련 문의사항이나 개선 제안은 개발팀에 문의해주세요.
