refactor: DeepCoin 1·2단계 파이프라인으로 구조 재편

레거시 분석·매칭·운영 코드를 정리하고 src/deepcoin 기반으로 재구성한다. 1단계 GT는 2년 스윙·눌림목·돌파·다이버전스 타점을 차트에 표시하고, 2단계는 8개 매매 기법과 GT 정합 평가 스크립트를 추가한다. .env와 GT JSON 산출물은 추적에서 제외한다. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-08 23:51:26 +09:00
parent 51f70076fb
commit df3c9aecb9
154 changed files with 4629 additions and 215122 deletions
--- a/README.md
+++ b/README.md
@@ -1,101 +1,119 @@
-# DeepCoin — WLD MTF · Ground Truth · Simulation · Operations
+# DeepCoin

-빗썸 KRW-WLD. 프로젝트는 **세 축**으로만 설계됩니다.
+빗썸 KRW 마켓 암호화폐 캔들 데이터 수집 프로젝트.

-| 축 | 역할 | 미래 데이터 |
-|----|------|-------------|
-| **Ground Truth** | 벤치마크 타점·leg·배분 | 허용 (사후 라벨) |
-| **Simulation** | 규칙·인과 백테스트·Go/No-Go | 금지 |
-| **Operations** | 시뮬과 동일 규칙·hybrid 배분 실주문 | 금지 |
+## 주요 기능

-설계 상세: [docs/reference/ARCHITECTURE.md](docs/reference/ARCHITECTURE.md)
+- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
+- SQLite(`coins.db`) 저장 — 테이블명 `{SYMBOL}_{인터벌코드}` (예: `BTC_60`, `BTC_10080`)
+- 최대 2년(기본 730일) 역방향 페이지네이션 수집

-## 파이프라인 (권장 순서)
+## 요구사항
+
+- Python 3.10+
+- Conda 환경 `ncue` 또는 `xavis`
+
+## 설치

 ```bash
-conda activate ncue   # 또는 xavis
-
-# 데이터
-python scripts/01_download.py
-
-# Ground Truth
-python scripts/02_ground_truth.py
-python scripts/03_analyze_enrich.py
-python scripts/03_analyze_trades.py
-python scripts/03_gt_mtf_profile.py
-python scripts/05_chart_truth.py
-
-# Simulation
-python scripts/04_match_rules.py
-python scripts/04_simulation_report.py
-
-# Operations (LIVE_TRADING_ENABLED=1)
-python scripts/06_verify_live.py
-python scripts/check_balance.py
-python scripts/06_execute_live.py --once
-python scripts/06_execute_live.py
+cd DeepCoin
+conda activate ncue
+pip install -r requirements.txt
+cp .env.example .env   # API 키 등 입력
 ```

-선택: `05_run_monitor.py` (알림만), `07_daily_pnl_telegram.py` (매일 24h 수익률), `00_sync_ops.py` (운영 전 봉 동기화)
+## 환경 변수

-## 디렉터리
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `SYMBOL` | 코인 심볼 | `BTC` |
+| `COIN_NAME` | 코인 이름 | `비트코인` |
+| `DB_PATH` | SQLite 경로 | `coins.db` |
+| `DOWNLOAD_DAYS` | 수집 일수 (최대 2년) | `730` |
+| `DOWNLOAD_INTERVALS` | 인터벌 코드 목록 | `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 키 없이도 동작합니다.
+
+## 5단계 파이프라인
+
+| 단계 | 목적 | 스크립트 |
+|------|------|----------|
+| 0 | 데이터 수집 | `01_download.py` |
+| 1 | Ground Truth (사후 벤치마크 타점) | `02_ground_truth.py` |
+| 2 | 매매 기법 개발·GT 정합 비교 | `03_run_techniques.py` |
+| 3 | 인과 신호 (과거 데이터만) | (예정) |
+| 4 | 시뮬레이션 백테스트 | (예정) |
+| 5 | 실거래 운영 | (예정) |
+
+```bash
+# 0. 데이터 수집
+python scripts/01_download.py
+
+# 1. Ground Truth (매수·매도 벤치마크 타점)
+python scripts/02_ground_truth.py
+
+# 2. 매매 기법 실행 및 GT 정합 비교
+python scripts/03_run_techniques.py
+```
+
+## 2단계 매매 기법 (8종)
+
+Ground Truth 타점에 맞출 수 있는 후보 기법. 모두 **인과 신호** (미래 데이터 미사용).
+
+| ID | 기법 | 유형 | 설명 |
+|----|------|------|------|
+| `zigzag_causal` | 인과 ZigZag | swing | GT ZigZag 5%의 인과 버전 |
+| `minor_swing` | 소형 스윙 하이브리드 | hybrid | ZigZag 2.5% + 국소 극값 |
+| `local_extrema` | 국소 극값 | swing | 눌림목·반등 고점 (9/27 유형) |
+| `bb_reversal` | 볼린저 역추세 | indicator | BB 하단 매수·상단 매도 |
+| `ma_cross` | EMA 크로스 | indicator | EMA(20/60) 골든·데드 크로스 |
+| `rsi_swing` | RSI 스윙 | indicator | RSI 과매도·과매수 복귀 |
+| `macd_cross` | MACD 크로스 | indicator | MACD 시그널선 크로스 |
+| `donchian` | 돈치안 채널 | swing | 채널 하단·상단 반전 |
+
+GT 정합 평가: 매수/매도 recall, 레그 recall, 수익 포착률, 종합 score.
+
+## 실행 (데이터 수집)
+
+```bash
+# 전체 인터벌, 최대 2년
+python scripts/download_candles.py
+
+# 일·주·월봉만 빠르게
+python scripts/download_candles.py --intervals 1440,10080,43200
+
+# 최근 90일, 60분봉만
+python scripts/download_candles.py --days 90 --intervals 60
+```
+
+## 디렉터리 구조

 ```text
 DeepCoin/
