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`

#### 수정 전
```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