@axboot-mcp/mcp-server 1.0.0

package/src/docs/troubleshooting.md

@@ -0,0 +1,544 @@
+# 문제 해결 가이드
+
+> MCP-AXBoot 사용 시 발생할 수 있는 문제와 해결 방법을 정리했습니다.
+
+## 목차
+
+1. [빌드/설치 문제](#1 빌드설치-문제)
+2. [Store 생성 문제](#2-store-생성-문제)
+3. [타입 오류](#3-타입-오류)
+4. [런타임 오류](#4-런타임-오류)
+5. [품질 개선 팁](#5-품질-개선-팁)
+
+---
+
+## 1. 빌드/설치 문제
+
+### 문제 1.1: import.meta 오류
+
+**에러 메시지**:
+```
+error TS1343: The 'import.meta' meta-property is only allowed when the '--module' option is 'es2020'...
+```
+
+**원인**: CommonJS 환경에서 `import.meta` 사용
+
+**해결**: 이미 `src/docs/loader.ts`에서 해결됨. 경로 계산 로직이 CommonJS 호환되도록 구현됨.
+
+**참고**: `docs/loader.ts`의 `getDocsDir()` 함수 참조
+
+### 문제 1.2: 모듈 찾기 오류
+
+**에러 메시지**:
+```
+Cannot find module '../docs/index.js' or its corresponding type declarations
+```
+
+**원인**: 빌드되지 않았거나 경로 오류
+
+**해결**:
+```bash
+# 프로젝트 루트에서
+npm run build
+```
+
+### 문제 1.3: docs 폴더 누락
+
+**에러 메시지**:
+```
+ENOENT: no such file or directory, open '.../dist/docs/patterns.json'
+```
+
+**원인**: docs 파일이 dist로 복사되지 않음
+
+**해결 1**: package.json에 copy 스크립트 추가
+```json
+{
+  "scripts": {
+    "build": "tsc && npm run copy-docs",
+    "copy-docs": "cp -r src/docs dist/docs"
+  }
+}
+```
+
+**해결 2**: tsconfig.json 설정 확인
+```json
+{
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  }
+}
+```
+
+---
+
+## 2. Store 생성 문제
+
+### 문제 2.1: Repository 분석 실패
+
+**에러 메시지**:
+```
+{
+  "success": false,
+  "error": "인터페이스 분석 실패"
+}
+```
+
+**원인**: Repository 파일이 TypeScript 인터페이스가 아님
+
+**해결**: Repository 파일 형식 확인
+
+```typescript
+// ✅ 올바른 형식
+export interface MemberRepository {
+  postMemberListMember(request: PostMemberListMemberRequest): Promise<MemberListResponse>;
+}
+
+// ❌ 잘못된 형식
+export class MemberRepository {
+  async postMemberListMember(request: PostMemberListMemberRequest) {
+    // ...
+  }
+}
+```
+
+### 문제 2.2: 지원하지 않는 Store 타입
+
+**에러 메시지**:
+```
+{
+  "success": false,
+  "error": "지원하지 않는 Store 타입입니다: 15"
+}
+```
+
+**원인**: 타입 번호가 1~10 범위를 벗어남
+
+**해결**: 올바른 타입 번호 사용
+
+| 타입 | 이름 | 설명 |
+|-----|------|------|
+| 1 | Basic List | 단순 조회 |
+| 2 | List + Excel | 엑셀 다운로드 |
+| 3 | List + Detail | 상세 보기/편집 |
+| 4 | Master-Detail | 마스터-디테일 |
+| 5 | CRUD | 전체 기능 |
+| 6 | Tree + Form | 트리 구조 |
+| 7 | Dashboard | 대시보드 |
+| 8 | Modal Based | 모달 기반 |
+| 9 | Status Change | 상태 변경 |
+| 10 | Master-Detail + Excel | 엑셀 포함 |
+
+### 문제 2.3: 잘못된 타입 추천
+
+**증상**: 요구사항과 맞지 않는 타입이 추천됨
+
+**해결 1**: 더 구체적인 요구사항 작성
+
+```
+❌ "회원 Store"
+✅ "회원 목록을 보여주고 검색할 수 있으며, 선택하면 상세 정보를 보여주는 Store"
+```
+
+**해결 2**: `analyze_requirements`로 먼저 분석
+
+```
+"회원 목록에 상세 보기, 저장, 삭제가 있는 Store"를 분석해줘.
+```
+
+**해결 3**: 타입을 직접 지정
+
+```
+Type 5 (CRUD)로 Store를 만들어줘.
+```
+
+---
+
+## 3. 타입 오류
+
+### 문제 3.1: Request/Response 타입 불일치
+
+**에러 메시지**:
+```
+Type 'PostMemberListRequest' is not assignable to type 'ListRequest'
+```
+
+**원인**: Repository Request 타입을 확장하지 않음
+
+**해결**: ListRequest가 Repository Request를 확장하도록 수정
+
+```typescript
+// ✅ 올바름
+interface ListRequest extends PostMemberListMemberRequest {
+  dateRange?: [string, string];
+}
+
+// ❌ 잘못됨
+interface ListRequest {
+  pageNumber: number;
+  pageSize: number;
+}
+```
+
+### 문제 3.2: Actions 타입 오류
+
+**에러 메시지**:
+```
+Property 'callXXXApi' does not exist on type...
+```
+
+**원인**: Actions 인터페이스에 메서드 누락
+
+**해결**: Actions 인터페이스에 메서드 추가
+
+```typescript
+interface Actions extends PageStoreActions<States> {
+  callListApi: (request?: ListRequest) => Promise<void>;
+  callSaveApi: (request?: SaveRequest) => Promise<void>; // 추가
+  // ...
+}
+```
+
+### 문제 3.3: TemplateVariables 타입 오류
+
+**에러 메시지**:
+```
+Object literal may only specify known properties, and 'XXX' does not exist in type 'TemplateVariables'
+```
+
+**원인**: 템플릿에 새 변수를 추가했지만 TemplateVariables 인터페이스에 없음
+
+**해결**: `src/templates/index.ts`에 필드 추가
+
+```typescript
+export interface TemplateVariables {
+  // ... 기존 필드
+  METADATA_FIELDS?: string; // 추가
+  CREATE_STATE_FIELDS?: string; // 추가
+}
+```
+
+---
+
+## 4. 런타임 오류
+
+### 문제 4.1: API 호출 실패
+
+**증상**: 리스트가 로드되지 않음
+
+**해결 1**: Service 메서드명 확인
+
+```typescript
+// 생성된 코드
+await MemberService.postMemberList(apiParam);
+
+// 실제 Service 확인
+// services/MemberService.ts에서 메서드명 확인
+```
+
+**해결 2**: deleteEmptyValue 사용 확인
+
+```typescript
+// ✅ 올바름
+await MemberService.postMemberList(
+  deleteEmptyValue({ ...apiParam })
+);
+
+// ❌ 잘못됨
+await MemberService.postMemberList(apiParam);
+```
+
+**해결 3**: API 파라미터 구조 확인
+
+```typescript
+// Request 구조 확인
+const apiParam: ListRequest = {
+  pageNumber: 1,
+  pageSize: 100,
+  // 필요한 파라미터 모두 포함
+};
+```
+
+### 문제 4.2: 스피넝이 멈추지 않음
+
+**증상**: 로딩 스피너가 계속 돔
+
+**원인**: finally 블록 누락
+
+**해결**: finally 블록에서 스피닝 해제
+
+```typescript
+// ✅ 올바름
+callListApi: async (request) => {
+  if (get().listSpinning) return;
+  set({ listSpinning: true });
+
+  try {
+    // API 호출
+  } finally {
+    set({ listSpinning: false }); // 필수
+  }
+}
+
+// ❌ 잘못됨
+callListApi: async (request) => {
+  set({ listSpinning: true });
+  await API.call();
+  // finally 블록 누락
+}
+```
+
+### 문ssue 4.3: Store.subscribe 오류
+
+**증상**: 탭 전환 시 상태가 유지되지 않음
+
+**해결 1**: equalityFn 확인
+
+```typescript
+// ✅ 올바름
+useXXXStore.subscribe(
+  (s) => ({ ... }),
+  getTabStoreListener<MetaData>(createState.routePath),
+  { equalityFn: shallow }, // 필수
+);
+```
+
+**해결 2**: Selector에 모든 MetaData 필드 포함
+
+```typescript
+// ✅ 올바름 - 모든 필드 포함
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    listColWidths: s.listColWidths,
+    listSortParams: s.listSortParams,
+  }),
+  // ...
+);
+
+// ❌ 잘못됨 - 필드 누락
+useXXXStore.subscribe(
+  (s): Record<keyof MetaData, any> => ({
+    programFn: s.programFn,
+    listRequestValue: s.listRequestValue,
+    // listColWidths 누락
+  }),
+  // ...
+);
+```
+
+---
+
+## 5. 품질 개선 팁
+
+### 팁 1: 생성 후 커스터마이징
+
+Store 생성 후 프로젝트에 맞게 커스터마이징하세요.
+
+**초기 검색조건 추가**:
+
+```typescript
+const createState: States = {
+  listRequestValue: {
+    pageNumber: 1,
+    pageSize: 100,
+    // 프로젝트에 맞는 검색조건 추가
+    searchKeyword: "",
+    searchStatus: "ACTIVE",
+    searchType: "ALL",
+    dateRange: undefined,
+  },
+  // ...
+};
+```
+
+**API 파라미터 변환 로직 추가**:
+
+```typescript
+callListApi: async (request) => {
+  // ...
+
+  // 파라미터 변환
+  const apiParam = {
+    ...get().listRequestValue,
+    ...request,
+    // 프로젝트 특화 변환
+    startDate: request.dateRange?.[0],
+    endDate: request.dateRange?.[1],
+  };
+
+  // ...
+},
+```
+
+### 팁 2: 타입 안전성 확보
+
+**DTO 타입 정의**:
+
+```typescript
+// Repository Response 타입 활용
+interface DtoItem extends MemberRes {
+  // 추가 필드가 필요한 경우
+  fullName?: string;
+}
+```
+
+**Service 타입 import**:
+
+```typescript
+// services/index.ts에서 재export 활용
+import {
+  MemberService,
+  PostMemberListMemberRequest,
+  MemberRes,
+} from "services";
+```
+
+### 팁 3: 성능 최적화
+
+**불시적 비교 사용 (shallow)**:
+
+```typescript
+// 컴포넌트에서 Store 사용 시
+import { shallow } from 'zustand/shallow';
+
+const listData = useMemberListStore(
+  (state) => state.listData,
+  shallow
+);
+```
+
+**선택자 사용**:
+
+```typescript
+// 필요한 상태만 선택
+const { listData, callListApi } = useMemberListStore(
+  (state) => ({
+    listData: state.listData,
+    callListApi: state.callListApi,
+  })
+);
+```
+
+### 팁 4: 재사용 가능한 Hooks
+
+Store와 함께 사용할 커스텀 Hook을 만드세요.
+
+```typescript
+// hooks/useMemberList.ts
+export function useMemberList() {
+  const store = useMemberListStore();
+
+  useEffect(() => {
+    if (!store.listData.length) {
+      store.callListApi();
+    }
+  }, []);
+
+  const handleSearch = (keyword: string) => {
+    store.setListRequestValue({
+      ...store.listRequestValue,
+      searchKeyword: keyword,
+    });
+    store.callListApi();
+  };
+
+  return {
+    ...store,
+    handleSearch,
+  };
+}
+```
+
+### 팁 5: 테스트 가능한 Store
+
+Store를 테스트하기 쉽게 만드세요.
+
+```typescript
+// 테스트용 초기값
+export const createTestStore = (initialState?: Partial<States>) =>
+  create(subscribeWithSelector<memberListStore>((set, get) => ({
+    ...createState,
+    ...initialState,
+    ...createActions(set, get),
+  })));
+
+// 테스트 예시
+describe('useMemberListStore', () => {
+  it('should load list data', async () => {
+    const store = createTestStore();
+    await store.callListApi();
+    expect(store.listData).toHaveLength(10);
+  });
+});
+```
+
+---
+
+## 6. 디버깅 팁
+
+### 팁 1: Store 상태 확인
+
+```typescript
+// 개발 중 상태 확인
+useEffect(() => {
+  console.log('Store State:', useMemberListStore.getState());
+}, []);
+```
+
+### 팁 2: API 요청/응답 확인
+
+```typescript
+callListApi: async (request) => {
+  console.log('API Request:', { ...get().listRequestValue, ...request });
+
+  try {
+    const response = await MemberService.postMemberList(apiParam);
+    console.log('API Response:', response);
+    // ...
+  } catch (error) {
+    console.error('API Error:', error);
+    throw error;
+  }
+},
+```
+
+### 팁 3: MCP 도구 확인
+
+생성된 Store가 올바른지 `analyze_requirements`로 확인:
+
+```
+"useMemberListStore와 유사한 기능을 가진 Store 타입을 추천해줘.
+리스트, 검색, 저장, 삭제, 엑셀 다운로드가 필요해.
+```
+
+---
+
+## 7. 지원 및 피드백
+
+### 문제 보고
+
+문제가 발생하면 다음 정보를 포함하여 보고해주세요:
+
+1. **Repository 인터페이스**: 사용한 Repository의 인터페이스 정의
+2. **요구사항**: Store 생성 요청 시 사용한 요구사항
+3. **에러 메시지**: 전체 에러 메시지
+4. **예상 동작**: 기대하던 동작
+
+### 기능 요청
+
+새로운 Store 타입이나 기능이 필요하면:
+
+1. `docs/patterns.json`에 새 패턴 추가
+2. `src/templates/`에 새 템플릿 추가
+3. `src/features/store-features.ts`에 피처 추가
+
+### 문서 기여
+
+경험을 공유하고 싶으시면:
+
+1. 예제 추가: `practical-examples.md`
+2. 문서 개선: 기존 문서 업데이트
+3. 템플릿 개선: 더 나은 템플릿 제안