# 08. 리얼그리드(RealGrid) 활용

ST 앱에서 사용하는 엔터프라이즈급 그리드 라이브러리인 **RealGrid 2**의 구현 방식과 주요 함수, 속성을 정리합니다.

---

## 1. 개요 및 구조

ST 앱은 `realgrid-react`를 사용하여 리액트 환경에서 그리드를 구현하고 있으며, 공통 모듈인 `DataGrid.tsx`에서 복잡한 설정을 추상화하여 제공합니다.

### 주요 컴포넌트
- **`DataGrid.tsx`**: 가장 핵심이 되는 공통 그리드 컴포넌트.
- **`TabDataGrid.tsx`**: 탭별로 독립적인 `DataGrid`를 렌더링.
- **`SplitDataGrid.tsx`**: 좌우 5:5 분할 화면에 두 개의 그리드를 배치.
- **`CompactDataGrid.tsx`**: 간소화된 형태의 그리드.

---

## 2. 주요 설정 및 속성 (Props)

`DataGridProps` 인터페이스를 통해 그리드의 동작을 제어합니다.

| 속성명 | 타입 | 설명 |
|-------|------|------|
| `columnInfo` | `ColumnInfo` | 컬럼 정의(`columns`)와 레이아웃(`columnLayout`) 정보 |
| `rowData` | `Record[]` | 그리드에 표시할 실제 데이터 배열 |
| `fixedColumns` | `number` | 좌측에 고정할 컬럼 수 |
| `rowStartNum` | `number` | 엑셀 임포트 시 헤더가 시작되는 행 번호 |
| `isExcelImport` | `boolean` | 엑셀 가져오기 버튼 표시 여부 |
| `isExcelExport` | `boolean` | 엑셀 내보내기 버튼 표시 여부 |
| `showHeaderCheckbox`| `boolean` | 헤더 체크박스(CheckBar) 표시 여부 |
| `cellStyleCallback` | `Function` | 실시간 조건부 셀 스타일 적용 콜백 |
| `cellTooltipCallback`| `Function` | 셀 호버 시 표시할 툴팁 메시지 콜백 |
| `onRowClick` | `Function` | 행 클릭 시 실행될 이벤트 핸들러 |

---

## 3. 컬럼 정의 (`ColumnConfig`)

`src/components/type/DataGrid.type.ts`에 정의된 주요 컬럼 속성입니다.

```typescript
export type ColumnConfig = {
    name: string;          // 컬럼 고유 이름
    fieldName: string;     // 데이터 필드명
    header: { text: string }; // 헤더 표시 텍스트
    width?: number;        // 컬럼 너비 (px)
    editable?: boolean;    // 편집 가능 여부
    visible?: boolean;     // 숨김 여부
    styleName?: string;    // 적용할 CSS 클래스
    mergeCells?: boolean;  // 셀 병합 여부 (내용이 같을 때)
    valueType?: ValueType; // 데이터 타입 (TEXT, NUMBER 등)
    footer?: FooterConfig; // 푸터 설정 (합계 등)
    computed?: Computed;   // 계산 필드 설정 (합계/평균/비율 등)
};
```

---

## 4. 핵심 기능 구현 상세

### 4-1. 커스텀 정렬 (`onSorting`)
기본 정렬 사용 시 "시군구" 등 병합된 셀의 그룹 순서가 깨지는 문제를 해결하기 위해 전용 핸들러를 사용합니다.
- **`createOnSortingHandler`**: 정렬 시 그룹(시군구) 내의 순서를 유지하며 그룹 간 정렬을 수행합니다.
- **`createNumberComparer`**: 숫자에 포함된 쉼표(,)를 제거하고 순수 숫자 값으로 비교하여 정확한 정렬을 보장합니다.

### 4-2. 계산 필드 (`Computed Field`)
`dataProvider.setFields` 시 `valueCallback`을 통해 실시간 계산 값을 생성합니다.
- **지원 유형**: 단순 합계(`sum`), 평균(`avg`), 보급률(`pblswrgPopltnSuprtRate`) 등 특수 비즈니스 로직.
- **매커니즘**: `getComputedValueCallback` 유틸을 통해 여러 필드의 값을 조합하여 결과를 반환합니다.

### 4-3. 엑셀 임포트/익스포트 (Smart Mapping)
일반적인 그리드와 달리, 엑셀 파일과 그리드 간의 정확한 필드 매칭을 위해 특수한 기법을 사용합니다.
- **익스포트 시**: 엑셀 헤더 텍스트 뒤에 `(fieldName)`을 임시로 붙여서 내보냅니다. (예: `인구수 (popltnCnt)`)
- **임포트 시**: 정규표현식 `/\(([a-zA-Z0-9_]+)\)$/`을 사용하여 헤더에서 `fieldName`을 추출, 데이터 파싱 시 정확한 객체 키로 매핑합니다.

### 4-4. 푸터(Footer) 및 레이아웃 합병
- **`footerUserSpans`**: `columnLayout` 설정을 통해 푸터 영역에서 여러 셀을 하나로 합치는 기능을 지원합니다.
- **멀티 푸터**: `gridView.setFooters`를 통해 2행 이상의 푸터를 설정하고, 각 행마다 다른 통계(합계, 평균 등)를 보여줍니다.

---

## 5. 자주 사용하는 유틸리티 함수

