# 현물 2단계 설계 가이드

> DeepCoin 현물 파이프라인 2단계(인과 기법 분석)의 목적, 구조, 설계 근거를 정리한 문서입니다.  
> 작성 기준: 2026-06-12 · 기본 TF: 3분봉 · GT: v3

---

## Plan (계획)

### 목적

현물 2단계는 **0단계 Ground Truth(GT) 타점을 인과적으로 재현할 수 있는 매매 기법을 검증·순위화**하고, 3단계 실거래(`composite_v3` + MTF 필터)에 넘길 전략을 확정하는 단계입니다.

| 단계 | 핵심 질문 | 미래 데이터 |
|------|-----------|-------------|
| 0단계 | 10년 3분봉에서 이론상 최적 매수/매도는 어디였나? | 사용 (사후 분석, 실거래 불가) |
| 1단계 | GT를 완벽히 따라가면 수익 상한은? | GT 자체가 사후 타점 |
| **2단계** | **과거 데이터만으로 GT 타점을 얼마나 맞출 수 있나?** | **미사용 (인과)** |
| 3단계 (예정) | 검증된 전략을 실거래에 연결 | 실시간 인과 |

### GT v3 신호 유형 (정답지)

0단계 GT v3는 3분봉 `bar_index` 기준으로 아래 6종 신호를 포함합니다.

| 코드 | 유형 | 의미 |
|------|------|------|
| B | swing_low | 스윙 매수 |
| B* | pullback | 눌림목 매수 |
| B^ | breakout | 돌파 매수 |
| Bd | div_bull | 상승 다이버전스 매수 |
| S | swing_high | 스윙 매도 |
| Sd | div_bear | 하락 다이버전스 매도 |

### 설계 원칙: 3분 = 타이밍, 상위 TF = 맥락

2단계는 **두 레이어**로 나뉩니다.

| 레이어 | 타임프레임 | 역할 |
|--------|------------|------|
| **기법 (2-1 ~ 2-3)** | 3분봉 | **언제** 사고팔지 — GT 타점 재현 |
| **MTF (2-4, 3단계)** | 1분 ~ 월봉 | **그때 해도 되는지** — 과매수·추세·변동성 보조 |

3분봉만 사용하는 것은 상위 TF를 무시한다는 뜻이 **아닙니다**. GT 정답지가 3분봉에 정의되어 있으므로 기법 평가는 동일 TF에서 수행하고, 일/주/월봉 맥락은 MTF 레이어에서 붙입니다.

### 2단계가 하지 **않는** 것

아래는 2단계의 목적과 맞지 않거나, 별도 설계가 필요한 접근입니다.

- 39개 기법을 1분 ~ 월봉 **모든 TF**에 각각 실행
- **모든 봉**에 시장 상태 라벨을 붙여 매수/매도를 처음부터 탐색
- GT 없이 상태 분류만으로 전략을 발견

---

## Do (실행)

### 파이프라인 실행

```bash
cd DeepCoin
export PYTHONPATH=src
bash scripts/2_run_stage2_all.sh
```

### 4단계 세부

| 순서 | 스크립트 | 입력 | 산출물 |
|------|----------|------|--------|
| 2-1 | `2_run_techniques.py` | 3분봉 3650일, GT v3 | `data/spot/techniques/*.json`, `comparison_report.html` |
| 2-2 | `2_run_causal_sim.py` | 2-1 결과 | `causal_sim_report.html`, 기법별 sim 차트 |
| 2-3 | `2_run_signal_type_align.py` | 2-1 결과 (캐시) | `signal_type_report.html` |
| 2-4 | `2_run_mtf_analysis.py` | GT v3, 1분~월봉 피처 | `mtf_correlation_report.html`, `data/spot/mtf/mtf_rules_v3.json` |

### 2-1. 기법 실행

**처리 흐름**

