@axboot-mcp/mcp-server 1.0.0

package/src/docs/store-patterns-rules.md

@@ -0,0 +1,1168 @@
+# NH-FE-B Store 패턴 제약 조건 및 규칙
+
+> Store 생성/수정 시 준수해야 할 제약 조건과 규칙을 정리한 문서입니다.
+
+---
+
+## 목차
+
+1. [필수 규칙](#1-필수-규칙)
+2. [MetaData 제약 조건](#2-metadata-제약-조건)
+3. [States 제약 조건](#3-states-제약-조건)
+4. [Actions 제약 조건](#4-actions-제약-조건)
+5. [Store.subscribe 제약 조건](#5-storesubscribe-제약-조건)
+6. [네이밍 규칙](#6-네이밍-규칙)
+7. [타입 제약 조건](#7-타입-제약-조건)
+8. [필드 조합 규칙](#8-필드-조합-규칙)
+9. [구현 순서 규칙](#9-구현-순서-규칙)
+10. [금지 패턴](#10-금지-패턴)
+
+---
+
+## 1. 필수 규칙
+
+### 1.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 { ProgramFn } from "@types";
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { shallow } from "zustand/shallow";
+import { getTabStoreListener } from "stores";
+
+// 2) 반드시 필요한 인터페이스
+interface ListRequest extends ... {}
+interface DtoItem extends ... {}
+interface MetaData { ... }
+interface States extends MetaData { ... }
+interface Actions extends PageStoreActions<States> { ... }
+
+// 3) 반드시 필요한 상수/초기화
+const createState: States = { ... };
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({ ... });
+
+// 4) 반드시 필요한 내보내기
+export interface xxxStore extends States, Actions, PageStoreActions<States> {}
+export const useXXXStore = create(subscribeWithSelector<xxxStore>((set, get) => ({ ... })));
+
+// 5) 반드시 필요한 subscribe
+useXXXStore.subscribe(...);
+```
+
+### 1.2 pageStoreActions는 항상 마지막에 위치
+
+```typescript
+// ✅ 올바름
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // ... 다른 액션들
+  ...pageStoreActions(set, get, { createState }),
+});
+
+// ❌ 잘못됨
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  // ... 다른 액션들
+});
+```
+
+---
+
+## 2. MetaData 제약 조건
+
+### 2.1 programFn은 항상 첫 번째 필드
+
+```typescript
+// ✅ 올바름
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  // ...
+}
+
+// ❌ 잘못됨
+interface MetaData {
+  listRequestValue: ListRequest;
+  programFn?: ProgramFn;
+  // ...
+}
+```
+
+### 2.2 MetaData 필드 순서 (권장)
+
+```typescript
+interface MetaData {
+  // 1) 항상 첫 번째
+  programFn?: ProgramFn;
+
+  // 2) 리스트 관련 (그룹화)
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+
+  // 3) 선택 관련 (그룹화)
+  listSelectedRowKey?: React.Key;
+  listCheckedIndexes?: number[];
+  checkedRowKeys?: React.Key[];
+  listCheckedKeys?: React.Key[];
+
+  // 4) 저장/폼 관련 (그룹화)
+  saveRequestValue: SaveRequest;
+  detail?: SaveRequest;
+  selectedItem?: DtoItem;
+  saveRequestValues?: DtoItem;
+
+  // 5) 폼 상태 관련 (그룹화)
+  formActive: boolean;
+  flexGrow: number;
+
+  // 6) 트리 관련 (그룹화)
+  expandedKeys: number[] | string[];
+
+  // 7) 탭 관련 (그룹화)
+  activeTabKey: string;
+}
+```
+
+### 2.3 MetaData와 States의 관계
+
+```typescript
+// ✅ 올바름: States는 MetaData를 확장해야 함
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ❌ 잘못됨: MetaData를 확장하지 않음
+interface States {
+  routePath?: string;
+  listSpinning: boolean;
+  // ...
+}
+```
+
+### 2.4 MetaData 필드는 States에도 포함되어야 함
+
+MetaData에 정의된 필드는 `getTabStoreListener`를 통해 저장되므로 States에 포함되어야 합니다.
+
+```typescript
+// ✅ 올바름
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  saveRequestValue: SaveRequest;
+}
+
+interface States extends MetaData {  // MetaData의 필드가 모두 포함됨
+  routePath?: string;
+  listSpinning: boolean;
+  // ...
+}
+
+// Store.subscribe에도 모두 포함
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    saveRequestValue: s.saveRequestValue,
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+## 3. States 제약 조건
+
+### 3.1 States 필드 순서 (권장)
+
+```typescript
+interface States extends MetaData {
+  // 1) 시스템 필드 (가장 먼저)
+  routePath?: string;
+
+  // 2) MetaData 필드들 (extends로 자동 포함)
+
+  // 3) 데이터 관련
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+  selectedItem?: DtoItem;
+  detail?: DtoItem;
+
+  // 4) 로딩 상태 (그룹화)
+  listSpinning: boolean;
+  excelSpinning: boolean;
+  saveSpinning: boolean;
+  deleteSpinning: boolean;
+  detailSpinning: boolean;
+  detailLoading: boolean;
+
+  // 5) UI 상태
+  modalOpen: boolean;
+  formActive: boolean;
+}
+```
+
+### 3.2 Spinning 필드 관련 규칙
+
+| Spinning 필드 | 용도 | 필수 조건 |
+|--------------|------|----------|
+| `listSpinning` | 리스트 로딩 | 모든 리스트형 Store 필수 |
+| `excelSpinning` | 엑셀 다운로드 | 엑셀 기능 있을 시만 |
+| `saveSpinning` | 저장 작업 | CRUD Store에서 저장 기능 있을 시 |
+| `deleteSpinning` | 삭제 작업 | CRUD Store에서 삭제 기능 있을 시 |
+| `detailSpinning` | 상세 조회 | 상세 정보 별도 조회 시 |
+| `detailLoading` | 상세 로딩 UI 지연용 | `setSelectedItem`에서 delay 사용 시 |
+| `updateSpinning` | 상태 변경 | 일괄 상태 변경 기능 있을 시 |
+| `copySpinning` | 데이터 복사 | 복사 기능 있을 시 |
+| `treeSpinning` | 트리 로딩 | 트리형 Store에서 |
+| `summarySpinning` | 요약 로딩 | 대시보드형 Store에서 |
+| `list01Spinning` | 리스트1 로딩 | 다중 리스트형 Store에서 |
+| `list02Spinning` | 리스트2 로딩 | 다중 리스트형 Store에서 |
+
+### 3.3 States 필드 초기값 규칙
+
+| 필드명 | 필수 초기값 | 설명 |
+|--------|------------|------|
+| `routePath` | `undefined` | 초기화되지 않은 상태 |
+| `listSpinning` | `false` | 로딩 아님 |
+| `listData` | `[]` | 빈 배열 |
+| `listPage` | `{ currentPage: 0, totalPages: 0 }` | 빈 페이지 상태 |
+| `listColWidths` | `[]` | 빈 배열 (사용자가 설정) |
+| `listSortParams` | `[]` | 빈 배열 (사용자가 설정) |
+| `listSelectedRowKey` | `""` | 빈 문자열 (선택 없음) |
+| `checkedRowKeys` | `[]` | 빈 배열 (체크 없음) |
+| `selectedItem` | `undefined` | 선택 없음 |
+| `detail` | `undefined` | 상세 없음 |
+| `modalOpen` | `false` | 모달 닫힘 |
+| `formActive` | `false` | 폼 비활성 |
+| `expandedKeys` | `[]` | 빈 배열 (모두 접힘) |
+
+### 3.4 고정값 필드 규칙
+
+고정값이 필요한 경우 상수로 선언 후 States와 listRequestValue에 모두 포함:
+
+```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,  // 고정값 사용
+  };
+  // ...
+};
+```
+
+---
+
+## 4. Actions 제약 조건
+
+### 4.1 Actions는 반드시 PageStoreActions를 확장
+
+```typescript
+// ✅ 올바름
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  // ...
+}
+
+// ❌ 잘못됨
+interface Actions {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  // ...
+}
+```
+
+### 4.2 Actions 필드 순서 (권장)
+
+```typescript
+interface Actions extends PageStoreActions<States> {
+  // 1) Setter들 (그룹화)
+  setListRequestValue: ...;
+  setListColWidths: ...;
+  setListSpinning: ...;
+  setListSortParams: ...;
+  setExcelSpinning: ...;
+  setSaveRequestValue: ...;
+  setSelectedItem: ...;
+  setCheckedRowKeys: ...;
+  setListSelectedRowKey: ...;
+
+  // 2) API 호출들 (그룹화)
+  callListApi: ...;
+  callListApi01: ...;
+  callListApi02: ...;
+  callSummaryApi: ...;
+  callTreeApi: ...;
+  callSaveApi: ...;
+  callDeleteApi: ...;
+  callExcelDownloadApi: ...;
+
+  // 3) 페이지 변경 (그룹화)
+  changeListPage: ...;
+  changeList01Page: ...;
+  changeList02Page: ...;
+
+  // 4) 기타 액션들
+  setModalOpen: ...;
+  setFormActive: ...;
+  cancelFormActive: ...;
+}
+```
+
+### 4.3 필수 액션 vs 선택 액션
+
+| 액션명 | 필수여부 | 조건 |
+|--------|----------|------|
+| `syncMetadata` | **필수** | 항상 |
+| `onMountApp` | **필수** | 항상 |
+| `setListRequestValue` | **필수** | 리스트형 Store |
+| `setListColWidths` | **필수** | 리스트형 Store |
+| `setListSpinning` | **필수** | 리스트형 Store |
+| `setListSortParams` | **필수** | 리스트형 Store |
+| `callListApi` | **필수** | 리스트형 Store |
+| `changeListPage` | **필수** | 리스트형 Store |
+| `setExcelSpinning` | 선택 | 엑셀 기능 있을 때 |
+| `callExcelDownloadApi` | 선택 | 엑셀 기능 있을 때 |
+| `setSelectedItem` | 선택 | 상세/폼 기능 있을 때 |
+| `setSaveRequestValue` | 선택 | 저장 기능 있을 때 |
+| `setCheckedRowKeys` | 선택 | 체크박스 있을 때 |
+| `setListSelectedRowKey` | 선택 | 단일 선택 기능 있을 때 |
+| `callSaveApi` | 선택 | 저장 기능 있을 때 |
+| `callDeleteApi` | 선택 | 삭제 기능 있을 때 |
+| `setModalOpen` | 선택 | 모달 기능 있을 때 |
+| `setFormActive` | 선택 | 폼 활성화 기능 있을 때 |
+| `cancelFormActive` | 선택 | 폼 활성화 기능 있을 때 |
+
+### 4.4 callListApi 구현 규칙
+
+```typescript
+// ✅ 올바른 callListApi 구현 패턴
+callListApi: async (request) => {
+  // 1) 중복 호출 방지 (필수)
+  if (get().listSpinning) return;
+  set({ listSpinning: true });
+
+  try {
+    // 2) 파라미터 병합
+    const apiParam: ListRequest = { ...get().listRequestValue, ...request };
+
+    // 3) API 호출 (deleteEmptyValue 필수)
+    const response = await XXXService.postXXXList(
+      deleteEmptyValue({ ...apiParam })
+    );
+
+    // 4) 상태 업데이트 (listRequestValue 포함)
+    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) 응답 반환 (선택사항)
+    return response;
+  } finally {
+    // 6) 스피닝 해제 (필수)
+    set({ listSpinning: false });
+  }
+},
+```
+
+### 4.5 Actions와 States의 일치 규칙
+
+모든 Actions에서 set/get하는 필드는 States에 정의되어 있어야 합니다.
+
+```typescript
+// ✅ 올바름
+interface States {
+  listSpinning: boolean;
+  selectedItem?: DtoItem;
+}
+
+const createActions = (set, get) => ({
+  setListSpinning: (spinning) => set({ listSpinning: spinning }),
+  setSelectedItem: (item) => set({ selectedItem: item }),
+});
+
+// ❌ 잘못됨: States에 없는 필드를 사용
+interface States {
+  listSpinning: boolean;
+}
+
+const createActions = (set, get) => ({
+  setSelectedItem: (item) => set({ selectedItem: item }),  // States에 없음!
+});
+```
+
+---
+
+## 5. Store.subscribe 제약 조건
+
+### 5.1 subscribe는 항상 Store 생성 후에 위치
+
+```typescript
+// ✅ 올바름
+export const useXXXStore = create(
+  subscribeWithSelector<xxxStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  })),
+);
+
+useXXXStore.subscribe(  // Store 생성 후
+  (s): Record<keyof MetaData, any> => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+
+// ❌ 잘못됨
+useXXXStore.subscribe(  // Store 생성 전
+  (s): Record<keyof MetaData, any> => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+
+export const useXXXStore = create(
+  subscribeWithSelector<xxxStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  })),
+);
+```
+
+### 5.2 subscribe selector는 MetaData의 모든 필드를 포함해야 함
+
+```typescript
+// ✅ 올바름
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+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 },
+);
+
+// ❌ 잘못됨: MetaData 필드 누락
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    // listColWidths 누락! ❌
+    // listSortParams 누락! ❌
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### 5.3 subscribe selector는 순서를 유지해야 함 (권장)
+
+```typescript
+// ✅ 권장: MetaData 필드 순서와 동일하게
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,              // 1) 첫 번째
+    listSortParams: s.listSortParams,     // 2) 정렬 파라미터
+    listRequestValue: s.listRequestValue, // 3) 요청값
+    listColWidths: s.listColWidths,       // 4) 컬럼 너비
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### 5.4 equalityFn은 항상 shallow
+
+```typescript
+// ✅ 올바름
+useXXXStore.subscribe(
+  (s) => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },  // 항상 shallow
+);
+
+// ❌ 잘못됨
+useXXXStore.subscribe(
+  (s) => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  // equalityFn 누락
+);
+```
+
+---
+
+## 6. 네이밍 규칙
+
+### 6.1 Store 인터페이스 네이밍
+
+```
+패턴: [소문자 camelCase] + "Store"
+```
+
+```typescript
+// ✅ 올바름
+export interface memberListStore extends States, Actions, PageStoreActions<States> {}
+export interface productMasterStore extends States, Actions, PageStoreActions<States> {}
+export interface orderClaimReturnStore extends States, Actions, PageStoreActions<States> {}
+export interface kdhFinancialHighlightsStore extends States, Actions, PageStoreActions<States> {}
+
+// ❌ 잘못됨
+export interface MemberListStore ...  // 대문자 시작
+export interface member_list_store ...  // 스네이크 케이스
+export interface Memberliststore ...  // 잘못된 케이스
+```
+
+### 6.2 Hook 네이밍
+
+```
+패턴: "use" + [PascalCase] + "Store"
+```
+
+```typescript
+// ✅ 올바름
+export const useMemberListStore = create(...);
+export const useProductMasterStore = create(...);
+export const useOrderClaimReturnStore = create(...);
+export const useKdhFinancialHighlightsStore = create(...);
+
+// ❌ 잘못됨
+export const usememberListStore ...  // 소문자 시작
+export const useMemberlistStore ...  // 잘못된 케이스
+export const memberListStore ...  // use 없음
+export const MemberListStore ...  // use 없고 대문자
+```
+
+### 6.3 Actions 네이밍
+
+| 용도 | 네이밍 패턴 | 예시 |
+|------|------------|------|
+| 요청값 설정 | `set[Target]RequestValue` | `setListRequestValue`, `setSummaryRequestValue` |
+| 데이터 설정 | `set[Target]` | `setSelectedItem`, `setTreeData` |
+| 컬럼 너비 설정 | `setListColWidths` | `setListColWidths` (복수형) |
+| 스피닝 설정 | `set[Target]Spinning` | `setListSpinning`, `setExcelSpinning` |
+| 정렬 설정 | `setListSortParams` | `setListSortParams` (복수형) |
+| 체크 설정 | `setChecked[Target]s` | `setCheckedRowKeys` (복수형) |
+| 선택 설정 | `set[Target]Selected` | `setListSelectedRowKey` |
+| API 호출 | `call[Target]Api` | `callListApi`, `callSaveApi`, `callTreeApi` |
+| 페이지 변경 | `change[Target]Page` | `changeListPage` |
+| 폼 활성화 | `setFormActive`, `cancelFormActive` | `setFormActive`, `cancelFormActive` |
+| 모달 열기 | `setModalOpen` | `setModalOpen` |
+
+### 6.4 States 필드 네이밍
+
+| 용도 | 네이밍 패턴 | 복수형 여부 | 예시 |
+|------|------------|-----------|------|
+| 요청값 | `[target]RequestValue` | 단수 | `listRequestValue`, `summaryRequestValue` |
+| 데이터 | `[target]Data` | 단수 | `listData`, `treeData`, `summaryData` |
+| 페이지 | `[target]Page` | 단수 | `listPage`, `list01Page` |
+| 스피닝 | `[target]Spinning` | 단수 | `listSpinning`, `excelSpinning` |
+| 로딩 | `[target]Loading` | 단수 | `detailLoading` |
+| 정렬 파라미터 | `[target]SortParams` | **복수** | `listSortParams`, `list01SortParams` |
+| 컬럼 너비 | `listColWidths` | **복수** | `listColWidths` |
+| 선택된 행 키 | `listSelectedRowKey` | 단수 | `listSelectedRowKey` |
+| 체크된 키들 | `checkedRowKeys` | **복수** | `checkedRowKeys` |
+| 체크된 인덱스들 | `listCheckedIndexes` | **복수** | `listCheckedIndexes` |
+| 확장된 키들 | `expandedKeys` | **복수** | `expandedKeys` |
+| 선택된 아이템 | `selectedItem` | 단수 | `selectedItem` |
+
+### 6.5 상수 네이밍
+
+```typescript
+// ✅ 올바름
+const createState: States = { ... };
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({ ... });
+
+// ❌ 잘못됨
+const initialState: States = { ... };  // createState 아님
+const actions: StoreActions<States & Actions, Actions> = (set, get) => ({ ... });  // createActions 아님
+```
+
+---
+
+## 7. 타입 제약 조건
+
+### 7.1 ListRequest 타입
+
+```typescript
+// ✅ 올바름: Repository Request 타입을 확장
+interface ListRequest extends PostXXXListRequest {
+  dateRange?: [string, string];  // 추가 필드
+}
+
+// 또는 Partial 사용
+interface ListRequest extends Partial<PostXXXListRequest> {
+  dateRange?: [string, string];
+}
+
+// ❌ 잘못됨: 확장하지 않음
+interface ListRequest {
+  pageNumber: number;
+  pageSize: number;
+  // 모든 필드를 다시 정의 (비효율)
+}
+```
+
+### 7.2 DtoItem 타입
+
+```typescript
+// ✅ 올바름: Repository Response 타입을 확장
+interface DtoItem extends XXXRes {}
+
+// ❌ 잘못됨: 확장하지 않음
+interface DtoItem {
+  id: number;
+  name: string;
+  // 모든 필드를 다시 정의
+}
+```
+
+### 7.3 SaveRequest 타입
+
+```typescript
+// ✅ 올바름: Repository Save Request 타입을 확장
+interface SaveRequest extends PostXXXSaveRequest {}
+
+// 또는 별도 정의
+interface SaveRequest {
+  // 필드들...
+}
+
+// ❌ 잘못됨: Request와 Response를 혼용
+interface SaveRequest extends XXXRes {}  // Response를 확장 (잘못됨)
+```
+
+### 7.4 States 타입
+
+```typescript
+// ✅ 올바름: States는 MetaData를 확장
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+  listData: AXDGDataItem<DtoItem>[];
+  listPage: AXDGPage;
+}
+
+// ✅ 올바름: Actions는 PageStoreActions를 확장
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: ...;
+  // ...
+}
+
+// ❌ 잘못됨: States가 MetaData를 확장하지 않음
+interface States {
+  routePath?: string;
+  listSpinning: boolean;
+  // MetaData 필드들이 누락됨
+}
+```
+
+### 7.5 Store 타입 (내보내기)
+
+```typescript
+// ✅ 올바름: States, Actions, PageStoreActions<States> 모두 확장
+export interface xxxStore extends States, Actions, PageStoreActions<States> {}
+
+// ❌ 잘못됨: PageStoreActions 누락
+export interface xxxStore extends States, Actions {}
+```
+
+---
+
+## 8. 필드 조합 규칙
+
+### 8.1 필수 필드 조합
+
+다음 필드들은 함께 사용되어야 합니다:
+
+| 그룹 | 함께 사용해야 하는 필드 |
+|------|----------------------|
+| **기본 리스트** | `listRequestValue`, `listColWidths`, `listSortParams`, `listSpinning`, `listData`, `listPage`, `callListApi`, `changeListPage` |
+| **엑셀 다운로드** | `excelSpinning`, `setExcelSpinning`, `callExcelDownloadApi` |
+| **상세/폼** | `saveRequestValue`, `selectedItem`, `setSelectedItem`, `setSaveRequestValue` |
+| **단일 선택** | `listSelectedRowKey`, `setListSelectedRowKey` |
+| **다중 선택(체크박스)** | `checkedRowKeys`, `setCheckedRowKeys` |
+| **다중 선택(인덱스)** | `listCheckedIndexes`, `setListCheckedIndexes` |
+| **CRUD 저장** | `saveSpinning`, `setSaveSpinning`, `saveRequestValue`, `callSaveApi` |
+| **CRUD 삭제** | `deleteSpinning`, `callDeleteApi` |
+| **CRUD 폼** | `formActive`, `setFormActive`, `cancelFormActive` |
+| **모달** | `modalOpen`, `setModalOpen` |
+| **트리** | `treeSpinning`, `treeData`, `expandedKeys`, `callTreeApi` |
+| **대시보드** | `summaryRequestValue`, `summaryData`, `callSummaryApi` |
+
+### 8.2 상호 배타적 필드 조합
+
+다음 필드들은 함께 사용할 수 없습니다:
+
+| 그룹 | 선택해야 할 필드 | 함께 사용하면 안 되는 필드 |
+|------|------------------|----------------------|
+| **데이터 구조** | `listData`, `listPage` 또는 `treeData` | `listData` + `treeData` 함께 사용 ❌ |
+| **스피닝** | `listSpinning` 또는 `treeSpinning` | `listSpinning` + `treeSpinning` 함께 사용 ❌ |
+| **요청값** | `listRequestValue` 또는 `summaryRequestValue` | 목적에 따라 선택 |
+
+### 8.3 의존 필드 조합
+
+특정 필드를 사용할 때 다른 필드도 함께 필요한 경우:
+
+| 필드 | 함께 필요한 필드 | 이유 |
+|------|------------------|------|
+| `callExcelDownloadApi` | `excelSpinning`, `setExcelSpinning` | 엑셀 다운로드 로딩 상태 |
+| `setSelectedItem` | `selectedItem`, `detailLoading` | 선택 및 로딩 상태 |
+| `callSaveApi` | `saveSpinning`, `saveRequestValue` | 저장 로딩 및 데이터 |
+| `callDeleteApi` | `deleteSpinning` | 삭제 로딩 상태 |
+| `setListSelectedRowKey` | `listSelectedRowKey` | 선택된 행 키 상태 |
+| `setCheckedRowKeys` | `checkedRowKeys` | 체크된 키 상태 |
+| `setExpandedKeys` | `expandedKeys` | 확장된 키 상태 |
+| `changeListPage` | `callListApi` | 페이지 변경은 리스트 API 호출 |
+| `setFormActive` | `formActive` | 폼 활성화 상태 |
+
+### 8.4 MetaData ↔ Store.subscribe 매칭
+
+MetaData에 정의된 모든 필드는 Store.subscribe에 포함되어야 합니다.
+
+```typescript
+// ✅ 올바름: 매칭됨
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,              // ✅ MetaData에 있음
+    listRequestValue: s.listRequestValue, // ✅ MetaData에 있음
+    listColWidths: s.listColWidths,       // ✅ MetaData에 있음
+    listSortParams: s.listSortParams,     // ✅ MetaData에 있음
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+
+// ❌ 잘못됨: 불일치
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    // listColWidths 누락! ❌
+    // listSortParams 누락! ❌
+  }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+---
+
+## 9. 구현 순서 규칙
+
+### 9.1 파일 내 순서
+
+```typescript
+// 1) Imports (가장 먼저)
+import { ... } from "...";
+
+// 2) Interface 정의
+interface ListRequest ... {}
+interface DtoItem ... {}
+interface SaveRequest ... {}  // 필요시
+interface RemoveRequest ... {}  // 필요시
+
+interface MetaData ... {}
+interface States extends MetaData ... {}
+interface Actions extends PageStoreActions<States> ... {}
+
+// 3) 상수/초기화
+const createState: States = { ... };
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({ ... });
+
+// 4) 내보내기
+export interface xxxStore ... {}
+export const useXXXStore = create(...);
+
+// 5) Subscribe (가장 마지막)
+useXXXStore.subscribe(...);
+```
+
+### 9.2 createActions 내 순서
+
+```typescript
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // 1) pageStoreActions 또는 syncMetadata (가장 먼저 또는 마지막)
+  ...pageStoreActions(set, get, { createState }),
+
+  // 또는
+  syncMetadata: (s = createState) => set(s),
+
+  // 2) onMountApp
+  onMountApp: async () => { ... },
+
+  // 3) Setter들 (알파벳 순 또는 그룹별)
+  setListRequestValue: ...,
+  setListColWidths: ...,
+  setListSpinning: ...,
+  setListSortParams: ...,
+
+  // 4) API 호출들
+  callListApi: ...,
+  callSaveApi: ...,
+  callDeleteApi: ...,
+  callExcelDownloadApi: ...,
+
+  // 5) 페이지 변경
+  changeListPage: ...,
+
+  // 6) 기타 액션들
+  setSelectedItem: ...,
+  setCheckedRowKeys: ...,
+});
+```
+
+### 9.3 Store 내 요소 순서
+
+```typescript
+// 1) createState 내 필드 순서
+const createState: States = {
+  // 1) 고정값들 (가장 먼저)
+  bbsNo: 26,
+
+  // 2) MetaData 필드들
+  listRequestValue: { ... },
+  listColWidths: [],
+  listSortParams: [],
+
+  // 3) UI 상태
+  listSpinning: false,
+  modalOpen: false,
+  formActive: false,
+
+  // 4) 데이터
+  listData: [],
+  listPage: { ... },
+  selectedItem: undefined,
+};
+
+// 2) createActions 내 액션 순서
+const createActions: StoreActions<States & Actions, Actions> = (set, get) => ({
+  // 시스템 액션 → Setter → API → 페이지 변경 → 기타
+});
+
+// 3) Store.subscribe 내 필드 순서
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    // MetaData 필드 순서와 동일하게
+    programFn: ...,
+    listSortParams: ...,
+    listRequestValue: ...,
+    listColWidths: ...,
+  }),
+  ...
+);
+```
+
+---
+
+## 10. 금지 패턴
+
+### 10.1 금지: States에 MetaData를 확장하지 않음
+
+```typescript
+// ❌ 금지
+interface States {
+  routePath?: string;
+  listSpinning: boolean;
+  // MetaData 필드들이 누락됨!
+}
+
+// ✅ 해결
+interface States extends MetaData {
+  routePath?: string;
+  listSpinning: boolean;
+}
+```
+
+### 10.2 금지: pageStoreActions를 잘못된 위치에 배치
+
+```typescript
+// ❌ 금지: pageStoreActions가 첫 번째에 있음
+const createActions = (set, get) => ({
+  ...pageStoreActions(set, get, { createState }),
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+  // ...
+});
+
+// ✅ 해결: pageStoreActions를 마지막으로
+const createActions = (set, get) => ({
+  syncMetadata: (s = createState) => set(s),
+  onMountApp: async () => {},
+  // ...
+  ...pageStoreActions(set, get, { createState }),
+});
+```
+
+### 10.3 금지: listRequestValue를 업데이트하지 않음
+
+```typescript
+// ❌ 금지: callListApi에서 listRequestValue를 업데이트하지 않음
+callListApi: async (request) => {
+  const response = await XXXService.postXXXList(...);
+  set({
+    // listRequestValue 누락! ❌
+    listData: response.ds.map((values) => ({ values })),
+    listPage: { ... },
+  });
+}
+
+// ✅ 해결: listRequestValue 업데이트 포함
+callListApi: async (request) => {
+  const apiParam = { ...get().listRequestValue, ...request };
+  const response = await XXXService.postXXXList(...);
+  set({
+    listRequestValue: apiParam,  // ✅ 포함
+    listData: response.ds.map((values) => ({ values })),
+    listPage: { ... },
+  });
+}
+```
+
+### 10.4 금지: deleteEmptyValue를 사용하지 않음
+
+```typescript
+// ❌ 금지: deleteEmptyValue 미사용
+const response = await XXXService.postXXXList(apiParam);
+
+// ✅ 해결: deleteEmptyValue 사용
+const response = await XXXService.postXXXList(
+  deleteEmptyValue(apiParam)
+);
+```
+
+### 10.5 금지: States에 없는 필드를 Actions에서 사용
+
+```typescript
+// ❌ 금지
+interface States {
+  listSpinning: boolean;
+}
+
+const createActions = (set, get) => ({
+  setSelectedItem: (item) => set({ selectedItem: item }),  // States에 없음!
+});
+
+// ✅ 해결
+interface States {
+  listSpinning: boolean;
+  selectedItem?: DtoItem;  // 추가
+}
+
+const createActions = (set, get) => ({
+  setSelectedItem: (item) => set({ selectedItem: item }),
+});
+```
+
+### 10.6 금지: shallow equalityFn 누락
+
+```typescript
+// ❌ 금지
+useXXXStore.subscribe(
+  (s) => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  // equalityFn 누락!
+);
+
+// ✅ 해결
+useXXXStore.subscribe(
+  (s) => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow },
+);
+```
+
+### 10.7 금지: Subscribe selector와 MetaData 불일치
+
+```typescript
+// ❌ 금지
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    // listColWidths, listSortParams 누락!
+  }),
+  ...
+);
+
+// ✅ 해결
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listSortParams: s.listSortParams,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+  }),
+  ...
+);
+```
+
+### 10.8 금지: Spinning 해제 누락
+
+```typescript
+// ❌ 금지: finally 블록 누락
+callListApi: async (request) => {
+  set({ listSpinning: true });
+  const response = await XXXService.postXXXList(...);
+  set({ listData: response.ds.map((values) => ({ values })) });
+  // spinning 해제 누락! ❌
+}
+
+// ✅ 해결: finally 블록 사용
+callListApi: async (request) => {
+  set({ listSpinning: true });
+  try {
+    const response = await XXXService.postXXXList(...);
+    set({ listData: response.ds.map((values) => ({ values })) });
+  } finally {
+    set({ listSpinning: false });  // ✅ 항상 해제
+  }
+}
+```
+
+### 10.9 금지: 중복 호출 방지 누락
+
+```typescript
+// ❌ 금지: 중복 호출 방지 없음
+callListApi: async (request) => {
+  set({ listSpinning: true });
+  // ...
+}
+
+// ✅ 해결: 중복 호출 방지 포함
+callListApi: async (request) => {
+  if (get().listSpinning) return;  // ✅ 중복 방지
+  set({ listSpinning: true });
+  // ...
+}
+```
+
+### 10.10 금지: Actions의 반환 타입 누락
+
+```typescript
+// ❌ 금지: Actions가 PageStoreActions를 확장하지 않음
+interface Actions {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  // ...
+}
+
+// ✅ 해결: PageStoreActions 확장
+interface Actions extends PageStoreActions<States> {
+  setListRequestValue: (requestValue: ListRequest) => void;
+  // ...
+}
+```
+
+---
+
+## 11. 빠른 참조: 체크리스트
+
+### Store 생성 체크리스트
+
+#### Interface
+- [ ] `ListRequest`가 Repository Request를 확장함
+- [ ] `DtoItem`가 Repository Response를 확장함
+- [ ] `SaveRequest`가 Repository Save Request를 확장함 (필요시)
+- [ ] `MetaData`에 필요한 필드가 모두 포함됨
+- [ ] `States`가 `MetaData`를 확장함
+- [ ] `Actions`가 `PageStoreActions<States>`를 확장함
+
+#### createState
+- [ ] `listRequestValue`에 `pageNumber`, `pageSize` 초기값 포함
+- [ ] `listColWidths`가 빈 배열로 초기화됨
+- [ ] `listSortParams`가 빈 배열로 초기화됨
+- [ ] `listSpinning`이 `false`로 초기화됨
+- [ ] `listData`가 빈 배열로 초기화됨
+- [ ] `listPage`가 빈 페이지 상태로 초기화됨
+- [ ] 고정값이 필요한 경우 상수로 선언되고 포함됨
+
+#### createActions
+- [ ] `syncMetadata`가 구현됨
+- [ ] `onMountApp`가 구현됨
+- [ ] `setListRequestValue`가 구현됨
+- [ ] `setListColWidths`가 구현됨
+- [ ] `setListSpinning`가 구현됨
+- [ ] `setListSortParams`가 구현됨
+- [ ] `callListApi`가 구현됨 (중복 호출 방지, try-finally 포함)
+- [ ] `changeListPage`가 구현됨
+- [ ] `callListApi`에서 `deleteEmptyValue` 사용됨
+- [ ] `callListApi`에서 `listRequestValue` 업데이트됨
+- [ ] 추가 기능의 액션들이 모두 구현됨
+- [ ] `...pageStoreActions(set, get, { createState })`가 마지막에 있음
+
+#### Store 내보내기
+- [ ] `xxxStore` 인터페이스가 `States, Actions, PageStoreActions<States>`를 모두 확장함
+- [ ] `useXXXStore`가 `subscribeWithSelector`로 생성됨
+
+#### Store.subscribe
+- [ ] `subscribe`가 Store 생성 후에 위치함
+- [ ] Selector가 `MetaData`의 모든 필드를 포함함
+- [ ] `getTabStoreListener<MetaData>`가 사용됨
+- [ ] `{ equalityFn: shallow }`가 포함됨
+
+---
+
+*이 문서는 NH-FE-B 프로젝트의 Store 패턴 제약 조건과 규칙을 정리한 것입니다.*