ERP-node/frontend/lib/registry/components/v2-table-grouped/README.md

# v2-table-grouped (그룹화 테이블)

## 개요

데이터를 특정 컬럼 기준으로 그룹화하여 접기/펼치기 기능을 제공하는 테이블 컴포넌트입니다.

## 주요 기능

- **그룹화**: 지정된 컬럼 기준으로 데이터를 그룹핑
- **접기/펼치기**: 그룹 헤더 클릭으로 하위 항목 토글
- **그룹 요약**: 그룹별 개수, 합계, 평균, 최대/최소값 표시
- **체크박스 선택**: 그룹 단위 또는 개별 항목 선택
- **전체 펼치기/접기**: 모든 그룹 일괄 토글 버튼

## 사용 예시

```tsx
import { TableGroupedComponent } from "./TableGroupedComponent";

<TableGroupedComponent
  config={{
    selectedTable: "production_plan_mng",
    groupConfig: {
      groupByColumn: "item_code",
      groupLabelFormat: "{item_name} ({item_code})",
      defaultExpanded: true,
      summary: {
        showCount: true,
        sumColumns: ["quantity"],
      },
    },
    columns: [
      { columnName: "plan_no", displayName: "계획번호", visible: true },
      { columnName: "plan_date", displayName: "계획일", visible: true },
      { columnName: "quantity", displayName: "수량", visible: true, format: "number" },
    ],
    showCheckbox: true,
    checkboxMode: "multi",
    showExpandAllButton: true,
  }}
  onSelectionChange={(event) => console.log("선택:", event.selectedItems)}
  onRowClick={(event) => console.log("행 클릭:", event.row)}
/>
```

## 설정 옵션

### 기본 설정

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `selectedTable` | string | - | 데이터 테이블명 |
| `useCustomTable` | boolean | false | 커스텀 테이블 사용 여부 |
| `customTableName` | string | - | 커스텀 테이블명 |
| `columns` | ColumnConfig[] | [] | 표시할 컬럼 설정 |

### 그룹화 설정 (groupConfig)

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `groupByColumn` | string | - | 그룹화 기준 컬럼 (필수) |
| `groupLabelFormat` | string | "{value}" | 그룹 라벨 형식 |
| `defaultExpanded` | boolean | true | 초기 펼침 상태 |
| `sortDirection` | "asc" \| "desc" | "asc" | 그룹 정렬 방향 |
| `summary.showCount` | boolean | true | 개수 표시 여부 |
| `summary.sumColumns` | string[] | [] | 합계 컬럼 목록 |
| `summary.avgColumns` | string[] | [] | 평균 컬럼 목록 |

### 표시 설정

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `showCheckbox` | boolean | false | 체크박스 표시 |
| `checkboxMode` | "single" \| "multi" | "multi" | 선택 모드 |
| `showExpandAllButton` | boolean | true | 전체 펼치기/접기 버튼 |
| `groupHeaderStyle` | "default" \| "compact" \| "card" | "default" | 그룹 헤더 스타일 |
| `rowClickable` | boolean | true | 행 클릭 가능 여부 |
| `maxHeight` | number | 600 | 최대 높이 (px) |
| `emptyMessage` | string | "데이터가 없습니다." | 빈 데이터 메시지 |

## 이벤트

### onSelectionChange

선택 상태가 변경될 때 호출됩니다.

```typescript
interface SelectionChangeEvent {
  selectedGroups: string[];  // 선택된 그룹 키 목록
  selectedItems: any[];      // 선택된 아이템 전체
  isAllSelected: boolean;    // 전체 선택 여부
}
```

### onGroupToggle

그룹 펼치기/접기 시 호출됩니다.

```typescript
interface GroupToggleEvent {
  groupKey: string;   // 그룹 키
  expanded: boolean;  // 펼침 상태
}
```

### onRowClick

행 클릭 시 호출됩니다.

```typescript
interface RowClickEvent {
  row: any;           // 클릭된 행 데이터
  groupKey: string;   // 그룹 키
  indexInGroup: number; // 그룹 내 인덱스
}
```

## 그룹 라벨 형식

`groupLabelFormat`에서 사용 가능한 플레이스홀더:

- `{value}`: 그룹화 컬럼의 값
- `{컬럼명}`: 해당 컬럼의 값

**예시:**
```
groupLabelFormat: "{item_name} ({item_code}) - {category}"
// 결과: "제품A (P001) - 완제품"
```

## 파일 구조

```
v2-table-grouped/
├── index.ts                    # Definition
├── types.ts                    # 타입 정의
├── config.ts                   # 기본 설정값
├── TableGroupedComponent.tsx   # 메인 컴포넌트
├── TableGroupedConfigPanel.tsx # 설정 패널
├── TableGroupedRenderer.tsx    # 레지스트리 등록
├── components/
│   └── GroupHeader.tsx         # 그룹 헤더
├── hooks/
│   └── useGroupedData.ts       # 그룹화 로직 훅
└── README.md
```

## v2-table-list와의 차이점

| 항목 | v2-table-list | v2-table-grouped |
|------|---------------|------------------|
| 데이터 구조 | 플랫 리스트 | 계층 구조 (그룹 > 아이템) |
| 렌더링 | 행 단위 | 그룹 헤더 + 상세 행 |
| 선택 | 개별 행 | 그룹 단위 / 개별 단위 |
| 요약 | 전체 합계 (선택) | 그룹별 요약 |
| 용도 | 일반 데이터 목록 | 카테고리별 분류 데이터 |

## 관련 컴포넌트

- `v2-table-list`: 기본 테이블 (그룹화 없음)
- `v2-pivot-grid`: 피벗 테이블 (다차원 집계)
- `v2-split-panel-layout`: 마스터-디테일 레이아웃