1. `coins.db`에서 BTC **3분봉** 3650일 로드 (`GT_INTERVAL_MIN=3`)
2. 등록된 **39개 인과 기법** 각각 `generate_signals()` 실행
3. 조건 충족 봉에서만 `buy` / `sell` **이벤트** 생성 (모든 봉에 상태 라벨 X)
4. 신호를 매수·매도 **레그(leg)** 로 묶고 수익률 계산
5. GT v3 타점과 **정합(alignment)** 평가 — 기본 허용 오차 ±480봉 (약 24시간)

**정합 지표**

- recall, precision, F1
- leg recall (매수·매도 쌍 단위)
- 종합 **score** (터미널 `score=91.1` 등)

**39개 기법 구성**

- 단일 기법 33종: 스윙, 눌림목, 돌파, 다이버전스, 지표, 추세, 모멘텀, 변동성, 구조, 거래량
- 복합 기법 6종: `composite_swing`, `composite_pullback`, `composite_breakout`, `composite_divergence`, **`composite_v3`**, `composite_full`

`composite_v3`는 v3 GT 6종 신호를 가중 투표로 재현하는 **3단계 실거래 후보 전략**입니다.

### 2-2. 인과 sim

- 2-1에서 저장한 기법 신호를 **최근 3년** (`GT_SIM_LOOKBACK_DAYS=1095`) 구간으로 sim
- 1단계 GT sim(정답지 수익 상한)과 비교
- 기법별 HTML sim 차트 생성

### 2-3. 신호 유형별 정합

- GT v3의 B / B* / B^ / Bd / S / Sd **유형별 recall** 분석
- 예: `ema_pullback`은 B*(눌림목)에 강한가, `rsi_divergence`는 Bd/Sd에 강한가
- 유형별 최고 recall 기법 리포트

### 2-4. MTF 상관 분석

39기법을 TF마다 다시 돌리지 **않습니다**. 대신:

