commit d38b842e8dec1df7f5842d73cd849b65572c9696 Author: 한성일 Date: Thu Jul 9 14:32:51 2026 +0900 GhiVideo 소스 복제 — v4 작업 시작 기준 기존 GhiVideo 저장소 HEAD의 트래킹 소스 362개 파일을 복제. (node_modules·storage·빌드 산출물·대용량 미디어는 .gitignore 규칙대로 제외) Co-Authored-By: Claude Fable 5 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..2e3727a --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,14 @@ +{ + "permissions": { + "allow": [ + "Bash(cd ~/projects/gitea/b23042/import_data/v2.0/ 2>/dev/null && ls -la && echo \"===\" && ls -la \"하행\\)회덕-대전조차장 데이터\\(v2.0\\)\" 2>/dev/null | head -50)", + "Read(//home/hanmac/projects/gitea/b23042/import_data/v2.0/**)", + "Bash(ls node_modules/proj4)", + "Bash(cp /tmp/chk.mjs ./chk.mjs)", + "Bash(node ./chk.mjs)", + "Bash(rm -f ./chk.mjs)", + "Bash(ls -la \"/mnt/c/Users/User/Pictures/Screenshots/\" 2>/dev/null | tail -10 || echo \"no /mnt/c path\")", + "Read(//mnt/c/Users/User/Pictures/Screenshots/**)" + ] + } +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fed1682 --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# 의존성 +node_modules/ + +# 빌드 산출물 +client/dist/ +server/dist/ +shared/dist/ +dist/ +*.tsbuildinfo + +# 파이썬 빌드 산출물 (exe/pkg/pyz 등) +pythonsource/build/ +pythonsource/dist/ +__pycache__/ +*.pyc + +# 런타임 저장소 (영상/HLS/프레임/썸네일/DB) +storage/ + +# 대용량 미디어/바이너리 +*.mp4 +*.MP4 +*.avi +*.mov +*.mkv +*.exe + +# 로그/환경 +*.log +.env +.env.* +npm-debug.log* + +# OS/에디터 +.DS_Store +Thumbs.db diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100755 index 0000000..20f2e0e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,616 @@ +# CLAUDE.md — abcvideo 프로젝트 + +이 파일은 Claude Code가 abcvideo 프로젝트에서 작업할 때 참조하는 가이드입니다. + +--- + +## 응답/소통 규칙 (항상 적용) + +- **모든 답변은 한글로 작성한다.** (코드·로그·식별자 등 원문 유지가 필요한 부분은 예외) +- 보고는 결론 → 근거 → 다음 행동 순으로 간결하게. + +--- + +## 작업 완료 시 필수 — 히스토리 기록 + +작업(대화 세션)이 끝날 때 반드시 아래 형식으로 히스토리 파일을 작성한다. + +``` +파일 경로: docs/history/YYYY-MM-DD_HHMM_{작업명}.md +``` + +필수 항목 (누락 시 Stop 훅이 응답을 차단함): + +```markdown +**소요 시간**: X분 +**Context 사용량**: input Xk / output Xk tokens +``` + +- 날짜는 오늘 날짜(YYYY-MM-DD), 시간은 작업 완료 시각 24시간제(HHMM), 작업명은 작업 내용을 한글 또는 영문으로 간략히 +- 같은 날 여러 작업이면 각각 별도 파일 (예: `2026-04-01_1430_StationOverlay-분석.md`) +- 소요 시간: 대화 시작부터 작업 완료까지의 실제 경과 시간 +- Context 사용량: 이 대화의 토큰 사용량 (모를 경우 추정값 기재) + +--- + +## 에이전트 협업 규칙 + +### 필수 파일 + +| 파일 | 용도 | 누가 관리 | +|------|------|----------| +| `CLAUDE.md` | 프로젝트 가이드 (아키텍처, 규칙, 기술 스택) | 사용자/아키텍트 | +| `PLAN.md` | 전체 구현 계획 + 각 단계별 세부 태스크 | 계획 수립 시 작성, 에이전트가 필요 시 업데이트 | +| `PROGRESS.md` | 각 단계의 진행 상태 + 완료/미완료/이슈 기록 | 작업하는 에이전트가 실시간 업데이트 | + +### 에이전트 작업 시작 프로토콜 + +모든 에이전트는 작업 시작 시 반드시 아래 순서를 따른다: + +``` +1. CLAUDE.md 읽기 → 프로젝트 규칙/아키텍처 파악 +2. PLAN.md 읽기 → 전체 계획에서 자신이 담당할 단계 확인 +3. PROGRESS.md 읽기 → 이전 단계 완료 여부, 현재 상태, 알려진 이슈 확인 +4. 작업 시작 전 PROGRESS.md에 자신의 단계를 "🔄 진행 중"으로 업데이트 +5. 작업 완료 후 PROGRESS.md에 결과 기록 (완료 항목, 남은 이슈, 다음 단계 참고사항) +``` + +### PLAN.md 구조 + +```markdown +# PLAN.md +## 단계 N: 단계 이름 +### 목표 +### 세부 태스크 +- [ ] 태스크 1 +- [ ] 태스크 2 +### 산출물 (완료 기준) +### 다음 단계 의존성 +``` + +- 각 단계는 독립적으로 실행 가능한 단위로 분할 +- 태스크는 체크박스(`- [ ]` / `- [x]`)로 관리 +- 완료 기준(산출물)이 명확해야 다음 에이전트가 판단 가능 + +### PROGRESS.md 구조 + +```markdown +# PROGRESS.md +## 현재 상태 요약 +- 마지막 완료 단계: N +- 현재 진행 단계: N+1 +- 블로커: (있으면 기록) + +## 단계별 진행 기록 +### 단계 N: 단계 이름 +- 상태: ✅ 완료 | 🔄 진행 중 | ⏳ 대기 | ❌ 실패 +- 완료일: YYYY-MM-DD +- 완료 항목: + - 항목 1 + - 항목 2 +- 미완료/이슈: + - 이슈 설명 +- 다음 단계 참고: + - 후속 에이전트가 알아야 할 사항 +``` + +- 에이전트는 작업 중 **의미 있는 마일스톤마다** PROGRESS.md를 업데이트 +- 실패 시 원인과 시도한 방법을 기록하여 다음 에이전트가 같은 실수를 반복하지 않도록 함 +- 이전 에이전트가 남긴 "다음 단계 참고"를 반드시 확인 후 작업 시작 + +### 에이전트 간 인계 규칙 + +1. **이전 단계 산출물 검증**: 코드가 빌드/실행 가능한 상태인지 확인 후 작업 시작 +2. **기존 코드 존중**: 이전 에이전트가 작성한 코드를 이유 없이 대폭 변경하지 않음 +3. **충돌 방지**: 같은 파일을 동시에 수정하는 병렬 에이전트 실행 금지 +4. **이슈 에스컬레이션**: 블로커 발견 시 PROGRESS.md에 기록하고 사용자에게 보고 + +--- + +## 프로젝트 개요 + +웹 브라우저(PC)에서 **2GB 이상의 대용량 동영상**을 안정적으로 재생하는 특화 기능 탑재 플레이어. +단순 재생을 넘어 **프레임 추출, 단위 이동, 텍스트 오버레이** 등 영상 분석/편집 보조 도구로 기능. + +### 핵심 요구사항 + +1. 2GB 이상 동영상 안정 재생 (서버 파일 + 로컬 파일 모두) +2. 프레임 단위 추출 (정확도 우선) +3. 입력 단위 기준 앞뒤 이동 (프레임 / 초 / 장면) +4. 영상 위 텍스트 입력 (자막형 + 메모형 병행 지원) +5. 확장 가능한 플러그인 아키텍처 + +### 설계 결정 (2026-03-24 확정) + +| 항목 | 결정 | 비고 | +|------|------|------| +| 사용자 모델 | **단일 사용자 도구** | 인증/세션/큐 불필요, 구현 단순화 | +| 로컬 파일 | **업로드 없이 직접 재생** | File API → `URL.createObjectURL()` | +| 프레임 정확도 | **표준 수준** | CFR: `1/fps` 산술, VFR: best-effort | +| HLS 변환 전 재생 | **원본 즉시 재생** | Range Request로 바로 재생, HLS는 백그라운드 변환 | +| 브라우저 지원 | **PC 웹 우선** | Chrome/Firefox/Edge, iOS Safari 무시 | + +--- + +## 아키텍처 결정 (ADR) + +### 재생 이중 경로 + +``` +서버 파일: GET /api/stream/:videoId (Range Request) → 즉시 재생 + POST /api/hls/:videoId/convert → 백그라운드 HLS 변환 + HLS 준비 완료 시 → hls.js로 전환 (seek 안정성 향상) + +로컬 파일: File API → URL.createObjectURL() →