LifetimePD/.agents/references/known-issues.md

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-10] ECOS API 통계표코드 — 대부분 404 반환

• 증상: 111Y002, 817Y002, 901Y067/A 등 다수의 통계표코드/항목코드가 "해당하는 데이터가 없습니다" 반환
• 원인: ECOS API 통계표 구조가 공식 문서와 다름. 예: GDP 성장률은 111Y002가 아닌 902Y015 (국제 비교 통계), CD금리는 817Y002가 아닌 721Y001
• 해결: StatisticItemList API로 각 통계표의 항목코드를 조회한 후, StatisticSearch로 실제 데이터 반환 확인. 검증된 전체 코드 목록은 config.yaml에 기록됨
• 주의: ECOS 통계표코드 변경 시 반드시 StatisticItemList → StatisticSearch 2단계 검증 수행. 선행지수(901Y067)는 연간 데이터 없음(월별만 존재)

[2026-03-10] Windows CP949 인코딩 — Unicode 렌더링 실패

• 증상: matplotlib에서 ✓, ✗, — (em dash) 등 Unicode 기호가 CP949에서 렌더링 실패
• 원인: Windows 콘솔/Malgun Gothic 폰트가 해당 기호를 지원하지 않음
• 해결: sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') + ASCII 대체 문자 사용 (Pass O / Fail X)
• 주의: 모든 Python 스크립트의 최상단에 UTF-8 stdout 설정 추가 필요

[2026-03-10] pandas fillna(method=) — Deprecation 오류

• 증상: fillna(method="ffill") 호출 시 FutureWarning/Error
• 원인: pandas 2.x에서 fillna(method=) 인자 deprecated
• 해결: df.ffill().bfill() 메서드 체인으로 대체
• 주의: pandas 2.x 이상 사용 시 fillna(method=) 전면 금지