@axboot-mcp/mcp-server 1.0.0

package/src/docs/store-pattern-analysis.md

@@ -0,0 +1,664 @@
+# AXBoot Zustand Store 패턴 분석
+
+## 개요
+
+NH-FE-B 프로젝트의 `/src/pages/resources/NH` 하위 Store 파일들에서 발견되는 일관된 패턴을 분석한 문서입니다. 이 패턴은 MCP-AXBoot의 Store 생성 템플릿에 반영하기 위한 목적으로 작성되었습니다.
+
+---
+
+## 1. 전체 파일 구조
+
+```typescript
+// 1. Imports
+import { AXDGDataItem, AXDGPage, AXDGSortParam } from "@axboot/datagrid";
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+import { PageStoreActions, StoreActions } from "@core/stores/types";
+import { ProgramFn } from "@types";
+import { XXXService, PostXXXListRequest, XXXRes } from "services";
+import { getTabStoreListener } from "stores";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+
+// 2. Interface 정의 (ListRequest, DtoItem, SaveRequest 등)
+interface ListRequest extends PostXXXListRequest { ... }
+interface DtoItem extends XXXRes {}
+interface SaveRequest { ... }
+
+// 3. MetaData 인터페이스 (페이지 모델에 저장될 필드)
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  // ... 추가 필드들
+}
+
+// 4. States 인터페이스
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  // ... 추가 상태들
+}
+
+// 5. createState 초기값
+const createState: States = { ... };
+
+// 6. Actions 인터페이스
+interface Actions extends PageStoreActions<States> {
+  // ... 액션 메서드들
+}
+
+// 7. createActions 구현
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({ ... });
+
+// 8. Store 타입 내보내기
+export interface xxxStore extends States, Actions, PageStoreActions<States> {}
+
+// 9. Store 생성
+export const useXXXStore = create(subscribeWithSelector<xxxStore>((set, get) => ({
+  ...createState,
+  ...createActions(set, get),
+})));
+
+// 10. Store.subscribe (페이지 모델 동기화)
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+## 2. createActions 패턴 상세 분석
+
+### 2.1 필수 액션 (모든 Store에 공통)
+
+```typescript
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // 1) 메타데이터 동기화 - 상태를 초기값으로 재설정
+  syncMetadata: (s = createState) => set(s),
+
+  // 2) 앱 마운트 시 실행
+  onMountApp: async () => {
+    // onDidMount and store initialized
+  },
+
+  // 3) 리스트 요청값 설정
+  setListRequestValue: (requestValues, changedValues) => {
+    set({ listRequestValue: requestValues });
+    // 또는
+    set({
+      listRequestValue: {
+        ...get().listRequestValue,
+        ...requestValues,
+      },
+    });
+  },
+
+  // 4) 컬럼 너비 설정
+  setListColWidths: (colWidths) => set({ listColWidths: colWidths }),
+
+  // 5) 로딩 스피닝 설정
+  setListSpinning: (spinning) => set({ listSpinning: spinning }),
+
+  // 6) 정렬 파라미터 설정
+  setListSortParams: (sortParams) => set({ listSortParams: sortParams }),
+
+  // 7) pageStoreActions 확장 (항상 마지막에 위치)
+  ...pageStoreActions(set, get, { createState }),
+});
+```
+
+### 2.2 리스트 API 호출 패턴 (callListApi)
+
+```typescript
+callListApi: async (request) => {
+  if (get().listSpinning) return;  // 중복 호출 방지
+  set({ listSpinning: true });
+
+  try {
+    const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+    const response = await XXXService.postXXXList(
+      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,
+      },
+    });
+
+    return response;  // 선택사항
+  } finally {
+    set({ listSpinning: false });
+  }
+},
+```
+
+### 2.3 페이지 변경 패턴 (changeListPage)
+
+```typescript
+changeListPage: async (pageNumber, pageSize) => {
+  await get().callListApi({
+    pageNumber,
+    pageSize,
+    // 추가 파라미터가 필요한 경우
+  });
+},
+```
+
+### 2.4 선택 관련 액션 패턴
+
+#### 단일 선택 (setSelectedItem)
+```typescript
+setSelectedItem: async (selectedItem) => {
+  set({ selectedItem, detailLoading: true });
+
+  if (!selectedItem || selectedItem["__status__"] === "C") {
+    set({ saveRequestValue: {} });
+  }
+
+  await delay(300);  // 딜레이 (선택사항)
+
+  set({ detailLoading: false });
+},
+```
+
+#### 행 키 선택 (setListSelectedRowKey)
+```typescript
+setListSelectedRowKey: async (key, detail) => {
+  if (detail) {
+    set({ listSelectedRowKey: key, detail, saveRequestValue: { ...detail } });
+  } else {
+    set({ listSelectedRowKey: undefined, detail: undefined, saveRequestValue: undefined });
+  }
+},
+
+// 단순 버전
+setListSelectedRowKey: (key) => {
+  set({ listSelectedRowKey: key });
+},
+```
+
+#### 체크박스 관련
+```typescript
+setCheckedRowKeys: (checkedRowKeys) => set({ checkedRowKeys }),
+setListCheckedIndexes: (indexes) => set({ listCheckedIndexes: indexes }),
+setListCheckedKeys: (checkedKeys) => set({ listCheckedKeys: checkedKeys }),
+```
+
+### 2.5 저장 API 패턴 (callSaveApi)
+
+```typescript
+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 XXXService.postXXXSave(apiParam);
+
+    // 응답으로 상태 업데이트
+    set({ saveRequestValue: rs, detail: rs });
+
+    // 저장 후 목록 갱신
+    await get().callListApi();
+  } finally {
+    set({ saveSpinning: false });
+  }
+},
+```
+
+### 2.6 삭제 API 패턴 (callDeleteApi)
+
+```typescript
+callDeleteApi: async (request) => {
+  if (get().deleteSpinning) return;
+  set({ deleteSpinning: true });
+
+  try {
+    const apiParam: RemoveRequest = {
+      ...get().saveRequestValue,
+      ...request,
+      __status__: "D",
+    };
+
+    await XXXService.postXXXDelete(apiParam);
+
+    // 삭제 후 목록 갱신
+    await get().callListApi();
+  } finally {
+    set({ deleteSpinning: false });
+  }
+},
+```
+
+### 2.7 엑셀 다운로드 패턴
+
+```typescript
+// 별도 스피닝 사용
+callExcelDownloadApi: async (request) => {
+  if (get().excelSpinning) return;
+  set({ excelSpinning: true });
+
+  try {
+    const { pageNumber, pageSize, ...restParams }: ListRequest = {
+      ...get().listRequestValue,
+      ...request,
+    };
+
+    await XXXService.postXXXListExcel(
+      deleteEmptyValue({ ...restParams })
+    );
+  } finally {
+    set({ excelSpinning: false });
+  }
+},
+
+// 메서드명이 downloadExcel인 경우
+downloadExcel: async () => {
+  try {
+    const apiParam = deleteEmptyValue({
+      ...get().listRequestValue,
+      // 추가 변환 로직
+    });
+
+    await XXXService.postXXXExcelDownload(apiParam);
+  } catch (error) {
+    console.error("엑셀 다운로드 오류:", error);
+    throw error;
+  }
+},
+```
+
+### 2.8 폼 활성화/비활성화 패턴
+
+```typescript
+setFormActive: () => {
+  set({ formActive: true, detail: undefined, saveRequestValue: undefined });
+},
+
+cancelFormActive: () => {
+  set({ formActive: false, listSelectedRowKey: undefined });
+},
+```
+
+### 2.9 대시보드/다중 리스트 패턴
+
+```typescript
+// 여러 리스트의 요청값/정렬/스피닝을 개별 관리
+setRequest01Value: (requestValues) => set({ listRequest01Value: requestValues }),
+setRequest02Value: (requestValues) => set({ listRequest02Value: requestValues }),
+setList01SortParams: (sortParams) => set({ list01SortParams: sortParams }),
+setList02SortParams: (sortParams) => set({ list02SortParams: sortParams }),
+setActiveTabKey: (key) => set({ activeTabKey: key }),
+
+// 동적 스피닝 설정
+setListSpinning: (spinning, target = "01") =>
+  set({ [`list${target}Spinning`]: spinning }),
+```
+
+---
+
+## 3. Store.subscribe 패턴 상세 분석
+
+### 3.1 기본 구조
+
+```typescript
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    // Selector: Store 상태에서 필요한 필드만 추출
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),  // Listener
+  { equalityFn: shallow },  // Options
+);
+```
+
+### 3.2 필드 조합별 패턴
+
+#### Pattern 1: 기본 리스트형 (가장 일반적)
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+#### Pattern 2: 리스트 + 상세폼
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  saveRequestValue: SaveRequest;
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    saveRequestValue: s.saveRequestValue,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+#### Pattern 3: 마스터-디테일
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSelectedRowKey: s.listSelectedRowKey,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+#### Pattern 4: 리스트 + 체크박스
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  listCheckedIndexes?: number[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSelectedRowKey: s.listSelectedRowKey,
+    listCheckedIndexes: s.listCheckedIndexes,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+#### Pattern 5: CRUD (리스트 + 상세 + 체크박스)
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  flexGrow: number;
+  saveRequestValue: SaveRequest;
+  detail?: SaveRequest;
+  formActive: boolean;
+  listCheckedKeys: React.Key[];
+}
+
+useXXXStore.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 },
+);
+```
+
+#### Pattern 6: 대시보드/다중 리스트
+```typescript
+interface MetaData {
+  programFn?: ProgramFn;
+  summaryRequestValue: SummaryRequest;
+  listRequest01Value: ListRequest01;
+  listRequest02Value: ListRequest02;
+  activeTabKey: PanelType;
+  list01SortParams: AXDGSortParam[];
+  list02SortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    summaryRequestValue: s.summaryRequestValue,
+    listRequest01Value: s.listRequest01Value,
+    listRequest02Value: s.listRequest02Value,
+    activeTabKey: s.activeTabKey,
+    list01SortParams: s.list01SortParams,
+    list02SortParams: s.list02SortParams,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### 3.3 MetaData 필드별 설명
+
+| 필드명 | 타입 | 설명 | 필수여부 |
+|--------|------|------|----------|
+| `programFn` | `ProgramFn \| undefined` | 프로그램 함수 참조 | 기본 |
+| `listSortParams` | `AXDGSortParam[]` | 그리드 정렬 파라미터 | 기본 |
+| `listRequestValue` | `ListRequest` | 리스트 요청값 (검색조건 등) | 기본 |
+| `listColWidths` | `number[]` | 그리드 컬럼 너비 배열 | 기본 |
+| `saveRequestValue` | `SaveRequest` | 저장/상세 요청값 | 선택 |
+| `selectedItem` | `DtoItem \| undefined` | 선택된 아이템 | 선택 |
+| `listSelectedRowKey` | `React.Key \| undefined` | 선택된 행 키 | 선택 |
+| `listCheckedIndexes` | `number[] \| undefined` | 체크된 인덱스 목록 | 선택 |
+| `checkedRowKeys` | `React.Key[]` | 체크된 행 키 목록 | 선택 |
+| `listCheckedKeys` | `React.Key[]` | 체크된 키 목록 | 선택 |
+| `flexGrow` | `number` | 플렉스 성장 비율 (레이아웃) | 선택 |
+| `detail` | `SaveRequest \| undefined` | 상세 데이터 | 선택 |
+| `formActive` | `boolean` | 폼 활성화 상태 | 선택 |
+| `activeTabKey` | `string` | 활성 탭 키 | 선택 |
+| `summaryRequestValue` | `SummaryRequest` | 요약 요청값 | 선택 |
+
+### 3.4 필드 네이밍 규칙 (다중 리스트)
+
+다중 리스트 패턴에서는 다음과 같은 네이밍 규칙이 사용됩니다:
+
+```
+- listRequestValue → listRequest01Value, listRequest02Value, ...
+- listSortParams → list01SortParams, list02SortParams, ...
+- listData → list01Data, list02Data, ...
+- listPage → list01Page, list02Page, ...
+- listSpinning → list01Spinning, list02Spinning, ...
+```
+
+---
+
+## 4. States 필드별 초기값 패턴
+
+### 4.1 기본 States 필드
+
+```typescript
+interface States {
+  routePath?: string;          // 초기값: undefined
+  listSpinning: boolean;       // 초기값: false
+  listData: AXDGDataItem<DtoItem>[];  // 초기값: []
+  listPage: AXDGPage;          // 초기값: { currentPage: 0, totalPages: 0 }
+}
+```
+
+### 4.2 createState 초기화 패턴
+
+```typescript
+const createState: States = {
+  // 검색조건 초기값
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    // 추가 검색조건...
+  },
+
+  // UI 상태 초기값
+  listColWidths: [],
+  listSpinning: false,
+  listData: [],
+  listPage: {
+    currentPage: 0,
+    totalPages: 0,
+  },
+  listSortParams: [],
+
+  // 선택 관련 초기값
+  listSelectedRowKey: "",
+  checkedRowKeys: [],
+
+  // 스피닝 초기값 (필요시)
+  excelSpinning: false,
+  saveSpinning: false,
+  detailSpinning: false,
+  deleteSpinning: false,
+};
+```
+
+---
+
+## 5. 타입 정의 패턴
+
+### 5.1 ListRequest 정의
+
+```typescript
+// 기본: Repository Request 타입 확장
+interface ListRequest extends PostXXXListRequest {
+  // 추가 필드 (dateRange 등)
+  dateRange?: [string, string];
+}
+
+// Partial 사용 (일부 필드만 필수로)
+interface ListRequest extends Partial<PostXXXListRequest> {
+  dateRange?: [string, string];
+}
+```
+
+### 5.2 SaveRequest 정의
+
+```typescript
+// Repository Save Request 확장
+interface SaveRequest extends PostXXXSaveRequest {}
+
+// 또는 별도 정의
+interface SaveRequest {
+  // 필드들...
+}
+```
+
+### 5.3 DtoItem 정의
+
+```typescript
+// Repository Response 타입 확장
+interface DtoItem extends XXXRes {}
+```
+
+---
+
+## 6. Store 타입 내보내기 패턴
+
+```typescript
+// Store 이름: camelCase + "Store"
+export interface xxxStore extends States, Actions, PageStoreActions<States> {}
+
+// Hook 이름: "use" + PascalCase + "Store"
+export const useXXXStore = create(
+  subscribeWithSelector<xxxStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  })),
+);
+```
+
+---
+
+## 7. 요약: 템플릿 생성을 위한 결정사항
+
+### 7.1 Store 타입별 분류
+
+| 타입 | 설명 | 주요 패턴 |
+|------|------|-----------|
+| **기본 리스트형** | 단순 조회만 | Pattern 1 |
+| **리스트+상세** | 조회 + 상세보기 | Pattern 2 |
+| **마스터-디테일** | 마스터 선택 시 디테일 표시 | Pattern 3 |
+| **체크박스 포함** | 다중 선택 기능 | Pattern 4 |
+| **CRUD** | 생성/조회/수정/删除 | Pattern 5 |
+| **대시보드** | 여러 데이터 표시 | Pattern 6 |
+| **다중 리스트** | 여러 그리드 | 다중 리스트 패턴 |
+
+### 7.2 createActions 구현 순서 (권장)
+
+1. `syncMetadata`
+2. `onMountApp`
+3. Setter들 (`setListRequestValue`, `setListColWidths`, `setListSpinning`, `setListSortParams`)
+4. API 호출 (`callListApi`, `callSaveApi`, `callDeleteApi`, `callExcelDownloadApi`)
+5. 페이지 변경 (`changeListPage`)
+6. 선택 관련 (`setSelectedItem`, `setListSelectedRowKey`, `setCheckedRowKeys`)
+7. 폼 관련 (`setFormActive`, `cancelFormActive`)
+8. 기타 커스텀 액션
+9. `...pageStoreActions(set, get, { createState })`
+
+### 7.3 MetaData 필드 포함 기준
+
+| 필드 | 포함 기준 |
+|------|-----------|
+| `programFn` | 항상 포함 |
+| `listSortParams` | 정렬 기능이 있을 때 |
+| `listRequestValue` | 리스트가 있을 때 |
+| `listColWidths` | 그리드 컬럼 너비 조절이 필요할 때 |
+| `saveRequestValue` | 저장/상세 기능이 있을 때 |
+| `listSelectedRowKey` | 단일 선택이 필요할 때 |
+| `listCheckedIndexes` | 인덱스 기반 다중 선택 |
+| `listCheckedKeys` | 키 기반 다중 선택 |
+| `flexGrow` | 플렉스 레이아웃 조절이 필요할 때 |
+| `formActive` | 폼 활성화 상태를 추적할 때 |
+| `activeTabKey` | 탭 전환이 있을 때 |