# PivotGrid 컴포넌트

다차원 데이터 분석을 위한 피벗 테이블 컴포넌트입니다.

## 주요 기능

### 1. 다차원 데이터 배치

- **행 영역(Row Area)**: 데이터를 행으로 그룹화 (예: 지역 → 도시)
- **열 영역(Column Area)**: 데이터를 열로 그룹화 (예: 연도 → 분기)
- **데이터 영역(Data Area)**: 집계될 수치 필드 (예: 매출액, 수량)
- **필터 영역(Filter Area)**: 전체 데이터 필터링

### 2. 집계 함수

| 함수 | 설명 | 사용 예 |
|------|------|---------|
| `sum` | 합계 | 매출 합계 |
| `count` | 개수 | 건수 |
| `avg` | 평균 | 평균 단가 |
| `min` | 최소값 | 최저가 |
| `max` | 최대값 | 최고가 |
| `countDistinct` | 고유값 개수 | 거래처 수 |

### 3. 날짜 그룹화

날짜 필드를 다양한 단위로 그룹화할 수 있습니다:

- `year`: 연도별
- `quarter`: 분기별
- `month`: 월별
- `week`: 주별
- `day`: 일별

### 4. 드릴다운

계층적 데이터를 확장/축소하여 상세 내용을 볼 수 있습니다.

### 5. 총합계/소계

- 행 총합계 (Row Grand Total)
- 열 총합계 (Column Grand Total)
- 행 소계 (Row Subtotal)
- 열 소계 (Column Subtotal)

### 6. 내보내기

CSV 형식으로 데이터를 내보낼 수 있습니다.

## 사용법

### 기본 사용

```tsx
import { PivotGridComponent } from "@/lib/registry/components/pivot-grid";

const salesData = [
  { region: "북미", city: "뉴욕", year: 2024, quarter: "Q1", amount: 15000 },
  { region: "북미", city: "LA", year: 2024, quarter: "Q1", amount: 12000 },
  // ...
];

<PivotGridComponent
  title="매출 분석"
  data={salesData}
  fields={[
    { field: "region", caption: "지역", area: "row", areaIndex: 0 },
    { field: "city", caption: "도시", area: "row", areaIndex: 1 },
    { field: "year", caption: "연도", area: "column", areaIndex: 0 },
    { field: "quarter", caption: "분기", area: "column", areaIndex: 1 },
    { field: "amount", caption: "매출액", area: "data", summaryType: "sum" },
  ]}
/>
```

### 날짜 그룹화

```tsx
<PivotGridComponent
  data={orderData}
  fields={[
    { field: "customer", caption: "거래처", area: "row" },
    {
      field: "orderDate",
      caption: "주문일",
      area: "column",
      dataType: "date",
      groupInterval: "month", // 월별 그룹화
    },
    { field: "totalAmount", caption: "주문금액", area: "data", summaryType: "sum" },
  ]}
/>
```

### 포맷 설정

```tsx
<PivotGridComponent
  data={salesData}
  fields={[
    { field: "region", caption: "지역", area: "row" },
    { field: "year", caption: "연도", area: "column" },
    {
      field: "amount",
      caption: "매출액",
      area: "data",
      summaryType: "sum",
      format: {
        type: "currency",
        prefix: "₩",
        thousandSeparator: true,
      },
    },
    {
      field: "ratio",
      caption: "비율",
      area: "data",
      summaryType: "avg",
      format: {
        type: "percent",
        precision: 1,
        suffix: "%",
      },
    },
  ]}
/>
```

### 화면 관리에서 사용

설정 패널을 통해 테이블 선택, 필드 배치, 집계 함수 등을 GUI로 설정할 수 있습니다.

```tsx
import { PivotGridRenderer } from "@/lib/registry/components/pivot-grid";

<PivotGridRenderer
  id="pivot1"
  config={{
    dataSource: {
      type: "table",
      tableName: "sales_data",
    },
    fields: [...],
    totals: {
      showRowGrandTotals: true,
      showColumnGrandTotals: true,
    },
    exportConfig: {
      excel: true,
    },
  }}
  autoFilter={{ companyCode: "COMPANY_A" }}
/>
```

## 설정 옵션

### PivotGridProps

| 속성 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `title` | `string` | - | 피벗 테이블 제목 |
| `data` | `any[]` | `[]` | 원본 데이터 배열 |
| `fields` | `PivotFieldConfig[]` | `[]` | 필드 설정 목록 |
| `totals` | `PivotTotalsConfig` | - | 총합계/소계 표시 설정 |
| `style` | `PivotStyleConfig` | - | 스타일 설정 |
| `allowExpandAll` | `boolean` | `true` | 전체 확장/축소 버튼 |
| `exportConfig` | `PivotExportConfig` | - | 내보내기 설정 |
| `height` | `string | number` | `"auto"` | 높이 |
| `maxHeight` | `string` | - | 최대 높이 |

### PivotFieldConfig

| 속성 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `field` | `string` | O | 데이터 필드명 |
| `caption` | `string` | O | 표시 라벨 |
| `area` | `"row" | "column" | "data" | "filter"` | O | 배치 영역 |
| `areaIndex` | `number` | - | 영역 내 순서 |
| `dataType` | `"string" | "number" | "date" | "boolean"` | - | 데이터 타입 |
| `summaryType` | `AggregationType` | - | 집계 함수 (data 영역) |
| `groupInterval` | `DateGroupInterval` | - | 날짜 그룹 단위 |
| `format` | `PivotFieldFormat` | - | 값 포맷 |
| `visible` | `boolean` | - | 표시 여부 |

### PivotTotalsConfig

| 속성 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `showRowGrandTotals` | `boolean` | `true` | 행 총합계 표시 |
| `showColumnGrandTotals` | `boolean` | `true` | 열 총합계 표시 |
| `showRowTotals` | `boolean` | `true` | 행 소계 표시 |
| `showColumnTotals` | `boolean` | `true` | 열 소계 표시 |

## 파일 구조

```
pivot-grid/
├── index.ts                    # 모듈 진입점
├── types.ts                    # 타입 정의
├── PivotGridComponent.tsx      # 메인 컴포넌트
├── PivotGridRenderer.tsx       # 화면 관리 렌더러
├── PivotGridConfigPanel.tsx    # 설정 패널
├── README.md                   # 문서
└── utils/
    ├── index.ts                # 유틸리티 모듈 진입점
    ├── aggregation.ts          # 집계 함수
    └── pivotEngine.ts          # 피벗 데이터 처리 엔진
```

## 사용 시나리오

### 1. 매출 분석

지역별/기간별/제품별 매출 현황을 분석합니다.

### 2. 재고 현황

창고별/품목별 재고 수량을 한눈에 파악합니다.

### 3. 생산 실적

생산라인별/일자별 생산량을 분석합니다.

### 4. 비용 분석

부서별/계정별 비용을 집계하여 분석합니다.

### 5. 수주 현황

거래처별/품목별/월별 수주 현황을 분석합니다.

## 주의사항

1. **대량 데이터**: 데이터가 많을 경우 성능에 영향을 줄 수 있습니다. 적절한 필터링을 사용하세요.
2. **멀티테넌시**: `autoFilter.companyCode`를 통해 회사별 데이터 격리가 적용됩니다.
3. **필드 순서**: `areaIndex`를 통해 영역 내 필드 순서를 지정하세요.