# 현물 3단계 설계 가이드 — 실거래 운영

> 2단계 검증 전략(`composite_v3` + MTF 필터)을 빗썸 현물에 연결하는 운영 단계  
> 작성 기준: 2026-06-12 · 기본 모드: **paper**

---

## Plan (계획)

### 목적

2단계에서 도출한 **인과 기법 + MTF 필터**를 실시간(또는 모의) 운영 파이프라인에 연결하고, **live 전환 전** 필터 효과를 백테스트로 재검증한다.

### 파이프라인

```
캔들 증분 동기화 (00_download.py)
    ↓
composite_v3 신호 생성 (3분봉)
    ↓
signal_type 추론 (기여 기법 → B/B*/B^/Bd/S/Sd)
    ↓
HtfTrendGate (60분·일봉 극단 차단)
    ↓
MtfSignalFilter (mtf_rules_v3.json)
    ↓
paper / live 체결 (구간별 매수 상한 동일)
```

### 운영 모드

| 모드 | 설명 | 기본값 |
|------|------|--------|
| **paper** | DB 캔들·신호 가격 기준 모의 체결 | **권장·기본** |
| **live** | 빗썸 Private API 시장가 주문 | API 키 필요, 신중히 사용 |

---

## Do (실행)

### 스크립트

| 순서 | 스크립트 | 역할 |
|------|----------|------|
| 3-1 | `3_run_filtered_backtest.py` | MTF 필터 전/후 3년 sim 비교 |
| 3-2 | `3_run_operations.py` | paper/live 1회 tick (신호·체결) |
| 일괄 | `3_run_stage3_all.sh` | 3-1 + 3-2 paper |

```bash
cd DeepCoin
export PYTHONPATH=src

# MTF 필터 백테스트
python scripts/3_run_filtered_backtest.py

# paper 운영 1회
python scripts/3_run_operations.py

# 일괄
bash scripts/3_run_stage3_all.sh
```

### 주요 환경 변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `OPS_MODE` | `paper` / `live` | `paper` |
| `OPS_TECHNIQUE_ID` | 운영 기법 | `composite_v3` |
| `OPS_MIN_SCORE` | composite 최소 점수 (선택) | 기법 기본 2.5 |
| `OPS_MTF_ENABLED` | MTF 필터 | `true` |
| `OPS_TREND_GATE_ENABLED` | 고TF 게이트 | `true` |
| `OPS_DAILY_MAX_TRADES` | 일일 체결 상한 | `20` |
| `OPS_MIN_ORDER_KRW` | 최소 주문 원화 | `5000` |
| `OPS_STATE_JSON` | 운영 상태 | `data/spot/operations/ops_state.json` |
| `BITHUMB_ACCESS_KEY` | live API (선택) | — |
| `BITHUMB_SECRET_KEY` | live API (선택) | — |

### 산출물

| 파일 | 내용 |
|------|------|
| `docs/spot/3_operations/filtered_backtest_report.json` | 필터 전/후 sim |
| `docs/spot/3_operations/ops_report.json` | 최근 tick 리포트 |
| `data/spot/operations/ops_state.json` | 포트폴리오·체결 이력 |

### 소스 모듈

| 모듈 | 경로 |
|------|------|
| 신호 파이프라인 | `src/deepcoin/operations/signal_pipeline.py` |
| signal_type 추론 | `src/deepcoin/operations/signal_type.py` |
| 체결 엔진 | `src/deepcoin/operations/trade_engine.py` |
| paper/live | `src/deepcoin/operations/executor.py` |
| 러너 | `src/deepcoin/operations/runner.py` |
| 빗썸 Private | `src/deepcoin/api/bithumb_private.py` |

---

## Check (검토)

### 초기 백테스트 결과 (BTC · 3년 · composite_v3)

| 구분 | 신호 수 | 3년 sim 수익률 |
|------|---------|----------------|
| MTF 필터 **전** | 12,262 | **-97.5%** |
| MTF 필터 **후** | 1,215 | **+3.37%** |

MTF 필터가 composite_v3의 과다 신호·역추세 진입을 상당 부분 걸러냅니다. live 전환 전 paper 운영으로 추가 검증이 필요합니다.

### live 전환 전 체크리스트

- [ ] `3_run_filtered_backtest.py` — 필터 후 sim이 raw 대비 개선되는지 확인
- [ ] 최소 1주일 **paper** 운영 (`--loop 180` 등)
- [ ] `OPS_DAILY_MAX_TRADES`·`OPS_MIN_SCORE` 튜닝
- [ ] 빗썸 API 키 **출금 비활성**·IP 제한 설정
- [ ] 소액으로 live 테스트

### 2단계 대비 3단계 차이

| 항목 | 2단계 | 3단계 |
|------|-------|-------|
| 목적 | 기법 평가·순위 | **운영 연결** |
| 신호 | 39종 개별 | **composite_v3 + MTF** |
| 체결 | 일괄 sim | **tick 단위 paper/live** |
| MTF | 분석·규칙 | **실시간 필터** |

---

## Act (개선)

### 권장 튜닝

1. `OPS_MIN_SCORE` 상향 (예: 3.5~4.0) — 신호 과다·스킵 감소
2. `OPS_DAILY_MAX_TRADES` 하향 — 과매매 방지
3. 텔레그램 알림 연동 (선택)
4. 슬리피지 가정 paper 백테스트 확장

### 하지 말아야 할 것

- 백테스트 미검증 상태에서 **live 풀오토**
- 2단계 sim 1위(`fractal_swing`) 그대로 운영
- API 키를 Git에 커밋

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2026-06-12 | 3단계 초版 — paper/live 파이프라인, MTF 필터 백테스트, 운영 스크립트 |