@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/DataGrid-/354/202/254/354/232/251/353/262/225.md

@@ -0,0 +1,866 @@
+# DataGrid 컴포넌트 사용법
+
+`DataGrid`는 AXBoot 프레임워크의 `AXDataGrid`를 래핑한 React 컴포넌트입니다. 테이블 형태의 데이터를 효율적으로 표시하고 관리할 수 있는 기능을 제공합니다.
+
+## 기본 사용법
+
+```tsx
+import { DataGrid } from "@core/components/DataGrid";
+import { useContainerSize } from "@core/hooks/useContainerSize";
+
+function MyListComponent() {
+  const { containerRef, width: containerWidth, height: containerHeight } = useContainerSize();
+
+  return (
+    <div ref={containerRef} style={{ flex: 1 }}>
+      <DataGrid<MyDataType>
+        width={containerWidth}
+        height={containerHeight}
+        columns={columns}
+        data={data}
+        rowKey="id"
+      />
+    </div>
+  );
+}
+```
+
+## Props 정의
+
+### 기본 Props
+
+| 속성 | 타입 | 설명 | 기본값 |
+|------|------|------|--------|
+| `width` | `number` | 그리드 너비 (필수) | - |
+| `height` | `number` | 그리드 높이 (필수) | - |
+| `showLineNumber` | `boolean` | 행 번호 표시 여부 | `true` |
+
+### 데이터 관련
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `data` | `AXDGDataItem<T>[]` | 표시할 데이터 배열 |
+| `rowKey` | `React.Key \| React.Key[]` | 행 식별키 |
+| `selectedRowKey` | `React.Key \| React.Key[]` | 선택된 행 키 |
+
+### 컬럼 관련
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `columns` | `AXDGColumnWithOptionalWidth<T>[]` | 컬럼 정의 배열 (필수) |
+| `columnsGroup` | `AXDGColumnGroup[]` | 컬럼 그룹 정의 |
+| `frozenColumnIndex` | `number` | 고정 컬럼 인덱스 |
+| `onChangeColumns` | `(columnIndex: number \| null, info: AXDGChangeColumnsInfo<T>) => void` | 컬럼 변경 이벤트 |
+
+### 레이아웃 관련
+
+| 속성 | 타입 | 설명 | 기본값 |
+|------|------|------|--------|
+| `headerHeight` | `number` | 헤더 높이 | `28` |
+| `footerHeight` | `number` | 푸터 높이 | `28` |
+| `itemHeight` | `number` | 행 높이 | `20` |
+| `summaryHeight` | `number` | 요약 행 높이 | - |
+| `itemPadding` | `number` | 행 패딩 | - |
+
+### 페이징 관련
+
+페이징 설정은 `page` prop으로 전달됩니다:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `currentPage` | `number` | 현재 페이지 |
+| `pageSize` | `number` | 페이지당 항목 수 |
+| `totalPages` | `number` | 전체 페이지 수 |
+| `totalElements` | `number` | 전체 항목 수 |
+| `loading` | `boolean` | 로딩 상태 |
+| `onChange` | `(currentPage: number, pageSize?: number) => void` | 페이지 변경 이벤트 |
+
+### 정렬 관련
+
+정렬 설정은 `sort` prop으로 전달됩니다:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `multiSort` | `boolean` | 다중 정렬 허용 |
+| `sortParams` | `AXDGSortParam[]` | 정렬 파라미터 |
+| `onChange` | `(sortParams: AXDGSortParam[]) => void` | 정렬 변경 이벤트 |
+
+### 행 선택 관련
+
+행 체크박스 설정은 `rowChecked` prop으로 전달됩니다:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `isRadio` | `boolean` | 라디오 모드 |
+| `checkedIndexes` | `number[]` | 선택된 인덱스 배열 |
+| `checkedRowKeys` | `React.Key[]` | 선택된 키 배열 |
+| `disabled` | `(index: number, item: AXDGDataItem<T>) => boolean` | 비활성화 조건 |
+| `onChange` | `(checkedIndexes: number[], checkedRowKeys: React.Key[], checkedAll?: CheckedAll) => void` | 선택 변경 이벤트 |
+
+### 이벤트 관련
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `onClick` | `(params: AXDGClickParams<T>) => void` | 행 클릭 이벤트 |
+| `onChangeData` | `(index: number, columnIndex: number \| null, item: T, column: AXDGColumn<T> \| null) => void` | 데이터 변경 이벤트 |
+
+### 기타
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `spinning` | `boolean` | 로딩 스피너 표시 |
+| `loading` | `boolean` | 로딩 상태 |
+| `editable` | `boolean` | 편집 가능 여부 |
+| `editTrigger` | `'dblclick' \| 'click'` | 편집 트리거 |
+| `className` | `string` | CSS 클래스명 |
+| `style` | `React.CSSProperties` | 인라인 스타일 |
+
+## 컬럼 정의 (AXDGColumn)
+
+```tsx
+interface AXDGColumn<T> {
+  key: string | string[];           // 데이터 키
+  label: ReactNode;                 // 컬럼 제목
+  width: number;                    // 컬럼 너비
+  align?: 'left' | 'center' | 'right';        // 정렬
+  headerAlign?: 'left' | 'center' | 'right';  // 헤더 정렬
+  sortDisable?: boolean;            // 정렬 비활성화
+  className?: string;               // CSS 클래스
+  getClassName?: (item: AXDGDataItem<T>) => string;  // 동적 클래스
+  headerClassName?: string;         // 헤더 CSS 클래스
+  itemRender?: React.FC<AXDGItemRenderProps<T>>;     // 셀 렌더러
+  editable?: boolean;               // 편집 가능 여부
+}
+```
+
+## 사용 예시
+
+### 1. 기본 리스트 (회원 목록)
+
+```tsx
+import { DataGrid } from "@core/components/DataGrid";
+import { useDataGridColumns } from "@core/hooks/useDataGridColumns";
+import { useDataGridSortedList } from "@core/hooks/useDataGridSortedList";
+
+interface MemberData {
+  usrNo: number;
+  usrNm: string;
+  usrHpNo: string;
+  pntAmt: number;
+  creatDtm: string;
+}
+
+export function MemberListDataGrid() {
+  const { containerRef, width: containerWidth, height: containerHeight } = useContainerSize();
+
+  // 컬럼 정의
+  const { columns } = useDataGridColumns<MemberData>([
+    { key: "usrNo", label: "번호", type: "rowNo" },
+    { key: "usrNm", label: "이름", align: "left", width: 120 },
+    { key: "usrHpNo", label: "핸드폰번호", align: "left", width: 150 },
+    {
+      key: "pntAmt",
+      label: "포인트",
+      type: "money",
+      width: 90,
+      itemRender: ({ value }) => formatterNumber(value),
+    },
+    {
+      key: "creatDtm",
+      label: "가입일",
+      type: "dateTime",
+      itemRender: ({ value }) => formatterDate(value),
+    },
+  ], { colWidths: listColWidths });
+
+  const sortedListData = useDataGridSortedList<MemberData>(listData, listSortParams);
+
+  return (
+    <div ref={containerRef} style={{ flex: 1 }}>
+      <DataGrid<MemberData>
+        frozenColumnIndex={0}
+        width={containerWidth}
+        height={containerHeight}
+        columns={columns}
+        data={sortedListData}
+        spinning={listSpinning}
+        onClick={onClickItem}
+        page={{
+          ...listPage,
+          loading: false,
+          onChange: async (currentPage, pageSize) => {
+            await changeListPage(currentPage, pageSize);
+          },
+        }}
+        sort={{
+          sortParams: listSortParams,
+          onChange: setListSortParams,
+        }}
+        rowKey="usrNo"
+        selectedRowKey={selectedItem?.usrNo ?? ""}
+      />
+    </div>
+  );
+}
+```
+
+### 2. 체크박스가 있는 리스트
+
+```tsx
+const [checkedRowKeys, setCheckedRowKeys] = useState<React.Key[]>([]);
+
+return (
+  <DataGrid<ItemType>
+    width={containerWidth}
+    height={containerHeight}
+    columns={columns}
+    data={data}
+    rowChecked={{
+      checkedRowKeys: checkedRowKeys,
+      onChange: (checkedIndexes, checkedRowKeys, checkedAll) => {
+        setCheckedRowKeys(checkedRowKeys);
+      },
+    }}
+    rowKey="id"
+  />
+);
+```
+
+### 3. 액션 버튼이 있는 리스트
+
+```tsx
+const { columns } = useDataGridColumns<ProductData>([
+  { key: "prodgrpMastrNm", label: "제품군 마스터 명", type: "title", width: 300 },
+  { key: "prodgrpMastrNo", label: "제품군 코드", align: "center", width: 100 },
+  {
+    key: "",
+    label: "관리",
+    align: "left",
+    width: 120,
+    itemRender: ({ item }) => {
+      return (
+        <Flex gap={6} justify="center">
+          <Button
+            size="small"
+            onClick={(e) => {
+              e.stopPropagation(); // 행 클릭 이벤트 방지
+              handleCopy(item.values.prodgrpMastrNo);
+            }}
+          >
+            복사
+          </Button>
+          <Button
+            size="small"
+            variant="outlined"
+            color="danger"
+            onClick={(e) => {
+              e.stopPropagation();
+              handleDelete(item.values.prodgrpMastrNo);
+            }}
+          >
+            삭제
+          </Button>
+        </Flex>
+      );
+    },
+  },
+]);
+
+// 특정 컬럼 클릭 시 행 클릭 이벤트 방지
+const onClickItem = useCallback((params: AXDGClickParams<ProductData>) => {
+  if (params.columnIndex === 2) { // 관리 컬럼
+    return; // 클릭 이벤트 무시
+  }
+  // 일반 행 클릭 처리
+  handleItemClick(params);
+}, [handleItemClick]);
+```
+
+### 4. 컬럼 그룹 헤더
+
+```tsx
+// 마일리지 일일 요약
+<DataGrid<DtoItem>
+  width={containerWidth}
+  height={containerHeight}
+  headerHeight={54} // 그룹 헤더를 위해 높이 증가
+  columns={columns}
+  columnsGroup={[
+    {
+      label: "마일리지",
+      groupStartIndex: 1,
+      groupEndIndex: 3,
+      headerAlign: "center"
+    }
+  ]}
+  data={sortedListData}
+/>
+
+// 복합 그룹 헤더 (배당 현황)
+<DataGrid<DtoItem>
+  headerHeight={60}
+  columnsGroup={[
+    { groupStartIndex: 10, groupEndIndex: 11, label: "현금배당 수익률(%)" },
+    { groupStartIndex: 12, groupEndIndex: 13, label: "주식배당 수익률(%)" },
+    { groupStartIndex: 14, groupEndIndex: 15, label: "주당 현금배당금(원)" },
+    { groupStartIndex: 16, groupEndIndex: 17, label: "주당 주식배당(주)" },
+  ]}
+  // ... other props
+/>
+```
+
+### 5. 셀 병합 기능
+
+```tsx
+// 주문 ID별로 셀 병합
+<DataGrid<OrderData>
+  width={containerWidth}
+  height={containerHeight}
+  columns={columns}
+  data={data}
+  cellMergeOptions={{
+    columnsMap: {
+      0: { mergeBy: "ordId" },    // 첫 번째 컬럼을 ordId로 병합
+      1: { mergeBy: "ordId" },    // 두 번째 컬럼을 ordId로 병합
+      2: { mergeBy: "ordId" },    // 세 번째 컬럼을 ordId로 병합
+      3: { mergeBy: "ordId" },    // 네 번째 컬럼을 ordId로 병합
+    },
+  }}
+  variant="vertical-bordered" // 세로 경계선 표시
+/>
+
+// 패키지 정산 - 상담 그룹별 병합
+<DataGrid<SettlementData>
+  cellMergeOptions={{
+    columnsMap: {
+      1: { mergeBy: "nhCnsltGroupNo" },
+      2: { mergeBy: "nhCnsltGroupNo" },
+      3: { mergeBy: "nhCnsltGroupNo" },
+      4: { mergeBy: "nhCnsltGroupNo" },
+    },
+  }}
+  // ... other props
+/>
+```
+
+### 6. 요약 행 표시
+
+```tsx
+// 상단 요약
+const summaryTop: AXDGProps<any>["summary"] = {
+  position: "top",
+  columns: [
+    {
+      columnIndex: 0,
+      align: "center",
+      colSpan: 3,
+      itemRender: () => <strong>요약 정보</strong>,
+    },
+    {
+      columnIndex: 3,
+      align: "right",
+      itemRender: ({ data }) => {
+        const total = data.reduce((sum, item) => sum + item.values.amount, 0);
+        return `총합: ${formatterNumber(total)}원`;
+      },
+    },
+  ],
+};
+
+// 하단 요약
+const summaryBottom: AXDGProps<any>["summary"] = {
+  position: "bottom",
+  columns: [
+    {
+      columnIndex: 0,
+      align: "center",
+      colSpan: 2,
+      itemRender: () => "합계",
+    },
+    {
+      columnIndex: 2,
+      align: "right",
+      itemRender: ({ data }) => {
+        return formatterNumber(data.length) + "건";
+      },
+    },
+  ],
+};
+
+<DataGrid<DataType>
+  // ... other props
+  summary={summaryTop} // 또는 summaryBottom
+/>
+```
+
+### 7. 중첩된 객체 데이터 참조
+
+```tsx
+// JSON 객체의 중첩 키 참조
+const { columns } = useDataGridColumns<FinancialData>([
+  { key: "bbscttMgmtYy", label: "년도", align: "center", width: 80 },
+  { key: "bbscttBgnDt", label: "분기", align: "center", width: 80 },
+
+  // paramtrJson.consolidated.revenue 형태로 중첩 참조
+  { key: ["paramtrJson", "consolidated", "revenue"], label: "매출액", type: "money" },
+  { key: ["paramtrJson", "consolidated", "gross_profit"], label: "매출이익", type: "money" },
+  { key: ["paramtrJson", "consolidated", "operating_income"], label: "영업이익", type: "money" },
+  { key: ["paramtrJson", "consolidated", "net_income"], label: "순이익", type: "money" },
+
+  // 별도 재무 데이터
+  { key: ["paramtrJson", "separate", "revenue"], label: "별도매출액", type: "money" },
+  { key: ["paramtrJson", "separate", "total_assets"], label: "별도자산", type: "money" },
+]);
+
+// 데이터 구조 예시
+const sampleData = {
+  bbscttMgmtYy: "2024",
+  bbscttBgnDt: "2024-01-01",
+  paramtrJson: {
+    consolidated: {
+      revenue: 1000000,
+      gross_profit: 200000,
+      operating_income: 150000,
+      net_income: 100000,
+    },
+    separate: {
+      revenue: 800000,
+      total_assets: 5000000,
+    }
+  }
+};
+```
+
+### 8. 이미지 및 미디어 렌더링
+
+```tsx
+const { columns } = useDataGridColumns<BannerData>([
+  { key: "bannerNm", label: "배너명", width: 200 },
+  {
+    key: "image",
+    label: "이미지",
+    width: 180,
+    itemRender: ({ values }) => {
+      return (
+        <Flex gap={6} justify="center" align="center">
+          {values.pcImageFlInfo && (
+            <ThumbPreview url={values.pcImageFlInfo.prevewUrlCtnts} />
+          )}
+          {values.moImageFlInfo && (
+            <ThumbPreview url={values.moImageFlInfo.prevewUrlCtnts} />
+          )}
+        </Flex>
+      );
+    },
+  },
+  {
+    key: "expsrBgnDtm",
+    label: "노출기간",
+    width: 150,
+    itemRender: ({ values }) => {
+      return values.expsrBgnDtm ? (
+        <Flex wrap gap={5} style={{ lineHeight: 1 }} justify="center">
+          <span>{dayjs(values.expsrBgnDtm).format("YYYY-MM-DD HH:mm")}</span>
+          <span>~</span>
+          <span>{dayjs(values.expsrEndDtm).format("YYYY-MM-DD HH:mm")}</span>
+        </Flex>
+      ) : (
+        "제한없음"
+      );
+    },
+  },
+]);
+
+<DataGrid<BannerData>
+  itemHeight={60} // 이미지 표시를 위해 행 높이 증가
+  // ... other props
+/>
+```
+
+### 9. 인라인 편집
+
+```tsx
+<DataGrid<EditableData>
+  width={containerWidth}
+  height={containerHeight}
+  columns={editableColumns}
+  data={data}
+  editable={true}
+  editTrigger="dblclick" // 더블클릭으로 편집 시작
+  onChangeData={(index, columnIndex, item, column) => {
+    // 데이터 변경 시 호출
+    console.log("Data changed:", { index, columnIndex, item, column });
+    // 서버에 저장 로직
+    handleSaveData(item);
+  }}
+  rowKey="id"
+/>
+
+// 편집 가능한 컬럼 정의
+const editableColumns = [
+  { key: "id", label: "ID", width: 80, editable: false }, // 편집 불가
+  { key: "name", label: "이름", width: 150, editable: true },
+  { key: "email", label: "이메일", width: 200, editable: true },
+  { key: "status", label: "상태", width: 100, editable: true },
+];
+```
+
+### 10. 엑셀 업로드 및 일괄 처리
+
+```tsx
+const handleExcelUpload = useCallback(async () => {
+  try {
+    await openExcelUploaderModal<ExcelDto>({
+      title: "재무 하이라이트 일괄등록",
+      showResultList: false,
+      showResultCount: true,
+      targetColumns: excelUploadColumns,
+      headerBtnRender: ExcelSampleDownload,
+      callExcelUpload: async (list) => {
+        // 엑셀 데이터 처리
+        for await (const item of list) {
+          const apiParams = {
+            bbscttMgmtYy: dayjs(item.bbscttBgnDt, "YYYY-Q").format("YYYY"),
+            bbscttBgnDt: dayjs(item.bbscttBgnDt, "YYYY-Q").format("YYYY-MM-DD"),
+            paramtrJson: {
+              consolidated: {
+                revenue: item.consolidated_revenue ? Number(item.consolidated_revenue) : undefined,
+                gross_profit: item.consolidated_gross_profit ? Number(item.consolidated_gross_profit) : undefined,
+              }
+            },
+            useYn: item.useYn === "Y" ? "Y" : "N",
+          };
+
+          await BbsPostService.postBbsPostSave(apiParams);
+        }
+
+        return {
+          successList: list,
+          failList: [],
+        };
+      },
+    });
+
+    await callListApi(); // 목록 새로고침
+  } catch (err) {
+    await errorHandling(err);
+  }
+}, [callListApi]);
+
+// 엑셀 컬럼 정의
+const excelUploadColumns: ExcelTargetColumn[] = [
+  { key: "bbscttBgnDt", label: "분기", type: "string", required: true },
+  { key: "useYn", label: "사용여부", type: "string", required: true },
+  { key: "consolidated_revenue", label: "연결_매출액", type: "number", required: true },
+  { key: "consolidated_gross_profit", label: "연결_매출이익", type: "number", required: true },
+];
+```
+
+## 훅 활용
+
+### useDataGridColumns
+컬럼 정의와 너비 관리를 위한 훅
+
+```tsx
+const { columns } = useDataGridColumns<DataType>(columnDefs, {
+  colWidths: listColWidths,
+  deps: [CODES] // 의존성 배열
+});
+```
+
+### useDataGridSortedList
+클라이언트 사이드 정렬을 위한 훅
+
+```tsx
+const sortedListData = useDataGridSortedList<DataType>(listData, listSortParams);
+```
+
+### useContainerSize
+컨테이너 크기 자동 계산을 위한 훅
+
+```tsx
+const { containerRef, width: containerWidth, height: containerHeight } = useContainerSize();
+```
+
+## 고급 기능
+
+### 컬럼 너비 조정
+
+```tsx
+const handleColumnsChange = React.useCallback(
+  (columnIndex: number | null, { columns }: AXDGChangeColumnsInfo<DtoItem>) => {
+    // 사용자가 컬럼 너비를 조정할 때 상태에 저장
+    setListColWidths(columns.map((column) => column.width));
+  },
+  [setListColWidths],
+);
+
+<DataGrid
+  columns={columns}
+  onChangeColumns={handleColumnsChange}
+  // ... other props
+/>
+```
+
+### 조건부 스타일링
+
+```tsx
+const { columns } = useDataGridColumns<DataType>([
+  {
+    key: "status",
+    label: "상태",
+    width: 100,
+    // 셀별 동적 클래스
+    getClassName: (item) => {
+      switch (item.values.status) {
+        case "active": return "status-active";
+        case "inactive": return "status-inactive";
+        case "pending": return "status-pending";
+        default: return "";
+      }
+    },
+  },
+]);
+
+<DataGrid
+  // 행별 동적 클래스
+  getRowClassName={(ri, item) => {
+    return item.values.important ? "important-row" : undefined;
+  }}
+  // ... other props
+/>
+```
+
+### 무한 스크롤
+
+```tsx
+<DataGrid<DataType>
+  width={containerWidth}
+  height={containerHeight}
+  columns={columns}
+  data={data}
+  enableLoadMore={true}
+  onLoadMore={({ scrollLeft, scrollTop }) => {
+    // 스크롤 위치에 따른 추가 데이터 로드
+    if (scrollTop > threshold) {
+      loadMoreData();
+    }
+  }}
+  endLoadMoreRender={() => (
+    <div style={{ textAlign: "center", padding: "20px" }}>
+      더 이상 데이터가 없습니다.
+    </div>
+  )}
+/>
+```
+
+### 드래그 앤 드롭 정렬
+
+```tsx
+<DataGrid<DataType>
+  width={containerWidth}
+  height={containerHeight}
+  columns={columns}
+  data={data}
+  reorder={{
+    enabled: true,
+    handleIcon: <Icon name="grip-vertical" />,
+    onReorder: (newData) => {
+      // 새로운 순서로 데이터 업데이트
+      setData(newData);
+      // 서버에 순서 저장
+      saveOrderToServer(newData);
+    },
+  }}
+/>
+```
+
+## 성능 최적화
+
+### 가상화 스크롤
+
+```tsx
+// DataGrid는 기본적으로 가상화를 지원합니다
+<DataGrid<DataType>
+  width={containerWidth}
+  height={containerHeight}
+  itemHeight={40} // 일정한 행 높이 설정으로 성능 향상
+  columns={columns}
+  data={largeDataset} // 수천, 수만 건의 데이터도 부드럽게 처리
+/>
+```
+
+### 메모이제이션
+
+```tsx
+// 컬럼 정의 메모이제이션
+const columns = useMemo(() => [
+  { key: "id", label: "ID", width: 80 },
+  { key: "name", label: "이름", width: 150 },
+  // 복잡한 itemRender 함수도 메모이제이션
+  {
+    key: "status",
+    label: "상태",
+    width: 100,
+    itemRender: useCallback(({ value }) => {
+      return <StatusBadge status={value} />;
+    }, []),
+  },
+], []);
+
+// 데이터 정렬도 메모이제이션
+const sortedData = useMemo(() => {
+  return useDataGridSortedList(rawData, sortParams);
+}, [rawData, sortParams]);
+```
+
+## 실제 사용 사례
+
+### 전자상거래 주문 관리
+
+```tsx
+// 주문 상태별 색상 구분, 셀 병합, 액션 버튼 등 복합 기능
+<DataGrid<OrderData>
+  cellMergeOptions={{
+    columnsMap: {
+      0: { mergeBy: "ordId" },
+      1: { mergeBy: "ordId" },
+      2: { mergeBy: "ordId" },
+    },
+  }}
+  getRowClassName={(ri, item) => {
+    switch (item.values.orderStatus) {
+      case "pending": return "order-pending";
+      case "processing": return "order-processing";
+      case "completed": return "order-completed";
+      case "cancelled": return "order-cancelled";
+      default: return "";
+    }
+  }}
+  onClick={handleOrderDetail}
+  rowChecked={{
+    checkedRowKeys: selectedOrders,
+    onChange: handleOrderSelection,
+  }}
+  // ... other props
+/>
+```
+
+### 재무 데이터 대시보드
+
+```tsx
+<DataGrid<FinancialData>
+  headerHeight={60}
+  columnsGroup={[
+    { groupStartIndex: 3, groupEndIndex: 6, label: "연결 재무" },
+    { groupStartIndex: 7, groupEndIndex: 10, label: "별도 재무" },
+  ]}
+  summary={{
+    position: "bottom",
+    columns: [
+      {
+        columnIndex: 0,
+        colSpan: 3,
+        itemRender: () => "합계",
+      },
+      {
+        columnIndex: 3,
+        itemRender: ({ data }) => {
+          const total = data.reduce((sum, item) =>
+            sum + (item.values.paramtrJson?.consolidated?.revenue || 0), 0
+          );
+          return formatterNumber(total);
+        },
+      },
+    ],
+  }}
+  // JSON 중첩 키 참조
+  columns={[
+    { key: ["paramtrJson", "consolidated", "revenue"], label: "연결매출", type: "money" },
+    { key: ["paramtrJson", "separate", "revenue"], label: "별도매출", type: "money" },
+  ]}
+/>
+```
+
+### 콘텐츠 관리 시스템
+
+```tsx
+<DataGrid<BannerData>
+  itemHeight={80} // 이미지 표시를 위한 높은 행
+  columns={[
+    {
+      key: "images",
+      label: "이미지",
+      width: 200,
+      itemRender: ({ values }) => (
+        <Flex gap={6} justify="center">
+          {values.pcImage && <ThumbPreview url={values.pcImage} />}
+          {values.mobileImage && <ThumbPreview url={values.mobileImage} />}
+        </Flex>
+      ),
+    },
+    {
+      key: "period",
+      label: "노출기간",
+      width: 180,
+      itemRender: ({ values }) => (
+        <Flex direction="column" align="center">
+          <span>{dayjs(values.startDate).format("YYYY-MM-DD")}</span>
+          <span>~</span>
+          <span>{dayjs(values.endDate).format("YYYY-MM-DD")}</span>
+        </Flex>
+      ),
+    },
+  ]}
+  onClick={(params) => {
+    if (params.columnIndex === 5) return; // 액션 컬럼 제외
+    handleEditBanner(params.item);
+  }}
+/>
+```
+
+## 스타일링
+
+DataGrid는 Emotion을 사용한 테마 시스템을 지원합니다:
+
+```tsx
+const Container = styled.div`
+  flex: 1;
+
+  .status-active {
+    background-color: #f6ffed;
+    color: #52c41a;
+  }
+
+  .status-inactive {
+    background-color: #fff2f0;
+    color: #ff4d4f;
+  }
+
+  .important-row {
+    background-color: #fffbe6;
+    border-left: 3px solid #faad14;
+  }
+
+  .selectable:hover {
+    background-color: #e6f7ff;
+    cursor: pointer;
+  }
+`;
+```
+
+## 주의사항
+
+> **⚠️ 중요사항들을 반드시 확인하세요:**
+
+1. `width`와 `height`가 0인 경우 컴포넌트가 렌더링되지 않습니다.
+2. `showLineNumber`는 기본적으로 `true`로 설정됩니다.
+3. 테마 시스템을 통해 다양한 스타일 변수를 커스터마이징할 수 있습니다.
+4. 반드시 `rowKey`를 설정해야 행 선택과 업데이트가 정상 작동합니다.
+5. 큰 데이터셋의 경우 페이징을 활용하는 것이 성능상 유리합니다.
+6. 셀 병합 사용 시 `variant="vertical-bordered"` 옵션으로 시각적 구분을 개선할 수 있습니다.
+7. 액션 버튼 클릭 시 행 클릭 이벤트가 발생하지 않도록 `e.stopPropagation()`을 사용하세요.
+8. 다중 키 참조 시 배열 형태로 키를 전달합니다: `key: ["parent", "child", "grandchild"]`
+
+> **💡 참고사항:**
+> 더 많은 예시와 고급 사용법은 프로젝트 내 `/src/pages/resources/NH/` 폴더의 다양한 `ListDataGrid.tsx` 파일들을 참조하세요.