# PLAN.md — abcvideo 구현 계획

> 이 파일은 전체 구현 계획과 각 단계별 세부 태스크를 정의합니다.
> 에이전트는 작업 시작 전 반드시 이 파일을 읽고, 자신이 담당할 단계를 확인합니다.

---

## 단계 1: 프로젝트 구조 세팅

### 목표
모노레포 구조 생성, TypeScript/빌드 설정, 개발 환경 구축

### 세부 태스크
- [ ] 루트 `package.json` (npm workspaces: client, server, shared)
- [ ] `client/` — Vite + React 18 + TypeScript 초기화
- [ ] `server/` — TypeScript + ts-node/tsx 설정
- [ ] `shared/` — 공유 타입 패키지 설정
- [ ] Tailwind CSS 설치 및 설정 (client)
- [ ] ESLint + Prettier 설정 (루트)
- [ ] `tsconfig.json` — 루트/client/server/shared 각각 설정 (경로 별칭 포함)
- [ ] `storage/` 디렉토리 구조 생성 + `.gitignore` 설정
- [ ] `server/.env.example` 작성
- [ ] 개발 서버 동시 실행 스크립트 (`concurrently` 또는 npm scripts)
- [ ] 빈 앱 기동 확인 (client dev + server dev 동시 실행)

### 산출물 (완료 기준)
- `npm install` 성공
- `npm run dev`로 client(5173) + server(3001) 동시 기동
- TypeScript 컴파일 에러 없음
- 빈 React 앱이 브라우저에 표시됨

### 다음 단계 의존성
- 단계 2, 3 모두 이 단계 완료 후 시작 가능

---

## 단계 2: 백엔드 서버

### 목표
Express 서버 + Range Request 스트리밍 + FFmpeg spawn 래퍼 + tus 업로드 + HLS 변환 + SSE 진행률

### 세부 태스크

#### 2-1. 서버 기본 골격
- [ ] Express 앱 생성 (`server/src/app.ts`)
- [ ] CORS 미들웨어 설정 (개발: localhost:5173 허용)
- [ ] 보안 미들웨어: Path traversal 방어 (`middleware/security.ts`)
- [ ] 에러 핸들링 미들웨어
- [ ] 환경변수 로드 (dotenv + `server/.env`)
- [ ] `storage/` 하위 디렉토리 자동 생성 로직

#### 2-2. Range Request 스트리밍
- [ ] `routes/stream.ts` — GET /api/stream/:videoId
- [ ] `services/streaming.ts` — Range 파싱, createReadStream, 206 응답
- [ ] Accept-Ranges 헤더, Content-Range 헤더 정확한 구현
- [ ] highWaterMark 1MB, 청크 크기 10MB 제한
- [ ] 테스트: curl로 Range Request 동작 확인

#### 2-3. FFmpeg spawn 래퍼
- [ ] `services/ffmpeg.ts` — runFFmpeg(), runFFprobe() 함수
- [ ] FFmpeg 설치 확인 로직 (서버 시작 시)
- [ ] stderr 진행률 파싱 (`time=HH:MM:SS.ms` 패턴)
- [ ] 코덱 감지: FFprobe로 H.264 여부 확인 → `-c copy` vs 트랜스코딩 분기
- [ ] 프레임 추출: `-accurate_seek -ss {time} -i {file} -frames:v 1`

#### 2-4. HLS 변환
- [ ] `routes/hls.ts` — POST /api/hls/:videoId/convert, GET 플레이리스트/세그먼트
- [ ] 변환 작업 관리 (Map 기반 인메모리 상태: idle/converting/done/error)
- [ ] H.264 → `-c copy` (빠른 리먹스), 비-H.264 → 트랜스코딩
- [ ] 세그먼트 6초, 키프레임 2초 간격
- [ ] SSE 진행률 엔드포인트: GET /api/hls/:videoId/progress

#### 2-5. tus 업로드
- [ ] `@tus/server` + `@tus/file-store` 설정
- [ ] `routes/upload.ts` — /api/upload 경로에 tus 서버 마운트
- [ ] 업로드 완료 훅: `onUploadFinish`에서 파일 이동 + FFprobe 메타데이터 추출
- [ ] 업로드 크기 제한: MAX_UPLOAD_SIZE (기본 20GB)
- [ ] MIME 타입 + FFprobe 실제 코덱 검증

#### 2-6. 메타데이터 & 영상 관리
- [ ] `routes/meta.ts` — GET /api/meta/:videoId (FFprobe 기반)
- [ ] GET /api/videos — 업로드된 영상 목록
- [ ] DELETE /api/videos/:videoId — 원본+HLS+프레임+썸네일+DB 일괄 삭제

