shoptime/.docs/dispatch-async/README.md

# Dispatch 비동기 처리 순서 보장 솔루션

## 📋 목차

1. [문제 상황](./01-problem.md)
2. [해결 방법 1: dispatchHelper.js](./02-solution-dispatch-helper.md)
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) ⭐

## 🎯 개요

이 문서는 Redux-thunk 환경에서 여러 개의 dispatch를 순차적으로 실행할 때 순서가 보장되지 않는 문제를 해결하기 위해 구현된 솔루션들을 정리한 문서입니다.

## ⚙️ 설치 및 설정

### 필수: panelQueueMiddleware 등록

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

**파일**: `src/store/store.js`

```javascript
import { applyMiddleware, combineReducers, createStore } from 'redux';
import thunk from 'redux-thunk';
import { panelHistoryMiddleware } from '../middleware/panelHistoryMiddleware';
import { autoCloseMiddleware } from '../middleware/autoCloseMiddleware';
import panelQueueMiddleware from '../middleware/panelQueueMiddleware'; // ← 추가

// ... reducers ...

export const store = createStore(
  rootReducer,
  applyMiddleware(
    thunk,
    panelHistoryMiddleware,
    autoCloseMiddleware,
    panelQueueMiddleware  // ← 추가 (맨 마지막에 위치)
  )
);
```

**⚠️ 중요**: panelQueueMiddleware를 등록하지 않으면 큐 시스템이 작동하지 않습니다!

## 🚀 주요 솔루션

### 1. dispatchHelper.js (2025-11-05)
Promise 체인 기반의 dispatch 순차 실행 헬퍼 함수 모음

- `createSequentialDispatch`: 순차적 dispatch 실행
- `createApiThunkWithChain`: API 후 dispatch 자동 체이닝
- `withLoadingState`: 로딩 상태 자동 관리
- `createConditionalDispatch`: 조건부 dispatch
- `createParallelDispatch`: 병렬 dispatch

### 2. asyncActionUtils.js (2025-11-06)
Promise 기반 비동기 액션 처리 및 성공/실패 기준 명확화

- API 성공 기준: HTTP 200-299 + retCode 0/'0'
- 모든 비동기 작업을 Promise로 래핑
- reject 없이 resolve + success 플래그 사용
- 타임아웃 지원

### 3. 큐 기반 패널 액션 시스템 (2025-11-06)
미들웨어 기반의 액션 큐 처리 시스템

- `queuedPanelActions.js`: 큐 기반 패널 액션
- `panelQueueMiddleware.js`: 자동 큐 처리 미들웨어
- `panelReducer.js`: 큐 상태 관리

## 📊 커밋 히스토리

```
f9290a1 [251106] fix: Dispatch Queue implementation
  - asyncActionUtils.js 추가
  - queuedPanelActions.js 확장
  - panelReducer.js 확장

5bd2774 [251106] feat: Queued Panel functions
  - queuedPanelActions.js 초기 구현
  - panelQueueMiddleware.js 추가

9490d72 [251105] feat: dispatchHelper.js
  - createSequentialDispatch
  - createApiThunkWithChain
  - withLoadingState
  - createConditionalDispatch
  - createParallelDispatch
```

## 📂 관련 파일

### Core Files
- `src/utils/dispatchHelper.js`
- `src/utils/asyncActionUtils.js`
- `src/actions/queuedPanelActions.js`
- `src/middleware/panelQueueMiddleware.js`
- `src/reducers/panelReducer.js`

### Example Files
- `src/actions/homeActions.js`
- `src/actions/cartActions.js`

## 🔑 핵심 개선 사항

1. ✅ **순서 보장**: Promise 체인과 큐 시스템으로 dispatch 순서 보장
2. ✅ **에러 처리**: reject 대신 resolve + success 플래그로 체인 보장
3. ✅ **성공 기준 명확화**: HTTP 상태 + retCode 둘 다 확인
4. ✅ **타임아웃 지원**: withTimeout으로 응답 없는 API 처리
5. ✅ **로깅**: 모든 단계에서 상세한 로그 출력
6. ✅ **호환성**: 기존 코드와 완전 호환 (선택적 사용 가능)

## 🎓 학습 자료

각 솔루션에 대한 자세한 설명은 개별 문서를 참고하세요.

### 시작하기
- **처음 시작한다면** → [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)

---

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