### `toGridRows<T>`
API 응답 객체 배열을 RealGrid가 처리하기 좋은 형태로 변환합니다.
- `null` 또는 `undefined` 값을 빈 문자열(`""`)로 치환하여 그리드 상에서 `null` 문구가 노출되지 않도록 합니다.

---

## 6. 스타일 가이드 (`styleName`)

그리드 셀에 적용되는 주요 CSS 클래스입니다 (프로젝트 관례).
- `rg-cell-readonly`: 읽기 전용 셀 배경색 처리
- `rg-cell-total`: 합계 행/열 강조
- `rg-cell-error`: 검증 오류 발생 셀 (빨간색 테두리 등)
- `rg-cell-required`: 필수 입력 셀 표시

---

## 7. RealGrid 원천 API 상세 (Native API)

프로젝트 코드(`DataGrid.tsx`, `CompactDataGrid.tsx`)에서 실제로 호출하고 있는 RealGrid의 원천 함수와 속성 목록입니다.

### 7-1. 전역 설정 (`realgrid`)
- **`RealGrid.setLicenseKey(key: string)`**: 라이선스 키를 등록합니다.
- **`ValueType`**: 필드 데이터 타입을 지정하는 열거형 (예: `ValueType.TEXT`, `ValueType.NUMBER`).
- **`GridFitStyle`**: 그리드 너비 맞춤 스타일 (예: `GridFitStyle.EVEN`).

### 7-2. 그리드 뷰 (`GridView`)
그리드의 시각적 요소와 이벤트를 제어합니다.

| API | 설명 |
|-----|-----|
| `setOptions(options)` | 그리드 전역 옵션 설정 (`checkBar.visible`, `summaryMode` 등) |
| `setDisplayOptions(options)` | 화면 표시 상세 설정 (`fitStyle`, `rowHeight` 등) |
| `setFixedOptions(options)` | 고정 컬럼 설정 (`colCount`) |
| `setFooters(heights)` | 멀티 푸터 행들의 높이를 배열로 설정 |
| `setColumns(columns)` | 컬럼 구성을 동적으로 재설정 |
| `setColumnLayout(layout)` | 컬럼의 시각적 배치(그룹 헤더 등) 적용 |
| `setColumnProperty(col, prop, val)` | 특정 컬럼의 속성(예: `renderer`)을 개별 변경 |
| `exportGrid(options)` | 엑셀 파일 내보내기 실행 |
| `setCurrent(index)` | 특정 행/셀로 포커스 이동 (`itemIndex` 사용) |
| `setFocus()` | 그리드 자체에 포커스 부여 |
| `refresh()` | 그리드 화면 강제 다시 그리기 (스타일 변경 시 유용) |
| `columnByName(name)` | 이름으로 특정 컬럼 객체 반환 |

**주요 이벤트 핸들러:**
- `onSorting`: 정렬 시점 발생. (커스텀 그룹 정렬 구현 시 사용)
- `onCellClicked`: 셀 클릭 시 발생. (행 선택 로직 구현)
- `onShowTooltip`: 툴팁 표시 직전 발생. (동적 툴팁 내용 생성)

### 7-3. 데이터 프로바이더 (`LocalDataProvider`)
그리드 내부의 실제 데이터를 관리합니다.

| API | 설명 |
|-----|-----|
| `setFields(fields)` | 데이터 필드(데이터 모델) 구조 정의 |
| `setRows(rows)` | 전체 데이터 로드 |
| `getRowCount()` | 전체 데이터 행 수 반환 |
| `getValue(row, field)` | 특정 행/필드의 데이터 값 조회 |
| `setDataComparer(field, fn)` | 특정 필드의 정렬 로직을 사용자 정의 함수로 위임 |

---

## 8. RealGrid-React 컴포넌트 (`realgrid-react`)

### 8-1. `<RealGridReact />` (메인 컨테이너)
- **`ref`**: 내부 `gridView`와 `dataProvider` 객체에 접근하기 위해 사용.
- **`rows`**: 리액트 상태(`rowData`)를 그리드 데이터와 바인딩.
- **`layout`**: 정의된 `columnLayout`을 적용.
- **`autoGenerateField`**: `true` 설정 시 행 데이터를 바탕으로 필드를 자동 생성.
- **`onInitialized(grid)`**: 그리드 초기화 완료 후 실행되는 콜백.

### 8-2. `<RGDataColumn />` (컬럼 속성 정의)
JSX 형태로 각 컬럼의 세부 속성을 설정합니다.

| 주요 Props | 설명 |
|-----------|-----|
| `name` / `fieldName` | 컬럼/필드 식별자 |
| `valueType` | 데이터 타입 (`TEXT`, `NUMBER`) |
| `numberFormat` | 숫자 표시 형식 (예: `#,##0.000`) |
| `header` | 헤더 설정 객체 (`{ text: "제목" }`) |
| `editable` | 해당 컬럼의 편집 가능 여부 |
| `styleName` | 해당 컬럼에 적용할 CSS 클래스명 |
| `renderer` | 셀 렌더러 설정 (예: `{ showTooltip: true }`) |
| `footer` | 푸터 합계/수식 설정 |
| `mergeRule` | 셀 병합 규칙 (`{ criteria: "value" }`) |
| `sortable` | 정렬 가능 여부 |