cointrader/docs/plans/2026-03-22-backtest-market-context-design.md

# 백테스트 시장 컨텍스트 리포트 설계

**일자**: 2026-03-22
**상태**: 설계 완료, 구현 대기

---

## 목적

Walk-Forward 백테스트 결과를 해석할 때, 각 폴드 기간의 시장 상황(BTC/ETH 추세, L/S ratio)을 함께 보여준다. **"왜 이 폴드에서 졌는가"**를 구조적으로 이해하기 위한 참조 데이터이며, 트레이딩 시그널이나 ML 피처로는 사용하지 않는다.

## 접근 방식

Walk-Forward 폴드 테이블 출력 직후에 시장 컨텍스트 테이블 2개(Market Regime + L/S Ratio)를 추가한다. 기존 `scripts/run_backtest.py`만 수정하며, 별도 CLI 명령어는 만들지 않는다.

---

## 데이터 소스

### 1. BTC/ETH 가격 데이터 (Market Regime)

- **소스**: XRP의 `data/xrpusdt/combined_15m.parquet`에 임베딩된 `close_btc`, `high_btc`, `low_btc`, `close_eth`, `high_eth`, `low_eth` 컬럼
- 별도 `data/btcusdt/combined_15m.parquet` 파일은 로컬/프로덕션 모두 **존재하지 않음**
- 백테스터가 이미 이 임베딩 컬럼을 로딩하므로 추가 데이터 fetch 불필요
- 폴드 기간별로 슬라이싱하여 수익률, ADX 계산

### 2. L/S Ratio 데이터

- **소스**: `data/{symbol}/ls_ratio_15m.parquet` (로컬 파일)
- **심볼**: XRPUSDT, BTCUSDT, ETHUSDT
- **주기**: 15m
- **컬럼**: `timestamp` (datetime64[ms, UTC]), `top_acct_ls_ratio` (float64), `global_ls_ratio` (float64)

#### 현재 데이터 상태

- L/S ratio collector는 운영 LXC(`10.1.10.24`)에서 가동 중 (commit `e2b0454`, 2026-03-22~)
- **프로덕션**: XRP/BTC/ETH 각 3건 (2026-03-22 13:15 ~ 13:45 UTC), 계속 축적 중
- **로컬**: XRP 2건, BTC 2건, ETH 2건 (로컬 collector 테스트 시 생성된 데이터)
- 과거 폴드(2025-06, 2025-09, 2025-12)에 대한 L/S ratio 데이터는 **존재하지 않음**
- Binance API는 최근 30일만 historical 제공 → 과거 데이터 복구 불가능

#### 데이터 동기화

구현 전 프로덕션 LXC에서 L/S ratio parquet 파일을 로컬로 복사해야 한다:

```bash
scp root@10.1.10.24:/root/cointrader/data/xrpusdt/ls_ratio_15m.parquet data/xrpusdt/
scp root@10.1.10.24:/root/cointrader/data/btcusdt/ls_ratio_15m.parquet data/btcusdt/
scp root@10.1.10.24:/root/cointrader/data/ethusdt/ls_ratio_15m.parquet data/ethusdt/
```

#### Fallback 전략

1. **로컬 parquet 우선**: `data/{symbol}/ls_ratio_15m.parquet`에서 폴드 기간 데이터 조회
2. **파일 없거나 해당 기간 데이터 없으면 `N/A`**: 폴드의 L/S ratio 셀을 `N/A`로 표시
3. **전체 폴드가 N/A이면 L/S ratio 테이블 자체를 생략**: 불필요한 N/A 테이블을 출력하지 않음
4. **Binance API에서 실시간 fetch하지 않음**: 백테스트는 오프라인 재현 가능해야 함
5. **시간이 지나면 해결됨**: collector가 계속 수집하므로, 데이터 축적 후 백테스트에 자연스럽게 반영

---

## Market Regime 분류 기준

BTC ADX와 수익률 기반으로 **코드에 명확히 정의**하여 주관적 해석을 방지한다:

| 조건 | 라벨 |
|------|------|
| ADX ≥ 25 and return > 0 | 상승 추세 |
| ADX ≥ 25 and return < 0 | 하락 추세 |
| ADX < 25 | 횡보 |

- ADX는 폴드 기간 내 BTC 15m 캔들(`high_btc`, `low_btc`, `close_btc`)로 계산한 **기간 평균 ADX** (`pandas_ta.adx(length=14)` 사용)
- return은 폴드 시작가 대비 종료가의 **단순 수익률** (`close_btc`)
- 라벨 뒤에 `(BTC ADX {값:.0f})` 형태로 실제 수치 병기

---

## 출력 형식

기존 폴드 테이블 바로 아래에 출력:

