shoptime/.docs/dispatch-async/06-setup-guide.md

설정 가이드

📋 목차

1. 초기 설정
2. 파일 구조 확인
3. 설정 순서
4. 검증 방법
5. 트러블슈팅

---

초기 설정

1️⃣ 필수: panelQueueMiddleware 등록

큐 기반 패널 액션 시스템을 사용하려면 반드시 Redux store에 미들웨어를 등록해야 합니다.

파일 위치

com.twin.app.shoptime/src/store/store.js

수정 전

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 등록 없음!
);

수정 후

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️⃣ 미들웨어 등록 순서

미들웨어 등록 순서는 다음과 같습니다:

applyMiddleware(
  thunk,                    // 1. Redux-thunk (비동기 액션 지원)
  panelHistoryMiddleware,   // 2. 패널 히스토리 관리
  autoCloseMiddleware,      // 3. 자동 닫기 처리
  panelQueueMiddleware      // 4. 패널 큐 처리 (맨 마지막)
)

중요: panelQueueMiddleware는 맨 마지막에 위치해야 합니다!

• 다른 미들웨어들이 먼저 액션을 처리한 후
• 큐 미들웨어가 큐 관련 액션을 감지하고 처리합니다

---

파일 구조 확인

필수 파일들이 모두 존재하는지 확인

# 프로젝트 루트에서 실행
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

파일이 없다면?

# 최신 코드를 pull 받으세요
git fetch origin
git pull origin <branch-name>

---

설정 순서

Step 1: 미들웨어 import 추가

파일: src/store/store.js

import panelQueueMiddleware from '../middleware/panelQueueMiddleware';

Step 2: applyMiddleware에 추가

export const store = createStore(
  rootReducer,
  applyMiddleware(
    thunk,
    panelHistoryMiddleware,
    autoCloseMiddleware,
    panelQueueMiddleware  // ← 추가
  )
);

Step 3: 저장 및 빌드

# 파일 저장 후
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하면 다음과 같은 로그가 출력됩니다:

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를 확인하여 큐 관련 상태가 정상적으로 업데이트되는지 확인:

// 콘솔에서 실행
store.getState().panels

예상 출력:

{
  panels: [...],  // 실제 패널들
  lastPanelAction: 'push',

  // 큐 관련 상태
  panelActionQueue: [],  // 처리 대기 중인 큐 (처리 후 비어있음)
  isProcessingQueue: false,
  queueError: null,
  queueStats: {
    totalProcessed: 1,
    failedCount: 0,
    averageProcessingTime: 2.5
  },

  // 비동기 액션 관련
  asyncActions: {},
  completedAsyncActions: [],
  failedAsyncActions: []
}

---

트러블슈팅

문제 1: 큐가 처리되지 않음

증상

dispatch(pushPanelQueued({ name: panel_names.SEARCH_PANEL }));
// 아무 일도 일어나지 않음
// 로그도 출력되지 않음

원인

panelQueueMiddleware가 등록되지 않음

해결 방법

1. store.js 파일 확인:

   // 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. 파일 존재 확인:

   ls -la com.twin.app.shoptime/src/middleware/panelQueueMiddleware.js
   

2. 파일이 없다면 최신 코드 pull:

   git fetch origin
   git pull origin main
   

3. 여전히 없다면 커밋 확인:

   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 확인:

   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 확인:

   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: 순서가 여전히 보장되지 않음

증상

dispatch(pushPanelQueued({ name: 'PANEL_1' }));
dispatch(pushPanelQueued({ name: 'PANEL_2' }));
// PANEL_2가 먼저 열림

원인

일반 pushPanel과 pushPanelQueued를 혼용

해결 방법

순서를 보장하려면 모두 queued 버전 사용:

// ❌ 잘못된 사용
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 - 전체 개요
• 04-solution-queue-system.md - 큐 시스템 상세 설명
• 05-usage-patterns.md - 사용 패턴 및 예제
• 07-changelog.md - 변경 이력

---

작성일: 2025-11-10 최종 수정일: 2025-11-10