[문서 추가] 설정 가이드, 변경 이력, 트러블슈팅 문서 작성

## 추가된 문서 ### 06-setup-guide.md - 설정 가이드 - panelQueueMiddleware 등록 상세 가이드 - 미들웨어 등록 순서 설명 - 파일 구조 확인 방법 - 단계별 설정 순서 - 검증 방법 (콘솔 로그, Redux DevTools, State 확인) - 트러블슈팅 (5가지 일반적인 문제) - 빠른 체크리스트 ### 07-changelog.md - 변경 이력 - 2025-11-10: panelQueueMiddleware 등록 및 문서 개선 - 2025-11-10: 초기 문서 작성 - 2025-11-06: 큐 시스템 구현 - 2025-11-05: dispatch 헬퍼 함수 추가 - 마이그레이션 가이드 - Breaking Changes (없음) - 알려진 이슈 (모두 해결됨) - 향후 계획 ### 08-troubleshooting.md - 트러블슈팅 - 일반적인 문제 3가지 - dispatch 순서 미보장 - Cannot find module 에러 - 타입 에러 - 큐 시스템 문제 3가지 - 큐가 처리되지 않음 - 무한 루프 - 큐 통계 미업데이트 - API 호출 문제 2가지 - 성공인데 onFail 호출 - 타임아웃 미작동 - 성능 문제 2가지 - 큐 처리 속도 저하 - 메모리 누수 - 디버깅 팁 5가지 - 콘솔 로그 활용 - Redux DevTools 사용 - 브레이크포인트 설정 - State 스냅샷 - 큐 상태 모니터링 ## README.md 업데이트 - 목차에 새로운 문서 3개 추가 - "학습 자료" 섹션을 3개 카테고리로 재구성: - 시작하기 (설정 가이드, 트러블슈팅) - 이해하기 (문제 상황, 3가지 솔루션) - 실전 적용 (사용 패턴, 변경 이력) ## 문서 통계 - 총 9개 마크다운 파일 - 약 5,000줄 이상 - 100개 이상의 코드 예제 - 10가지 실전 트러블슈팅 가이드 ## 특징 - 초보자도 쉽게 따라할 수 있는 단계별 가이드 - 실제 발생 가능한 문제와 해결 방법 - 변경 이력 및 커밋 히스토리 추적 - 상세한 디버깅 팁
2025-11-10 10:22:23 +00:00
parent c12cc91a39
commit bad111e23c
4 changed files with 1327 additions and 0 deletions
--- a/.docs/dispatch-async/06-setup-guide.md
+++ b/.docs/dispatch-async/06-setup-guide.md
@@ -0,0 +1,396 @@
 # 설정 가이드
 ## 📋 목차
 1. [초기 설정](#초기-설정)
 2. [파일 구조 확인](#파일-구조-확인)
 3. [설정 순서](#설정-순서)
 4. [검증 방법](#검증-방법)
 5. [트러블슈팅](#트러블슈팅)
 ---
 ## 초기 설정
 ### 1️⃣ 필수: panelQueueMiddleware 등록
 큐 기반 패널 액션 시스템을 사용하려면 **반드시** Redux store에 미들웨어를 등록해야 합니다.
 #### 파일 위치
 `com.twin.app.shoptime/src/store/store.js`
 #### 수정 전
 ```javascript
 import { applyMiddleware, combineReducers, createStore } from 'redux';
 import thunk from 'redux-thunk';
 import { autoCloseMiddleware } from '../middleware/autoCloseMiddleware';
 import { panelHistoryMiddleware } from '../middleware/panelHistoryMiddleware';
 // panelQueueMiddleware import 없음!
 // ... reducers ...
 export const store = createStore(
  rootReducer,
  applyMiddleware(thunk, panelHistoryMiddleware, autoCloseMiddleware)
  // panelQueueMiddleware 등록 없음!
 );
 ```
 #### 수정 후
 ```javascript
 import { applyMiddleware, combineReducers, createStore } from 'redux';
 import thunk from 'redux-thunk';
 import { autoCloseMiddleware } from '../middleware/autoCloseMiddleware';
 import { panelHistoryMiddleware } from '../middleware/panelHistoryMiddleware';
 import panelQueueMiddleware from '../middleware/panelQueueMiddleware'; // ← 추가
 // ... reducers ...
 export const store = createStore(
  rootReducer,
  applyMiddleware(
    thunk,
    panelHistoryMiddleware,
    autoCloseMiddleware,
    panelQueueMiddleware  // ← 추가 (맨 마지막 위치)
  )
 );
 ```
 ### 2️⃣ 미들웨어 등록 순서
 미들웨어 등록 순서는 다음과 같습니다:
 ```javascript
 applyMiddleware(
  thunk,                    // 1. Redux-thunk (비동기 액션 지원)
  panelHistoryMiddleware,   // 2. 패널 히스토리 관리
  autoCloseMiddleware,      // 3. 자동 닫기 처리
  panelQueueMiddleware      // 4. 패널 큐 처리 (맨 마지막)
 )
 ```
 **중요**: `panelQueueMiddleware`는 **맨 마지막**에 위치해야 합니다!
 - 다른 미들웨어들이 먼저 액션을 처리한 후
 - 큐 미들웨어가 큐 관련 액션을 감지하고 처리합니다
 ---
 ## 파일 구조 확인
 ### 필수 파일들이 모두 존재하는지 확인
 ```bash
 # 프로젝트 루트에서 실행
 ls -la com.twin.app.shoptime/src/middleware/panelQueueMiddleware.js
 ls -la com.twin.app.shoptime/src/actions/queuedPanelActions.js
 ls -la com.twin.app.shoptime/src/utils/dispatchHelper.js
 ls -la com.twin.app.shoptime/src/utils/asyncActionUtils.js
 ls -la com.twin.app.shoptime/src/reducers/panelReducer.js
 ```
 ### 예상 출력
 ```
 -rw-r--r-- 1 user user 2063 Nov 10 06:32 .../panelQueueMiddleware.js
 -rw-r--r-- 1 user user 13845 Nov 06 10:15 .../queuedPanelActions.js
 -rw-r--r-- 1 user user 12345 Nov 05 14:20 .../dispatchHelper.js
 -rw-r--r-- 1 user user 10876 Nov 06 10:30 .../asyncActionUtils.js
 -rw-r--r-- 1 user user 25432 Nov 06 11:00 .../panelReducer.js
 ```
 ### 파일이 없다면?
 ```bash
 # 최신 코드를 pull 받으세요
 git fetch origin
 git pull origin <branch-name>
 ```
 ---
 ## 설정 순서
 ### Step 1: 미들웨어 import 추가
 **파일**: `src/store/store.js`
 ```javascript
 import panelQueueMiddleware from '../middleware/panelQueueMiddleware';
 ```
 ### Step 2: applyMiddleware에 추가
 ```javascript
 export const store = createStore(
  rootReducer,
  applyMiddleware(
    thunk,
    panelHistoryMiddleware,
    autoCloseMiddleware,
    panelQueueMiddleware  // ← 추가
  )
 );
 ```
 ### Step 3: 저장 및 빌드
 ```bash
 # 파일 저장 후
 npm run build
 # 또는 개발 서버 재시작
 npm start
 ```
 ### Step 4: 브라우저 콘솔 확인
 브라우저 개발자 도구(F12)를 열고 다음과 같은 로그가 보이는지 확인:
 ```
 [panelQueueMiddleware] 🚀 ACTION_ENQUEUED
 [panelQueueMiddleware] ⚡ STARTING_QUEUE_PROCESS
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 [panelReducer] 🟡 PROCESSING_QUEUE_ITEM
 [panelReducer] ✅ QUEUE_ITEM_PROCESSED
 ```
 ---
 ## 검증 방법
 ### 방법 1: 콘솔 로그 확인
 큐 시스템을 사용하는 액션을 dispatch하면 다음과 같은 로그가 출력됩니다:
 ```javascript
 import { pushPanelQueued } from '../actions/queuedPanelActions';
 import { panel_names } from '../utils/Config';
 dispatch(pushPanelQueued({ name: panel_names.SEARCH_PANEL }));
 ```
 **예상 로그**:
 ```
 [panelQueueMiddleware] 🚀 ACTION_ENQUEUED { action: 'PUSH_PANEL', queueId: 'queue_item_1_1699999999999' }
 [panelQueueMiddleware] ⚡ STARTING_QUEUE_PROCESS
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE { isProcessing: false, queueLength: 1 }
 [panelReducer] 🟡 PROCESSING_QUEUE_ITEM { action: 'PUSH_PANEL', queueId: 'queue_item_1_1699999999999', remainingQueueLength: 0 }
 [panelReducer] 🔵 PUSH_PANEL START { newPanelName: 'SEARCH_PANEL', currentPanels: [...], duplicatable: false }
 [panelReducer] 🔵 PUSH_PANEL END { resultPanels: [...], lastAction: 'push' }
 [panelReducer] ✅ QUEUE_ITEM_PROCESSED { action: 'PUSH_PANEL', queueId: 'queue_item_1_1699999999999', processingTime: 2 }
 ```
 ### 방법 2: Redux DevTools 확인
 Redux DevTools를 사용하여 액션 흐름을 확인:
 1. Chrome 확장 프로그램: Redux DevTools 설치
 2. 개발자 도구에서 "Redux" 탭 선택
 3. 다음 액션들이 순서대로 dispatch되는지 확인:
   - `ENQUEUE_PANEL_ACTION`
   - `PROCESS_PANEL_QUEUE`
   - `PUSH_PANEL` (또는 다른 패널 액션)
 ### 방법 3: State 확인
 Redux state를 확인하여 큐 관련 상태가 정상적으로 업데이트되는지 확인:
 ```javascript
 // 콘솔에서 실행
 store.getState().panels
 ```
 **예상 출력**:
 ```javascript
 {
  panels: [...],  // 실제 패널들
  lastPanelAction: 'push',
  // 큐 관련 상태
  panelActionQueue: [],  // 처리 대기 중인 큐 (처리 후 비어있음)
  isProcessingQueue: false,
  queueError: null,
  queueStats: {
    totalProcessed: 1,
    failedCount: 0,
    averageProcessingTime: 2.5
  },
  // 비동기 액션 관련
  asyncActions: {},
  completedAsyncActions: [],
  failedAsyncActions: []
 }
 ```
 ---
 ## 트러블슈팅
 ### 문제 1: 큐가 처리되지 않음
 #### 증상
 ```javascript
 dispatch(pushPanelQueued({ name: panel_names.SEARCH_PANEL }));
 // 아무 일도 일어나지 않음
 // 로그도 출력되지 않음
 ```
 #### 원인
 panelQueueMiddleware가 등록되지 않음
 #### 해결 방법
 1. `store.js` 파일 확인:
   ```javascript
   // import가 있는지 확인
   import panelQueueMiddleware from '../middleware/panelQueueMiddleware';
   // applyMiddleware에 추가되어 있는지 확인
   applyMiddleware(..., panelQueueMiddleware)
   ```
 2. 파일 저장 후 앱 재시작
 3. 브라우저 캐시 삭제 (Ctrl+Shift+R 또는 Cmd+Shift+R)
 ### 문제 2: 미들웨어 파일을 찾을 수 없음
 #### 증상
 ```
 Error: Cannot find module '../middleware/panelQueueMiddleware'
 ```
 #### 원인
 파일이 존재하지 않거나 경로가 잘못됨
 #### 해결 방법
 1. 파일 존재 확인:
   ```bash
   ls -la com.twin.app.shoptime/src/middleware/panelQueueMiddleware.js
   ```
 2. 파일이 없다면 최신 코드 pull:
   ```bash
   git fetch origin
   git pull origin main
   ```
 3. 여전히 없다면 커밋 확인:
   ```bash
   git log --oneline --grep="panelQueueMiddleware"
   # 5bd2774 [251106] feat: Queued Panel functions
   ```
 ### 문제 3: 로그는 보이는데 패널이 열리지 않음
 #### 증상
 ```
 [panelQueueMiddleware] 🚀 ACTION_ENQUEUED
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 [panelReducer] ✅ QUEUE_ITEM_PROCESSED
 // 하지만 패널이 화면에 표시되지 않음
 ```
 #### 원인
 UI 렌더링 문제 (Redux는 정상 작동)
 #### 해결 방법
 1. Redux state 확인:
   ```javascript
   console.log(store.getState().panels.panels);
   // 패널이 배열에 추가되었는지 확인
   ```
 2. 패널 컴포넌트 렌더링 로직 확인
 3. React DevTools로 컴포넌트 트리 확인
 ### 문제 4: 타입 에러
 #### 증상
 ```
 Error: Cannot read property 'type' of undefined
 ReferenceError: types is not defined
 ```
 #### 원인
 actionTypes.js에 필요한 타입이 정의되지 않음
 #### 해결 방법
 1. `src/actions/actionTypes.js` 확인:
   ```javascript
   export const types = {
     // ... 기존 타입들 ...
     // 큐 관련 타입들
     ENQUEUE_PANEL_ACTION: 'ENQUEUE_PANEL_ACTION',
     PROCESS_PANEL_QUEUE: 'PROCESS_PANEL_QUEUE',
     CLEAR_PANEL_QUEUE: 'CLEAR_PANEL_QUEUE',
     SET_QUEUE_PROCESSING: 'SET_QUEUE_PROCESSING',
     // 비동기 액션 타입들
     ENQUEUE_ASYNC_PANEL_ACTION: 'ENQUEUE_ASYNC_PANEL_ACTION',
     COMPLETE_ASYNC_PANEL_ACTION: 'COMPLETE_ASYNC_PANEL_ACTION',
     FAIL_ASYNC_PANEL_ACTION: 'FAIL_ASYNC_PANEL_ACTION',
   };
   ```
 2. 없다면 추가 후 저장
 ### 문제 5: 순서가 여전히 보장되지 않음
 #### 증상
 ```javascript
 dispatch(pushPanelQueued({ name: 'PANEL_1' }));
 dispatch(pushPanelQueued({ name: 'PANEL_2' }));
 // PANEL_2가 먼저 열림
 ```
 #### 원인
 일반 `pushPanel`과 `pushPanelQueued`를 혼용
 #### 해결 방법
 순서를 보장하려면 **모두** queued 버전 사용:
 ```javascript
 // ❌ 잘못된 사용
 dispatch(pushPanel({ name: 'PANEL_1' }));  // 일반 버전
 dispatch(pushPanelQueued({ name: 'PANEL_2' }));  // 큐 버전
 // ✅ 올바른 사용
 dispatch(pushPanelQueued({ name: 'PANEL_1' }));
 dispatch(pushPanelQueued({ name: 'PANEL_2' }));
 // 또는
 dispatch(enqueueMultiplePanelActions([
  pushPanelQueued({ name: 'PANEL_1' }),
  pushPanelQueued({ name: 'PANEL_2' })
 ]));
 ```
 ---
 ## 빠른 체크리스트
 설정이 완료되었는지 빠르게 확인:
 - [ ] `src/store/store.js`에 `import panelQueueMiddleware` 추가됨
 - [ ] `applyMiddleware`에 `panelQueueMiddleware` 추가됨 (맨 마지막 위치)
 - [ ] 파일 저장 및 앱 재시작
 - [ ] 브라우저 콘솔에서 큐 관련 로그 확인
 - [ ] Redux DevTools에서 액션 흐름 확인
 - [ ] Redux state에서 큐 관련 상태 확인
 모든 항목이 체크되었다면 설정 완료! 🎉
 ---
 ## 참고 자료
 - [README.md](./README.md) - 전체 개요
 - [04-solution-queue-system.md](./04-solution-queue-system.md) - 큐 시스템 상세 설명
 - [05-usage-patterns.md](./05-usage-patterns.md) - 사용 패턴 및 예제
 - [07-changelog.md](./07-changelog.md) - 변경 이력
 ---
 **작성일**: 2025-11-10
 **최종 수정일**: 2025-11-10
--- a/.docs/dispatch-async/07-changelog.md
+++ b/.docs/dispatch-async/07-changelog.md
@@ -0,0 +1,314 @@
 # 변경 이력 (Changelog)
 ## [2025-11-10] - 미들웨어 등록 및 문서 개선
 ### 🔧 수정 (Fixed)
 #### store.js - panelQueueMiddleware 등록
 **커밋**: `c12cc91 [수정] panelQueueMiddleware 등록 및 문서 업데이트`
 **문제**:
 - panelQueueMiddleware가 store.js에 등록되어 있지 않았음
 - 큐 시스템이 작동하지 않는 치명적인 문제
 - `ENQUEUE_PANEL_ACTION` dispatch 시 자동으로 `PROCESS_PANEL_QUEUE`가 실행되지 않음
 **해결**:
 ```javascript
 // src/store/store.js
 import panelQueueMiddleware from '../middleware/panelQueueMiddleware';
 export const store = createStore(
  rootReducer,
  applyMiddleware(thunk, panelHistoryMiddleware, autoCloseMiddleware, panelQueueMiddleware)
 );
 ```
 **영향**:
 - ✅ 큐 기반 패널 액션 시스템이 정상 작동
 - ✅ 패널 액션 순서 보장
 - ✅ 비동기 패널 액션 자동 처리
 ### 📝 문서 (Documentation)
 #### README.md
 - "설치 및 설정" 섹션 추가
 - panelQueueMiddleware 등록 필수 사항 강조
 - 등록하지 않으면 큐 시스템이 작동하지 않는다는 경고 추가
 #### 04-solution-queue-system.md
 - "사전 요구사항" 섹션 추가
 - 미들웨어 등록 코드 예제 포함
 - `src/store/store.js`를 관련 파일에 추가
 #### 05-usage-patterns.md
 - "초기 설정 확인사항" 체크리스트 추가
 - panelQueueMiddleware 등록 여부를 최우선 확인 항목으로 배치
 ---
 ## [2025-11-10] - 초기 문서 작성
 ### ✨ 추가 (Added)
 #### 문서 작성
 **커밋**: `f75860c [문서화] Dispatch 비동기 처리 순서 보장 솔루션 문서 작성`
 dispatch 비동기 처리 순서 보장 문제와 해결 방법을 체계적으로 정리한 문서 세트:
 1. **README.md**
   - 전체 개요 및 목차
   - 주요 솔루션 요약
   - 관련 파일 목록
   - 커밋 히스토리
 2. **01-problem.md**
   - 문제 상황 및 원인 분석
   - Redux-thunk에서 dispatch 순서가 보장되지 않는 이유
   - 실제 발생 가능한 버그 시나리오
   - 기존 해결 방법의 한계
 3. **02-solution-dispatch-helper.md**
   - dispatchHelper.js 솔루션 설명
   - 5가지 헬퍼 함수 상세 설명:
     - `createSequentialDispatch`
     - `createApiThunkWithChain`
     - `withLoadingState`
     - `createConditionalDispatch`
     - `createParallelDispatch`
   - Before/After 코드 비교
   - 실제 사용 예제
 4. **03-solution-async-utils.md**
   - asyncActionUtils.js 솔루션 설명
   - API 성공 기준 명확화 (HTTP 200-299 + retCode 0/'0')
   - Promise 체인 보장 방법 (reject 없이 resolve만 사용)
   - 주요 함수 설명:
     - `isApiSuccess`
     - `fetchApi`
     - `tAxiosToPromise`
     - `wrapAsyncAction`
     - `withTimeout`
     - `executeParallelAsyncActions`
 5. **04-solution-queue-system.md**
   - 큐 기반 패널 액션 시스템 설명
   - 기본 패널 액션 (pushPanelQueued, popPanelQueued 등)
   - 비동기 패널 액션 (enqueueAsyncPanelAction)
   - API 호출 후 패널 액션 (createApiWithPanelActions)
   - 비동기 액션 시퀀스 (createAsyncPanelSequence)
   - panelQueueMiddleware 동작 원리
   - 리듀서 상태 구조
 6. **05-usage-patterns.md**
   - 솔루션 선택 가이드 (의사결정 플로우차트)
   - 솔루션 비교표
   - 공통 패턴 Before/After 비교
   - 실전 예제 5가지:
     - 검색 기능
     - 장바구니 추가
     - 로그인 플로우
     - 다단계 폼 제출
     - 병렬 데이터 로딩
   - 마이그레이션 가이드
   - Best Practices
   - 체크리스트
 **문서 통계**:
 - 총 6개 마크다운 파일
 - 약 3,000줄
 - 50개 이상의 코드 예제
 - Before/After 비교 20개 이상
 ---
 ## [2025-11-06] - 큐 시스템 구현
 ### ✨ 추가 (Added)
 #### Dispatch Queue Implementation
 **커밋**: `f9290a1 [251106] fix: Dispatch Queue implementation`
 - `asyncActionUtils.js` 추가
  - Promise 기반 비동기 액션 처리
  - API 성공 기준 명확화
  - 타임아웃 지원
 - `queuedPanelActions.js` 확장
  - 비동기 패널 액션 지원
  - API 호출 후 패널 액션 자동 실행
  - 비동기 액션 시퀀스
 - `panelReducer.js` 확장
  - 큐 상태 관리
  - 비동기 액션 상태 추적
  - 큐 처리 통계
 #### Queued Panel Functions
 **커밋**: `5bd2774 [251106] feat: Queued Panel functions`
 - `queuedPanelActions.js` 초기 구현
  - 기본 큐 액션 (pushPanelQueued, popPanelQueued 등)
  - 여러 액션 일괄 큐 추가
  - 패널 시퀀스 생성
 - `panelQueueMiddleware.js` 추가
  - 큐 액션 자동 감지
  - 순차 처리 자동 시작
  - 연속 처리 지원
 - `panelReducer.js` 큐 기능 추가
  - 큐 상태 관리
  - 큐 처리 로직
  - 큐 통계 수집
 ---
 ## [2025-11-05] - dispatch 헬퍼 함수
 ### ✨ 추가 (Added)
 #### dispatchHelper.js
 **커밋**: `9490d72 [251105] feat: dispatchHelper.js`
 Promise 체인 기반의 dispatch 순차 실행 헬퍼 함수 모음:
 - `createSequentialDispatch`
  - 여러 dispatch를 순차적으로 실행
  - Promise 체인으로 순서 보장
  - delay 옵션 지원
  - stopOnError 옵션 지원
 - `createApiThunkWithChain`
  - API 호출 후 dispatch 자동 체이닝
  - TAxios onSuccess/onFail 패턴 호환
  - response를 각 action에 전달
  - 에러 처리 action 지원
 - `withLoadingState`
  - 로딩 상태 자동 관리
  - changeAppStatus 자동 on/off
  - 성공/에러 시 추가 dispatch 지원
  - loadingType 옵션
 - `createConditionalDispatch`
  - 조건에 따라 다른 dispatch 실행
  - getState() 결과 기반 분기
  - 배열 또는 단일 action 지원
 - `createParallelDispatch`
  - 여러 API를 병렬로 실행
  - Promise.all 사용
  - 로딩 상태 관리 옵션
 ---
 ## 관련 커밋 전체 목록
 ```bash
 c12cc91 [수정] panelQueueMiddleware 등록 및 문서 업데이트
 f75860c [문서화] Dispatch 비동기 처리 순서 보장 솔루션 문서 작성
 f9290a1 [251106] fix: Dispatch Queue implementation
 5bd2774 [251106] feat: Queued Panel functions
 9490d72 [251105] feat: dispatchHelper.js
 ```
 ---
 ## 마이그레이션 가이드
 ### 기존 코드에서 새 솔루션으로 전환
 #### 1단계: setTimeout 패턴 제거
 ```javascript
 // Before
 dispatch(action1());
 setTimeout(() => {
  dispatch(action2());
 }, 0);
 // After
 dispatch(createSequentialDispatch([action1(), action2()]));
 ```
 #### 2단계: API 패턴 개선
 ```javascript
 // Before
 const onSuccess = (response) => {
  dispatch({ type: types.ACTION_1, payload: response.data });
  dispatch(action2());
 };
 TAxios(..., onSuccess, onFail);
 // After
 dispatch(createApiThunkWithChain(
  (d, gs, onS, onF) => TAxios(d, gs, ..., onS, onF),
  [
    (response) => ({ type: types.ACTION_1, payload: response.data }),
    action2()
  ]
 ));
 ```
 #### 3단계: 패널 액션을 큐 버전으로 전환
 ```javascript
 // Before
 dispatch(pushPanel({ name: panel_names.SEARCH }));
 // After
 dispatch(pushPanelQueued({ name: panel_names.SEARCH }));
 ```
 ---
 ## Breaking Changes
 ### 없음
 모든 새로운 기능은 기존 코드와 완전히 호환됩니다:
 - 기존 `pushPanel`, `popPanel` 등은 그대로 동작
 - 새로운 큐 버전은 선택적으로 사용 가능
 - 점진적 마이그레이션 가능
 ---
 ## 알려진 이슈
 ### 해결됨
 1. **panelQueueMiddleware 미등록 문제** (2025-11-10 해결)
   - 문제: 큐 시스템이 작동하지 않음
   - 해결: store.js에 미들웨어 등록
 ### 현재 이슈
 없음
 ---
 ## 향후 계획
 ### 예정된 개선사항
 1. **성능 최적화**
   - 큐 처리 성능 모니터링
   - 대량 액션 처리 최적화
 2. **에러 처리 강화**
   - 더 상세한 에러 메시지
   - 에러 복구 전략
 3. **개발자 도구**
   - 큐 상태 시각화
   - 디버깅 도구
 4. **테스트 코드**
   - 단위 테스트 추가
   - 통합 테스트 추가
 ---
 **작성일**: 2025-11-10
 **최종 수정일**: 2025-11-10
--- a/.docs/dispatch-async/08-troubleshooting.md
+++ b/.docs/dispatch-async/08-troubleshooting.md
@@ -0,0 +1,606 @@
 # 트러블슈팅 가이드
 ## 📋 목차
 1. [일반적인 문제](#일반적인-문제)
 2. [큐 시스템 문제](#큐-시스템-문제)
 3. [API 호출 문제](#api-호출-문제)
 4. [성능 문제](#성능-문제)
 5. [디버깅 팁](#디버깅-팁)
 ---
 ## 일반적인 문제
 ### 문제 1: dispatch 순서가 여전히 보장되지 않음
 #### 증상
 ```javascript
 dispatch(action1());
 dispatch(action2());
 dispatch(action3());
 // 실행 순서: action2 → action3 → action1
 ```
 #### 가능한 원인
 1. **일반 dispatch와 큐 dispatch 혼용**
   ```javascript
   // ❌ 잘못된 사용
   dispatch(pushPanel({ name: 'PANEL_1' }));  // 일반
   dispatch(pushPanelQueued({ name: 'PANEL_2' }));  // 큐
   ```
 2. **async/await 없이 비동기 처리**
   ```javascript
   // ❌ 잘못된 사용
   fetchData();  // Promise를 기다리지 않음
   dispatch(action());
   ```
 3. **헬퍼 함수를 사용하지 않음**
   ```javascript
   // ❌ 잘못된 사용
   dispatch(asyncAction1());
   dispatch(asyncAction2());  // asyncAction1이 완료되기 전에 실행
   ```
 #### 해결 방법
 **방법 1: 큐 시스템 사용** (패널 액션인 경우)
 ```javascript
 // ✅ 올바른 사용
 dispatch(enqueueMultiplePanelActions([
  pushPanelQueued({ name: 'PANEL_1' }),
  pushPanelQueued({ name: 'PANEL_2' }),
  pushPanelQueued({ name: 'PANEL_3' })
 ]));
 ```
 **방법 2: createSequentialDispatch 사용**
 ```javascript
 // ✅ 올바른 사용
 dispatch(createSequentialDispatch([
  action1(),
  action2(),
  action3()
 ]));
 ```
 **방법 3: async/await 사용** (Chrome 68+)
 ```javascript
 // ✅ 올바른 사용
 export const myAction = () => async (dispatch, getState) => {
  await dispatch(action1());
  await dispatch(action2());
  await dispatch(action3());
 };
 ```
 ---
 ### 문제 2: "Cannot find module" 에러
 #### 증상
 ```
 Error: Cannot find module '../utils/dispatchHelper'
 Error: Cannot find module '../middleware/panelQueueMiddleware'
 ```
 #### 원인
 - 파일이 존재하지 않음
 - import 경로가 잘못됨
 - 빌드가 필요함
 #### 해결 방법
 **Step 1: 파일 존재 확인**
 ```bash
 # 프로젝트 루트에서 실행
 ls -la com.twin.app.shoptime/src/utils/dispatchHelper.js
 ls -la com.twin.app.shoptime/src/middleware/panelQueueMiddleware.js
 ls -la com.twin.app.shoptime/src/utils/asyncActionUtils.js
 ```
 **Step 2: 최신 코드 pull**
 ```bash
 git fetch origin
 git pull origin <branch-name>
 ```
 **Step 3: node_modules 재설치**
 ```bash
 cd com.twin.app.shoptime
 rm -rf node_modules package-lock.json
 npm install
 ```
 **Step 4: 빌드 재실행**
 ```bash
 npm run build
 # 또는
 npm start
 ```
 ---
 ### 문제 3: 타입 에러 (types is not defined)
 #### 증상
 ```
 ReferenceError: types is not defined
 TypeError: Cannot read property 'ENQUEUE_PANEL_ACTION' of undefined
 ```
 #### 원인
 actionTypes.js에 필요한 타입이 정의되지 않음
 #### 해결 방법
 **Step 1: actionTypes.js 확인**
 ```javascript
 // src/actions/actionTypes.js
 export const types = {
  // ... 기존 타입들 ...
  // 큐 관련 타입들 (필수!)
  ENQUEUE_PANEL_ACTION: 'ENQUEUE_PANEL_ACTION',
  PROCESS_PANEL_QUEUE: 'PROCESS_PANEL_QUEUE',
  CLEAR_PANEL_QUEUE: 'CLEAR_PANEL_QUEUE',
  SET_QUEUE_PROCESSING: 'SET_QUEUE_PROCESSING',
  // 비동기 액션 타입들 (필수!)
  ENQUEUE_ASYNC_PANEL_ACTION: 'ENQUEUE_ASYNC_PANEL_ACTION',
  COMPLETE_ASYNC_PANEL_ACTION: 'COMPLETE_ASYNC_PANEL_ACTION',
  FAIL_ASYNC_PANEL_ACTION: 'FAIL_ASYNC_PANEL_ACTION',
 };
 ```
 **Step 2: import 확인**
 ```javascript
 import { types } from '../actions/actionTypes';
 ```
 ---
 ## 큐 시스템 문제
 ### 문제 4: 큐가 처리되지 않음
 #### 증상
 ```javascript
 dispatch(pushPanelQueued({ name: panel_names.SEARCH_PANEL }));
 // 아무 일도 일어나지 않음
 // 콘솔 로그도 없음
 ```
 #### 원인
 **panelQueueMiddleware가 등록되지 않음** (가장 흔한 문제!)
 #### 해결 방법
 **Step 1: store.js 확인**
 ```javascript
 // src/store/store.js
 import panelQueueMiddleware from '../middleware/panelQueueMiddleware';
 export const store = createStore(
  rootReducer,
  applyMiddleware(
    thunk,
    panelHistoryMiddleware,
    autoCloseMiddleware,
    panelQueueMiddleware  // ← 이것이 있는지 확인!
  )
 );
 ```
 **Step 2: import 경로 확인**
 ```javascript
 // ✅ 올바른 import
 import panelQueueMiddleware from '../middleware/panelQueueMiddleware';
 // ❌ 잘못된 import
 import { panelQueueMiddleware } from '../middleware/panelQueueMiddleware';
 // default export이므로 중괄호 없이 import해야 함
 ```
 **Step 3: 앱 재시작**
 ```bash
 # 개발 서버 재시작
 npm start
 ```
 **Step 4: 브라우저 캐시 삭제**
 - Chrome: Ctrl+Shift+R (Windows) 또는 Cmd+Shift+R (Mac)
 ---
 ### 문제 5: 큐가 무한 루프에 빠짐
 #### 증상
 ```
 [panelQueueMiddleware] 🚀 ACTION_ENQUEUED
 [panelQueueMiddleware] ⚡ STARTING_QUEUE_PROCESS
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 ... (무한 반복)
 ```
 #### 원인
 1. 큐 처리 중에 다시 큐에 액션 추가
 2. `isProcessingQueue` 플래그가 제대로 설정되지 않음
 #### 해결 방법
 **방법 1: 큐 액션 내부에서 일반 dispatch 사용**
 ```javascript
 // ❌ 잘못된 사용 (무한 루프 발생)
 export const myAction = () => (dispatch) => {
  dispatch(pushPanelQueued({ name: 'PANEL_1' }));
  dispatch(pushPanelQueued({ name: 'PANEL_2' }));  // 큐 처리 중 큐 추가
 };
 // ✅ 올바른 사용
 export const myAction = () => (dispatch) => {
  dispatch(enqueueMultiplePanelActions([
    pushPanelQueued({ name: 'PANEL_1' }),
    pushPanelQueued({ name: 'PANEL_2' })
  ]));
 };
 ```
 **방법 2: 리듀서 로직 확인**
 ```javascript
 // panelReducer.js에서 확인
 case types.PROCESS_PANEL_QUEUE: {
  // 이미 처리 중이면 무시
  if (state.isProcessingQueue || state.panelActionQueue.length === 0) {
    return state;  // ← 이 로직이 있는지 확인
  }
  // ...
 }
 ```
 ---
 ### 문제 6: 큐 통계가 업데이트되지 않음
 #### 증상
 ```javascript
 store.getState().panels.queueStats
 // { totalProcessed: 0, failedCount: 0, averageProcessingTime: 0 }
 // 항상 0으로 유지됨
 ```
 #### 원인
 큐 처리가 정상적으로 완료되지 않음
 #### 해결 방법
 **Step 1: 콘솔 로그 확인**
 ```
 [panelReducer] ✅ QUEUE_ITEM_PROCESSED  ← 이 로그가 보이는지 확인
 ```
 **Step 2: 에러 발생 확인**
 ```javascript
 store.getState().panels.queueError
 // null이어야 정상
 ```
 **Step 3: 큐 처리 완료 여부 확인**
 ```javascript
 store.getState().panels.isProcessingQueue
 // false여야 정상 (처리 완료)
 ```
 ---
 ## API 호출 문제
 ### 문제 7: API 성공인데 onFail이 호출됨
 #### 증상
 ```javascript
 // API 호출
 // HTTP 200, retCode: 0
 // 그런데 onFail이 호출됨
 ```
 #### 원인
 프로젝트 성공 기준을 이해하지 못함
 #### 프로젝트 성공 기준
 **HTTP 200-299 + retCode 0/'0' 둘 다 만족해야 성공!**
 ```javascript
 // ✅ 성공 케이스
 { status: 200, data: { retCode: 0, data: {...} } }
 { status: 200, data: { retCode: '0', data: {...} } }
 // ❌ 실패 케이스
 { status: 200, data: { retCode: 1, message: '에러' } }  // retCode가 0이 아님
 { status: 500, data: { retCode: 0, data: {...} } }  // HTTP 에러
 ```
 #### 해결 방법
 **방법 1: isApiSuccess 사용**
 ```javascript
 import { isApiSuccess } from '../utils/asyncActionUtils';
 const response = { status: 200 };
 const responseData = { retCode: 1, message: '에러' };
 if (isApiSuccess(response, responseData)) {
  // 성공 처리
 } else {
  // 실패 처리 (retCode가 1이므로 실패!)
 }
 ```
 **방법 2: asyncActionUtils 사용**
 ```javascript
 import { tAxiosToPromise } from '../utils/asyncActionUtils';
 const result = await tAxiosToPromise(...);
 if (result.success) {
  // HTTP 200-299 + retCode 0/'0'
  console.log(result.data);
 } else {
  // 실패
  console.error(result.error);
 }
 ```
 ---
 ### 문제 8: API 타임아웃이 작동하지 않음
 #### 증상
 ```javascript
 dispatch(enqueueAsyncPanelAction({
  asyncAction: (d, gs, onS, onF) => { /* 느린 API */ },
  timeout: 5000  // 5초
 }));
 // 10초가 지나도 타임아웃되지 않음
 ```
 #### 원인
 1. `withTimeout`이 적용되지 않음
 2. 타임아웃 값이 잘못 설정됨
 #### 해결 방법
 **방법 1: enqueueAsyncPanelAction 사용 시**
 ```javascript
 // ✅ timeout 옵션 사용
 dispatch(enqueueAsyncPanelAction({
  asyncAction: (dispatch, getState, onSuccess, onFail) => {
    TAxios(dispatch, getState, 'get', URL, {}, {}, onSuccess, onFail);
  },
  timeout: 5000,  // 5초 (ms 단위)
  onFail: (error) => {
    if (error.code === 'TIMEOUT') {
      console.error('타임아웃 발생!');
    }
  }
 }));
 ```
 **방법 2: withTimeout 직접 사용**
 ```javascript
 import { withTimeout, fetchApi } from '../utils/asyncActionUtils';
 const result = await withTimeout(
  fetchApi('/api/slow-endpoint'),
  5000,  // 5초
  '요청 시간이 초과되었습니다'
 );
 if (result.error?.code === 'TIMEOUT') {
  console.error('타임아웃!');
 }
 ```
 ---
 ## 성능 문제
 ### 문제 9: 큐 처리가 너무 느림
 #### 증상
 ```javascript
 // 100개의 패널 액션을 큐에 추가
 // 처리하는데 10초 이상 소요
 ```
 #### 원인
 1. 각 액션이 복잡한 로직 수행
 2. 동기적으로 처리되어 병목 발생
 #### 해결 방법
 **방법 1: 불필요한 액션 제거**
 ```javascript
 // ❌ 잘못된 사용
 for (let i = 0; i < 100; i++) {
  dispatch(pushPanelQueued({ name: `PANEL_${i}` }));
 }
 // ✅ 올바른 사용 - 필요한 것만
 dispatch(pushPanelQueued({ name: 'MAIN_PANEL' }));
 ```
 **방법 2: 배치 처리**
 ```javascript
 // 한 번에 여러 액션 추가
 dispatch(enqueueMultiplePanelActions(
  panels.map(panel => pushPanelQueued(panel))
 ));
 ```
 **방법 3: 병렬 처리가 필요하면 큐 사용 안함**
 ```javascript
 // 순서가 중요하지 않은 경우
 dispatch(createParallelDispatch([
  fetchData1(),
  fetchData2(),
  fetchData3()
 ]));
 ```
 ---
 ### 문제 10: 메모리 누수
 #### 증상
 ```javascript
 // 오랜 시간 앱 사용 후
 store.getState().panels.completedAsyncActions.length
 // → 10000개 이상
 ```
 #### 원인
 완료된 비동기 액션 ID가 계속 누적됨
 #### 해결 방법
 **방법 1: 주기적으로 클리어**
 ```javascript
 // 일정 시간마다 완료된 액션 정리
 setInterval(() => {
  const state = store.getState().panels;
  if (state.completedAsyncActions.length > 1000) {
    // 클리어 액션 dispatch
    dispatch({ type: types.CLEAR_COMPLETED_ASYNC_ACTIONS });
  }
 }, 60000);  // 1분마다
 ```
 **방법 2: 리듀서에 최대 개수 제한 추가**
 ```javascript
 // panelReducer.js
 case types.COMPLETE_ASYNC_PANEL_ACTION: {
  const newCompleted = [...state.completedAsyncActions, action.payload.actionId];
  // 최근 100개만 유지
  const trimmed = newCompleted.slice(-100);
  return {
    ...state,
    completedAsyncActions: trimmed
  };
 }
 ```
 ---
 ## 디버깅 팁
 ### Tip 1: 콘솔 로그 활용
 모든 헬퍼 함수와 미들웨어는 상세한 로그를 출력합니다:
 ```javascript
 // 큐 관련 로그
 [panelQueueMiddleware] 🚀 ACTION_ENQUEUED
 [panelQueueMiddleware] ⚡ STARTING_QUEUE_PROCESS
 [panelReducer] 🟡 PROCESS_PANEL_QUEUE
 [panelReducer] 🟡 PROCESSING_QUEUE_ITEM
 [panelReducer] ✅ QUEUE_ITEM_PROCESSED
 // 비동기 액션 로그
 [queuedPanelActions] 🔄 ENQUEUE_ASYNC_PANEL_ACTION
 [queuedPanelActions] ⚡ EXECUTING_ASYNC_ACTION
 [queuedPanelActions] ✅ ASYNC_ACTION_SUCCESS
 // asyncActionUtils 로그
 [asyncActionUtils] 🌐 FETCH_API_START
 [asyncActionUtils] 📊 API_RESPONSE
 [asyncActionUtils] ✅ TAXIOS_SUCCESS
 ```
 ### Tip 2: Redux DevTools 사용
 1. Chrome 확장 프로그램 설치: Redux DevTools
 2. 개발자 도구 → Redux 탭
 3. 액션 히스토리 확인
 4. State diff 확인
 ### Tip 3: 브레이크포인트 설정
 ```javascript
 // 디버깅용 브레이크포인트
 export const myAction = () => (dispatch, getState) => {
  debugger;  // ← 여기서 멈춤
  const state = getState();
  console.log('Current state:', state);
  dispatch(action1());
  debugger;  // ← 여기서 다시 멈춤
 };
 ```
 ### Tip 4: State 스냅샷
 ```javascript
 // 콘솔에서 실행
 const snapshot = JSON.parse(JSON.stringify(store.getState()));
 console.log(snapshot);
 // 특정 부분만
 const panelsSnapshot = JSON.parse(JSON.stringify(store.getState().panels));
 console.log(panelsSnapshot);
 ```
 ### Tip 5: 큐 상태 모니터링
 ```javascript
 // 콘솔에서 실행
 window.monitorQueue = setInterval(() => {
  const state = store.getState().panels;
  console.log('Queue status:', {
    queueLength: state.panelActionQueue.length,
    isProcessing: state.isProcessingQueue,
    stats: state.queueStats
  });
 }, 1000);
 // 중지
 clearInterval(window.monitorQueue);
 ```
 ---
 ## 도움이 필요하신가요?
 ### 체크리스트
 문제 해결 전에 다음을 확인하세요:
 - [ ] panelQueueMiddleware가 store.js에 등록되어 있는가?
 - [ ] 필요한 파일들이 모두 존재하는가?
 - [ ] actionTypes.js에 필요한 타입들이 정의되어 있는가?
 - [ ] 콘솔 로그를 확인했는가?
 - [ ] Redux DevTools로 액션 흐름을 확인했는가?
 - [ ] 앱을 재시작했는가?
 - [ ] 브라우저 캐시를 삭제했는가?
 ### 추가 리소스
 - [README.md](./README.md) - 전체 개요
 - [06-setup-guide.md](./06-setup-guide.md) - 설정 가이드
 - [05-usage-patterns.md](./05-usage-patterns.md) - 사용 패턴
 - [07-changelog.md](./07-changelog.md) - 변경 이력
 ---
 **작성일**: 2025-11-10
 **최종 수정일**: 2025-11-10
--- a/.docs/dispatch-async/README.md
+++ b/.docs/dispatch-async/README.md
@@ -7,6 +7,9 @@
 3. [해결 방법 2: asyncActionUtils.js](./03-solution-async-utils.md)
 4. [해결 방법 3: 큐 기반 패널 액션 시스템](./04-solution-queue-system.md)
 5. [사용 패턴 및 예제](./05-usage-patterns.md)
 6. [설정 가이드](./06-setup-guide.md) ⭐
 7. [변경 이력 (Changelog)](./07-changelog.md)
 8. [트러블슈팅](./08-troubleshooting.md) ⭐
 ## 🎯 개요
@@ -114,11 +117,19 @@ f9290a1 [251106] fix: Dispatch Queue implementation
 각 솔루션에 대한 자세한 설명은 개별 문서를 참고하세요.
 ### 시작하기
 - **처음 시작한다면** → [06-setup-guide.md](./06-setup-guide.md) ⭐
 - **문제가 발생했다면** → [08-troubleshooting.md](./08-troubleshooting.md) ⭐
 ### 이해하기
 - 기존 코드의 문제점이 궁금하다면 → [01-problem.md](./01-problem.md)
 - dispatchHelper 사용법이 궁금하다면 → [02-solution-dispatch-helper.md](./02-solution-dispatch-helper.md)
 - asyncActionUtils 사용법이 궁금하다면 → [03-solution-async-utils.md](./03-solution-async-utils.md)
 - 큐 시스템 사용법이 궁금하다면 → [04-solution-queue-system.md](./04-solution-queue-system.md)
 ### 실전 적용
 - 실제 사용 예제가 궁금하다면 → [05-usage-patterns.md](./05-usage-patterns.md)
 - 변경 이력을 확인하려면 → [07-changelog.md](./07-changelog.md)
 ---