-├── scripts/              # CLI 진입점 (GT / Sim / Ops)
-├── deepcoin/
-│   ├── data/             # 01
-│   ├── ground_truth/     # GT
-│   ├── analysis/         # GT 입력 (03)
-│   ├── matching/         # Sim (04)
-│   └── ops/              # Ops (05·06)
-├── data/                 # coins.db, ground_truth/, ops/
-└── docs/
-    ├── reference/        # ARCHITECTURE, SIMULATION, OPERATIONS …
-    └── 02~05/              # 재생성 산출물
+├── src/deepcoin/
+│   ├── api/bithumb.py
+│   ├── data/
+│   ├── ground_truth/       # 1단계
+│   ├── techniques/         # 2단계 매매 기법
+│   └── evaluation/         # GT 정합 평가
+├── scripts/
+│   ├── 01_download.py
+│   ├── 02_ground_truth.py
+│   └── 03_run_techniques.py
+├── data/ground_truth/
+├── data/techniques/
+├── docs/02_ground_truth/
+├── docs/03_analysis/
+└── coins.db
 ```

-## 환경
+## 변경 이력

-| 파일 | 용도 |
-|------|------|
-| `.env` | API 키·전역 설정 (Git 제외) |
-| `config.py` | `.env` 로드 |
-
-`scripts/_bootstrap.py`가 루트 `.env`를 자동 로드합니다.
-
-### 주요 변수
-
-| 변수 | 기본 | 축 |
-|------|------|-----|
-| `CHART_LOOKBACK_DAYS` | 365 | GT·Sim |
-| `GT_INITIAL_CASH_KRW` | 400000 | GT·Sim·Ops 배분 |
-| `GENERAL_ANALYSIS_INTERVALS` | 3m~일봉+주·월 | Sim 스캔 |
-| `GT_SIGNAL_CAUSAL` | 1 | Sim·Ops (인과) |
-| `LIVE_TRADING_ENABLED` | 1 | Ops (`0`이면 06 기동 불가) |
-
-전체: `.env.example`, [docs/05_ops/env.recommended.md](docs/05_ops/env.recommended.md)
-
-## 산출물
-
-| 경로 | 축 |
-|------|-----|
-| `data/ground_truth/ground_truth_trades.json` | GT |
-| `docs/02_ground_truth/wld_ground_truth_chart.html` | GT 차트 (`05_chart_truth.py` 재생성) |
-| `docs/04_matching/matched_rules.json` | Sim |
-| `docs/04_matching/simulation_report.html` | Sim |
-| `data/ops/live_trades.jsonl` | Ops |
-
-## 문서
-
-| 문서 | 내용 |
-|------|------|
-| [ARCHITECTURE.md](docs/reference/ARCHITECTURE.md) | 3축 설계 (필독) |
-| [GROUND_TRUTH.md](docs/reference/GROUND_TRUTH.md) | GT 타점 |
-| [SIMULATION.md](docs/reference/SIMULATION.md) | 시뮬·Go/No-Go |
-| [OPERATIONS.md](docs/reference/OPERATIONS.md) | 운영 루틴 |
-| [LIVE_TRADING.md](docs/reference/LIVE_TRADING.md) | 06 실거래 |
-
-## 면책
-
-실거래 손익은 사용자 책임입니다. 본 저장소는 투자 자문이 아닙니다.
+- 2026-06-08: 2단계 매매 기법 8종 + GT 정합 비교 리포트 추가
+- 2026-06-08: 1단계 Ground Truth (ZigZag 스윙 매수·매도 타점) 추가
+- 2026-06-07: BTC 최대 2년 분·일·주·월봉 수집 지원
+- 2026-06-07: 캔들 수집 모듈 초기 구현