@axboot-mcp/mcp-server 1.0.0

package/src/docs/practical-examples.md

@@ -0,0 +1,732 @@
+# MCP-AXBoot 실전 예제 모음
+
+> 실제 프로젝트에서 자주 발생하는 시나리오별 Store 생성 예제입니다.
+
+## 목차
+
+1. [예제 1: 회원 관리 (CRUD)](#예제-1-회원-관리-crud)
+2. [예제 2: 상품 카테고리 (트리)](#예제-2-상품-카테고리-트리)
+3. [예제 3: 주문 관리 (마스터-디테일)](#예제-3-주문-관리-마스터-디테일)
+4. [예제 4: 대시보드 (다중 데이터)](#예제-4-대시보드-다중-데이터)
+5. [예제 5: 배치 처리 (체크박스)](#예제-5-배치-처리-체크박스)
+6. [예제 6: 게시판 (고정값)](#예제-6-게시판-고정값)
+
+---
+
+## 예제 1: 회원 관리 (CRUD)
+
+### 시나리오
+
+회원 목록을 조회하고, 선택한 회원의 상세 정보를 보여주며, 수정과 삭제가 가능한 페이지입니다.
+
+### Repository
+
+```typescript
+// services/MemberRepository.ts
+export interface MemberRepository {
+  postMemberListMember(request: PostMemberListMemberRequest): Promise<MemberListResponse>;
+  postMemberDetailMember(request: PostMemberDetailMemberRequest): Promise<MemberDetailResponse>;
+  postMemberSaveMember(request: PostMemberSaveMemberRequest): Promise<MemberSaveResponse>;
+  postMemberDeleteMember(request: PostMemberDeleteMemberRequest): Promise<void>;
+}
+```
+
+### 요구사항
+
+```
+회원 목록을 보여주고, 회원을 선택하면 상세 정보가 표시됩니다.
+상세 정보에서 수정과 삭제가 가능해야 합니다.
+엑셀 다운로드도 필요합니다.
+```
+
+### Claude 대화
+
+```
+👤 사용자:
+회원 목록 CRUD Store를 만들어줘.
+Repository는 services/MemberRepository.ts야.
+
+🤖 Claude:
+먼저 MemberRepository를 분석하겠습니다...
+
+분석 결과:
+- List 메서드: postMemberListMember ✓
+- Detail 메서드: postMemberDetailMember ✓
+- Save 메서드: postMemberSaveMember ✓
+- Delete 메서드: postMemberDeleteMember ✓
+
+추천 타입: Type 5 (CRUD) - 점수 0.95
+
+Store를 생성할까요?
+
+👤 사용자:
+응, 생성해줘. 출력은 stores/useMemberListStore.ts로 해줘.
+
+🤖 Claude:
+Store를 생성했습니다! 생성된 파일:
+stores/useMemberListStore.ts
+
+주요 기능:
+- 리스트 조회 (callListApi)
+- 상세 조회 (setListSelectedRowKey)
+- 저장 (callSaveApi)
+- 삭제 (callDeleteApi)
+- 엑셀 다운로드 (callExcelDownloadApi)
+```
+
+### 생성된 Store 코드
+
+```typescript
+// stores/useMemberListStore.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 { ProgramFn } from "@types";
+import {
+  MemberService,
+  PostMemberListMemberRequest,
+  MemberRes
+} from "services";
+import { getTabStoreListener } from "stores";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+
+interface ListRequest extends PostMemberListMemberRequest {}
+interface DtoItem extends MemberRes {}
+interface SaveRequest {
+  memberUuid?: string;
+  memberName?: string;
+  memberEmail?: string;
+  // ... other fields
+}
+
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  flexGrow: number;
+  saveRequestValue: SaveRequest;
+  detail?: SaveRequest;
+  formActive: boolean;
+  listCheckedKeys: React.Key[];
+}
+
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  saveSpinning: boolean;
+  detailSpinning: boolean;
+  deleteSpinning: boolean;
+}
+
+const createState: States = {
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+  },
+  listColWidths: [],
+  listSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+  listSortParams: [],
+  listSelectedRowKey: "",
+  flexGrow: 400,
+  saveRequestValue: {},
+  detail: undefined,
+  formActive: false,
+  listCheckedKeys: [],
+  saveSpinning: false,
+  detailSpinning: false,
+  deleteSpinning: false,
+};
+
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (pageNumber: number, pageSize?: number) => Promise<void>;
+  setListSelectedRowKey: (key?: React.Key, detail?: DtoItem) => void;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setSaveSpinning: (spinning: boolean) => void;
+  callSaveApi: (request?: SaveRequest) => Promise<void>;
+  callDeleteApi: (request?: SaveRequest) => Promise<void>;
+  cancelFormActive: () => void;
+  setFormActive: () => void;
+  setListCheckedKeys: (checkedKeys: React.Key[]) => void;
+  setFlexGrow: (flexGlow: number) => void;
+}
+
+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 }),
+  setListSpinning: (spinning) => set({ listSpinning: spinning }),
+  setListSortParams: (sortParams) => set({ listSortParams: sortParams }),
+
+  callListApi: async (request) => {
+    if (get().listSpinning) return;
+    set({ listSpinning: true });
+
+    try {
+      const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+      const response = await MemberService.postMemberList(
+        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,
+        },
+      });
+    } finally {
+      set({ listSpinning: false });
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+
+  setListSelectedRowKey: async (key, detail) => {
+    if (detail) {
+      set({ listSelectedRowKey: key, detail, saveRequestValue: { ...detail } });
+    } else {
+      set({ listSelectedRowKey: undefined, detail: undefined, saveRequestValue: undefined });
+    }
+  },
+
+  setSaveRequestValue: (saveRequestValue) => {
+    set({ saveRequestValue });
+  },
+
+  setSaveSpinning: (saveSpinning) => set({ saveSpinning: saveSpinning }),
+
+  callSaveApi: async (request) => {
+    if (get().saveSpinning) return;
+    set({ saveSpinning: true });
+
+    try {
+      const apiParam: SaveRequest = {
+        ...get().saveRequestValue,
+        ...request,
+      };
+
+      apiParam.__status__ = get().listSelectedRowKey ? "U" : "C";
+
+      const { rs } = await MemberService.postMemberSave(apiParam);
+      set({ saveRequestValue: rs, detail: rs });
+
+      await get().callListApi();
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  callDeleteApi: async (request) => {
+    if (get().deleteSpinning) return;
+    set({ deleteSpinning: true });
+
+    try {
+      const apiParam: SaveRequest = {
+        ...get().saveRequestValue,
+        ...request,
+        __status__: "D",
+      };
+
+      await MemberService.postMemberDelete(apiParam);
+      await get().callListApi();
+    } finally {
+      set({ deleteSpinning: false });
+    }
+  },
+
+  cancelFormActive: () => {
+    set({ formActive: false, listSelectedRowKey: undefined });
+  },
+
+  setFormActive: () => {
+    set({ formActive: true, detail: undefined, saveRequestValue: undefined });
+  },
+
+  setListCheckedKeys: (checkedKeys) => {
+    set({ listCheckedKeys: checkedKeys });
+  },
+
+  setFlexGrow: (flexGlow) => {
+    set({ flexGrow: flexGlow });
+  },
+});
+
+export interface memberListStore extends States, Actions, PageStoreActions<States> {}
+
+export const useMemberListStore = create(
+  subscribeWithSelector<memberListStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  }))
+);
+
+useMemberListStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSelectedRowKey: s.listSelectedRowKey,
+    flexGrow: s.flexGrow,
+    saveRequestValue: s.saveRequestValue,
+    detail: s.detail,
+    formActive: s.formActive,
+    listCheckedKeys: s.listCheckedKeys,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### 컴포넌트 사용 예시
+
+```tsx
+import React, { useEffect } from 'react';
+import { useMemberListStore } from './stores/useMemberListStore';
+
+export default function MemberListPage() {
+  const {
+    listData,
+    listPage,
+    listSpinning,
+    listSelectedRowKey,
+    detail,
+    formActive,
+    callListApi,
+    changeListPage,
+    setListSelectedRowKey,
+    setFormActive,
+    cancelFormActive,
+    callSaveApi,
+    callDeleteApi,
+  } = useMemberListStore();
+
+  useEffect(() => {
+    callListApi();
+  }, []);
+
+  const handleSave = async () => {
+    await callSaveApi();
+  };
+
+  const handleDelete = async () => {
+    await callDeleteApi();
+  };
+
+  return (
+    <div className="member-list-page">
+      {/* 검색 영역 */}
+      <SearchForm />
+
+      {/* 리스트 영역 */}
+      <MemberTable
+        data={listData}
+        page={listPage}
+        loading={listSpinning}
+        selectedRowKey={listSelectedRowKey}
+        onSelect={(key) => setListSelectedRowKey(key, detail)}
+        onChangePage={changeListPage}
+      />
+
+      {/* 상세/편집 영역 */}
+      {listSelectedRowKey && (
+        <MemberDetailForm
+          detail={detail}
+          formActive={formActive}
+          onSave={handleSave}
+          onDelete={handleDelete}
+          onEdit={setFormActive}
+          onCancel={cancelFormActive}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## 예제 2: 상품 카테고리 (트리)
+
+### 시나리오
+
+상품 카테고리를 트리 구조로 표시하고, 선택된 카테고리를 오른쪽 폼에서 편집합니다.
+
+### Repository
+
+```typescript
+// services/CategoryRepository.ts
+export interface CategoryRepository {
+  postCategoryListCtgrTree(request: PostCategoryListCtgrTreeRequest): Promise<CategoryTreeResponse>;
+  postCategorySaveCtgr(request: PostCategorySaveCtgrRequest): Promise<CategorySaveResponse>;
+}
+```
+
+### 요구사항
+
+```
+상품 카테고리를 트리로 표시하고, 선택된 카테고리의 정보를 편집할 수 있는 Store.
+검색어로 카테고리를 찾을 수 있어야 합니다.
+```
+
+### Claude 대화
+
+```
+👤 사용자:
+상품 카테고리용 Store를 만들어줘.
+트리 구조가 필요해.
+
+🤖 Claude:
+CategoryRepository를 분석하겠습니다...
+
+분석 결과:
+- Tree 메서드: postCategoryListCtgrTree ✓
+- Save 메서드: postCategorySaveCtgr ✓
+
+추천 타입: Type 6 (Tree + Form) - 점수 0.98
+
+Store를 생성할까요?
+
+👤 사용자:
+응, useProductCategoryStore.ts로 생성해줘.
+```
+
+### 생성된 Store (주요 부분)
+
+```typescript
+// stores/useProductCategoryStore.ts
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  flexGrow: number;
+  selectedItem?: DtoItem;
+  saveRequestValues?: DtoItem;
+  expandedKeys: number[] | string[];
+  categorySearch?: boolean;
+}
+
+interface States extends MetaData {
+  routePath?: string;
+  treeSpinning: boolean;
+  treeData: DtoItem[];
+  saveSpinning: boolean;
+  isDirty: boolean;
+  isFormDirty: boolean;
+}
+
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+
+  setFlexGrow: (flexGrow) => set({ flexGrow }),
+
+  callTreeApi: async (request) => {
+    set({ treeSpinning: true });
+    try {
+      if (request?.ctgrNm && request.ctgrNm !== "") {
+        // 검색어가 있으면 리스트 조회
+        const { ds: list } = await CategoryService.postCategoryList({
+          ctgrNm: request.ctgrNm,
+          pathDelim: " > ",
+        });
+        set({ treeData: list, categorySearch: true });
+      } else {
+        // 없으면 트리 조회
+        const { ds: tree } = await CategoryService.postCategoryListTree({});
+        set({ treeData: tree, categorySearch: false });
+      }
+    } finally {
+      set({ treeSpinning: false });
+    }
+  },
+
+  setSelectedItem: (item) => {
+    set({ selectedItem: item, saveRequestValues: { ...item } });
+  },
+
+  setTreeData: (treeData) => set({ treeData }),
+
+  setExpandedKeys: (expandedKeys) => set({ expandedKeys }),
+
+  setSaveRequestValues: (saveRequestValues) => {
+    set({ saveRequestValues });
+  },
+
+  setListRequestValue: (requestValues) => {
+    set({ listRequestValue: requestValues });
+  },
+
+  setCategorySearch: (search) => set({ categorySearch: search }),
+
+  callTreeSaveApi: async (treeData) => {
+    set({ saveSpinning: true });
+    try {
+      await CategoryService.postCategorySave({ treeData });
+      await get().callTreeApi({});
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  setIsDirty: (dirty) => set({ isDirty: dirty }),
+});
+```
+
+---
+
+## 예제 3: 주문 관리 (마스터-디테일)
+
+### 시나리오
+
+주문 목록에서 주문을 선택하면 하단에 해당 주문의 상세 내역이 표시됩니다.
+
+### 요구사항
+
+```
+주문 목록과 상세 내역이 있는 Store.
+상단에 주문 목록, 하단에 선택된 주문의 상세 내역이 표시되어야 함.
+```
+
+### 추천 타입
+
+**Type 4: Master-Detail**
+
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  listCheckedIndexes?: number[];
+}
+```
+
+---
+
+## 예제 4: 대시보드 (다중 데이터)
+
+### 시나리오
+
+회원 대시보드 페이지. 상단에 가입/탈퇴 통계가 표시되고, 하단에 탭으로 구분된 회원 목록들이 있습니다.
+
+### 요구사항
+
+```
+회원 대시보드 Store.
+- 상단: 회원 통계 (가입자수, 탈퇴자수 등)
+- 하단: 탭1 - 가입 회원 목록, 탭2 - 탈퇴 회원 목록
+- 각 목록은 엑셀 다운로드 가능
+```
+
+### 추천 타입
+
+**Type 7: Dashboard**
+
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  summaryRequestValue: SummaryRequest;
+  listRequest01Value: ListRequest01;
+  listRequest02Value: ListRequest02;
+  activeTabKey: PanelType;
+  list01SortParams: AXDGSortParam[];
+  list02SortParams: AXDGSortParam[];
+}
+
+interface States extends MetaData {
+  routePath?: string;
+  spinning: boolean;
+  summaryData: DtoItem;
+  list01Data: AXDGDataItem<DtoItem01>[];
+  list01Page: AXDGPage;
+  list02Data: AXDGDataItem<DtoItem02>[];
+  list02Page: AXDGPage;
+  summarySpinning: boolean;
+  list01Spinning: boolean;
+  list02Spinning: boolean;
+}
+```
+
+---
+
+## 예제 5: 배치 처리 (체크박스)
+
+### 시나리오
+
+상품 목록에서 체크박스로 여러 상품을 선택하고, 일괄적으로 전시/비전시 상태를 변경합니다.
+
+### 요구사항
+
+```
+상품 목록에서 체크박스로 여러 상품을 선택하여
+일괄 상태 변경(전시/비전시/판매중/품절/판매중지)이 가능한 Store.
+```
+
+### 추천 타입
+
+**Type 9: Status Change**
+
+```typescript
+interface Actions extends PageStoreActions<States> {
+  // ... 기본 액션들
+  callChangeStatusApi: (changeStatus: string) => void;
+  callDeleteApi: (selectedItems: string | React.Key[]) => void;
+  callDataCopyApi: (prdCd: string) => Promise<void>;
+}
+
+// 구현 예시
+callChangeStatusApi: async (changeStatus) => {
+  const selectedPrdCds = get().checkedRowKeys as string[];
+  if (!selectedPrdCds || selectedPrdCds.length === 0) return;
+
+  if (get().updateSpinning) return;
+  set({ updateSpinning: true });
+
+  try {
+    switch (changeStatus) {
+      case "전시":
+        await ProductService.postProductSavePrdDspyY({ prdCds: selectedPrdCds });
+        break;
+      case "비전시":
+        await ProductService.postProductSavePrdDspN({ prdCds: selectedPrdCds });
+        break;
+      case "판매중":
+        await ProductService.postProductSavePrdSleSttus10({ prdCds: selectedPrdCds });
+        break;
+      case "품절":
+        await ProductService.postProductSavePrdSleSttus20({ prdCds: selectedPrdCds });
+        break;
+      case "판매중지":
+        await ProductService.postProductSavePrdSleSttus50({ prdCds: selectedPrdCds });
+        break;
+      default:
+        console.warn("알 수 없는 상태 변경 요청:", changeStatus);
+    }
+  } finally {
+    set({ updateSpinning: false });
+  }
+},
+```
+
+---
+
+## 예제 6: 게시판 (고정값)
+
+### 시나리오
+
+특정 게시판(bbsNo=26)의 게시글 목록을 표시하는 페이지입니다.
+
+### 요구사항
+
+```
+bbsNo가 26인 공지사항 게시판의 목록을 보여주는 Store.
+게시글은 제목, 작성일, 조회수 등을 표시.
+```
+
+### 추천 타입
+
+**Type 10: Fixed Value Based** (또는 Type 1 + 고정값)
+
+```typescript
+const bbsNo = 26; // 고정값
+
+const createState: States = {
+  bbsNo, // States에 포함
+  listRequestValue: {
+    bbsNo, // listRequestValue에도 포함
+    pageNumber: 1,
+    pageSize: 100,
+  },
+  // ...
+};
+
+// API 호출 시 사용
+callListApi: async (request) => {
+  const apiParam = {
+    ...get().listRequestValue,
+    ...request,
+    bbsNo: get().bbsNo, // 고정값 사용
+  };
+  // ...
+},
+```
+
+---
+
+## 팁: 생성 후 확인사항
+
+모든 예제에서 Store 생성 후 다음을 확인하세요:
+
+### 1. 초기 검색조건 설정
+
+```typescript
+const createState: States = {
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    // 필요한 검색조건 추가
+    searchKeyword: "",
+    searchStatus: "ALL",
+    dateRange: undefined,
+  },
+  // ...
+};
+```
+
+### 2. Service 메서드명 확인
+
+```typescript
+// 생성된 코드
+const response = await MemberService.postMemberList(apiParam);
+
+// 실제 Service 메서드명으로 변경
+const response = await MemberService.postMemberListMember(apiParam);
+```
+
+### 3. 타입 정의 확인
+
+```typescript
+// Repository Request 타입 확인
+interface ListRequest extends PostMemberListMemberRequest {
+  // 추가 필드
+  dateRange?: [string, string];
+}
+```
+
+### 4. TODO 주석 구현
+
+```typescript
+// TODO: 삭제 API 호출 구현 필요
+// await MemberService.removeMember({ id });
+
+// → 실제 구현
+await MemberService.postMemberDelete({
+  memberUuid: id,
+  __status__: "D",
+});
+```