# Scenario Robustness Test — `fithia2 scenario-test`

합성 시장 데이터를 이용해 다양한 시장 환경에서 전략을 검증하고 과적합/취약점을 탐지하는 도구.

`overfit-check`가 **실제 데이터 기반 통계 검증**이라면, `scenario-test`는 **역사에 없었던 시장 환경**에 대한 내성 테스트다.
예: "VIX가 지속적으로 30이었다면?", "2022년 하락장이 2배 길었다면?", "유동성이 60% 증발했다면?"

---

## 빠른 사용법

```bash
# 3개 핵심 시나리오 (2~3초)
fithia2 scenario-test --config return_max_long_v7.70 --quick

# 전체 12개 시나리오 (~10초)
fithia2 scenario-test --config return_max_long_v7.70

# 특정 시나리오만
fithia2 scenario-test --config return_max_long_v7.70 --scenario crash_v_recovery

# 시나리오 그룹
fithia2 scenario-test --config return_max_long_v7.70 --group structural
fithia2 scenario-test --config return_max_long_v7.70 --group signal
```

`--config`에는 실험 이름, ID(숫자), 파일 경로 모두 사용 가능.

---

## 12개 사전 정의 시나리오

| 시나리오 | 시장 특성 | VIX | 신호강도 | 목적 |
|----------|----------|-----|---------|------|
| `steady_bull` | drift +15%, vol 14%, 252d | 14 | 0.35 | 기본 수익 환경 기준선 |
| `steady_bear` | drift -20%, vol 22%, 252d | 28 | 0.35 | 장기 하락 + Gate 0 동작 확인 |
| `crash_v_recovery` | 60d 정상 → 20d 폭락 → 172d 회복 | 15→45 | 0.35 | 폭락 복원력 |
| `prolonged_bear` | drift -15%, vol 25%, 504d | 30 | 0.30 | 역사보다 긴 2년 하락 |
| `low_vol_grind` | drift +8%, vol 8% | 11 | 0.20 | 저변동 환경 (ATR 축소) |
| `high_vol_chop` | drift 0%, vol 30% | 32 | 0.25 | 방향 없는 고변동 횡보 |
| `regime_switch` | 60d 상승/하락 4회 교대 | 20 | 0.30 | 빈번한 레짐 전환 |
| `vix_spike` | 정상 + 5회 VIX 급등(40+) | 18 | 0.35 | 스트레스 클러스터 |
| `no_signal` | drift 0%, vol 16%, 신호 없음 | 16 | **0.00** | 가격 패턴 과적합 탐지 |
| `strong_signal` | drift +10%, vol 16%, 강한 신호 | 16 | **0.60** | 이벤트 알파 포착 확인 |
| `sector_rotation` | 분기별 섹터 순환 | 20 | 0.35 | 섹터 집중 리스크 |
| `liquidity_drought` | drift +5%, vol 18%, 거래량 -70% | 22 | 0.30 | 유동성 필터 영향 |

### 시나리오 그룹

| 그룹 | 포함 시나리오 |
|------|-------------|
| `trend` | steady_bull, steady_bear, prolonged_bear |
| `volatility` | low_vol_grind, high_vol_chop, vix_spike |
| `regime` | regime_switch, crash_v_recovery |
| `signal` | no_signal, strong_signal |
| `structural` | sector_rotation, liquidity_drought |
| `quick` | steady_bull, steady_bear, no_signal |
| `all` | 전체 12개 |

---

## Regime Robustness Score (RRS)

5개 하위 점수의 가중 합산으로 전략의 환경 내성을 0-100으로 표현한다.

```
RRS = 0.25 × Signal Integrity
    + 0.25 × Breadth
    + 0.20 × Drawdown Resilience
    + 0.15 × Regime Transition
    + 0.15 × Stability
```

| 하위 점수 | 가중치 | 계산 방법 |
|-----------|--------|----------|
| **Signal Integrity** | 25% | `no_signal` Sharpe ≤ 0이면 100. `no_signal` ≥ `strong_signal`이면 0. 선형 보간. |
| **Breadth** | 25% | Sharpe > 0인 시나리오 비율 × 100 |
| **Drawdown Resilience** | 20% | `100 × (1 - 최악_DD / 50)`, 0-100 범위 클램핑 |
| **Regime Transition** | 15% | `regime_switch` Sharpe / 중앙값 Sharpe, 100 상한 |
| **Stability** | 15% | `100 × (1 - CV)`, CV = Sharpe의 변동계수 |

