# CRUDPageTemplate 사용 가이드

품목관리 패턴을 기반으로 한 범용 CRUD(Create, Read, Update, Delete) 페이지 템플릿입니다.

## 📋 개요

모든 관리 화면(품목관리, 거래처관리, 현장관리, 사용자관리 등)에서 공통적으로 사용되는 패턴을 템플릿화했습니다.

### 지원 기능

- ✅ **목록 화면**: 검색, 필터링, 통계, 페이지네이션
- ✅ **등록 화면**: 폼 입력, 유효성 검증
- ✅ **수정 화면**: 기존 데이터 수정
- ✅ **상세 화면**: 탭 구성 지원
- ✅ **모바일 반응형**: 테이블 → 카드 자동 전환
- ✅ **공통 액션**: 등록, 수정, 삭제, 보기

## 🎯 사용 방법

### 1. 기본 사용

```tsx
import { CRUDPageTemplate } from "./templates/CRUDPageTemplate";
import { Column } from "./organisms/DataTable";

function MyManagementPage() {
  const { items, addItem, updateItem, deleteItem } = useData();
  
  const columns: Column<Item>[] = [
    { key: "code", label: "코드" },
    { key: "name", label: "이름" },
  ];
  
  return (
    <CRUDPageTemplate
      title="항목 관리"
      data={items}
      columns={columns}
      renderForm={(data, onChange) => (
        <div>
          <Input 
            value={data.name || ""} 
            onChange={(e) => onChange("name", e.target.value)} 
          />
        </div>
      )}
      onCreate={addItem}
      onUpdate={updateItem}
      onDelete={deleteItem}
    />
  );
}
```

### 2. 검색 기능 추가

```tsx
<CRUDPageTemplate
  title="거래처 관리"
  data={clients}
  columns={columns}
  searchPlaceholder="거래처명, 코드로 검색..."
  searchFields={["name", "code", "representative"]}
  renderForm={renderForm}
  onCreate={handleCreate}
/>
```

### 3. 통계 카드 추가

```tsx
const stats = [
  {
    label: "전체",
    value: items.length,
    icon: Package,
    iconColor: "text-blue-600",
  },
  {
    label: "활성",
    value: items.filter(i => i.active).length,
    icon: CheckCircle,
    iconColor: "text-green-600",
  },
];

<CRUDPageTemplate
  title="품목 관리"
  stats={stats}
  // ... 기타 props
/>
```

### 4. 폼 검증 추가

```tsx
const validateForm = (data: Partial<Client>) => {
  const errors: Record<string, string> = {};
  
  if (!data.name?.trim()) {
    errors.name = "이름은 필수입니다";
  }
  
  if (!data.code?.trim()) {
    errors.code = "코드는 필수입니다";
  }
  
  return Object.keys(errors).length > 0 ? errors : null;
};

<CRUDPageTemplate
  validateForm={validateForm}
  // ... 기타 props
/>
```

### 5. 상세보기 탭 구성

```tsx
const detailTabs = [
  {
    id: "basic",
    label: "기본정보",
    icon: Info,
    render: (item) => <BasicInfo item={item} />,
  },
  {
    id: "history",
    label: "이력",
    icon: History,
    render: (item) => <HistoryView item={item} />,
  },
];

<CRUDPageTemplate
  detailTabs={detailTabs}
  // ... 기타 props
/>
```

### 6. 커스텀 액션 버튼

```tsx
const customActions = [
  {
    label: "엑셀 다운로드",
    icon: Download,
    onClick: handleExcelDownload,
    variant: "outline",
  },
  {
    label: "일괄 등록",
    icon: Upload,
    onClick: handleBulkUpload,
  },
];

<CRUDPageTemplate
  customActions={customActions}
  // ... 기타 props
/>
```

### 7. 모바일 카드 렌더링

```tsx
const renderMobileCard = (client: Client) => ({
  title: client.name,
  subtitle: client.code,
  icon: <Building2 className="w-4 h-4 text-blue-600" />,
  badge: {
    label: client.type,
    variant: "default",
  },
  fields: [
    { label: "대표자", value: client.representative },
    { label: "연락처", value: client.phone },
  ],
});

<CRUDPageTemplate
  renderMobileCard={renderMobileCard}
  // ... 기타 props
/>
```

## 📝 Props 레퍼런스

### 필수 Props

| Prop | 타입 | 설명 |
|------|------|------|
| `title` | `string` | 페이지 제목 |
| `data` | `T[]` | 데이터 배열 |
| `columns` | `Column<T>[]` | 테이블 컬럼 정의 |
| `renderForm` | `function` | 폼 렌더링 함수 |

### 선택 Props

