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=) 전면 금지

[2026-03-11] Belkin Zt 부호 규칙 — 전체 파이프라인 부호 반전 버그

• 증상: Zt 1998=+2.12 (IMF 위기인데 양수), 2006=-1.53 (호황인데 음수)
• 원인: Belkin 논문 원본: Z>0=호황(PD↓). 코드에서 임계값이 오름차순(AAA→D)인데 수식에 (d - √ρ·Z)로 구현하여 부호 반전. 올바른 수식은 (d + √ρ·Z)
• 해결: credit_cycle.py, vasicek.py, transition_matrices.py 3파일 모두 (d - sqrt_rho * z) → (d + sqrt_rho * z) 수정
• 주의: vasicek.py의 conditional_pd()는 Basel convention (Z↑=불황)으로 별도 체계. 조건부 전이행렬은 Belkin convention (Z↑=호황). 두 규약이 코드에 공존하므로 반드시 docstring 확인 후 사용

[2026-03-11] ECOS 거시변수 — fallback 커버리지 부족

• 증상: 기존 11개 변수만으로는 Zt 설명력 부족 (R² < 0.6)
• 원인: 한국 경제 특수성(유가의존, 수출주도, 부동산 영향 등) 미반영
• 해결: 31개 변수로 확장 (KOSPI, OIL_PRICE, USDKRW, DISHONOR_RATE, HOUSING_PRICE, BSI_MANUF 등). data/ecos_fetcher.py + data/cache/macro_ecos.csv 캐싱 구조
• 주의: fallback 데이터는 대략적 수치. 정밀 분석 시 ECOS API 실제 호출 필요 (--force 옵션)

[2026-03-11] Windows Python — 소스 코드 특수문자 SyntaxError

• 증상: 파이썬 코드 내 문자열(예: docstring)에 × (U+00D7), → (U+2192) 등 특수문자나 한글 이외의 유니코드가 포함될 때, Windows CP949 환경에서 SyntaxError: invalid character 또는 unterminated triple-quoted string literal 로 파싱 오류가 발생함.
• 원인: Windows Python 3.12 런타임이 파일 맨 앞 # -*- coding: utf-8 -*- 이나 -X utf8 런타임 플래그도 소스 구문 분석 레벨에서 완벽하게 해석해내지 못하는 Windows 인코딩 고질병 문제 발생.
• 해결: 소스 코드 내에선 (특히 docstring 등 Python 인터프리터가 읽을 영역에서는) × 대신 x 또는 by를 사용하고, → 대신 -> 로 ASCII 코드로 치환하여 작성함 (정규식 치환 등 활용). 한글 자체는 정상적으로 파싱됨.
• 주의: 모델링, 모듈 코드 작성 시 문자열이나 주석 내에 특수 유니코드 기호(×, →, —, §)를 직접 삽입하지 말고 안전한 ASCII 문자로 대체하여 코딩할 것.

[2026-03-11] ADF 단위근 검정 — autolag='AIC' 소표본 과적합

• 증상: Zt ADF 검정이 autolag='AIC'에서 p=0.40 (FAIL), autolag='BIC'에서 p=0.0000 (PASS)
• 원인: AIC는 소표본(N<50)에서 lag를 과다 선택 (N=26에서 lag=8 선택 -> 유효관측치=17 -> 검정력 상실). Hamilton (1994, Ch.17) 참조
• 해결: validation/statistical_tests.py에서 adfuller(series, autolag="AIC") -> adfuller(series, autolag="BIC"), BIC는 보수적 lag 선택으로 소표본 적합 (Schwarz 1978)
• 주의: N<50 시계열 ADF 검정에서 항상 autolag='BIC' 사용. AIC는 대표본(N>100)에서만 신뢰할 것

[2026-03-11] KAP 채권 YTM PD Floor — 하드코딩 vs 실계산 혼동

• 증상: DEFAULT_PD_FLOORS 하드코딩 값(BBB=20bp)과 KAP YTM 기반 실계산값(BBB=93bp)의 차이가 큼
• 원인: pd_floor.py에 build_complete_pd_floor_table() 함수가 존재하나 사용되지 않고, get_default_pd_floors()만 호출
• 해결: main.py와 generate_report.py 모두 build_complete_pd_floor_table() 호출로 변경. ytm_fetcher.py fallback 데이터(2025-12-31)로 오프라인에서도 작동
• 주의: PD Floor 변경 시 Zt 재추정 + AR(1) 변수 재탐색 필수. 단, 투자적격등급(AAA-A)은 0% 부도 보정이므로 Zt 전체 분포에 미치는 영향은 미미