### 판정 기준

| RRS | 판정 | 의미 |
|-----|------|------|
| ≥ 70 | **ROBUST** | 다양한 환경에서 안정적 성과 |
| 40–69 | **FRAGILE** | 특정 환경 의존성 있음 |
| < 40 | **OVERFIT** | 가격 패턴 또는 특정 레짐에 과적합 |

---

## 결과 해석 가이드

### v7.70 기준 시나리오별 해석

```
시장 환경              Sharpe   운용 판단
──────────────────────────────────────────────
steady_bull   +1.09  ✅ 정상 운용, 풀 사이징
crash+회복    +0.41  ✅ 폭락 후 회복 구간 운용 가능
vix_spike     +0.30  ✅ VIX 급등 이벤트, 소폭 수익
prolonged_bear +0.13 ⚠️ 2년 하락장, flat → 사이징 축소
steady_bear   +0.03  ⚠️ 하락장, 간신히 손익분기 → 방어 모드
──────────────────────────────────────────────
regime_switch -0.56  🔴 방향 빈번 전환 → 쉬어야 함
low_vol_grind -0.40  🔴 변동성 너무 낮음 → 신호 희박
high_vol_chop -1.11  🔴 방향 없는 고변동 → 매우 위험
liquidity_drought -1.10 🔴 거래량 증발 → 진입 자체 불리
sector_rotation -1.40 🔴 섹터 로테이션 → 최악 환경
```

### 현재 시장 매핑

| 실시간 지표 | 해당 시나리오 | 운용 판단 |
|------------|--------------|---------|
| SPY 상승, VIX < 20 | steady_bull | 풀 운용 |
| SPY 횡보, VIX 20~30 | regime_switch | 사이징 50% |
| VIX 35+ 급등 | vix_spike | 소폭 or 대기 |
| SPY SMA 아래 지속 하락 | steady_bear | 방어, 최소 운용 |
| 거래량 급감 (ADV -40%+) | liquidity_drought | 일시 중단 |

---

## 주요 Status 플래그

| 플래그 | 조건 | 의미 |
|--------|------|------|
| `OVERFIT` | `no_signal` Sharpe > `strong_signal` Sharpe | 이벤트 신호 없이도 수익 → 가격 패턴 과적합 |
| `WEAK` | `strong_signal` Sharpe < 0 | 강한 알파 환경에서도 손실 → 셀렉션 기준 불일치 |

---

## 전략 비교 활용

```bash
# 취약 환경에서 새 전략이 개선됐는지 확인
fithia2 scenario-test --config return_max_long_v11.x --group structural

# sector_rotation / liquidity_drought 내성 개선 여부 비교
# → 두 Sharpe 모두 -1.0 이하면 개선 없음, -0.5 이상이면 유의미한 개선
```

---

## 구현 파일

| 파일 | 역할 |
|------|------|
| `libs/backtest/scenarios/price_gen.py` | Regime-switching GBM + 점프 확산 OHLCV 생성 |
| `libs/backtest/scenarios/macro_gen.py` | VIX/HY OU 프로세스, SPY/QQQ + 롤링 통계 |
| `libs/backtest/scenarios/event_gen.py` | 합성 이벤트 후보 전체 필드 생성 |
| `libs/backtest/scenarios/coupling.py` | 이벤트-가격 신호 커플링 (signal_strength 제어) |
| `libs/backtest/scenarios/store_builder.py` | SnapshotStore 조립 파이프라인 |
| `libs/backtest/scenarios/scenarios.py` | 12개 사전 정의 시나리오 + 레지스트리 |
| `libs/backtest/scenarios/robustness.py` | RRS 계산 + 판정 로직 |
| `apps/scenario/cli.py` | CLI 진입점, Rich 테이블 + RRS 패널 |
| `apps/tracker/cli.py` | `scenario-test` 서브커맨드 라우팅 |