```
📊 Market Context per Fold
┌──────┬──────────────┬──────────────┬─────────────────────────────────┐
│ Fold │ BTC Return   │ ETH Return   │ Market Regime                   │
├──────┼──────────────┼──────────────┼─────────────────────────────────┤
│ 1    │ +12.3%       │ +8.7%        │ 상승 추세 (BTC ADX 32)          │
│ 2    │ -2.1%        │ -5.4%        │ 횡보 (BTC ADX 18)               │
│ 3    │ +25.6%       │ +18.2%       │ 상승 추세 (BTC ADX 41)          │
└──────┴──────────────┴──────────────┴─────────────────────────────────┘

📊 L/S Ratio Context per Fold (period avg)
┌──────┬──────────────────┬──────────────────┬──────────────────┐
│ Fold │ XRP Top/Global   │ BTC Top/Global   │ ETH Top/Global   │
├──────┼──────────────────┼──────────────────┼──────────────────┤
│ 1    │ N/A              │ N/A              │ N/A              │
│ 2    │ N/A              │ N/A              │ N/A              │
│ 3    │ 1.15 / 0.98      │ 0.95 / 1.02      │ 1.08 / 1.05      │
└──────┴──────────────────┴──────────────────┴──────────────────┘
  → Fold 1~2: L/S ratio 데이터 없음 (collector 가동 전)
  → Fold 3: 데이터 가용
```

**전체 폴드가 N/A인 경우** (현재 상태에서 과거 데이터만으로 백테스트하면):

```
📊 Market Context per Fold
┌──────┬──────────────┬──────────────┬─────────────────────────────────┐
│ Fold │ BTC Return   │ ETH Return   │ Market Regime                   │
├──────┼──────────────┼──────────────┼─────────────────────────────────┤
│ 1    │ +12.3%       │ +8.7%        │ 상승 추세 (BTC ADX 32)          │
│ 2    │ -2.1%        │ -5.4%        │ 횡보 (BTC ADX 18)               │
│ 3    │ +25.6%       │ +18.2%       │ 상승 추세 (BTC ADX 41)          │
└──────┴──────────────┴──────────────┴─────────────────────────────────┘
  ℹ️ L/S ratio 데이터 없음 — collector 데이터 축적 후 표시됩니다
```

### JSON 출력

walk-forward 결과 JSON에도 `market_context` 필드 추가:

```json
{
  "folds": [
    {
      "fold": 1,
      "test_period": "2025-06-07 ~ 2025-07-06",
      "test_start": "2025-06-07T00:00:00",
      "test_end": "2025-07-06T00:00:00",
      "summary": { "..." : "..." },
      "market_context": {
        "btc_return_pct": 12.3,
        "eth_return_pct": 8.7,
        "btc_avg_adx": 32.1,
        "market_regime": "상승 추세",
        "ls_ratio": null
      }
    },
    {
      "fold": 3,
      "test_period": "2026-03-01 ~ 2026-04-01",
      "test_start": "2026-03-01T00:00:00",
      "test_end": "2026-04-01T00:00:00",
      "summary": { "..." : "..." },
      "market_context": {
        "btc_return_pct": 5.2,
        "eth_return_pct": 3.1,
        "btc_avg_adx": 28.5,
        "market_regime": "상승 추세",
        "ls_ratio": {
          "xrp": { "top_acct_avg": 1.15, "global_avg": 0.98 },
          "btc": { "top_acct_avg": 0.95, "global_avg": 1.02 },
          "eth": { "top_acct_avg": 1.08, "global_avg": 1.05 }
        }
      }
    }
  ]
}
```

---

## 수정 대상 파일

| 파일 | 변경 유형 | 역할 |
|------|-----------|------|
| `scripts/run_backtest.py` | Modify | 시장 컨텍스트 계산 + 출력 함수 추가 |
| `src/backtester.py` | Modify (최소) | 폴드 결과에 `test_start`/`test_end`를 timestamp로 노출 (현재는 문자열 `test_period`만 있음) |

### 변경하지 않는 것

- `src/indicators.py` — ADX 계산은 `run_backtest.py` 내에서 `pandas_ta.adx()` 직접 사용
- `scripts/collect_ls_ratio.py` — 기존 collector 로직 변경 없음
- `src/ml_filter.py`, `src/ml_features.py` — ML 피처와 무관
- `scripts/fetch_history.py` — BTC/ETH 별도 fetch 불필요 (XRP parquet에 임베딩됨)

---

## 구현 전 선행 작업

1. ~~BTC/ETH 히스토리 데이터 fetch~~ → **불필요** (XRP parquet에 `close_btc`, `close_eth` 등 임베딩됨)
2. `backtester.py`에서 `test_start`/`test_end`를 timestamp로 노출하도록 수정
3. 프로덕션 LXC에서 L/S ratio parquet 파일 로컬 동기화

---

## 구현 범위 제한

- **참조 전용**: 시장 컨텍스트는 출력/리포트에만 사용. 트레이딩 로직에 영향 없음
- **오프라인 우선**: Binance API 호출 없음. 로컬 데이터만 사용
- **기존 테스트 영향 없음**: 출력 함수 추가이므로 기존 백테스트 로직 불변
- **L/S ratio 테이블 조건부 출력**: 전체 N/A이면 테이블 생략, 한 줄 안내 메시지만 출력