feat(phase9): add real corporate bond pipeline and fix rate mapping

docs/Wiki_Summary_Phase9.md

@@ -0,0 +1,29 @@
+# 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) 시뮬레이션 구조를 통합하는 아키텍처 개편 검토가 필요합니다.

docs/benchmark_test_report.md

@@ -0,0 +1,37 @@
+# ISDA Phase 4 기후 시나리오 벤치마크 (Plausibility) 검증 리포트 및 고객 가이드
+
+본 문서는 `Market_Risk_Engine` 파이프라인에서 생성된 한국 자본시장(주식/채권/금리)의 쇼크 텐서 결과물에 대한 정합성 평가 모델 및 재검증 가이드를 설명합니다.
+
+## 1. 테스트 목적 및 요건
+사용자(고객)가 직접 스크립트(`src/benchmark_test.py`)를 가동하거나 타 검증 시스템에서 데이터를 호출할 때, "어떤 데이터를 기준으로 어떻게 계산이 구현되었는가"를 완벽히 파악하여 결과물의 타당성(Plausibility)을 직관적으로 평가하기 위해 작성되었습니다.
+
+## 2. 검증된 데이터 파라미터 상세 항목
+
+### 가. 수익률 곡선 이동 (IR Parallel Shift) 검증
+- **추적 테이블**: `shocks_ir` (또는 `data/exports/shocks_ir.csv`)
+- **계산식 검증 방법**: `shift_bps` 열이 모든 만기(Tenor) 포인트에 대해 동일한 증감폭(단일 상수)을 지니고 있는지 검증합니다.
+- **실제 산출 예시**: 'Sudden Wake-up Call(SWUC)' 시나리오의 경우, 한국의 단기 정책 금리 상승폭 분분인 **+45 bps** 가 1개월물부터 10년물 국채에 일정한 폭으로 가산(+45bps shift)되었음이 성공적으로 확증되었습니다.
+
+### 나. 주가 지수 충격 (Equity Leverage) 검증
+- **추적 테이블**: `shocks_equity` (또는 `data/exports/shocks_equity.csv`)
+- **계산식 검증 방법**: $\Delta V$ (기업 총 자산 충격 = GDP충격 * KSIC 민감도 - CO2충격 * KSIC 민감도) 에 `Leverage Factor` (배수, 부채 비율 기인성) 를 곱한 값이 `equity_shock_pct` 로 수렴하는지 확인합니다.
+- **실현된 인덱스 쇼크 테스트**: 
+  - KOSPI 200 Index의 경우 Base 대비 **-2.8%**대 하락이 포착되었으나, 탄소 다배출 고위험 팩터로 묶인 삼성전자(`005930.KS`) 등 단일 공장 기업 팩터는 **-17.1%**에 가까운 압도적 쇼크(Heavy Shock)로 유의미하게 벌어짐을 확증했습니다. ISDA 의도(브라운 섹터 처벌)가 정확하게 동작합니다.
+
+### 다. 부도율 대비 크레딧 점프 (Merton Spreands Expansion) 검증
+- **추적 테이블**: `shocks_credit` (또는 `data/exports/shocks_credit.csv`)
+- **계산식 검증 방법**: 기초 등급 (Rating) 에 해당하는 베이스 마진에 대해 익스포넨셜 마진 $e^{(-\Delta V \times 0.5)}$가 적용되어 `jump_bps` 열이 양수(확장)로 뛰었는지 확인합니다.
+- **테스트 결과**: 단기 충격 구간 내에서 2.62 bps ~ 2.90 bps 수준의 미세한 회사채 금리 확장이 기록되었습니다 (스프레드 증가 통과).
+
+## 3. 사용자(고객) 교차 테스트 방식
+고객님께서 직접 테스트할 때는 다음의 명령어를 VSCode 터미널이나 파워셸에서 입력해 주십시오.
+
+```powershell
+# 1. 데이터 Export 확인 (CSV로 산출물 추출)
+C:\ProgramData\miniforge3\envs\climate\python.exe src\data_exporter.py
+
+# 2. ISDA 벤치마크 플로저빌리티 통과 검증 (Assertion 방식)
+C:\ProgramData\miniforge3\envs\climate\python.exe src\benchmark_test.py
+```
+
+만약 타 `Repricing` 모듈에서 위 변수들을 호출하여 파생상품 가치를 다시 계산하고자 한다면, 폴더 내에 생성된 `data/exports/shocks_*.csv` 파일을 로드하여 `year='2026'` 및 `scenario='Sudden Wake-up Call'` 등의 필터링을 걸면 곧바로 프라이싱 인풋으로 이용할 수 있습니다.

