# 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-08] nas_scanner docstring — Unicode escape SyntaxError
- **증상**: `from tools.nas_scanner import NasScanner` 시 `SyntaxError: (unicode error) 'unicodeescape' codec can't decode \N`
- **원인**: docstring 내 `\\NasData` 경로에서 `\N`이 Python Unicode named escape로 해석
- **해결**: docstring을 `r"""..."""` (raw string)으로 변경
- **주의**: Windows 경로(`\\`, `\N`, `\U` 등)가 포함된 docstring은 반드시 `r"""`로 작성

### [2026-03-08] title_matcher _kata_to_hira — 장음기호 깨짐
- **증상**: `フリーレン` → `ふり゜れん` (ー가 ゜로 변환)
- **원인**: 카타카나 범위 `0x30A0~0x30FF`에 기호 문자(`ー` U+30FC) 포함
- **해결**: 범위를 `0x30A1~0x30F6`으로 좁혀 실제 문자만 변환
- **주의**: 유니코드 범위 지정 시 기호/구두점 문자 포함 여부 확인 필수

### [2026-03-08] anime_pipeline — Nyaa 검색 0건 반환
- **증상**: 한자 포함 원제의 로마자 변환 결과(`葬送nofuriren`) + suffix 고정으로 Nyaa 검색 실패
- **원인**: 단일 검색 전략, suffix(ASW HEVC) 항상 부착
- **해결**: 6단계 fallback 전략 (romaji±suffix → 원제±suffix → 한글±suffix)
- **주의**: 외부 API 검색 시 반드시 다중 전략 + suffix 토글 구현

### [2026-03-15] _extract_episode — v2/S01E10 패턴 미인식 → 중복 다운로드
- **증상**: NAS에 ep9, 10이 있는데 재다운로드. ASW `- 10v2` 릴리스 에피소드 추출 실패
- **원인**: 정규식 `[-–]\s*(\d{1,4})(?:\s|$|\.|\[)`이 v2 접미사 미처리. `S01E10`은 하이픈 패턴이 `S01`의 `01`을 먼저 매칭
- **해결**: (1) SxxExx 패턴을 최우선 체크, (2) `(?:v\d)?` 추가로 version suffix 허용, (3) `\(` 추가로 SubsPlease 포맷 지원
- **주의**: 에피소드 추출 정규식 수정 시 반드시 v2/v3 릴리스 + SxxExx + 한글(N화) + false positive(29-sai) 테스트 포함

### [2026-03-15] _add_torrents — 릴리스 그룹 불일치 다운로드
- **증상**: NAS에 `[ASW] HEVC` 파일(~300MB)만 있는데 `CR WEB-DL DUAL`(1.4GB) 릴리스를 다운
- **원인**: 스코어링이 ASW에 +100을 주지만, ASW 릴리스가 없는 에피소드에서 아무 릴리스나 선택
- **해결**: NAS 기존 파일의 릴리스 그룹(`[ASW]`)을 감지하여 같은 그룹만 허용. 매칭 없으면 스킵
- **주의**: Nyaa 토렌트 제목에 영어+일본어 제목이 모두 포함되어 키워드 필터만으로는 불충분

### [2026-03-15] _download_subtitles — 기존 자막 덮어쓰기 위험
- **증상**: 이미 수동으로 배치한 자막 파일을 Anissia 자막으로 덮어쓸 수 있음
- **원인**: 기존 자막 파일 존재 여부를 확인하지 않고 전 에피소드 자막 다운로드 시도
- **해결**: NAS 폴더의 기존 자막 파일을 에피소드별로 스캔, 이미 있으면 스킵
- **주의**: 자막 처리 시 사용자 수동 입력 파일의 보존을 항상 고려

### [2026-03-15] Wiki.js GraphQL — update mutation에 tags 누락 시 에러
- **증상**: `update_page()` 호출 시 `Cannot read properties of undefined` 백엔드 에러
- **원인**: Wiki.js `update` mutation이 `tags` 파라미터 생략 시 내부적으로 undefined 처리하여 crash
- **해결**: `update_page()`에서 `tags`가 None이면 `get_page()`로 기존 tags를 먼저 조회하여 항상 전달
- **주의**: Wiki.js GraphQL mutation은 optional로 보이는 필드도 생략 시 에러 가능. 항상 모든 필드를 명시적으로 전달