From 43694ebd302af6a957c087db793472fd04624f4e Mon Sep 17 00:00:00 2001 From: Variet Main Worker Date: Wed, 25 Mar 2026 13:03:35 +0000 Subject: [PATCH] Update "Known-Issues.-" --- Known-Issues.-.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 Known-Issues.-.md diff --git a/Known-Issues.-.md b/Known-Issues.-.md new file mode 100644 index 0000000..3034db4 --- /dev/null +++ b/Known-Issues.-.md @@ -0,0 +1,75 @@ +# Known Issues & Lessons Learned + +> **이 파일은 SSOT(Single Source of Truth)입니다.** +> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요. +> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다. + +--- + +## 포맷 + +각 항목은 아래 형식을 따릅니다: + +```markdown +### [날짜] [키워드] — 한줄 요약 +- **증상**: 무엇이 잘못되었는가 +- **원인**: 근본 원인 +- **해결**: 올바른 해결 방법 +- **주의**: 재발 방지를 위한 교훈 +``` + +--- + +## 공통 이슈 + +### [2026-03-08] PowerShell curl — Invoke-WebRequest 충돌 +- **증상**: `curl` 명령이 예상과 다른 응답 형식을 반환 +- **원인**: PowerShell에서 `curl`은 `Invoke-WebRequest`의 별칭 +- **해결**: **`curl.exe`**를 명시적으로 사용 +- **주의**: HTTP 관련 모든 명령에서 `curl.exe` 사용 필수 + +### [2026-03-08] PowerShell npm — 실행 정책 오류 +- **증상**: `npm run` 명령이 `실행 정책` 관련 오류로 실패 +- **원인**: PowerShell 스크립트 실행 정책이 제한적으로 설정됨 +- **해결**: `cmd /c npm run dev` 형식으로 cmd를 통해 실행 +- **주의**: npm 관련 명령은 항상 `cmd /c` 접두어 사용 권장 + +--- + +## 프로젝트별 이슈 + +### [2026-03-24] 히스토그램 비교 — Tab 프레임 구분 불가 +- **증상**: 서로 다른 Tab 페이지가 "동일"로 판정되어 프레임 수가 과소 추출 +- **원인**: 히스토그램 상관관계는 밝기 분포만 비교 — Tab 용지 배경이 같으면 다른 내용도 동일로 판정 +- **해결**: MSE 픽셀 비교로 전환 (320px 리사이즈, factor 8) +- **주의**: MSE scaling factor는 영상 타입에 따라 다르게 동작할 수 있음 + +### [2026-03-24] split 감지 — 밝은 배경 오분류 +- **증상**: 밝은 배경 기타 연주 영상(空奏列車)이 split으로 오분류 +- **원인**: 흰 셔츠/밝은 배경이 상단 밝기 조건 통과, 기타줄이 _has_tab_lines 통과 +- **해결**: split 검증 강화 (top>180, bottom<100, diff>80, 4+ lines) + overlay 우선 검사 +- **주의**: 패턴 감지 순서는 반드시 overlay → split → scroll 유지 + +### [2026-03-24] overlay 크롭 크기 불일치 +- **증상**: overlay 프레임 비교 시 모든 프레임이 "다르다"로 판정 (1000+개 추출) +- **원인**: _detect_tab_overlay가 프레임마다 다른 크기의 바운딩박스 반환 (69~360px) +- **해결**: 320×120 흰색 캔버스에 정규화 후 비교 + 슬라이딩 윈도우(5프레임) +- **주의**: overlay 프레임 수 최적화는 아직 진행 중 (추가 튜닝 필요) + +### [2026-03-25] pHash 16×16 — Tab 프레임 과도합병 +- **증상**: 서로 다른 Tab 페이지가 pHash 클러스터링에서 동일 그룹으로 합병 (20→9 프레임) +- **원인**: 16×16 dHash(256비트)는 Tab 구조(6선 + 숫자)를 구분하기엔 해상도 부족. 모든 Tab이 유사한 hash 생성 +- **해결**: dHash 32×32(1024비트)로 확대 + max_hamming 50→20 조정 +- **주의**: hash_size와 max_hamming은 항상 쌍으로 조정해야 함 (비트수 대비 비율) + +### [2026-03-25] 1080p 프레임 — 메모리 부족/프로세스 행 +- **증상**: 1920×1080 프레임 500+개 로딩 시 프로세스 무한 대기 (3.5GB+ RAM) +- **원인**: extract_frames가 모든 프레임을 list에 보관, 1080p는 프레임당 ~6MB +- **해결**: MAX_FRAME_WIDTH=1280 캡 + gc.collect() 추가. 4K→1280px 다운스케일 +- **주의**: 영상 3개 순차 처리 시 GC 없으면 누적 메모리로 swap thrashing 발생 + +### [2026-03-25] yt-dlp 다운로드 — 360p 폴백 +- **증상**: `bestvideo[height>=720]` 포맷으로 요청했으나 640×360 파일 다운로드 +- **원인**: format string의 `/best` 폴백이 720p 없을 때 360p 선택. 또는 mp4 전용 필터가 해상도 제한 +- **해결**: 명시적 1080p 우선 + 720p 폴백 체인 분리 (`bestvideo[height>=1080]/.../best[height>=720]/best`) +- **주의**: 캐시된 파일이 있으면 재다운로드 안 함 — 해상도 변경 시 기존 파일 삭제 필요 \ No newline at end of file