docs/phase1_explanation.md

@@ -0,0 +1,33 @@
+# Phase 1: 시나리오 데이터 입수 및 KSIC 매핑 구현 설명서
+
+본 문서는 NGFS 거시경제 기후 시나리오의 입수 과정과 한국 시장에 맞는 KSIC(한국표준산업분류) 기반의 탄소 민감도(Carbon Beta) 스케일러 매핑 로직 구축 과정을 정리한 설명서입니다.
+
+## 1. NGFS 시나리오 데이터 입수 아키텍처
+NGFS(네트워크 오브 센트럴 뱅크스 앤 슈퍼바이저스 포 그리닝 더 파이낸셜 시스템) 시나리오 데이터는 오스트리아 IIASA(국제응용시스템분석연구소) 데이터 익스플로러를 통해 관리되며 전 세계 누구나 접근 권한 없이 public으로 사용 가능합니다.
+본 프로젝트는 데이터 처리 파이프라인 자동화를 위해 Python IAMC 통합 패키지인 `pyam-iamc` 모듈을 활용하여 API 기반 데이터 획득을 구축했습니다. 
+
+- **접근 권한(Auth)**: 기억하신 바와 같이 NGFS 공개 데이터베이스 특성상 별도의 사용자 인증/계정 없이 Python 환경에서 바로 다운로드 및 조회가 가능합니다.
+- **필수 추출 변수**:
+  - `Emissions|CO2|Price` : 톤당 탄소세 및 배출 비용 경로 (전환 리스크 충격 크기)
+  - `Policy Rate|Short-term` / `Interest Rate`: 단기 금리 경로
+  - `GDP|MER`: 실제 경제성장률 둔화폭 산정용 거시 지표
+- **장애 대응 프록시(Fallback Proxy)**: 의존성 모듈의 인터페이스 업데이트나 IIASA 서버 일시 점검 시 파이프라인이 멈추는 것을 방지하기 위해, ISDA Phase 4의 `Sudden Wake-Up Call`과 `Disasters and Policy Stagnation` 핵심 배수 스케일을 반영한 한국 구조적 가상 데이터 셋을 연산하여 폴백으로 자동 로드하도록 이중화해 두었습니다.
+
+## 2. KSIC (한국표준산업분류) 대응 탄소 민감도 (Carbon Beta) 설계
+국내 채권 부도율 증분 및 주가 배당할인모형(DDM) 하락률에 적용되어야 하는 가장 중요한 시장 리스크 충격 스케일러이자 본 엔진의 핵심 팩터입니다.
+국내 기업의 평가/공시는 주로 KSIC 체계로 묶여 관리되므로 이를 통해 글로벌 NGFS 데이터를 국내 파라미터로 다운스케일링합니다.
+
+| KSIC 분류 | 산업군 명칭 | Carbon Beta 설정 기조 | 적용 논리 (NGMS 데이터 기반) |
+| --- | --- | --- | --- |
+| **C** | 제조업 종합 | `1.8` | 탄소다배출 업종 다수 포함. 탄소세 급증에 따른 이익경계 악화 고위험군 |
+| **C19/C24**| 석유/1차금속 | `2.5`, `2.2` | 제조업 중에서도 하드투어베이트(Hard-to-Abate) 섹터로 전환 리스크 최고치 |
+| **D** | 전기, 가스 | `2.8` | 연료 믹스 전환과 배출권 비용 직격탄을 맞는 핵심 취약 섹터 |
+| **J** | 정보통신업 | `0.4` | Scope 1 배출량이 미미하여 전력(Scope 2) 비용 이외 타격 최소화 |
+| **K** | 금융 및 보험 | `0.3` | Scope 3 이슈가 있으나 자체 운영 배출량 증가 리스크는 최저수준 |
+
+**적용 원리**:
+NGFS API 파싱 테이블의 "Carbon Price" 혹은 "GDP"의 % 충격(Shock Delta) 값에 각 섹터의 **Carbon Beta**를 곱하여, 실제 개별 채권(Credit Spread 가산) 및 주식 팩터(Shock 하락률) 변동 충격을 최종 연산합니다.
+
+## 3. SQLite 연동 (Storage Layer)
+- `src/db_storage.py`를 통해 위의 NGFS 산출물(`ngfs_macro_time_series`)과 KSIC 기초 매핑 체계(`ksic_carbon_beta`)가 `data/climate_risk.db` SQLite 파일 내에 RDBMS로 성공적으로 적재 완료되었습니다.
+- 구축된 테이블들은 2단계(Phase 2)에 제작될 시장 파라미터 연산 엔진(변환 모듈)이 SQL 형식으로 값을 직접 Select하여 손쉽게 Tensor 계산을 수행하도록 돕습니다.

