@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/Store-/355/214/250/355/204/264-/354/202/254/354/232/251/353/262/225.md

@@ -0,0 +1,1135 @@
+# Zustand Store 패턴 사용법 가이드
+
+AXBoot에서 사용하는 Zustand 기반 Store 패턴에 대한 상세 가이드입니다. NH 프로젝트의 실제 Store 파일들을 분석하여 다양한 케이스별 사용법을 제시합니다.
+
+## 목차
+1. [개요](#개요)
+2. [기본 구조](#기본-구조)
+3. [케이스별 Store 패턴](#케이스별-store-패턴)
+4. [공통 인터페이스](#공통-인터페이스)
+5. [메타데이터 관리](#메타데이터-관리)
+6. [실제 구현 예제](#실제-구현-예제)
+7. [고급 패턴](#고급-패턴)
+8. [성능 최적화](#성능-최적화)
+
+## 개요
+
+### Store 시스템의 특징
+- **Zustand 기반**: 가벼운 상태 관리 라이브러리
+- **TypeScript 완전 지원**: 타입 안정성 보장
+- **페이지별 분리**: 각 페이지마다 독립적인 Store
+- **메타데이터 영속화**: 탭 간 상태 유지
+- **표준화된 패턴**: 일관성 있는 구조
+
+### 핵심 컴포넌트
+- **States**: 상태 인터페이스 정의
+- **Actions**: 액션 인터페이스 정의
+- **MetaData**: 영속화할 데이터 정의
+- **PageStoreActions**: 공통 페이지 액션
+- **TabStoreListener**: 탭 상태 동기화
+
+## 기본 구조
+
+### 1. Store 파일 구조
+
+```typescript
+// 1. 필요한 imports
+import { AXDGDataItem, AXDGPage, AXDGSortParam } from "@axboot/datagrid";
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+import { PageStoreActions, StoreActions } from "@core/stores/types";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+
+// 2. Request/Response 인터페이스
+interface ListRequest extends ServiceRequestType {}
+interface DtoItem extends ServiceResponseType {}
+interface SaveRequest {}
+
+// 3. MetaData 정의 (영속화 대상)
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  // ... 기타 영속화할 상태들
+}
+
+// 4. States 정의
+interface States extends MetaData {
+  loadedStore: boolean;
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  // ... 기타 임시 상태들
+}
+
+// 5. Actions 정의
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  // ... 기타 액션들
+}
+
+// 6. 초기 상태
+const createState: States = {
+  // 초기값 설정
+};
+
+// 7. Actions 구현
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // 액션 구현
+});
+
+// 8. Store 생성 및 구독
+export const useYourStore = create(
+  subscribeWithSelector<YourStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  }))
+);
+
+// 9. 메타데이터 구독 설정
+useYourStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    // 영속화할 상태들만 선택
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow }
+);
+```
+
+## 케이스별 Store 패턴
+
+### 1. 기본 목록 관리 Store (Basic List Pattern)
+
+**사용 케이스**: 단순한 목록 조회 및 페이징
+**예시**: `useProductMasterStore.ts`
+
+```typescript
+// 기본 목록 관리 패턴
+interface ListRequest extends PostProductGroupMasterListRequest {}
+interface DtoItem extends ProdgrpMst {}
+
+interface States extends MetaData {
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  listSelectedRowKey?: React.Key;
+}
+
+interface Actions {
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+  setListSelectedRowKey: (key?: React.Key) => void;
+}
+
+const createActions = (set, get) => ({
+  callListApi: async (request) => {
+    if (get().listSpinning) return;
+    set({ listSpinning: true });
+
+    try {
+      const apiParam = { ...get().listRequestValue, ...request };
+      const response = await ServiceClass.callApi(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: (key) => {
+    set({ listSelectedRowKey: key });
+  }
+});
+```
+
+**특징**:
+- 페이징 지원
+- 로딩 상태 관리
+- 선택된 행 추적
+
+---
+
+### 2. 상세 정보 포함 Store (Master-Detail Pattern)
+
+**사용 케이스**: 목록에서 선택한 항목의 상세 정보 표시
+**예시**: `useMemberListStore.ts`
+
+```typescript
+interface States extends MetaData {
+  listData: AXDGDataItem<DtoItem>[];
+  selectedItem?: DtoItem;
+  detailLoading: boolean;
+  saveRequestValue: SaveRequest;
+  checkedRowKeys: React.Key[];
+}
+
+interface Actions {
+  setSelectedItem: (selectedItem?: DtoItem) => Promise<void>;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+}
+
+const createActions = (set, get) => ({
+  setSelectedItem: async (selectedItem) => {
+    set({ selectedItem, detailLoading: true });
+
+    if (!selectedItem) {
+      set({ saveRequestValue: {} });
+    } else {
+      // 상세 정보 로딩 로직
+      const detailData = await loadDetailData(selectedItem.id);
+      set({ saveRequestValue: detailData });
+    }
+
+    await delay(300); // UX 개선을 위한 지연
+    set({ detailLoading: false });
+  },
+
+  setSaveRequestValue: (saveRequestValue) => {
+    set({ saveRequestValue });
+  },
+
+  setCheckedRowKeys: (checkedRowKeys) => {
+    set({ checkedRowKeys });
+  }
+});
+```
+
+**특징**:
+- 선택 항목 상세 로딩
+- 저장용 데이터 관리
+- 다중 선택 지원
+- 로딩 상태 분리
+
+---
+
+### 3. 날짜 범위 검색 Store (Date Range Search Pattern)
+
+**사용 케이스**: 날짜 범위 기반 검색 기능
+**예시**: `useBenefitCouponStore.ts`, `useCsFaqStore.ts`
+
+```typescript
+interface ListRequest extends ServiceRequest {
+  dateRange?: [string, string];
+}
+
+const createState: States = {
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    dateRange: [
+      dayjs().add(-1, "month").format("YYYY-MM-DD"),
+      dayjs().format("YYYY-MM-DD")
+    ],
+  },
+  // ... 기타 초기값
+};
+
+const createActions = (set, get) => ({
+  callListApi: async (request) => {
+    const apiParam = { ...get().listRequestValue, ...request };
+
+    // 날짜 범위를 API 형식으로 변환
+    const response = await ServiceClass.callApi(
+      deleteEmptyValue({
+        ...apiParam,
+        ...dateRangeToDts(apiParam.dateRange, {
+          startDateTime: DT_FORMAT.DATE + " 00:00:00",
+          endDateTime: DT_FORMAT.DATE + " 23:59:59",
+        }),
+      })
+    );
+
+    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,
+      },
+    });
+  }
+});
+```
+
+**특징**:
+- 날짜 범위 기본값 설정
+- 자동 날짜 포맷 변환
+- 시작/종료 시간 자동 설정
+
+---
+
+### 4. 복합 조건 검색 Store (Complex Search Pattern)
+
+**사용 케이스**: 다중 조건 검색 및 필터링
+**예시**: `useMemberListStore.ts`
+
+```typescript
+interface ListRequest extends PostMemberListMemberRequest {
+  visitCount?: string[]; // 방문 횟수 범위
+  dateRange?: [string, string]; // 날짜 범위
+}
+
+const createActions = (set, get) => ({
+  callListApi: async (request) => {
+    const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+
+    // 방문 횟수 범위 처리
+    if (isEmpty(apiParam.visitCount)) {
+      apiParam.mummTmnum = undefined;
+      apiParam.mxmmTmnum = undefined;
+    } else {
+      apiParam.mummTmnum = parseInt(apiParam.visitCount?.[0] ?? "0");
+      apiParam.mxmmTmnum = parseInt(apiParam.visitCount?.[1] ?? "99999999");
+    }
+
+    const response = await MemberService.postMemberListMember(
+      deleteEmptyValue({
+        ...apiParam,
+        ...dateRangeToDts(apiParam.dateRange, {
+          bgnDtm: "YYYY-MM-DD 00:00:00",
+          endDtm: "YYYY-MM-DD 23:59:59",
+        }),
+      })
+    );
+
+    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,
+      },
+    });
+  }
+});
+```
+
+**특징**:
+- 복합 검색 조건 처리
+- 조건별 데이터 변환
+- 빈 값 필터링
+
+---
+
+### 5. 삭제 기능 포함 Store (Bulk Delete Pattern)
+
+**사용 케이스**: 체크박스 선택 후 일괄 삭제
+**예시**: `useSystemSeoStore.ts`
+
+```typescript
+interface States extends MetaData {
+  listCheckedIndexes?: number[];
+}
+
+interface Actions {
+  setListCheckedIndexes: (indexes?: number[]) => void;
+  callDeleteApi: (indexes: number[]) => Promise<void>;
+}
+
+const createActions = (set, get) => ({
+  setListCheckedIndexes: (indexes) => {
+    set({ listCheckedIndexes: indexes });
+  },
+
+  callDeleteApi: async (indexes) => {
+    const deleteListData = get().listData.filter((r, index) => {
+      return indexes.includes(index);
+    });
+
+    // 순차적 삭제 처리
+    for await (const _r of deleteListData) {
+      try {
+        await SsSystemService.postSsSystemDeleteSeo({
+          seoNo: _r.values.seoNo,
+        });
+      } catch (e) {
+        await errorHandling(e);
+      }
+    }
+
+    set({ listCheckedIndexes: [] }); // 선택 초기화
+  }
+});
+```
+
+**특징**:
+- 체크된 인덱스 관리
+- 순차적 삭제 처리
+- 에러 핸들링
+- 삭제 후 선택 초기화
+
+---
+
+### 6. 동적 탭 Store (Dynamic Tab Pattern)
+
+**사용 케이스**: 탭에 따른 동적 데이터 로딩
+**예시**: `useDisplayBannerMenuStore.ts`
+
+```typescript
+interface MetaData {
+  bannerLocTp: BannerLocTp[]; // 탭 목록
+  activeBannerLocTp?: string; // 활성 탭
+}
+
+interface Actions {
+  setActiveBannerLocTp: (bannerLocTpcd?: string) => void;
+}
+
+const createActions = (set, get) => ({
+  onMountApp: async () => {
+    // 탭 목록 로딩
+    const { ds } = await BannerService.postBannerListBannerLocTp();
+    set({ bannerLocTp: ds });
+
+    // 기본 탭 설정
+    if (!get().activeBannerLocTp || !ds.find(n => n.bannerLocTpcd === get().activeBannerLocTp)) {
+      set({ activeBannerLocTp: ds[0].bannerLocTpcd });
+    }
+  },
+
+  setActiveBannerLocTp: (bannerLocTpcd) => {
+    set({ activeBannerLocTp: bannerLocTpcd });
+  },
+
+  callListApi: async (request) => {
+    const bannerLocTpcd = get().activeBannerLocTp;
+    const apiParam = { ...get().listRequestValue, ...request, bannerLocTpcd };
+
+    // 탭별 조건부 로직
+    if (apiParam.bannerLocTpcd === "1" && !apiParam.ctgrNo) {
+      set({ listData: [] });
+      throw new Error("카테고리를 선택해주세요.");
+    }
+
+    const response = await BannerService.postBannerListBanner(apiParam);
+
+    set({
+      listRequestValue: apiParam,
+      listData: response.ds.map((values) => ({ values })),
+    });
+  }
+});
+```
+
+**특징**:
+- 동적 탭 목록 로딩
+- 탭별 조건부 로직
+- 기본 탭 자동 설정
+- 탭 변경 시 데이터 갱신
+
+---
+
+## 공통 인터페이스
+
+### 1. PageStoreActions
+
+모든 Store에서 공통으로 사용하는 액션들:
+
+```typescript
+interface PageStoreActions<T> {
+  syncMetadata: (metadata?: T) => void;
+  onMountApp: () => Promise<void>;
+  resetStore: () => void;
+  setRouterPath: (path: string) => void;
+}
+```
+
+### 2. StoreActions 타입
+
+```typescript
+type StoreActions<T, A> = (
+  set: (partial: T | Partial<T> | ((state: T) => T | Partial<T>)) => void,
+  get: () => T
+) => A;
+```
+
+### 3. MetaData 패턴
+
+영속화할 데이터를 정의:
+
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;           // 프로그램 권한 정보
+  listRequestValue: ListRequest;   // 검색 조건
+  listColWidths: number[];         // 컬럼 너비
+  listSortParams: AXDGSortParam[]; // 정렬 정보
+  // ... 기타 영속화 필요한 상태들
+}
+```
+
+## 메타데이터 관리
+
+### 1. 탭 스토어 리스너
+
+```typescript
+useYourStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    // 영속화할 상태만 선택
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow }
+);
+```
+
+### 2. 메타데이터 동기화
+
+```typescript
+const createActions = (set, get) => ({
+  syncMetadata: (s = createState) => {
+    set(s); // 저장된 메타데이터로 상태 복원
+  },
+
+  resetStore: () => {
+    set(createState); // 초기 상태로 리셋
+  }
+});
+```
+
+## 실제 구현 예제
+
+### 1. 회원 관리 Store 완전 구현
+
+```typescript
+// useMemberManagementStore.ts
+import { AXDGDataItem, AXDGPage, AXDGSortParam } from "@axboot/datagrid";
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+import { PageStoreActions, StoreActions } from "@core/stores/types";
+import { delay } from "@core/utils";
+import { deleteEmptyValue } from "@core/utils/object";
+import { ProgramFn } from "@types";
+import { MemberRes, MemberService, PostMemberListRequest } 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 PostMemberListRequest {
+  dateRange?: [string, string];
+  statusFilter?: string[];
+}
+
+interface DtoItem extends MemberRes {}
+
+interface SaveRequest {
+  memberNo?: number;
+  memberName?: string;
+  email?: string;
+  status?: string;
+}
+
+// 2. MetaData 정의
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  saveRequestValue: SaveRequest;
+  activeTab: string;
+}
+
+// 3. States 정의
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  selectedItem?: DtoItem;
+  detailLoading: boolean;
+  checkedRowKeys: React.Key[];
+  saveSpinning: boolean;
+}
+
+// 4. Actions 정의
+interface Actions extends PageStoreActions<States> {
+  // 검색 관련
+  setListRequestValue: (requestValue: ListRequest) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+
+  // 선택 관련
+  setSelectedItem: (selectedItem?: DtoItem) => Promise<void>;
+  setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+
+  // 저장 관련
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  callSaveApi: () => Promise<void>;
+  callDeleteApi: (memberNos: number[]) => Promise<void>;
+
+  // UI 관련
+  setListColWidths: (colWidths: number[]) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  setActiveTab: (tab: string) => void;
+}
+
+// 5. 초기 상태
+const createState: States = {
+  routePath: "/member/management",
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    searchType: "NAME",
+    dateRange: [
+      dayjs().add(-1, "month").format("YYYY-MM-DD"),
+      dayjs().format("YYYY-MM-DD")
+    ],
+    statusFilter: ["ACTIVE"]
+  },
+  listColWidths: [],
+  listSpinning: false,
+  listData: [],
+  listPage: {
+    currentPage: 0,
+    totalPages: 0,
+  },
+  listSortParams: [],
+  saveRequestValue: {},
+  detailLoading: false,
+  checkedRowKeys: [],
+  saveSpinning: false,
+  activeTab: "basic"
+};
+
+// 6. Actions 구현
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // 공통 액션 포함
+  ...pageStoreActions(set, get, { createState }),
+
+  syncMetadata: (s = createState) => set(s),
+
+  onMountApp: async () => {
+    // 초기화 로직
+    await get().callListApi();
+  },
+
+  // 검색 관련 액션
+  setListRequestValue: (requestValues) => {
+    set({ listRequestValue: requestValues });
+  },
+
+  callListApi: async (request) => {
+    if (get().listSpinning) return;
+    set({ listSpinning: true });
+
+    try {
+      const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+
+      // 상태 필터 처리
+      const statusCondition = apiParam.statusFilter?.join(",") || "";
+
+      const response = await MemberService.postMemberList(
+        deleteEmptyValue({
+          ...apiParam,
+          status: statusCondition,
+          ...dateRangeToDts(apiParam.dateRange, {
+            startDate: "YYYY-MM-DD",
+            endDate: "YYYY-MM-DD",
+          }),
+        })
+      );
+
+      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 (error) {
+      console.error("목록 조회 실패:", error);
+    } finally {
+      set({ listSpinning: false });
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+
+  // 선택 관련 액션
+  setSelectedItem: async (selectedItem) => {
+    set({ selectedItem, detailLoading: true });
+
+    if (!selectedItem) {
+      set({ saveRequestValue: {} });
+    } else {
+      // 상세 정보 로딩
+      try {
+        const detailResponse = await MemberService.getMemberDetail({
+          memberNo: selectedItem.memberNo
+        });
+        set({ saveRequestValue: detailResponse });
+      } catch (error) {
+        console.error("상세 조회 실패:", error);
+      }
+    }
+
+    await delay(300);
+    set({ detailLoading: false });
+  },
+
+  setCheckedRowKeys: (checkedRowKeys) => {
+    set({ checkedRowKeys });
+  },
+
+  // 저장 관련 액션
+  setSaveRequestValue: (saveRequestValue) => {
+    set({ saveRequestValue });
+  },
+
+  callSaveApi: async () => {
+    const { saveRequestValue, selectedItem } = get();
+    set({ saveSpinning: true });
+
+    try {
+      if (selectedItem?.memberNo) {
+        // 수정
+        await MemberService.putMemberUpdate({
+          ...saveRequestValue,
+          memberNo: selectedItem.memberNo
+        });
+      } else {
+        // 신규 등록
+        await MemberService.postMemberCreate(saveRequestValue);
+      }
+
+      // 목록 새로고침
+      await get().callListApi();
+      set({ selectedItem: undefined, saveRequestValue: {} });
+
+    } catch (error) {
+      console.error("저장 실패:", error);
+      throw error;
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  callDeleteApi: async (memberNos) => {
+    try {
+      for (const memberNo of memberNos) {
+        await MemberService.deleteMember({ memberNo });
+      }
+
+      // 목록 새로고침
+      await get().callListApi();
+      set({ checkedRowKeys: [] });
+
+    } catch (error) {
+      console.error("삭제 실패:", error);
+      throw error;
+    }
+  },
+
+  // UI 관련 액션
+  setListColWidths: (colWidths) => {
+    set({ listColWidths: colWidths });
+  },
+
+  setListSortParams: (sortParams) => {
+    set({ listSortParams: sortParams });
+  },
+
+  setActiveTab: (activeTab) => {
+    set({ activeTab });
+  }
+});
+
+// 7. Store 생성
+export interface memberManagementStore extends States, Actions, PageStoreActions<States> {}
+
+export const useMemberManagementStore = create(
+  subscribeWithSelector<memberManagementStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  }))
+);
+
+// 8. 메타데이터 구독 설정
+useMemberManagementStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    saveRequestValue: s.saveRequestValue,
+    activeTab: s.activeTab
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow }
+);
+```
+
+### 2. Store 사용법 (컴포넌트에서)
+
+```tsx
+// MemberManagementPage.tsx
+import React from 'react';
+import { useMemberManagementStore } from './useMemberManagementStore';
+
+export function MemberManagementPage() {
+  // Store 상태 및 액션 구독
+  const listData = useMemberManagementStore(s => s.listData);
+  const listSpinning = useMemberManagementStore(s => s.listSpinning);
+  const selectedItem = useMemberManagementStore(s => s.selectedItem);
+  const listRequestValue = useMemberManagementStore(s => s.listRequestValue);
+
+  const callListApi = useMemberManagementStore(s => s.callListApi);
+  const setListRequestValue = useMemberManagementStore(s => s.setListRequestValue);
+  const setSelectedItem = useMemberManagementStore(s => s.setSelectedItem);
+
+  // 컴포넌트 마운트 시 초기화
+  React.useEffect(() => {
+    callListApi();
+  }, [callListApi]);
+
+  // 검색 핸들러
+  const handleSearch = (searchParams: any) => {
+    setListRequestValue({
+      ...listRequestValue,
+      ...searchParams,
+      pageNumber: 1 // 검색 시 첫 페이지로
+    });
+    callListApi({
+      ...searchParams,
+      pageNumber: 1
+    });
+  };
+
+  // 행 선택 핸들러
+  const handleRowClick = (record: any) => {
+    setSelectedItem(record.values);
+  };
+
+  return (
+    <div>
+      {/* 검색 폼 */}
+      <SearchForm
+        onSearch={handleSearch}
+        initialValues={listRequestValue}
+      />
+
+      {/* 데이터 그리드 */}
+      <DataGrid
+        loading={listSpinning}
+        data={listData}
+        onRowClick={handleRowClick}
+        selectedItem={selectedItem}
+      />
+
+      {/* 상세 정보 */}
+      {selectedItem && (
+        <DetailPanel member={selectedItem} />
+      )}
+    </div>
+  );
+}
+```
+
+## 고급 패턴
+
+### 1. 조건부 Store 액션
+
+```typescript
+const createActions = (set, get) => ({
+  callListApi: async (request, options = {}) => {
+    const { skipLoading = false, resetPage = false } = options;
+
+    if (!skipLoading && get().listSpinning) return;
+
+    if (!skipLoading) {
+      set({ listSpinning: true });
+    }
+
+    try {
+      let apiParam = { ...get().listRequestValue, ...request };
+
+      if (resetPage) {
+        apiParam.pageNumber = 1;
+      }
+
+      const response = await ServiceClass.callApi(apiParam);
+
+      set({
+        listRequestValue: apiParam,
+        listData: response.ds.map(values => ({ values })),
+        listPage: response.page,
+      });
+    } finally {
+      if (!skipLoading) {
+        set({ listSpinning: false });
+      }
+    }
+  }
+});
+```
+
+### 2. 캐싱 패턴
+
+```typescript
+interface States {
+  cache: Map<string, any>;
+  cacheExpiry: Map<string, number>;
+}
+
+const createActions = (set, get) => ({
+  getCachedData: async (key: string, fetcher: () => Promise<any>, ttl = 5 * 60 * 1000) => {
+    const cache = get().cache;
+    const cacheExpiry = get().cacheExpiry;
+    const now = Date.now();
+
+    // 캐시 확인
+    if (cache.has(key) && cacheExpiry.get(key)! > now) {
+      return cache.get(key);
+    }
+
+    // 데이터 페치
+    const data = await fetcher();
+
+    // 캐시 저장
+    cache.set(key, data);
+    cacheExpiry.set(key, now + ttl);
+
+    set({ cache, cacheExpiry });
+    return data;
+  }
+});
+```
+
+### 3. 낙관적 업데이트 패턴
+
+```typescript
+const createActions = (set, get) => ({
+  updateItemOptimistic: async (itemId: string, updates: Partial<DtoItem>) => {
+    const { listData } = get();
+
+    // 즉시 UI 업데이트
+    const optimisticData = listData.map(item =>
+      item.values.id === itemId
+        ? { ...item, values: { ...item.values, ...updates } }
+        : item
+    );
+
+    set({ listData: optimisticData });
+
+    try {
+      // 서버 업데이트
+      await ServiceClass.updateItem({ id: itemId, ...updates });
+    } catch (error) {
+      // 실패 시 롤백
+      set({ listData });
+      throw error;
+    }
+  }
+});
+```
+
+### 4. 무한 스크롤 패턴
+
+```typescript
+interface States {
+  hasMore: boolean;
+  loadingMore: boolean;
+}
+
+const createActions = (set, get) => ({
+  loadMore: async () => {
+    const { listRequestValue, listData, hasMore, loadingMore } = get();
+
+    if (!hasMore || loadingMore) return;
+
+    set({ loadingMore: true });
+
+    try {
+      const nextPage = listRequestValue.pageNumber + 1;
+      const response = await ServiceClass.callApi({
+        ...listRequestValue,
+        pageNumber: nextPage
+      });
+
+      set({
+        listRequestValue: { ...listRequestValue, pageNumber: nextPage },
+        listData: [...listData, ...response.ds.map(values => ({ values }))],
+        hasMore: response.ds.length === listRequestValue.pageSize,
+        loadingMore: false
+      });
+    } catch (error) {
+      set({ loadingMore: false });
+      throw error;
+    }
+  }
+});
+```
+
+## 성능 최적화
+
+### 1. 선택적 구독
+
+```typescript
+// 전체 상태 구독 (지양)
+const store = useMemberManagementStore();
+
+// 필요한 상태만 구독 (권장)
+const listData = useMemberManagementStore(s => s.listData);
+const listSpinning = useMemberManagementStore(s => s.listSpinning);
+
+// 복수 상태를 하나의 selector로
+const { listData, listSpinning } = useMemberManagementStore(
+  s => ({ listData: s.listData, listSpinning: s.listSpinning }),
+  shallow // 얕은 비교로 불필요한 렌더링 방지
+);
+```
+
+### 2. 메모이제이션
+
+```typescript
+// computed 상태 메모이제이션
+const filteredData = useMemberManagementStore(
+  s => s.listData.filter(item =>
+    s.listRequestValue.statusFilter?.includes(item.values.status)
+  ),
+  shallow
+);
+
+// 액션 메모이제이션
+const actions = useMemberManagementStore(
+  s => ({
+    callListApi: s.callListApi,
+    setSelectedItem: s.setSelectedItem,
+    setListRequestValue: s.setListRequestValue
+  }),
+  shallow
+);
+```
+
+### 3. 배치 업데이트
+
+```typescript
+const createActions = (set, get) => ({
+  batchUpdate: (updates: Array<{ key: string, value: any }>) => {
+    // 여러 상태를 한 번에 업데이트
+    const batchedUpdates = updates.reduce((acc, { key, value }) => {
+      acc[key] = value;
+      return acc;
+    }, {} as any);
+
+    set(batchedUpdates);
+  }
+});
+```
+
+### 4. 디바운싱
+
+```typescript
+import { debounce } from 'lodash';
+
+const createActions = (set, get) => {
+  const debouncedSearch = debounce(async (searchTerm: string) => {
+    await get().callListApi({ searchTerm });
+  }, 300);
+
+  return {
+    setSearchTerm: (searchTerm: string) => {
+      set({ searchTerm });
+      debouncedSearch(searchTerm);
+    }
+  };
+};
+```
+
+## 에러 처리 및 디버깅
+
+### 1. 에러 처리 패턴
+
+```typescript
+const createActions = (set, get) => ({
+  callListApi: async (request) => {
+    set({ listSpinning: true, error: null });
+
+    try {
+      const response = await ServiceClass.callApi(request);
+      set({
+        listData: response.ds.map(values => ({ values })),
+        listPage: response.page,
+      });
+    } catch (error) {
+      console.error('API 호출 실패:', error);
+      set({
+        error: error.message,
+        listData: [],
+        listPage: { currentPage: 0, totalPages: 0 }
+      });
+
+      // 에러 처리 서비스 호출
+      await errorHandling(error);
+    } finally {
+      set({ listSpinning: false });
+    }
+  }
+});
+```
+
+### 2. 개발 모드 디버깅
+
+```typescript
+// 개발 환경에서만 로깅
+const createActions = (set, get) => ({
+  callListApi: async (request) => {
+    if (process.env.NODE_ENV === 'development') {
+      console.group('🔍 Store Debug: callListApi');
+      console.log('Request:', request);
+      console.log('Current State:', get());
+      console.groupEnd();
+    }
+
+    // API 호출 로직...
+  }
+});
+
+// Zustand devtools 연동 (개발 환경)
+export const useMemberManagementStore = create<memberManagementStore>()(
+  process.env.NODE_ENV === 'development'
+    ? devtools(
+        subscribeWithSelector((set, get) => ({
+          ...createState,
+          ...createActions(set, get),
+        })),
+        { name: 'MemberManagementStore' }
+      )
+    : subscribeWithSelector((set, get) => ({
+        ...createState,
+        ...createActions(set, get),
+      }))
+);
+```
+
+이 가이드를 통해 AXBoot의 Zustand Store 패턴을 효과적으로 활용하여 일관성 있고 유지보수 가능한 상태 관리를 구현할 수 있습니다.