refactor: Git에서 데이터 제거, 설정·코드만 유지

파이프라인 산출물(data/, docs/)을 Git 추적에서 제외하고
히스토리를 단일 커밋으로 재구성해 저장소 용량을 경량화한다.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -0,0 +1,314 @@
+# DeepCoin
+
+빗썸 KRW 마켓 암호화폐 캔들 데이터 수집 및 현물·선물 매매 전략 파이프라인.
+
+## 주요 기능
+
+- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
+- SQLite(`coins.db`) 저장 — 테이블명 `{SYMBOL}_{인터벌코드}` (예: `BTC_60`, `BTC_10080`)
+- 2017-01-01~ 역방향 페이지네이션 수집 (기본 3650일·10년, **1분봉 포함**)
+- Ground Truth 기반 현물·선물 벤치마크 및 인과 기법 분석
+
+## 요구사항
+
+- Python 3.10+
+- Conda 환경 `ncue` 또는 `xavis`
+
+## 설치
+
+```bash
+cd DeepCoin
+conda activate ncue
+pip install -r requirements.txt
+cp .env.example .env   # API 키 등 입력
+```
+
+## 환경 변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `SYMBOL` | 코인 심볼 | `BTC` |
+| `COIN_NAME` | 코인 이름 | `비트코인` |
+| `DB_PATH` | SQLite 경로 | `coins.db` |
+| `DOWNLOAD_DAYS` | 전체 수집·차트 일수 (10년) | `3650` |
+| `DOWNLOAD_INTERVALS` | 인터벌 코드 목록 (`1`=1분봉 포함) | `1,3,5,10,15,30,60,240,1440,10080,43200` |
+| `BITHUMB_API_CANDLE_COUNT` | 요청당 캔들 수 (최대 200) | `200` |
+| `API_REQUEST_SLEEP_SEC` | API 호출 간격(초) | `0.35` |
+
+인터벌 코드: 분봉은 분 단위 숫자, 일봉=`1440`, 주봉=`10080`, 월봉=`43200`
+
+캔들 조회는 Public API이므로 API 키 없이도 동작합니다.
+
+---
+
+## 파이프라인
+
+**0단계**는 현물·선물 공통입니다. 이후 현물·선물은 각각 1~3단계로 독립 진행합니다.
+
+| 구분 | 단계 | 내용 | 산출물 | 스크립트 |
+|------|------|------|--------|----------|
+| 사전 | — | 캔들 수집 | `coins.db` | `00_download.py` |
+
+### 0단계 — GT 타점 (현물·선물 공통)
+
+| 시장 | 산출물 | 스크립트 |
+|------|--------|----------|
+| 현물 | `docs/0_ground_truth/spot/` | `0_ground_truth.py` |
+| 선물 | `docs/0_ground_truth/futures/` | `0_ground_truth_futures.py` |
+
+### 현물 단계
+
+| 단계 | 내용 | 산출물 | 스크립트 |
+|------|------|--------|----------|
+| **현물 1단계** | GT sim (벤치마크) 현물 | `docs/spot/1_simulation/` | `1_ground_truth_sim.py` |
+| **현물 2단계** | 인과 기법 분석 (현물) | `docs/spot/2_analysis/` | `2_run_techniques.py` 등 |
+| **현물 3단계** | 현물 실거래 운영 | (예정) | (예정) |
+
+### 선물 단계
+
+| 단계 | 내용 | 산출물 | 스크립트 |
+|------|------|--------|----------|
+| **선물 1단계** | GT sim (벤치마크) 선물 | (예정) | (예정) |
+| **선물 2단계** | 인과 기법 분석 (선물) | (예정) | (예정) |
+| **선물 3단계** | 선물 실거래 운영 | (예정) | (예정) |
+
+### 단계별 상세 설명
+
+#### 사전 — 캔들 수집
+
+빗썸 Public API로 분·일·주·월봉(1분봉 포함) OHLCV를 수집해 `coins.db`에 저장합니다. 이후 모든 단계는 이 DB만 참조하며, 현물·선물이 DB를 공유합니다.
+
+- 기본 동작: DB 최신 시각 이후 **증분 갱신** (`00_download.py`)
+- 전체 재수집: `--full` 옵션 (최초 1회·DB 재구축 시)
+- 테이블명: `{SYMBOL}_{인터벌코드}` (예: `BTC_3`, `BTC_1440`)
+
+#### 0단계 — GT 타점 (현물·선물 공통)
+
+**Ground Truth(GT)** 는 사후적으로 “이상적인 매매 타점”을 정의한 기준 데이터입니다. 미래 캔들을 참조해 ZigZag 스윙·눌림목·돌파·다이버전스 타점을 찾으므로 **실거래에 직접 쓸 수 없고**, 이후 단계(벤치마크·기법 분석)의 **정답지(기준선)** 역할을 합니다.
+
+| 티어 | 포함 신호 | 설명 |
+|------|-----------|------|
+| **v1** | 스윙 B/S | ZigZag 스윙 저점 매수·고점 매도만 |
+| **v2** | + 눌림목 B* | v1 + 상승 레그 중 눌림목 매수 |
+| **v3** | + 돌파 B^ + 다이버전스 Bd/Sd | v2 + 돌파 매수 + RSI 다이버전스 매수·매도 |
+
+v3 신호 유형 6종:
+
+| `signal_type` | 라벨 | 의미 |
+|---------------|------|------|
+| `swing_low` | B | ZigZag 스윙 저점 매수 |
+| `pullback` | B* | 상승 추세 눌림목 매수 |
+| `breakout` | B^ | 횡보·레인지 상단 돌파 매수 |
+| `div_bull` | Bd | RSI 상승 다이버전스 매수 |
+| `swing_high` | S | ZigZag 스윙 고점 매도 |
+| `div_bear` | Sd | RSI 하락 다이버전스 매도 |
+
+**현물 0단계** (`0_ground_truth.py`): 3분봉·2017년~ 구간에서 GT를 생성하고, 매수/매도 마커가 표시된 인터랙티브 차트를 만듭니다.
+
+- 데이터: `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`
+- 차트: `docs/0_ground_truth/spot/ground_truth_chart_v{1,2,3}.html`
+
+**선물 0단계** (`0_ground_truth_futures.py`): 동일한 현물 GT 신호를 선물 롱·숏 4색 마커로 변환합니다. 가격·시각은 현물 GT와 동일하며, 해석만 선물 관점으로 매핑합니다.
+
+| 현물 GT | 선물 마커 | 의미 |
+|---------|-----------|------|
+| buy (B·B*·B^·Bd) | **L↑** | 롱 진입 (상방 매수) |
+| buy | **S↑** | 숏 청산 (하방 매도) |
+| sell (S·Sd) | **L↓** | 롱 청산 (상방 매도) |
+| sell | **S↓** | 숏 진입 (하방 매수) |
+
+- 데이터: `data/futures/ground_truth/ground_truth_trades_v{1,2,3}.json`
+- 차트: `docs/0_ground_truth/futures/ground_truth_chart_v{1,2,3}.html`
+
+#### 현물 1단계 — GT sim (벤치마크) 현물
+
+0단계 GT 타점을 **그대로** 따라 매매했을 때의 수익을 재현하는 **현물 벤치마크**입니다. “GT를 완벽히 따랐다면 얼마를 벌 수 있었는가”를 측정하며, 이후 인과 기법·실거래 전략이 비교해야 할 **상한선(천장)** 입니다.
+
+- 기간: 최근 **3년** (`GT_SIM_LOOKBACK_DAYS=1095`)
+- 초기 자본: **20만 원**
+- 매수 규칙: 총평가 구간별 현금 비율 상한 — 1억↑ 10% · 10억↑ 5% · 100억↑ 1%
+- 수수료: 편도 0.05% (`GT_TRADING_FEE_RATE`)
+- 산출물: `docs/spot/1_simulation/ground_truth_chart_sim_v{1,2,3}.html` (누적 수익 곡선·체결 마커 포함)
+
+#### 현물 2단계 — 인과 기법 분석 (현물)
+
+0단계 GT v3 타점을 **미래 데이터 없이** 재현할 수 있는 인과(causal) 매매 기법 39종을 실행하고, GT와 얼마나 맞는지 정량 평가합니다. 목표는 “실시간으로 쓸 수 있는 기법 조합이 GT 타점을 얼마나 포착하는가”를 파악하는 것입니다.
+
+| 스크립트 | 분석 내용 | 산출물 |
+|----------|-----------|--------|
+| `2_run_techniques.py` | 39종 기법 전체 실행 + GT 정합 비교 | `comparison_report.html`, `data/spot/techniques/*.json` |
+| `2_run_signal_type_align.py` | B/B*/B^/Bd/S/Sd 유형별 recall | `signal_type_report.html` |
+| `2_run_mtf_analysis.py` | GT v3 × 10개 TF 피처 상관 (Cohen's d) | `mtf_correlation_report.html`, `data/spot/mtf/mtf_rules_v3.json` |
+
+평가 지표:
+
+- **recall**: GT 신호 대비 기법 신호가 허용 오차(`GT_ALIGN_TOLERANCE_BARS`) 내에 맞춘 비율
+- **score**: recall·정밀도·타점 거리를 종합한 정합 점수
+- **MTF 상관**: 일·주·월 등 상위 TF 지표가 GT 유형별로 어떤 패턴을 보이는지 통계 분석
+
+#### 현물 3단계 — 현물 실거래 운영 (예정)
+
+현물 2단계에서 검증된 인과 기법(또는 `composite_v3` 등 통합 기법)을 빗썸 현물 API에 연결해 **실제 주문·체결·리스크 관리**를 수행하는 단계입니다.
+
+- 실시간 캔들 수신 및 인과 신호 생성
+- 주문 실행·포지션(보유 코인)·손절/익절 규칙
+- 1단계 GT sim 벤치마크 대비 실거래 성과 모니터링
+- 텔레그램 등 알림·로그·장애 복구
+
+#### 선물 1단계 — GT sim (벤치마크) 선물 (예정)
+
+선물 0단계 GT 타점(L↑/L↓/S↓/S↑)을 그대로 따라 롱·숏 포지션을 운용했을 때의 수익을 재현하는 **선물 벤치마크**입니다. 현물 1단계와 동일한 개념이나, 롱·숏 양방향·레버리지·청산 규칙 등 선물 고유 파라미터를 반영합니다.
+
+- 0단계 선물 GT 4색 마커 기준 체결 시뮬레이션
+- 현물 1단계와 동일한 초기 자본·기간·수수료 체계 (선물 수수료·슬리피지 별도 정의 예정)
+- 산출물 예정: `docs/futures/1_simulation/`
+
+#### 선물 2단계 — 인과 기법 분석 (선물) (예정)
+
+현물 2단계와 동일한 인과 기법 39종(또는 선물 특화 변형)을 선물 GT v3 타점과 정합 평가합니다. 롱·숏 각각의 recall, MTF 필터, 신호 유형별 성능을 선물 관점에서 분석합니다.
+
+- 선물 GT 6종 신호 ↔ 인과 기법 정합 리포트
+- 선물 MTF 상관 분석 및 규칙 추출
+- 산출물 예정: `docs/futures/2_analysis/`, `data/futures/techniques/`, `data/futures/mtf/`
+
+#### 선물 3단계 — 선물 실거래 운영 (예정)
+
+선물 2단계에서 검증된 전략을 실제 선물 거래 API에 연결해 롱·숏 포지션을 자동 운용하는 단계입니다.
+
+- 실시간 인과 신호 → 롱/숏 진입·청산
+- 레버리지·증거금·청산가 모니터링
+- 선물 1단계 sim 벤치마크 대비 실거래 성과 추적
+
+### 실행 순서
+
+0단계(GT 타점)를 먼저 만든 뒤, 현물 1단계 sim → 현물 2단계 인과 분석 순으로 진행합니다. 선물·현물 3단계는 각 시장의 1·2단계 완료 후 구현 예정입니다.
+
+```bash
+# 사전: 전체 인터벌 증분 갱신 (1분~월봉, DB 최신 이후만)
+python scripts/00_download.py
+
+# 사전: 전체 인터벌 풀 다운 (최초 1회 또는 DB 재구축)
+python scripts/00_download.py --full
+
+# 1분봉만 풀 다운 (수 시간 소요)
+python scripts/00_download_candles.py --full --days 3650 --intervals 1
+
+# 0단계: Ground Truth 타점 생성 (v1/v2/v3)
+python scripts/0_ground_truth.py
+
+# 0단계: 선물 GT 타점 차트 (롱·숏 4색, 타점만)
+python scripts/0_ground_truth_futures.py
+
+# 현물 1단계: GT sim (최근 3년 · 20만원)
+python scripts/1_ground_truth_sim.py --tier all
+
+# 현물 2단계: 인과 기법 GT 정합 비교
+python scripts/2_run_techniques.py
+python scripts/2_run_signal_type_align.py --from-cache
+python scripts/2_run_mtf_analysis.py
+```
+
+### 현물 2단계 인과 기법 목록 (39종)
+
+`src/deepcoin/techniques/` — 단일 33 + 복합 6, **미래 데이터 미사용**. 카탈로그: `data/spot/techniques_catalog.json`
+
+| ID | 기법 | 유형 | 설명 |
+|----|------|------|------|
+| `zigzag_causal` | 인과 ZigZag | 스윙 B/S | 되돌림 % 확정 시 스윙 저점 매수·고점 매도 (GT ZigZag 인과 버전) |
+| `minor_swing` | 소형 스윙 하이브리드 | 하이브리드 | 소형 ZigZag(2.5%) + 국소 극값 — GT 중간 눌림목 보완 |
+| `local_extrema` | 국소 극값 | 스윙 B/S | 국소 저점 매수·고점 매도 (눌림목 유형 포착) |
+| `pivot_swing` | 피벗 스윙 | 스윙 B/S | 피벗 저점 매수·고점 매도 (스윙 B/S) |
+| `fractal_swing` | 프랙탈 스윙 | 스윙 B/S | Williams 프랙탈 스윙 저점 매수·고점 매도 |
+| `swing_failure` | 스윙 실패 | 스윙 B/S | 스윙 고저점 돌파 실패(페일드 브레이크아웃) 반전 신호 |
+| `donchian` | 돈치안 채널 | 스윙 B/S | 돈치안(40) 채널 하단 매수·상단 매도 |
+| `ema_pullback` | EMA 눌림목 | 눌림목 B* | EMA(20/60) 눌림목 반등 매수·되돌림 매도 (B*) |
+| `fib_pullback` | 피보나치 눌림목 | 눌림목 B* | 피보나치 38.2~61.8% 되돌림 구간 매수·매도 (B*) |
+| `support_bounce` | 지지·저항 반등 | 눌림목 B* | N봉 지지·저항 터치 후 반전 (B*) |
+| `keltner_breakout` | Keltner 돌파 | 돌파 B^ | Keltner 채널 상·하단 돌파 (B^) |
+| `range_breakout` | 레인지 돌파 | 돌파 B^ | N봉 레인지 상·하단 돌파 (B^) |
+| `volume_breakout` | 거래량 돌파 | 돌파 B^ | 거래량 스파이크 + 레인지 돌파 (B^) |
+| `bb_squeeze_breakout` | BB 스퀴즈 돌파 | 돌파 B^ | 볼린저 밴드 스퀴즈 후 돌파 (B^) |
+| `rsi_divergence` | RSI 다이버전스 | 다이버전스 Bd/Sd | RSI 상승(Bd)·하락(Sd) 다이버전스 |
+| `macd_divergence` | MACD 다이버전스 | 다이버전스 Bd/Sd | MACD 히스토그램 상승(Bd)·하락(Sd) 다이버전스 |
+| `obv_divergence` | OBV 다이버전스 | 다이버전스 Bd/Sd | OBV 상승(Bd)·하락(Sd) 다이버전스 |
+| `bb_reversal` | 볼린저 역추세 | 지표 | BB(20,2) 하단 매수·상단 매도 + EMA 추세 필터 |
+| `ma_cross` | EMA 크로스 | 지표 | EMA(20/60) 골든크로스 매수·데드크로스 매도 |
+| `rsi_swing` | RSI 스윙 | 지표 | RSI(14) 과매도 반등 매수·과매수 하락 매도 |
+| `macd_cross` | MACD 크로스 | 지표 | MACD(12,26,9) 시그널선 골든·데드 크로스 |
+| `supertrend` | Supertrend | 추세 | Supertrend 상승·하락 전환 신호 |
+| `adx_trend` | ADX 추세 | 추세 | ADX(14) 강세 + DI 크로스 추세 신호 |
+| `ichimoku_trend` | 일목 추세 | 추세 | 일목 전환선·기준선 크로스 추세 신호 |
+| `parabolic_sar` | Parabolic SAR | 추세 | Parabolic SAR 추세 전환 신호 |
+| `stochastic_cross` | Stochastic 크로스 | 모멘텀 | Stochastic(14,3) %K/%D 크로스 |
+| `cci_extreme` | CCI 극값 | 모멘텀 | CCI(20) 과매도·과매수 반전 |
+| `roc_reversal` | ROC 반전 | 모멘텀 | ROC(12) 극값 반전 신호 |
+| `keltner_reversal` | Keltner 역추세 | 변동성 | Keltner 채널 하단 매수·상단 매도 |
+| `atr_channel` | ATR 채널 | 변동성 | EMA(20) ± ATR(14)×2 채널 반전 |
+| `pivot_points` | 피벗 포인트 | 구조 | 롤링 피벗 S1/R1 반전 |
+| `support_resistance` | 구조적 지지·저항 | 구조 | 스윙 피벗 기반 S/R 반전 |
+| `volume_spike` | 거래량 스파이크 | 거래량 | 거래량 스파이크 후 반전 (클라이맥스) |
+| `composite_swing` | 스윙 복합 | 복합 | 스윙 저점·고점 전담 기법 가중 투표 (B/S) |
+| `composite_pullback` | 눌림목 복합 | 복합 | 눌림목·역추세 기법 가중 투표 (B*) |
+| `composite_breakout` | 돌파 복합 | 복합 | 돌파·모멘텀 기법 가중 투표 (B^) |
+| `composite_divergence` | 다이버전스 복합 | 복합 | RSI/MACD/OBV 다이버전스 가중 투표 (Bd/Sd) |
+| `composite_v3` | v3 통합 스코어링 | 복합 | v3 GT 6종 신호 유형별 핵심 기법 가중 투표 + EMA(60) 추세 필터 |
+| `composite_full` | 전체 통합 복합 | 복합 | 전체 인과 기법 가중 투표 + EMA 추세 필터 |
+
+---
+
+## 디렉터리 구조
+
+```text
+DeepCoin/
+├── src/deepcoin/
+│   ├── data/               # 캔들 수집·로드
+│   ├── ground_truth/       # 0·1단계 GT·차트
+│   ├── techniques/         # 현물 2단계 인과 기법 (39종)
+│   ├── evaluation/         # 현물 2단계 GT 정합 평가
+│   └── mtf/                # 현물 2단계 MTF 분석
+├── scripts/                        # 접두사: 00=사전, 0=0단계, 1=현물1, 2=현물2
+│   ├── 00_download.py              # 사전 (증분/풀다운 래퍼)
+│   ├── 00_download_candles.py      # 사전 (캔들 수집 본체)
+│   ├── 0_ground_truth.py          # 0단계 현물 GT
+│   ├── 0_ground_truth_futures.py  # 0단계 선물 GT 차트
+│   ├── 1_ground_truth_sim.py      # 현물 1단계 sim
+│   ├── 2_run_techniques.py        # 현물 2단계
+│   ├── 2_run_signal_type_align.py
+│   └── 2_run_mtf_analysis.py
+├── coins.db                # 공유 캔들 DB (현물·선물 유일한 공유 리소스)
+├── data/
+│   ├── spot/               # 현물 전용
+│   │   ├── ground_truth/   # GT JSON v1~v3
+│   │   ├── techniques/     # 2단계 기법 실행 결과
+│   │   └── mtf/            # MTF 규칙
+│   └── futures/            # 선물 (0단계 GT만, 1~3단계 추후)
+│       └── ground_truth/
+├── docs/
+│   ├── 0_ground_truth/       # 0단계 (현물·선물 공통)
+│   │   ├── spot/
+│   │   └── futures/
+│   └── spot/               # 현물 1~2단계
+│       ├── 1_simulation/
+│       └── 2_analysis/
+```
+
+현물·선물은 `coins.db`만 공유합니다. 현재 구현 범위는 **0단계(공통) + 현물 1·2단계**이며, 선물 1~3단계·현물 3단계는 추후 구현 예정입니다.
+
+## 변경 이력
+
+- 2026-06-11: `docs/0_ground_truth/{spot,futures}/`로 0단계 차트를 docs 직하로 이동
+- 2026-06-11: `scripts/` 접두사를 파이프라인 단계와 일치 (`00_` 사전, `0_` 0단계, `1_` 현물1, `2_` 현물2)
+- 2026-06-11: README 파이프라인 단계별 상세 설명 추가 (0단계 공통 + 현물·선물 1~3단계)
+- 2026-06-11: README 파이프라인을 0단계(공통) + 현물·선물 각 1~3단계 체계로 정리
+- 2026-06-11: 선물 1~3단계·`04_run_causal_futures` 제거, 현물 0·1·2단계만 유지
+- 2026-06-11: `docs/spot/`·`docs/futures/` 상위 분리 (`data/`와 동일 구조)
+- 2026-06-11: `data/spot/`·`data/futures/` 완전 분리 (`coins.db`만 공유), 선물 GT·MTF·causal 독립 경로
+- 2026-06-11: 2단계 38종 기법 리포트 재생성, 3단계 causal/MTF/walkforward 재검증, README 39종 표 반영
+- 2026-06-11: 캔들 수집 기본 동작을 DB 최신 이후 증분 갱신으로 변경 (`--full`로 전체 재수집)
+- 2026-06-10: docs를 단계별 폴더(`0_ground_truth`~`3_causal`)로 재구성, 단계 정의 정렬 (0=GT 타점, 1=sim)
+- 2026-06-09: 파이프라인 번호를 0~4단계 체계로 통일 (0=벤치마크, 1=GT+기법, 2=인과분석, 3=시뮬, 4=실거래)
+- 2026-06-09: 3단계 인과 선물 전략 (composite_v3 + ATR) + 0단계 벤치마크 비교
+- 2026-06-09: v3 신호 유형별 GT 정합 리포트 + composite_v3 통합 기법
+- 2026-06-09: 선물 GT 차트 futures/gt/ 정리, 마커 UI 개선
+- 2026-06-08: Ground Truth v1/v2/v3 + 매매 기법 8종
+- 2026-06-07: 캔들 수집 모듈 초기 구현