1. GT v3 **매수/매도 시점**(양성 샘플)에서 1분 ~ 월봉 피처 스냅샷 추출
2. GT가 아닌 **랜덤 3분봉 시점**(음성 샘플, 기본 2000건)에서 동일 추출
3. 양성 vs 음성 피처 차이(Cohen's d) 분석
4. 신호 유형별 MTF **필터 규칙** 도출 → `mtf_rules_v3.json`

**사용 TF** (`DEFAULT_DOWNLOAD_INTERVALS`)

1, 3, 5, 10, 15, 30, 60, 240분, 일(1440), 주(10080), 월(43200)

**TF별 피처** (`src/deepcoin/mtf/features.py`)

| 피처 | 용도 |
|------|------|
| `rsi14` | 과매수 / 과매도 |
| `bb_position` | 볼린저 밴드 내 위치 |
| `close_vs_ema60_pct` | EMA60 대비 이격 (추세·과열) |
| `ema60_slope_5_pct` | EMA60 기울기 |
| `trend_bias` | bullish / bearish |
| `atr_pct` | 변동성 |
| `zigzag_direction`, `zigzag_leg_pct` | 인과 ZigZag 상태 |

모든 피처는 **인과적** — 해당 시점에 확정된 봉만 사용, 미래 데이터·미완성 상위 TF 봉 미사용.

### 3단계 연동 (예정)

```
3분 composite_v3 신호 발생
    → MtfFeatureExtractor: 그 시점 1분~월봉 스냅샷
    → HtfTrendGate: 60분·일봉 EMA 이격으로 극단 구간 차단
    → MtfSignalFilter: 신호 유형별 MTF 규칙 N개 이상 충족
    → 통과 신호만 실거래
```

**고TF 추세 게이트** (`HtfTrendGate`) 기본값

| 조건 | 동작 |
|------|------|
| 일봉 EMA60 대비 -25% 이하 | 매수 차단 (과매도·칼날) |
| 60분 EMA60 대비 -15% 이하 | 매수 차단 |
| 일봉 EMA60 대비 +35% 이상 | 매도 차단 (과열) |
| 60분 EMA60 대비 +20% 이상 | 매도 차단 |

### 데이터 흐름

```mermaid
flowchart TD
    GT["0단계 GT v3\n(3분봉 정답 타점)"]
    Candles["3분봉 3650일\n(coins.db)"]

    subgraph step21 ["2-1 기법 실행"]
        T["39개 인과 기법"]
        T --> Sig["매수/매도 신호"]
        Sig --> Align["GT 정합 score"]
    end

    subgraph step22 ["2-2 sim"]
        Sim["최근 3년 수익률"]
    end

    subgraph step23 ["2-3 신호유형"]
        Type["B/B*/B^/Bd/S/Sd별 recall"]
    end

    subgraph step24 ["2-4 MTF"]
        MTF["1분~월봉 피처"]
        MTF --> Rules["mtf_rules_v3.json"]
    end

    subgraph step3 ["3단계 (예정)"]
        Filter["composite_v3 + MtfSignalFilter"]
    end

    GT --> Align
    Candles --> step21
    Align --> step22
    Align --> step23
    GT --> step24
    MTF --> Rules
    Rules --> Filter
    Sig --> Filter
```

---

## Check (검토)

### 접근 방식 비교

#### A. 현재 방식 (채택)

3분봉 × 39기법 GT 정합 + 4단계 MTF 상관 분석

#### B. 대안: 모든 기법 × 모든 TF × 모든 봉 상태

| 구분 | A: 현재 2단계 | B: 전 TF·전 봉 상태 | C: 절충 (선택 실험) |
|------|---------------|---------------------|---------------------|
| **품질 (Q)** | GT와 동일 TF·bar_index로 평가 **명확** | TF마다 신호 의미 상이, **평가 기준 혼란** | 핵심 기법만 상위 TF 추가 검증 |
| **비용 (C)** | 39기법 × 1 TF ≈ 1~2시간 | 39 × 11 TF ≈ 10~20시간+, 봉별 상태 저장 부담 큼 | +2~3 TF 시 +30~50% |
| **일정 (D)** | 파이프라인·3단계 **구현 완료** | 정합·스키마·리포트 **전면 재설계** | 기존 유지 + 실험 브랜치 |
| **리스크 (R)** | 단일 TF 편향 (MTF로 보완) | 차원 폭발 → **과적합** | 실험 범위 제한으로 통제 |
| **장점 (S)** | 인과·실거래·GT 정합 **일관** | TF별 탐색적 발견 | A 명확성 + B 인사이트 일부 |
| **단점 (W)** | 2-1 단독으론 상위 TF 안 보임 | GT(3분)와 **축 불일치** | 실험 설계 부담 |
| **비고** | **현 단계 최적** | 2단계 **대체안 부적합** | 장기 개선 1순위 |

**결론: A(현재 방식) 유지. 필요 시 C로 확장.**

### 3분봉만으로 상위 TF 과매수/과매도 판단이 어렵지 않은가?

**맞습니다.** 3분봉 신호만 따르면:

- 일봉 RSI 과매수 구간 3분 눌림목 매수 → 역추세 진입
- 주봉 하락 추세 3분 돌파 매수 → 가짜 돌파
- 월봉 과매도 3분 매도 → 바닥 청산

등의 문제가 발생합니다. DeepCoin은 이를 **MTF 레이어**로 보완합니다.

| 상황 | MTF 해석 | 의도 |
|------|----------|------|
| 3분 B* + 주봉 RSI 과매도 + 일봉 trend bullish | MTF 규칙 다수 충족 | 적극 매수 (3단계 확장) |
| 3분 B* + 일봉 RSI 과매수 | 게이트/규칙 미충족 | 보류 |
| 3분 S + 월봉 과열 + 60분 기울기 꺾임 | 매도 규칙 충족 | 적극 매도 (3단계 확장) |

현재 구현은 **차단(필터)** 중심이며, MTF 점수 기반 **포지션 크기 조절**은 3단계에서 확장 가능합니다.

### KPI · 확인 방법

| KPI | 확인 위치 | 기준 예시 |
|-----|-----------|-----------|
| GT 정합 score | `comparison_report.html` | composite_v3 상위권 |
| leg recall | `data/spot/techniques/*.json` | 70% 이상 (기법별 상이) |
| sim 수익률 (3년) | `causal_sim_report.html` | 1단계 GT sim 대비 합리적 |
| 신호 유형 recall | `signal_type_report.html` | B/B*/B^/Bd/S/Sd 유형별 1위 기법 |
| MTF Cohen's d | `mtf_correlation_report.html` | \|d\| ≥ 1.2 규칙 후보 |
| MTF 규칙 통과율 | 3단계 `MtfSignalFilter` | kept/rejected 비율 |

### 주요 환경 변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `GT_INTERVAL_MIN` | GT·기법 기준 인터벌(분) | `3` |
| `GT_LOOKBACK_DAYS` | GT·기법 기간(일) | `3650` |
| `GT_SIM_LOOKBACK_DAYS` | sim·MTF 분석 구간(일) | `1095` |
| `GT_ALIGN_TOLERANCE_BARS` | GT 정합 허용 봉 수 | `480` |
| `TECHNIQUES_DIR` | 기법 결과 JSON | `data/spot/techniques/` |
| `MTF_RULES_JSON` | MTF 규칙 | `data/spot/mtf/mtf_rules_v3.json` |

---

## Act (개선)

### 현재 한계

| 항목 | 상태 | 비고 |
|------|------|------|
| 2-1 ~ 2-3 | MTF 미적용 | 의도적 — GT 정합 단계 |
| `HtfTrendGate` | 60분·일봉만 | 주·월봉 RSI/BB 게이트 추가 가능 |
| MTF 필터 | 통과/실패 이진 | 점수 기반 사이즈 조절 (3단계) |
| 2-4 → rules JSON | `derive_rules_from_report()` 존재 | 2-4 스크립트 자동 저장 연동 검토 |

### 권장 개선 (절충 C)

2단계 골격은 유지하고, 아래만 **별도 실험**으로 진행합니다.

1. **TF별 핵심 기법**: 스윙 5종 + `composite_v3`를 60분·일봉에 추가 실행 — 상위 TF 스윙과 3분 GT 정합 비교
2. **MTF 4단계 강화**: 음성 샘플 수, 피처, `min_cohens_d` 조정
3. **주·월봉 게이트**: `HtfTrendGate`에 RSI/BB 기반 조건 추가
4. **레짐 라벨 모듈**: EMA/ADX 등 봉별 장세 라벨 — 39기법 전 TF 재실행 없이 보조

### 하지 말아야 할 것

- 39기법 × 11 TF × 175만 3분봉 상태를 2단계 **기본 산출물**로 포함
- GT(3분)와 다른 TF 신호를 **동일 tolerance**로 무조건 비교

### 실행 체크리스트

- [ ] 0단계 GT v3 생성 완료 (`0_ground_truth.py --tier all`)
- [ ] 1단계 GT sim 완료 (벤치마크 참조용)
- [ ] `bash scripts/2_run_stage2_all.sh` 완료
- [ ] `comparison_report.html` — 기법 순위 확인
- [ ] `signal_type_report.html` — 유형별 강점 기법 확인
- [ ] `mtf_correlation_report.html` — 일/주/월 RSI·EMA 패턴 확인
- [x] `mtf_rules_v3.json` — 3단계 필터 규칙 반영 (`data/spot/mtf/mtf_rules_v3.json`)

---

## 참고: 관련 소스

| 모듈 | 경로 |
|------|------|
| 기법 실행 | `scripts/2_run_techniques.py`, `src/deepcoin/techniques/runner.py` |
| GT 정합 | `src/deepcoin/evaluation/gt_align.py` |
| MTF 피처 | `src/deepcoin/mtf/features.py`, `extractor.py`, `store.py` |
| MTF 규칙 | `src/deepcoin/mtf/rules.py` |
| MTF 필터 | `src/deepcoin/mtf/filter.py`, `trend_gate.py` |
| 통합 기법 | `src/deepcoin/techniques/composite_v3.py` |

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2026-06-12 | 초版 작성 — 2단계 목적, 4단계 구조, MTF 보완, 접근 방식 비교 정리 |