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

- 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>
2025-11-11 10:00:59 +09:00
parent 9d8dd7e661
commit fd5a171a28
16 changed files with 6784 additions and 2 deletions
--- a/com.twin.app.shoptime/.docs/video-player-analysis-and-optimization-plan.md
+++ b/com.twin.app.shoptime/.docs/video-player-analysis-and-optimization-plan.md
@@ -0,0 +1,214 @@
+# 비디오 플레이어 분석 및 최적화 계획
+
+**작성일**: 2025-11-10
+**대상**: MediaPlayer.v2.jsx 설계
+
+---
+
+## 📊 현재 구조 분석
+
+### 1. 발견된 파일들
+
+| 파일 | 경로 | 라인 수 | 타입 |
+|------|------|---------|------|
+| VideoPlayer.js | `src/components/VideoPlayer/VideoPlayer.js` | 2,658 | Class Component |
+| MediaPlayer.jsx | `src/components/VideoPlayer/MediaPlayer.jsx` | 2,595 | Class Component |
+| MediaPanel.jsx | `src/views/MediaPanel/MediaPanel.jsx` | 415 | Function Component |
+| PlayerPanel.jsx | `src/views/PlayerPanel/PlayerPanel.jsx` | 25,146+ | (파일 읽기 실패) |
+
+### 2. 주요 문제점
+
+#### 🔴 심각한 코드 비대화
+```
+VideoPlayer.js:     2,658 라인 (클래스 컴포넌트)
+MediaPlayer.jsx:    2,595 라인 (거의 동일한 복사본)
+PlayerPanel.jsx:   25,146+ 라인
+```
+
+#### 🔴 과도한 Enact 프레임워크 의존성
+```javascript
+// 7개 이상의 Decorator 래핑
+ApiDecorator
+I18nContextDecorator
+Slottable
+FloatingLayerDecorator
+Skinnable
+SpotlightContainerDecorator
+Spottable, Touchable
+```
+
+#### 🔴 복잡한 상태 관리 (20+ 상태 변수)
+```javascript
+state = {
+  // 미디어 상태
+  currentTime, duration, paused, loading, error,
+  playbackRate, proportionLoaded, proportionPlayed,
+
+  // UI 상태
+  announce, feedbackVisible, feedbackAction,
+  mediaControlsVisible, mediaSliderVisible, miniFeedbackVisible,
+  titleVisible, infoVisible, bottomControlsRendered,
+
+  // 기타
+  sourceUnavailable, titleOffsetHeight, bottomOffsetHeight,
+  lastFocusedTarget, slider5WayPressed, thumbnailUrl
+}
+```
+
+#### 🔴 메모리 점유 과다
+
+**8개의 Job 인스턴스**:
+- `autoCloseJob` - 자동 controls 숨김
+- `hideTitleJob` - 타이틀 숨김
+- `hideFeedbackJob` - 피드백 숨김
+- `hideMiniFeedbackJob` - 미니 피드백 숨김
+- `rewindJob` - 되감기 처리
+- `announceJob` - 접근성 알림
+- `renderBottomControl` - 하단 컨트롤 렌더링
+- `slider5WayPressJob` - 슬라이더 5-way 입력
+
+**다수의 이벤트 리스너**:
+- `mousemove`, `touchmove`, `keydown`, `wheel`
+- 복잡한 Spotlight 포커스 시스템
+
+#### 🔴 불필요한 기능들 (MediaPanel에서 미사용)
+```javascript
+// PlayerOverlayQRCode (QR코드 표시)
+// VideoOverlayWithPhoneNumber (전화번호 오버레이)
+// ThemeIndicatorArrow (테마 인디케이터)
+// FeedbackTooltip, MediaTitle (주석 처리됨)
+// 복잡한 TabContainerV2 동기화
+// Redux 통합 (updateVideoPlayState)
+```
+
+---
+
+## 🔍 webOS 특정 기능 분석
+
+### 필수 기능
+
+#### 1. Spotlight 포커스 관리
+```javascript
+// 리모컨 5-way 네비게이션
+SpotlightContainerDecorator
+Spottable, Touchable
+```
+
+#### 2. Media 컴포넌트 (webOS 전용)
+```javascript
+videoComponent: window.PalmSystem ? Media : TReactPlayer
+```
+
+#### 3. playbackRate 네거티브 지원
+```javascript
+if (platform.webos) {
+  this.video.playbackRate = pbNumber; // 음수 지원 (되감기)
+} else {
+  // 브라우저: 수동 되감기 구현
+  this.beginRewind();
+}
+```
+
+### 제거 가능한 기능
+
+- FloatingLayer 시스템
+- 복잡한 announce/accessibility 시스템
+- Marquee 애니메이션
+- 다중 오버레이 시스템
+- Job 기반 타이머 → `setTimeout`으로 대체 가능
+
+---
+
+## 📐 MediaPlayer.v2.jsx 초기 설계 (수정 전)
+
+### 설계 원칙
+```
+1. 함수 컴포넌트 + React Hooks 사용
+2. 상태 최소화 (5~7개만)
+3. Enact 의존성 최소화 (Spotlight 기본만)
+4. 직접 video element 제어
+5. props 최소화 (15개 이하)
+6. 단순한 controls UI
+7. 메모리 효율성 우선
+```
+
+### 최소 상태 (6개)
+```javascript
+const [currentTime, setCurrentTime] = useState(0);
+const [duration, setDuration] = useState(0);
+const [paused, setPaused] = useState(true);
+const [loading, setLoading] = useState(true);
+const [controlsVisible, setControlsVisible] = useState(false);
+const [error, setError] = useState(null);
+```
+
+### 필수 Props (~12개)
+```javascript
+{
+  src,              // 비디오 URL
+  type,             // 비디오 타입
+  autoPlay,         // 자동 재생
+  loop,             // 반복 재생
+  disabled,         // modal 상태
+  onEnded,          // 종료 콜백
+  onError,          // 에러 콜백
+  onBackButton,     // 뒤로가기
+  thumbnailUrl,     // 썸네일
+  panelInfo,        // 패널 정보
+  spotlightId,      // spotlight ID
+  videoComponent    // Media or TReactPlayer
+}
+```
+
+### 제거할 기능들
+```
+❌ QR코드 오버레이
+❌ 전화번호 오버레이
+❌ 테마 인디케이터
+❌ 복잡한 피드백 시스템
+❌ MediaSlider (seek bar)
+❌ 자동 숨김/보임 Job 시스템
+❌ Announce/Accessibility 복잡계
+❌ FloatingLayer
+❌ Redux 통합
+❌ TabContainer 동기화
+❌ 다중 overlay 시스템
+❌ MediaTitle, infoComponents
+❌ jumpBy, fastForward, rewind
+❌ playbackRate 조정
+```
+
+---
+
+## 📈 예상 개선 효과
+
+| 항목 | 현재 | 개선 후 | 개선율 |
+|------|------|---------|--------|
+| **코드 라인** | 2,595 | ~500 | **80% 감소** |
+| **상태 변수** | 20+ | 5~7 | **65% 감소** |
+| **Props** | 70+ | ~12 | **83% 감소** |
+| **타이머/Job** | 8 | 2~3 | **70% 감소** |
+| **메모리 점유** | 높음 | 낮음 | **예상 50%+ 감소** |
+| **렌더링 속도** | 느림 | 빠름 | **예상 2~3배 향상** |
+
+---
+
+## 🚨 중요 요구사항 추가
+
+### Modal 모드 전환 기능 (필수)
+
+사용자 피드백:
+> "비디오 플레이어가 이렇게 복잡하게 된 데에는 다 이유가 있다.
+> modal=true 모드에서 화면의 일부 크기로 재생이 되다가
+> 그 화면 그대로 키워서 modal=false로 전체화면으로 비디오를 재생하는 부분이 있어야 한다."
+
+**→ 이 기능은 반드시 유지되어야 함**
+
+---
+
+## 📝 다음 단계
+
+1. Modal 전환 기능 상세 분석
+2. 필수 기능 재정의
+3. MediaPlayer.v2.jsx 재설계
+4. 구현 우선순위 결정