#### 2-7. SQLite + 주석 API
- [ ] `db/schema.sql` — annotations 테이블 스키마
- [ ] better-sqlite3 초기화 (`services/storage.ts`)
- [ ] `routes/annotations.ts` — CRUD + 내보내기 (VTT, SRT, JSON, CSV)

#### 2-8. 파일 정리
- [ ] 서버 시작 시 24시간 이상 된 임시 파일 정리
- [ ] 주기적 정리 (setInterval, 1시간마다)
- [ ] 디스크 잔여 공간 체크 (check-disk-space, 10GB 미만 시 로그 경고)

### 산출물 (완료 기준)
- 서버 기동 성공 (FFmpeg 감지 로그 출력)
- curl로 Range Request 스트리밍 동작 확인
- curl로 영상 업로드 (tus) 성공
- HLS 변환 시작/진행률/완료 확인
- 주석 CRUD API 동작 확인

### 다음 단계 의존성
- 단계 3 (기본 플레이어)은 최소 2-1, 2-2 완료 시 시작 가능
- 단계 4 (프레임 추출)은 2-3 완료 필요
- 단계 6 (텍스트 오버레이)은 2-7 완료 필요

---

## 단계 3: 기본 플레이어

### 목표
Video.js + 이중 경로 재생 (로컬 File API + 서버 Range Request/HLS) + 기본 UI

### 세부 태스크

#### 3-1. Video.js 통합
- [ ] Video.js 8.23.x + 타입 정의 설치
- [ ] `components/player/VideoPlayer.tsx` — ref + useEffect 패턴
- [ ] `hooks/useVideoPlayer.ts` — 초기화/제어/이벤트 추상화
- [ ] Video.js 옵션: fluid, responsive, playbackRates 설정
- [ ] 전체화면: 컨테이너 div 기준 fullscreen (오버레이 유지)

#### 3-2. 서버 파일 재생
- [ ] 서버 영상 목록 조회 UI
- [ ] Range Request URL로 즉시 재생
- [ ] HLS 변환 트리거 + SSE 진행률 표시
- [ ] HLS 준비 완료 시 hls.js로 소스 전환

#### 3-3. 로컬 파일 재생
- [ ] 파일 드래그앤드롭 / 파일 선택 UI
- [ ] `URL.createObjectURL()` → Video.js src 설정
- [ ] 재생 종료/파일 변경 시 `URL.revokeObjectURL()` 호출

#### 3-4. hls.js 설정
- [ ] hls.js 1.6.x 설치 및 Video.js VHS와의 역할 분담 결정
- [ ] backBufferLength: 30, maxBufferSize: 60MB 등 필수 설정 적용
- [ ] 에러 복구 로직 (QuotaExceededError 대응)

#### 3-5. 기본 UI 레이아웃
- [ ] 메인 레이아웃: 플레이어 영역 + 사이드 패널 (영상 목록/주석)
- [ ] 반응형 기본 구조 (Tailwind)
- [ ] Zustand 스토어 기본 구조 (현재 영상, 재생 상태, 소스 타입)

### 산출물 (완료 기준)
- 로컬 mp4 파일 드래그앤드롭 → 즉시 재생
- 서버 영상 선택 → Range Request로 재생
- HLS 변환 완료 후 HLS로 전환 재생
- 전체화면 동작 확인

### 다음 단계 의존성
- 단계 4, 5, 6 모두 이 단계 완료 후 시작 가능

---

## 단계 4: 프레임 추출

### 목표
Canvas 즉시 미리보기 + 서버 FFmpeg API를 통한 정확한 프레임 추출

### 세부 태스크
- [ ] `utils/frameCapture.ts` — Canvas 기반 현재 프레임 캡처 (로컬 파일용 즉시 미리보기)
- [ ] 단일 Canvas 재사용 패턴 적용
- [ ] `routes/frame.ts` 연동 — 서버 FFmpeg 프레임 추출 요청
- [ ] 프레임 추출 결과 표시 UI (모달 또는 패널)
- [ ] 프레임 이미지 다운로드 기능
- [ ] Shift+S 단축키 → 현재 프레임 캡처

### 산출물 (완료 기준)
- 일시정지 상태에서 Shift+S → 프레임 이미지 표시 + 다운로드
- 서버 영상: FFmpeg 정확 추출
- 로컬 파일: Canvas 즉시 캡처

### 다음 단계 의존성
- 단계 5에서 FPS 감지 로직과 연계

---

## 단계 5: 단위 이동

### 목표
프레임/초/장면 단위 seek + requestVideoFrameCallback FPS 감지 + 키보드 단축키

