refactor: GT·시뮬·운영 3축 정리 및 hybrid 실거래 정합

Phase C/dry-run·미사용 모듈·재생성 HTML을 제거하고, 운영 체결을 sim_causal_hybrid와 동일한 hybrid 로직으로 통합한다. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-03 23:50:28 +09:00
parent a16c942be4
commit d7848df6f7
85 changed files with 177180 additions and 196131 deletions
--- a/docs/reference/ARCHITECTURE.md
+++ b/docs/reference/ARCHITECTURE.md
@@ -0,0 +1,182 @@
+# DeepCoin 아키텍처 — Ground Truth · Simulation · Operations
+
+프로젝트는 **세 축만** 사용합니다. 예전 Phase A/B/C·dry-run·paper 모의 체결은 제거되었습니다.
+
+```mermaid
+flowchart TB
+    subgraph data [공통 데이터]
+        DL[01_download]
+        DB[(coins.db)]
+        DL --> DB
+    end
+
+    subgraph gt [Ground Truth]
+        GT02[02_ground_truth]
+        GT03[03 분석·프로필]
+        GT05[05_chart_truth]
+        DB --> GT02
+        GT02 --> GJSON[ground_truth_trades.json]
+        GT03 --> GJSON
+        GJSON --> GT05
+    end
+
+    subgraph sim [Simulation]
+        M04[04_match_rules]
+        S04[04_simulation_report]
+        GJSON --> M04
+        DB --> M04
+        M04 --> MR[matched_rules.json]
+        MR --> S04
+        S04 --> SR[simulation_report.*]
+    end
+
+    subgraph ops [Operations]
+        V06[06_verify_live]
+        E06[06_execute_live]
+        MR --> E06
+        SR --> V06
+        E06 --> BT[빗썸 API]
+    end
+```
+
+---
+
+## 1. Ground Truth (정답)
+
+### Plan — 목적
+
+- **벤치마크** 매수·매도 타점·leg·비중 (운영 목표 수익의 상한 참고).
+- **미래 데이터 허용**: ZigZag·피벗은 사후 라벨링 (`ground_truth.py`).
+- 시뮬·운영 규칙의 **교사 신호**가 아님 (oracle 직접 매매 금지).
+
+### Do — 실행
+
+| 순서 | 스크립트 | 산출 |
+|------|----------|------|
+| (선행) | `01_download.py` | `data/coins.db` (3m~일봉 + 주·월봉) |
+| 1 | `02_ground_truth.py` | `data/ground_truth/ground_truth_trades.json` |
+| 2 | `03_analyze_enrich.py` | `docs/03_analysis/latest/*` (10TF 지표) |
+| 3 | `03_analyze_trades.py` | `general_analysis_trades.csv` (GT 타점 스냅샷) |
+| 4 | `03_gt_mtf_profile.py` | `gt_mtf_profile.json` (규칙 후보 입력) |
+| 5 | `05_chart_truth.py` | `docs/02_ground_truth/wld_ground_truth_chart.html` |
+
+패키지: `deepcoin/ground_truth/`, `deepcoin/analysis/`
+
+### Check — 핵심 설정
+
+| 변수 | 의미 |
+|------|------|
+| `CHART_LOOKBACK_DAYS` | GT·스캔 구간 (기본 365) |
+| `GT_INITIAL_CASH_KRW` | GT 포트폴리오 시뮬 초기 자금 (40만) |
+| `GT_*` | ZigZag·분할 매수·leg 티어 |
+
+### Act — 갱신 시
+
+GT 파라미터·구간 변경 후 **02 → 03* → 05** 순 재실행.
+
+---
+
+## 2. Simulation (시뮬레이션)
+
+### Plan — 목적
+
+- GT 프로필에서 **규칙 후보** 생성 → 전 구간 **발화 스캔** → EV·holdout 검증.
+- **과거 데이터만** 사용 (`GT_SIGNAL_CAUSAL=1`, `enrich_scan_frame_gt_signals(causal=True)`).
+- 초기 자금 **40만 원**, **현금 있을 때만 매수**, **보유 있을 때만 매도** (`gt_allocation` / `HybridSimPortfolio`).
+
+### Do — 실행
+
+| 순서 | 스크립트 | 산출 |
+|------|----------|------|
+| 1 | `04_match_rules.py` | `matched_rules.json`, `fire_outcomes.csv` |
+| 2 | `04_simulation_report.py` | `simulation_report.json/html`, Go/No-Go |
+| (선택) | `04_hybrid_dd_calibrate.py` | `hybrid_dd_calibration.json` |
+| (선택) | `04_causal_gt_calibrate.py` | `causal_gt_calibration.json` |
+
+패키지: `deepcoin/matching/`
+
+### Check — 운영 규칙·배분
+
+| 항목 | 값 |
+|------|-----|
+| `monitor_rules` | `buy_compound_tight`, `sell_mtf_cross_all_tf` (주봉 w1 조건 포함 가능) |
+| **권장 primary** | `sim_causal_hybrid` (hybrid DD tier, `enhanced=False`) |
+| **배포 금지** | `sim_tier_enhanced` (conviction) |
+| Go/No-Go | holdout EV, MDD, fee stress — [SIMULATION.md](SIMULATION.md) |
+
+### Act — 재검증
+
+데이터·GT·`GENERAL_ANALYSIS_INTERVALS` 변경 시 **04_match → 04_simulation** 재실행.  
+운영 전 **simulation_report.html** 에서 hybrid Go/No-Go 확인.
+
+---
+
+## 3. Operations (운영)
+
+### Plan — 목적
+
+- 시뮬과 **동일 규칙·동일 hybrid 배분**으로 빗썸 **실주문**.
+- `LIVE_TRADING_ENABLED=1` **필수**. dry-run·paper 없음.
+
+### Do — 실행
+
+| 순서 | 스크립트 | 역할 |
+|------|----------|------|
+| (선행) | `00_sync_ops.py` | 운영 전 봉 동기화 |
+| 1 | `06_verify_live.py` | 설정·규칙·한도·tier 점검 |
+| 2 | `check_balance.py` | 빗썸 KRW·보유 확인 |
+| 3 | `06_execute_live.py` | 실거래 루프 (`--once` 1회 테스트) |
+| (선택) | `05_run_monitor.py` | 알림만 (주문 없음) |
+
+패키지: `deepcoin/ops/live_trader.py`, `hybrid_sim_execution.py`
+
+### Check — 제약 (시뮬과 동일)
+
+| 제약 | 구현 |
+|------|------|
+| 초기 자금 | `GT_INITIAL_CASH_KRW=400000` (배분 기준) |
+| 매수 | 가용 현금·수수료, `LIVE_DAILY_KRW_MAX`, EV/WF 통과 매수만 |
+| 매도 | 보유 수량, `plan_live_hit` → `sell_qty` |
+| 이력 | `LIVE_HYBRID_BOOTSTRAP_FIRES=1` → `fire_outcomes` monitor 발화 + 운영 체결분 |
+| 인과 | 발화 시점까지 OHLC·지표만 (`live_eval` + causal GT signals) |
+
+### Act — Kill switch
+
+1. `06_execute_live` 프로세스 중지  
+2. 빗썸 앱 수동 청산  
+3. 필요 시 `01`~`04` 재실행 후 규칙·시뮬 재승인  
+
+---
+
+## 스크립트 번호 ↔ 축 (빠른 참조)
+
+| 축 | 스크립트 |
+|----|----------|
+| **데이터** | `01_download`, `00_sync_ops` |
+| **GT** | `02`, `03_*`, `05_chart_truth` |
+| **Sim** | `04_match_rules`, `04_simulation_report`, `04_*_calibrate` |
+| **Ops** | `06_verify_live`, `06_execute_live`, `check_balance`, `05_run_monitor` |
+| **검증** | `verify_env.py`, `test_buy_sell_rehearsal.py` |
+
+---
+
+## 데이터·미래 사용 정책
+
+| 축 | 미래 데이터 |
+|----|-------------|
+| Ground Truth | **허용** (라벨링·벤치마크) |
+| Simulation | **금지** (발화·스캔·배분 tier는 과거 leg·DD만) |
+| Operations | **금지** (Simulation과 동일 규칙·엔진) |
+
+---
+
+## 관련 문서
+
+| 문서 | 내용 |
+|------|------|
+| [GROUND_TRUTH.md](GROUND_TRUTH.md) | GT 타점·배분 상세 |
+| [SIMULATION.md](SIMULATION.md) | Go/No-Go·portfolio_compare |
+| [LIVE_TRADING.md](LIVE_TRADING.md) | 06 실거래 |
+| [OPERATIONS.md](OPERATIONS.md) | 일상 루틴 |
+| [RISK.md](RISK.md) | 한도·Kill switch |
+| [DEPLOYMENT_CHECKLIST.md](../05_ops/DEPLOYMENT_CHECKLIST.md) | 기동 체크리스트 |