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

## 추가된 문서 ### 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