optrader/shoptime
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

restore: .docs 폴더 복원 및 .gitignore 수정

Browse Source 
- claude/ 브랜치에서 누락된 .docs 폴더 복원 완료
- dispatch-async 관련 문서 9개 파일 복원
  * 01-problem.md, 02-solution-dispatch-helper.md
  * 03-solution-async-utils.md, 04-solution-queue-system.md
  * 05-usage-patterns.md, 06-setup-guide.md
  * 07-changelog.md, 08-troubleshooting.md, README.md
- MediaPlayer.v2 관련 문서 4개 파일 복원
  * MediaPlayer-v2-README.md, MediaPlayer-v2-Required-Changes.md
  * MediaPlayer-v2-Risk-Analysis.md, PR-MediaPlayer-v2.md
- 기타 분석 문서 2개 파일 복원
  * modal-transition-analysis.md, video-player-analysis-and-optimization-plan.md
- .gitignore에서 .docs 항목 제거로 문서 추적 가능하도록 수정

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: GLM 4.6 <noreply@z.ai>
This commit is contained in:
hyeon soo noh
2025-11-11 10:00:59 +09:00
parent 9d8dd7e661
commit fd5a171a28
16 changed files with 6784 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

396
com.twin.app.shoptime/.docs/dispatch-async/06-setup-guide.md Normal file
View File

@@ -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