# SAM MES 표준 페이지 포맷 가이드

> **작성일**: 2025년 10월 24일  
> **버전**: 1.0.0

---

## 📋 표준 페이지 구조

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

```
1️⃣ PageHeader (제목 + 서브제목 + 아이콘 + 액션버튼)
2️⃣ StatCards (대시보드 통계 카드)
3️⃣ SearchFilter / QuickActions (검색/필터/빠른 작업)
4️⃣ Main Content (테이블/차트/폼 등)
```

---

## 🎯 페이지 타입별 표준 포맷

### Type 1: 관리 페이지 (List + CRUD)

**사용 템플릿**: `ListPageTemplate`

```typescript
import { ListPageTemplate } from './templates/ListPageTemplate';
import { Building2, Plus, Download } from 'lucide-react';
import { Button } from './ui/button';

export function SupplierManagement() {
  return (
    <ListPageTemplate
      // 1️⃣ Header
      title="공급처 관리"
      description="원자재 및 부품 공급처를 관리합니다"
      icon={Building2}
      actions={
        <>
          <Button variant="outline">
            <Download className="w-4 h-4 mr-2" />
            엑셀 다운로드
          </Button>
          <Button onClick={() => setShowDialog(true)}>
            <Plus className="w-4 h-4 mr-2" />
            공급처 등록
          </Button>
        </>
      }
      
      // 2️⃣ Stats
      stats={[
        { label: "전체 공급처", value: 156, icon: Building2, iconColor: "text-blue-600" },
        { label: "활성 거래처", value: 142, icon: CheckCircle, iconColor: "text-green-600" },
        { label: "신규 (이번 달)", value: 8, icon: Plus, iconColor: "text-purple-600" },
        { label: "평균 거래액", value: "2,450만원", icon: DollarSign, iconColor: "text-orange-600" }
      ]}
      
      // 3️⃣ Search & Filter
      searchValue={searchTerm}
      onSearchChange={setSearchTerm}
      searchPlaceholder="공급처명, 대표자, 연락처 검색..."
      filterButton={true}
      onFilterClick={() => setShowFilter(true)}
      
      // 4️⃣ Data & Table
      data={filteredData}
      keyField="id"
      columns={columns}
      onRowClick={(row) => handleEdit(row)}
      renderMobileCard={(item) => ({
        title: item.name,
        subtitle: item.representative,
        icon: <Building2 className="w-5 h-5 text-blue-600" />,
        badge: { label: item.status, variant: item.status === "활성" ? "default" : "secondary" },
        fields: [
          { label: "연락처", value: item.phone },
          { label: "거래액", value: `${item.totalAmount.toLocaleString()}원` },
          { label: "등록일", value: item.createdAt }
        ],
        actions: [
          { label: "수정", onClick: () => handleEdit(item), icon: <Edit className="w-4 h-4" /> },
          { label: "삭제", onClick: () => handleDelete(item.id), icon: <Trash2 className="w-4 h-4" />, variant: "destructive" }
        ]
      })}
      
      // Empty State
      emptyIcon={Building2}
      emptyTitle="등록된 공급처가 없습니다"
      emptyDescription="새 공급처를 등록하여 시작하세요"
      emptyAction={{ label: "공급처 등록", onClick: () => setShowDialog(true) }}
    />
  );
}
```

### Type 2: Dashboard 페이지

**사용 템플릿**: `DashboardTemplate`

```typescript
import { DashboardTemplate } from './templates/DashboardTemplate';
import { TrendingUp, DollarSign, ShoppingBag, Users } from 'lucide-react';

export function SalesDashboard() {
  return (
    <DashboardTemplate
      // 1️⃣ Header
      title="영업 대시보드"
      description="영업 현황 및 실적을 한눈에 확인합니다"
      icon={TrendingUp}
      
      // 2️⃣ Stats
      stats={[
        { 
          label: "금일 매출", 
          value: "4,500만원", 
          icon: DollarSign, 
          iconColor: "text-green-600",
          trend: { value: "+12.5%", isPositive: true }
        },
        { 
          label: "월 매출", 
          value: "12.3억원", 
          icon: TrendingUp, 
          iconColor: "text-blue-600",
          trend: { value: "+8.3%", isPositive: true }
        },
        { 
          label: "진행중 계약", 
          value: 45, 
          icon: ShoppingBag, 
          iconColor: "text-purple-600" 
        },
        { 
          label: "신규 고객", 
          value: 12, 
          icon: Users, 
          iconColor: "text-orange-600" 
        }
      ]}
      
      // 3️⃣ Quick Actions (선택사항)
      quickActions={[
        {
          label: "견적서 작성",
          description: "신규 견적 생성",
          icon: FileText,
          onClick: () => navigate('/quote/new')
        },
        {
          label: "계약 관리",
          description: "진행중 계약 확인",
          icon: FileCheck,
          onClick: () => navigate('/contracts')
        }
      ]}
      
      // 4️⃣ Dashboard Sections
      sections={[
        {
          title: "월별 매출 추이",
          content: <SalesChart data={salesData} />,
          span: "full"
        },
        {
          title: "상위 거래처",
          content: <TopCustomersTable data={topCustomers} />
        },
        {
          title: "진행 현황",
          content: <StatusOverview data={statusData} />
        }
      ]}
    />
  );
}
```

