@axboot-mcp/mcp-server 1.0.0

package/src/docs/type-selection-guide.md

@@ -0,0 +1,572 @@
+# Store 타입 선택 가이드
+
+> 프로젝트에 맞는 올바른 Store 타입을 선택하는 방법을 안내합니다.
+
+## 목차
+
+1. [타입 선택 결정 트리](#1-타입-선택-결정-트리)
+2. [타입별 상세 비교](#2-타입별-상세-비교)
+3. [선택 시 고려사항](#3-선택-시-고려사항)
+4. [타입 변환 가이드](#4-타입-변환-가이드)
+
+---
+
+## 1. 타입 선택 결정 트리
+
+```
+시작
+  ↓
+데이터가 트리 구조인가요?
+  YES → Type 6 (Tree + Form)
+  NO
+  ↓
+대시보드/요약 정보가 필요한가요?
+  YES → Type 7 (Dashboard)
+  NO
+  ↓
+엑셀 다운로드만 필요한가요? (저장/삭제 없음)
+  YES → Type 2 (List + Excel)
+  NO
+  ↓
+저장/삭제 기능이 필요한가요?
+  YES
+  ↓  ↓
+전체 CRUD인가요?    체크박스 일괄 처리인가요?
+  YES → Type 5        YES → Type 9 (Status Change)
+  (CRUD)            (일괄 상태 변경)
+  NO  ↓  ↓
+  ↓
+모달로 처리하는가요?
+  YES → Type 8 (Modal Based)
+  NO
+  ↓
+마스터-디테일 구조인가요?
+  YES → Type 4 (Master-Detail)
+  NO
+  ↓
+상세 편집이 필요한가요?
+  YES → Type 3 (List + Detail)
+  NO
+  ↓
+Type 1 (Basic List)
+```
+
+---
+
+## 2. 타입별 상세 비교
+
+### 2.1 Type 1: Basic List
+
+**사용처**: 단순 조회 페이지
+
+**특징**:
+- 리스트 조회만 가능
+- 검색, 정렬, 페이지네이션 기본 지원
+- 수정/删除 기능 없음
+
+**예시**:
+- 부서 목록
+- 공지사항 목록
+- 통계 데이터 조회
+
+**MetaData**:
+```typescript
+{
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+}
+```
+
+**필수 조건**:
+- ✅ 리스트 표시
+- ✅ 검색
+- ❌ 저장/삭제
+- ❌ 상세 보기
+
+---
+
+### 2.2 Type 2: List + Excel
+
+**사용처**: 조회 + 엑셀 다운로드
+
+**특징**:
+- Type 1 + 엑셀 다운로드
+- 엑셀 스피닝 별도 관리
+
+**예시**:
+- 상품 리뷰 목록
+- 고객 문의 내역
+- 배송 조회 내역
+
+**추가 States**:
+```typescript
+{
+  excelSpinning: boolean;
+}
+```
+
+**추가 Actions**:
+```typescript
+{
+  callExcelDownloadApi: (request?: ListRequest) => Promise<void>;
+  setExcelSpinning: (spinning: boolean) => void;
+}
+```
+
+---
+
+### 2.3 Type 3: List + Detail/Form
+
+**사용처**: 조회 + 상세 보기/편집
+
+**특징**:
+- 리스트 선택 시 상세 표시
+- 상세 정보 편집 가능
+- 저장 기능 포함
+
+**예시**:
+- 회원 목록 + 상세 정보
+- 혜택 관리
+- 이벤트 관리
+
+**추가 States**:
+```typescript
+{
+  selectedItem?: DtoItem;
+  detailLoading: boolean;
+  checkedRowKeys: React.Key[];
+}
+```
+
+**추가 Actions**:
+```typescript
+{
+  setSelectedItem: (selectedItem?: DtoItem) => Promise<void>;
+  setSaveRequestValue: (saveRequestValue: SaveRequest) => void;
+  setCheckedRowKeys: (checkedRowKeys: React.Key[]) => void;
+}
+```
+
+---
+
+### 2.4 Type 4: Master-Detail
+
+**사용처**: 마스터 리스트 선택 시 디테일 표시
+
+**특징**:
+- 선택한 항목의 디테일을 별도로 관리
+- 단일 선택 focus
+- 체크박스 다중 선택 가능
+
+**예시**:
+- 상품 마스터 + 상세
+- 주문 목록 + 주문 상세
+- 클레임 목록 + 클레임 상세
+
+**추가 States**:
+```typescript
+{
+  listSelectedRowKey?: React.Key;
+  listCheckedIndexes?: number[];
+  checkedRowKeys: React.Key[];
+}
+```
+
+---
+
+### 2.5 Type 5: CRUD
+
+**사용처**: 전체 기능 (생성, 조회, 수정, 삭제)
+
+**특징**:
+- 모든 기능 포함
+- 폼 활성/비활성 상태 관리
+- 체크박스 다중 선택
+
+**예시**:
+- 시스템 BBS 관리
+- 코드 그룹 관리
+- 메뉴 관리
+
+**추가 States**:
+```typescript
+{
+  listSelectedRowKey?: React.Key;
+  flexGrow: number;
+  saveRequestValue: SaveRequest;
+  detail?: SaveRequest;
+  formActive: boolean;
+  listCheckedKeys: React.Key[];
+  saveSpinning: boolean;
+  detailSpinning: boolean;
+  deleteSpinning: boolean;
+}
+```
+
+---
+
+### 2.6 Type 6: Tree + Form
+
+**사용처**: 트리 구조 + 선택된 항목 편집
+
+**특징**:
+- 트리 데이터 구조
+- 확장/축소 상태 관리
+- 검색어로 리스트 전환 가능
+
+**예시**:
+- 상품 카테고리
+- 메뉴 구조
+- 조직도
+
+**주요 States**:
+```typescript
+{
+  treeData: DtoItem[];
+  treeSpinning: boolean;
+  expandedKeys: number[] | string[];
+  selectedItem?: DtoItem;
+  saveRequestValues?: DtoItem;
+  categorySearch?: boolean;
+}
+```
+
+**주요 Actions**:
+```typescript
+{
+  callTreeApi: (request?: ListRequest) => Promise<void>;
+  setExpandedKeys: (expandedKeys: number[]) => void;
+  setSelectedItem: (item?: DtoItem) => void;
+  callTreeSaveApi: (treeData?: DtoItem[]) => Promise<void>;
+}
+```
+
+---
+
+### 2.7 Type 7: Dashboard
+
+**사용처**: 여러 데이터 요약 + 여러 리스트
+
+**특징**:
+- 다중 데이터 소스
+- 탭으로 전환
+- 각 리스트 독립적 관리
+
+**예시**:
+- 회원 대시보드
+- 혜택 대시보드
+- 메인 전시 관리
+
+**주요 States**:
+```typescript
+{
+  summaryRequestValue: SummaryRequest;
+  listRequest01Value: ListRequest01;
+  listRequest02Value: ListRequest02;
+  activeTabKey: PanelType;
+  list01SortParams: AXDGSortParam[];
+  list02SortParams: AXDGSortParam[];
+  summaryData: DtoItem;
+  list01Data: AXDGDataItem<DtoItem01>[];
+  list02Data: AXDGDataItem<DtoItem02>[];
+}
+```
+
+---
+
+### 2.8 Type 8: Modal Based
+
+**사용처**: 리스트 + 모달로 상세/작업
+
+**특징**:
+- 모달 열림 상태 관리
+- 모달 내에서 작업 수행
+
+**예시**:
+- B2B 상품 관리
+- 견적 상담 관리
+- 배송지 관리
+
+**추가 States**:
+```typescript
+{
+  modalOpen: boolean;
+  detail?: DtoItem;
+  deleteSpinning: boolean;
+  excelSpinning: boolean;
+}
+```
+
+---
+
+### 2.9 Type 9: Status Change
+
+**사용처**: 다중 선택 후 일괄 상태 변경
+
+**특징**:
+- 체크박스 다중 선택
+- 일괄 상태 변경 로직
+- 데이터 복사 기능
+
+**예시**:
+- 상품 전시 관리
+- 상품 판매 상태 관리
+- 상품 패키지 관리
+
+**추가 States**:
+```typescript
+{
+  updateSpinning: boolean;
+  deleteSpinning: boolean;
+  copySpinning: boolean;
+}
+```
+
+**주요 Actions**:
+```typescript
+{
+  callChangeStatusApi: (changeStatus: string) => void;
+  callDataCopyApi: (prdCd: string) => Promise<void>;
+}
+```
+
+---
+
+### 2.10 Type 10: Master-Detail + Excel
+
+**사용처**: 마스터-디테일 + 엑셀 다운로드
+
+**특징**:
+- Type 4 + 엑셀 다운로드
+- 주문/배송 관리에 적합
+
+---
+
+## 3. 선택 시 고려사항
+
+### 3.1 기능 요구사항
+
+| 필요 기능 | 추천 타입 |
+|-----------|----------|
+| 조회만 | Type 1 |
+| 조회 + 엑셀 | Type 2 |
+| 조회 + 상세 편집 | Type 3 |
+| 조회 + 상세 + 모달 | Type 8 |
+| CRUD 전체 | Type 5 |
+| CRUD + 엑셀 | Type 5 (엑셀 추가) |
+| 트리 구조 | Type 6 |
+| 대시보드 | Type 7 |
+| 일괄 상태 변경 | Type 9 |
+
+### 3.2 UI 패턴
+
+| UI 패턴 | 추천 타입 |
+|---------|----------|
+| 단일 리스트 | Type 1, 2, 3, 5 |
+| 왼쪽 목록 + 오른쪽 상세 | Type 3, 4, 6 |
+| 상단 목록 + 하단 상세 | Type 4, 5 |
+| 리스트 + 모달 | Type 8 |
+| 트리 + 폼 | Type 6 |
+| 요약 + 다중 리스트 | Type 7 |
+
+### 3.3 데이터 복잡도
+
+| 복잡도 | 추천 타입 |
+|--------|----------|
+| 단순 (단일 엔티티) | Type 1, 2, 3 |
+| 중간 (1:N 관계) | Type 4, 5, 8 |
+| 복잡 (다중 소스) | Type 7 |
+| 계층적 (트리) | Type 6 |
+
+### 3.4 사용자 상호작용
+
+| 상호작용 | 추천 타입 |
+|---------|----------|
+| 보기만 | Type 1, 2 |
+| 선택 후 상세 보기 | Type 3, 4 |
+| 편집 필요 | Type 3, 5, 6, 8 |
+| 다중 선택 후 작업 | Type 5, 9 |
+| 드래그앤드롭 | Type 6 (재정렬) |
+
+---
+
+## 4. 타입 변환 가이드
+
+### 4.1 Type 1 → Type 2 (엑셀 추가)
+
+**변경 사항**:
+
+1. States에 `excelSpinning` 추가
+2. Actions에 `callExcelDownloadApi`, `setExcelSpinning` 추가
+
+```typescript
+// 추가
+interface States extends MetaData {
+  // ... 기존 필드
+  excelSpinning: boolean; // 추가
+}
+
+// 추가
+const createActions = (set, get) => ({
+  // ... 기존 액션
+
+  setExcelSpinning: (spinning) => set({ excelSpinning: spinning }),
+
+  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 });
+    }
+  },
+});
+```
+
+### 4.2 Type 3 → Type 5 (CRUD 추가)
+
+**변경 사항**:
+
+1. MetaData에 CRUD 관련 필드 추가
+2. States에 스피닝 필드 추가
+3. Actions에 CRUD 액션 추가
+
+```typescript
+// MetaData 추가
+interface MetaData {
+  // ... 기존 필드
+  listSelectedRowKey?: React.Key;
+  flexGrow: number;
+  detail?: SaveRequest;
+  formActive: boolean;
+  listCheckedKeys: React.Key[];
+}
+
+// States 추가
+interface States extends MetaData {
+  // ... 기존 필드
+  saveSpinning: boolean;
+  detailSpinning: boolean;
+  deleteSpinning: boolean;
+}
+
+// Actions 추가
+const createActions = (set, get) => ({
+  // ... 기존 액션
+
+  setListSelectedRowKey: async (key, detail) => {
+    if (detail) {
+      set({ listSelectedRowKey: key, detail, saveRequestValue: { ...detail } });
+    } else {
+      set({ listSelectedRowKey: undefined, detail: undefined, saveRequestValue: undefined });
+    }
+  },
+
+  setSaveSpinning: (spinning) => set({ saveSpinning: spinning }),
+
+  callSaveApi: async (request) => {
+    // ... 저장 로직
+  },
+
+  callDeleteApi: async (request) => {
+    // ... 삭제 로직
+  },
+
+  cancelFormActive: () => {
+    set({ formActive: false, listSelectedRowKey: undefined });
+  },
+
+  setFormActive: () => {
+    set({ formActive: true, detail: undefined, saveRequestValue: undefined });
+  },
+});
+```
+
+### 4.3 Type 4 → Type 8 (모달 추가)
+
+**변경 사항**:
+
+1. States에 `modalOpen` 추가
+2. Actions에 `setModalOpen` 추가
+3. 삭제 시 모달 사용
+
+---
+
+## 5. 추천 질문
+
+### Q1: Type 5를 무조건 쓰면 되나요?
+
+**A**: 아닙니다. Type 5는 모든 기능을 포함하지만 불필요한 기능이 있을 수 있습니다.
+
+- 단순 조회만 필요 → Type 1
+- 조회 + 엑셀만 필요 → Type 2
+- 조회 + 상세만 필요 → Type 3
+
+불필요한 기능이 없는 타입을 선택하는 것이 좋습니다.
+
+### Q2: 한 타입으로 충분하지 않은 경우?
+
+**A**: 두 가지 방법:
+
+1. **가장 근접한 타입 선택 후 수정**
+   - 기존 타입을 기반으로 생성
+   - 필요한 기능만 추가
+
+2. **다중 리스트 사용**
+   - `generate_multi_stores` 도구 활용
+   - 왼쪽/상단/하단 리스트 조합
+
+### Q3: 타입을 나중에 변경할 수 있나요?
+
+**A**: 네, 가능합니다. 하지만:
+
+- 처음부터 올바른 타입을 선택하는 것이 좋습니다.
+- 타입 변경 시 MetaData, States, Actions를 모두 수정해야 합니다.
+- Store.subscribe도 함께 수정해야 합니다.
+
+### Q4: 커스텀 타입을 만들 수 있나요?
+
+**A**: 네, 두 가지 방법:
+
+1. **기존 타입 수정**: 생성된 Store를 직접 수정
+2. **새 템플릿 추가**: `src/templates/`에 새 템플릿 파일 생성
+
+---
+
+## 6. Claude에서의 사용 예시
+
+### 예시 1: 타입 추천 요청
+
+```
+주문 관리용 Store를 만들려고 해.
+주문 목록에서 주문을 선택하면 하단에 주문 상세 내역이 표시되고,
+엑셀 다운로드도 필요해.
+어떤 타입을 추천해?
+```
+
+### 예시 2: 타입 지정 후 생성
+
+```
+상품 카테고리 관리를 위한 Store를 만들어줘.
+트리 구조로 표시되고, 선택된 카테고리를 편집할 수 있어야 해.
+Type 6으로 만들어줘.
+```
+
+### 예시 3: 조건 비교
+
+```
+회원 관리 Store를 만들려고 해.
+조회, 검색, 저장, 삭제, 엑셀 다운로드가 필요해.
+어떤 타입이 가장 적합한지 비교해줘.
+```