# 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-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` 옵션)