### Type 3: 커스텀 관리 페이지 (템플릿 미사용)

**직접 조합**하되, 동일한 구조 유지:

```typescript
import { PageLayout } from './organisms/PageLayout';
import { PageHeader } from './organisms/PageHeader';
import { StatCards } from './organisms/StatCards';
import { SearchFilter } from './organisms/SearchFilter';

export function CustomManagement() {
  return (
    <PageLayout>
      {/* 1️⃣ Header */}
      <PageHeader
        title="페이지 제목"
        description="페이지 설명"
        icon={IconName}
        actions={<Button>액션</Button>}
      />
      
      {/* 2️⃣ Stats */}
      <StatCards stats={stats} />
      
      {/* 3️⃣ Search/Filter */}
      <SearchFilter
        searchValue={searchTerm}
        onSearchChange={setSearchTerm}
        filterButton={true}
      />
      
      {/* 4️⃣ Custom Content */}
      <Tabs defaultValue="tab1">
        <TabsList>
          <TabsTrigger value="tab1">탭1</TabsTrigger>
          <TabsTrigger value="tab2">탭2</TabsTrigger>
        </TabsList>
        <TabsContent value="tab1">
          {/* 커스텀 컨텐츠 */}
        </TabsContent>
      </Tabs>
    </PageLayout>
  );
}
```

---

## 🎨 StatCards 표준 구성

### 4개 통계 카드 (권장)

```typescript
const stats = [
  {
    label: "전체 항목",           // 총 개수
    value: 156,
    icon: IconTotal,
    iconColor: "text-blue-600"
  },
  {
    label: "활성/진행중",         // 활성 상태
    value: 142,
    icon: IconActive,
    iconColor: "text-green-600",
    trend: { value: "+12.5%", isPositive: true }
  },
  {
    label: "신규/대기",           // 대기/신규
    value: 8,
    icon: IconNew,
    iconColor: "text-purple-600"
  },
  {
    label: "금액/성과",           // 금액 또는 성과 지표
    value: "2,450만원",
    icon: IconMetric,
    iconColor: "text-orange-600"
  }
];
```

### 카테고리별 통계 예시

#### 영업관리
```typescript
[
  { label: "전체 고객", value: 245, icon: Building2, iconColor: "text-blue-600" },
  { label: "활성 거래처", value: 198, icon: CheckCircle, iconColor: "text-green-600" },
  { label: "이번 달 신규", value: 12, icon: Plus, iconColor: "text-purple-600" },
  { label: "평균 거래액", value: "3,250만원", icon: DollarSign, iconColor: "text-orange-600" }
]
```

#### 생산관리
```typescript
[
  { label: "전체 작업지시", value: 89, icon: Factory, iconColor: "text-purple-600" },
  { label: "진행중", value: 34, icon: Activity, iconColor: "text-blue-600" },
  { label: "완료", value: 52, icon: CheckCircle, iconColor: "text-green-600" },
  { label: "가동률", value: "87.5%", icon: Gauge, iconColor: "text-orange-600" }
]
```

#### 품질관리
```typescript
[
  { label: "검사 건수", value: 156, icon: ClipboardCheck, iconColor: "text-blue-600" },
  { label: "합격", value: 142, icon: CheckCircle2, iconColor: "text-green-600" },
  { label: "부적합", value: 8, icon: AlertTriangle, iconColor: "text-red-600" },
  { label: "합격률", value: "91.0%", icon: Target, iconColor: "text-purple-600" }
]
```

#### 자재/재고관리
```typescript
[
  { label: "전체 품목", value: 1234, icon: Package, iconColor: "text-orange-600" },
  { label: "재고 부족", value: 23, icon: AlertTriangle, iconColor: "text-red-600" },
  { label: "총 재고액", value: "5.2억원", icon: DollarSign, iconColor: "text-green-600" },
  { label: "회전율", value: "4.2회", icon: RotateCcw, iconColor: "text-blue-600" }
]
```

#### 구매관리
```typescript
[
  { label: "발주 건수", value: 67, icon: ShoppingCart, iconColor: "text-teal-600" },
  { label: "입고 대기", value: 12, icon: Clock, iconColor: "text-orange-600" },
  { label: "이번 달 구매액", value: "2.8억원", icon: DollarSign, iconColor: "text-green-600" },
  { label: "공급처", value: 156, icon: Building2, iconColor: "text-blue-600" }
]
```

