# ClientVirtualTable V3 가이드 (한국어)

`components/client-table-v2` 테이블 컴포넌트와 `fetchMode="server"` 사용 시 주의점을 정리했습니다.

## 모듈 맵
- `client-virtual-table.tsx`: 코어 테이블(가상 스크롤, 컬럼 DnD, 핀/숨김, 프리셋, 툴바, 페이지네이션).
- `client-table-column-header.tsx`: 헤더 셀(정렬 토글, 필터 UI, 컨텍스트 메뉴: 핀/숨김/그룹/재정렬).
- `client-table-toolbar.tsx` (client-table): 검색, 내보내기, 뷰 옵션, 프리셋 엔트리.
- `client-table-view-options.tsx` (client-table): 컬럼 표시/숨김 토글.
- `client-table-filter.tsx`: 컬럼 필터 UI(text/select/boolean).
- `client-table-preset.tsx`: `tableKey`+사용자별 프리셋 저장/불러오기/삭제.
- 기타: `export-utils`, `import-utils`, `ClientDataTablePagination`(client-data-table).
- 서버 헬퍼: `adapter/create-table-service.ts`, `adapter/drizzle-table-adapter.ts`.
- 타입: `types.ts`, `preset-types.ts`.

## 핵심 동작 (ClientVirtualTable)
- 가상 스크롤: `height` 필수, `estimateRowHeight` 기본 40.
- DnD: 컬럼 재배치, 핀 섹션 간 이동 시 핀 상태 동기화.
- 핀/숨김/순서: 클라이언트 상태(`columnVisibility`, `columnPinning`, `columnOrder`).
- 정렬/필터/페이지네이션/그룹핑
  - `fetchMode="client"`: TanStack 모델 사용.
  - `fetchMode="server"`: manual 플래그 on, 클라이언트 모델 skip → **서버가 정렬/필터/페이징된 결과를 반환해야 함**.
- 내보내기: 현재 렌더된 행 기준. 서버 모드에서 전체 내보내기는 직접 `onExport`로 구현 필요.
- 프리셋: `enableUserPreset`+`tableKey` 설정 시 표시. 불러올 때 pageIndex를 0으로 리셋해 서버 모드에서 범위 오류 방지.

## 주요 Props
- `fetchMode`: `"client"` | `"server"` (기본 `"client"`).
- 데이터: `data`, `rowCount?`, `pageCount?`.
- 상태/핸들러:
  - 페이지: `pagination`, `onPaginationChange`, `enablePagination`, `manualPagination?`.
  - 정렬: `sorting`, `onSortingChange`.
  - 필터: `columnFilters`, `onColumnFiltersChange`, `globalFilter`, `onGlobalFilterChange`.
  - 그룹핑: `grouping`, `onGroupingChange`, `expanded`, `onExpandedChange`, `enableGrouping`.
  - 표시/핀/순서: `columnVisibility`, `columnPinning`, `columnOrder` 및 각 onChange.
  - 선택: `enableRowSelection`, `enableMultiRowSelection`, `rowSelection`, `onRowSelectionChange`.
- UX: `actions`, `customToolbar`, `enableExport`, `onExport`, `renderHeaderVisualFeedback`, `getRowClassName`, `onRowClick`.
- 프리셋: `enableUserPreset`, `tableKey`.
- 메타: `meta`, `getRowId`.

## 서버 페칭 패턴
### 패턴 1: 클라이언트 모드
- `fetchMode="client"`, 전체 데이터 전달. 정렬/필터/그룹핑은 브라우저에서 처리.

### 패턴 2: Factory Service (`createTableService`)
- 서버 액션: `createTableService({ db, schema, columns, defaultWhere?, customQuery? })`.
- 어댑터가 `sorting`, `columnFilters`, `globalFilter`, `pagination`, `grouping`을 Drizzle `where/orderBy/limit/offset/groupBy`로 변환.
- 반환 `{ data, totalRows, pageCount }` → 클라이언트에서 `rowCount` 설정 필수.
- 클라이언트: `pagination/sorting/columnFilters/globalFilter` 제어 후 deps로 `useEffect` 재호출.

### 패턴 2-B: 서버 그룹핑
- `getProductTableDataWithGrouping` 예시: `grouping` 없으면 일반 페칭, 있으면 DB `GROUP BY` 후 `{ groups }` 반환.
- 서버 그룹핑 가능한 컬럼(`meta.serverGroupable`)만 사용.
- 그룹 확장 시 그룹 키별 하위 행을 추가 조회, 그룹 변경 시 확장 상태 초기화.
- 그룹뷰 렌더 시 가상 테이블 대신 커스텀 블록을 사용할 수 있음.

### 패턴 3: 커스텀 서비스
- 조인/파생 컬럼용. `tableState`를 읽어 정렬 ID를 조인 컬럼에 매핑, 정렬 없을 때 기본 정렬 제공.
- 필터/글로벌 필터는 직접 구현해야 함.
- 그룹핑도 수동 구현(`getOrderTableDataGroupedByStatus` 참고).

## 상태 → 쿼리 매핑 (서버)
- 정렬: `tableState.sorting`(id, desc) → DB 컬럼 매핑, 모르는 id는 무시.
- 필터: 텍스트(ilike), 불리언, 숫자, 범위[min,max], 다중선택(IN) 지원.
- 글로벌 필터: 매핑된 컬럼 OR ilike.
- 페이지: pageIndex/pageSize → limit/offset, `rowCount` 반환.
- 그룹핑: 지원 컬럼만 `GROUP BY`.

## 프리셋 (서버 호환)
- 저장: sorting, columnFilters, globalFilter, columnVisibility, columnPinning, columnOrder, grouping, pageSize.
- 불러오기: `table.set*` 호출 + pageIndex 0 리셋 → 상위 `on*Change` 핸들러에서 재페칭.
- 화면별 고유 `tableKey` 사용 권장. 세션 필요.

## 기능 매트릭스 (서버 모드)
- 정렬: 지원 (서버 구현 필요)
- 필터: 지원 (서버 구현 필요)
- 페이지네이션: 지원 (manual, `rowCount` 필요)
- 그룹핑: 자동 미지원, 서버 그룹핑 또는 커스텀 뷰로 구현
- 컬럼 숨김/핀/순서: 클라이언트 전용(시각용), 서버 쿼리에 자동 반영 안 함
- 내보내기: 로드된 행만; 전체 내보내기는 커스텀 `onExport` 필요

## 구현 팁
- `fetchMode="server"`일 때 `rowCount` 꼭 설정.
- `pagination/sorting/columnFilters/globalFilter/(grouping)` 변경 시마다 재페칭.
- 정렬 없을 때 서버 기본 정렬을 지정.
- 그룹 변경 시 확장 상태 초기화.
- `height`를 항상 지정(가상 스크롤 컨테이너 필요).

## 빠른 예시
- 클라이언트: `fetchMode="client"`, 전체 데이터 전달, 그룹핑 옵션 사용 가능.
- Factory 서버: `fetchMode="server"`, `createTableService`, 제어형 상태 + `rowCount`.
- 서버 그룹핑: `grouping`에 따라 `{ groups }` vs `{ data }` 반환, `serverGroupable` 컬럼만 허용.
- 커스텀 조인: 정렬 ID 직접 매핑, 필터/글로벌 직접 적용, `rowCount` 반환.