@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/MCP-/353/260/224/354/235/264/353/270/214/354/275/224/353/224/251-/352/260/200/354/235/264/353/223/234.md

@@ -0,0 +1,1133 @@
+# MCP 바이브코딩 가이드
+
+> NH-FE-BO 프로젝트의 Store, Hook, Component 패턴을 MCP 서버에서 활용하여 자동 코드 생성을 위한 매뉴얼입니다.
+
+## 목차
+
+1. [아키텍처 개요](#아키텍처-개요)
+2. [Store 구현 패턴](#store-구현-패턴)
+3. [Hook 구현 패턴](#hook-구현-패턴)
+4. [Component 구현 패턴](#component-구현-패턴)
+5. [Ant Design 컴포넌트 패턴](#ant-design-컴포넌트-패턴)
+6. [AX Grid 컴포넌트 패턴](#ax-grid-컴포넌트-패턴)
+7. [레이어 간 연결 방식](#레이어-간-연결-방식)
+8. [MCP 활용 예시](#mcp-활용-예시)
+
+---
+
+## 아키텍처 개요
+
+### 레이어 구조
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Component Layer                      │
+│  (App.tsx, ListDataGrid.tsx, FormModal.tsx)                 │
+└────────────────────────┬────────────────────────────────────┘
+                         │ subscribe/useStore
+┌────────────────────────▼────────────────────────────────────┐
+│                         Store Layer                         │
+│  (useXxxListStore.ts - Zustand)                             │
+│  - States: 상태 정의                                         │
+│  - Actions: 액션 정의                                        │
+│  - MetaData: 영속화 데이터                                   │
+└────────────────────────┬────────────────────────────────────┘
+                         │ API 호출
+┌────────────────────────▼────────────────────────────────────┐
+│                         Hook Layer                          │
+│  (useXxxService.ts)                                          │
+│  - API 호출 래핑                                             │
+│  - 데이터 변환                                               │
+└────────────────────────┬────────────────────────────────────┘
+                         │ HTTP Request
+┌────────────────────────▼────────────────────────────────────┐
+│                      Service Layer                          │
+│  (XxxService.ts)                                             │
+└────────────────────────┬────────────────────────────────────┘
+                         │ Repository 호출
+┌────────────────────────▼────────────────────────────────────┐
+│                    Repository Layer                         │
+│  (XxxRepository.ts - Interface)                              │
+└────────────────────────┬────────────────────────────────────┘
+                         │ axios
+┌────────────────────────▼────────────────────────────────────┐
+│                         Backend API                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Store 구현 패턴
+
+### 기본 구조 (Zustand)
+
+```typescript
+// use[Entity]ListStore.ts
+
+import { AXDGDataItem, AXDGPage, AXDGSortParam } from "@axboot/datagrid";
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+import { PageStoreActions, StoreActions } from "@core/stores/types";
+import { deleteEmptyValue } from "@core/utils/object";
+import { errorHandling } from "utils";
+import { ProgramFn } from "@types";
+import { EntityService } from "services";
+import { getTabStoreListener } from "stores";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+
+// ========== 1. Request/Response 인터페이스 ==========
+interface ListRequest extends PostEntityListRequest {}
+
+interface DtoItem extends Entity {}
+
+// ========== 2. MetaData 정의 (영속화 대상) ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  listCheckedIndexes?: number[];
+  modalOpen: boolean;
+}
+
+// ========== 3. States 정의 ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  deleteSpinning: boolean;
+  saveSpinning: boolean;
+  detailSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  selectedItem?: DtoItem;
+  detail?: DtoItem;
+  checkedRowKeys: React.Key[];
+}
+
+// ========== 4. 초기 상태 ==========
+const createState: States = {
+  routePath: "/entity/list",
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    // 초기 검색 조건
+  },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  deleteSpinning: false,
+  saveSpinning: false,
+  detailSpinning: false,
+  listData: [],
+  listPage: {
+    currentPage: 0,
+    totalPages: 0,
+  },
+  selectedItem: undefined,
+  detail: undefined,
+  modalOpen: false,
+  checkedRowKeys: [],
+  listSelectedRowKey: "",
+  listCheckedIndexes: [],
+};
+
+// ========== 5. Actions 정의 ==========
+interface Actions extends PageStoreActions<States> {
+  // 검색 관련
+  setListRequestValue: (requestValue: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+
+  // 선택 관련
+  setListSelectedRowKey: (key?: React.Key) => void;
+  setSelectedItem: (selectedItem?: DtoItem) => void;
+  setDetail: (detail?: DtoItem) => void;
+  callDetailApi: (id: number | string) => Promise<void>;
+
+  // CRUD 관련
+  callSaveApi: (request?: PostEntitySaveRequest) => Promise<void>;
+  callDeleteApi: (request: PostEntityDeleteRequest) => Promise<void>;
+
+  // UI 관련
+  setModalOpen: (open: boolean) => void;
+  setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+}
+
+// ========== 6. Actions 구현 ==========
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+
+  // 검색 관련
+  setListRequestValue: (requestValues) => set({ listRequestValue: requestValues }),
+  setListColWidths: (colWidths) => set({ listColWidths: colWidths }),
+  setListSortParams: (sortParams) => set({ listSortParams: sortParams }),
+  setListSpinning: (spinning) => set({ listSpinning: spinning }),
+
+  callListApi: async (request) => {
+    if (get().listSpinning) return;
+    set({ listSpinning: true });
+
+    try {
+      const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+      const response = await EntityService.postEntityList(deleteEmptyValue(apiParam));
+
+      set({
+        listRequestValue: apiParam,
+        listData: response.ds.map((values) => ({ values })),
+        listPage: {
+          currentPage: response.page.pageNumber ?? 1,
+          pageSize: response.page.pageSize ?? 0,
+          totalPages: response.page.pageCount ?? 0,
+          totalElements: response.page?.totalCount,
+        },
+      });
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ listSpinning: false });
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ ...get().listRequestValue, pageNumber, pageSize });
+  },
+
+  // 선택 관련
+  setListSelectedRowKey: (key) => set({ listSelectedRowKey: key }),
+  setSelectedItem: async (selectedItem) => {
+    set({ selectedItem, detailSpinning: true });
+    if (!selectedItem || (selectedItem as any)["__status__"] === "C") {
+      set({ modalOpen: false });
+    }
+    set({ detailSpinning: false });
+  },
+  setDetail: (detail) => set({ detail }),
+  setModalOpen: (open) => set({ modalOpen: open }),
+  setCheckedRowKeys: (checkedRowKeys) => set({ checkedRowKeys }),
+
+  // CRUD 관련
+  callSaveApi: async (request) => {
+    if (get().saveSpinning) return;
+    if (!request) return;
+
+    try {
+      set({ saveSpinning: true });
+      request.__status__ = get().listSelectedRowKey ? ("U" as const) : ("C" as const);
+      await EntityService.postEntitySave(request);
+      await get().callListApi();
+      set({ modalOpen: false });
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  callDeleteApi: async (request) => {
+    if (get().deleteSpinning) return;
+    try {
+      set({ deleteSpinning: true });
+      await EntityService.postEntityDelete(request);
+      await get().callListApi();
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ deleteSpinning: false });
+    }
+  },
+});
+
+// ========== 7. Store 생성 ==========
+export interface EntityListStore extends States, Actions, PageStoreActions<States> {}
+
+export const useEntityListStore = create(
+  subscribeWithSelector<EntityListStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  })),
+);
+
+// ========== 8. 메타데이터 구독 ==========
+useEntityListStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+    listSelectedRowKey: s.listSelectedRowKey,
+    listCheckedIndexes: s.listCheckedIndexes,
+    modalOpen: s.modalOpen,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### Store 타입별 패턴
+
+| 타입 | 특징 | 추가 States | 추가 Actions |
+|------|------|-------------|--------------|
+| **기본 목록** | 단순 조회, 페이징 | - | `callListApi`, `changeListPage` |
+| **마스터-디테일** | 목록 + 상세 | `selectedItem`, `detail` | `setSelectedItem`, `callDetailApi` |
+| **모달 포함** | 팝업 폼 | `modalOpen` | `setModalOpen`, `callSaveApi` |
+| **삭제 포함** | 일괄 삭제 | `deleteSpinning` | `callDeleteApi` |
+| **체크박스** | 다중 선택 | `checkedRowKeys` | `setCheckedRowKeys` |
+| **트리 구조** | 계층 데이터 | `treeData`, `expandedKeys` | `setExpandedKeys`, `toggleExpand` |
+
+---
+
+## Hook 구현 패턴
+
+### 기본 서비스 훅
+
+```typescript
+// use[Entity]Service.ts
+
+import { useState, useCallback } from "react";
+import { deleteEmptyValue } from "@core/utils/object";
+import { errorHandling } from "utils/errorHandling";
+import { EntityRes, PostEntityListRequest, EntityService } from "services";
+
+interface UseEntityServiceParams {
+  autoFetch?: boolean;
+  initialParams?: Partial<PostEntityListRequest>;
+}
+
+export function useEntityService(params?: UseEntityServiceParams) {
+  const [list, setList] = useState<EntityRes[]>([]);
+  const [spinning, setSpinning] = useState(false);
+
+  const getList = useCallback(async (listParams?: Partial<PostEntityListRequest>) => {
+    setSpinning(true);
+    try {
+      const data = await EntityService.postEntityList(
+        deleteEmptyValue(listParams ?? {})
+      );
+      setList(data.ds);
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      setSpinning(false);
+    }
+  }, []);
+
+  return {
+    list,
+    spinning,
+    getList,
+  };
+}
+```
+
+### Repository 기반 훅 생성
+
+MCP 서버를 활용한 훅 자동 생성:
+
+```
+MCP Tool: mcp__mcp-axboot__generate_hook
+
+Input:
+- interfacePath: /path/to/XxxRepository.ts
+- outputPath: /path/to/src/hooks/useXxxService.ts (optional)
+
+Output:
+- Repository 인터페이스 분석
+- list/detail API 기반 훅 자동 생성
+```
+
+---
+
+## Component 구현 패턴
+
+### App.tsx 기본 구조
+
+```typescript
+// App.tsx
+
+import { ProgramTitle, StoreResetButton } from "@core/components/common";
+import { SearchParams, SearchParamType } from "@core/components/search";
+import { useDidMountEffect } from "@core/hooks/useDidMountEffect";
+import styled from "@emotion/styled";
+import { Button, Flex, Form } from "antd";
+import { useI18n, useUnmountEffect } from "hooks";
+import React from "react";
+import { PageLayout } from "styles/pageStyled";
+import { errorHandling } from "utils/errorHandling";
+import { ListDataGrid } from "./ListDataGrid";
+import { useEntityListStore } from "./useEntityListStore";
+
+interface Props {}
+
+function App({}: Props) {
+  const { t } = useI18n("_entity");
+
+  // Store 상태
+  const init = useEntityListStore((s) => s.init);
+  const destroy = useEntityListStore((s) => s.destroy);
+  const callListApi = useEntityListStore((s) => s.callListApi);
+  const listRequestValue = useEntityListStore((s) => s.listRequestValue);
+  const setListRequestValue = useEntityListStore((s) => s.setListRequestValue);
+  const listSpinning = useEntityListStore((s) => s.listSpinning);
+  const programFn = useEntityListStore((s) => s.programFn);
+
+  const resizerContainerRef = React.useRef<HTMLDivElement>(null);
+  const [searchForm] = Form.useForm();
+
+  const handleSearch = React.useCallback(async () => {
+    try {
+      await callListApi({ pageNumber: 1 });
+    } catch (e) {
+      await errorHandling(e);
+    }
+  }, [callListApi]);
+
+  useDidMountEffect(() => {
+    (async () => {
+      try {
+        await init();
+        await callListApi();
+      } catch (e) {
+        await errorHandling(e);
+      }
+    })();
+  });
+
+  useUnmountEffect(() => {
+    destroy();
+  });
+
+  return (
+    <Container stretch role={"page-container"}>
+      <Header>
+        <ProgramTitle>
+          <StoreResetButton onReset={useEntityListStore.getState().reset} />
+        </ProgramTitle>
+
+        <Flex align={"center"} gap={6}>
+          {programFn?.fn01 && <Button onClick={handleSearch}>{t("검색")}</Button>}
+        </Flex>
+
+        <PageSearchBar>
+          <SearchParams
+            form={searchForm}
+            params={[
+              {
+                label: t("검색어"),
+                name: "filter",
+                type: SearchParamType.INPUT,
+                placeholder: t("검색어를 입력하세요"),
+              },
+            ]}
+            paramsValue={listRequestValue}
+            onChangeParamsValue={(value) => setListRequestValue(value)}
+            onSearch={handleSearch}
+            spinning={listSpinning}
+          />
+        </PageSearchBar>
+      </Header>
+
+      <Body ref={resizerContainerRef}>
+        <Frame>
+          <ListDataGrid />
+        </Frame>
+      </Body>
+    </Container>
+  );
+}
+
+const Container = styled(PageLayout)``;
+const Header = styled(PageLayout.Header)``;
+const PageSearchBar = styled(PageLayout.PageSearchBar)``;
+const Body = styled(PageLayout.FrameRow)``;
+const Frame = styled(PageLayout.FrameColumn)``;
+
+export default App;
+```
+
+### ListDataGrid.tsx 기본 구조
+
+```typescript
+// ListDataGrid.tsx
+
+import { DataGrid } from "@core/components/DataGrid";
+import { useDataGridColumns } from "@core/hooks/useDataGridColumns";
+import { useDataGridSortedList } from "@core/hooks/useDataGridSortedList";
+import { useContainerSize } from "hooks";
+import React from "react";
+import { PageLayout } from "styles/pageStyled";
+import { useEntityListStore } from "./useEntityListStore";
+
+interface DtoItem extends Entity {}
+
+interface Props {}
+
+export function ListDataGrid({}: Props) {
+  // Store 상태
+  const listColWidths = useEntityListStore((s) => s.listColWidths);
+  const listSortParams = useEntityListStore((s) => s.listSortParams);
+  const listData = useEntityListStore((s) => s.listData);
+  const listPage = useEntityListStore((s) => s.listPage);
+  const listSpinning = useEntityListStore((s) => s.listSpinning);
+  const setListColWidths = useEntityListStore((s) => s.setListColWidths);
+  const setListSortParams = useEntityListStore((s) => s.setListSortParams);
+  const changeListPage = useEntityListStore((s) => s.changeListPage);
+  const programFn = useEntityListStore((s) => s.programFn);
+
+  // 컬럼 정의
+  const { columns } = useDataGridColumns<DtoItem>(
+    [
+      { key: "id", label: "ID", align: "left", width: 80 },
+      { key: "name", label: "이름", align: "left", width: 150 },
+      { key: "status", label: "상태", align: "center", width: 100 },
+    ],
+    {
+      colWidths: listColWidths,
+    },
+  );
+
+  const sortedListData = useDataGridSortedList<DtoItem>(listData, listSortParams);
+  const { containerRef, width: containerWidth, height: containerHeight } = useContainerSize();
+
+  const handleColumnsChange = React.useCallback(
+    (columnIndex: number | null, { columns }: AXDGChangeColumnsInfo<DtoItem>) => {
+      setListColWidths(columns.map((column) => column.width));
+    },
+    [setListColWidths],
+  );
+
+  const onClickItem = React.useCallback((params: AXDGClickParams<DtoItem>) => {
+    // 행 클릭 처리
+  }, []);
+
+  return (
+    <>
+      <FormHeader>
+        목록
+        <FormHeaderActions programFn={programFn} />
+      </FormHeader>
+      <Container ref={containerRef}>
+        <DataGrid<DtoItem>
+          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,
+          }}
+          onChangeColumns={handleColumnsChange}
+        />
+      </Container>
+    </>
+  );
+}
+
+const Container = styled.div`
+  flex: 1;
+`;
+const FormHeader = styled(PageLayout.FrameHeader)``;
+```
+
+---
+
+## Ant Design 컴포넌트 패턴
+
+### 1. Form 관련 컴포넌트
+
+#### Form.Item 기본 패턴
+
+```typescript
+import { Form, Input, Select } from "antd";
+
+// 텍스트 입력
+<Form.Item
+  name="fieldName"
+  label="필드명"
+  rules={[{ required: true, message: "필수 입력입니다" }]}
+>
+  <Input placeholder="입력하세요" />
+</Form.Item>
+
+// 선택 (Select)
+<Form.Item
+  name="status"
+  label="상태"
+  initialValue="Y"
+>
+  <Select
+    options={[
+      { label: "활성", value: "Y" },
+      { label: "비활성", value: "N" },
+    ]}
+  />
+</Form.Item>
+```
+
+#### DatePicker 패턴
+
+```typescript
+import { DatePicker } from "antd";
+import dayjs from "dayjs";
+
+// 단일 날짜
+<Form.Item
+  name="date"
+  label="날짜"
+>
+  <DatePicker
+    format="YYYY-MM-DD"
+    placeholder="날짜 선택"
+  />
+</Form.Item>
+
+// 날짜 범위
+<Form.Item
+  name="dateRange"
+  label="기간"
+>
+  <DatePicker.RangePicker
+    format="YYYY-MM-DD"
+    placeholder={["시작일", "종료일"]}
+  />
+</Form.Item>
+```
+
+### 2. Button 패턴
+
+```typescript
+import { Button } from "antd";
+
+// 기본 버튼
+<Button onClick={handleClick}>클릭</Button>
+
+// 타입별
+<Button type="primary">주요 버튼</Button>
+<Button type="default">기본 버튼</Button>
+<Button danger>삭제</Button>
+
+// 아이콘 포함
+<Button icon={<SearchOutlined />} onClick={handleSearch}>
+  검색
+</Button>
+
+// 로딩 상태
+<Button loading={loading} onClick={handleSave}>
+  저장
+</Button>
+
+// 크기별
+<Button size="small">작은 버튼</Button>
+<Button size="middle">중간 버튼</Button>
+<Button size="large">큰 버튼</Button>
+```
+
+### 3. Modal/Drawer 패턴
+
+```typescript
+import { Modal } from "antd";
+import { AXModal, AXDrawer } from "@core/components";
+
+// Ant Design Modal
+<Modal
+  open={open}
+  onOk={handleOk}
+  onCancel={handleCancel}
+  title="제목"
+  width={800}
+>
+  {/* 내용 */}
+</Modal>
+
+// AXModal (프로젝트 커스텀)
+<AXModal<Q, R>
+  open={modalOpen}
+  params={selectedItem}
+  onOk={handleSave}
+  onCancel={() => setModalOpen(false)}
+  width={800}
+>
+  <AXModal.Header title="배너 정보" />
+  <AXModal.Body>
+    {/* 폼 내용 */}
+  </AXModal.Body>
+  <AXModal.Footer>
+    <Button onClick={() => setModalOpen(false)}>취소</Button>
+    <Button type="primary" onClick={handleSave}>저장</Button>
+  </AXModal.Footer>
+</AXModal>
+```
+
+### 4. Table 관련
+
+```typescript
+import { Table } from "antd";
+
+<Table
+  columns={[
+    {
+      title: "이름",
+      dataIndex: "name",
+      key: "name",
+      align: "center",
+      width: 150,
+    },
+    {
+      title: "상태",
+      dataIndex: "status",
+      key: "status",
+      render: (value) => (value === "Y" ? "활성" : "비활성"),
+    },
+  ]}
+  dataSource={data}
+  rowKey="id"
+  pagination={{
+    current: page,
+    pageSize: pageSize,
+    total: total,
+    onChange: handlePageChange,
+  }}
+  loading={loading}
+/>
+```
+
+### 5. Space, Flex 레이아웃
+
+```typescript
+import { Space, Flex } from "antd";
+
+// Space (수평 간격)
+<Space size={8}>
+  <Button>버튼1</Button>
+  <Button>버튼2</Button>
+</Space>
+
+// Flex (유연한 레이아웃)
+<Flex gap={6} align="center" justify="space-between">
+  <div>왼쪽</div>
+  <div>오른쪽</div>
+</Flex>
+
+// 수직 Flex
+<Flex vertical gap={12}>
+  <div>항목1</div>
+  <div>항목2</div>
+</Flex>
+```
+
+---
+
+## AX Grid 컴포넌트 패턴
+
+### DataGrid 컬럼 타입
+
+```typescript
+// src/components/@dataGridColumn.tsx 참고
+
+type DataGridColumnType =
+  | "default"        // 기본
+  | "money"          // 금액 (오른쪽 정렬, 천단위 콤마)
+  | "percent"        //百分比 (오른쪽 정렬, % 추가)
+  | "title"          // 텍스트 (왼쪽 정렬)
+  | "rowNo"          // 행 번호
+  | "date"           // 날짜
+  | "dateTime"       // 날짜시간 (YYYY-MM-DD HH:mm:ss)
+  | "user"           // 사용자 정보
+  | "selectable"     // 선택 가능 텍스트
+  | "fileDownload"   // 파일 다운로드
+  | "custom";        // 커스텀 렌더링
+```
+
+### 컬럼 정의 예시
+
+```typescript
+import { useDataGridColumns } from "@core/hooks/useDataGridColumns";
+
+const { columns } = useDataGridColumns<DtoItem>([
+  // 기본 컬럼
+  { key: "id", label: "ID", align: "left", width: 80 },
+
+  // 프리셋 타입 사용
+  { key: "amount", label: "금액", type: "money" },
+  { key: "rate", label: "비율", type: "percent" },
+  { key: "name", label: "이름", type: "title" },
+  { key: "createdAt", label: "생성일", type: "dateTime" },
+
+  // 커스텀 렌더링
+  {
+    key: "status",
+    label: "상태",
+    width: 100,
+    align: "center",
+    itemRender: ({ value }) => {
+      return value === "Y" ? <Tag color="green">활성</Tag> : <Tag color="red">비활성</Tag>;
+    },
+  },
+
+  // 복합 컬럼
+  {
+    key: "user",
+    label: "사용자",
+    type: "user",
+    width: 120,
+    itemRender: ({ values }) => (
+      <div>
+        <div>{values.userName}</div>
+        <div style={{ fontSize: 12, color: "#999" }}>{values.userId}</div>
+      </div>
+    ),
+  },
+], {
+  colWidths: listColWidths,
+  deps: [CODES], // 컬럼 의존성 배열
+});
+```
+
+### DataGrid Props 패턴
+
+```typescript
+<DataGrid<DtoItem>
+  // 필수
+  width={containerWidth}
+  height={containerHeight}
+  columns={columns}
+  data={sortedListData}
+
+  // 행 식별
+  rowKey="id"
+  selectedRowKey={selectedItem?.id}
+
+  // 로딩
+  spinning={listSpinning}
+  loading={false}
+
+  // 이벤트
+  onClick={onClickItem}
+  onChangeColumns={handleColumnsChange}
+
+  // 페이징
+  page={{
+    currentPage: listPage.currentPage,
+    pageSize: listPage.pageSize,
+    totalPages: listPage.totalPages,
+    totalElements: listPage.totalElements,
+    loading: false,
+    onChange: async (currentPage, pageSize) => {
+      await changeListPage(currentPage, pageSize);
+    },
+  }}
+
+  // 정렬
+  sort={{
+    sortParams: listSortParams,
+    onChange: setListSortParams,
+  }}
+
+  // 체크박스
+  rowChecked={{
+    checkedRowKeys: checkedRowKeys,
+    onChange: (checkedIndexes, checkedRowKeys) => {
+      setCheckedRowKeys(checkedRowKeys);
+    },
+  }}
+
+  // 고정 컬럼
+  frozenColumnIndex={0}
+
+  // 행 높이
+  headerHeight={28}
+  itemHeight={20}
+  footerHeight={28}
+/>
+```
+
+### DataGrid Editor 패턴
+
+```typescript
+import { InputEditor } from "@core/components/dataGridEditor/InputEditor";
+import { SelectEditor } from "@core/components/dataGridEditor/getSelectEditor";
+import { DateEditor } from "@core/components/dataGridEditor/DateEditor";
+
+const editableColumns = [
+  { key: "id", label: "ID", width: 80, editable: false },
+  {
+    key: "name",
+    label: "이름",
+    width: 150,
+    editable: true,
+    itemRender: InputEditor,
+  },
+  {
+    key: "status",
+    label: "상태",
+    width: 100,
+    editable: true,
+    itemRender: SelectEditor,
+    editorConfig: {
+      options: [
+        { label: "활성", value: "Y" },
+        { label: "비활성", value: "N" },
+      ],
+    },
+  },
+];
+
+<DataGrid
+  editable={true}
+  editTrigger="dblclick"
+  columns={editableColumns}
+  onChangeData={(index, columnIndex, item, column) => {
+    // 데이터 변경 처리
+  }}
+/>
+```
+
+---
+
+## 레이어 간 연결 방식
+
+### Store ↔ Component 연결
+
+```typescript
+// Component에서 Store 사용
+
+// 1. 단일 상태 구독
+const listData = useEntityListStore((s) => s.listData);
+
+// 2. 복수 상태 구독 (shallow 비교)
+const { listData, listSpinning } = useEntityListStore(
+  (s) => ({ listData: s.listData, listSpinning: s.listSpinning }),
+  shallow
+);
+
+// 3. 액션 구독
+const callListApi = useEntityListStore((s) => s.callListApi);
+const setListRequestValue = useEntityListStore((s) => s.setListRequestValue);
+```
+
+### SearchParams → Store 연결
+
+```typescript
+<SearchParams
+  form={searchForm}
+  params={searchParamsConfig}
+  paramsValue={listRequestValue}           // Store의 검색 조건
+  onChangeParamsValue={(value) => {        // 검색 조건 변경 시
+    setListRequestValue(value);            // Store 업데이트
+  }}
+  onSearch={async () => {                   // 검색 버튼 클릭 시
+    await callListApi({ pageNumber: 1 });  // API 호출
+  }}
+  spinning={listSpinning}                   // 로딩 상태
+/>
+```
+
+### DataGrid → Store 연결
+
+```typescript
+const sortedListData = useDataGridSortedList(listData, listSortParams);
+
+<DataGrid
+  data={sortedListData}           // Store 데이터
+  spinning={listSpinning}         // Store 로딩 상태
+  page={{
+    ...listPage,                  // Store 페이지 정보
+    onChange: changeListPage,     // Store 액션
+  }}
+  sort={{
+    sortParams: listSortParams,   // Store 정렬 정보
+    onChange: setListSortParams,  // Store 액션
+  }}
+  onChangeColumns={(idx, { columns }) => {
+    setListColWidths(columns.map(c => c.width)); // Store 액션
+  }}
+/>
+```
+
+---
+
+## MCP 활용 예시
+
+### MCP Tool 활용
+
+```typescript
+// 1. Store + Hook 자동 생성
+mcp__mcp-axboot__generate_store_and_hook_interactive({
+  fileName: "MemberRepository",
+  projectRoot: "/path/to/project",
+})
+
+// 2. Store 생성 (타입 지정)
+mcp__mcp-axboot__generate_store({
+  interfacePath: "/path/to/MemberRepository.ts",
+  outputPath: "/path/to/src/stores/useMemberListStore.ts",
+  storeType: 2, // 1: 기본, 2: 마스터-디테일+모달+삭제
+  storeName: "useMemberListStore",
+})
+
+// 3. Hook 생성
+mcp__mcp-axboot__generate_hook({
+  interfacePath: "/path/to/MemberRepository.ts",
+  outputPath: "/path/to/src/hooks/useMemberService.ts",
+})
+
+// 4. ListDataGrid 생성
+mcp__mcp-axboot__generate_listdatagrid({
+  outputPath: "/path/to/src/pages/member/ListDataGrid.tsx",
+  config: {
+    storeName: "useMemberListStore",
+    dtoType: "MemberRes",
+    rowKey: "memberNo",
+    selectionMode: "multi",
+    withFormHeader: true,
+    withExcel: true,
+    columns: [
+      { key: "memberNo", label: "회원번호", type: "rowNo" },
+      { key: "memberNm", label: "이름", align: "left" },
+      { key: "joinDt", label: "가입일", type: "date" },
+    ],
+  },
+})
+
+// 5. SearchParams 생성
+mcp__mcp-axboot__generate_search_params({
+  appPath: "/path/to/src/pages/member/App.tsx",
+  searchParams: {
+    dateRange: {
+      withPeriodType: true,
+      periodOptions: [
+        { label: "가입일", value: "JOIN" },
+        { label: "수정일", value: "UPDATE" },
+      ],
+    },
+    codes: [
+      { name: "statusCd", label: "상태", codeVar: "STATUS_CODE", multi: true },
+    ],
+    search: {
+      withSearchType: true,
+      options: [
+        { label: "이름", value: "NAME" },
+        { label: "이메일", value: "EMAIL" },
+      ],
+    },
+  },
+})
+```
+
+### MCP로 자동 생성 가능한 파일
+
+| 파일 | MCP Tool | 설명 |
+|------|----------|------|
+| `useXxxStore.ts` | `generate_store` | Repository 기반 Store 자동 생성 |
+| `useXxxService.ts` | `generate_hook` | Repository 기반 Hook 자동 생성 |
+| `ListDataGrid.tsx` | `generate_listdatagrid` | DataGrid 컴포넌트 자동 생성 |
+| `App.tsx` (SearchParams) | `generate_search_params` | 검색 폼 JSX 자동 생성 |
+| Store + Hook | `generate_store_and_hook_interactive` | 대화형 생성 |
+
+---
+
+## 파일 명명 규칙
+
+### Store
+```
+use[도메인][기능]Store.ts
+예: useMemberListStore.ts, useProductMasterStore.ts
+```
+
+### Hook
+```
+use[도메인][기능]Service.ts
+예: useMemberService.ts, useProductService.ts
+```
+
+### Component
+```
+- ListDataGrid.tsx (목록 그리드)
+- FormModal.tsx (모달 폼)
+- App.tsx (메인 컴포넌트)
+```
+
+### Repository
+```
+[도메인]Repository.ts
+예: MemberRepository.ts, ProductRepository.ts
+```
+
+---
+
+## 공통 유틸리티
+
+### 데이터 변환
+
+```typescript
+import { deleteEmptyValue, dateRangeToDts } from "@core/utils/object";
+
+// 빈 값 제거
+const cleanParams = deleteEmptyValue({
+  name: "John",
+  email: "",     // 제거됨
+  age: null,     // 제거됨
+});
+
+// 날짜 범위 변환
+const apiParams = {
+  ...dateRangeToDts(dateRange, {
+    startDate: "YYYY-MM-DD",
+    endDate: "YYYY-MM-DD",
+  }),
+};
+```
+
+### 에러 핸들링
+
+```typescript
+import { errorHandling } from "utils/errorHandling";
+
+try {
+  await someApiCall();
+} catch (err) {
+  await errorHandling(err); // 메시지 표시 자동 처리
+}
+```
+
+### 포맷터
+
+```typescript
+import { formatterNumber, formatterDate } from "@core/utils";
+
+// 숫자 포맷 (천단위 콤마)
+formatterNumber(1234567); // "1,234,567"
+
+// 날짜 포맷
+formatterDate("2024-01-15 10:30:00", "YYYY-MM-DD"); // "2024-01-15"
+```
+
+---
+
+## 요약
+
+이 가이드를 통해 다음과 같은 작업을 MCP 서버를 통해 자동화할 수 있습니다:
+
+1. **Repository 분석** → 인터페이스에서 타입 추출
+2. **Store 자동 생성** → 타입별 템플릿 적용
+3. **Hook 자동 생성** → API 호출 래핑
+4. **Component 자동 생성** → DataGrid, SearchParams 등
+5. **검색 폼 자동 생성** → SearchParams JSX
+
+MCP 서버는 이 패턴들을 참고하여 일관성 있는 코드를 생성합니다.