| Prop | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `description` | `string` | - | 페이지 설명 |
| `icon` | `LucideIcon` | - | 페이지 아이콘 |
| `stats` | `StatCard[]` | - | 통계 카드 |
| `searchPlaceholder` | `string` | `"${title} 검색..."` | 검색 플레이스홀더 |
| `searchFields` | `(keyof T)[]` | - | 검색 대상 필드 |
| `validateForm` | `function` | - | 폼 검증 함수 |
| `getDefaultFormData` | `function` | - | 초기 폼 데이터 생성 |
| `renderDetail` | `function` | - | 상세 화면 렌더링 |
| `detailTabs` | `Tab[]` | - | 상세 화면 탭 |
| `onCreate` | `function` | - | 생성 핸들러 |
| `onUpdate` | `function` | - | 수정 핸들러 |
| `onDelete` | `function` | - | 삭제 핸들러 |
| `enableCreate` | `boolean` | `true` | 생성 기능 활성화 |
| `enableEdit` | `boolean` | `true` | 수정 기능 활성화 |
| `enableDelete` | `boolean` | `true` | 삭제 기능 활성화 |
| `enableView` | `boolean` | `true` | 상세보기 활성화 |
| `enableSearch` | `boolean` | `true` | 검색 기능 활성화 |
| `enableStats` | `boolean` | `true` | 통계 카드 활성화 |

## 🎨 화면 구성

### 목록 화면 (List View)
```
┌─────────────────────────────────────────┐
│ [제목]                    [새로 만들기] │
├─────────────────────────────────────────┤
│ 📊 통계 카드 (4개)                      │
├─────────────────────────────────────────┤
│ 🔍 검색창                                │
├─────────────────────────────────────────┤
│ 📋 데이터 테이블                         │
│   - 컬럼 헤더                            │
│   - 데이터 행                            │
│   - 액션 버튼 (보기/수정/삭제)          │
└─────────────────────────────────────────┘
```

### 등록/수정 화면 (Form View)
```
┌─────────────────────────────────────────┐
│ [제목 - 등록/수정]                      │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ 신규 등록 / 정보 수정               │ │
│ ├─────────────────────────────────────┤ │
│ │                                     │ │
│ │  [커스텀 폼 영역]                   │ │
│ │                                     │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│              [취소] [저장/등록]         │
└─────────────────────────────────────────┘
```

### 상세 화면 (Detail View)
```
┌─────────────────────────────────────────┐
│ [제목 - 상세]                           │
├─────────────────────────────────────────┤
│ [기본정보] [이력] [첨부파일]            │
│ ┌─────────────────────────────────────┐ │
│ │                                     │ │
│ │  [선택된 탭 내용]                   │ │
│ │                                     │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│         [뒤로] [수정] [삭제]            │
└─────────────────────────────────────────┘
```

## 🔧 적용 가능한 페이지

이 템플릿은 다음과 같은 페이지에 적용할 수 있습니다:

### 생산관리
- ✅ 품목관리 (ItemManagement)
- ✅ 모델관리 (ModelManagement)
- ✅ 공정관리 (ProcessManagement)
- ✅ BOM관리 (BOMManagement)

### 영업/판매
- ✅ 거래처관리 (ClientManagement)
- ✅ 현장관리 (SiteManagement)
- ✅ 견적관리 (QuoteManagement)
- ✅ 수주관리 (OrderManagement)

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

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

## 💡 Best Practices

### 1. 컬럼 정의 시
- 중요한 정보는 앞쪽 컬럼에 배치
- 액션 버튼은 자동으로 마지막에 추가됨
- 모바일에서는 카드로 자동 변환

### 2. 폼 구성 시
- 필수 필드는 `*` 표시
- 에러 메시지는 필드 하단에 표시
- 그리드 레이아웃 사용 (1열 또는 2열)

### 3. 검증 함수
- 필수 필드 검증
- 형식 검증 (이메일, 전화번호 등)
- 중복 검증
- 비즈니스 로직 검증

### 4. 성능 최적화
- 대용량 데이터는 페이지네이션 사용
- 검색/필터는 debounce 적용
- 불필요한 리렌더링 방지

## 📚 예시 코드

완전한 예시는 `/components/examples/ClientManagementExample.tsx`를 참고하세요.

## 🔄 기존 페이지 마이그레이션

기존 CRUD 페이지를 이 템플릿으로 변환하는 방법:

1. **데이터 준비**: `useData()` 훅에서 데이터 가져오기
2. **컬럼 정의**: `Column<T>[]` 타입으로 컬럼 정의
3. **폼 렌더링**: `renderForm` 함수 구현
4. **액션 연결**: `onCreate`, `onUpdate`, `onDelete` 구현
5. **템플릿 적용**: 기존 JSX를 `<CRUDPageTemplate>`으로 교체

## ⚠️ 주의사항

1. 데이터 타입은 반드시 `id: string` 필드를 포함해야 함
2. `keyField`를 지정하지 않으면 기본값으로 `"id"` 사용
3. 비동기 작업(API 호출)은 `onCreate`, `onUpdate`, `onDelete`에서 처리
4. 복잡한 UI가 필요한 경우 커스텀 컴포넌트 사용 권장

## 🚀 향후 개선 계획

- [ ] 엑셀 내보내기/가져오기 기능
- [ ] 일괄 작업 (선택 삭제, 선택 수정 등)
- [ ] 고급 필터링 (날짜 범위, 다중 선택 등)
- [ ] 정렬 기능
- [ ] 컬럼 표시/숨김 설정
