Variet/variet-agent

Files

CD 6490ed4be4 fix(wiki): update_page tags 누락 에러 수정 + refactor(bot): 레거시 NLU/핸들러 800줄 제거

2026-03-15 22:43:56 +09:00

4.8 KiB

Raw Blame History

Known Issues & Lessons Learned

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

포맷

각 항목은 아래 형식을 따릅니다:

### [날짜] [키워드] — 한줄 요약
- **증상**: 무엇이 잘못되었는가
- **원인**: 근본 원인
- **해결**: 올바른 해결 방법
- **주의**: 재발 방지를 위한 교훈

공통 이슈

[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로 보이는 필드도 생략 시 에러 가능. 항상 모든 필드를 명시적으로 전달