#### 인사관리
```typescript
[
  { label: "전체 직원", value: 234, icon: Users, iconColor: "text-blue-600" },
  { label: "출근", value: 198, icon: UserCheck, iconColor: "text-green-600" },
  { label: "휴가", value: 12, icon: Calendar, iconColor: "text-orange-600" },
  { label: "신규 입사", value: 5, icon: Plus, iconColor: "text-purple-600" }
]
```

---

## 📏 레이아웃 규칙

### 1. PageHeader
- 항상 최상단 배치
- icon은 필수
- description은 선택 (권장)
- actions는 우측 정렬

### 2. StatCards
- PageHeader 바로 다음
- 최소 3개, 권장 4개
- 모바일: 1열, 태블릿: 2열, 데스크톱: 4열
- Trend는 선택사항 (전년 대비, 전월 대비 등)

### 3. SearchFilter
- StatCards 다음
- 검색, 필터, 추가 액션 포함
- 반응형 레이아웃

### 4. Main Content
- SearchFilter 다음
- DataTable (데스크톱) + MobileCard (모바일)
- 또는 커스텀 컨텐츠 (차트, 폼 등)

---

## 🎯 반응형 디자인

### 모바일 (< 768px)
```
┌─────────────────┐
│ PageHeader      │
├─────────────────┤
│ StatCard 1      │
│ StatCard 2      │
│ StatCard 3      │
│ StatCard 4      │
├─────────────────┤
│ SearchFilter    │
├─────────────────┤
│ MobileCard 1    │
│ MobileCard 2    │
│ MobileCard 3    │
└─────────────────┘
```

### 데스크톱 (≥ 768px)
```
┌─────────────────────────────────────┐
│ PageHeader                    [Act] │
├─────────────────────────────────────┤
│ Stat1 │ Stat2 │ Stat3 │ Stat4      │
├─────────────────────────────────────┤
│ Search [Filter] [Actions]           │
├─────────────────────────────────────┤
│ DataTable                           │
│ ┌───┬─────┬─────┬─────┬──────┐    │
│ │ # │ Col1│ Col2│ Col3│Action│    │
│ ├───┼─────┼─────┼─────┼──────┤    │
│ │ 1 │ ... │ ... │ ... │ ...  │    │
│ └───┴─────┴─────┴─────┴──────┘    │
└─────────────────────────────────────┘
```

---

## ✅ 체크리스트

페이지 생성/리팩토링 시 확인:

- [ ] `PageLayout`으로 감싸기
- [ ] `PageHeader` 추가 (title, description, icon 필수)
- [ ] `StatCards` 추가 (최소 3개, 권장 4개)
- [ ] `SearchFilter` 추가 (검색 기능이 있는 경우)
- [ ] 메인 컨텐츠 (DataTable 또는 커스텀)
- [ ] 모바일 대응 (`MobileCard` 또는 반응형 레이아웃)
- [ ] EmptyState 처리
- [ ] 로딩 상태 처리

---

## 📚 참고 예시 파일

### 완벽 구현 예시
1. **SupplierManagement.tsx** - ListPageTemplate 사용
2. **BOMManagement.tsx** - ListPageTemplate 사용
3. **SalesDashboard.tsx** - DashboardTemplate 사용
4. **ProductionDashboard.tsx** - DashboardTemplate 사용
5. **QualityDashboard.tsx** - DashboardTemplate 사용

### 리팩토링 대기
- InventoryManagement.tsx (커스텀 헤더 → PageHeader)
- MaterialManagement.tsx
- ReceivingManagement.tsx
- ShippingManagement.tsx

---

## 🚀 빠른 시작

### Step 1: 템플릿 선택
```bash
# 관리 페이지 (CRUD)
ListPageTemplate

# Dashboard
DashboardTemplate

# 커스텀 (직접 조합)
PageLayout + PageHeader + StatCards + Custom
```

### Step 2: 필수 Import
```typescript
import { PageLayout } from './organisms/PageLayout';
import { PageHeader } from './organisms/PageHeader';
import { StatCards } from './organisms/StatCards';
import { IconName } from 'lucide-react';
```

### Step 3: 데이터 준비
```typescript
// Stats 데이터
const stats = [/* ... */];

// 테이블 컬럼
const columns: Column<YourType>[] = [/* ... */];

// 데이터
const [data, setData] = useState<YourType[]>([]);
```

### Step 4: 렌더링
```typescript
return <ListPageTemplate {...props} />;
// 또는
return (
  <PageLayout>
    <PageHeader {...} />
    <StatCards stats={stats} />
    {/* ... */}
  </PageLayout>
);
```

---

**문서 버전**: 1.0.0  
**최종 업데이트**: 2025년 10월 24일  
**참고**: [COMMON_COMPONENTS_GUIDE.md](COMMON_COMPONENTS_GUIDE.md), [TABLE_DESIGN_SYSTEM.md](TABLE_DESIGN_SYSTEM.md)
