@axboot-mcp/mcp-server 1.0.0

package/STORE_PATTERNS.md

@@ -0,0 +1,1178 @@
+# NH Store 생성 가이드
+
+이 문서는 `src/pages/resources/NH` 하위 Store 파일들의 createActions 영역 API 연결 패턴을 분석하여 정리한 것입니다.
+
+---
+
+## 목차
+
+1. [기본 구조](#기본-구조)
+2. [Spinning State 종류](#spinning-state-종류)
+3. [API 패턴별 상세](#api-패턴별-상세)
+   - [Pattern 1: List Only](#pattern-1-list-only)
+   - [Pattern 2: List + Detail](#pattern-2-list--detail)
+   - [Pattern 3: List + Delete](#pattern-3-list--delete)
+   - [Pattern 4: List + Save](#pattern-4-list--save)
+   - [Pattern 5: List + Excel](#pattern-5-list--excel)
+   - [Pattern 6: Tree](#pattern-6-tree)
+   - [Pattern 7: Master-Detail + SubList](#pattern-7-master-detail--sublist)
+   - [Pattern 8: List + Modal](#pattern-8-list--modal)
+4. [공통 헬퍼 함수](#공통-헬퍼-함수)
+5. [공통 Setter 메서드](#공통-setter-메서드)
+
+---
+
+## 기본 구조
+
+모든 Store는 다음 기본 구조를 따릅니다:
+
+```typescript
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+import { PageStoreActions, StoreActions } from "@core/stores/types";
+import { deleteEmptyValue } from "@core/utils/object";
+import { ProgramFn } from "@types";
+import { XxxService, XxxRequest, XxxResponse } from "services";
+import { getTabStoreListener } from "stores";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+
+// DTO 타입 정의
+interface DtoItem extends XxxDto {}
+
+// 요청 타입 정의
+interface ListRequest extends XxxRequest {
+  dateRange?: [string, string];
+  // 추가 필드...
+}
+
+interface MetaData {
+  programFn?: ProgramFn;
+  // 메타데이터 필드...
+}
+
+interface States extends MetaData {
+  routePath?: string;
+  // spinning 상태 필드...
+  // 데이터 필드...
+}
+
+// create states
+const createState: States = {
+  // 초기값...
+};
+
+// create actions
+interface Actions extends PageStoreActions<States> {
+  // 액션 메서드 정의...
+}
+
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }), // 위치: 맨 앞 또는 맨 뒤
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+  // API 호출 메서드...
+});
+
+// export
+export interface xxxStore extends States, Actions, PageStoreActions<States> {}
+export const useXxxStore = create(
+  subscribeWithSelector<xxxStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  })),
+);
+
+// subscribe
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    // 메타데이터 필드...
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+## Spinning State 종류
+
+| Spinning State | 용도 | 관련 API 메서드 |
+|----------------|------|----------------|
+| `listSpinning` | 리스트 조회 로딩 | `callListApi` |
+| `excelSpinning` | 엑셀 다운로드 로딩 | `callExcelDownloadApi` / `downloadExcel` |
+| `saveSpinning` | 저장 로딩 | `callSaveApi` / `callFormSaveApi` |
+| `deleteSpinning` | 삭제 로딩 | `callDeleteApi` |
+| `detailSpinning` | 상세 조회 로딩 | `callDetailApi` |
+| `subListSpinning` | 서브 리스트 로딩 | `callSubListApi` |
+| `treeSpinning` | 트리 로딩 | `callTreeApi` |
+| `detailLoading` | 디테일 로딩 (지연) | `setSelectedItem` (with delay) |
+
+---
+
+## API 패턴별 상세
+
+### Pattern 1: List Only
+
+가장 기본적인 리스트만 있는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+  },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  listData: [],
+  listPage: {
+    currentPage: 0,
+    totalPages: 0,
+  },
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+  },
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 2: List + Detail
+
+리스트와 선택된 항목의 상세를 표시하는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  saveRequestValue: SaveRequest;
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  selectedItem?: DtoItem;
+  detailLoading: boolean;
+  checkedRowKeys: React.Key[];
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: { pageNumber: 1, pageSize: 100 },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+  saveRequestValue: {},
+  detailLoading: false,
+  checkedRowKeys: [],
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+  setSelectedItem: (selectedItem?: DtoItem) => Promise<void>;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+  },
+
+  setSelectedItem: async (selectedItem) => {
+    set({ selectedItem, detailLoading: true });
+    if (!selectedItem) {
+      set({ saveRequestValue: {} });
+    }
+    await delay(300);
+    set({ detailLoading: false });
+  },
+
+  setSaveRequestValue: (saveRequestValue) => set({ saveRequestValue }),
+  setCheckedRowKeys: (checkedRowKeys) => set({ checkedRowKeys }),
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+    saveRequestValue: s.saveRequestValue,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 3: List + Delete
+
+리스트와 삭제 기능이 있는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  deleteSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: { pageNumber: 1, pageSize: 100 },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  deleteSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  callDeleteApi: (id: number) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+    }
+  },
+
+  callDeleteApi: async (id) => {
+    set({ deleteSpinning: true });
+    try {
+      await XxxService.postXxxDeleteXxx({ id });
+    } finally {
+      set({ deleteSpinning: false });
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 4: List + Save
+
+리스트와 저장 기능이 있는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  saveRequestValue: SaveRequest;
+  modalOpen: boolean;
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  saveSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: { pageNumber: 1, pageSize: 100 },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  saveSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+  saveRequestValue: {},
+  modalOpen: false,
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  callSaveApi: (apiParam: SaveRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setModalOpen: (open: boolean) => void;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+    }
+  },
+
+  callSaveApi: async (apiParam) => {
+    try {
+      await XxxService.postXxxSaveXxx(apiParam);
+      await get().callListApi();
+    } catch (err) {
+      await errorHandling(err);
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+
+  setSaveRequestValue: (saveRequestValue) => set({ saveRequestValue }),
+  setModalOpen: (open) => set({ modalOpen: open }),
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+    saveRequestValue: s.saveRequestValue,
+    modalOpen: s.modalOpen,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 5: List + Excel
+
+리스트와 엑셀 다운로드 기능이 있는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  excelSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: { pageNumber: 1, pageSize: 100 },
+  listColWidths: [],
+  listSortParams: [],
+  listSpinning: false,
+  excelSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  callExcelDownloadApi: (request?: ListRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+    }
+  },
+
+  callExcelDownloadApi: async (request) => {
+    if (get().excelSpinning) return;
+    set({ excelSpinning: true });
+    try {
+      const { pageNumber, pageSize, ...restParams }: ListRequest = {
+        ...get().listRequestValue,
+        ...request,
+      };
+      await XxxService.postXxxListXxxExcel(deleteEmptyValue(restParams));
+    } finally {
+      set({ excelSpinning: false });
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 6: Tree
+
+트리 구조 데이터를 다루는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  mdiaClcd: string;
+  siteTpcd: string;
+  flexGrow: number;
+  selectedItem?: DtoItem;
+  saveRequestValues?: DtoItem;
+  expandedKeys: string[];
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  treeSpinning: boolean;
+  saveSpinning: boolean;
+  treeData: DtoItem[];
+  isDirty: boolean;
+  isFormDirty: boolean;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  flexGrow: 450,
+  siteTpcd: "10",
+  mdiaClcd: "10",
+  treeSpinning: false,
+  saveSpinning: false,
+  treeData: [],
+  expandedKeys: [],
+  selectedItem: undefined,
+  saveRequestValues: undefined,
+  isDirty: false,
+  isFormDirty: false,
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setFlexGrow: (flexGlow: number) => void;
+  callTreeApi: (mdiaClcd?: string) => Promise<void>;
+  callTreeSaveApi: (treeData?: DtoItem[]) => Promise<void>;
+  callFormSaveApi: () => Promise<void>;
+  setSelectedItem: (item?: DtoItem) => void;
+  setMdiaClcd: (mdiaClcd: string) => void;
+  setTreeData: (treeData: DtoItem[]) => void;
+  setExpandedKeys: (expandedKeys: string[]) => void;
+  setSaveRequestValues: (saveRequestValues: DtoItem) => void;
+  setIsDirty: (dirty: boolean) => void;
+  setIsFormDirty: (dirty: boolean) => void;
+}
+
+// ========== const createActions ==========
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  onMountApp: async () => {},
+  syncMetadata: (s = createState) => set(s),
+  setFlexGrow: (flexGrow) => set({ flexGrow }),
+
+  callTreeApi: async (mdiaClcd) => {
+    set({ treeSpinning: true });
+    try {
+      const { ds } = await XxxService.postXxxGetXxxTree({
+        siteTpcd: get().siteTpcd,
+        mdiaClcd: mdiaClcd ?? get().mdiaClcd,
+      });
+      set({ treeData: ds });
+    } finally {
+      set({ treeSpinning: false });
+    }
+  },
+
+  callTreeSaveApi: async (treeData) => {
+    set({ saveSpinning: true });
+    try {
+      const data = treeData ?? get().treeData;
+      await XxxService.postXxxSaveXxxTree(getMenuSortedChildren(data, 0, "0"));
+      set({ isDirty: false });
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  callFormSaveApi: async () => {
+    const { saveRequestValues } = get();
+    if (!saveRequestValues?.id) return;
+
+    set({ saveSpinning: true });
+    try {
+      await XxxService.postXxxSaveXxx(saveRequestValues);
+      set({ isFormDirty: false });
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  setSelectedItem: (item) => {
+    set({ selectedItem: item, saveRequestValues: { ...item } });
+  },
+  setMdiaClcd: (mdiaClcd) => {
+    set({ mdiaClcd, selectedItem: undefined, saveRequestValues: undefined });
+  },
+  setTreeData: (treeData) => set({ treeData }),
+  setExpandedKeys: (expandedKeys) => set({ expandedKeys }),
+  setSaveRequestValues: (saveRequestValues) => set({ saveRequestValues }),
+  setIsDirty: (dirty) => set({ isDirty: dirty }),
+  setIsFormDirty: (dirty) => set({ isFormDirty: dirty }),
+
+  ...pageStoreActions(set, get, { createState }),
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    flexGrow: s.flexGrow,
+    mdiaClcd: s.mdiaClcd,
+    siteTpcd: s.siteTpcd,
+    selectedItem: s.selectedItem,
+    saveRequestValues: s.saveRequestValues,
+    expandedKeys: s.expandedKeys,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 7: Master-Detail + SubList
+
+마스터 리스트와 디테일 서브 리스트가 있는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  listRequestValue: ListRequest;
+  subListRequestValue: SubListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  flexGrow: number;
+  saveRequestValue: SaveRequest;
+  detail?: DetailResponse;
+  formActive: boolean;
+  subListColWidths: number[];
+  subListSelectedRowKey?: React.Key;
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  saveSpinning: boolean;
+  detailSpinning: boolean;
+  subListSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  subListData: AXDGDataItem<SubDtoItem>[];
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: {},
+  subListRequestValue: {},
+  listColWidths: [],
+  listSortParams: [],
+  listSelectedRowKey: undefined,
+  flexGrow: 40,
+  saveRequestValue: { cd: '', nm: '' },
+  detail: { cd: '', nm: '' },
+  formActive: true,
+  listSpinning: false,
+  saveSpinning: false,
+  detailSpinning: false,
+  subListSpinning: false,
+  listData: [],
+  subListColWidths: [],
+  subListSelectedRowKey: undefined,
+  subListData: [],
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  callListApi: (request?: ListRequest, pageNumber?: number) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+  callSubListApi: (request?: SubListRequest) => Promise<void>;
+  callSaveApi: () => Promise<void>;
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setSubListRequestValue: (requestValue: SubListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setSubListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  setListSelectedRowKey: (key: React.Key, detail?: DetailResponse) => void;
+  setFlexGrow: (flexGlow: number) => void;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setSubListColWidths: (colWidths: number[]) => void;
+  setSubListSelectedRowKey: (key?: React.Key) => void;
+  cancelFormActive: () => void;
+  setFormActive: () => void;
+}
+
+// ========== const createActions ==========
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  onMountApp: async () => {},
+  syncMetadata: (s = createState) => set(s),
+
+  callListApi: async (request) => {
+    if (get().listSpinning) return;
+    set({ listSpinning: true });
+    try {
+      const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+      const response = await XxxService.postXxxListXxx(deleteEmptyValue(apiParam));
+      set({
+        listRequestValue: apiParam,
+        listData: (response.ds ?? []).map((values) => ({ values })),
+      });
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ listSpinning: false });
+    }
+  },
+
+  changeListPage: async (currentPage, pageSize) => {
+    await get().callListApi({
+      pageNumber: currentPage,
+      pageSize: pageSize ?? get().listRequestValue.pageSize,
+    });
+  },
+
+  callSubListApi: async (request) => {
+    set({ subListSpinning: true, subListData: [], subListSelectedRowKey: "" });
+    try {
+      if (!get().listSelectedRowKey) return;
+      const apiParam = request ?? { id: get().listSelectedRowKey };
+      const response = await XxxService.postXxxSubList(deleteEmptyValue(apiParam));
+      set({
+        subListData: (response.ds ?? []).map((values) => ({ values })),
+      });
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ subListSpinning: false });
+    }
+  },
+
+  callSaveApi: async () => {
+    set({ saveSpinning: true });
+    try {
+      await get().callSubListApi();
+    } catch (err) {
+      await errorHandling(err);
+    } finally {
+      set({ saveSpinning: false });
+    }
+  },
+
+  setListRequestValue: (requestValues, changedValues) =>
+    set({ listRequestValue: { ...requestValues, ...changedValues } }),
+  setListColWidths: (colWidths) => set({ listColWidths: colWidths }),
+  setListSortParams: (sortParams) => set({ listSortParams: sortParams }),
+  setListSelectedRowKey: (key, detail) => {
+    set({
+      listSelectedRowKey: key,
+      subListSelectedRowKey: "",
+      detail,
+      saveRequestValue: detail ?? { cd: '', nm: '' },
+    });
+  },
+  setFlexGrow: (flexGlow) => set({ flexGrow: flexGlow }),
+  setSaveRequestValue: (saveRequestValue) => set({ saveRequestValue }),
+  setSubListRequestValue: (requestValues) => set({ subListRequestValue: requestValues }),
+  setListSpinning: (spinning) => set({ listSpinning: spinning }),
+  setSubListSpinning: (spinning) => set({ subListSpinning: spinning }),
+  setSubListColWidths: (colWidths) => set({ subListColWidths: colWidths }),
+  setSubListSelectedRowKey: (key) => set({ subListSelectedRowKey: key }),
+  cancelFormActive: () => set({ formActive: false, listSelectedRowKey: undefined }),
+  setFormActive: () => set({ formActive: true, detail: undefined, saveRequestValue: undefined }),
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    listRequestValue: s.listRequestValue,
+    subListRequestValue: s.subListRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+    listSelectedRowKey: s.listSelectedRowKey,
+    flexGrow: s.flexGrow,
+    saveRequestValue: s.saveRequestValue,
+    detail: s.detail,
+    formActive: s.formActive,
+    subListColWidths: s.subListColWidths,
+    subListSelectedRowKey: s.subListSelectedRowKey,
+    subListData: s.subListData,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+### Pattern 8: List + Modal
+
+리스트와 모달을 사용하는 패턴입니다.
+
+```typescript
+// ========== interface MetaData ==========
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  modalOpen: boolean;
+  modalData?: DtoItem;
+}
+
+// ========== interface States ==========
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  saveSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ========== const createState ==========
+const createState: States = {
+  listRequestValue: { pageNumber: 1, pageSize: 100 },
+  listColWidths: [],
+  listSortParams: [],
+  modalOpen: false,
+  listSpinning: false,
+  saveSpinning: false,
+  listData: [],
+  listPage: { currentPage: 0, totalPages: 0 },
+};
+
+// ========== interface Actions ==========
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+  setListColWidths: (colWidths: number[]) => void;
+  setListSpinning: (spinning: boolean) => void;
+  setListSortParams: (sortParams: AXDGSortParam[]) => void;
+  callListApi: (request?: ListRequest) => Promise<void>;
+  callSaveApi: (apiParam: SaveRequest) => Promise<void>;
+  changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+  setModalOpen: (open: boolean, data?: DtoItem) => void;
+  setModalData: (data?: DtoItem) => void;
+}
+
+// ========== const createActions ==========
+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 XxxService.postXxxListXxx(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 });
+    }
+  },
+
+  callSaveApi: async (apiParam) => {
+    try {
+      await XxxService.postXxxSaveXxx(apiParam);
+      await get().callListApi();
+    } catch (err) {
+      await errorHandling(err);
+    }
+  },
+
+  changeListPage: async (pageNumber, pageSize) => {
+    await get().callListApi({ pageNumber, pageSize });
+  },
+
+  setModalOpen: (open, data) => set({ modalOpen: open, modalData: data }),
+  setModalData: (data) => set({ modalData: data }),
+});
+
+// ========== Store.subscribe ==========
+useXxxStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+    modalOpen: s.modalOpen,
+    modalData: s.modalData,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+## 공통 헬퍼 함수
+
+| 함수 | 용도 | 사용 예시 |
+|------|------|----------|
+| `deleteEmptyValue()` | 빈 값 제거 | `deleteEmptyValue({ ...apiParam })` |
+| `dateRangeToDts()` | 날짜 범위 변환 | `dateRangeToDts(dateRange, { startDt: "YYYY-MM-DD", endDt: "YYYY-MM-DD" })` |
+| `errorHandling()` | 공통 에러 처리 | `await errorHandling(err)` |
+| `delay()` | 지연 | `await delay(300)` |
+| `isEmpty()` | 빈 값 체크 | `isEmpty(value)` |
+
+---
+
+## 공통 Setter 메서드
+
+### 리스트 관련
+```typescript
+setListRequestValue: (requestValue: ListRequest, changedValues?: ListRequest) => void;
+setListColWidths: (colWidths: number[]) => void;
+setListSpinning: (spinning: boolean) => void;
+setListSortParams: (sortParams: AXDGSortParam[]) => void;
+setListSelectedRowKey: (key?: React.Key, detail?: DtoItem) => void;
+```
+
+### 페이지네이션 관련
+```typescript
+changeListPage: (currentPage: number, pageSize?: number) => Promise<void>;
+```
+
+### 선택/상세 관련
+```typescript
+setSelectedItem: (selectedItem?: DtoItem) => Promise<void>;
+setDetail: (detail: DtoItem) => void;
+setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+```
+
+### 모달 관련
+```typescript
+setModalOpen: (open: boolean) => void;
+setModalData: (data?: DtoItem) => void;
+```
+
+### 체크박스 관련
+```typescript
+setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+```
+
+### 트리 관련
+```typescript
+setExpandedKeys: (expandedKeys: string[]) => void;
+setTreeData: (treeData: DtoItem[]) => void;
+```
+
+### 서브 리스트 관련
+```typescript
+setSubListRequestValue: (requestValue: SubListRequest) => void;
+setSubListColWidths: (colWidths: number[]) => void;
+setSubListSpinning: (spinning: boolean) => void;
+setSubListSelectedRowKey: (key?: React.Key) => void;
+```
+
+### Form 관련
+```typescript
+setFormActive: () => void;
+cancelFormActive: () => void;
+setIsDirty: (dirty: boolean) => void;
+setIsFormDirty: (dirty: boolean) => void;
+```
+
+---
+
+## pageStoreActions 위치 규칙
+
+`pageStoreActions`는 다음 두 위치 중 하나에 배치할 수 있습니다:
+
+**옵션 1: 맨 앞에 배치**
+```typescript
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+  // 나머지 액션...
+});
+```
+
+**옵션 2: 맨 뒤에 배치**
+```typescript
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  onMountApp: async () => {},
+  syncMetadata: (s = createState) => set(s),
+  // 나머지 액션...
+  ...pageStoreActions(set, get, { createState }),
+});
+```