# Climate Risk Engine - Real-World Bond Pipeline Upgrade (Phase 9)

본 문서는 기후 리스크 엔진 내 **진성 회사채 데이터 수집 파이프라인(Phase 9)** 구축에 대한 기술적 요약 및 경과 보고서입니다. 본 아키텍처 개선을 통해 무위험 금리 벤치마크가 부도 확률 지표로 잘못 모델링되는 심각한 도메인 오류를 근본적으로 수정하고, 실제 기업에서 발행된 채권 ISIN 데이터를 통한 정밀한 금리 스프레드 시뮬레이션 기반을 마련하였습니다.

## 1. 개요 (Overview)
과거 단일 스냅샷 및 난수(Mock) 데이터에 의존하던 평가 시스템에서 탈피하여, 지정된 실제 기업의 발행 회사채 수익률(YTM)을 외부 오픈소스 채널로부터 크롤링하여 연결하는 데이터 융합 파이프라인을 신설했습니다.

## 2. 주요 개선 항목 (Key Implementation Details)

### 2.1. 시장 벤치마크(Rate)의 Credit 평가 분리
*   `SOFR`, `CD91D` 와 같은 단기 자금 및 무위험 지표들을 `firm_reference_data` 의 GICS 섹터에서 `Rate` 클래스로 강제 치환 및 하드코딩 격리 조치.
*   `market_risk_engine.py` 루프 진입 시 `asset_type == 'Rate'` 인 경우 **Merton 모델 부도거리/PD 연산 대상에서 원천 배제**하여 파이프라인 간섭 차단.

### 2.2. 오픈소스 기반 YTM 스크래퍼 신규 개발 (`src/bond_data_fetcher.py`)
*   **제약 극복**: `pykrx` 오픈소스 모듈의 채권 스크래핑 기능이 차단된 상태임을 확인. 대안으로 `requests` 와 `pandas.read_html`을 활용해 Naver Finance 채권 시장수익률 데이터를 API 인증키(Key) 없이 실시간 수집하는 무인 봇 설계 완료.
*   **타겟 지정**: 신용/무위험 등급 간 차이를 대표하기 위해 최상위 우량회사채(AA- 3년물)와 국고채(KTB 3년물 03125-2606) 수익률 수집 및 `data/live_bond_yields.json` 배포 자동화.

### 2.3. 진성 개별 채권(ISIN) 발행 정보 매핑 (`create_security_master.py`)
*   임의의 추상적 인덱스(`CORP_AA_3Y`) 대신 사용자 요청에 따라 실제 발행 이력을 기반으로 한 **고유 ISIN 증권코드**를 Security Master에 주입 및 평가.
    *   `KR600538012C`: 현대자동차 제316-1회 무보증사채 (발행)
    *   `KR600593000A`: 삼성전자 제1회 무보증사채 (발행)
    *   `KR610556011B`: KB금융지주 제2024-1회 (국민은행채)

## 3. 안정화 (Stability & Fixes)
*   **엔진 SQLite Syntax Error 픽스**: 모델 연산 중 `shocks_equity` DF가 0 row 상태에서 Pandas `to_sql()` 이 SQLite 내부 문법 오류를 일으켜 DB 적재를 실패하고 백엔드 API가 `500 Internal Server Error` 를 내뿜던 버그(`데이터 안뜬다`)를 완벽히 해결.
*   현재 uvicorn 서버는 `/api/matrix/baseline` 페이로드를 안정적으로 200 OK 서빙 중.

## 4. Next Steps
현재 로직은 개별 ISIN 기준 베이스 수익률은 잘 가져오나, Merton 모델 시뮬레이션 시 `V_base`가 Bond의 가격 자체로 들어가 평가되는 구조적 한계를 안고 있습니다 (원칙적으로 발행 기업의 Equity Value를 통해 Bond Spread가 후행 도출되어야 함). 향후 기업 Equity와 Bond 의 계층적(Cascading) 시뮬레이션 구조를 통합하는 아키텍처 개편 검토가 필요합니다.
