# 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) | 기동 체크리스트 |