### 세부 태스크
- [ ] `hooks/useFrameStep.ts` — requestVideoFrameCallback으로 FPS 동적 감지 (fallback 30fps)
- [ ] 프레임 이동: `,`(이전) / `.`(다음) — 일시정지 상태에서만
- [ ] 초 이동: ←/→(5초), J/L(10초)
- [ ] 장면 이동: `[`/`]` — 키프레임 기반 또는 일정 간격(30초) 이동
- [ ] 10% 단위 탐색: 0~9 키
- [ ] 재생 속도: +/- 키 (0.25x ~ 4x)
- [ ] 전체화면 토글: F 키
- [ ] 음소거 토글: M 키
- [ ] 키보드 이벤트: 플레이어 포커스 시에만 활성, 텍스트 입력 시 비활성
- [ ] 현재 프레임 번호 / 타임코드 표시 UI

### 산출물 (완료 기준)
- 모든 키보드 단축키 동작 확인
- 프레임 단위 이동 시 타임코드 정확 갱신
- FPS 감지 로그 출력

### 다음 단계 의존성
- 없음 (단계 6과 병렬 진행 가능)

---

## 단계 6: 텍스트 오버레이

### 목표
자막형(WebVTT track) + 메모형(interact.js DOM 오버레이) + 내보내기(subsrt)

### 세부 태스크

#### 6-1. 자막형
- [ ] WebVTT `<track kind="subtitles">` 연동
- [ ] 자막 추가/편집 UI (시작 시간, 종료 시간, 텍스트)
- [ ] 서버 주석 API 연동 (type: "subtitle")
- [ ] VTT/SRT 내보내기 (subsrt 라이브러리)

#### 6-2. 메모형
- [ ] `components/overlay/MemoOverlay.tsx` — DOM 오버레이 컨테이너
- [ ] interact.js 드래그/리사이즈 연동
- [ ] 좌표 정규화: px → % 변환/저장
- [ ] 메모 추가 UI: Shift+M → 현재 시점에 메모 생성
- [ ] 메모 편집/삭제 UI
- [ ] 표시 로직: requestAnimationFrame 루프 + 이진 탐색
- [ ] 서버 주석 API 연동 (type: "memo")
- [ ] JSON/CSV 내보내기

#### 6-3. 주석 관리 패널
- [ ] `hooks/useAnnotations.ts` — 주석 CRUD + 서버 동기화
- [ ] 사이드 패널: 시간순 주석 목록, 클릭 시 해당 시점으로 이동
- [ ] 타임라인 위 주석 마커 표시

### 산출물 (완료 기준)
- 자막 추가 → 영상 재생 시 하단에 표시
- 메모 추가 → 드래그로 위치 조정 가능
- VTT/SRT/JSON/CSV 내보내기 동작 확인

### 다음 단계 의존성
- 없음 (단계 5와 병렬 진행 가능)

---

## 단계 7: UI/UX 통합

### 목표
전체 기능 통합, UI 다듬기, 썸네일 미리보기, 디스크 관리

### 세부 태스크
- [ ] 전체 레이아웃 정리 (플레이어 + 컨트롤 + 사이드패널 통합)
- [ ] 탐색바 썸네일 미리보기 (서버 FFmpeg 스프라이트 + VTT)
- [ ] HLS 변환 진행률 UI (프로그레스 바 + 상태 텍스트)
- [ ] 영상 목록 UI 개선 (업로드 상태, HLS 변환 상태, 용량)
- [ ] 디스크 사용량 표시 + 경고
- [ ] 로딩/에러 상태 처리 (스켈레톤, 에러 바운더리)
- [ ] 키보드 단축키 도움말 오버레이 (? 키)
- [ ] 전체 기능 통합 테스트
- [ ] README.md 작성 (설치, 실행, 사용법)

### 산출물 (완료 기준)
- 전체 기능이 하나의 UI에서 동작
- 서버 파일 + 로컬 파일 모두 테스트 완료
- README.md로 프로젝트 세팅/실행 가능

### 다음 단계 의존성
- 모든 이전 단계 완료 필요

---

## 단계 의존성 다이어그램

```
단계 1 (프로젝트 구조)
  ├── 단계 2 (백엔드 서버)
  │     ├── 단계 4 (프레임 추출) ──┐
  │     └── 단계 6-자막 (주석 API) │
  └── 단계 3 (기본 플레이어)       │
        ├── 단계 4 (프레임 추출) ──┤
        ├── 단계 5 (단위 이동) ────┤ → 단계 7 (UI/UX 통합)
        └── 단계 6 (텍스트 오버레이)┘

※ 단계 5와 6은 병렬 진행 가능
```