docs/phase2_explanation.md

@@ -0,0 +1,36 @@
+# Phase 2: 시장 리스크 파라미터 변환 엔진 (ISDA 방법론 검증)
+
+## 1. 아키텍처 다이어그램 및 데이터 흐름
+
+- **입력 1**: NGFS 거시경제 시계열 모의 결과 (`climate_risk.db`의 SQLite)
+- **입력 2**: Deriva 운영 DB의 기초 시장 데이터 (`localhost:15400` PostgreSQL `deriva` DB의 `asset_masters`, `yield_curves`)
+- **프로세서**: `Market_Risk_Engine` (파이썬 모듈, ISDA Merton Firm-Value Framework 탑재)
+- **출력**: `climate_risk.db`의 4대 텐서 적재 (`shocks_ir`, `shocks_credit`, `shocks_equity`)
+
+## 2. Deriva DB (PostgreSQL) 기초 데이터 수집
+포스트그레스 `deriva` 스키마로부터 실제 레벨(Base Market Level)을 추출하여 모델의 기준으로 삼았습니다.
+- **Yield Curves**: DB 내의 평탄화 기준 Zero Rate들을 조회해 국채 및 OIS의 Base 커브 포인트를 설정합니다.
+- **Asset Masters**: `asset_code`, `credit_rating`, `gics_sector` 테이블을 참조해 매핑하되 해당 회사가 KSIC 탄소 민감도 테이블 스케일러의 어느 그룹에 속하는지 식별합니다.
+
+## 3. ISDA 펌 밸류 통합 충격 수식 (Merton Asset Value $\Delta V$ )
+고객님께서 지적하신 ISDA Phase 4에 부합하도록 주가, 채권 스프레드의 변화량을 '기업 총 자산가치의 증감량'이라는 하나의 공통 팩터로 묶어 무재정(No-arbitrage) 연산을 실현했습니다.
+
+`dV = (GDP_Shock * Carbon_Beta) - (CO2_Shock * Carbon_Beta)`
+
+위처럼 도출된 단일한 `dV` (부정적일 경우 자산 감소) 값을 기반으로 다음과 같이 개별 파라미터가 갈라집니다:
+
+### 가. 주식 충격율 (Equities) - 레버리지 하락분
+주식은 자본 구조상 자산 가치 하락 시 후순위 레버리지 지분을 전량 흡수하므로 증폭을 받습니다.
+`Equity_Shock(%) = dV * Leverage_Multiplier`
+엔진 로직상 부채비율(레버리지 팩터) 기반으로 Base 주가지수를 타격합니다.
+
+### 나. 크레딧 스프레드 상향 (Credit Spread Jump)
+기조 부도 스프레드(Base Spread)를 출발점으로 잡고 Merton 모델의 탄성을 반영합니다:
+`New_Spread_bps = Base_Spread * exp(-dV * Tuning_Factor)`
+자산가치가 줄어듦에 따라, Distance-to-Default가 한계치로 이동하면서 기하급수적으로 베이시스가 상승/팽창합니다. 채권의 신용 등급별(Base Spread) 차동과 섹터별 민감도가 완벽히 반영됩니다.
+
+### 다. 이자율 평행 이동 (IR Parallel Shift)
+정책 금리 쇼크분율은 Base 커브 포인트 구간 배열 전체에 1:1 Parallel Shift 가산되는 보수적 충격 구조를 사용했습니다.
+
+## 4. 최종 적재 완료
+출력 연산 파이프루틴은 성공적으로 완료되었으며 `climate_risk.db` SQL 데이터베이스 속에 채권-주식-금리의 3가지 리프라이싱 전용 테이블로 분할 저장되었습니다.