feat: enhance precision optimization in model training

- Introduced a new plan to modify the Optuna objective function to prioritize precision under a recall constraint of 0.35, improving model performance in scenarios where false positives are costly.
- Updated training scripts to implement precision-based metrics and adjusted the walk-forward cross-validation process to incorporate precision and recall calculations.
- Enhanced the active LGBM parameters and training log to reflect the new metrics and model configurations.
- Added a new design document outlining the implementation steps for the precision-focused optimization.

This update aims to refine the model's decision-making process by emphasizing precision, thereby reducing potential losses from false positives.

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

.gitignore

@@ -7,4 +7,9 @@ logs/
 .venv/
 venv/
 models/*.pkl
+models/*.onnx
+models/tune_results_*.json
 data/*.parquet
+.worktrees/
+.DS_Store
+.cursor/

ARCHITECTURE.md

@@ -0,0 +1,646 @@
+# CoinTrader — 아키텍처 문서
+
+> 이 문서는 CoinTrader 코드베이스를 처음 접하는 개발자와 트레이딩 배경 독자 모두를 위해 작성되었습니다.  
+> 기술 스택, 레이어별 역할, MLOps 파이프라인, 핵심 동작 시나리오를 순서대로 설명합니다.
+
+---
+
+## 목차
+
+1. [시스템 오버뷰](#1-시스템-오버뷰)
+2. [코어 레이어 아키텍처](#2-코어-레이어-아키텍처)
+3. [MLOps 파이프라인 — 자가 진화 시스템](#3-mlops-파이프라인--자가-진화-시스템)
+4. [핵심 동작 시나리오](#4-핵심-동작-시나리오)
+5. [테스트 커버리지](#5-테스트-커버리지)
+
+---
+
+## 1. 시스템 오버뷰
+
+CoinTrader는 **Binance Futures 자동매매 봇**입니다. 기술 지표 신호를 1차 필터로, LightGBM(또는 MLX 신경망) 모델을 2차 필터로 사용하여 XRPUSDT 선물 포지션을 자동 진입·청산합니다.
+
+### 전체 데이터 파이프라인 흐름도
+
+```mermaid
+flowchart TD
+    subgraph 외부["외부 데이터 소스 (Binance)"]
+        WS1["Combined WebSocket<br/>XRP/BTC/ETH 15분봉 캔들"]
+        WS2["User Data Stream WebSocket<br/>ORDER_TRADE_UPDATE 이벤트"]
+        REST["REST API<br/>OI·펀딩비·잔고·포지션 조회"]
+    end
+
+    subgraph 실시간봇["실시간 봇 (bot.py — asyncio)"]
+        DS["data_stream.py<br/>MultiSymbolStream<br/>캔들 버퍼 (deque 200개)"]
+        IND["indicators.py<br/>기술 지표 계산<br/>RSI·MACD·BB·EMA·StochRSI·ATR·ADX"]
+        MF["ml_features.py<br/>23개 피처 추출<br/>(XRP 13 + BTC/ETH 8 + OI/FR 2)"]
+        ML["ml_filter.py<br/>MLFilter<br/>ONNX 우선 / LightGBM 폴백<br/>확률 ≥ 0.60 시 진입 허용"]
+        RM["risk_manager.py<br/>RiskManager<br/>일일 손실 5% 한도<br/>동적 증거금 비율"]
+        EX["exchange.py<br/>BinanceFuturesClient<br/>주문·레버리지·잔고 API"]
+        UDS["user_data_stream.py<br/>UserDataStream<br/>TP/SL 즉시 감지"]
+        NT["notifier.py<br/>DiscordNotifier<br/>진입·청산·오류 알림"]
+    end
+
+    subgraph mlops["MLOps 파이프라인 (맥미니 — 수동/크론)"]
+        FH["fetch_history.py<br/>과거 캔들 + OI/펀딩비<br/>Parquet Upsert"]
+        DB["dataset_builder.py<br/>벡터화 데이터셋 생성<br/>레이블: ATR SL/TP 6시간 룩어헤드"]
+        TM["train_model.py<br/>LightGBM 학습<br/>Walk-Forward 5폴드 검증"]
+        TN["tune_hyperparams.py<br/>Optuna 50 trials<br/>TPE + MedianPruner"]
+        AP["active_lgbm_params.json<br/>Active Config 패턴<br/>승인된 파라미터 저장"]
+        DM["deploy_model.sh<br/>rsync → LXC 서버<br/>봇 핫리로드 트리거"]
+    end
+
+    WS1 -->|캔들 마감 이벤트| DS
+    WS2 -->|체결 이벤트| UDS
+    REST -->|OI·펀딩비| MF
+    DS -->|DataFrame| IND
+    IND -->|신호 + 지표값| MF
+    MF -->|피처 Series| ML
+    ML -->|진입 허용/차단| RM
+    RM -->|주문 승인| EX
+    EX -->|체결 결과| NT
+    UDS -->|net_pnl·청산 사유| NT
+    UDS -->|상태 초기화| DS
+
+    FH -->|combined_15m.parquet| DB
+    DB -->|X, y, w| TM
+    TM -->|lgbm_filter.pkl| DM
+    TN -->|Best Params| AP
+    AP -->|파라미터 반영| TM
+    DM -->|모델 파일 전송| ML
+```
+
+### 기술 스택 요약
+
+| 분류 | 기술 |
+|------|------|
+| 언어 | Python 3.11+ |
+| 비동기 런타임 | `asyncio` + `python-binance` WebSocket |
+| 기술 지표 | `pandas-ta` (RSI, MACD, BB, EMA, StochRSI, ATR) |
+| ML 프레임워크 | `LightGBM` (CPU) / `MLX` (Apple Silicon GPU) |
+| 모델 서빙 | `onnxruntime` (ONNX 우선) / `joblib` (LightGBM 폴백) |
+| 하이퍼파라미터 탐색 | `Optuna` (TPE Sampler + MedianPruner) |
+| 데이터 저장 | `Parquet` (pyarrow) |
+| 로깅 | `Loguru` |
+| 알림 | Discord Webhook (`httpx`) |
+| 컨테이너화 | Docker + Docker Compose |
+| CI/CD | Jenkins + Gitea Container Registry |
+| 운영 서버 | LXC 컨테이너 (`10.1.10.24`) |
+
+---
+
+## 2. 코어 레이어 아키텍처
+
+봇은 5개의 레이어로 구성됩니다. 각 레이어는 단일 책임을 가지며, 위에서 아래로 데이터가 흐릅니다.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Layer 1: Data Layer         data_stream.py          │
+│           캔들 수신 · 버퍼 관리 · 과거 데이터 프리로드  │
+├─────────────────────────────────────────────────────┤
+│  Layer 2: Signal Layer       indicators.py           │
+│           기술 지표 계산 · 복합 신호 생성              │
+├─────────────────────────────────────────────────────┤
+│  Layer 3: ML Filter Layer    ml_filter.py            │
+│           LightGBM/ONNX 확률 예측 · 진입 차단         │
+├─────────────────────────────────────────────────────┤
+│  Layer 4: Execution & Risk   exchange.py             │
+│           Layer              risk_manager.py         │
+│           주문 실행 · 포지션 관리 · 리스크 제어         │
+├─────────────────────────────────────────────────────┤
+│  Layer 5: Event / Alert      user_data_stream.py     │
+│           Layer              notifier.py             │
+│           TP/SL 즉시 감지 · Discord 알림              │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+### Layer 1: Data Layer
+
+**파일:** `src/data_stream.py`
+
+봇이 시작되면 가장 먼저 실행되는 레이어입니다. Binance Combined WebSocket 단일 연결로 XRP·BTC·ETH 3개 심볼의 15분봉 캔들을 동시에 수신합니다.
+
+**핵심 동작:**
+
+1. **프리로드**: 봇 시작 시 REST API로 과거 캔들 200개를 `deque`에 즉시 채웁니다. EMA50 안정화에 필요한 최소 캔들(100개)을 확보하여 첫 캔들부터 신호를 계산할 수 있게 합니다.
+2. **버퍼 관리**: 심볼별 `deque(maxlen=200)`에 마감된 캔들만 추가합니다. 미마감 캔들(`is_closed=False`)은 무시합니다.
+3. **콜백 트리거**: XRP(주 심볼) 캔들이 마감되면 `bot._on_candle_closed()`를 호출합니다. BTC·ETH는 버퍼에만 쌓이고 콜백을 트리거하지 않습니다.
+
+```
+Combined WebSocket
+  ├── xrpusdt@kline_15m  →  buffers["xrpusdt"]  →  on_candle() 호출
+  ├── btcusdt@kline_15m  →  buffers["btcusdt"]  (콜백 없음)
+  └── ethusdt@kline_15m  →  buffers["ethusdt"]  (콜백 없음)
+```
+
+---
+
+### Layer 2: Signal Layer
+
+**파일:** `src/indicators.py`
+
+`pandas-ta` 라이브러리로 기술 지표를 계산하고, 복합 가중치 시스템으로 매매 신호를 생성합니다.
+
+**계산되는 지표:**
+
+| 지표 | 파라미터 | 역할 |
+|------|---------|------|
+| RSI | length=14 | 과매수/과매도 판단 |
+| MACD | (12, 26, 9) | 추세 전환 감지 (골든/데드크로스) |
+| 볼린저 밴드 | (20, 2σ) | 가격 이탈 감지 |
+| EMA | (9, 21, 50) | 추세 방향 (정배열/역배열) |
+| Stochastic RSI | (14, 14, 3, 3) | 단기 과매수/과매도 |
+| ATR | length=14 | 변동성 측정 → SL/TP 계산에 사용 |
+| ADX | length=14 | 추세 강도 측정 → 횡보장 필터 (ADX < 25 시 진입 차단) |
+| Volume MA | length=20 | 거래량 급증 감지 |
+
+**신호 생성 로직 (ADX 필터 + 가중치 합산):**
+
+```
+[1단계] ADX 횡보장 필터:
+  ADX < 25 → 즉시 HOLD 반환 (추세 부재로 진입 차단)
+
+[2단계] 롱 신호 점수:
+  RSI < 35                          → +1
+  MACD 골든크로스 (전봉→현봉)          → +2  ← 강한 신호
+  종가 < 볼린저 하단                  → +1
+  EMA 정배열 (9 > 21 > 50)           → +1
+  StochRSI K < 20 and K > D         → +1
+
+진입 조건: 점수 ≥ 3 AND (거래량 급증 OR 점수 ≥ 4)
+SL = 진입가 - ATR × 1.5
+TP = 진입가 + ATR × 3.0  (리스크:리워드 = 1:2)
+```
+
+숏 신호는 롱의 대칭 조건으로 계산됩니다.
+
+---
+
+### Layer 3: ML Filter Layer
+
+**파일:** `src/ml_filter.py`, `src/ml_features.py`
+
+기술 지표 신호가 발생해도 ML 모델이 "이 타점은 실패 확률이 높다"고 판단하면 진입을 차단합니다. 오진입(억까 타점)을 줄이는 2차 게이트키퍼입니다.
+
+**모델 우선순위:**
+
+```
+ONNX (MLX 신경망)  →  LightGBM  →  폴백(항상 허용)
+```
+
+모델 파일이 없으면 모든 신호를 허용합니다. 봇 재시작 없이 모델 파일을 교체하면 다음 캔들 마감 시 자동으로 핫리로드됩니다(`mtime` 감지).
+
+**23개 ML 피처:**
+
+```
+XRP 기술 지표 (13개):
+  rsi, macd_hist, bb_pct, ema_align, stoch_k, stoch_d,
+  atr_pct, vol_ratio, ret_1, ret_3, ret_5,
+  signal_strength, side
+
+BTC/ETH 상관관계 (8개):
+  btc_ret_1, btc_ret_3, btc_ret_5,
+  eth_ret_1, eth_ret_3, eth_ret_5,
+  xrp_btc_rs, xrp_eth_rs
+
+시장 미시구조 (2개):
+  oi_change    ← 이전 캔들 대비 미결제약정 변화율
+  funding_rate ← 현재 펀딩비
+```
+
+`oi_change`와 `funding_rate`는 캔들 마감마다 Binance REST API로 실시간 조회합니다. API 실패 시 `0.0`으로 폴백하여 봇이 멈추지 않습니다.
+
+**진입 판단:**
+
+```python
+proba = model.predict_proba(features)[0][1]  # 성공 확률
+return proba >= 0.60  # 임계값 60%
+```
+
+---
+
+### Layer 4: Execution & Risk Layer
+
+**파일:** `src/exchange.py`, `src/risk_manager.py`
+
+ML 필터를 통과한 신호를 실제 주문으로 변환하고, 리스크 한도를 관리합니다.
+
+**포지션 크기 계산 (동적 증거금 비율):**
+
+잔고가 늘어날수록 증거금 비율을 선형으로 줄여 복리 과노출을 방지합니다.
+
+```
+증거금 비율 = max(20%, min(50%, 50% - (잔고 - 기준잔고) × 0.0006))
+명목금액 = 잔고 × 증거금 비율 × 레버리지
+수량 = 명목금액 / 현재가
+```
+
+**주문 흐름:**
+
+```
+1. set_leverage(10x)
+2. place_order(MARKET)          ← 진입
+3. place_order(STOP_MARKET)     ← SL 설정
+4. place_order(TAKE_PROFIT_MARKET) ← TP 설정
+```
+
+SL/TP 주문은 `/fapi/v1/algoOrder` 엔드포인트로 전송됩니다 (일반 계정의 `-4120` 오류 대응).
+
+**리스크 제어:**
+
+| 제어 항목 | 기준 |
+|----------|------|
+| 일일 최대 손실 | 기준 잔고의 5% |
+| 최대 동시 포지션 | 3개 |
+| 최소 명목금액 | $5 USDT |
+
+**반대 시그널 재진입:** 보유 포지션과 반대 방향 신호 발생 시 기존 포지션을 즉시 청산하고, ML 필터 통과 시 반대 방향으로 재진입합니다. 재진입 중 User Data Stream 콜백이 신규 포지션 상태를 덮어쓰지 않도록 `_is_reentering` 플래그로 보호합니다.
+
+---
+
+### Layer 5: Event / Alert Layer
+
+**파일:** `src/user_data_stream.py`, `src/notifier.py`
+
+기존 폴링 방식(캔들 마감마다 포지션 조회)의 한계를 극복하기 위해 도입된 레이어입니다.
+
+**User Data Stream의 역할:**
+
+Binance `ORDER_TRADE_UPDATE` 웹소켓 이벤트를 구독하여 TP/SL 체결을 **즉시** 감지합니다. 기존 방식은 최대 15분 지연이 발생했지만, 이제 체결 즉시 콜백이 호출됩니다.
+
+```
+이벤트 필터링 조건:
+  e == "ORDER_TRADE_UPDATE"
+  AND s == "XRPUSDT"          ← 심볼 필터
+  AND x == "TRADE"            ← 실제 체결
+  AND X == "FILLED"           ← 완전 체결
+  AND (reduceOnly OR order_type in {STOP_MARKET, TAKE_PROFIT_MARKET} OR rp != 0)
+```
+
+청산 사유 분류:
+- `TAKE_PROFIT_MARKET` → `"TP"`
+- `STOP_MARKET` → `"SL"`
+- 그 외 → `"MANUAL"`
+
+순수익 계산:
+```
+net_pnl = realized_pnl - commission
+```
+
+**Discord 알림 포맷:**
+
+진입 시:
+```
+[XRPUSDT] LONG 진입
+진입가: 2.3450 | 수량: 100.0 | 레버리지: 10x
+SL: 2.3100 | TP: 2.4150
+RSI: 32.50 | MACD Hist: -0.000123 | ATR: 0.023400
+```
+
+청산 시:
+```
+✅ [XRPUSDT] LONG TP 청산
+청산가:               2.4150
+예상 수익:            +7.0000 USDT
+실제 순수익:          +6.7800 USDT
+차이(슬리피지+수수료): -0.2200 USDT
+```
+
+---
+
+## 3. MLOps 파이프라인 — 자가 진화 시스템
+
+봇의 ML 모델은 고정된 것이 아니라 주기적으로 재학습·개선됩니다. 전체 라이프사이클은 다음과 같습니다.
+
+### 3.1 전체 라이프사이클
+
+```mermaid
+flowchart LR
+    A["주말 수동 트리거<br/>tune_hyperparams.py<br/>(Optuna 50 trials, ~30분)"]
+    B["결과 검토<br/>tune_results_YYYYMMDD.json<br/>Best AUC vs Baseline 비교"]
+    C{"개선폭 충분?<br/>(AUC +0.01 이상<br/>폴드 분산 낮음)"}
+    D["active_lgbm_params.json<br/>업데이트<br/>(Active Config 패턴)"]
+    E["새벽 2시 크론탭<br/>train_and_deploy.sh<br/>(데이터 수집 → 학습 → 배포)"]
+    F["LXC 서버<br/>lgbm_filter.pkl 교체"]
+    G["봇 핫리로드<br/>다음 캔들 mtime 감지<br/>→ 자동 리로드"]
+
+    A --> B
+    B --> C
+    C -->|Yes| D
+    C -->|No| A
+    D --> E
+    E --> F
+    F --> G
+    G --> A
+```
+
+### 3.2 단계별 상세 설명
+
+#### Step 1: Optuna 하이퍼파라미터 탐색
+
+`scripts/tune_hyperparams.py`는 LightGBM의 9개 하이퍼파라미터를 자동으로 탐색합니다.
+
+- **알고리즘**: TPE Sampler (Tree-structured Parzen Estimator) — 베이지안 최적화 계열
+- **조기 종료**: MedianPruner — 중간 폴드 AUC가 중앙값 미만이면 trial 조기 종료
+- **평가 지표**: Walk-Forward 5폴드 평균 AUC (시계열 순서 유지, 미래 데이터 누수 방지)
+- **클래스 불균형 처리**: 언더샘플링 (양성:음성 = 1:1, 시간 순서 유지)
+
+탐색 공간:
+
+```
+n_estimators:      100 ~ 600
+learning_rate:     0.01 ~ 0.20  (log scale)
+max_depth:         2 ~ 7
+num_leaves:        7 ~ min(31, 2^max_depth - 1)  ← 과적합 방지 제약
+min_child_samples: 10 ~ 50
+subsample:         0.5 ~ 1.0
+colsample_bytree:  0.5 ~ 1.0
+reg_alpha:         1e-4 ~ 1.0   (log scale)
+reg_lambda:        1e-4 ~ 1.0   (log scale)
+```
+
+결과는 `models/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다.
+
+#### Step 2: Active Config 패턴으로 파라미터 승인
+
+Optuna가 찾은 파라미터는 **자동으로 적용되지 않습니다.** 사람이 결과를 검토하고 직접 `models/active_lgbm_params.json`을 업데이트해야 합니다.
+
+```json
+{
+  "promoted_at": "2026-03-02T14:47:49",
+  "best_trial": {
+    "number": 23,
+    "value": 0.6821,
+    "params": {
+      "n_estimators": 434,
+      "learning_rate": 0.123659,
+      ...
+    }
+  }
+}
+```
+
+`train_model.py`는 학습 시작 시 이 파일을 읽어 파라미터를 적용합니다. 파일이 없으면 코드 내 기본값을 사용합니다.
+
+> **주의**: Optuna 결과는 과적합 위험이 있습니다. 폴드별 AUC 분산이 크거나 (std > 0.05), 개선폭이 미미하면 (< 0.01) 적용하지 않는 것을 권장합니다.
+
+#### Step 3: 자동 학습 및 배포 (크론탭)
+
+`scripts/train_and_deploy.sh`는 3단계를 자동으로 실행합니다:
+
+```
+[1/3] 데이터 수집 (fetch_history.py)
+  - 기존 parquet 없음 → 1년치(365일) 전체 수집
+  - 기존 parquet 있음 → 35일치 Upsert (OI/펀딩비 0.0 구간 보충)
+
+[2/3] 모델 학습 (train_model.py)
+  - active_lgbm_params.json 파라미터 로드
+  - 벡터화 데이터셋 생성 (dataset_builder.py)
+  - Walk-Forward 5폴드 검증 후 최종 모델 저장
+  - 학습 로그: models/training_log.json
+
+[3/3] LXC 배포 (deploy_model.sh)
+  - rsync로 lgbm_filter.pkl → LXC 서버 전송
+  - 기존 모델 자동 백업 (lgbm_filter_prev.pkl)
+  - ONNX 파일 충돌 방지 (우선순위 보장)
+```
+
+#### Step 4: 봇 핫리로드
+
+모델 파일이 교체되면 봇 재시작 없이 자동으로 새 모델이 적용됩니다.
+
+```python
+# bot.py → process_candle() 첫 줄
+self.ml_filter.check_and_reload()
+
+# ml_filter.py → check_and_reload()
+onnx_changed = _mtime(self._onnx_path) != self._loaded_onnx_mtime
+lgbm_changed = _mtime(self._lgbm_path) != self._loaded_lgbm_mtime
+if onnx_changed or lgbm_changed:
+    self._try_load()  # 새 모델 로드
+```
+
+매 캔들 마감(15분)마다 모델 파일의 `mtime`을 확인합니다. 변경이 감지되면 즉시 리로드합니다.
+
+### 3.3 레이블 생성 방식
+
+학습 데이터의 레이블은 **미래 6시간(24캔들) 룩어헤드**로 생성됩니다.
+
+```
+신호 발생 시점 기준:
+  SL = 진입가 - ATR × 1.5
+  TP = 진입가 + ATR × 3.0
+
+향후 24캔들 동안:
+  - 저가가 SL에 먼저 닿으면 → label = 0 (실패)
+  - 고가가 TP에 먼저 닿으면 → label = 1 (성공)
+  - 둘 다 안 닿으면 → 샘플 제외
+```
+
+보수적 접근: SL 체크를 TP보다 먼저 수행하여 동시 돌파 시 실패로 처리합니다.
+
+---
+
+## 4. 핵심 동작 시나리오
+
+### 시나리오 1: 15분 캔들 마감 시 봇의 동작 흐름
+
+> "XRP 15분봉이 마감되면 봇은 무엇을 하는가?"
+
+```mermaid
+sequenceDiagram
+    participant WS as Binance WebSocket
+    participant DS as data_stream.py
+    participant BOT as bot.py
+    participant IND as indicators.py
+    participant MF as ml_features.py
+    participant ML as ml_filter.py
+    participant RM as risk_manager.py
+    participant EX as exchange.py
+    participant NT as notifier.py
+
+    WS->>DS: kline 이벤트 (is_closed=True)
+    DS->>DS: buffers["xrpusdt"].append(candle)
+    DS->>BOT: on_candle_closed(candle) 콜백
+
+    BOT->>BOT: ml_filter.check_and_reload() [mtime 확인]
+    BOT->>EX: get_open_interest() + get_funding_rate() [병렬]
+    BOT->>RM: is_trading_allowed() [일일 손실 한도 확인]
+
+    BOT->>IND: calculate_all(xrp_df) [지표 계산]
+    IND-->>BOT: df_with_indicators (RSI, MACD, BB, EMA, StochRSI, ATR, ADX)
+    BOT->>IND: get_signal(df) [신호 생성]
+    IND-->>BOT: "LONG" | "SHORT" | "HOLD"
+
+    alt 신호 = LONG 또는 SHORT, 포지션 없음
+        BOT->>MF: build_features(df, signal, btc_df, eth_df, oi_change, funding_rate)
+        MF-->>BOT: features (23개 피처 Series)
+        BOT->>ML: should_enter(features)
+        ML-->>BOT: proba=0.73 ≥ 0.60 → True
+
+        BOT->>EX: get_balance()
+        BOT->>RM: get_dynamic_margin_ratio(balance)
+        BOT->>EX: set_leverage(10)
+        BOT->>EX: place_order(MARKET, BUY, qty=100.0)
+        BOT->>EX: place_order(STOP_MARKET, SELL, stop=2.3100)
+        BOT->>EX: place_order(TAKE_PROFIT_MARKET, SELL, stop=2.4150)
+        BOT->>NT: notify_open(진입가, SL, TP, RSI, MACD, ATR)
+
+    else 신호 = HOLD 또는 ML 차단
+        BOT->>BOT: 대기 (다음 캔들까지)
+    end
+```
+
+**핵심 포인트:**
+- OI·펀딩비 조회는 `asyncio.gather()`로 병렬 실행 → 지연 최소화
+- ML 필터가 없으면(모델 파일 없음) 모든 신호를 허용
+- 명목금액 < $5 USDT이면 주문을 건너뜀 (바이낸스 최소 주문 제약)
+
+---
+
+### 시나리오 2: TP/SL 체결 시 봇의 동작 흐름
+
+> "거래소에서 TP가 작동하면 봇은 어떻게 반응하는가?"
+
+```mermaid
+sequenceDiagram
+    participant BN as Binance
+    participant UDS as user_data_stream.py
+    participant BOT as bot.py
+    participant RM as risk_manager.py
+    participant NT as notifier.py
+
+    BN->>UDS: ORDER_TRADE_UPDATE 이벤트
+    Note over UDS: e="ORDER_TRADE_UPDATE"<br/>s="XRPUSDT"<br/>x="TRADE", X="FILLED"<br/>o="TAKE_PROFIT_MARKET"<br/>rp="+7.0000", n="0.2200"
+
+    UDS->>UDS: 심볼 필터 (XRPUSDT만 처리)
+    UDS->>UDS: 청산 주문 판별 (reduceOnly or TP/SL type)
+    UDS->>UDS: net_pnl = 7.0000 - 0.2200 = 6.7800
+    UDS->>UDS: close_reason = "TP"
+
+    UDS->>BOT: _on_position_closed(net_pnl=6.78, reason="TP", exit_price=2.4150)
+
+    BOT->>BOT: estimated_pnl = (2.4150 - 2.3450) × 100 = 7.0000
+    BOT->>BOT: diff = 6.7800 - 7.0000 = -0.2200
+
+    BOT->>RM: record_pnl(6.7800) [일일 누적 PnL 갱신]
+
+    BOT->>NT: notify_close(TP, exit=2.4150, est=+7.00, net=+6.78, diff=-0.22)
+    NT->>NT: Discord 웹훅 전송
+
+    BOT->>BOT: current_trade_side = None
+    BOT->>BOT: _entry_price = None
+    BOT->>BOT: _entry_quantity = None
+    Note over BOT: Flat 상태로 초기화 완료
+```
+
+**핵심 포인트:**
+- User Data Stream은 `asyncio.gather()`로 캔들 스트림과 **병렬** 실행
+- 체결 즉시 감지 (최대 15분 지연이었던 폴링 방식 대비 실시간)
+- `realized_pnl - commission` = 정확한 순수익 (슬리피지·수수료 포함)
+- `_is_reentering` 플래그: 반대 시그널 재진입 중에는 콜백이 신규 포지션 상태를 초기화하지 않음
+
+---
+
+## 5. 테스트 커버리지
+
+### 5.1 테스트 파일 구성
+
+`tests/` 폴더에 12개 테스트 파일, 총 **81개의 테스트 케이스**가 작성되어 있습니다.
+
+```bash
+pytest tests/ -v          # 전체 실행
+bash scripts/run_tests.sh  # 래퍼 스크립트 실행
+```
+
+### 5.2 모듈별 테스트 현황
+
+| 테스트 파일 | 대상 모듈 | 테스트 케이스 | 주요 검증 항목 |
+|------------|----------|:------------:|--------------|
+| `test_bot.py` | `src/bot.py` | 11 | 반대 시그널 재진입 흐름, ML 차단 시 재진입 스킵, OI/펀딩비 피처 전달, OI 변화율 계산 |
+| `test_indicators.py` | `src/indicators.py` | 7 | RSI 범위(0~100), MACD 컬럼 존재, 볼린저 밴드 상하단 대소관계, 신호 반환값 유효성, ADX 컬럼 존재, ADX<25 횡보장 차단, ADX NaN 폴스루 |
+| `test_ml_features.py` | `src/ml_features.py` | 11 | 23개 피처 수, BTC/ETH 포함 시 피처 수, RS 분모 0 처리, NaN 없음, side 인코딩, OI/펀딩비 파라미터 반영 |
+| `test_ml_filter.py` | `src/ml_filter.py` | 5 | 모델 없을 때 폴백 허용, 임계값 이상/미만 판단, 핫리로드 후 상태 변화 |
+| `test_risk_manager.py` | `src/risk_manager.py` | 8 | 일일 손실 한도 초과 차단, 최대 포지션 수 제한, 동적 증거금 비율 상한/하한 클램핑 |
+| `test_exchange.py` | `src/exchange.py` | 8 | 수량 계산(기본/최소명목금액/잔고0), OI·펀딩비 조회 정상/오류 시 반환값 |
+| `test_data_stream.py` | `src/data_stream.py` | 6 | 3심볼 버퍼 존재, 빈 버퍼 None 반환, 캔들 파싱, 마감 캔들 콜백 호출, 프리로드 200개 |
+| `test_label_builder.py` | `src/label_builder.py` | 4 | LONG TP 도달 → 1, LONG SL 도달 → 0, 미결 → None, SHORT TP 도달 → 1 |
+| `test_dataset_builder.py` | `src/dataset_builder.py` | 9 | DataFrame 반환, 필수 컬럼 존재, 레이블 이진값, BTC/ETH 포함 시 23개 피처, inf/NaN 없음, OI nan 마스킹, RS 분모 0 처리 |
+| `test_mlx_filter.py` | `src/mlx_filter.py` | 5 | GPU 디바이스 확인, 학습 전 예측 형태, 학습 후 유효 확률, NaN 피처 처리, 저장/로드 후 동일 예측 |
+| `test_fetch_history.py` | `scripts/fetch_history.py` | 5 | OI=0 구간 Upsert, 신규 행 추가, 기존 비0값 보존, 파일 없을 때 신규 반환, 타임스탬프 오름차순 정렬 |
+| `test_config.py` | `src/config.py` | 2 | 환경변수 로드, 동적 증거금 파라미터 로드 |
+
+> `test_mlx_filter.py`는 Apple Silicon(`mlx` 패키지)이 없는 환경에서 자동 스킵됩니다.
+
+### 5.3 커버리지 매트릭스
+
+아래는 핵심 비즈니스 로직의 테스트 커버 여부입니다.
+
+| 기능 | 단위 테스트 | 통합 수준 테스트 | 비고 |
+|------|:----------:|:--------------:|------|
+| 기술 지표 계산 (RSI/MACD/BB/EMA/StochRSI/ADX) | ✅ | ✅ | `test_indicators` + `test_ml_features` + `test_dataset_builder` |
+| 신호 생성 (가중치 합산) | ✅ | ✅ | `test_indicators` + `test_dataset_builder` |
+| ADX 횡보장 필터 (ADX < 25 차단) | ✅ | ✅ | `test_indicators` + `test_dataset_builder` (`_calc_signals` 실제 호출) |
+| ML 피처 추출 (23개) | ✅ | ✅ | `test_ml_features` + `test_dataset_builder` (`_calc_features_vectorized` 실제 호출) |
+| ML 필터 추론 (임계값 판단) | ✅ | — | `test_ml_filter` |
+| MLX 신경망 학습/저장/로드 | ✅ | — | `test_mlx_filter` (Apple Silicon 전용) |
+| 레이블 생성 (SL/TP 룩어헤드) | ✅ | ✅ | `test_label_builder` + `test_dataset_builder` (전체 파이프라인 실제 호출) |
+| 벡터화 데이터셋 빌더 | ✅ | ✅ | `test_dataset_builder` |
+| 동적 증거금 비율 계산 | ✅ | — | `test_risk_manager` |
+| 일일 손실 한도 제어 | ✅ | — | `test_risk_manager` |
+| 포지션 수량 계산 | ✅ | — | `test_exchange` |
+| OI/펀딩비 API 조회 (정상/오류) | ✅ | ✅ | `test_exchange` + `test_bot` (`process_candle` → OI/펀딩비 → `build_features` 전달) |
+| 반대 시그널 재진입 흐름 | ✅ | ✅ | `test_bot` |
+| ML 차단 시 재진입 스킵 | ✅ | ✅ | `test_bot` (`_close_and_reenter` → ML 판단 → 스킵 전체 흐름) |
+| OI 변화율 계산 (API 실패 폴백) | ✅ | ✅ | `test_bot` (`process_candle` → OI 조회 → `_calc_oi_change` 흐름) |
+| 캔들 버퍼 관리 및 프리로드 | ✅ | — | `test_data_stream` |
+| Parquet Upsert (OI=0 보충) | ✅ | — | `test_fetch_history` |
+| User Data Stream TP/SL 감지 | ❌ | — | 미작성 (실제 WebSocket 의존) |
+| Discord 알림 전송 | ❌ | — | 미작성 (외부 웹훅 의존) |
+| CI/CD 파이프라인 | ❌ | — | Jenkins 환경 의존 |
+
+### 5.4 테스트 전략
+
+**Mock 활용 원칙:**
+- Binance API 호출(`BinanceFuturesClient`, `AsyncClient`)은 모두 `unittest.mock.AsyncMock`으로 대체합니다.
+- 외부 의존성(Discord Webhook, Binance WebSocket)은 테스트 대상에서 제외합니다.
+- `tmp_path` pytest fixture로 Parquet 파일 I/O를 격리합니다.
+
+**비동기 테스트:**
+- `pytest-asyncio`를 사용하며, `@pytest.mark.asyncio` 데코레이터로 `async def` 테스트를 실행합니다.
+
+**경계값 및 엣지 케이스 중심:**
+- 분모 0 (RS 계산, bb_range, vol_ma20)
+- API 실패 시 `None` 반환 및 `0.0` 폴백
+- 최소 명목금액 미달 시 주문 스킵
+- OI=0 구간 Parquet Upsert 보존/덮어쓰기 조건
+
+---
+
+## 부록: 파일별 역할 요약
+
+| 파일 | 레이어 | 역할 |
+|------|--------|------|
+| `main.py` | — | 진입점. `Config` 로드 후 `TradingBot.run()` 실행 |
+| `src/bot.py` | 오케스트레이터 | 모든 레이어를 조율하는 메인 트레이딩 루프 |
+| `src/config.py` | — | 환경변수 기반 설정 (`@dataclass`) |
+| `src/data_stream.py` | Data | Combined WebSocket 캔들 수신·버퍼 관리 |
+| `src/indicators.py` | Signal | 기술 지표 계산 및 복합 신호 생성 |
+| `src/ml_features.py` | ML Filter | 23개 ML 피처 추출 |
+| `src/ml_filter.py` | ML Filter | ONNX/LightGBM 모델 로드·추론·핫리로드 |
+| `src/mlx_filter.py` | ML Filter | Apple Silicon GPU 학습 + ONNX export |
+| `src/exchange.py` | Execution | Binance Futures REST API 클라이언트 |
+| `src/risk_manager.py` | Risk | 일일 손실 한도·동적 증거금 비율·포지션 수 제어 |
+| `src/user_data_stream.py` | Event | User Data Stream TP/SL 즉시 감지 |
+| `src/notifier.py` | Alert | Discord 웹훅 알림 |
+| `src/label_builder.py` | MLOps | 학습 레이블 생성 (ATR SL/TP 룩어헤드) |
+| `src/dataset_builder.py` | MLOps | 벡터화 데이터셋 빌더 (학습용) |
+| `src/logger_setup.py` | — | Loguru 로거 설정 |
+| `scripts/fetch_history.py` | MLOps | 과거 캔들 + OI/펀딩비 수집 (Parquet Upsert) |
+| `scripts/train_model.py` | MLOps | LightGBM 모델 학습 (CPU) |
+| `scripts/train_mlx_model.py` | MLOps | MLX 신경망 학습 (Apple Silicon GPU) |
+| `scripts/tune_hyperparams.py` | MLOps | Optuna 하이퍼파라미터 탐색 (수동 트리거) |
+| `scripts/train_and_deploy.sh` | MLOps | 전체 파이프라인 (수집→학습→배포) |
+| `scripts/deploy_model.sh` | MLOps | 모델 파일 LXC 서버 전송 |
+| `models/active_lgbm_params.json` | MLOps | 승인된 LightGBM 파라미터 (Active Config) |

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CoinTrader is a Python asyncio-based automated cryptocurrency trading bot for Binance Futures. It trades XRPUSDT on 15-minute candles, using BTC/ETH as correlation features. The system has 5 layers: Data (WebSocket streams) → Signal (technical indicators) → ML Filter (ONNX/LightGBM) → Execution & Risk → Event/Alert (Discord).
+
+## Common Commands
+
+```bash
+# venv 
+source .venv/bin/activate
+
+# Run the bot
+python main.py
+
+# Run full test suite
+bash scripts/run_tests.sh
+
+# Run filtered tests
+bash scripts/run_tests.sh -k "bot"
+
+# Run pytest directly
+pytest tests/ -v --tb=short
+
+# ML training pipeline (LightGBM default)
+bash scripts/train_and_deploy.sh
+
+# MLX GPU training (macOS Apple Silicon)
+bash scripts/train_and_deploy.sh mlx
+
+# Hyperparameter tuning (50 trials, 5-fold walk-forward)
+python scripts/tune_hyperparams.py
+
+# Fetch historical data
+python scripts/fetch_history.py --symbols XRPUSDT BTCUSDT ETHUSDT --interval 15m --days 365
+
+# Deploy models to production
+bash scripts/deploy_model.sh
+```
+
+## Architecture
+
+**Entry point**: `main.py` → creates `Config` (dataclass from env vars) → runs `TradingBot`
+
+**5-layer data flow on each 15m candle close:**
+1. `src/data_stream.py` — Combined WebSocket for XRP/BTC/ETH, deque buffers (200 candles each)
+2. `src/indicators.py` — RSI, MACD, BB, EMA, StochRSI, ATR; weighted signal aggregation → LONG/SHORT/HOLD
+3. `src/ml_filter.py` + `src/ml_features.py` — 23-feature extraction, ONNX priority > LightGBM fallback, threshold ≥ 0.60
+4. `src/exchange.py` + `src/risk_manager.py` — Dynamic margin, MARKET orders with SL/TP, daily loss limit (5%)
+5. `src/user_data_stream.py` + `src/notifier.py` — Real-time TP/SL detection via WebSocket, Discord webhooks
+
+**Parallel execution**: `user_data_stream` runs independently via `asyncio.gather()` alongside candle processing.
+
+## Key Patterns
+
+- **Async-first**: All I/O operations use `async/await`; parallel tasks via `asyncio.gather()`
+- **Reverse signal re-entry**: While holding LONG, if SHORT signal appears → close position, cancel SL/TP, open SHORT. `_is_reentering` flag prevents race conditions with User Data Stream
+- **ML hot reload**: `ml_filter.check_and_reload()` compares file mtime on every candle, reloads model without restart
+- **Active Config pattern**: Best hyperparams stored in `models/active_lgbm_params.json`, must be manually approved before retraining
+- **Graceful degradation**: Missing model → all signals pass; API failure → use fallback values (0.0 for OI/funding)
+- **Walk-forward validation**: Time-series CV with undersampling (1:1 class balance, preserving time order)
+- **Label generation**: Binary labels based on 24-candle (6h) lookahead — check SL hit first (conservative), then TP
+
+## Testing
+
+- All external APIs (Binance, Discord) are mocked with `unittest.mock.AsyncMock`
+- Async tests use `@pytest.mark.asyncio`
+- 14 test files, 80+ test cases covering all layers
+- Testing is done in actual terminal, not IDE sandbox
+
+## Configuration
+
+Environment variables via `.env` file (see `.env.example`). Key vars: `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `SYMBOL` (default XRPUSDT), `LEVERAGE`, `DISCORD_WEBHOOK_URL`, `MARGIN_MAX_RATIO`, `MARGIN_MIN_RATIO`, `NO_ML_FILTER`.
+
+`src/config.py` uses `@dataclass` with `__post_init__` to load and validate all env vars.
+
+## Deployment
+
+- **Docker**: `Dockerfile` (Python 3.12-slim) + `docker-compose.yml`
+- **CI/CD**: Jenkins pipeline (Gitea → Docker registry → LXC production server)
+- Models stored in `models/`, data cache in `data/`, logs in `logs/`
+
+## Design & Implementation Plans
+
+All design documents and implementation plans are stored in `docs/plans/` with the naming convention `YYYY-MM-DD-feature-name.md`. Design docs (`-design.md`) describe architecture decisions; implementation plans (`-plan.md`) contain step-by-step tasks for Claude to execute.
+
+**Chronological plan history:**
+
+| Date | Plan | Status |
+|------|------|--------|
+| 2026-03-01 | `xrp-futures-autotrader` | Completed |
+| 2026-03-01 | `discord-notifier-and-position-recovery` | Completed |
+| 2026-03-01 | `upload-to-gitea` | Completed |
+| 2026-03-01 | `dockerfile-and-docker-compose` | Completed |
+| 2026-03-01 | `fix-pandas-ta-python312` | Completed |
+| 2026-03-01 | `jenkins-gitea-registry-cicd` | Completed |
+| 2026-03-01 | `ml-filter-design` / `ml-filter-implementation` | Completed |
+| 2026-03-01 | `train-on-mac-deploy-to-lxc` | Completed |
+| 2026-03-01 | `m4-accelerated-training` | Completed |
+| 2026-03-01 | `vectorized-dataset-builder` | Completed |
+| 2026-03-01 | `btc-eth-correlation-features` (design + plan) | Completed |
+| 2026-03-01 | `dynamic-margin-ratio` (design + plan) | Completed |
+| 2026-03-01 | `lgbm-improvement` | Completed |
+| 2026-03-01 | `15m-timeframe-upgrade` | Completed |
+| 2026-03-01 | `oi-nan-epsilon-precision-threshold` | Completed |
+| 2026-03-02 | `rs-divide-mlx-nan-fix` | Completed |
+| 2026-03-02 | `reverse-signal-reenter` (design + plan) | Completed |
+| 2026-03-02 | `realtime-oi-funding-features` | Completed |
+| 2026-03-02 | `oi-funding-accumulation` | Completed |
+| 2026-03-02 | `optuna-hyperparam-tuning` (design + plan) | Completed |
+| 2026-03-02 | `user-data-stream-tp-sl-detection` (design + plan) | Completed |
+| 2026-03-02 | `adx-filter-design` | Completed |
+| 2026-03-02 | `hold-negative-sampling` (design + plan) | Completed |
+| 2026-03-03 | `optuna-precision-objective-plan` | Pending |

Jenkinsfile

@@ -7,9 +7,24 @@ pipeline {
         IMAGE_TAG     = "${env.BUILD_NUMBER}"
         FULL_IMAGE    = "${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"
         LATEST_IMAGE  = "${REGISTRY}/${IMAGE_NAME}:latest"
+        
+        // 젠킨스 자격 증명에 저장해둔 디스코드 웹훅 주소를 불러옵니다.
+        DISCORD_WEBHOOK = credentials('discord-webhook')
     }
 
     stages {
+        // 빌드가 시작되자마자 알림을 보냅니다.
+        stage('Notify Build Start') {
+            steps {
+                sh """
+                curl -H "Content-Type: application/json" \
+                     -X POST \
+                     -d '{"content": "🚀 **[빌드 시작]** `cointrader` (Build #${env.BUILD_NUMBER}) 배포 파이프라인 가동"}' \
+                     ${DISCORD_WEBHOOK}
+                """
+            }
+        }
+
         stage('Git Clone from Gitea') {
             steps {
                 git branch: 'main',
@@ -55,12 +70,25 @@ pipeline {
         }
     }
 
+    // 파이프라인 결과에 따른 디스코드 알림
     post {
         success {
             echo "Build #${env.BUILD_NUMBER} 성공: ${FULL_IMAGE} → 운영 LXC(10.1.10.24) 배포 완료"
+            sh """
+            curl -H "Content-Type: application/json" \
+                 -X POST \
+                 -d '{"content": "✅ **[배포 성공]** `cointrader` (Build #${env.BUILD_NUMBER}) 운영 서버(10.1.10.24) 배포 완료!\\n- 📦 이미지: `${FULL_IMAGE}`"}' \
+                 ${DISCORD_WEBHOOK}
+            """
         }
         failure {
             echo "Build #${env.BUILD_NUMBER} 실패"
+            sh """
+            curl -H "Content-Type: application/json" \
+                 -X POST \
+                 -d '{"content": "❌ **[배포 실패]** `cointrader` (Build #${env.BUILD_NUMBER}) 파이프라인 에러 발생. 젠킨스 로그를 확인해 주세요!"}' \
+                 ${DISCORD_WEBHOOK}
+            """
         }
     }
-}
+}

README.md

@@ -1,18 +1,32 @@
 # CoinTrader
 
-Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.
+Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / MLX 신경망)를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.
+
+> **아키텍처 문서**: 코드 구조, 레이어별 역할, MLOps 파이프라인, 동작 시나리오를 상세히 설명한 [ARCHITECTURE.md](./ARCHITECTURE.md)를 참고하세요.
 
 ---
 
 ## 주요 기능
 
-- **복합 기술 지표 신호**: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 3개 이상 일치 시 진입
-- **ML 필터 (LightGBM)**: 기술 지표 신호를 한 번 더 검증하여 오진입 차단 (모델 없으면 자동 폴백)
+- **복합 기술 지표 신호**: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 가중치 합계 ≥ 3 시 진입
+- **ML 필터 (ONNX 우선 / LightGBM 폴백)**: 기술 지표 신호를 한 번 더 검증하여 오진입 차단. 우선순위: ONNX > LightGBM > 폴백(항상 허용)
+- **모델 핫리로드**: 캔들마다 모델 파일 mtime을 감지해 변경 시 자동 리로드 (봇 재시작 불필요)
+- **멀티심볼 스트림**: XRP/BTC/ETH 3개 심볼을 단일 Combined WebSocket으로 수신, BTC·ETH 상관관계 피처 활용
+- **23개 ML 피처**: XRP 기술 지표 13개 + BTC/ETH 수익률·상대강도 8개 + OI 변화율·펀딩비 2개 (캔들 마감 시 실시간 조회, 실패 시 0으로 폴백)
+- **점진적 OI 데이터 축적 (Upsert)**: 바이낸스 OI 히스토리 API는 최근 30일치만 제공. `fetch_history.py` 실행 시 기존 parquet의 `oi_change/funding_rate=0` 구간을 신규 값으로 채워 학습 데이터 품질을 점진적으로 개선
+- **실시간 OI/펀딩비 조회**: 캔들 마감마다 `get_open_interest()` / `get_funding_rate()`를 비동기 병렬 조회하여 ML 피처에 전달. 이전 캔들 대비 OI 변화율로 변환하여 train-serve skew 해소
 - **ATR 기반 손절/익절**: 변동성에 따라 동적으로 SL/TP 계산 (1.5× / 3.0× ATR)
-- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도 제어
+- **Algo Order API 지원**: 계정 설정에 따라 STOP_MARKET/TAKE_PROFIT_MARKET 주문을 `/fapi/v1/algoOrder` 엔드포인트로 자동 전송 (오류 코드 -4120 대응)
+- **동적 증거금 비율**: 잔고 증가에 따라 선형 감소 (최대 50% → 최소 20%)
+- **반대 시그널 재진입**: 보유 포지션과 반대 신호 발생 시 즉시 청산 후 ML 필터 통과 시 반대 방향 재진입
+- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도(5%) 제어
 - **포지션 복구**: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원
+- **실시간 TP/SL 감지**: Binance User Data Stream으로 TP/SL 작동을 즉시 감지 (캔들 마감 대기 없음)
+- **순수익(Net PnL) 기록**: 바이낸스 `realizedProfit - commission`으로 정확한 순수익 계산
+- **Discord 상세 청산 알림**: 예상 수익 vs 실제 순수익 + 슬리피지/수수료 차이 표시
+- **listenKey 자동 갱신**: 30분 keepalive + 네트워크 단절 시 자동 재연결. `stream.recv()` 기반으로 수신하며, 라이브러리 내부 에러 페이로드(`{"e":"error"}`) 감지 시 즉시 재연결하여 좀비 커넥션 방지
 - **Discord 알림**: 진입·청산·오류 이벤트 실시간 웹훅 알림
-- **CI/CD**: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포
+- **CI/CD**: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포 (LXC 운영 서버 자동 적용)
 
 ---
 
@@ -20,27 +34,34 @@ Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를
 
 ```
 cointrader/
-├── main.py                  # 진입점
+├── main.py                    # 진입점
 ├── src/
-│   ├── bot.py               # 메인 트레이딩 루프
-│   ├── config.py            # 환경변수 기반 설정
-│   ├── exchange.py          # Binance Futures API 클라이언트
-│   ├── data_stream.py       # WebSocket 1분봉 스트림
-│   ├── indicators.py        # 기술 지표 계산 및 신호 생성
-│   ├── ml_filter.py         # LightGBM 진입 필터
-│   ├── ml_features.py       # ML 피처 빌더
-│   ├── label_builder.py     # 학습 레이블 생성
-│   ├── dataset_builder.py   # 벡터화 데이터셋 빌더 (학습용)
-│   ├── risk_manager.py      # 리스크 관리
-│   ├── notifier.py          # Discord 웹훅 알림
-│   └── logger_setup.py      # Loguru 로거 설정
+│   ├── bot.py                 # 메인 트레이딩 루프
+│   ├── config.py              # 환경변수 기반 설정
+│   ├── exchange.py            # Binance Futures API 클라이언트
+│   ├── data_stream.py         # WebSocket 15분봉 멀티심볼 스트림 (XRP/BTC/ETH)
+│   ├── indicators.py          # 기술 지표 계산 및 신호 생성
+│   ├── ml_filter.py           # ML 필터 (ONNX 우선 / LightGBM 폴백 / 핫리로드)
+│   ├── ml_features.py         # ML 피처 빌더 (23개 피처)
+│   ├── mlx_filter.py          # MLX 신경망 필터 (Apple Silicon GPU 학습 + ONNX export)
+│   ├── label_builder.py       # 학습 레이블 생성
+│   ├── dataset_builder.py     # 벡터화 데이터셋 빌더 (학습용)
+│   ├── risk_manager.py        # 리스크 관리 (일일 손실 한도, 동적 증거금 비율)
+│   ├── notifier.py            # Discord 웹훅 알림
+│   └── logger_setup.py        # Loguru 로거 설정
 ├── scripts/
-│   ├── fetch_history.py     # 과거 데이터 수집
-│   └── train_model.py       # ML 모델 수동 학습
-├── models/                  # 학습된 모델 저장 (.pkl)
-├── data/                    # 과거 데이터 캐시
-├── logs/                    # 로그 파일
-├── tests/                   # 테스트 코드
+│   ├── fetch_history.py       # 과거 데이터 수집 (XRP/BTC/ETH + OI/펀딩비, Upsert 지원)
+│   ├── train_model.py         # LightGBM 모델 학습 (CPU)
+│   ├── train_mlx_model.py     # MLX 신경망 학습 (Apple Silicon GPU)
+│   ├── train_and_deploy.sh    # 전체 파이프라인 (수집 → 학습 → LXC 배포)
+│   ├── tune_hyperparams.py    # Optuna 하이퍼파라미터 자동 탐색 (수동 트리거)
+│   ├── deploy_model.sh        # 모델 파일 LXC 서버 전송
+│   └── run_tests.sh           # 전체 테스트 실행
+├── models/                    # 학습된 모델 저장 (.pkl / .onnx)
+├── data/                      # 과거 데이터 캐시 (.parquet)
+├── logs/                      # 로그 파일
+├── docs/plans/                # 설계 문서 및 구현 플랜
+├── tests/                     # 테스트 코드
 ├── Dockerfile
 ├── docker-compose.yml
 ├── Jenkinsfile
@@ -64,7 +85,6 @@ BINANCE_API_KEY=your_api_key
 BINANCE_API_SECRET=your_api_secret
 SYMBOL=XRPUSDT
 LEVERAGE=10
-RISK_PER_TRADE=0.02
 DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
 ```
 
@@ -91,17 +111,82 @@ docker compose logs -f cointrader
 
 ## ML 모델 학습
 
-봇은 모델 파일(`models/lgbm_filter.pkl`)이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.
+봇은 모델 파일이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.
+
+### 전체 파이프라인 (권장)
+
+맥미니에서 데이터 수집 → 학습 → LXC 배포까지 한 번에 실행합니다.
+
+> **자동 분기**: `data/combined_15m.parquet`가 없으면 1년치(365일) 전체 수집, 있으면 35일치 Upsert로 자동 전환합니다. 서버 이전이나 데이터 유실 시에도 사람의 개입 없이 자동 복구됩니다.
 
 ```bash
-# 1. 과거 데이터 수집
-python scripts/fetch_history.py
+# LightGBM + Walk-Forward 5폴드 (기본값)
+bash scripts/train_and_deploy.sh
 
-# 2. 모델 학습 (LightGBM, CPU)
-python scripts/train_model.py
+# MLX GPU 학습 + Walk-Forward 5폴드
+bash scripts/train_and_deploy.sh mlx
+
+# LightGBM + Walk-Forward 3폴드
+bash scripts/train_and_deploy.sh lgbm 3
+
+# 학습만 (배포 없이)
+bash scripts/train_and_deploy.sh lgbm 0
 ```
 
-학습된 모델은 `models/lgbm_filter.pkl`에 저장됩니다. 재학습이 필요하면 맥미니에서 위 스크립트를 다시 실행하고 모델 파일을 컨테이너에 배포합니다.
+### 단계별 수동 실행
+
+```bash
+# 1. 과거 데이터 수집 (XRP/BTC/ETH 3심볼, 15분봉, 1년치 + OI/펀딩비)
+# 기본값: Upsert 활성화 — 기존 parquet의 oi_change/funding_rate=0 구간을 실제 값으로 채움
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/combined_15m.parquet
+
+# 기존 파일을 완전히 덮어쓰려면 --no-upsert 플래그 사용
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/combined_15m.parquet \
+    --no-upsert
+
+# 2-A. LightGBM 모델 학습 (CPU)
+python scripts/train_model.py --data data/combined_15m.parquet
+
+# 2-B. MLX 신경망 학습 (Apple Silicon GPU)
+python scripts/train_mlx_model.py --data data/combined_15m.parquet
+
+# 3. LXC 서버에 모델 배포
+bash scripts/deploy_model.sh        # LightGBM
+bash scripts/deploy_model.sh mlx    # MLX (ONNX)
+```
+
+학습된 모델은 `models/lgbm_filter.pkl` (LightGBM) 또는 `models/mlx_filter.weights.onnx` (MLX) 에 저장됩니다.
+
+> **모델 핫리로드**: 봇이 실행 중일 때 모델 파일을 교체하면, 다음 캔들 마감 시 자동으로 감지해 리로드합니다. 봇 재시작이 필요 없습니다.
+
+### 하이퍼파라미터 자동 튜닝 (Optuna)
+
+봇 성능이 저하되거나 데이터가 충분히 축적되었을 때 Optuna로 최적 LightGBM 파라미터를 탐색합니다.
+결과를 확인하고 직접 승인한 후 재학습에 반영하는 **수동 트리거** 방식입니다.
+
+```bash
+# 기본 실행 (50 trials, 5폴드 Walk-Forward, ~30분)
+python scripts/tune_hyperparams.py
+
+# 빠른 테스트 (10 trials, 3폴드, ~5분)
+python scripts/tune_hyperparams.py --trials 10 --folds 3
+
+# 베이스라인 측정 없이 탐색만
+python scripts/tune_hyperparams.py --no-baseline
+```
+
+결과는 `models/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다.
+콘솔에 Best Params, 베이스라인 대비 개선폭, 폴드별 AUC를 출력하므로 직접 확인 후 판단하세요.
+
+> **주의**: Optuna가 찾은 파라미터는 과적합 위험이 있습니다. Best Params를 `train_model.py`에 반영하기 전에 반드시 폴드별 AUC 분산과 개선폭을 검토하세요.
 
 ### Apple Silicon GPU 가속 학습 (M1/M2/M3/M4)
 
@@ -110,23 +195,16 @@ M 시리즈 맥에서는 MLX를 사용해 통합 GPU(Metal)로 학습할 수 있
 > **설치**: `mlx`는 Apple Silicon 전용이며 `requirements.txt`에 포함되지 않습니다.
 > 맥미니에서 별도 설치: `pip install mlx`
 
-```bash
-# MLX 별도 설치 (맥미니 전용)
-pip install mlx
+MLX로 학습한 모델은 ONNX 포맷으로 export되어 Linux 서버에서 `onnxruntime`으로 추론합니다.
 
-# MLX 신경망 필터 학습 (GPU 자동 사용)
-python scripts/train_mlx_model.py
-
-# train_and_deploy.sh에서 MLX 백엔드 사용
-TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
-```
-
-> **참고**: LightGBM은 Apple Silicon GPU를 공식 지원하지 않습니다. MLX는 Apple이 만든 ML 프레임워크로 통합 GPU를 자동으로 활용합니다. Neural Engine(NPU)은 Apple 내부 전용으로 Python에서 직접 제어할 수 없습니다.
+> **참고**: LightGBM은 Apple Silicon GPU를 공식 지원하지 않습니다. MLX는 Apple이 만든 ML 프레임워크로 통합 GPU를 자동으로 활용합니다.
 
 ---
 
 ## 매매 전략
 
+### 기술 지표 신호 (15분봉)
+
 | 지표 | 롱 조건 | 숏 조건 | 가중치 |
 |------|---------|---------|--------|
 | RSI (14) | < 35 | > 65 | 1 |
@@ -138,7 +216,13 @@ TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
 
 **진입 조건**: 가중치 합계 ≥ 3 + (거래량 급증 또는 가중치 합계 ≥ 4)  
 **손절/익절**: ATR × 1.5 / ATR × 3.0 (리스크:리워드 = 1:2)  
-**ML 필터**: LightGBM 예측 확률 ≥ 0.60 이어야 최종 진입
+**ML 필터**: 예측 확률 ≥ 0.60 이어야 최종 진입
+
+### 반대 시그널 재진입
+
+보유 포지션과 반대 방향 신호가 발생하면:
+1. 기존 포지션 즉시 청산 (미체결 SL/TP 주문 취소 포함)
+2. ML 필터 통과 시 반대 방향으로 즉시 재진입
 
 ---
 
@@ -146,22 +230,27 @@ TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
 
 `main` 브랜치에 푸시하면 Jenkins 파이프라인이 자동으로 실행됩니다.
 
-1. **Checkout** — 소스 체크아웃
-2. **Build Image** — Docker 이미지 빌드 (`:{BUILD_NUMBER}` + `:latest` 태그)
-3. **Push** — Gitea Container Registry(`10.1.10.28:3000`)에 푸시
-4. **Cleanup** — 로컬 이미지 정리
+1. **Notify Build Start** — Discord 빌드 시작 알림
+2. **Git Clone from Gitea** — 소스 체크아웃
+3. **Build Docker Image** — Docker 이미지 빌드 (`:{BUILD_NUMBER}` + `:latest` 태그)
+4. **Push to Gitea Registry** — Gitea Container Registry(`10.1.10.28:3000`)에 푸시
+5. **Deploy to Prod LXC** — 운영 LXC 서버(`10.1.10.24`)에 자동 배포 (`docker compose pull && up -d`)
+6. **Cleanup** — 빌드 서버 로컬 이미지 정리
 
-배포 서버에서 최신 이미지를 반영하려면:
-
-```bash
-docker compose pull && docker compose up -d
-```
+빌드 성공/실패 결과는 Discord로 자동 알림됩니다.
 
 ---
 
 ## 테스트
 
 ```bash
+# 전체 테스트
+bash scripts/run_tests.sh
+
+# 특정 키워드 필터
+bash scripts/run_tests.sh -k bot
+
+# pytest 직접 실행
 pytest tests/ -v
 ```
 
@@ -175,13 +264,16 @@ pytest tests/ -v
 | `BINANCE_API_SECRET` | — | Binance API 시크릿 |
 | `SYMBOL` | `XRPUSDT` | 거래 심볼 |
 | `LEVERAGE` | `10` | 레버리지 배수 |
-| `RISK_PER_TRADE` | `0.02` | 트레이드당 리스크 비율 (2%) |
 | `DISCORD_WEBHOOK_URL` | — | Discord 웹훅 URL |
+| `MARGIN_MAX_RATIO` | `0.50` | 최대 증거금 비율 (잔고 대비 50%) |
+| `MARGIN_MIN_RATIO` | `0.20` | 최소 증거금 비율 (잔고 대비 20%) |
+| `MARGIN_DECAY_RATE` | `0.0006` | 잔고 증가 시 증거금 비율 감소 속도 |
+| `NO_ML_FILTER` | — | `true`/`1`/`yes` 설정 시 ML 필터 완전 비활성화 — 모델 로드 없이 모든 신호 허용 |
 
 ---
 
 ## 주의사항
 
 > **이 봇은 실제 자산을 거래합니다.** 운영 전 반드시 Binance Testnet에서 충분히 검증하세요.  
-> 과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다.
+> 과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다.  
 > 성투기원합니다.

docs/plans/2026-03-01-15m-timeframe-upgrade.md

@@ -0,0 +1,376 @@
+# 15분봉 타임프레임 업그레이드 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 1분봉 파이프라인 전체를 15분봉으로 전환하고, LOOKAHEAD=24(6시간 뷰)로 조정해 모델 AUC를 0.49~0.50 구간에서 0.53+ 이상으로 개선한다.
+
+**Architecture:** 데이터 수집(fetch_history.py) → 데이터셋 빌더(dataset_builder.py) → 학습 스크립트(train_model.py, train_mlx_model.py) → 실시간 봇(bot.py, data_stream.py) 순서로 파라미터를 변경한다. 각 레이어는 `interval` 문자열과 `LOOKAHEAD` 상수만 수정하면 되며 피처 구조는 그대로 유지한다.
+
+**Tech Stack:** Python, LightGBM, pandas, binance-python-client, pytest
+
+---
+
+## 변경 요약
+
+| 파일 | 변경 내용 |
+|------|-----------|
+| `src/dataset_builder.py` | `LOOKAHEAD 90→24`, `WARMUP 60→60` (유지) |
+| `scripts/train_model.py` | `LOOKAHEAD 60→24`, `--data` 기본값 `combined_1m→combined_15m` |
+| `scripts/train_mlx_model.py` | `--data` 기본값 `combined_1m→combined_15m` |
+| `scripts/fetch_history.py` | `--interval` 기본값 `1m→15m`, `--output` 기본값 반영 |
+| `scripts/train_and_deploy.sh` | `--interval 1m→15m`, 파일명 `1m→15m` |
+| `src/bot.py` | `interval="1m"→"15m"` |
+| `src/data_stream.py` | `buffer_size` 기본값 `200→200` (유지, 15분봉 200개=50시간 충분) |
+
+---
+
+## Task 1: dataset_builder.py — LOOKAHEAD 상수 변경
+
+**Files:**
+- Modify: `src/dataset_builder.py:14-17`
+
+**Step 1: 현재 상수 확인**
+
+```bash
+head -20 src/dataset_builder.py
+```
+
+Expected: `LOOKAHEAD = 90`, `WARMUP = 60`
+
+**Step 2: 상수 변경**
+
+`src/dataset_builder.py` 14번째 줄:
+```python
+# 변경 전
+LOOKAHEAD    = 90
+ATR_SL_MULT  = 1.5
+ATR_TP_MULT  = 2.0
+WARMUP       = 60
+
+# 변경 후
+LOOKAHEAD    = 24   # 15분봉 × 24 = 6시간 뷰
+ATR_SL_MULT  = 1.5
+ATR_TP_MULT  = 2.0
+WARMUP       = 60   # 15분봉 기준 60캔들 = 15시간 (지표 안정화 충분)
+```
+
+**Step 3: 변경 확인**
+
+```bash
+head -20 src/dataset_builder.py
+```
+
+Expected: `LOOKAHEAD = 24`
+
+---
+
+## Task 2: train_model.py — LOOKAHEAD 상수 및 기본 데이터 경로 변경
+
+**Files:**
+- Modify: `scripts/train_model.py:56-61`, `scripts/train_model.py:360`
+
+**Step 1: 현재 상수 확인**
+
+```bash
+sed -n '55,62p' scripts/train_model.py
+sed -n '358,362p' scripts/train_model.py
+```
+
+Expected: `LOOKAHEAD = 60`, `--data default="data/combined_1m.parquet"`
+
+**Step 2: LOOKAHEAD 변경**
+
+`scripts/train_model.py` 56번째 줄:
+```python
+# 변경 전
+LOOKAHEAD = 60
+
+# 변경 후
+LOOKAHEAD = 24  # 15분봉 × 24 = 6시간 (dataset_builder.py와 동기화)
+```
+
+**Step 3: --data 기본값 변경**
+
+`scripts/train_model.py` 360번째 줄 근처 `argparse` 부분:
+```python
+# 변경 전
+parser.add_argument("--data", default="data/combined_1m.parquet")
+
+# 변경 후
+parser.add_argument("--data", default="data/combined_15m.parquet")
+```
+
+**Step 4: 변경 확인**
+
+```bash
+grep -n "LOOKAHEAD\|combined_" scripts/train_model.py
+```
+
+Expected: `LOOKAHEAD = 24`, `combined_15m.parquet`
+
+---
+
+## Task 3: train_mlx_model.py — 기본 데이터 경로 변경
+
+**Files:**
+- Modify: `scripts/train_mlx_model.py:149`
+
+**Step 1: 현재 기본값 확인**
+
+```bash
+grep -n "combined_" scripts/train_mlx_model.py
+```
+
+Expected: `default="data/combined_1m.parquet"`
+
+**Step 2: 기본값 변경**
+
+`scripts/train_mlx_model.py` 149번째 줄:
+```python
+# 변경 전
+parser.add_argument("--data", default="data/combined_1m.parquet")
+
+# 변경 후
+parser.add_argument("--data", default="data/combined_15m.parquet")
+```
+
+**Step 3: 변경 확인**
+
+```bash
+grep -n "combined_" scripts/train_mlx_model.py
+```
+
+Expected: `combined_15m.parquet`
+
+---
+
+## Task 4: fetch_history.py — 기본 interval 및 output 변경
+
+**Files:**
+- Modify: `scripts/fetch_history.py:114-118`
+
+**Step 1: 현재 argparse 기본값 확인**
+
+```bash
+sed -n '112,120p' scripts/fetch_history.py
+```
+
+Expected: `--interval default="1m"`, `--output default="data/xrpusdt_1m.parquet"`
+
+**Step 2: 기본값 변경**
+
+```python
+# 변경 전
+parser.add_argument("--interval", default="1m")
+parser.add_argument("--days",     type=int, default=90)
+parser.add_argument("--output",   default="data/xrpusdt_1m.parquet")
+
+# 변경 후
+parser.add_argument("--interval", default="15m")
+parser.add_argument("--days",     type=int, default=365)
+parser.add_argument("--output",   default="data/xrpusdt_15m.parquet")
+```
+
+**Step 3: 변경 확인**
+
+```bash
+grep -n "interval\|output\|days" scripts/fetch_history.py | grep "default"
+```
+
+Expected: `default="15m"`, `default=365`, `default="data/xrpusdt_15m.parquet"`
+
+---
+
+## Task 5: train_and_deploy.sh — interval 및 파일명 변경
+
+**Files:**
+- Modify: `scripts/train_and_deploy.sh:26-43`
+
+**Step 1: 현재 스크립트 확인**
+
+```bash
+cat scripts/train_and_deploy.sh
+```
+
+**Step 2: 스크립트 변경**
+
+```bash
+# 변경 전 (26~32번째 줄)
+echo "=== [1/3] 데이터 수집 (XRP + BTC + ETH 3심볼, 1년치) ==="
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 1m \
+    --days 365 \
+    --output data/xrpusdt_1m.parquet
+# 결과: data/combined_1m.parquet (타임스탬프 기준 병합)
+
+# 변경 후
+echo "=== [1/3] 데이터 수집 (XRP + BTC + ETH 3심볼, 1년치) ==="
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/xrpusdt_15m.parquet
+# 결과: data/combined_15m.parquet (타임스탬프 기준 병합)
+```
+
+```bash
+# 변경 전 (38~43번째 줄)
+    python scripts/train_mlx_model.py --data data/combined_1m.parquet --decay "$DECAY"
+else
+    echo "  백엔드: LightGBM (CPU), decay=${DECAY}"
+    python scripts/train_model.py --data data/combined_1m.parquet --decay "$DECAY"
+
+# 변경 후
+    python scripts/train_mlx_model.py --data data/combined_15m.parquet --decay "$DECAY"
+else
+    echo "  백엔드: LightGBM (CPU), decay=${DECAY}"
+    python scripts/train_model.py --data data/combined_15m.parquet --decay "$DECAY"
+```
+
+**Step 3: 변경 확인**
+
+```bash
+grep -n "1m\|15m" scripts/train_and_deploy.sh
+```
+
+Expected: 모든 `1m` 참조가 `15m`으로 변경됨
+
+---
+
+## Task 6: bot.py — 실시간 스트림 interval 변경
+
+**Files:**
+- Modify: `src/bot.py:22-25`
+
+**Step 1: 현재 interval 확인**
+
+```bash
+grep -n "interval" src/bot.py
+```
+
+Expected: `interval="1m"` (MultiSymbolStream 생성자)
+
+**Step 2: interval 변경**
+
+`src/bot.py` 21~25번째 줄:
+```python
+# 변경 전
+self.stream = MultiSymbolStream(
+    symbols=[config.symbol, "BTCUSDT", "ETHUSDT"],
+    interval="1m",
+    on_candle=self._on_candle_closed,
+)
+
+# 변경 후
+self.stream = MultiSymbolStream(
+    symbols=[config.symbol, "BTCUSDT", "ETHUSDT"],
+    interval="15m",
+    on_candle=self._on_candle_closed,
+)
+```
+
+**Step 3: 변경 확인**
+
+```bash
+grep -n "interval" src/bot.py
+```
+
+Expected: `interval="15m"`
+
+---
+
+## Task 7: 전체 변경 검증
+
+**Step 1: 모든 `1m` 하드코딩 잔재 확인**
+
+```bash
+grep -rn '"1m"' src/ scripts/
+```
+
+Expected: 결과 없음 (모두 `"15m"`으로 변경됨)
+
+**Step 2: LOOKAHEAD 동기화 확인**
+
+```bash
+grep -rn "LOOKAHEAD" src/ scripts/
+```
+
+Expected:
+- `src/dataset_builder.py`: `LOOKAHEAD = 24`
+- `scripts/train_model.py`: `LOOKAHEAD = 24`
+
+**Step 3: combined 파일명 일관성 확인**
+
+```bash
+grep -rn "combined_" src/ scripts/
+```
+
+Expected: 모두 `combined_15m` 참조
+
+**Step 4: 파이프라인 드라이런 (데이터 없이 import 테스트)**
+
+```bash
+python -c "
+from src.dataset_builder import LOOKAHEAD, ATR_SL_MULT, ATR_TP_MULT, WARMUP
+assert LOOKAHEAD == 24, f'LOOKAHEAD={LOOKAHEAD}'
+print(f'OK: LOOKAHEAD={LOOKAHEAD}, ATR_SL={ATR_SL_MULT}, ATR_TP={ATR_TP_MULT}, WARMUP={WARMUP}')
+"
+```
+
+Expected: `OK: LOOKAHEAD=24, ATR_SL=1.5, ATR_TP=2.0, WARMUP=60`
+
+---
+
+## Task 8: 데이터 수집 및 Walk-Forward 검증 실행
+
+> 이 태스크는 실제 바이낸스 API 키와 네트워크가 필요합니다.
+
+**Step 1: 15분봉 데이터 수집**
+
+```bash
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/xrpusdt_15m.parquet
+```
+
+Expected: `data/combined_15m.parquet` 생성, 약 35,040행 (365일 × 96캔들/일)
+
+**Step 2: Walk-Forward AUC 측정 (기준선 확인)**
+
+```bash
+python scripts/train_model.py \
+    --data data/combined_15m.parquet \
+    --wf \
+    --wf-splits 5
+```
+
+Expected: Walk-Forward 평균 AUC가 0.53 이상이면 개선 확인
+
+**Step 3: 정식 학습 및 모델 저장**
+
+```bash
+python scripts/train_model.py \
+    --data data/combined_15m.parquet \
+    --decay 2.0
+```
+
+Expected: `models/lgbm_filter.pkl` 저장, 기존 모델은 `lgbm_filter_prev.pkl`로 백업
+
+---
+
+## 롤백 방법
+
+15분봉 모델이 기대에 미치지 못할 경우:
+
+```bash
+# 기존 1분봉 모델 복원
+cp models/lgbm_filter_prev.pkl models/lgbm_filter.pkl
+
+# 코드는 git으로 복원
+git checkout src/dataset_builder.py scripts/train_model.py \
+    scripts/train_mlx_model.py scripts/fetch_history.py \
+    scripts/train_and_deploy.sh src/bot.py
+```

docs/plans/2026-03-01-dynamic-margin-ratio-design.md

@@ -0,0 +1,131 @@
+# 동적 증거금 비율 설계
+
+**날짜**: 2026-03-01  
+**목적**: 잔고의 50%를 증거금으로 사용하되, 잔고가 늘어날수록 비율이 선형으로 감소하는 안전한 포지션 크기 계산 도입
+
+---
+
+## 배경
+
+- 현재 포지션 크기 계산: `risk_per_trade = 0.02` (잔고의 2%) × 레버리지 → 명목금액
+- 현재 잔고 22 USDT 기준, 최소 명목금액(5 USDT) 보장 로직으로 5 USDT 포지션만 잡힘
+- 목표: 잔고의 50%를 증거금으로 활용하여 실질적인 포지션 크기 확보
+- 안전장치: 잔고가 늘수록 비율이 자동으로 줄어들어 과도한 노출 방지
+
+---
+
+## 아키텍처
+
+### 데이터 흐름
+
+```
+bot.run()
+  └─ balance = await exchange.get_balance()
+  └─ risk.set_base_balance(balance)          ← 봇 시작 시 1회
+
+bot._open_position()
+  └─ balance = await exchange.get_balance()
+  └─ margin_ratio = risk.get_dynamic_margin_ratio(balance)   ← 신규
+  └─ exchange.calculate_quantity(balance, price, leverage, margin_ratio)
+```
+
+### 비율 계산 공식
+
+```
+ratio = MAX_RATIO - (balance - base_balance) × DECAY_RATE
+ratio = clamp(ratio, MIN_RATIO, MAX_RATIO)
+```
+
+- `base_balance`: 봇 시작 시 바이낸스 API로 조회한 실제 잔고
+- `MAX_RATIO`: 잔고가 기준값일 때 최대 비율 (기본 50%)
+- `MIN_RATIO`: 잔고가 아무리 늘어도 내려가지 않는 하한 비율 (기본 20%)
+- `DECAY_RATE`: 잔고 1 USDT 증가당 비율 감소량 (기본 0.0006)
+
+### 시뮬레이션 (기본 파라미터 기준)
+
+| 잔고 | 증거금 비율 | 증거금 | 명목금액(×10배) |
+|---|---|---|---|
+| 22 USDT | 50.0% | 11.0 USDT | 110 USDT |
+| 100 USDT | 45.3% | 45.3 USDT | 453 USDT |
+| 300 USDT | 33.2% | 99.6 USDT | 996 USDT |
+| 600 USDT | 20.0% (하한) | 120 USDT | 1,200 USDT |
+
+---
+
+## 변경 파일
+
+### 1. `src/config.py`
+
+`Config` 데이터클래스에 3개 파라미터 추가:
+
+```python
+margin_max_ratio: float = 0.50
+margin_min_ratio: float = 0.20
+margin_decay_rate: float = 0.0006
+```
+
+`__post_init__`에서 `.env` 값 읽기:
+
+```python
+self.margin_max_ratio = float(os.getenv("MARGIN_MAX_RATIO", "0.50"))
+self.margin_min_ratio = float(os.getenv("MARGIN_MIN_RATIO", "0.20"))
+self.margin_decay_rate = float(os.getenv("MARGIN_DECAY_RATE", "0.0006"))
+```
+
+### 2. `src/risk_manager.py`
+
+메서드 2개 추가:
+
+```python
+def set_base_balance(self, balance: float) -> None:
+    """봇 시작 시 기준 잔고 설정"""
+    self.initial_balance = balance
+
+def get_dynamic_margin_ratio(self, balance: float) -> float:
+    """잔고에 따라 선형 감소하는 증거금 비율 반환"""
+    ratio = self.config.margin_max_ratio - (
+        (balance - self.initial_balance) * self.config.margin_decay_rate
+    )
+    return max(self.config.margin_min_ratio, min(self.config.margin_max_ratio, ratio))
+```
+
+### 3. `src/exchange.py`
+
+`calculate_quantity` 시그니처에 `margin_ratio` 파라미터 추가:
+
+```python
+def calculate_quantity(self, balance: float, price: float, leverage: int, margin_ratio: float) -> float:
+    notional = balance * margin_ratio * leverage
+    if notional < self.MIN_NOTIONAL:
+        notional = self.MIN_NOTIONAL
+    ...
+```
+
+기존 `risk_per_trade` 기반 로직 제거.
+
+### 4. `src/bot.py`
+
+- `run()`: 시작 시 잔고 조회 후 `risk.set_base_balance(balance)` 호출
+- `_open_position()`: `margin_ratio = self.risk.get_dynamic_margin_ratio(balance)` 호출 후 `calculate_quantity`에 전달
+
+### 5. `.env`
+
+```
+MARGIN_MAX_RATIO=0.50
+MARGIN_MIN_RATIO=0.20
+MARGIN_DECAY_RATE=0.0006
+```
+
+---
+
+## 제거되는 설정
+
+- `RISK_PER_TRADE` — `.env` 및 `Config`에서 제거 (동적 비율로 대체)
+
+---
+
+## 리스크 고려사항
+
+- 잔고 22 USDT × 50% × 10배 레버리지 = 명목금액 110 USDT 노출 (잔고의 5배)
+- 손실 시 잔고가 줄어들면 다음 포지션 크기도 자동으로 줄어드는 자연스러운 안전장치 존재
+- `MARGIN_DECAY_RATE` 조정으로 감소 속도 제어 가능

docs/plans/2026-03-01-dynamic-margin-ratio-plan.md

@@ -0,0 +1,368 @@
+# 동적 증거금 비율 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 잔고의 50%를 증거금으로 사용하되, 잔고가 늘수록 비율이 선형으로 감소하는 동적 포지션 크기 계산 도입
+
+**Architecture:** `RiskManager`에 `get_dynamic_margin_ratio(balance)` 메서드를 추가하고, `bot.py`에서 포지션 진입 전 호출한다. `exchange.py`의 `calculate_quantity`는 `margin_ratio` 파라미터를 받아 기존 `risk_per_trade` 로직을 대체한다. 봇 시작 시 바이낸스 API로 실제 잔고를 조회하여 기준값(`base_balance`)으로 저장한다.
+
+**Tech Stack:** Python 3.11, python-binance, loguru, pytest, python-dotenv
+
+---
+
+## 사전 확인
+
+- 현재 `.env`: `RISK_PER_TRADE=0.02` 존재
+- 현재 `Config.risk_per_trade: float = 0.02` 존재
+- 현재 `calculate_quantity`는 `balance * risk_per_trade * leverage` 로직 사용
+- 테스트 파일 위치: `tests/` 디렉토리 (없으면 생성)
+
+---
+
+### Task 1: Config에 동적 증거금 파라미터 추가
+
+**Files:**
+- Modify: `src/config.py`
+- Modify: `.env`
+
+**Step 1: `.env`에 새 파라미터 추가**
+
+`.env` 파일 하단에 추가:
+
+```
+MARGIN_MAX_RATIO=0.50
+MARGIN_MIN_RATIO=0.20
+MARGIN_DECAY_RATE=0.0006
+```
+
+기존 `RISK_PER_TRADE=0.02` 줄은 삭제.
+
+**Step 2: `src/config.py` 수정**
+
+`Config` 데이터클래스에 필드 추가, `risk_per_trade` 필드 제거:
+
+```python
+@dataclass
+class Config:
+    api_key: str = ""
+    api_secret: str = ""
+    symbol: str = "XRPUSDT"
+    leverage: int = 10
+    max_positions: int = 3
+    stop_loss_pct: float = 0.015
+    take_profit_pct: float = 0.045
+    trailing_stop_pct: float = 0.01
+    discord_webhook_url: str = ""
+    margin_max_ratio: float = 0.50
+    margin_min_ratio: float = 0.20
+    margin_decay_rate: float = 0.0006
+
+    def __post_init__(self):
+        self.api_key = os.getenv("BINANCE_API_KEY", "")
+        self.api_secret = os.getenv("BINANCE_API_SECRET", "")
+        self.symbol = os.getenv("SYMBOL", "XRPUSDT")
+        self.leverage = int(os.getenv("LEVERAGE", "10"))
+        self.discord_webhook_url = os.getenv("DISCORD_WEBHOOK_URL", "")
+        self.margin_max_ratio = float(os.getenv("MARGIN_MAX_RATIO", "0.50"))
+        self.margin_min_ratio = float(os.getenv("MARGIN_MIN_RATIO", "0.20"))
+        self.margin_decay_rate = float(os.getenv("MARGIN_DECAY_RATE", "0.0006"))
+```
+
+**Step 3: Commit**
+
+```bash
+git add src/config.py .env
+git commit -m "feat: add dynamic margin ratio config params"
+```
+
+---
+
+### Task 2: RiskManager에 동적 비율 메서드 추가
+
+**Files:**
+- Modify: `src/risk_manager.py`
+- Create: `tests/test_risk_manager.py`
+
+**Step 1: 실패하는 테스트 작성**
+
+`tests/test_risk_manager.py` 생성:
+
+```python
+import pytest
+from src.config import Config
+from src.risk_manager import RiskManager
+
+
+@pytest.fixture
+def config():
+    c = Config()
+    c.margin_max_ratio = 0.50
+    c.margin_min_ratio = 0.20
+    c.margin_decay_rate = 0.0006
+    return c
+
+
+@pytest.fixture
+def risk(config):
+    r = RiskManager(config)
+    r.set_base_balance(22.0)
+    return r
+
+
+def test_set_base_balance(risk):
+    assert risk.initial_balance == 22.0
+
+
+def test_ratio_at_base_balance(risk):
+    """기준 잔고에서 최대 비율(50%) 반환"""
+    ratio = risk.get_dynamic_margin_ratio(22.0)
+    assert ratio == pytest.approx(0.50, abs=1e-6)
+
+
+def test_ratio_decreases_as_balance_grows(risk):
+    """잔고가 늘수록 비율 감소"""
+    ratio_100 = risk.get_dynamic_margin_ratio(100.0)
+    ratio_300 = risk.get_dynamic_margin_ratio(300.0)
+    assert ratio_100 < 0.50
+    assert ratio_300 < ratio_100
+
+
+def test_ratio_clamped_at_min(risk):
+    """잔고가 매우 커도 최소 비율(20%) 이하로 내려가지 않음"""
+    ratio = risk.get_dynamic_margin_ratio(10000.0)
+    assert ratio == pytest.approx(0.20, abs=1e-6)
+
+
+def test_ratio_clamped_at_max(risk):
+    """잔고가 기준보다 작아도 최대 비율(50%) 초과하지 않음"""
+    ratio = risk.get_dynamic_margin_ratio(5.0)
+    assert ratio == pytest.approx(0.50, abs=1e-6)
+```
+
+**Step 2: 테스트 실패 확인**
+
+```bash
+pytest tests/test_risk_manager.py -v
+```
+
+Expected: `AttributeError: 'RiskManager' object has no attribute 'set_base_balance'`
+
+**Step 3: `src/risk_manager.py` 수정**
+
+기존 코드에 메서드 2개 추가:
+
+```python
+def set_base_balance(self, balance: float) -> None:
+    """봇 시작 시 기준 잔고 설정 (동적 비율 계산 기준점)"""
+    self.initial_balance = balance
+
+def get_dynamic_margin_ratio(self, balance: float) -> float:
+    """잔고에 따라 선형 감소하는 증거금 비율 반환"""
+    ratio = self.config.margin_max_ratio - (
+        (balance - self.initial_balance) * self.config.margin_decay_rate
+    )
+    return max(self.config.margin_min_ratio, min(self.config.margin_max_ratio, ratio))
+```
+
+**Step 4: 테스트 통과 확인**
+
+```bash
+pytest tests/test_risk_manager.py -v
+```
+
+Expected: 5개 테스트 모두 PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/risk_manager.py tests/test_risk_manager.py
+git commit -m "feat: add get_dynamic_margin_ratio to RiskManager"
+```
+
+---
+
+### Task 3: exchange.py의 calculate_quantity 수정
+
+**Files:**
+- Modify: `src/exchange.py:18-29`
+- Create: `tests/test_exchange.py`
+
+**Step 1: 실패하는 테스트 작성**
+
+`tests/test_exchange.py` 생성:
+
+```python
+import pytest
+from unittest.mock import MagicMock
+from src.config import Config
+from src.exchange import BinanceFuturesClient
+
+
+@pytest.fixture
+def client():
+    config = Config()
+    config.leverage = 10
+    c = BinanceFuturesClient.__new__(BinanceFuturesClient)
+    c.config = config
+    return c
+
+
+def test_calculate_quantity_basic(client):
+    """잔고 22, 비율 50%, 레버리지 10배 → 명목금액 110, XRP 가격 2.5 → 수량 44.0"""
+    qty = client.calculate_quantity(balance=22.0, price=2.5, leverage=10, margin_ratio=0.50)
+    # 명목금액 = 22 * 0.5 * 10 = 110, 수량 = 110 / 2.5 = 44.0
+    assert qty == pytest.approx(44.0, abs=0.1)
+
+
+def test_calculate_quantity_min_notional(client):
+    """명목금액이 최소(5 USDT) 미만이면 최소값으로 올림"""
+    qty = client.calculate_quantity(balance=1.0, price=2.5, leverage=1, margin_ratio=0.01)
+    # 명목금액 = 1 * 0.01 * 1 = 0.01 < 5 → 최소 5 USDT
+    assert qty * 2.5 >= 5.0
+
+
+def test_calculate_quantity_zero_balance(client):
+    """잔고 0이면 최소 명목금액 기반 수량 반환"""
+    qty = client.calculate_quantity(balance=0.0, price=2.5, leverage=10, margin_ratio=0.50)
+    assert qty > 0
+```
+
+**Step 2: 테스트 실패 확인**
+
+```bash
+pytest tests/test_exchange.py -v
+```
+
+Expected: `TypeError: calculate_quantity() got an unexpected keyword argument 'margin_ratio'`
+
+**Step 3: `src/exchange.py` 수정**
+
+`calculate_quantity` 메서드를 아래로 교체:
+
+```python
+def calculate_quantity(self, balance: float, price: float, leverage: int, margin_ratio: float) -> float:
+    """동적 증거금 비율 기반 포지션 크기 계산 (최소 명목금액 $5 보장)"""
+    notional = balance * margin_ratio * leverage
+    if notional < self.MIN_NOTIONAL:
+        notional = self.MIN_NOTIONAL
+    quantity = notional / price
+    qty_rounded = round(quantity, 1)
+    if qty_rounded * price < self.MIN_NOTIONAL:
+        qty_rounded = round(self.MIN_NOTIONAL / price + 0.05, 1)
+    return qty_rounded
+```
+
+**Step 4: 테스트 통과 확인**
+
+```bash
+pytest tests/test_exchange.py -v
+```
+
+Expected: 3개 테스트 모두 PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/exchange.py tests/test_exchange.py
+git commit -m "feat: replace risk_per_trade with margin_ratio in calculate_quantity"
+```
+
+---
+
+### Task 4: bot.py 연결
+
+**Files:**
+- Modify: `src/bot.py:85-99` (`_open_position`)
+- Modify: `src/bot.py:165-172` (`run`)
+
+**Step 1: `run()` 메서드에 `set_base_balance` 호출 추가**
+
+`run()` 메서드를 아래로 교체:
+
+```python
+async def run(self):
+    logger.info(f"봇 시작: {self.config.symbol}, 레버리지 {self.config.leverage}x")
+    await self._recover_position()
+    balance = await self.exchange.get_balance()
+    self.risk.set_base_balance(balance)
+    logger.info(f"기준 잔고 설정: {balance:.2f} USDT (동적 증거금 비율 기준점)")
+    await self.stream.start(
+        api_key=self.config.api_key,
+        api_secret=self.config.api_secret,
+    )
+```
+
+**Step 2: `_open_position()` 메서드에 동적 비율 적용**
+
+`_open_position()` 내부 `quantity` 계산 부분을 수정:
+
+```python
+async def _open_position(self, signal: str, df):
+    balance = await self.exchange.get_balance()
+    price = df["close"].iloc[-1]
+    margin_ratio = self.risk.get_dynamic_margin_ratio(balance)
+    quantity = self.exchange.calculate_quantity(
+        balance=balance, price=price, leverage=self.config.leverage, margin_ratio=margin_ratio
+    )
+    logger.info(f"포지션 크기: 잔고={balance:.2f} USDT, 증거금비율={margin_ratio:.1%}, 수량={quantity}")
+    # 이하 기존 코드 유지 (stop_loss, take_profit, place_order 등)
+```
+
+**Step 3: 전체 테스트 실행**
+
+```bash
+pytest tests/ -v
+```
+
+Expected: 전체 PASS
+
+**Step 4: Commit**
+
+```bash
+git add src/bot.py
+git commit -m "feat: apply dynamic margin ratio in bot position sizing"
+```
+
+---
+
+### Task 5: 기존 risk_per_trade 참조 정리
+
+**Files:**
+- Search: 프로젝트 전체에서 `risk_per_trade` 참조 확인
+
+**Step 1: 잔여 참조 검색**
+
+```bash
+grep -r "risk_per_trade" src/ tests/ .env
+```
+
+Expected: 결과 없음 (이미 모두 제거됨)
+
+남아있는 경우 해당 파일에서 제거.
+
+**Step 2: 전체 테스트 최종 확인**
+
+```bash
+pytest tests/ -v
+```
+
+Expected: 전체 PASS
+
+**Step 3: Commit**
+
+```bash
+git add -A
+git commit -m "chore: remove unused risk_per_trade references"
+```
+
+---
+
+## 검증 체크리스트
+
+- [ ] `pytest tests/test_risk_manager.py` — 5개 PASS
+- [ ] `pytest tests/test_exchange.py` — 3개 PASS
+- [ ] `pytest tests/` — 전체 PASS
+- [ ] `.env`에 `MARGIN_MAX_RATIO`, `MARGIN_MIN_RATIO`, `MARGIN_DECAY_RATE` 존재
+- [ ] `.env`에 `RISK_PER_TRADE` 없음
+- [ ] 봇 시작 로그에 "기준 잔고 설정: XX USDT" 출력
+- [ ] 포지션 진입 로그에 "증거금비율=50.0%" 출력 (잔고 22 USDT 기준)

docs/plans/2026-03-01-lgbm-improvement.md

@@ -0,0 +1,251 @@
+# LightGBM 예측력 개선 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 현재 AUC 0.54 수준의 LightGBM 모델을 피처 정규화 + 강한 시간 가중치 + Walk-Forward 검증 세 가지를 순서대로 적용해 AUC 0.57+ 로 끌어올린다.
+
+**Architecture:**
+- `src/dataset_builder.py`에 rolling z-score 정규화를 추가해 레짐 변화에 강한 피처를 만든다.
+- `scripts/train_model.py`에 Walk-Forward 검증 루프를 추가해 실제 예측력을 정확히 측정한다.
+- 1년치 `combined_1m.parquet` 데이터를 decay=4.0 이상의 강한 시간 가중치로 학습해 샘플 수와 최신성을 동시에 확보한다.
+
+**Tech Stack:** LightGBM, pandas, numpy, scikit-learn, Python 3.13
+
+---
+
+## 배경: 현재 문제 진단 결과
+
+| 데이터 | 구간별 독립 AUC | 전체 80/20 AUC |
+|--------|----------------|----------------|
+| combined 1년 | 0.49~0.51 (전 구간 동일) | 0.49 |
+| xrpusdt 3개월 | 0.49~0.58 (구간 편차 큼) | 0.54 |
+
+**핵심 원인 두 가지:**
+1. `xrp_btc_rs` 같은 절대값 피처가 Q1=0.86 → Q4=3.68로 4배 변동 → 모델이 스케일 변화에 혼란
+2. 학습셋(과거)이 검증셋(최근)을 설명 못 함 → Walk-Forward로 실제 예측력 측정 필요
+
+---
+
+## Task 1: 피처 정규화 개선 (rolling z-score)
+
+**Files:**
+- Modify: `src/dataset_builder.py` — `_calc_features_vectorized()` 함수 내부
+
+**목표:** 절대값 피처(`atr_pct`, `vol_ratio`, `xrp_btc_rs`, `xrp_eth_rs`, `ret_1/3/5`, `btc_ret_1/3/5`, `eth_ret_1/3/5`)를 rolling 200 window z-score로 정규화해서 레짐 변화에 무관하게 만든다.
+
+**Step 1: 정규화 헬퍼 함수 추가**
+
+`_calc_features_vectorized()` 함수 시작 부분에 추가:
+
+```python
+def _rolling_zscore(arr: np.ndarray, window: int = 200) -> np.ndarray:
+    """rolling window z-score 정규화. window 미만 구간은 0으로 채운다."""
+    s = pd.Series(arr)
+    mean = s.rolling(window, min_periods=window).mean()
+    std  = s.rolling(window, min_periods=window).std()
+    z = (s - mean) / std.replace(0, np.nan)
+    return z.fillna(0).values.astype(np.float32)
+```
+
+**Step 2: 절대값 피처에 정규화 적용**
+
+`result` DataFrame 생성 시 다음 피처를 정규화 버전으로 교체:
+
+```python
+# 기존
+"atr_pct":   atr_pct.astype(np.float32),
+"vol_ratio": vol_ratio.astype(np.float32),
+"ret_1":     ret_1.astype(np.float32),
+"ret_3":     ret_3.astype(np.float32),
+"ret_5":     ret_5.astype(np.float32),
+
+# 변경 후
+"atr_pct":   _rolling_zscore(atr_pct),
+"vol_ratio": _rolling_zscore(vol_ratio),
+"ret_1":     _rolling_zscore(ret_1),
+"ret_3":     _rolling_zscore(ret_3),
+"ret_5":     _rolling_zscore(ret_5),
+```
+
+BTC/ETH 피처도 동일하게:
+```python
+"btc_ret_1": _rolling_zscore(btc_r1), "btc_ret_3": _rolling_zscore(btc_r3), ...
+"xrp_btc_rs": _rolling_zscore(xrp_btc_rs), "xrp_eth_rs": _rolling_zscore(xrp_eth_rs),
+```
+
+**Step 3: 검증**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+.venv/bin/python -c "
+from src.dataset_builder import generate_dataset_vectorized
+import pandas as pd
+df = pd.read_parquet('data/combined_1m.parquet')
+base = ['open','high','low','close','volume']
+btc = df[[c+'_btc' for c in base]].copy(); btc.columns = base
+eth = df[[c+'_eth' for c in base]].copy(); eth.columns = base
+ds = generate_dataset_vectorized(df[base].copy(), btc_df=btc, eth_df=eth, time_weight_decay=0)
+print(ds[['atr_pct','vol_ratio','xrp_btc_rs']].describe())
+"
+```
+
+기대 결과: `atr_pct`, `vol_ratio`, `xrp_btc_rs` 모두 mean≈0, std≈1 범위
+
+---
+
+## Task 2: Walk-Forward 검증 함수 추가
+
+**Files:**
+- Modify: `scripts/train_model.py` — `train()` 함수 뒤에 `walk_forward_auc()` 함수 추가 및 `main()` 에 `--wf` 플래그 추가
+
+**목표:** 시계열 순서를 지키면서 n_splits번 학습/검증을 반복해 실제 미래 예측력의 평균 AUC를 측정한다.
+
+**Step 1: walk_forward_auc 함수 추가**
+
+`train()` 함수 바로 아래에 추가:
+
+```python
+def walk_forward_auc(
+    data_path: str,
+    time_weight_decay: float = 2.0,
+    n_splits: int = 5,
+    train_ratio: float = 0.6,
+) -> None:
+    """Walk-Forward 검증: 슬라이딩 윈도우로 n_splits번 학습/검증 반복."""
+    import warnings
+    from sklearn.metrics import roc_auc_score
+
+    print(f"\n=== Walk-Forward 검증 ({n_splits}폴드) ===")
+    df_raw = pd.read_parquet(data_path)
+    base_cols = ["open", "high", "low", "close", "volume"]
+    btc_df = eth_df = None
+    if "close_btc" in df_raw.columns:
+        btc_df = df_raw[[c + "_btc" for c in base_cols]].copy(); btc_df.columns = base_cols
+    if "close_eth" in df_raw.columns:
+        eth_df = df_raw[[c + "_eth" for c in base_cols]].copy(); eth_df.columns = base_cols
+    df = df_raw[base_cols].copy()
+
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df,
+                                          time_weight_decay=time_weight_decay)
+    actual_feature_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    X = dataset[actual_feature_cols].values
+    y = dataset["label"].values
+    w = dataset["sample_weight"].values
+    n = len(dataset)
+
+    step = int(n * (1 - train_ratio) / n_splits)
+    train_end_start = int(n * train_ratio)
+
+    aucs = []
+    for i in range(n_splits):
+        tr_end = train_end_start + i * step
+        val_end = tr_end + step
+        if val_end > n:
+            break
+
+        X_tr, y_tr, w_tr = X[:tr_end], y[:tr_end], w[:tr_end]
+        X_val, y_val = X[tr_end:val_end], y[tr_end:val_end]
+
+        pos_idx = np.where(y_tr == 1)[0]
+        neg_idx = np.where(y_tr == 0)[0]
+        if len(neg_idx) > len(pos_idx):
+            np.random.seed(42)
+            neg_idx = np.random.choice(neg_idx, size=len(pos_idx), replace=False)
+        idx = np.sort(np.concatenate([pos_idx, neg_idx]))
+
+        model = lgb.LGBMClassifier(
+            n_estimators=500, learning_rate=0.05, num_leaves=31,
+            min_child_samples=15, subsample=0.8, colsample_bytree=0.8,
+            reg_alpha=0.05, reg_lambda=0.1, random_state=42, verbose=-1,
+        )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model.fit(X_tr[idx], y_tr[idx], sample_weight=w_tr[idx])
+
+        proba = model.predict_proba(X_val)[:, 1]
+        if len(np.unique(y_val)) < 2:
+            auc = 0.5
+        else:
+            auc = roc_auc_score(y_val, proba)
+        aucs.append(auc)
+        print(f"  폴드 {i+1}/{n_splits}: 학습={tr_end}, 검증={tr_end}~{val_end} ({step}개), AUC={auc:.4f}")
+
+    print(f"\n  Walk-Forward 평균 AUC: {np.mean(aucs):.4f} ± {np.std(aucs):.4f}")
+    print(f"  폴드별: {[round(a,4) for a in aucs]}")
+```
+
+**Step 2: main()에 --wf 플래그 추가**
+
+```python
+parser.add_argument("--wf", action="store_true", help="Walk-Forward 검증 실행")
+parser.add_argument("--wf-splits", type=int, default=5)
+
+# args 처리 부분
+if args.wf:
+    walk_forward_auc(args.data, time_weight_decay=args.decay, n_splits=args.wf_splits)
+else:
+    train(args.data, time_weight_decay=args.decay)
+```
+
+**Step 3: 검증 실행**
+
+```bash
+# xrpusdt 3개월 Walk-Forward
+.venv/bin/python scripts/train_model.py --data data/xrpusdt_1m.parquet --decay 2.0 --wf
+
+# combined 1년 Walk-Forward
+.venv/bin/python scripts/train_model.py --data data/combined_1m.parquet --decay 2.0 --wf
+```
+
+기대 결과: 폴드별 AUC가 0.50~0.58 범위, 평균 0.52+
+
+---
+
+## Task 3: 강한 시간 가중치 + 1년 데이터 최적화
+
+**Files:**
+- Modify: `scripts/train_model.py` — `train()` 함수 내 `--decay` 기본값 및 권장값 주석
+
+**목표:** `combined_1m.parquet`에서 decay=4.0~5.0으로 최근 3개월에 집중하되 1년치 패턴도 참고한다.
+
+**Step 1: decay 값별 AUC 비교 스크립트 실행**
+
+```bash
+for decay in 1.0 2.0 3.0 4.0 5.0; do
+    echo "=== decay=$decay ==="
+    .venv/bin/python scripts/train_model.py --data data/combined_1m.parquet --decay $decay --wf --wf-splits 3 2>&1 | grep "Walk-Forward 평균"
+done
+```
+
+**Step 2: 최적 decay 값으로 최종 학습**
+
+Walk-Forward 평균 AUC가 가장 높은 decay 값으로:
+
+```bash
+.venv/bin/python scripts/train_model.py --data data/combined_1m.parquet --decay <최적값>
+```
+
+**Step 3: 결과 확인**
+
+```bash
+.venv/bin/python -c "import json; log=json.load(open('models/training_log.json')); [print(e) for e in log[-3:]]"
+```
+
+---
+
+## 예상 결과
+
+| 개선 단계 | 예상 AUC |
+|-----------|---------|
+| 현재 (3개월, 기본) | 0.54 |
+| + rolling z-score 정규화 | 0.54~0.56 |
+| + Walk-Forward로 정확한 측정 | 측정 정확도 향상 |
+| + decay=4.0, 1년 데이터 | 0.55~0.58 |
+
+---
+
+## 주의사항
+
+- `_rolling_zscore`는 `dataset_builder.py` 내부에서만 사용 (실시간 봇 경로 `ml_features.py`는 건드리지 않음)
+- Walk-Forward는 `--wf` 플래그로만 실행, 기본 `train()`은 그대로 유지
+- rolling window=200은 약 3~4시간치 1분봉 → 단기 레짐 변화 반영

docs/plans/2026-03-01-oi-nan-epsilon-precision-threshold.md

@@ -0,0 +1,463 @@
+# OI NaN 마스킹 / 분모 epsilon / 정밀도 우선 임계값 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** OI 데이터 결측 구간을 np.nan으로 처리하고, 분모 연산을 1e-8 패턴으로 통일하며, 임계값 탐색을 정밀도 우선(최소 재현율 조건부)으로 변경한다.
+
+**Architecture:**
+- `dataset_builder.py`: OI/펀딩비 nan 마스킹 + 분모 epsilon 통일 + `_rolling_zscore`의 nan-safe 처리
+- `mlx_filter.py`: `fit()` 정규화 시 `np.nanmean`/`np.nanstd` + `nan_to_num` 적용
+- `train_model.py`: 임계값 탐색 함수를 `precision_recall_curve` 기반으로 교체
+- `train_mlx_model.py`: 동일한 임계값 탐색 함수 적용
+
+**Tech Stack:** numpy, pandas, scikit-learn(precision_recall_curve), lightgbm, mlx
+
+---
+
+### Task 1: `dataset_builder.py` — OI/펀딩비 nan 마스킹
+
+**Files:**
+- Modify: `src/dataset_builder.py:261-268`
+- Test: `tests/test_dataset_builder.py`
+
+**Step 1: 기존 테스트 실행 (기준선 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py -v
+```
+Expected: 기존 테스트 전부 PASS (변경 전 기준선)
+
+**Step 2: OI nan 마스킹 테스트 작성**
+
+`tests/test_dataset_builder.py`에 아래 테스트 추가:
+
+```python
+def test_oi_nan_masking_no_column():
+    """oi_change 컬럼이 없으면 전체가 nan이어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    # 최소한의 OHLCV 데이터 (지표 계산에 충분한 길이)
+    n = 100
+    np.random.seed(0)
+    df = pd.DataFrame({
+        "open":   np.random.uniform(1, 2, n),
+        "high":   np.random.uniform(2, 3, n),
+        "low":    np.random.uniform(0.5, 1, n),
+        "close":  np.random.uniform(1, 2, n),
+        "volume": np.random.uniform(1000, 5000, n),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    # oi_change 컬럼이 없으면 oi_change 피처는 전부 nan이어야 함
+    # (rolling zscore 후에도 nan이 전파되어야 함)
+    assert feat["oi_change"].isna().all(), "oi_change 컬럼 없을 때 전부 nan이어야 함"
+
+
+def test_oi_nan_masking_with_zeros():
+    """oi_change 컬럼이 있어도 0.0 구간은 nan으로 마스킹되어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 100
+    np.random.seed(0)
+    df = pd.DataFrame({
+        "open":      np.random.uniform(1, 2, n),
+        "high":      np.random.uniform(2, 3, n),
+        "low":       np.random.uniform(0.5, 1, n),
+        "close":     np.random.uniform(1, 2, n),
+        "volume":    np.random.uniform(1000, 5000, n),
+        "oi_change": np.concatenate([np.zeros(50), np.random.uniform(-0.1, 0.1, 50)]),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    # 앞 50개 구간은 0이었으므로 nan으로 마스킹 → rolling zscore 후에도 nan 전파
+    # 뒤 50개 구간은 실제 값이 있으므로 일부는 유한값이어야 함
+    assert feat["oi_change"].iloc[50:].notna().any(), "실제 OI 값 구간에 유한값이 있어야 함"
+```
+
+**Step 3: 테스트 실행 (FAIL 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py::test_oi_nan_masking_no_column tests/test_dataset_builder.py::test_oi_nan_masking_with_zeros -v
+```
+Expected: FAIL (현재 0.0으로 채우므로 isna().all()이 False)
+
+**Step 4: `dataset_builder.py` 수정**
+
+`src/dataset_builder.py` 261~268줄을 아래로 교체:
+
+```python
+    # OI 변화율 / 펀딩비 피처
+    # 컬럼 없으면 전체 nan, 있으면 0.0 구간(데이터 미제공 구간)을 nan으로 마스킹
+    # LightGBM은 nan을 자체 처리; MLX는 fit()에서 nanmean/nanstd + nan_to_num 처리
+    if "oi_change" in d.columns:
+        oi_raw = np.where(d["oi_change"].values == 0.0, np.nan, d["oi_change"].values)
+    else:
+        oi_raw = np.full(len(d), np.nan)
+
+    if "funding_rate" in d.columns:
+        fr_raw = np.where(d["funding_rate"].values == 0.0, np.nan, d["funding_rate"].values)
+    else:
+        fr_raw = np.full(len(d), np.nan)
+
+    result["oi_change"]    = _rolling_zscore(oi_raw.astype(np.float64))
+    result["funding_rate"] = _rolling_zscore(fr_raw.astype(np.float64))
+```
+
+**Step 5: `_rolling_zscore` nan-safe 처리 확인 및 수정**
+
+`src/dataset_builder.py` `_rolling_zscore` 함수 (118~128줄)를 nan-safe하게 수정:
+
+```python
+def _rolling_zscore(arr: np.ndarray, window: int = 288) -> np.ndarray:
+    """rolling window z-score 정규화. nan은 전파된다(nan-safe).
+    15분봉 기준 3일(288캔들) 윈도우. min_periods=1로 초반 데이터도 활용."""
+    s = pd.Series(arr.astype(np.float64))
+    r = s.rolling(window=window, min_periods=1)
+    mean = r.mean()   # pandas rolling은 nan을 자동으로 건너뜀
+    std  = r.std(ddof=0)
+    std  = std.where(std >= 1e-8, other=1e-8)
+    z = (s - mean) / std
+    return z.values.astype(np.float32)
+```
+
+> 참고: pandas `rolling().mean()`은 기본적으로 nan을 건너뛰므로 별도 처리 불필요.
+> nan 입력 → nan 출력이 자연스럽게 전파됨.
+
+**Step 6: 테스트 재실행 (PASS 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py -v
+```
+Expected: 모든 테스트 PASS
+
+**Step 7: 커밋**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "feat: OI/펀딩비 결측 구간을 np.nan으로 마스킹 (0.0 → nan)"
+```
+
+---
+
+### Task 2: `dataset_builder.py` — 분모 epsilon 통일
+
+**Files:**
+- Modify: `src/dataset_builder.py:157-168`
+- Test: `tests/test_dataset_builder.py`
+
+**Step 1: epsilon 통일 테스트 작성**
+
+`tests/test_dataset_builder.py`에 추가:
+
+```python
+def test_epsilon_no_division_by_zero():
+    """bb_range=0, close=0, vol_ma20=0 극단값에서 nan/inf가 발생하지 않아야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 100
+    # close를 모두 같은 값으로 → bb_range=0 유발
+    df = pd.DataFrame({
+        "open":   np.ones(n),
+        "high":   np.ones(n),
+        "low":    np.ones(n),
+        "close":  np.ones(n),
+        "volume": np.ones(n),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    numeric_cols = feat.select_dtypes(include=[np.number]).columns
+    assert not feat[numeric_cols].isin([np.inf, -np.inf]).any().any(), \
+        "inf 값이 있으면 안 됨"
+```
+
+**Step 2: 테스트 실행 (기준선)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py::test_epsilon_no_division_by_zero -v
+```
+
+**Step 3: `_calc_features_vectorized` 분모 epsilon 통일**
+
+`src/dataset_builder.py` 157~168줄을 아래로 교체:
+
+```python
+    bb_range = bb_upper - bb_lower
+    bb_pct = (close - bb_lower) / (bb_range + 1e-8)
+
+    ema_align = np.where(
+        (ema9 > ema21) & (ema21 > ema50),  1,
+        np.where(
+            (ema9 < ema21) & (ema21 < ema50), -1, 0
+        )
+    ).astype(np.float32)
+
+    atr_pct   = atr / (close + 1e-8)
+    vol_ratio = volume / (vol_ma20 + 1e-8)
+```
+
+그리고 상대강도 계산 (246~247줄):
+
+```python
+        xrp_btc_rs_raw = (xrp_r1 / (btc_r1 + 1e-8)).astype(np.float32)
+        xrp_eth_rs_raw = (xrp_r1 / (eth_r1 + 1e-8)).astype(np.float32)
+```
+
+**Step 4: 테스트 재실행**
+
+```bash
+python -m pytest tests/test_dataset_builder.py -v
+```
+Expected: 모든 테스트 PASS
+
+**Step 5: 커밋**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "refactor: 분모 연산을 1e-8 epsilon 패턴으로 통일"
+```
+
+---
+
+### Task 3: `mlx_filter.py` — nan-safe 정규화
+
+**Files:**
+- Modify: `src/mlx_filter.py:140-145`
+- Test: `tests/test_mlx_filter.py`
+
+**Step 1: nan-safe 정규화 테스트 작성**
+
+`tests/test_mlx_filter.py`에 추가:
+
+```python
+def test_fit_with_nan_features():
+    """oi_change 피처에 nan이 포함된 경우 학습이 정상 완료되어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.mlx_filter import MLXFilter
+    from src.ml_features import FEATURE_COLS
+
+    n = 300
+    np.random.seed(42)
+    X = pd.DataFrame(
+        np.random.randn(n, len(FEATURE_COLS)).astype(np.float32),
+        columns=FEATURE_COLS,
+    )
+    # oi_change 앞 절반을 nan으로
+    X["oi_change"] = np.where(np.arange(n) < n // 2, np.nan, X["oi_change"])
+    y = pd.Series((np.random.rand(n) > 0.5).astype(np.float32))
+
+    model = MLXFilter(input_dim=len(FEATURE_COLS), hidden_dim=32, epochs=3)
+    model.fit(X, y)  # nan 있어도 예외 없이 완료되어야 함
+
+    proba = model.predict_proba(X)
+    assert not np.any(np.isnan(proba)), "예측 확률에 nan이 없어야 함"
+    assert proba.min() >= 0.0 and proba.max() <= 1.0
+```
+
+**Step 2: 테스트 실행 (FAIL 확인)**
+
+```bash
+python -m pytest tests/test_mlx_filter.py::test_fit_with_nan_features -v
+```
+Expected: FAIL (현재 nan이 그대로 들어가 loss=nan 발생)
+
+**Step 3: `mlx_filter.py` fit() 정규화 수정**
+
+`src/mlx_filter.py` 140~145줄을 아래로 교체:
+
+```python
+        X_np = X[FEATURE_COLS].values.astype(np.float32)
+        y_np = y.values.astype(np.float32)
+
+        # nan-safe 정규화: nanmean/nanstd로 통계 계산 후 nan → 0.0 대치
+        # (z-score 후 0.0 = 평균값, 신경망에 줄 수 있는 가장 무난한 결측 대치값)
+        self._mean = np.nanmean(X_np, axis=0)
+        self._std  = np.nanstd(X_np, axis=0) + 1e-8
+        X_np = (X_np - self._mean) / self._std
+        X_np = np.nan_to_num(X_np, nan=0.0)
+```
+
+**Step 4: `predict_proba`도 nan_to_num 적용**
+
+`src/mlx_filter.py` 185~189줄:
+
+```python
+    def predict_proba(self, X: pd.DataFrame) -> np.ndarray:
+        X_np = X[FEATURE_COLS].values.astype(np.float32)
+        if self._trained and self._mean is not None:
+            X_np = (X_np - self._mean) / self._std
+            X_np = np.nan_to_num(X_np, nan=0.0)
+```
+
+**Step 5: 테스트 재실행**
+
+```bash
+python -m pytest tests/test_mlx_filter.py -v
+```
+Expected: 모든 테스트 PASS
+
+**Step 6: 커밋**
+
+```bash
+git add src/mlx_filter.py tests/test_mlx_filter.py
+git commit -m "fix: MLXFilter fit/predict에 nan-safe 정규화 적용 (nanmean + nan_to_num)"
+```
+
+---
+
+### Task 4: `train_model.py` — 정밀도 우선 임계값 탐색
+
+**Files:**
+- Modify: `scripts/train_model.py:236-246`
+- Test: 없음 (스크립트 레벨 변경, 수동 검증)
+
+**Step 1: `train_model.py` 임계값 탐색 교체**
+
+`scripts/train_model.py` 234~246줄을 아래로 교체:
+
+```python
+    val_proba = model.predict_proba(X_val)[:, 1]
+    auc = roc_auc_score(y_val, val_proba)
+
+    # 최적 임계값 탐색: 최소 재현율(0.15) 조건부 정밀도 최대화
+    from sklearn.metrics import precision_recall_curve
+    precisions, recalls, thresholds = precision_recall_curve(y_val, val_proba)
+    # precision_recall_curve의 마지막 원소는 (1.0, 0.0)이므로 제외
+    precisions, recalls = precisions[:-1], recalls[:-1]
+
+    MIN_RECALL = 0.15
+    valid_idx = np.where(recalls >= MIN_RECALL)[0]
+    if len(valid_idx) > 0:
+        best_idx  = valid_idx[np.argmax(precisions[valid_idx])]
+        best_thr  = float(thresholds[best_idx])
+        best_prec = float(precisions[best_idx])
+        best_rec  = float(recalls[best_idx])
+    else:
+        best_thr, best_prec, best_rec = 0.50, 0.0, 0.0
+        print(f"  [경고] recall >= {MIN_RECALL} 조건 만족 임계값 없음 → 기본값 0.50 사용")
+
+    print(f"\n검증 AUC: {auc:.4f}  |  최적 임계값: {best_thr:.4f} "
+          f"(Precision={best_prec:.3f}, Recall={best_rec:.3f})")
+    print(classification_report(y_val, (val_proba >= best_thr).astype(int), zero_division=0))
+```
+
+그리고 로그 저장 부분 (261~271줄)에 임계값 정보 추가:
+
+```python
+    log.append({
+        "date": datetime.now().isoformat(),
+        "backend": "lgbm",
+        "auc": round(auc, 4),
+        "best_threshold": round(best_thr, 4),
+        "best_precision": round(best_prec, 3),
+        "best_recall":    round(best_rec, 3),
+        "samples": len(dataset),
+        "features": len(actual_feature_cols),
+        "time_weight_decay": time_weight_decay,
+        "model_path": str(MODEL_PATH),
+    })
+```
+
+**Step 2: 수동 검증 (dry-run)**
+
+```bash
+python scripts/train_model.py --data data/combined_15m.parquet 2>&1 | tail -30
+```
+Expected: "최적 임계값: X.XXXX (Precision=X.XXX, Recall=X.XXX)" 형태 출력
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/train_model.py
+git commit -m "feat: LightGBM 임계값 탐색을 정밀도 우선(recall>=0.15 조건부)으로 변경"
+```
+
+---
+
+### Task 5: `train_mlx_model.py` — 동일한 임계값 탐색 적용
+
+**Files:**
+- Modify: `scripts/train_mlx_model.py:119-122`
+
+**Step 1: `train_mlx_model.py` 임계값 탐색 교체**
+
+`scripts/train_mlx_model.py` 119~122줄을 아래로 교체:
+
+```python
+    val_proba = model.predict_proba(X_val)
+    auc = roc_auc_score(y_val, val_proba)
+
+    # 최적 임계값 탐색: 최소 재현율(0.15) 조건부 정밀도 최대화
+    from sklearn.metrics import precision_recall_curve, classification_report
+    precisions, recalls, thresholds = precision_recall_curve(y_val, val_proba)
+    precisions, recalls = precisions[:-1], recalls[:-1]
+
+    MIN_RECALL = 0.15
+    valid_idx = np.where(recalls >= MIN_RECALL)[0]
+    if len(valid_idx) > 0:
+        best_idx  = valid_idx[np.argmax(precisions[valid_idx])]
+        best_thr  = float(thresholds[best_idx])
+        best_prec = float(precisions[best_idx])
+        best_rec  = float(recalls[best_idx])
+    else:
+        best_thr, best_prec, best_rec = 0.50, 0.0, 0.0
+        print(f"  [경고] recall >= {MIN_RECALL} 조건 만족 임계값 없음 → 기본값 0.50 사용")
+
+    print(f"\n검증 AUC: {auc:.4f}  |  최적 임계값: {best_thr:.4f} "
+          f"(Precision={best_prec:.3f}, Recall={best_rec:.3f})")
+    print(classification_report(y_val, (val_proba >= best_thr).astype(int), zero_division=0))
+```
+
+그리고 로그 저장 부분에 임계값 정보 추가:
+
+```python
+    log.append({
+        "date": datetime.now().isoformat(),
+        "backend": "mlx",
+        "auc": round(auc, 4),
+        "best_threshold": round(best_thr, 4),
+        "best_precision": round(best_prec, 3),
+        "best_recall":    round(best_rec, 3),
+        "samples": len(dataset),
+        "train_sec": round(t3 - t2, 1),
+        "time_weight_decay": time_weight_decay,
+        "model_path": str(MLX_MODEL_PATH),
+    })
+```
+
+**Step 2: 커밋**
+
+```bash
+git add scripts/train_mlx_model.py
+git commit -m "feat: MLX 임계값 탐색을 정밀도 우선(recall>=0.15 조건부)으로 변경"
+```
+
+---
+
+### Task 6: 전체 테스트 통과 확인
+
+**Step 1: 전체 테스트 실행**
+
+```bash
+python -m pytest tests/ -v --tb=short 2>&1 | tail -40
+```
+Expected: 모든 테스트 PASS
+
+**Step 2: 최종 커밋 (필요 시)**
+
+```bash
+git add -A
+git commit -m "chore: OI nan 마스킹 / epsilon 통일 / 정밀도 우선 임계값 전체 통합"
+```

docs/plans/2026-03-02-adx-filter-design.md

@@ -0,0 +1,150 @@
+# ADX 횡보장 필터 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** ADX < 25일 때 get_signal()에서 즉시 HOLD를 반환하여 횡보장 진입을 차단한다.
+
+**Architecture:** `calculate_all()`에서 `pandas_ta.adx()`로 ADX 컬럼을 추가하고, `get_signal()`에서 가중치 계산 전 ADX < 25이면 early-return HOLD. NaN(초기 캔들)은 기존 로직으로 폴백.
+
+**Tech Stack:** pandas-ta (이미 사용 중), pytest
+
+---
+
+### Task 1: ADX 계산 테스트 추가
+
+**Files:**
+- Test: `tests/test_indicators.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_adx_column_exists(sample_df):
+    """calculate_all()이 adx 컬럼을 생성하는지 확인."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    assert "adx" in df.columns
+    valid = df["adx"].dropna()
+    assert (valid >= 0).all()
+```
+
+`tests/test_indicators.py`에 위 테스트 함수를 추가한다.
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_indicators.py::test_adx_column_exists -v`
+Expected: FAIL — `"adx" not in df.columns`
+
+---
+
+### Task 2: calculate_all()에 ADX 계산 추가
+
+**Files:**
+- Modify: `src/indicators.py:46-48` (vol_ma20 계산 바로 앞에 추가)
+
+**Step 3: Write minimal implementation**
+
+`calculate_all()`의 Stochastic RSI 계산 뒤, `vol_ma20` 계산 앞에 추가:
+
+```python
+        # ADX (14) — 횡보장 필터
+        adx_df = ta.adx(df["high"], df["low"], df["close"], length=14)
+        df["adx"] = adx_df["ADX_14"]
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_indicators.py::test_adx_column_exists -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/indicators.py tests/test_indicators.py
+git commit -m "feat: add ADX calculation to indicators"
+```
+
+---
+
+### Task 3: ADX 필터 테스트 추가 (차단 케이스)
+
+**Files:**
+- Test: `tests/test_indicators.py`
+
+**Step 6: Write the failing test**
+
+```python
+def test_adx_filter_blocks_low_adx(sample_df):
+    """ADX < 25일 때 가중치와 무관하게 HOLD를 반환해야 한다."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    # ADX를 강제로 낮은 값으로 설정
+    df["adx"] = 15.0
+    signal = ind.get_signal(df)
+    assert signal == "HOLD"
+```
+
+**Step 7: Run test to verify it fails**
+
+Run: `pytest tests/test_indicators.py::test_adx_filter_blocks_low_adx -v`
+Expected: FAIL — signal이 LONG 또는 SHORT 반환 (ADX 필터 미구현)
+
+---
+
+### Task 4: ADX 필터 테스트 추가 (NaN 폴백 케이스)
+
+**Files:**
+- Test: `tests/test_indicators.py`
+
+**Step 8: Write the failing test**
+
+```python
+def test_adx_nan_falls_through(sample_df):
+    """ADX가 NaN(초기 캔들)이면 기존 가중치 로직으로 폴백해야 한다."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    df["adx"] = float("nan")
+    signal = ind.get_signal(df)
+    # NaN이면 차단하지 않고 기존 로직 실행 → LONG/SHORT/HOLD 중 하나
+    assert signal in ("LONG", "SHORT", "HOLD")
+```
+
+**Step 9: Run test to verify it passes (이 테스트는 현재도 통과)**
+
+Run: `pytest tests/test_indicators.py::test_adx_nan_falls_through -v`
+Expected: PASS (ADX 컬럼이 무시되므로 기존 로직 그대로)
+
+---
+
+### Task 5: get_signal()에 ADX early-return 구현
+
+**Files:**
+- Modify: `src/indicators.py:51-56` (get_signal 메서드 시작부)
+
+**Step 10: Write minimal implementation**
+
+`get_signal()` 메서드의 `last = df.iloc[-1]` 바로 다음에 추가:
+
+```python
+        # ADX 횡보장 필터: ADX < 25이면 추세 부재로 판단하여 진입 차단
+        adx = last.get("adx", None)
+        if adx is not None and not pd.isna(adx) and adx < 25:
+            logger.debug(f"ADX 필터: {adx:.1f} < 25 — HOLD")
+            return "HOLD"
+```
+
+**Step 11: Run all ADX-related tests**
+
+Run: `pytest tests/test_indicators.py -k "adx" -v`
+Expected: 3 tests PASS
+
+**Step 12: Run full test suite to check for regressions**
+
+Run: `pytest tests/ -v --tb=short`
+Expected: All tests PASS
+
+**Step 13: Commit**
+
+```bash
+git add src/indicators.py tests/test_indicators.py
+git commit -m "feat: add ADX filter to block sideways market entries"
+```

docs/plans/2026-03-02-hold-negative-sampling-design.md

@@ -0,0 +1,91 @@
+# HOLD Negative Sampling + Stratified Undersampling Design
+
+## Problem
+
+현재 ML 파이프라인의 학습 데이터가 535개로 매우 적음.
+`dataset_builder.py`에서 시그널(LONG/SHORT) 발생 캔들만 라벨링하기 때문.
+전체 ~35,000개 캔들 중 98.5%가 HOLD로 버려짐.
+
+## Goal
+
+- HOLD 캔들을 negative sample로 활용하여 학습 데이터 증가
+- Train-Serve Skew 방지 (학습/추론 데이터 분포 일치)
+- 기존 signal 샘플은 하나도 버리지 않는 계층적 샘플링
+
+## Design
+
+### 1. dataset_builder.py — HOLD Negative Sampling
+
+**변경 위치**: `generate_dataset_vectorized()` (line 360-421)
+
+**현재 로직**:
+```python
+valid_rows = (
+    (signal_arr != "HOLD") &  # ← 시그널 캔들만 선택
+    ...
+)
+```
+
+**변경 로직**:
+1. 기존 시그널 캔들(LONG/SHORT) 라벨링은 그대로 유지
+2. HOLD 캔들 중 랜덤 샘플링 (시그널 수의 NEGATIVE_RATIO배)
+3. HOLD 캔들: label=0, side=랜덤(50% LONG / 50% SHORT), signal_strength=0
+4. `source` 컬럼 추가: "signal" | "hold_negative" (계층적 샘플링에 사용)
+
+**파라미터**:
+```python
+NEGATIVE_RATIO = 5    # 시그널 대비 HOLD 샘플 비율
+RANDOM_SEED = 42      # 재현성
+```
+
+**예상 데이터량**:
+- 시그널: ~535개 (Win ~200, Loss ~335)
+- HOLD negative: ~2,675개
+- 총 학습 데이터: ~3,210개
+
+### 2. train_model.py — Stratified Undersampling
+
+**변경 위치**: `train()` 함수 내 언더샘플링 블록 (line 241-257)
+
+**현재 로직**: 양성:음성 = 1:1 블라인드 언더샘플링
+```python
+if len(neg_idx) > len(pos_idx):
+    neg_idx = np.random.choice(neg_idx, size=len(pos_idx), replace=False)
+```
+
+**변경 로직**: 계층적 3-class 샘플링
+```python
+# 1. Signal 샘플(source="signal") 전수 유지 (Win + Loss 모두)
+# 2. HOLD negative(source="hold_negative")에서만 샘플링
+#    → 양성(Win) 수와 동일한 수만큼 샘플링
+# 최종: Win ~200 + Signal Loss ~335 + HOLD ~200 = ~735개
+```
+
+**효과**:
+- Signal 샘플 보존율: 100% (Win/Loss 모두)
+- HOLD negative: 적절한 양만 추가
+- Train-Serve Skew 없음 (추론 시 signal_strength ≥ 3에서만 호출)
+
+### 3. 런타임 (변경 없음)
+
+- `bot.py`: 시그널 발생 시에만 ML 필터 호출 (기존 동일)
+- `ml_filter.py`: `should_enter()` 그대로
+- `ml_features.py`: `FEATURE_COLS` 그대로
+- `label_builder.py`: 기존 SL/TP 룩어헤드 로직 그대로
+
+## Test Cases
+
+### 필수 테스트
+1. **HOLD negative label 검증**: HOLD negative 샘플의 label이 전부 0인지 확인
+2. **Signal 보존 검증**: 계층적 샘플링 후 source="signal" 샘플이 하나도 버려지지 않았는지 확인
+
+### 기존 테스트 호환성
+- 기존 dataset_builder 관련 테스트가 깨지지 않도록 보장
+
+## File Changes
+
+| File | Change |
+|------|--------|
+| `src/dataset_builder.py` | HOLD negative sampling, source 컬럼 추가 |
+| `scripts/train_model.py` | 계층적 샘플링으로 교체 |
+| `tests/test_dataset_builder.py` (or equivalent) | 2개 테스트 케이스 추가 |

docs/plans/2026-03-02-hold-negative-sampling-plan.md

@@ -0,0 +1,432 @@
+# HOLD Negative Sampling Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** HOLD 캔들을 negative sample로 추가하고 계층적 언더샘플링을 도입하여 ML 학습 데이터를 535 → ~3,200개로 증가시킨다.
+
+**Architecture:** `dataset_builder.py`에서 시그널 캔들 외에 HOLD 캔들을 label=0으로 추가 샘플링하고, `source` 컬럼("signal"/"hold_negative")으로 구분한다. 학습 시 signal 샘플은 전수 유지, HOLD negative에서만 양성 수 만큼 샘플링하는 계층적 언더샘플링을 적용한다.
+
+**Tech Stack:** Python, NumPy, pandas, LightGBM, pytest
+
+---
+
+### Task 1: dataset_builder.py — HOLD Negative Sampling 추가
+
+**Files:**
+- Modify: `src/dataset_builder.py:360-421` (generate_dataset_vectorized 함수)
+- Test: `tests/test_dataset_builder.py`
+
+**Step 1: Write the failing tests**
+
+`tests/test_dataset_builder.py` 끝에 2개 테스트 추가:
+
+```python
+def test_hold_negative_labels_are_all_zero(sample_df):
+    """HOLD negative 샘플의 label은 전부 0이어야 한다."""
+    result = generate_dataset_vectorized(sample_df, negative_ratio=3)
+    if len(result) > 0 and "source" in result.columns:
+        hold_neg = result[result["source"] == "hold_negative"]
+        if len(hold_neg) > 0:
+            assert (hold_neg["label"] == 0).all(), \
+                f"HOLD negative 중 label != 0인 샘플 존재: {hold_neg['label'].value_counts().to_dict()}"
+
+
+def test_signal_samples_preserved_after_sampling(sample_df):
+    """계층적 샘플링 후 source='signal' 샘플이 하나도 버려지지 않아야 한다."""
+    # negative_ratio=0이면 기존 동작 (signal만), >0이면 HOLD 추가
+    result_signal_only = generate_dataset_vectorized(sample_df, negative_ratio=0)
+    result_with_hold   = generate_dataset_vectorized(sample_df, negative_ratio=3)
+
+    if len(result_with_hold) > 0 and "source" in result_with_hold.columns:
+        signal_count = (result_with_hold["source"] == "signal").sum()
+        assert signal_count == len(result_signal_only), \
+            f"Signal 샘플 손실: 원본={len(result_signal_only)}, 유지={signal_count}"
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_dataset_builder.py::test_hold_negative_labels_are_all_zero tests/test_dataset_builder.py::test_signal_samples_preserved_after_sampling -v`
+Expected: FAIL — `generate_dataset_vectorized()` does not accept `negative_ratio` parameter
+
+**Step 3: Implement HOLD negative sampling in generate_dataset_vectorized**
+
+`src/dataset_builder.py`의 `generate_dataset_vectorized()` 함수를 수정한다.
+시그니처에 `negative_ratio: int = 0` 파라미터를 추가하고, HOLD 캔들 샘플링 로직을 삽입한다.
+
+수정 대상: `generate_dataset_vectorized` 함수 전체.
+
+```python
+def generate_dataset_vectorized(
+    df: pd.DataFrame,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+    time_weight_decay: float = 0.0,
+    negative_ratio: int = 0,
+) -> pd.DataFrame:
+    """
+    전체 시계열을 1회 계산해 학습 데이터셋을 생성한다.
+
+    negative_ratio: 시그널 샘플 대비 HOLD negative 샘플 비율.
+        0이면 기존 동작 (시그널만). 5면 시그널의 5배만큼 HOLD 샘플 추가.
+    """
+    print("  [1/3] 전체 시계열 지표 계산 (1회)...")
+    d = _calc_indicators(df)
+
+    print("  [2/3] 신호 마스킹 및 피처 추출...")
+    signal_arr = _calc_signals(d)
+    feat_all   = _calc_features_vectorized(d, signal_arr, btc_df=btc_df, eth_df=eth_df)
+
+    # 신호 발생 + NaN 없음 + 미래 데이터 충분한 인덱스만
+    OPTIONAL_COLS = {"oi_change", "funding_rate"}
+    available_cols_for_nan_check = [
+        c for c in FEATURE_COLS
+        if c in feat_all.columns and c not in OPTIONAL_COLS
+    ]
+    base_valid = (
+        (~feat_all[available_cols_for_nan_check].isna().any(axis=1).values) &
+        (np.arange(len(d)) >= WARMUP) &
+        (np.arange(len(d)) < len(d) - LOOKAHEAD)
+    )
+
+    # --- 시그널 캔들 (기존 로직) ---
+    sig_valid = base_valid & (signal_arr != "HOLD")
+    sig_idx = np.where(sig_valid)[0]
+    print(f"  신호 발생 인덱스: {len(sig_idx):,}개")
+
+    print("  [3/3] 레이블 계산...")
+    labels, valid_mask = _calc_labels_vectorized(d, feat_all, sig_idx)
+
+    final_sig_idx = sig_idx[valid_mask]
+    available_feature_cols = [c for c in FEATURE_COLS if c in feat_all.columns]
+    feat_signal = feat_all.iloc[final_sig_idx][available_feature_cols].copy()
+    feat_signal["label"] = labels
+    feat_signal["source"] = "signal"
+
+    # --- HOLD negative 캔들 ---
+    if negative_ratio > 0 and len(final_sig_idx) > 0:
+        hold_valid = base_valid & (signal_arr == "HOLD")
+        hold_candidates = np.where(hold_valid)[0]
+        n_neg = min(len(hold_candidates), len(final_sig_idx) * negative_ratio)
+
+        if n_neg > 0:
+            rng = np.random.default_rng(42)
+            hold_idx = rng.choice(hold_candidates, size=n_neg, replace=False)
+            hold_idx = np.sort(hold_idx)
+
+            feat_hold = feat_all.iloc[hold_idx][available_feature_cols].copy()
+            feat_hold["label"] = 0
+            feat_hold["source"] = "hold_negative"
+
+            # HOLD 캔들은 시그널이 없으므로 side를 랜덤 할당 (50:50)
+            sides = rng.integers(0, 2, size=len(feat_hold)).astype(np.float32)
+            feat_hold["side"] = sides
+            # signal_strength는 이미 0 (시그널 미발생이므로)
+
+            print(f"  HOLD negative 추가: {len(feat_hold):,}개 "
+                  f"(비율 1:{negative_ratio})")
+
+            feat_final = pd.concat([feat_signal, feat_hold], ignore_index=True)
+            # 시간 순서 복원 (원본 인덱스 기반 정렬)
+            original_order = np.concatenate([final_sig_idx, hold_idx])
+            sort_order = np.argsort(original_order)
+            feat_final = feat_final.iloc[sort_order].reset_index(drop=True)
+        else:
+            feat_final = feat_signal.reset_index(drop=True)
+    else:
+        feat_final = feat_signal.reset_index(drop=True)
+
+    # 시간 가중치
+    n = len(feat_final)
+    if time_weight_decay > 0 and n > 1:
+        weights = np.exp(time_weight_decay * np.linspace(0.0, 1.0, n)).astype(np.float32)
+        weights /= weights.mean()
+        print(f"  시간 가중치 적용 (decay={time_weight_decay}): "
+              f"min={weights.min():.3f}, max={weights.max():.3f}")
+    else:
+        weights = np.ones(n, dtype=np.float32)
+
+    feat_final["sample_weight"] = weights
+
+    total_sig = (feat_final["source"] == "signal").sum() if "source" in feat_final.columns else len(feat_final)
+    total_hold = (feat_final["source"] == "hold_negative").sum() if "source" in feat_final.columns else 0
+    print(f"  최종 데이터셋: {n:,}개 (시그널={total_sig:,}, HOLD={total_hold:,})")
+
+    return feat_final
+```
+
+**Step 4: Run the new tests to verify they pass**
+
+Run: `pytest tests/test_dataset_builder.py::test_hold_negative_labels_are_all_zero tests/test_dataset_builder.py::test_signal_samples_preserved_after_sampling -v`
+Expected: PASS
+
+**Step 5: Run all existing dataset_builder tests to verify no regressions**
+
+Run: `pytest tests/test_dataset_builder.py -v`
+Expected: All existing tests PASS (기존 동작은 negative_ratio=0 기본값으로 유지)
+
+**Step 6: Commit**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "feat: add HOLD negative sampling to dataset builder"
+```
+
+---
+
+### Task 2: 계층적 언더샘플링 헬퍼 함수
+
+**Files:**
+- Modify: `src/dataset_builder.py` (파일 끝에 헬퍼 추가)
+- Test: `tests/test_dataset_builder.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_stratified_undersample_preserves_signal():
+    """stratified_undersample은 signal 샘플을 전수 유지해야 한다."""
+    from src.dataset_builder import stratified_undersample
+
+    y      = np.array([1, 0, 0, 0, 0, 0, 0, 0, 1, 0])
+    source = np.array(["signal", "signal", "signal", "hold_negative",
+                        "hold_negative", "hold_negative", "hold_negative",
+                        "hold_negative", "signal", "signal"])
+
+    idx = stratified_undersample(y, source, seed=42)
+
+    # signal 인덱스: 0, 1, 2, 8, 9 → 전부 포함
+    signal_indices = np.where(source == "signal")[0]
+    for si in signal_indices:
+        assert si in idx, f"signal 인덱스 {si}가 누락됨"
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_dataset_builder.py::test_stratified_undersample_preserves_signal -v`
+Expected: FAIL — `stratified_undersample` 함수 미존재
+
+**Step 3: Implement stratified_undersample**
+
+`src/dataset_builder.py` 끝에 추가:
+
+```python
+def stratified_undersample(
+    y: np.ndarray,
+    source: np.ndarray,
+    seed: int = 42,
+) -> np.ndarray:
+    """Signal 샘플 전수 유지 + HOLD negative만 양성 수 만큼 샘플링.
+
+    Args:
+        y: 라벨 배열 (0 or 1)
+        source: 소스 배열 ("signal" or "hold_negative")
+        seed: 랜덤 시드
+
+    Returns:
+        정렬된 인덱스 배열 (학습에 사용할 행 인덱스)
+    """
+    pos_idx = np.where(y == 1)[0]                                    # Signal Win
+    sig_neg_idx = np.where((y == 0) & (source == "signal"))[0]       # Signal Loss
+    hold_neg_idx = np.where(source == "hold_negative")[0]             # HOLD negative
+
+    # HOLD negative에서 양성 수 만큼만 샘플링
+    n_hold = min(len(hold_neg_idx), len(pos_idx))
+    rng = np.random.default_rng(seed)
+    if n_hold > 0:
+        hold_sampled = rng.choice(hold_neg_idx, size=n_hold, replace=False)
+    else:
+        hold_sampled = np.array([], dtype=np.intp)
+
+    return np.sort(np.concatenate([pos_idx, sig_neg_idx, hold_sampled]))
+```
+
+**Step 4: Run tests**
+
+Run: `pytest tests/test_dataset_builder.py::test_stratified_undersample_preserves_signal -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "feat: add stratified_undersample helper function"
+```
+
+---
+
+### Task 3: train_model.py — 계층적 언더샘플링 적용
+
+**Files:**
+- Modify: `scripts/train_model.py:229-257` (train 함수)
+- Modify: `scripts/train_model.py:356-391` (walk_forward_auc 함수)
+
+**Step 1: Update train() function**
+
+`scripts/train_model.py`에서 `dataset_builder`에서 `stratified_undersample`을 import하고,
+`train()` 함수의 언더샘플링 블록을 교체한다.
+
+import 수정 (line 25):
+```python
+from src.dataset_builder import generate_dataset_vectorized, stratified_undersample
+```
+
+`train()` 함수에서 데이터셋 생성 호출에 `negative_ratio=5` 추가 (line 217):
+```python
+    dataset = generate_dataset_vectorized(
+        df, btc_df=btc_df, eth_df=eth_df,
+        time_weight_decay=time_weight_decay,
+        negative_ratio=5,
+    )
+```
+
+source 배열 추출 추가 (line 231 부근, w 다음):
+```python
+    source = dataset["source"].values if "source" in dataset.columns else np.full(len(X), "signal")
+```
+
+언더샘플링 블록 교체 (line 241-257):
+```python
+    # --- 계층적 샘플링: signal 전수 유지, HOLD negative만 양성 수 만큼 ---
+    source_train = source[:split]
+    balanced_idx = stratified_undersample(y_train.values, source_train, seed=42)
+
+    X_train = X_train.iloc[balanced_idx]
+    y_train = y_train.iloc[balanced_idx]
+    w_train = w_train[balanced_idx]
+
+    sig_count = (source_train[balanced_idx] == "signal").sum()
+    hold_count = (source_train[balanced_idx] == "hold_negative").sum()
+    print(f"\n계층적 샘플링 후 학습 데이터: {len(X_train)}개 "
+          f"(Signal={sig_count}, HOLD={hold_count}, "
+          f"양성={int(y_train.sum())}, 음성={int((y_train==0).sum())})")
+    print(f"검증 데이터: {len(X_val)}개 (양성={int(y_val.sum())}, 음성={int((y_val==0).sum())})")
+```
+
+**Step 2: Update walk_forward_auc() function**
+
+`walk_forward_auc()` 함수에서도 동일하게 적용.
+
+dataset 생성 (line 356-358)에 `negative_ratio=5` 추가:
+```python
+    dataset = generate_dataset_vectorized(
+        df, btc_df=btc_df, eth_df=eth_df,
+        time_weight_decay=time_weight_decay,
+        negative_ratio=5,
+    )
+```
+
+source 배열 추출 (line 362 부근):
+```python
+    source = dataset["source"].values if "source" in dataset.columns else np.full(n, "signal")
+```
+
+폴드 내 언더샘플링 교체 (line 381-386):
+```python
+        source_tr = source[:tr_end]
+        bal_idx = stratified_undersample(y_tr, source_tr, seed=42)
+```
+
+**Step 3: Run training to verify**
+
+Run: `python scripts/train_model.py --data data/combined_15m.parquet --decay 2.0`
+Expected: 학습 샘플 수 대폭 증가 확인 (기존 ~535 → ~3,200)
+
+**Step 4: Commit**
+
+```bash
+git add scripts/train_model.py
+git commit -m "feat: apply stratified undersampling to training pipeline"
+```
+
+---
+
+### Task 4: tune_hyperparams.py — 계층적 언더샘플링 적용
+
+**Files:**
+- Modify: `scripts/tune_hyperparams.py:41-81` (load_dataset)
+- Modify: `scripts/tune_hyperparams.py:88-144` (_walk_forward_cv)
+- Modify: `scripts/tune_hyperparams.py:151-206` (make_objective)
+- Modify: `scripts/tune_hyperparams.py:213-244` (measure_baseline)
+- Modify: `scripts/tune_hyperparams.py:370-449` (main)
+
+**Step 1: Update load_dataset to return source**
+
+import 수정 (line 34):
+```python
+from src.dataset_builder import generate_dataset_vectorized, stratified_undersample
+```
+
+`load_dataset()` 시그니처와 반환값 수정:
+```python
+def load_dataset(data_path: str) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+```
+
+dataset 생성에 `negative_ratio=5` 추가 (line 66):
+```python
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=0.0, negative_ratio=5)
+```
+
+source 추출 추가 (line 74 부근, w 다음):
+```python
+    source = dataset["source"].values if "source" in dataset.columns else np.full(len(dataset), "signal")
+```
+
+return 수정:
+```python
+    return X, y, w, source
+```
+
+**Step 2: Update _walk_forward_cv to accept and use source**
+
+시그니처에 source 추가:
+```python
+def _walk_forward_cv(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    source: np.ndarray,
+    params: dict,
+    ...
+```
+
+폴드 내 언더샘플링 교체 (line 117-122):
+```python
+        source_tr = source[:tr_end]
+        bal_idx = stratified_undersample(y_tr, source_tr, seed=42)
+```
+
+**Step 3: Update make_objective, measure_baseline, main**
+
+`make_objective()`: 클로저에 source 캡처, `_walk_forward_cv` 호출에 source 전달
+`measure_baseline()`: source 파라미터 추가, `_walk_forward_cv` 호출에 전달
+`main()`: `load_dataset` 반환값 4개로 변경, 하위 함수에 source 전달
+
+**Step 4: Commit**
+
+```bash
+git add scripts/tune_hyperparams.py
+git commit -m "feat: apply stratified undersampling to hyperparameter tuning"
+```
+
+---
+
+### Task 5: 전체 테스트 실행 및 검증
+
+**Step 1: Run full test suite**
+
+Run: `bash scripts/run_tests.sh`
+Expected: All tests PASS
+
+**Step 2: Run training pipeline end-to-end**
+
+Run: `python scripts/train_model.py --data data/combined_15m.parquet --decay 2.0`
+Expected:
+- 학습 샘플 ~3,200개 (기존 535)
+- "계층적 샘플링 후" 로그에 Signal/HOLD 카운트 표시
+- AUC 출력 (값 자체보다 실행 완료가 중요)
+
+**Step 3: Commit final state**
+
+```bash
+git add -A
+git commit -m "chore: verify HOLD negative sampling pipeline end-to-end"
+```

docs/plans/2026-03-02-oi-funding-accumulation.md

@@ -0,0 +1,394 @@
+# OI/펀딩비 누적 저장 (접근법 B) 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** `fetch_history.py`의 데이터 수집 방식을 덮어쓰기(Overwrite)에서 Upsert(병합)로 변경해, 매일 실행할 때마다 기존 parquet의 OI/펀딩비 0.0 구간이 실제 값으로 채워지며 고품질 데이터가 무한히 누적되도록 한다.
+
+**Architecture:**
+- `fetch_history.py`에 `--upsert` 플래그 추가 (기본값 True). 기존 parquet이 있으면 로드 후 신규 데이터와 timestamp 기준 병합(Upsert). 없으면 기존처럼 새로 생성.
+- Upsert 규칙: 기존 행의 `oi_change` / `funding_rate`가 0.0이면 신규 값으로 덮어씀. 신규 행은 그냥 추가. 중복 제거 후 시간순 정렬.
+- `train_and_deploy.sh`의 `--days` 인자를 35일로 조정 (30일 API 한도 + 5일 버퍼).
+- LXC 운영서버는 모델 파일만 받으므로 변경 없음. 맥미니의 `data/` 폴더에만 누적.
+
+**Tech Stack:** pandas, parquet (pyarrow), pytest
+
+---
+
+## Task 1: fetch_history.py — upsert_parquet() 함수 추가 및 --upsert 플래그
+
+**Files:**
+- Modify: `scripts/fetch_history.py`
+- Test: `tests/test_fetch_history.py` (신규 생성)
+
+### Step 1: 실패 테스트 작성
+
+`tests/test_fetch_history.py` 파일을 새로 만든다.
+
+```python
+"""fetch_history.py의 upsert_parquet() 함수 테스트."""
+import pandas as pd
+import numpy as np
+import pytest
+from pathlib import Path
+
+
+def _make_parquet(tmp_path: Path, rows: dict) -> Path:
+    """테스트용 parquet 파일 생성 헬퍼."""
+    df = pd.DataFrame(rows)
+    df["timestamp"] = pd.to_datetime(df["timestamp"], utc=True)
+    df = df.set_index("timestamp")
+    path = tmp_path / "test.parquet"
+    df.to_parquet(path)
+    return path
+
+
+def test_upsert_fills_zero_oi_with_real_value(tmp_path):
+    """기존 행의 oi_change=0.0이 신규 데이터의 실제 값으로 덮어써진다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00", "2026-01-01 00:15"],
+        "close": [1.0, 1.1],
+        "oi_change": [0.0, 0.0],
+        "funding_rate": [0.0, 0.0],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1],
+        "oi_change": [0.05, 0.03],
+        "funding_rate": [0.0001, 0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00", "2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert result.loc["2026-01-01 00:00+00:00", "oi_change"] == pytest.approx(0.05)
+    assert result.loc["2026-01-01 00:15+00:00", "oi_change"] == pytest.approx(0.03)
+
+
+def test_upsert_appends_new_rows(tmp_path):
+    """신규 타임스탬프 행이 기존 데이터 아래에 추가된다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00"],
+        "close": [1.0],
+        "oi_change": [0.05],
+        "funding_rate": [0.0001],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.1],
+        "oi_change": [0.03],
+        "funding_rate": [0.0002],
+    }, index=pd.to_datetime(["2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert len(result) == 2
+    assert "2026-01-01 00:15+00:00" in result.index.astype(str).tolist() or \
+           pd.Timestamp("2026-01-01 00:15", tz="UTC") in result.index
+
+
+def test_upsert_keeps_nonzero_existing_oi(tmp_path):
+    """기존 행의 oi_change가 이미 0이 아니면 덮어쓰지 않는다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00"],
+        "close": [1.0],
+        "oi_change": [0.07],   # 이미 실제 값 존재
+        "funding_rate": [0.0003],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0],
+        "oi_change": [0.05],   # 다른 값으로 덮어쓰려 해도
+        "funding_rate": [0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    # 기존 값(0.07)이 유지되어야 한다
+    assert result.iloc[0]["oi_change"] == pytest.approx(0.07)
+
+
+def test_upsert_no_existing_file_returns_new_df(tmp_path):
+    """기존 parquet 파일이 없으면 신규 데이터를 그대로 반환한다."""
+    from scripts.fetch_history import upsert_parquet
+
+    nonexistent_path = tmp_path / "nonexistent.parquet"
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1],
+        "oi_change": [0.05, 0.03],
+        "funding_rate": [0.0001, 0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00", "2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(nonexistent_path, new_df)
+
+    assert len(result) == 2
+    assert result.iloc[0]["oi_change"] == pytest.approx(0.05)
+
+
+def test_upsert_result_is_sorted_by_timestamp(tmp_path):
+    """결과 DataFrame이 timestamp 기준 오름차순 정렬되어 있다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:15"],
+        "close": [1.1],
+        "oi_change": [0.0],
+        "funding_rate": [0.0],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1, 1.2],
+        "oi_change": [0.05, 0.03, 0.02],
+        "funding_rate": [0.0001, 0.0001, 0.0002],
+    }, index=pd.to_datetime(
+        ["2026-01-01 00:00", "2026-01-01 00:15", "2026-01-01 00:30"], utc=True
+    ))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert result.index.is_monotonic_increasing
+    assert len(result) == 3
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+.venv/bin/pytest tests/test_fetch_history.py -v
+```
+
+Expected: `FAILED` — `ImportError: cannot import name 'upsert_parquet' from 'scripts.fetch_history'`
+
+### Step 3: fetch_history.py에 upsert_parquet() 함수 구현
+
+`scripts/fetch_history.py`의 `main()` 함수 바로 위에 추가한다.
+
+```python
+def upsert_parquet(path: Path | str, new_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    기존 parquet 파일에 신규 데이터를 Upsert(병합)한다.
+
+    규칙:
+    - 기존 행의 oi_change / funding_rate가 0.0이면 신규 값으로 덮어씀
+    - 기존 행의 oi_change / funding_rate가 이미 0이 아니면 유지
+    - 신규 타임스탬프 행은 그냥 추가
+    - 결과는 timestamp 기준 오름차순 정렬, 중복 제거
+
+    Args:
+        path: 기존 parquet 경로 (없으면 new_df 그대로 반환)
+        new_df: 새로 수집한 DataFrame (timestamp index)
+
+    Returns:
+        병합된 DataFrame
+    """
+    path = Path(path)
+    if not path.exists():
+        return new_df.sort_index()
+
+    existing = pd.read_parquet(path)
+
+    # timestamp index 통일 (tz-aware UTC)
+    if existing.index.tz is None:
+        existing.index = existing.index.tz_localize("UTC")
+    if new_df.index.tz is None:
+        new_df.index = new_df.index.tz_localize("UTC")
+
+    # 기존 데이터에서 oi_change / funding_rate가 0.0인 행만 신규 값으로 업데이트
+    UPSERT_COLS = ["oi_change", "funding_rate"]
+    overlap_idx = existing.index.intersection(new_df.index)
+
+    for col in UPSERT_COLS:
+        if col not in existing.columns or col not in new_df.columns:
+            continue
+        # 겹치는 행 중 기존 값이 0.0인 경우에만 신규 값으로 교체
+        zero_mask = existing.loc[overlap_idx, col] == 0.0
+        update_idx = overlap_idx[zero_mask]
+        if len(update_idx) > 0:
+            existing.loc[update_idx, col] = new_df.loc[update_idx, col]
+
+    # 신규 타임스탬프 행 추가 (기존에 없는 것만)
+    new_only_idx = new_df.index.difference(existing.index)
+    if len(new_only_idx) > 0:
+        existing = pd.concat([existing, new_df.loc[new_only_idx]])
+
+    return existing.sort_index()
+```
+
+### Step 4: main()에 --upsert 플래그 추가 및 저장 로직 수정
+
+`main()` 함수의 `parser` 정의 부분에 인자 추가:
+
+```python
+parser.add_argument(
+    "--no-upsert", action="store_true",
+    help="기존 parquet을 Upsert하지 않고 새로 덮어씀 (기본: Upsert 활성화)",
+)
+```
+
+그리고 단일 심볼 저장 부분:
+```python
+# 기존:
+df.to_parquet(args.output)
+
+# 변경:
+if not args.no_upsert:
+    df = upsert_parquet(args.output, df)
+df.to_parquet(args.output)
+```
+
+멀티 심볼 저장 부분도 동일하게:
+```python
+# 기존:
+merged.to_parquet(output)
+
+# 변경:
+if not args.no_upsert:
+    merged = upsert_parquet(output, merged)
+merged.to_parquet(output)
+```
+
+### Step 5: 테스트 통과 확인
+
+```bash
+.venv/bin/pytest tests/test_fetch_history.py -v
+```
+
+Expected: 전체 PASS
+
+### Step 6: 커밋
+
+```bash
+git add scripts/fetch_history.py tests/test_fetch_history.py
+git commit -m "feat: add upsert_parquet to accumulate OI/funding data incrementally"
+```
+
+---
+
+## Task 2: train_and_deploy.sh — 데이터 수집 일수 35일로 조정
+
+**Files:**
+- Modify: `scripts/train_and_deploy.sh`
+
+### Step 1: 현재 상태 확인
+
+`scripts/train_and_deploy.sh`에서 `--days 365` 부분을 찾는다.
+
+### Step 2: 수정
+
+`train_and_deploy.sh`에서 `fetch_history.py` 호출 부분을 수정한다.
+
+기존:
+```bash
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/combined_15m.parquet
+```
+
+변경:
+```bash
+# OI/펀딩비 API 제한(30일) + 버퍼 5일 = 35일치 신규 수집 후 기존 parquet에 Upsert
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 35 \
+    --output data/combined_15m.parquet
+```
+
+**이유**: 매일 실행 시 35일치만 새로 가져와 기존 누적 parquet에 Upsert한다.
+- 최초 실행 시(`data/combined_15m.parquet` 없음): 35일치로 시작
+- 이후 매일: 35일치 신규 데이터로 기존 파일의 0.0 구간을 채우고 최신 행 추가
+- 시간이 지날수록 OI/펀딩비 실제 값이 있는 구간이 1달 → 2달 → ... 로 늘어남
+
+**주의**: 최초 실행 시 캔들 데이터도 35일치만 있으므로, 첫 실행은 수동으로
+`--days 365 --no-upsert`로 전체 캔들을 먼저 수집하는 것을 권장한다.
+README에 이 내용을 추가한다.
+
+### Step 3: 커밋
+
+```bash
+git add scripts/train_and_deploy.sh
+git commit -m "feat: fetch 35 days for daily upsert instead of overwriting 365 days"
+```
+
+---
+
+## Task 3: 전체 테스트 통과 확인 및 README 업데이트
+
+### Step 1: 전체 테스트 실행
+
+```bash
+.venv/bin/pytest tests/ --ignore=tests/test_mlx_filter.py --ignore=tests/test_database.py -v
+```
+
+Expected: 전체 PASS
+
+### Step 2: README.md 업데이트
+
+**"ML 모델 학습" 섹션의 "전체 파이프라인 (권장)" 부분 아래에 아래 내용을 추가한다:**
+
+```markdown
+### 최초 실행 (캔들 전체 수집)
+
+처음 실행하거나 `data/combined_15m.parquet`가 없을 때는 전체 캔들을 먼저 수집한다.
+이후 매일 크론탭이 `train_and_deploy.sh`를 실행하면 35일치 신규 데이터가 자동으로 Upsert된다.
+
+```bash
+# 최초 1회: 1년치 캔들 전체 수집 (OI/펀딩비는 최근 30일만 실제 값, 나머지 0.0)
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --no-upsert \
+    --output data/combined_15m.parquet
+
+# 이후 매일 자동 실행 (크론탭 또는 train_and_deploy.sh):
+# 35일치 신규 데이터를 기존 파일에 Upsert → OI/펀딩비 0.0 구간이 야금야금 채워짐
+bash scripts/train_and_deploy.sh
+```
+```
+
+**"주요 기능" 섹션에 아래 항목 추가:**
+
+```markdown
+- **OI/펀딩비 누적 학습**: 매일 35일치 신규 데이터를 기존 parquet에 Upsert. 시간이 지날수록 실제 OI/펀딩비 값이 있는 학습 구간이 1달 → 2달 → 반년으로 늘어남
+```
+
+### Step 3: 최종 커밋
+
+```bash
+git add README.md
+git commit -m "docs: document OI/funding incremental accumulation strategy"
+```
+
+---
+
+## 구현 후 검증 포인트
+
+1. `data/combined_15m.parquet`에서 날짜별 `oi_change` 값 분포 확인:
+   ```python
+   import pandas as pd
+   df = pd.read_parquet("data/combined_15m.parquet")
+   print(df["oi_change"].describe())
+   print((df["oi_change"] == 0.0).sum(), "개 행이 아직 0.0")
+   ```
+2. 매일 실행 후 0.0 행 수가 줄어드는지 확인
+3. 모델 학습 시 `oi_change` / `funding_rate` 피처의 non-zero 비율이 증가하는지 확인
+
+---
+
+## 아키텍처 메모 (LXC 운영서버 관련)
+
+- **LXC 운영서버(10.1.10.24)**: 변경 없음. 모델 파일(`*.pkl` / `*.onnx`)만 받음
+- **맥미니**: `data/combined_15m.parquet`를 누적 보관. 매일 35일치 Upsert 후 학습
+- **데이터 흐름**: 맥미니 parquet 누적 → 학습 → 모델 → LXC 배포
+- **봇 실시간 OI/펀딩비**: 접근법 A(Task 1~4)에서 이미 구현됨. LXC 봇이 캔들마다 REST API로 실시간 수집

docs/plans/2026-03-02-optuna-hyperparam-tuning-design.md

@@ -0,0 +1,184 @@
+# Optuna 하이퍼파라미터 자동 튜닝 설계 문서
+
+**작성일:** 2026-03-02  
+**목표:** 봇 운영 로그/학습 결과를 바탕으로 LightGBM 하이퍼파라미터를 Optuna로 자동 탐색하고, 사람이 결과를 확인·승인한 후 재학습에 반영하는 수동 트리거 파이프라인 구축
+
+---
+
+## 배경 및 동기
+
+현재 `train_model.py`의 LightGBM 파라미터는 하드코딩되어 있다. 봇 성능이 저하되거나 데이터가 축적될 때마다 사람이 직접 파라미터를 조정해야 한다. 이를 Optuna로 자동화하되, 과적합 위험을 방지하기 위해 **사람이 결과를 먼저 확인하고 승인하는 구조**를 유지한다.
+
+---
+
+## 구현 범위 (2단계)
+
+### 1단계 (현재): LightGBM 하이퍼파라미터 튜닝
+- `scripts/tune_hyperparams.py` 신규 생성
+- Optuna + Walk-Forward AUC 목적 함수
+- 결과를 JSON + 콘솔 리포트로 출력
+
+### 2단계 (추후): 기술 지표 파라미터 확장
+- RSI 임계값, MACD 가중치, Stochastic RSI 임계값, 거래량 배수, 진입 점수 임계값 등을 탐색 공간에 추가
+- `dataset_builder.py`의 `_calc_signals()` 파라미터화 필요
+
+---
+
+## 아키텍처
+
+```
+scripts/tune_hyperparams.py
+├── load_dataset()              ← 데이터 로드 + 벡터화 데이터셋 1회 생성 (캐싱)
+├── objective(trial, dataset)   ← Optuna trial 함수
+│   ├── trial.suggest_*()       ← 하이퍼파라미터 샘플링
+│   ├── num_leaves 상한 강제    ← 2^max_depth - 1 제약
+│   └── _walk_forward_cv()      ← Walk-Forward 교차검증 → 평균 AUC 반환
+├── run_study()                 ← Optuna study 실행 (TPESampler + MedianPruner)
+├── print_report()              ← 콘솔 리포트 출력
+└── save_results()              ← JSON 저장 (models/tune_results_YYYYMMDD_HHMMSS.json)
+```
+
+---
+
+## 탐색 공간 (소규모 데이터셋 보수적 설계)
+
+| 파라미터 | 범위 | 타입 | 근거 |
+|---|---|---|---|
+| `n_estimators` | 100 ~ 600 | int | 데이터 적을 때 500+ 트리는 과적합 |
+| `learning_rate` | 0.01 ~ 0.2 | float (log) | 낮을수록 일반화 유리 |
+| `max_depth` | 2 ~ 7 | int | 트리 깊이 상한 강제 |
+| `num_leaves` | 7 ~ min(31, 2^max_depth-1) | int | **핵심**: leaf-wise 과적합 방지 |
+| `min_child_samples` | 10 ~ 50 | int | 리프당 최소 샘플 수 |
+| `subsample` | 0.5 ~ 1.0 | float | 행 샘플링 |
+| `colsample_bytree` | 0.5 ~ 1.0 | float | 열 샘플링 |
+| `reg_alpha` | 1e-4 ~ 1.0 | float (log) | L1 정규화 |
+| `reg_lambda` | 1e-4 ~ 1.0 | float (log) | L2 정규화 |
+| `time_weight_decay` | 0.5 ~ 4.0 | float | 시간 가중치 강도 |
+
+### 핵심 제약: `num_leaves <= 2^max_depth - 1`
+
+LightGBM은 leaf-wise 성장 전략을 사용하므로, `num_leaves`가 `2^max_depth - 1`을 초과하면 `max_depth` 제약이 무의미해진다. trial 내에서 `max_depth`를 먼저 샘플링한 후 `num_leaves` 상한을 동적으로 계산하여 강제한다.
+
+```python
+max_depth = trial.suggest_int("max_depth", 2, 7)
+max_leaves = min(31, 2 ** max_depth - 1)
+num_leaves = trial.suggest_int("num_leaves", 7, max_leaves)
+```
+
+---
+
+## 목적 함수: Walk-Forward AUC
+
+기존 `train_model.py`의 `walk_forward_auc()` 로직을 재활용한다. 데이터셋은 study 시작 전 1회만 생성하여 모든 trial이 공유한다 (속도 최적화).
+
+```
+전체 데이터셋 (N개 샘플)
+├── 폴드 1: 학습[0:60%] → 검증[60%:68%]
+├── 폴드 2: 학습[0:68%] → 검증[68%:76%]
+├── 폴드 3: 학습[0:76%] → 검증[76%:84%]
+├── 폴드 4: 학습[0:84%] → 검증[84%:92%]
+└── 폴드 5: 학습[0:92%] → 검증[92%:100%]
+목적 함수 = 5폴드 평균 AUC (최대화)
+```
+
+### Pruning (조기 종료)
+
+`MedianPruner` 적용: 각 폴드 완료 후 중간 AUC를 Optuna에 보고. 이전 trial들의 중앙값보다 낮으면 나머지 폴드를 건너뛰고 trial 종료. 전체 탐색 시간 ~40% 단축 효과.
+
+---
+
+## 출력 형식
+
+### 콘솔 리포트
+
+```
+============================================================
+  Optuna 튜닝 완료 | 50 trials | 소요: 28분 42초
+============================================================
+  Best AUC : 0.6234 (Trial #31)
+  Baseline : 0.5891 (현재 train_model.py 고정값)
+  개선폭   : +0.0343 (+5.8%)
+------------------------------------------------------------
+  Best Parameters:
+    n_estimators      : 320
+    learning_rate     : 0.0412
+    max_depth         : 4
+    num_leaves        : 15
+    min_child_samples : 28
+    subsample         : 0.72
+    colsample_bytree  : 0.81
+    reg_alpha         : 0.0023
+    reg_lambda         : 0.0891
+    time_weight_decay : 2.31
+------------------------------------------------------------
+  Walk-Forward 폴드별 AUC:
+    폴드 1: 0.6102
+    폴드 2: 0.6341
+    폴드 3: 0.6198
+    폴드 4: 0.6287
+    폴드 5: 0.6241
+    평균: 0.6234 ± 0.0082
+------------------------------------------------------------
+  결과 저장: models/tune_results_20260302_143022.json
+  다음 단계: python scripts/train_model.py --tuned-params models/tune_results_20260302_143022.json
+============================================================
+```
+
+### JSON 저장 (`models/tune_results_YYYYMMDD_HHMMSS.json`)
+
+```json
+{
+  "timestamp": "2026-03-02T14:30:22",
+  "n_trials": 50,
+  "elapsed_sec": 1722,
+  "baseline_auc": 0.5891,
+  "best_trial": {
+    "number": 31,
+    "auc": 0.6234,
+    "fold_aucs": [0.6102, 0.6341, 0.6198, 0.6287, 0.6241],
+    "params": { ... }
+  },
+  "all_trials": [ ... ]
+}
+```
+
+---
+
+## 사용법
+
+```bash
+# 기본 실행 (50 trials, 5폴드)
+python scripts/tune_hyperparams.py
+
+# 빠른 테스트 (10 trials, 3폴드)
+python scripts/tune_hyperparams.py --trials 10 --folds 3
+
+# 데이터 경로 지정
+python scripts/tune_hyperparams.py --data data/combined_15m.parquet --trials 100
+```
+
+---
+
+## 파일 변경 목록
+
+| 파일 | 변경 | 설명 |
+|---|---|---|
+| `scripts/tune_hyperparams.py` | **신규 생성** | Optuna 튜닝 스크립트 |
+| `requirements.txt` | **수정** | `optuna` 의존성 추가 |
+| `README.md` | **수정** | 튜닝 사용법 섹션 추가 |
+
+---
+
+## 향후 확장 (2단계)
+
+`dataset_builder.py`의 `_calc_signals()` 함수를 파라미터화하여 기술 지표 임계값도 탐색 공간에 추가:
+
+```python
+# 추가될 탐색 공간 예시
+rsi_long_threshold  = trial.suggest_int("rsi_long",  25, 40)
+rsi_short_threshold = trial.suggest_int("rsi_short", 60, 75)
+vol_surge_mult      = trial.suggest_float("vol_surge_mult", 1.2, 2.5)
+entry_threshold     = trial.suggest_int("entry_threshold", 3, 5)
+stoch_low           = trial.suggest_int("stoch_low",  10, 30)
+stoch_high          = trial.suggest_int("stoch_high", 70, 90)
+```

docs/plans/2026-03-02-optuna-hyperparam-tuning-plan.md

@@ -0,0 +1,569 @@
+# Optuna 하이퍼파라미터 자동 튜닝 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** `scripts/tune_hyperparams.py`를 신규 생성하여 Optuna + Walk-Forward AUC 기반 LightGBM 하이퍼파라미터 자동 탐색 파이프라인을 구축한다.
+
+**Architecture:** 데이터셋을 study 시작 전 1회만 생성해 캐싱하고, 각 Optuna trial에서 LightGBM 파라미터를 샘플링 → Walk-Forward 5폴드 AUC를 목적 함수로 최대화한다. `num_leaves <= 2^max_depth - 1` 제약을 코드 레벨에서 강제하여 소규모 데이터셋 과적합을 방지한다. 결과는 콘솔 리포트 + JSON 파일로 출력한다.
+
+**Tech Stack:** Python 3.11+, optuna, lightgbm, numpy, pandas, scikit-learn (기존 의존성 재활용)
+
+**설계 문서:** `docs/plans/2026-03-02-optuna-hyperparam-tuning-design.md`
+
+---
+
+## Task 1: optuna 의존성 추가
+
+**Files:**
+- Modify: `requirements.txt`
+
+**Step 1: requirements.txt에 optuna 추가**
+
+```
+optuna>=3.6.0
+```
+
+`requirements.txt` 파일 끝에 추가한다.
+
+**Step 2: 설치 확인 (로컬)**
+
+```bash
+pip install optuna
+python -c "import optuna; print(optuna.__version__)"
+```
+
+Expected: 버전 번호 출력 (예: `3.6.0`)
+
+**Step 3: Commit**
+
+```bash
+git add requirements.txt
+git commit -m "feat: add optuna dependency for hyperparameter tuning"
+```
+
+---
+
+## Task 2: `scripts/tune_hyperparams.py` 핵심 구조 생성
+
+**Files:**
+- Create: `scripts/tune_hyperparams.py`
+
+**Step 1: 파일 생성 — 전체 코드**
+
+아래 코드를 `scripts/tune_hyperparams.py`로 저장한다.
+
+```python
+"""
+Optuna를 사용한 LightGBM 하이퍼파라미터 자동 탐색.
+
+사용법:
+    python scripts/tune_hyperparams.py                          # 기본 (50 trials, 5폴드)
+    python scripts/tune_hyperparams.py --trials 10 --folds 3   # 빠른 테스트
+    python scripts/tune_hyperparams.py --data data/combined_15m.parquet --trials 100
+
+결과:
+    - 콘솔: Best Params + Walk-Forward 리포트
+    - JSON: models/tune_results_YYYYMMDD_HHMMSS.json
+"""
+import sys
+import warnings
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import argparse
+import json
+import time
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+import lightgbm as lgb
+import optuna
+from optuna.samplers import TPESampler
+from optuna.pruners import MedianPruner
+from sklearn.metrics import roc_auc_score
+
+from src.ml_features import FEATURE_COLS
+from src.dataset_builder import generate_dataset_vectorized
+
+
+# ──────────────────────────────────────────────
+# 데이터 로드 및 데이터셋 생성 (1회 캐싱)
+# ──────────────────────────────────────────────
+
+def load_dataset(data_path: str) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    parquet 로드 → 벡터화 데이터셋 생성 → (X, y, w) numpy 배열 반환.
+    study 시작 전 1회만 호출하여 모든 trial이 공유한다.
+    """
+    print(f"데이터 로드: {data_path}")
+    df_raw = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df_raw):,}, 컬럼: {list(df_raw.columns)}")
+
+    base_cols = ["open", "high", "low", "close", "volume"]
+    btc_df = eth_df = None
+
+    if "close_btc" in df_raw.columns:
+        btc_df = df_raw[[c + "_btc" for c in base_cols]].copy()
+        btc_df.columns = base_cols
+        print("BTC 피처 활성화")
+
+    if "close_eth" in df_raw.columns:
+        eth_df = df_raw[[c + "_eth" for c in base_cols]].copy()
+        eth_df.columns = base_cols
+        print("ETH 피처 활성화")
+
+    df = df_raw[base_cols].copy()
+
+    print("\n데이터셋 생성 중 (1회만 실행)...")
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=0.0)
+
+    if dataset.empty or "label" not in dataset.columns:
+        raise ValueError("데이터셋 생성 실패: 샘플 0개")
+
+    actual_feature_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    X = dataset[actual_feature_cols].values.astype(np.float32)
+    y = dataset["label"].values.astype(np.int8)
+    w = dataset["sample_weight"].values.astype(np.float32)
+
+    pos = y.sum()
+    neg = (y == 0).sum()
+    print(f"데이터셋 완성: {len(dataset):,}개 샘플 (양성={pos:.0f}, 음성={neg:.0f})")
+    print(f"사용 피처: {len(actual_feature_cols)}개\n")
+
+    return X, y, w
+
+
+# ──────────────────────────────────────────────
+# Walk-Forward 교차검증
+# ──────────────────────────────────────────────
+
+def _walk_forward_cv(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    params: dict,
+    n_splits: int,
+    train_ratio: float,
+    trial: optuna.Trial | None = None,
+) -> tuple[float, list[float]]:
+    """
+    Walk-Forward 교차검증으로 평균 AUC를 반환한다.
+    trial이 제공되면 각 폴드 후 Optuna에 중간 값을 보고하여 Pruning을 활성화한다.
+    """
+    n = len(X)
+    step = max(1, int(n * (1 - train_ratio) / n_splits))
+    train_end_start = int(n * train_ratio)
+
+    fold_aucs = []
+
+    for fold_idx in range(n_splits):
+        tr_end = train_end_start + fold_idx * step
+        val_end = tr_end + step
+        if val_end > n:
+            break
+
+        X_tr, y_tr, w_tr = X[:tr_end], y[:tr_end], w[:tr_end]
+        X_val, y_val = X[tr_end:val_end], y[tr_end:val_end]
+
+        # 클래스 불균형 처리: 언더샘플링 (시간 순서 유지)
+        pos_idx = np.where(y_tr == 1)[0]
+        neg_idx = np.where(y_tr == 0)[0]
+        if len(neg_idx) > len(pos_idx) and len(pos_idx) > 0:
+            rng = np.random.default_rng(42)
+            neg_idx = rng.choice(neg_idx, size=len(pos_idx), replace=False)
+        bal_idx = np.sort(np.concatenate([pos_idx, neg_idx]))
+
+        if len(bal_idx) < 20 or len(np.unique(y_val)) < 2:
+            fold_aucs.append(0.5)
+            continue
+
+        model = lgb.LGBMClassifier(**params, random_state=42, verbose=-1)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model.fit(X_tr[bal_idx], y_tr[bal_idx], sample_weight=w_tr[bal_idx])
+
+        proba = model.predict_proba(X_val)[:, 1]
+        auc = roc_auc_score(y_val, proba) if len(np.unique(y_val)) > 1 else 0.5
+        fold_aucs.append(auc)
+
+        # Optuna Pruning: 중간 값 보고
+        if trial is not None:
+            trial.report(float(np.mean(fold_aucs)), step=fold_idx)
+            if trial.should_prune():
+                raise optuna.TrialPruned()
+
+    mean_auc = float(np.mean(fold_aucs)) if fold_aucs else 0.5
+    return mean_auc, fold_aucs
+
+
+# ──────────────────────────────────────────────
+# Optuna 목적 함수
+# ──────────────────────────────────────────────
+
+def make_objective(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    n_splits: int,
+    train_ratio: float,
+):
+    """클로저로 데이터셋을 캡처한 목적 함수를 반환한다."""
+
+    def objective(trial: optuna.Trial) -> float:
+        # ── 하이퍼파라미터 샘플링 ──
+        n_estimators = trial.suggest_int("n_estimators", 100, 600)
+        learning_rate = trial.suggest_float("learning_rate", 0.01, 0.2, log=True)
+        max_depth = trial.suggest_int("max_depth", 2, 7)
+
+        # 핵심 제약: num_leaves <= 2^max_depth - 1 (leaf-wise 과적합 방지)
+        max_leaves_upper = min(31, 2 ** max_depth - 1)
+        num_leaves = trial.suggest_int("num_leaves", 7, max(7, max_leaves_upper))
+
+        min_child_samples = trial.suggest_int("min_child_samples", 10, 50)
+        subsample = trial.suggest_float("subsample", 0.5, 1.0)
+        colsample_bytree = trial.suggest_float("colsample_bytree", 0.5, 1.0)
+        reg_alpha = trial.suggest_float("reg_alpha", 1e-4, 1.0, log=True)
+        reg_lambda = trial.suggest_float("reg_lambda", 1e-4, 1.0, log=True)
+
+        # time_weight_decay는 데이터셋 생성 시 적용되어야 하지만,
+        # 데이터셋을 1회 캐싱하는 구조이므로 LightGBM sample_weight 스케일로 근사한다.
+        # 실제 decay 효과는 w 배열에 이미 반영되어 있으므로 스케일 파라미터로 활용한다.
+        weight_scale = trial.suggest_float("weight_scale", 0.5, 2.0)
+        w_scaled = (w * weight_scale).astype(np.float32)
+
+        params = {
+            "n_estimators": n_estimators,
+            "learning_rate": learning_rate,
+            "max_depth": max_depth,
+            "num_leaves": num_leaves,
+            "min_child_samples": min_child_samples,
+            "subsample": subsample,
+            "colsample_bytree": colsample_bytree,
+            "reg_alpha": reg_alpha,
+            "reg_lambda": reg_lambda,
+        }
+
+        mean_auc, fold_aucs = _walk_forward_cv(
+            X, y, w_scaled, params,
+            n_splits=n_splits,
+            train_ratio=train_ratio,
+            trial=trial,
+        )
+
+        # 폴드별 AUC를 user_attrs에 저장 (결과 리포트용)
+        trial.set_user_attr("fold_aucs", fold_aucs)
+
+        return mean_auc
+
+    return objective
+
+
+# ──────────────────────────────────────────────
+# 베이스라인 AUC 측정 (현재 고정 파라미터)
+# ──────────────────────────────────────────────
+
+def measure_baseline(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    n_splits: int,
+    train_ratio: float,
+) -> tuple[float, list[float]]:
+    """train_model.py의 현재 고정 파라미터로 베이스라인 AUC를 측정한다."""
+    baseline_params = {
+        "n_estimators": 500,
+        "learning_rate": 0.05,
+        "num_leaves": 31,
+        "min_child_samples": 15,
+        "subsample": 0.8,
+        "colsample_bytree": 0.8,
+        "reg_alpha": 0.05,
+        "reg_lambda": 0.1,
+        "max_depth": -1,  # 현재 train_model.py는 max_depth 미설정
+    }
+    print("베이스라인 측정 중 (현재 train_model.py 고정 파라미터)...")
+    return _walk_forward_cv(X, y, w, baseline_params, n_splits=n_splits, train_ratio=train_ratio)
+
+
+# ──────────────────────────────────────────────
+# 결과 출력 및 저장
+# ──────────────────────────────────────────────
+
+def print_report(
+    study: optuna.Study,
+    baseline_auc: float,
+    baseline_folds: list[float],
+    elapsed_sec: float,
+    output_path: Path,
+) -> None:
+    """콘솔에 최종 리포트를 출력한다."""
+    best = study.best_trial
+    best_auc = best.value
+    best_folds = best.user_attrs.get("fold_aucs", [])
+    improvement = best_auc - baseline_auc
+    improvement_pct = (improvement / baseline_auc * 100) if baseline_auc > 0 else 0.0
+
+    elapsed_min = int(elapsed_sec // 60)
+    elapsed_s = int(elapsed_sec % 60)
+
+    sep = "=" * 62
+    dash = "-" * 62
+
+    print(f"\n{sep}")
+    print(f"  Optuna 튜닝 완료 | {len(study.trials)} trials | 소요: {elapsed_min}분 {elapsed_s}초")
+    print(sep)
+    print(f"  Best AUC  : {best_auc:.4f}  (Trial #{best.number})")
+    print(f"  Baseline  : {baseline_auc:.4f}  (현재 train_model.py 고정값)")
+    sign = "+" if improvement >= 0 else ""
+    print(f"  개선폭    : {sign}{improvement:.4f} ({sign}{improvement_pct:.1f}%)")
+    print(dash)
+    print("  Best Parameters:")
+    for k, v in best.params.items():
+        if isinstance(v, float):
+            print(f"    {k:<22}: {v:.6f}")
+        else:
+            print(f"    {k:<22}: {v}")
+    print(dash)
+    print("  Walk-Forward 폴드별 AUC (Best Trial):")
+    for i, auc in enumerate(best_folds, 1):
+        print(f"    폴드 {i}: {auc:.4f}")
+    if best_folds:
+        print(f"    평균: {np.mean(best_folds):.4f} ± {np.std(best_folds):.4f}")
+    print(dash)
+    print("  Baseline 폴드별 AUC:")
+    for i, auc in enumerate(baseline_folds, 1):
+        print(f"    폴드 {i}: {auc:.4f}")
+    if baseline_folds:
+        print(f"    평균: {np.mean(baseline_folds):.4f} ± {np.std(baseline_folds):.4f}")
+    print(dash)
+    print(f"  결과 저장: {output_path}")
+    print(f"  다음 단계: python scripts/train_model.py --tuned-params {output_path}")
+    print(sep)
+
+
+def save_results(
+    study: optuna.Study,
+    baseline_auc: float,
+    baseline_folds: list[float],
+    elapsed_sec: float,
+    data_path: str,
+) -> Path:
+    """결과를 JSON 파일로 저장하고 경로를 반환한다."""
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    output_path = Path(f"models/tune_results_{timestamp}.json")
+    output_path.parent.mkdir(exist_ok=True)
+
+    best = study.best_trial
+
+    all_trials = []
+    for t in study.trials:
+        if t.state == optuna.trial.TrialState.COMPLETE:
+            all_trials.append({
+                "number": t.number,
+                "auc": round(t.value, 6),
+                "fold_aucs": [round(a, 6) for a in t.user_attrs.get("fold_aucs", [])],
+                "params": {k: (round(v, 6) if isinstance(v, float) else v) for k, v in t.params.items()},
+            })
+
+    result = {
+        "timestamp": datetime.now().isoformat(),
+        "data_path": data_path,
+        "n_trials_total": len(study.trials),
+        "n_trials_complete": len(all_trials),
+        "elapsed_sec": round(elapsed_sec, 1),
+        "baseline": {
+            "auc": round(baseline_auc, 6),
+            "fold_aucs": [round(a, 6) for a in baseline_folds],
+        },
+        "best_trial": {
+            "number": best.number,
+            "auc": round(best.value, 6),
+            "fold_aucs": [round(a, 6) for a in best.user_attrs.get("fold_aucs", [])],
+            "params": {k: (round(v, 6) if isinstance(v, float) else v) for k, v in best.params.items()},
+        },
+        "all_trials": all_trials,
+    }
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2, ensure_ascii=False)
+
+    return output_path
+
+
+# ──────────────────────────────────────────────
+# 메인
+# ──────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="Optuna LightGBM 하이퍼파라미터 튜닝")
+    parser.add_argument("--data",   default="data/combined_15m.parquet", help="학습 데이터 경로")
+    parser.add_argument("--trials", type=int, default=50,  help="Optuna trial 수 (기본: 50)")
+    parser.add_argument("--folds",  type=int, default=5,   help="Walk-Forward 폴드 수 (기본: 5)")
+    parser.add_argument("--train-ratio", type=float, default=0.6, help="학습 구간 비율 (기본: 0.6)")
+    parser.add_argument("--no-baseline", action="store_true", help="베이스라인 측정 건너뜀")
+    args = parser.parse_args()
+
+    # 1. 데이터셋 로드 (1회)
+    X, y, w = load_dataset(args.data)
+
+    # 2. 베이스라인 측정
+    if args.no_baseline:
+        baseline_auc, baseline_folds = 0.0, []
+        print("베이스라인 측정 건너뜀 (--no-baseline)")
+    else:
+        baseline_auc, baseline_folds = measure_baseline(X, y, w, args.folds, args.train_ratio)
+        print(f"베이스라인 AUC: {baseline_auc:.4f} (폴드별: {[round(a,4) for a in baseline_folds]})\n")
+
+    # 3. Optuna study 실행
+    optuna.logging.set_verbosity(optuna.logging.WARNING)
+    sampler = TPESampler(seed=42)
+    pruner  = MedianPruner(n_startup_trials=5, n_warmup_steps=2)
+    study   = optuna.create_study(
+        direction="maximize",
+        sampler=sampler,
+        pruner=pruner,
+        study_name="lgbm_wf_auc",
+    )
+
+    objective = make_objective(X, y, w, n_splits=args.folds, train_ratio=args.train_ratio)
+
+    print(f"Optuna 탐색 시작: {args.trials} trials, {args.folds}폴드 Walk-Forward")
+    print("(진행 상황은 trial 완료마다 출력됩니다)\n")
+
+    start_time = time.time()
+
+    def _progress_callback(study: optuna.Study, trial: optuna.trial.FrozenTrial):
+        if trial.state == optuna.trial.TrialState.COMPLETE:
+            best_so_far = study.best_value
+            print(
+                f"  Trial #{trial.number:3d} | AUC={trial.value:.4f} "
+                f"| Best={best_so_far:.4f} "
+                f"| {trial.params.get('num_leaves', '?')}leaves "
+                f"depth={trial.params.get('max_depth', '?')}"
+            )
+        elif trial.state == optuna.trial.TrialState.PRUNED:
+            print(f"  Trial #{trial.number:3d} | PRUNED")
+
+    study.optimize(
+        objective,
+        n_trials=args.trials,
+        callbacks=[_progress_callback],
+        show_progress_bar=False,
+    )
+
+    elapsed = time.time() - start_time
+
+    # 4. 결과 저장 및 출력
+    output_path = save_results(study, baseline_auc, baseline_folds, elapsed, args.data)
+    print_report(study, baseline_auc, baseline_folds, elapsed, output_path)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+**Step 2: 문법 오류 확인**
+
+```bash
+cd /path/to/cointrader
+python -c "import ast; ast.parse(open('scripts/tune_hyperparams.py').read()); print('문법 OK')"
+```
+
+Expected: `문법 OK`
+
+**Step 3: Commit**
+
+```bash
+git add scripts/tune_hyperparams.py
+git commit -m "feat: add Optuna Walk-Forward AUC hyperparameter tuning script"
+```
+
+---
+
+## Task 3: 동작 검증 (빠른 테스트)
+
+**Files:**
+- Read: `scripts/tune_hyperparams.py`
+
+**Step 1: 빠른 테스트 실행 (10 trials, 3폴드)**
+
+```bash
+python scripts/tune_hyperparams.py --trials 10 --folds 3 --no-baseline
+```
+
+Expected:
+- 오류 없이 10 trials 완료
+- `models/tune_results_YYYYMMDD_HHMMSS.json` 생성
+- 콘솔에 Best Params 출력
+
+**Step 2: JSON 결과 확인**
+
+```bash
+cat models/tune_results_*.json | python -m json.tool | head -40
+```
+
+Expected: `best_trial.auc`, `best_trial.params` 등 구조 확인
+
+**Step 3: Commit**
+
+```bash
+git add models/tune_results_*.json
+git commit -m "test: verify Optuna tuning pipeline with 10 trials"
+```
+
+---
+
+## Task 4: README.md 업데이트
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: ML 모델 학습 섹션에 튜닝 사용법 추가**
+
+`README.md`의 `## ML 모델 학습` 섹션 아래에 다음 내용을 추가한다:
+
+```markdown
+### 하이퍼파라미터 자동 튜닝 (Optuna)
+
+봇 성능이 저하되거나 데이터가 충분히 축적되었을 때 Optuna로 최적 파라미터를 탐색합니다.
+결과를 확인하고 직접 승인한 후 재학습에 반영하는 **수동 트리거** 방식입니다.
+
+```bash
+# 기본 실행 (50 trials, 5폴드 Walk-Forward, ~30분)
+python scripts/tune_hyperparams.py
+
+# 빠른 테스트 (10 trials, 3폴드, ~5분)
+python scripts/tune_hyperparams.py --trials 10 --folds 3
+
+# 결과 확인 후 승인하면 재학습
+python scripts/train_model.py
+```
+
+결과는 `models/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다.
+Best Params와 베이스라인 대비 개선폭을 확인하고 직접 판단하세요.
+```
+
+**Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add Optuna hyperparameter tuning usage to README"
+```
+
+---
+
+## 검증 체크리스트
+
+- [ ] `python -c "import optuna"` 오류 없음
+- [ ] `python scripts/tune_hyperparams.py --trials 10 --folds 3 --no-baseline` 오류 없이 완료
+- [ ] `models/tune_results_*.json` 파일 생성 확인
+- [ ] JSON에 `best_trial.params`, `best_trial.fold_aucs` 포함 확인
+- [ ] 콘솔 리포트에 Best AUC, 폴드별 AUC, 파라미터 출력 확인
+- [ ] `num_leaves <= 2^max_depth - 1` 제약이 모든 trial에서 지켜지는지 JSON으로 확인
+
+---
+
+## 향후 확장 (2단계 — 별도 플랜)
+
+파이프라인 안정화 후 `dataset_builder.py`의 `_calc_signals()` 함수를 파라미터화하여 기술 지표 임계값(RSI, Stochastic RSI, 거래량 배수, 진입 점수 임계값)을 탐색 공간에 추가한다.

docs/plans/2026-03-02-realtime-oi-funding-features.md

@@ -0,0 +1,399 @@
+# 실시간 OI/펀딩비 피처 수집 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 실시간 봇에서 캔들 마감 시 바이낸스 REST API로 현재 OI와 펀딩비를 수집해 ML 피처에 실제 값을 넣어 학습-추론 불일치(train-serve skew)를 해소한다.
+
+**Architecture:**
+- `exchange.py`에 `get_open_interest()`, `get_funding_rate()` 메서드 추가 (REST 호출)
+- `bot.py`의 `process_candle()`에서 캔들 마감 시 두 값을 조회하고 `build_features()` 호출 시 전달
+- `ml_features.py`의 `build_features()`가 `oi_change`, `funding_rate` 파라미터를 받아 실제 값으로 채우도록 수정
+
+**Tech Stack:** python-binance AsyncClient, aiohttp (이미 사용 중), pytest-asyncio
+
+---
+
+## Task 1: exchange.py — OI / 펀딩비 조회 메서드 추가
+
+**Files:**
+- Modify: `src/exchange.py`
+- Test: `tests/test_exchange.py`
+
+### Step 1: 실패 테스트 작성
+
+`tests/test_exchange.py` 파일에 아래 테스트를 추가한다.
+
+```python
+@pytest.mark.asyncio
+async def test_get_open_interest(exchange):
+    """get_open_interest()가 float을 반환하는지 확인."""
+    exchange.client.futures_open_interest = MagicMock(
+        return_value={"openInterest": "123456.789"}
+    )
+    result = await exchange.get_open_interest()
+    assert isinstance(result, float)
+    assert result == pytest.approx(123456.789)
+
+
+@pytest.mark.asyncio
+async def test_get_funding_rate(exchange):
+    """get_funding_rate()가 float을 반환하는지 확인."""
+    exchange.client.futures_mark_price = MagicMock(
+        return_value={"lastFundingRate": "0.0001"}
+    )
+    result = await exchange.get_funding_rate()
+    assert isinstance(result, float)
+    assert result == pytest.approx(0.0001)
+
+
+@pytest.mark.asyncio
+async def test_get_open_interest_error_returns_none(exchange):
+    """API 오류 시 None 반환 확인."""
+    from binance.exceptions import BinanceAPIException
+    exchange.client.futures_open_interest = MagicMock(
+        side_effect=BinanceAPIException(MagicMock(status_code=400), 400, '{"code":-1121,"msg":"Invalid symbol"}')
+    )
+    result = await exchange.get_open_interest()
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_get_funding_rate_error_returns_none(exchange):
+    """API 오류 시 None 반환 확인."""
+    from binance.exceptions import BinanceAPIException
+    exchange.client.futures_mark_price = MagicMock(
+        side_effect=BinanceAPIException(MagicMock(status_code=400), 400, '{"code":-1121,"msg":"Invalid symbol"}')
+    )
+    result = await exchange.get_funding_rate()
+    assert result is None
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_exchange.py::test_get_open_interest tests/test_exchange.py::test_get_funding_rate -v
+```
+
+Expected: `FAILED` — `AttributeError: 'BinanceFuturesClient' object has no attribute 'get_open_interest'`
+
+### Step 3: exchange.py에 메서드 구현
+
+`src/exchange.py`의 `cancel_all_orders()` 메서드 아래에 추가한다.
+
+```python
+async def get_open_interest(self) -> float | None:
+    """현재 미결제약정(OI)을 조회한다. 오류 시 None 반환."""
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(
+            None,
+            lambda: self.client.futures_open_interest(symbol=self.config.symbol),
+        )
+        return float(result["openInterest"])
+    except Exception as e:
+        logger.warning(f"OI 조회 실패 (무시): {e}")
+        return None
+
+async def get_funding_rate(self) -> float | None:
+    """현재 펀딩비를 조회한다. 오류 시 None 반환."""
+    loop = asyncio.get_event_loop()
+    try:
+        result = await loop.run_in_executor(
+            None,
+            lambda: self.client.futures_mark_price(symbol=self.config.symbol),
+        )
+        return float(result["lastFundingRate"])
+    except Exception as e:
+        logger.warning(f"펀딩비 조회 실패 (무시): {e}")
+        return None
+```
+
+### Step 4: 테스트 통과 확인
+
+```bash
+pytest tests/test_exchange.py -v
+```
+
+Expected: 기존 테스트 포함 전체 PASS
+
+### Step 5: 커밋
+
+```bash
+git add src/exchange.py tests/test_exchange.py
+git commit -m "feat: add get_open_interest and get_funding_rate to BinanceFuturesClient"
+```
+
+---
+
+## Task 2: ml_features.py — build_features()에 oi/funding 파라미터 추가
+
+**Files:**
+- Modify: `src/ml_features.py`
+- Test: `tests/test_ml_features.py`
+
+### Step 1: 실패 테스트 작성
+
+`tests/test_ml_features.py`에 아래 테스트를 추가한다.
+
+```python
+def test_build_features_uses_provided_oi_funding(sample_df_with_indicators):
+    """oi_change, funding_rate 파라미터가 제공되면 실제 값이 피처에 반영된다."""
+    from src.ml_features import build_features
+    feat = build_features(
+        sample_df_with_indicators,
+        signal="LONG",
+        oi_change=0.05,
+        funding_rate=0.0002,
+    )
+    assert feat["oi_change"] == pytest.approx(0.05)
+    assert feat["funding_rate"] == pytest.approx(0.0002)
+
+
+def test_build_features_defaults_to_zero_when_not_provided(sample_df_with_indicators):
+    """oi_change, funding_rate 파라미터 미제공 시 0.0으로 채워진다."""
+    from src.ml_features import build_features
+    feat = build_features(sample_df_with_indicators, signal="LONG")
+    assert feat["oi_change"] == pytest.approx(0.0)
+    assert feat["funding_rate"] == pytest.approx(0.0)
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_ml_features.py::test_build_features_uses_provided_oi_funding -v
+```
+
+Expected: `FAILED` — `TypeError: build_features() got an unexpected keyword argument 'oi_change'`
+
+### Step 3: ml_features.py 수정
+
+`build_features()` 시그니처와 마지막 부분을 수정한다.
+
+```python
+def build_features(
+    df: pd.DataFrame,
+    signal: str,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+    oi_change: float | None = None,
+    funding_rate: float | None = None,
+) -> pd.Series:
+```
+
+그리고 함수 끝의 `setdefault` 부분을 아래로 교체한다.
+
+```python
+    # 실시간에서 실제 값이 제공되면 사용, 없으면 0으로 채운다
+    base["oi_change"]    = float(oi_change)    if oi_change    is not None else 0.0
+    base["funding_rate"] = float(funding_rate) if funding_rate is not None else 0.0
+
+    return pd.Series(base)
+```
+
+기존 코드:
+```python
+    # 실시간에서는 OI/펀딩비를 수집하지 않으므로 0으로 채워 학습 피처(23개)와 일치시킨다
+    base.setdefault("oi_change", 0.0)
+    base.setdefault("funding_rate", 0.0)
+
+    return pd.Series(base)
+```
+
+### Step 4: 테스트 통과 확인
+
+```bash
+pytest tests/test_ml_features.py -v
+```
+
+Expected: 전체 PASS
+
+### Step 5: 커밋
+
+```bash
+git add src/ml_features.py tests/test_ml_features.py
+git commit -m "feat: build_features accepts oi_change and funding_rate params"
+```
+
+---
+
+## Task 3: bot.py — 캔들 마감 시 OI/펀딩비 조회 후 피처에 전달
+
+**Files:**
+- Modify: `src/bot.py`
+- Test: `tests/test_bot.py`
+
+### Step 1: 실패 테스트 작성
+
+`tests/test_bot.py`에 아래 테스트를 추가한다.
+
+```python
+@pytest.mark.asyncio
+async def test_process_candle_fetches_oi_and_funding(config, sample_df):
+    """process_candle()이 OI와 펀딩비를 조회하고 build_features에 전달하는지 확인."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_balance = AsyncMock(return_value=1000.0)
+    bot.exchange.get_position = AsyncMock(return_value=None)
+    bot.exchange.place_order = AsyncMock(return_value={"orderId": "1"})
+    bot.exchange.set_leverage = AsyncMock()
+    bot.exchange.get_open_interest = AsyncMock(return_value=5000000.0)
+    bot.exchange.get_funding_rate = AsyncMock(return_value=0.0001)
+
+    with patch("src.bot.build_features") as mock_build:
+        mock_build.return_value = pd.Series({col: 0.0 for col in __import__("src.ml_features", fromlist=["FEATURE_COLS"]).FEATURE_COLS})
+        # ML 필터는 비활성화
+        bot.ml_filter.is_model_loaded = MagicMock(return_value=False)
+        await bot.process_candle(sample_df)
+
+    # build_features가 oi_change, funding_rate 키워드 인자와 함께 호출됐는지 확인
+    assert mock_build.called
+    call_kwargs = mock_build.call_args.kwargs
+    assert "oi_change" in call_kwargs
+    assert "funding_rate" in call_kwargs
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_bot.py::test_process_candle_fetches_oi_and_funding -v
+```
+
+Expected: `FAILED` — `AssertionError: assert 'oi_change' in {}`
+
+### Step 3: bot.py 수정
+
+`process_candle()` 메서드에서 OI/펀딩비를 조회하고 `build_features()`에 전달한다.
+
+`process_candle()` 메서드 시작 부분에 OI/펀딩비 조회를 추가한다:
+
+```python
+async def process_candle(self, df, btc_df=None, eth_df=None):
+    self.ml_filter.check_and_reload()
+
+    if not self.risk.is_trading_allowed():
+        logger.warning("리스크 한도 초과 - 거래 중단")
+        return
+
+    # 캔들 마감 시 OI/펀딩비 실시간 조회 (실패해도 0으로 폴백)
+    oi_change, funding_rate = await self._fetch_market_microstructure()
+
+    ind = Indicators(df)
+    df_with_indicators = ind.calculate_all()
+    raw_signal = ind.get_signal(df_with_indicators)
+    # ... (이하 동일)
+```
+
+그리고 `build_features()` 호출 부분 두 곳을 모두 수정한다:
+
+```python
+features = build_features(
+    df_with_indicators, signal,
+    btc_df=btc_df, eth_df=eth_df,
+    oi_change=oi_change, funding_rate=funding_rate,
+)
+```
+
+`_fetch_market_microstructure()` 메서드를 추가한다:
+
+```python
+async def _fetch_market_microstructure(self) -> tuple[float, float]:
+    """OI 변화율과 펀딩비를 실시간으로 조회한다. 실패 시 0.0으로 폴백."""
+    oi_val, fr_val = await asyncio.gather(
+        self.exchange.get_open_interest(),
+        self.exchange.get_funding_rate(),
+        return_exceptions=True,
+    )
+    oi_float = float(oi_val) if isinstance(oi_val, (int, float)) else 0.0
+    fr_float = float(fr_val) if isinstance(fr_val, (int, float)) else 0.0
+
+    # OI는 절대값이므로 이전 값 대비 변화율로 변환
+    oi_change = self._calc_oi_change(oi_float)
+    logger.debug(f"OI={oi_float:.0f}, OI변화율={oi_change:.6f}, 펀딩비={fr_float:.6f}")
+    return oi_change, fr_float
+```
+
+`_calc_oi_change()` 메서드와 `_prev_oi` 상태를 추가한다:
+
+`__init__()` 에 추가:
+```python
+self._prev_oi: float | None = None  # OI 변화율 계산용 이전 값
+```
+
+메서드 추가:
+```python
+def _calc_oi_change(self, current_oi: float) -> float:
+    """이전 OI 대비 변화율을 계산한다. 첫 캔들은 0.0 반환."""
+    if self._prev_oi is None or self._prev_oi == 0.0:
+        self._prev_oi = current_oi
+        return 0.0
+    change = (current_oi - self._prev_oi) / self._prev_oi
+    self._prev_oi = current_oi
+    return change
+```
+
+### Step 4: 테스트 통과 확인
+
+```bash
+pytest tests/test_bot.py -v
+```
+
+Expected: 전체 PASS
+
+### Step 5: 커밋
+
+```bash
+git add src/bot.py tests/test_bot.py
+git commit -m "feat: fetch realtime OI and funding rate on candle close for ML features"
+```
+
+---
+
+## Task 4: 전체 테스트 통과 확인 및 README 업데이트
+
+### Step 1: 전체 테스트 실행
+
+```bash
+bash scripts/run_tests.sh
+```
+
+Expected: 전체 PASS (새 테스트 포함)
+
+### Step 2: README.md 업데이트
+
+`README.md`의 "주요 기능" 섹션에서 ML 피처 설명을 수정한다.
+
+기존:
+```
+- **23개 ML 피처**: XRP 기술 지표 13개 + BTC/ETH 수익률·상대강도 8개 + OI 변화율·펀딩비 2개 (실시간 미수집 항목은 0으로 채움)
+```
+
+변경:
+```
+- **23개 ML 피처**: XRP 기술 지표 13개 + BTC/ETH 수익률·상대강도 8개 + OI 변화율·펀딩비 2개 (캔들 마감 시 REST API로 실시간 수집)
+```
+
+### Step 3: 최종 커밋
+
+```bash
+git add README.md
+git commit -m "docs: update README to reflect realtime OI/funding rate collection"
+```
+
+---
+
+## 구현 후 검증 포인트
+
+1. 봇 실행 로그에서 `OI=xxx, OI변화율=xxx, 펀딩비=xxx` 라인이 15분마다 출력되는지 확인
+2. API 오류(네트워크 단절 등) 시 `WARNING: OI 조회 실패 (무시)` 로그 후 0.0으로 폴백해 봇이 정상 동작하는지 확인
+3. `build_features()` 호출 시 `oi_change`, `funding_rate`가 실제 값으로 채워지는지 로그 확인
+
+---
+
+## 다음 단계: 접근법 B (OI/펀딩비 누적 저장)
+
+A 완료 후 진행할 계획:
+- `scripts/fetch_history.py` 실행 시 기존 parquet에 새 30일치를 **append(중복 제거)** 방식으로 저장
+- 시간이 지날수록 OI/펀딩비 학습 데이터가 누적되어 모델 품질 향상
+- 별도 플랜 문서로 작성 예정

docs/plans/2026-03-02-reverse-signal-reenter-design.md

@@ -0,0 +1,125 @@
+# 반대 시그널 시 청산 후 즉시 재진입 설계
+
+- **날짜**: 2026-03-02
+- **파일**: `src/bot.py`
+- **상태**: 설계 완료, 구현 대기
+
+---
+
+## 배경
+
+현재 `TradingBot.process_candle`은 반대 방향 시그널이 오면 기존 포지션을 청산만 하고 종료한다.
+새 포지션은 다음 캔들에서 시그널이 다시 나와야 잡힌다.
+
+```
+현재: 반대 시그널 → 청산 → 다음 캔들 대기
+목표: 반대 시그널 → 청산 → (ML 필터 통과 시) 즉시 반대 방향 재진입
+```
+
+같은 방향 시그널이 오거나 HOLD이면 기존 포지션을 그대로 유지한다.
+
+---
+
+## 요구사항
+
+| 항목 | 결정 |
+|------|------|
+| 포지션 크기 | 재진입 시점 잔고 + 동적 증거금 비율로 새로 계산 |
+| SL/TP | 청산 시 기존 주문 전부 취소, 재진입 시 새로 설정 |
+| ML 필터 | 재진입에도 동일하게 적용 (차단 시 청산만 하고 대기) |
+| 같은 방향 시그널 | 포지션 유지 (변경 없음) |
+| HOLD 시그널 | 포지션 유지 (변경 없음) |
+
+---
+
+## 설계
+
+### 변경 범위
+
+`src/bot.py` 한 파일만 수정한다.
+
+1. `_close_and_reenter` 메서드 신규 추가
+2. `process_candle` 내 반대 시그널 분기에서 `_close_position` 대신 `_close_and_reenter` 호출
+
+### 데이터 흐름
+
+```
+process_candle()
+  └─ 반대 시그널 감지
+       └─ _close_and_reenter(position, signal, df, btc_df, eth_df)
+            ├─ _close_position(position)          # 청산 + cancel_all_orders
+            ├─ risk.can_open_new_position() 체크
+            │    └─ 불가 → 로그 + 종료
+            ├─ ML 필터 체크 (ml_filter.is_model_loaded())
+            │    ├─ 차단 → 로그 + 종료 (포지션 없는 상태로 대기)
+            │    └─ 통과 → 계속
+            └─ _open_position(signal, df)          # 재진입 + 새 SL/TP 설정
+```
+
+### `process_candle` 수정
+
+```python
+# 변경 전
+elif position is not None:
+    pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
+    if (pos_side == "LONG" and signal == "SHORT") or \
+       (pos_side == "SHORT" and signal == "LONG"):
+        await self._close_position(position)
+
+# 변경 후
+elif position is not None:
+    pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
+    if (pos_side == "LONG" and signal == "SHORT") or \
+       (pos_side == "SHORT" and signal == "LONG"):
+        await self._close_and_reenter(position, signal, df_with_indicators, btc_df, eth_df)
+```
+
+### 신규 메서드 `_close_and_reenter`
+
+```python
+async def _close_and_reenter(
+    self,
+    position: dict,
+    signal: str,
+    df,
+    btc_df=None,
+    eth_df=None,
+) -> None:
+    """기존 포지션을 청산하고, ML 필터 통과 시 반대 방향으로 즉시 재진입한다."""
+    await self._close_position(position)
+
+    if not self.risk.can_open_new_position():
+        logger.info("최대 포지션 수 도달 — 재진입 건너뜀")
+        return
+
+    if self.ml_filter.is_model_loaded():
+        features = build_features(df, signal, btc_df=btc_df, eth_df=eth_df)
+        if not self.ml_filter.should_enter(features):
+            logger.info(f"ML 필터 차단: {signal} 재진입 무시")
+            return
+
+    await self._open_position(signal, df)
+```
+
+---
+
+## 엣지 케이스
+
+| 상황 | 처리 |
+|------|------|
+| 청산 후 ML 필터 차단 | 청산만 하고 포지션 없는 상태로 대기 |
+| 청산 후 잔고 부족 (명목금액 미달) | `_open_position` 내부 경고 후 건너뜀 (기존 로직) |
+| 청산 후 최대 포지션 수 초과 | 재진입 건너뜀 |
+| 같은 방향 시그널 | 포지션 유지 (변경 없음) |
+| HOLD 시그널 | 포지션 유지 (변경 없음) |
+| 봇 재시작 후 포지션 복구 | `_recover_position` 로직 변경 없음 |
+
+---
+
+## 영향 없는 코드
+
+- `_close_position` — 변경 없음
+- `_open_position` — 변경 없음
+- `_recover_position` — 변경 없음
+- `RiskManager` — 변경 없음
+- `MLFilter` — 변경 없음

docs/plans/2026-03-02-reverse-signal-reenter-plan.md

@@ -0,0 +1,269 @@
+# 반대 시그널 시 청산 후 즉시 재진입 구현 플랜
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 반대 방향 시그널이 오면 기존 포지션을 청산하고 ML 필터 통과 시 즉시 반대 방향으로 재진입한다.
+
+**Architecture:** `src/bot.py`에 `_close_and_reenter` 메서드를 추가하고, `process_candle`의 반대 시그널 분기에서 이를 호출한다. 기존 `_close_position`과 `_open_position`을 그대로 재사용하므로 중복 없음.
+
+**Tech Stack:** Python 3.12, pytest, unittest.mock
+
+---
+
+## 테스트 스크립트
+
+각 태스크 단계마다 아래 스크립트로 테스트를 실행한다.
+
+```bash
+# Task 1 — 신규 테스트 실행 (구현 전, FAIL 확인용)
+bash scripts/test_reverse_reenter.sh 1
+
+# Task 2 — _close_and_reenter 메서드 테스트 (구현 후, PASS 확인)
+bash scripts/test_reverse_reenter.sh 2
+
+# Task 3 — process_candle 분기 테스트 (수정 후, PASS 확인)
+bash scripts/test_reverse_reenter.sh 3
+
+# test_bot.py 전체
+bash scripts/test_reverse_reenter.sh bot
+
+# 전체 테스트 스위트
+bash scripts/test_reverse_reenter.sh all
+```
+
+---
+
+## 참고 파일
+
+- 설계 문서: `docs/plans/2026-03-02-reverse-signal-reenter-design.md`
+- 구현 대상: `src/bot.py`
+- 기존 테스트: `tests/test_bot.py`
+
+---
+
+## Task 1: `_close_and_reenter` 테스트 작성
+
+**Files:**
+- Modify: `tests/test_bot.py`
+
+### Step 1: 테스트 3개 추가
+
+`tests/test_bot.py` 맨 아래에 다음 테스트를 추가한다.
+
+```python
+@pytest.mark.asyncio
+async def test_close_and_reenter_calls_open_when_ml_passes(config, sample_df):
+    """반대 시그널 + ML 필터 통과 시 청산 후 재진입해야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True
+    bot.ml_filter.should_enter.return_value = True
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_awaited_once_with("SHORT", sample_df)
+
+
+@pytest.mark.asyncio
+async def test_close_and_reenter_skips_open_when_ml_blocks(config, sample_df):
+    """ML 필터 차단 시 청산만 하고 재진입하지 않아야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True
+    bot.ml_filter.should_enter.return_value = False
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_close_and_reenter_skips_open_when_max_positions_reached(config, sample_df):
+    """최대 포지션 수 도달 시 청산만 하고 재진입하지 않아야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.risk = MagicMock()
+    bot.risk.can_open_new_position.return_value = False
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_not_called()
+```
+
+### Step 2: 테스트 실행 — 실패 확인
+
+```bash
+bash scripts/test_reverse_reenter.sh 1
+```
+
+예상 결과: `AttributeError: 'TradingBot' object has no attribute '_close_and_reenter'` 로 3개 FAIL
+
+---
+
+## Task 2: `_close_and_reenter` 메서드 구현
+
+**Files:**
+- Modify: `src/bot.py:148` (`_close_position` 메서드 바로 아래에 추가)
+
+### Step 1: `_close_position` 다음에 메서드 추가
+
+`src/bot.py`에서 `_close_position` 메서드(148~167번째 줄) 바로 뒤에 다음을 추가한다.
+
+```python
+    async def _close_and_reenter(
+        self,
+        position: dict,
+        signal: str,
+        df,
+        btc_df=None,
+        eth_df=None,
+    ) -> None:
+        """기존 포지션을 청산하고, ML 필터 통과 시 반대 방향으로 즉시 재진입한다."""
+        await self._close_position(position)
+
+        if not self.risk.can_open_new_position():
+            logger.info("최대 포지션 수 도달 — 재진입 건너뜀")
+            return
+
+        if self.ml_filter.is_model_loaded():
+            features = build_features(df, signal, btc_df=btc_df, eth_df=eth_df)
+            if not self.ml_filter.should_enter(features):
+                logger.info(f"ML 필터 차단: {signal} 재진입 무시")
+                return
+
+        await self._open_position(signal, df)
+```
+
+### Step 2: 테스트 실행 — 통과 확인
+
+```bash
+bash scripts/test_reverse_reenter.sh 2
+```
+
+예상 결과: 3개 PASS
+
+### Step 3: 커밋
+
+```bash
+git add src/bot.py tests/test_bot.py
+git commit -m "feat: add _close_and_reenter method for reverse signal handling"
+```
+
+---
+
+## Task 3: `process_candle` 분기 수정
+
+**Files:**
+- Modify: `src/bot.py:83-85`
+
+### Step 1: 기존 분기 테스트 추가
+
+`tests/test_bot.py`에 다음 테스트를 추가한다.
+
+```python
+@pytest.mark.asyncio
+async def test_process_candle_calls_close_and_reenter_on_reverse_signal(config, sample_df):
+    """반대 시그널 시 process_candle이 _close_and_reenter를 호출해야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_position = AsyncMock(return_value={
+        "positionAmt": "100",
+        "entryPrice": "0.5",
+        "markPrice": "0.52",
+    })
+    bot._close_and_reenter = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = False
+    bot.ml_filter.should_enter.return_value = True
+
+    with patch("src.bot.Indicators") as MockInd:
+        mock_ind = MagicMock()
+        mock_ind.calculate_all.return_value = sample_df
+        mock_ind.get_signal.return_value = "SHORT"  # 현재 LONG 포지션에 반대 시그널
+        MockInd.return_value = mock_ind
+        await bot.process_candle(sample_df)
+
+    bot._close_and_reenter.assert_awaited_once()
+    call_args = bot._close_and_reenter.call_args
+    assert call_args.args[1] == "SHORT"
+```
+
+### Step 2: 테스트 실행 — 실패 확인
+
+```bash
+bash scripts/test_reverse_reenter.sh 3
+```
+
+예상 결과: FAIL (`_close_and_reenter`가 아직 호출되지 않음)
+
+### Step 3: `process_candle` 수정
+
+`src/bot.py`에서 아래 부분을 찾아 수정한다.
+
+```python
+# 변경 전 (81~85번째 줄 근처)
+        elif position is not None:
+            pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
+            if (pos_side == "LONG" and signal == "SHORT") or \
+               (pos_side == "SHORT" and signal == "LONG"):
+                await self._close_position(position)
+
+# 변경 후
+        elif position is not None:
+            pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
+            if (pos_side == "LONG" and signal == "SHORT") or \
+               (pos_side == "SHORT" and signal == "LONG"):
+                await self._close_and_reenter(
+                    position, signal, df_with_indicators, btc_df=btc_df, eth_df=eth_df
+                )
+```
+
+### Step 4: 전체 테스트 실행 — 통과 확인
+
+```bash
+bash scripts/test_reverse_reenter.sh bot
+```
+
+예상 결과: 전체 PASS (기존 테스트 포함)
+
+### Step 5: 커밋
+
+```bash
+git add src/bot.py tests/test_bot.py
+git commit -m "feat: call _close_and_reenter on reverse signal in process_candle"
+```
+
+---
+
+## Task 4: 전체 테스트 스위트 확인
+
+### Step 1: 전체 테스트 실행
+
+```bash
+bash scripts/test_reverse_reenter.sh all
+```
+
+예상 결과: 모든 테스트 PASS
+
+### Step 2: 실패 테스트 있으면 수정 후 재실행
+
+실패가 있으면 원인을 파악하고 수정한다. 기존 테스트를 깨뜨리지 않도록 주의.

docs/plans/2026-03-02-rs-divide-mlx-nan-fix.md

@@ -0,0 +1,203 @@
+# RS np.divide 복구 / MLX NaN-Safe 통계 저장 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** RS(상대강도) 계산의 epsilon 폭발 이상치를 `np.divide` 방식으로 제거하고, MLXFilter의 `self._mean`/`self._std`에 NaN이 잔류하는 근본 허점을 차단한다.
+
+**Architecture:**
+- `src/dataset_builder.py`: `xrp_btc_rs_raw` / `xrp_eth_rs_raw` 계산을 `np.divide(..., where=...)` 방식으로 교체. 분모(btc_r1, eth_r1)가 0이면 결과를 0.0으로 채워 rolling zscore 윈도우 오염을 방지한다.
+- `src/mlx_filter.py`: `fit()` 내부에서 `self._mean`/`self._std`를 저장하기 전에 `nan_to_num`을 적용해 전체-NaN 컬럼(OI 초반 구간 등)이 `predict_proba` 시점까지 NaN을 전파하지 않도록 한다.
+
+**Tech Stack:** numpy, pandas, pytest, mlx(Apple Silicon 전용 — MLX 테스트는 Mac에서만 실행)
+
+---
+
+### Task 1: `dataset_builder.py` — RS 계산을 `np.divide` 방식으로 교체
+
+**Files:**
+- Modify: `src/dataset_builder.py:245-246`
+- Test: `tests/test_dataset_builder.py`
+
+**배경:**
+`btc_r1 = 0.0`(15분 동안 BTC 가격 변동 없음)일 때 `xrp_r1 / (btc_r1 + 1e-8)`는 최대 수백만의 이상치를 만든다. 이 이상치가 288캔들 rolling zscore 윈도우에 들어가면 나머지 287개 값이 전부 0에 가깝게 압사된다.
+
+**Step 1: 기존 테스트 실행 (기준선 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py -v
+```
+
+Expected: 모든 테스트 PASS (변경 전 기준선)
+
+**Step 2: RS 제로-분모 테스트 작성**
+
+`tests/test_dataset_builder.py` 파일 끝에 추가:
+
+```python
+def test_rs_zero_denominator():
+    """btc_r1=0일 때 RS가 inf/nan이 아닌 0.0이어야 한다 (np.divide 방식 검증)."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 500
+    np.random.seed(7)
+    # XRP close: 약간의 변동
+    xrp_close = np.cumprod(1 + np.random.randn(n) * 0.001) * 1.0
+    xrp_df = pd.DataFrame({
+        "open":   xrp_close * 0.999,
+        "high":   xrp_close * 1.005,
+        "low":    xrp_close * 0.995,
+        "close":  xrp_close,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+    # BTC close: 완전히 고정 → btc_r1 = 0.0
+    btc_close = np.ones(n) * 50000.0
+    btc_df = pd.DataFrame({
+        "open":   btc_close,
+        "high":   btc_close,
+        "low":    btc_close,
+        "close":  btc_close,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+
+    from src.dataset_builder import generate_dataset_vectorized
+    result = generate_dataset_vectorized(xrp_df, btc_df=btc_df)
+
+    if result.empty:
+        pytest.skip("신호 없음")
+
+    assert "xrp_btc_rs" in result.columns, "xrp_btc_rs 컬럼이 있어야 함"
+    assert not result["xrp_btc_rs"].isin([np.inf, -np.inf]).any(), \
+        "xrp_btc_rs에 inf가 있으면 안 됨"
+    assert not result["xrp_btc_rs"].isna().all(), \
+        "xrp_btc_rs가 전부 nan이면 안 됨"
+```
+
+**Step 3: 테스트 실행 (FAIL 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py::test_rs_zero_denominator -v
+```
+
+Expected: FAIL — `xrp_btc_rs에 inf가 있으면 안 됨` (현재 epsilon 방식은 inf 대신 수백만 이상치를 만들어 rolling zscore 후 nan이 될 수 있음)
+
+> 참고: 현재 코드는 inf를 직접 만들지 않을 수도 있다. 하지만 rolling zscore 후 nan이 생기거나 이상치가 남아있는지 확인하는 것이 목적이다. PASS가 나오더라도 Step 4를 진행한다.
+
+**Step 4: `dataset_builder.py` 245~246줄 수정**
+
+`src/dataset_builder.py`의 아래 두 줄을:
+
+```python
+        xrp_btc_rs_raw = (xrp_r1 / (btc_r1 + 1e-8)).astype(np.float32)
+        xrp_eth_rs_raw = (xrp_r1 / (eth_r1 + 1e-8)).astype(np.float32)
+```
+
+다음으로 교체:
+
+```python
+        xrp_btc_rs_raw = np.divide(
+            xrp_r1, btc_r1,
+            out=np.zeros_like(xrp_r1),
+            where=(btc_r1 != 0),
+        ).astype(np.float32)
+        xrp_eth_rs_raw = np.divide(
+            xrp_r1, eth_r1,
+            out=np.zeros_like(xrp_r1),
+            where=(eth_r1 != 0),
+        ).astype(np.float32)
+```
+
+**Step 5: 전체 테스트 실행 (PASS 확인)**
+
+```bash
+python -m pytest tests/test_dataset_builder.py -v
+```
+
+Expected: 모든 테스트 PASS
+
+**Step 6: 커밋**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "fix: RS 계산을 np.divide(where=) 방식으로 교체 — epsilon 이상치 폭발 차단"
+```
+
+---
+
+### Task 2: `mlx_filter.py` — `self._mean`/`self._std` 저장 전 `nan_to_num` 적용
+
+**Files:**
+- Modify: `src/mlx_filter.py:145-146`
+- Test: `tests/test_mlx_filter.py` (기존 `test_fit_with_nan_features` 활용)
+
+**배경:**
+현재 코드는 `self._mean = np.nanmean(X_np, axis=0)`으로 저장한다. 전체가 NaN인 컬럼(Walk-Forward 초반 11개월의 OI 데이터)이 있으면 `np.nanmean`은 해당 컬럼의 평균으로 NaN을 반환한다. 이 NaN이 `self._mean`에 저장되면 `predict_proba` 시점에 `(X_np - self._mean)`이 NaN이 되어 OI 데이터를 영원히 활용하지 못한다.
+
+**Step 1: 기존 테스트 실행 (기준선 확인)**
+
+```bash
+python -m pytest tests/test_mlx_filter.py -v
+```
+
+Expected: 모든 테스트 PASS (MLX 없는 환경에서는 전체 SKIP)
+
+**Step 2: `mlx_filter.py` 145~146줄 수정**
+
+`src/mlx_filter.py`의 아래 두 줄을:
+
+```python
+        self._mean = np.nanmean(X_np, axis=0)
+        self._std  = np.nanstd(X_np, axis=0) + 1e-8
+```
+
+다음으로 교체:
+
+```python
+        mean_vals  = np.nanmean(X_np, axis=0)
+        self._mean = np.nan_to_num(mean_vals, nan=0.0)   # 전체-NaN 컬럼 → 평균 0.0
+        std_vals   = np.nanstd(X_np, axis=0)
+        self._std  = np.nan_to_num(std_vals, nan=1.0) + 1e-8  # 전체-NaN 컬럼 → std 1.0
+```
+
+**Step 3: 테스트 실행 (PASS 확인)**
+
+```bash
+python -m pytest tests/test_mlx_filter.py::test_fit_with_nan_features -v
+```
+
+Expected: PASS (MLX 없는 환경에서는 SKIP)
+
+**Step 4: 전체 테스트 실행**
+
+```bash
+python -m pytest tests/test_mlx_filter.py -v
+```
+
+Expected: 모든 테스트 PASS (또는 SKIP)
+
+**Step 5: 커밋**
+
+```bash
+git add src/mlx_filter.py
+git commit -m "fix: MLXFilter self._mean/std 저장 전 nan_to_num 적용 — 전체-NaN 컬럼 predict_proba 오염 차단"
+```
+
+---
+
+### Task 3: 전체 테스트 통과 확인
+
+**Step 1: 전체 테스트 실행**
+
+```bash
+python -m pytest tests/ -v --tb=short 2>&1 | tail -40
+```
+
+Expected: 모든 테스트 PASS (MLX 관련은 SKIP 허용)
+
+**Step 2: 최종 커밋 (필요 시)**
+
+```bash
+git add -A
+git commit -m "chore: RS epsilon 폭발 차단 + MLX NaN-Safe 통계 저장 통합"
+```

docs/plans/2026-03-02-user-data-stream-tp-sl-detection-design.md

@@ -0,0 +1,300 @@
+# User Data Stream TP/SL 감지 설계
+
+**날짜:** 2026-03-02  
+**목적:** Binance Futures User Data Stream을 도입하여 TP/SL 작동을 실시간 감지하고, 순수익(Net PnL)을 기록하며, Discord에 상세 청산 알림을 전송한다.
+
+---
+
+## 배경 및 문제
+
+기존 봇은 매 캔들 마감마다 `get_position()`을 폴링하여 포지션 소멸 여부를 확인하는 방식이었다. 이 구조의 한계:
+
+1. **TP/SL 작동 후 최대 15분 지연** — 캔들 마감 전까지 감지 불가
+2. **청산 원인 구분 불가** — TP인지 SL인지 수동 청산인지 알 수 없음
+3. **PnL 기록 누락** — `_close_position()`을 봇이 직접 호출하지 않으면 `record_pnl()` 미실행
+4. **Discord 알림 누락** — 동일 이유로 `notify_close()` 미호출
+
+---
+
+## 선택한 접근 방식
+
+**방식 A: `python-binance` 내장 User Data Stream + 30분 수동 keepalive 보강**
+
+- 기존 `BinanceSocketManager` 활용으로 추가 의존성 없음
+- `futures_user_socket(listenKey)`로 User Data Stream 연결
+- 별도 30분 keepalive 백그라운드 태스크로 안정성 보강
+- `while True: try-except` 무한 재연결 루프로 네트워크 단절 복구
+
+---
+
+## 전체 아키텍처
+
+### 파일 변경 목록
+
+| 파일 | 변경 유형 | 내용 |
+|------|----------|------|
+| `src/user_data_stream.py` | **신규** | User Data Stream 전담 클래스 |
+| `src/bot.py` | 수정 | `UserDataStream` 초기화, `run()` 병렬 실행, `_on_position_closed()` 콜백, `_entry_price`/`_entry_quantity` 상태 추가 |
+| `src/exchange.py` | 수정 | `create_listen_key()`, `keepalive_listen_key()`, `delete_listen_key()` 메서드 추가 |
+| `src/notifier.py` | 수정 | `notify_close()`에 `close_reason`, `estimated_pnl`, `net_pnl` 파라미터 추가 |
+| `src/risk_manager.py` | 수정 | `record_pnl()`이 net_pnl을 받도록 유지 (인터페이스 변경 없음) |
+
+### 실행 흐름
+
+```
+bot.run()
+  └── AsyncClient 단일 인스턴스 생성
+        └── asyncio.gather()
+              ├── MultiSymbolStream.start(client)   ← 기존 캔들 스트림
+              └── UserDataStream.start()             ← 신규
+                    ├── [백그라운드] _keepalive_loop()  30분마다 PUT /listenKey
+                    └── [메인루프]  while True:
+                                    try:
+                                      listenKey 발급
+                                      futures_user_socket() 연결
+                                      async for msg: _handle_message()
+                                    except CancelledError: break
+                                    except Exception: sleep(5) → 재연결
+```
+
+---
+
+## 섹션 1: UserDataStream 클래스 (`src/user_data_stream.py`)
+
+### 상수
+
+```python
+KEEPALIVE_INTERVAL = 30 * 60   # 30분 (listenKey 만료 60분의 절반)
+RECONNECT_DELAY    = 5         # 재연결 대기 초
+```
+
+### listenKey 생명주기
+
+| 단계 | API | 시점 |
+|------|-----|------|
+| 발급 | `POST /fapi/v1/listenKey` | 연결 시작 / 재연결 시 |
+| 갱신 | `PUT /fapi/v1/listenKey` | 30분마다 (백그라운드 태스크) |
+| 삭제 | `DELETE /fapi/v1/listenKey` | 봇 정상 종료 시 (`CancelledError`) |
+
+### 재연결 로직
+
+```python
+while True:
+    try:
+        listen_key = await exchange.create_listen_key()
+        keepalive_task = asyncio.create_task(_keepalive_loop(listen_key))
+        async with bm.futures_user_socket(listen_key):
+            async for msg:
+                await _handle_message(msg)
+    except asyncio.CancelledError:
+        await exchange.delete_listen_key(listen_key)
+        keepalive_task.cancel()
+        break
+    except Exception as e:
+        logger.warning(f"User Data Stream 끊김: {e}, {RECONNECT_DELAY}초 후 재연결")
+        keepalive_task.cancel()
+        await asyncio.sleep(RECONNECT_DELAY)
+        # while True 상단으로 돌아가 listenKey 재발급
+```
+
+### keepalive 백그라운드 태스크
+
+```python
+async def _keepalive_loop(listen_key: str):
+    while True:
+        await asyncio.sleep(KEEPALIVE_INTERVAL)
+        try:
+            await exchange.keepalive_listen_key(listen_key)
+            logger.debug("listenKey 갱신 완료")
+        except Exception:
+            logger.warning("listenKey 갱신 실패 → 재연결 루프가 처리")
+            break  # 재연결 루프가 새 태스크 생성
+```
+
+---
+
+## 섹션 2: 이벤트 파싱 로직
+
+### 페이로드 구조 (Binance Futures ORDER_TRADE_UPDATE)
+
+주문 상세 정보는 최상위가 아닌 **내부 `"o"` 딕셔너리에 중첩**되어 있다.
+
+```json
+{
+  "e": "ORDER_TRADE_UPDATE",
+  "o": {
+    "x": "TRADE",          // Execution Type
+    "X": "FILLED",         // Order Status
+    "o": "TAKE_PROFIT_MARKET",  // Order Type
+    "R": true,             // reduceOnly
+    "rp": "0.48210000",    // realizedProfit
+    "n": "0.02100000",     // commission
+    "ap": "1.3393"         // average price (체결가)
+  }
+}
+```
+
+### 판단 트리
+
+```
+msg["e"] == "ORDER_TRADE_UPDATE"?
+  └── order = msg["o"]
+      order["x"] == "TRADE" AND order["X"] == "FILLED"?
+        └── 청산 주문인가?
+            (order["R"] == true OR float(order["rp"]) != 0
+             OR order["o"] in {"TAKE_PROFIT_MARKET", "STOP_MARKET"})
+              ├── NO  → 무시 (진입 주문)
+              └── YES → close_reason 판별:
+                          "TAKE_PROFIT_MARKET" → "TP"
+                          "STOP_MARKET"        → "SL"
+                          그 외               → "MANUAL"
+                        net_pnl = float(rp) - abs(float(n))
+                        exit_price = float(order["ap"])
+                        await on_order_filled(net_pnl, close_reason, exit_price)
+```
+
+---
+
+## 섹션 3: `_on_position_closed()` 콜백 (`src/bot.py`)
+
+### 진입가 상태 저장
+
+`_open_position()` 내부에서 진입가와 수량을 인스턴스 변수로 저장한다. 청산 시점에는 포지션이 이미 사라져 있으므로 사전 저장이 필수다.
+
+```python
+# __init__에 추가
+self._entry_price: float | None = None
+self._entry_quantity: float | None = None
+
+# _open_position() 내부에서 저장
+self._entry_price = price
+self._entry_quantity = quantity
+```
+
+### 예상 PnL 계산
+
+```python
+def _calc_estimated_pnl(self, exit_price: float) -> float:
+    if self._entry_price is None or self._entry_quantity is None:
+        return 0.0
+    if self.current_trade_side == "LONG":
+        return (exit_price - self._entry_price) * self._entry_quantity
+    else:  # SHORT
+        return (self._entry_price - exit_price) * self._entry_quantity
+```
+
+### 콜백 전체 흐름
+
+```python
+async def _on_position_closed(
+    self,
+    net_pnl: float,
+    close_reason: str,   # "TP" | "SL" | "MANUAL"
+    exit_price: float,
+):
+    estimated_pnl = self._calc_estimated_pnl(exit_price)
+    diff = net_pnl - estimated_pnl  # 슬리피지 + 수수료 차이
+
+    # RiskManager에 순수익 기록
+    self.risk.record_pnl(net_pnl)
+
+    # Discord 알림
+    self.notifier.notify_close(
+        symbol=self.config.symbol,
+        side=self.current_trade_side or "UNKNOWN",
+        close_reason=close_reason,
+        exit_price=exit_price,
+        estimated_pnl=estimated_pnl,
+        net_pnl=net_pnl,
+        diff=diff,
+    )
+
+    logger.success(
+        f"포지션 청산({close_reason}): 예상={estimated_pnl:+.4f}, "
+        f"순수익={net_pnl:+.4f}, 차이={diff:+.4f} USDT"
+    )
+
+    # 봇 상태 초기화 (Flat 상태로 복귀)
+    self.current_trade_side = None
+    self._entry_price = None
+    self._entry_quantity = None
+```
+
+### 기존 `_close_position()` 변경
+
+봇이 직접 청산하는 경우(`_close_and_reenter`)에도 User Data Stream의 `ORDER_TRADE_UPDATE`가 발생한다. **중복 처리 방지**를 위해 `_close_position()`에서 `notify_close()`와 `record_pnl()` 호출을 제거한다. 모든 청산 후처리는 `_on_position_closed()` 콜백 하나로 일원화한다.
+
+---
+
+## 섹션 4: Discord 알림 포맷 (`src/notifier.py`)
+
+### `notify_close()` 시그니처 변경
+
+```python
+def notify_close(
+    self,
+    symbol: str,
+    side: str,
+    close_reason: str,    # "TP" | "SL" | "MANUAL"
+    exit_price: float,
+    estimated_pnl: float,
+    net_pnl: float,
+    diff: float,          # net_pnl - estimated_pnl
+) -> None:
+```
+
+### 알림 포맷
+
+```
+✅ [XRPUSDT] SHORT TP 청산
+청산가:          `1.3393`
+예상 수익:       `+0.4821 USDT`
+실제 순수익:     `+0.4612 USDT`
+차이(슬리피지+수수료): `-0.0209 USDT`
+```
+
+| 청산 원인 | 이모지 |
+|----------|--------|
+| TP       | ✅     |
+| SL       | ❌     |
+| MANUAL   | 🔶     |
+
+---
+
+## 섹션 5: `src/exchange.py` 추가 메서드
+
+```python
+async def create_listen_key(self) -> str:
+    """POST /fapi/v1/listenKey — listenKey 신규 발급"""
+
+async def keepalive_listen_key(self, listen_key: str) -> None:
+    """PUT /fapi/v1/listenKey — listenKey 만료 연장"""
+
+async def delete_listen_key(self, listen_key: str) -> None:
+    """DELETE /fapi/v1/listenKey — listenKey 삭제 (정상 종료 시)"""
+```
+
+---
+
+## 데이터 흐름 요약
+
+```
+Binance WebSocket
+  → ORDER_TRADE_UPDATE (FILLED, reduceOnly)
+  → UserDataStream._handle_message()
+  → net_pnl = rp - |commission|
+  → bot._on_position_closed(net_pnl, close_reason, exit_price)
+      ├── estimated_pnl = (exit - entry) × qty  (봇 계산)
+      ├── diff = net_pnl - estimated_pnl
+      ├── risk.record_pnl(net_pnl)              → 일일 PnL 누적
+      ├── notifier.notify_close(...)             → Discord 알림
+      └── 상태 초기화 (current_trade_side, _entry_price, _entry_quantity = None)
+```
+
+---
+
+## 제외 범위 (YAGNI)
+
+- DB 영구 저장 (SQLite/Postgres) — 현재 로그 기반으로 충분
+- 진입 주문 체결 알림 (`TRADE` + not reduceOnly) — 기존 `notify_open()`으로 커버
+- 부분 청산(partial fill) 처리 — 현재 봇은 전량 청산만 사용

docs/plans/2026-03-02-user-data-stream-tp-sl-detection-plan.md

@@ -0,0 +1,510 @@
+# User Data Stream TP/SL 감지 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Binance Futures User Data Stream을 도입하여 TP/SL 작동을 실시간 감지하고, 순수익(Net PnL)을 기록하며, Discord에 예상 수익 vs 실제 순수익 비교 알림을 전송한다.
+
+**Architecture:** `python-binance`의 `futures_user_socket(listenKey)`로 User Data Stream에 연결하고, 30분 keepalive 백그라운드 태스크와 `while True: try-except` 무한 재연결 루프로 안정성을 확보한다. `ORDER_TRADE_UPDATE` 이벤트에서 청산 주문을 감지하면 `bot._on_position_closed()` 콜백을 호출하여 PnL 기록과 Discord 알림을 일원화한다.
+
+**Tech Stack:** Python 3.12, python-binance (AsyncClient, BinanceSocketManager), asyncio, loguru
+
+**Design Doc:** `docs/plans/2026-03-02-user-data-stream-tp-sl-detection-design.md`
+
+---
+
+## Task 1: `exchange.py`에 listenKey 관리 메서드 추가
+
+**Files:**
+- Modify: `src/exchange.py` (끝에 메서드 추가)
+
+**Step 1: listenKey 3개 메서드 구현**
+
+`src/exchange.py` 끝에 아래 메서드 3개를 추가한다.
+
+```python
+async def create_listen_key(self) -> str:
+    """POST /fapi/v1/listenKey — listenKey 신규 발급"""
+    loop = asyncio.get_event_loop()
+    result = await loop.run_in_executor(
+        None,
+        lambda: self.client.futures_stream_get_listen_key(),
+    )
+    return result
+
+async def keepalive_listen_key(self, listen_key: str) -> None:
+    """PUT /fapi/v1/listenKey — listenKey 만료 연장 (60분 → 리셋)"""
+    loop = asyncio.get_event_loop()
+    await loop.run_in_executor(
+        None,
+        lambda: self.client.futures_stream_keepalive(listenKey=listen_key),
+    )
+
+async def delete_listen_key(self, listen_key: str) -> None:
+    """DELETE /fapi/v1/listenKey — listenKey 삭제 (정상 종료 시)"""
+    loop = asyncio.get_event_loop()
+    try:
+        await loop.run_in_executor(
+            None,
+            lambda: self.client.futures_stream_close(listenKey=listen_key),
+        )
+    except Exception as e:
+        logger.warning(f"listenKey 삭제 실패 (무시): {e}")
+```
+
+**Step 2: 커밋**
+
+```bash
+git add src/exchange.py
+git commit -m "feat: add listenKey create/keepalive/delete methods to exchange"
+```
+
+---
+
+## Task 2: `notifier.py`의 `notify_close()` 시그니처 확장
+
+**Files:**
+- Modify: `src/notifier.py`
+
+**Step 1: `notify_close()` 메서드 교체**
+
+기존 `notify_close()`를 아래로 교체한다. `close_reason`, `estimated_pnl`, `net_pnl`, `diff` 파라미터가 추가된다.
+
+```python
+def notify_close(
+    self,
+    symbol: str,
+    side: str,
+    close_reason: str,      # "TP" | "SL" | "MANUAL"
+    exit_price: float,
+    estimated_pnl: float,   # 봇 계산 (entry-exit 기반)
+    net_pnl: float,         # 바이낸스 rp - |commission|
+    diff: float,            # net_pnl - estimated_pnl (슬리피지+수수료)
+) -> None:
+    emoji_map = {"TP": "✅", "SL": "❌", "MANUAL": "🔶"}
+    emoji = emoji_map.get(close_reason, "🔶")
+    msg = (
+        f"{emoji} **[{symbol}] {side} {close_reason} 청산**\n"
+        f"청산가:               `{exit_price:.4f}`\n"
+        f"예상 수익:            `{estimated_pnl:+.4f} USDT`\n"
+        f"실제 순수익:          `{net_pnl:+.4f} USDT`\n"
+        f"차이(슬리피지+수수료): `{diff:+.4f} USDT`"
+    )
+    self._send(msg)
+```
+
+**Step 2: 커밋**
+
+```bash
+git add src/notifier.py
+git commit -m "feat: extend notify_close with close_reason, net_pnl, diff fields"
+```
+
+---
+
+## Task 3: `src/user_data_stream.py` 신규 생성
+
+**Files:**
+- Create: `src/user_data_stream.py`
+
+**Step 1: 파일 전체 작성**
+
+```python
+import asyncio
+from typing import Callable
+from binance import AsyncClient, BinanceSocketManager
+from loguru import logger
+
+_KEEPALIVE_INTERVAL = 30 * 60   # 30분 (listenKey 만료 60분의 절반)
+_RECONNECT_DELAY    = 5         # 재연결 대기 초
+
+_CLOSE_ORDER_TYPES = {"TAKE_PROFIT_MARKET", "STOP_MARKET"}
+
+
+class UserDataStream:
+    """
+    Binance Futures User Data Stream을 구독하여 주문 체결 이벤트를 처리한다.
+
+    - listenKey 30분 keepalive 백그라운드 태스크
+    - 네트워크 단절 시 무한 재연결 루프
+    - ORDER_TRADE_UPDATE 이벤트에서 청산 주문만 필터링하여 콜백 호출
+    """
+
+    def __init__(
+        self,
+        exchange,                        # BinanceFuturesClient 인스턴스
+        on_order_filled: Callable,       # bot._on_position_closed 콜백
+    ):
+        self._exchange = exchange
+        self._on_order_filled = on_order_filled
+        self._listen_key: str | None = None
+        self._keepalive_task: asyncio.Task | None = None
+
+    async def start(self, api_key: str, api_secret: str) -> None:
+        """User Data Stream 메인 루프 — 봇 종료 시까지 실행."""
+        client = await AsyncClient.create(
+            api_key=api_key,
+            api_secret=api_secret,
+        )
+        bm = BinanceSocketManager(client)
+        try:
+            await self._run_loop(bm)
+        finally:
+            await client.close_connection()
+
+    async def _run_loop(self, bm: BinanceSocketManager) -> None:
+        """listenKey 발급 → 연결 → 재연결 무한 루프."""
+        while True:
+            try:
+                self._listen_key = await self._exchange.create_listen_key()
+                logger.info(f"User Data Stream listenKey 발급: {self._listen_key[:8]}...")
+
+                self._keepalive_task = asyncio.create_task(
+                    self._keepalive_loop(self._listen_key)
+                )
+
+                async with bm.futures_user_socket(self._listen_key) as stream:
+                    logger.info("User Data Stream 연결 완료")
+                    async for msg in stream:
+                        await self._handle_message(msg)
+
+            except asyncio.CancelledError:
+                logger.info("User Data Stream 정상 종료")
+                if self._listen_key:
+                    await self._exchange.delete_listen_key(self._listen_key)
+                if self._keepalive_task:
+                    self._keepalive_task.cancel()
+                break
+
+            except Exception as e:
+                logger.warning(
+                    f"User Data Stream 끊김: {e} — "
+                    f"{_RECONNECT_DELAY}초 후 재연결"
+                )
+                if self._keepalive_task:
+                    self._keepalive_task.cancel()
+                    self._keepalive_task = None
+                await asyncio.sleep(_RECONNECT_DELAY)
+
+    async def _keepalive_loop(self, listen_key: str) -> None:
+        """30분마다 listenKey를 갱신한다."""
+        while True:
+            await asyncio.sleep(_KEEPALIVE_INTERVAL)
+            try:
+                await self._exchange.keepalive_listen_key(listen_key)
+                logger.debug("listenKey 갱신 완료")
+            except Exception as e:
+                logger.warning(f"listenKey 갱신 실패: {e} — 재연결 루프가 처리")
+                break
+
+    async def _handle_message(self, msg: dict) -> None:
+        """ORDER_TRADE_UPDATE 이벤트에서 청산 주문을 필터링하여 콜백을 호출한다."""
+        if msg.get("e") != "ORDER_TRADE_UPDATE":
+            return
+
+        order = msg.get("o", {})
+
+        # x: Execution Type, X: Order Status
+        if order.get("x") != "TRADE" or order.get("X") != "FILLED":
+            return
+
+        order_type   = order.get("o", "")
+        is_reduce    = order.get("R", False)
+        realized_pnl = float(order.get("rp", "0"))
+
+        # 청산 주문 판별: reduceOnly이거나, TP/SL 타입이거나, rp != 0
+        is_close = is_reduce or order_type in _CLOSE_ORDER_TYPES or realized_pnl != 0
+        if not is_close:
+            return
+
+        commission = abs(float(order.get("n", "0")))
+        net_pnl    = realized_pnl - commission
+        exit_price = float(order.get("ap", "0"))
+
+        if order_type == "TAKE_PROFIT_MARKET":
+            close_reason = "TP"
+        elif order_type == "STOP_MARKET":
+            close_reason = "SL"
+        else:
+            close_reason = "MANUAL"
+
+        logger.info(
+            f"청산 감지({close_reason}): exit={exit_price:.4f}, "
+            f"rp={realized_pnl:+.4f}, commission={commission:.4f}, "
+            f"net_pnl={net_pnl:+.4f}"
+        )
+
+        await self._on_order_filled(
+            net_pnl=net_pnl,
+            close_reason=close_reason,
+            exit_price=exit_price,
+        )
+```
+
+**Step 2: 커밋**
+
+```bash
+git add src/user_data_stream.py
+git commit -m "feat: add UserDataStream with keepalive and reconnect loop"
+```
+
+---
+
+## Task 4: `bot.py` 수정 — 상태 변수 추가 및 `_open_position()` 저장
+
+**Files:**
+- Modify: `src/bot.py`
+
+**Step 1: `__init__`에 상태 변수 추가**
+
+`TradingBot.__init__()` 내부에서 `self.current_trade_side` 선언 바로 아래에 추가한다.
+
+```python
+self._entry_price: float | None = None
+self._entry_quantity: float | None = None
+```
+
+**Step 2: `_open_position()` 내부에서 진입가/수량 저장**
+
+`self.current_trade_side = signal` 바로 아래에 추가한다.
+
+```python
+self._entry_price = price
+self._entry_quantity = quantity
+```
+
+**Step 3: 커밋**
+
+```bash
+git add src/bot.py
+git commit -m "feat: store entry_price and entry_quantity on position open"
+```
+
+---
+
+## Task 5: `bot.py` 수정 — `_on_position_closed()` 콜백 추가
+
+**Files:**
+- Modify: `src/bot.py`
+
+**Step 1: `_calc_estimated_pnl()` 헬퍼 메서드 추가**
+
+`_close_position()` 메서드 바로 위에 추가한다.
+
+```python
+def _calc_estimated_pnl(self, exit_price: float) -> float:
+    """진입가·수량 기반 예상 PnL 계산 (수수료 미반영)."""
+    if self._entry_price is None or self._entry_quantity is None:
+        return 0.0
+    if self.current_trade_side == "LONG":
+        return (exit_price - self._entry_price) * self._entry_quantity
+    return (self._entry_price - exit_price) * self._entry_quantity
+```
+
+**Step 2: `_on_position_closed()` 콜백 추가**
+
+`_calc_estimated_pnl()` 바로 아래에 추가한다.
+
+```python
+async def _on_position_closed(
+    self,
+    net_pnl: float,
+    close_reason: str,
+    exit_price: float,
+) -> None:
+    """User Data Stream에서 청산 감지 시 호출되는 콜백."""
+    estimated_pnl = self._calc_estimated_pnl(exit_price)
+    diff = net_pnl - estimated_pnl
+
+    self.risk.record_pnl(net_pnl)
+
+    self.notifier.notify_close(
+        symbol=self.config.symbol,
+        side=self.current_trade_side or "UNKNOWN",
+        close_reason=close_reason,
+        exit_price=exit_price,
+        estimated_pnl=estimated_pnl,
+        net_pnl=net_pnl,
+        diff=diff,
+    )
+
+    logger.success(
+        f"포지션 청산({close_reason}): 예상={estimated_pnl:+.4f}, "
+        f"순수익={net_pnl:+.4f}, 차이={diff:+.4f} USDT"
+    )
+
+    # Flat 상태로 초기화
+    self.current_trade_side = None
+    self._entry_price = None
+    self._entry_quantity = None
+```
+
+**Step 3: 커밋**
+
+```bash
+git add src/bot.py
+git commit -m "feat: add _on_position_closed callback with net PnL and discord alert"
+```
+
+---
+
+## Task 6: `bot.py` 수정 — `_close_position()`에서 중복 후처리 제거
+
+**Files:**
+- Modify: `src/bot.py`
+
+**배경:** 봇이 직접 청산(`_close_and_reenter`)하는 경우에도 User Data Stream의 `ORDER_TRADE_UPDATE`가 발생한다. 중복 방지를 위해 `_close_position()`에서 `notify_close()`와 `record_pnl()` 호출을 제거한다.
+
+**Step 1: `_close_position()` 수정**
+
+기존 코드:
+```python
+async def _close_position(self, position: dict):
+    amt = abs(float(position["positionAmt"]))
+    side = "SELL" if float(position["positionAmt"]) > 0 else "BUY"
+    pos_side = "LONG" if side == "SELL" else "SHORT"
+    await self.exchange.cancel_all_orders()
+    await self.exchange.place_order(side=side, quantity=amt, reduce_only=True)
+
+    entry = float(position["entryPrice"])
+    mark  = float(position["markPrice"])
+    pnl   = (mark - entry) * amt if side == "SELL" else (entry - mark) * amt
+
+    self.notifier.notify_close(
+        symbol=self.config.symbol,
+        side=pos_side,
+        exit_price=mark,
+        pnl=pnl,
+    )
+    self.risk.record_pnl(pnl)
+    self.current_trade_side = None
+    logger.success(f"포지션 청산: PnL={pnl:.4f} USDT")
+```
+
+수정 후 (`notify_close`, `record_pnl`, `current_trade_side = None` 제거 — User Data Stream 콜백이 처리):
+```python
+async def _close_position(self, position: dict):
+    """포지션 청산 주문만 실행한다. PnL 기록/알림은 _on_position_closed 콜백이 담당."""
+    amt = abs(float(position["positionAmt"]))
+    side = "SELL" if float(position["positionAmt"]) > 0 else "BUY"
+    await self.exchange.cancel_all_orders()
+    await self.exchange.place_order(side=side, quantity=amt, reduce_only=True)
+    logger.info(f"청산 주문 전송 완료 (side={side}, qty={amt})")
+```
+
+**Step 2: 커밋**
+
+```bash
+git add src/bot.py
+git commit -m "refactor: remove duplicate pnl/notify from _close_position (handled by callback)"
+```
+
+---
+
+## Task 7: `bot.py` 수정 — `run()`에서 UserDataStream 병렬 실행
+
+**Files:**
+- Modify: `src/bot.py`
+
+**Step 1: import 추가**
+
+파일 상단 import 블록에 추가한다.
+
+```python
+from src.user_data_stream import UserDataStream
+```
+
+**Step 2: `run()` 메서드 수정**
+
+기존:
+```python
+async def run(self):
+    logger.info(f"봇 시작: {self.config.symbol}, 레버리지 {self.config.leverage}x")
+    await self._recover_position()
+    balance = await self.exchange.get_balance()
+    self.risk.set_base_balance(balance)
+    logger.info(f"기준 잔고 설정: {balance:.2f} USDT (동적 증거금 비율 기준점)")
+    await self.stream.start(
+        api_key=self.config.api_key,
+        api_secret=self.config.api_secret,
+    )
+```
+
+수정 후:
+```python
+async def run(self):
+    logger.info(f"봇 시작: {self.config.symbol}, 레버리지 {self.config.leverage}x")
+    await self._recover_position()
+    balance = await self.exchange.get_balance()
+    self.risk.set_base_balance(balance)
+    logger.info(f"기준 잔고 설정: {balance:.2f} USDT (동적 증거금 비율 기준점)")
+
+    user_stream = UserDataStream(
+        exchange=self.exchange,
+        on_order_filled=self._on_position_closed,
+    )
+
+    await asyncio.gather(
+        self.stream.start(
+            api_key=self.config.api_key,
+            api_secret=self.config.api_secret,
+        ),
+        user_stream.start(
+            api_key=self.config.api_key,
+            api_secret=self.config.api_secret,
+        ),
+    )
+```
+
+**Step 3: 커밋**
+
+```bash
+git add src/bot.py
+git commit -m "feat: run UserDataStream in parallel with candle stream"
+```
+
+---
+
+## Task 8: README.md 업데이트
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: 기능 목록에 User Data Stream 항목 추가**
+
+README의 주요 기능 섹션에 아래 내용을 추가한다.
+
+- **실시간 TP/SL 감지**: Binance User Data Stream으로 TP/SL 작동을 즉시 감지 (캔들 마감 대기 없음)
+- **순수익(Net PnL) 기록**: 바이낸스 `realizedProfit - commission`으로 정확한 순수익 계산
+- **Discord 상세 청산 알림**: 예상 수익 vs 실제 순수익 + 슬리피지/수수료 차이 표시
+- **listenKey 자동 갱신**: 30분 keepalive + 네트워크 단절 시 자동 재연결
+
+**Step 2: 커밋**
+
+```bash
+git add README.md
+git commit -m "docs: update README with User Data Stream TP/SL detection feature"
+```
+
+---
+
+## 최종 검증
+
+봇 실행 후 로그에서 아래 메시지가 순서대로 나타나면 정상 동작:
+
+```
+INFO  | User Data Stream listenKey 발급: xxxxxxxx...
+INFO  | User Data Stream 연결 완료
+DEBUG | listenKey 갱신 완료  ← 30분 후
+INFO  | 청산 감지(TP): exit=1.3393, rp=+0.4821, commission=0.0209, net_pnl=+0.4612
+SUCCESS | 포지션 청산(TP): 예상=+0.4821, 순수익=+0.4612, 차이=-0.0209 USDT
+```
+
+Discord에는 아래 형식의 알림이 전송됨:
+
+```
+✅ [XRPUSDT] SHORT TP 청산
+청산가:               1.3393
+예상 수익:            +0.4821 USDT
+실제 순수익:          +0.4612 USDT
+차이(슬리피지+수수료): -0.0209 USDT
+```

docs/plans/2026-03-03-optuna-precision-objective-plan.md

@@ -0,0 +1,80 @@
+# Optuna 목적함수를 Precision 중심으로 변경
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 현재 ROC-AUC만 최적화하는 Optuna objective를 **recall >= 0.35 제약 하에서 precision을 최대화**하는 방향으로 변경한다. AUC는 threshold-independent 지표라 실제 운용 시점의 성능(precision)을 반영하지 못하며, 오탐(false positive = 잘못된 진입)이 실제 손실을 발생시키므로 precision 우선 최적화가 필요하다.
+
+**Tech Stack:** Python, LightGBM, Optuna, scikit-learn
+
+---
+
+## 변경 파일
+- `scripts/tune_hyperparams.py` (유일한 변경 대상)
+
+---
+
+## 구현 단계
+
+### 1. `_find_best_precision_at_recall` 헬퍼 함수 추가
+- `sklearn.metrics.precision_recall_curve`로 recall >= min_recall 조건의 최대 precision과 threshold 반환
+- 조건 불만족 시 `(0.0, 0.0, 0.50)` fallback
+- train_model.py:277-292와 동일한 로직
+
+### 2. `_walk_forward_cv` 수정
+- 기존 반환: `(mean_auc, fold_aucs)` → 신규: `(mean_score, details_dict)`
+- `details_dict` 키: `fold_aucs`, `fold_precisions`, `fold_recalls`, `fold_thresholds`, `fold_n_pos`, `mean_auc`, `mean_precision`, `mean_recall`
+- **Score 공식**: `precision + auc * 0.001` (AUC는 precision 동률 시 tiebreaker)
+- fold 내 양성 < 3개면 해당 fold precision=0.0으로 처리, 평균 계산에서 제외
+- 인자 추가: `min_recall: float = 0.35`
+- import 추가: `from sklearn.metrics import precision_recall_curve`
+- Pruning: 양성 충분한 fold만 report하여 false pruning 방지
+
+### 3. `make_objective` 수정
+- `min_recall` 인자 추가 → `_walk_forward_cv`에 전달
+- `trial.set_user_attr`로 precision/recall/threshold/n_pos 등 저장
+- 반환값: `mean_score` (precision + auc * 0.001)
+
+### 4. `measure_baseline` 수정
+- `min_recall` 인자 추가
+- 반환값을 `(mean_score, details_dict)` 형태로 변경
+
+### 5. `--min-recall` CLI 인자 추가
+- `parser.add_argument("--min-recall", type=float, default=0.35)`
+- `make_objective`와 `measure_baseline`에 전달
+
+### 6. `print_report` 수정
+- Best Score, Precision, AUC 모두 표시
+- 폴드별 AUC + Precision + Recall + Threshold + 양성수 표시
+- Baseline과 비교 시 precision 기준 개선폭 표시
+
+### 7. `save_results` 수정
+- JSON에 `min_recall_constraint`, precision/recall/threshold 필드 추가
+- `best_trial` 내 `score`, `precision`, `recall`, `threshold`, `fold_precisions`, `fold_recalls`, `fold_thresholds`, `fold_n_pos` 추가
+- `best_trial.params` 구조는 그대로 유지 (하위호환)
+
+### 8. 비교 로직 및 기타 수정
+- line 440: `study.best_value > baseline_auc` → `study.best_value > baseline_score`
+- `study_name`: `"lgbm_wf_auc"` → `"lgbm_wf_precision"`
+- progress callback: Precision과 AUC 동시 표시
+- `n_warmup_steps` 2 → 3 (precision이 AUC보다 노이즈가 크므로)
+
+---
+
+## 검증 방법
+
+```bash
+# 기본 실행 (min_recall=0.35)
+python scripts/tune_hyperparams.py --trials 10 --folds 3
+
+# min_recall 조절
+python scripts/tune_hyperparams.py --trials 10 --min-recall 0.4
+
+# 기존 테스트 통과 확인
+bash scripts/run_tests.sh
+```
+
+확인 포인트:
+- 폴드별 precision/recall/threshold가 리포트에 표시되는지
+- recall >= min_recall 제약이 올바르게 동작하는지
+- active_lgbm_params.json이 precision 기준으로 갱신되는지
+- train_model.py가 새 JSON 포맷을 기존과 동일하게 읽는지

models/training_log.json

@@ -31,5 +31,400 @@
     "samples": 1696,
     "features": 21,
     "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:03:56.314547",
+    "auc": 0.5406,
+    "samples": 1707,
+    "features": 21,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:12:23.866860",
+    "auc": 0.502,
+    "samples": 3269,
+    "features": 21,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:46:29.599674",
+    "backend": "mlx",
+    "auc": 0.516,
+    "samples": 6470,
+    "train_sec": 1.3,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T21:50:12.449819",
+    "backend": "lgbm",
+    "auc": 0.4772,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:50:32.491318",
+    "backend": "lgbm",
+    "auc": 0.4943,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:50:48.665654",
+    "backend": "lgbm",
+    "auc": 0.4943,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:51:02.539565",
+    "backend": "lgbm",
+    "auc": 0.4943,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:51:09.830250",
+    "backend": "lgbm",
+    "auc": 0.4925,
+    "samples": 1716,
+    "features": 13,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:51:20.133303",
+    "backend": "lgbm",
+    "auc": 0.54,
+    "samples": 1716,
+    "features": 13,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:51:25.445363",
+    "backend": "lgbm",
+    "auc": 0.4943,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T21:52:24.296191",
+    "backend": "lgbm",
+    "auc": 0.54,
+    "samples": 1716,
+    "features": 13,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T22:00:34.737597",
+    "backend": "lgbm",
+    "auc": 0.5097,
+    "samples": 6470,
+    "features": 21,
+    "time_weight_decay": 3.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T22:12:06.299119",
+    "backend": "mlx",
+    "auc": 0.5746,
+    "samples": 533,
+    "train_sec": 0.2,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T22:13:20.434893",
+    "backend": "mlx",
+    "auc": 0.5663,
+    "samples": 533,
+    "train_sec": 0.2,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T22:15:43.163315",
+    "backend": "lgbm",
+    "auc": 0.5581,
+    "samples": 533,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T22:18:59.852831",
+    "backend": "lgbm",
+    "auc": 0.5504,
+    "samples": 533,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T22:19:29.532472",
+    "backend": "lgbm",
+    "auc": 0.5504,
+    "samples": 533,
+    "features": 21,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T22:19:30.938005",
+    "backend": "mlx",
+    "auc": 0.5714,
+    "samples": 533,
+    "train_sec": 0.1,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T22:26:46.459326",
+    "backend": "mlx",
+    "auc": 0.6167,
+    "samples": 533,
+    "train_sec": 0.2,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T22:45:55.473533",
+    "backend": "lgbm",
+    "auc": 0.556,
+    "samples": 533,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T23:04:51.194544",
+    "backend": "mlx",
+    "auc": 0.5972,
+    "samples": 533,
+    "train_sec": 0.1,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T23:59:27.956019",
+    "backend": "mlx",
+    "auc": 0.5595,
+    "best_threshold": 0.9538,
+    "best_precision": 0.462,
+    "best_recall": 0.171,
+    "samples": 533,
+    "train_sec": 0.2,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-02T00:40:15.931055",
+    "backend": "mlx",
+    "auc": 0.5829,
+    "best_threshold": 0.9609,
+    "best_precision": 0.6,
+    "best_recall": 0.171,
+    "samples": 534,
+    "train_sec": 0.2,
+    "time_weight_decay": 2.0,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-02T00:54:32.264425",
+    "backend": "lgbm",
+    "auc": 0.5607,
+    "best_threshold": 0.6532,
+    "best_precision": 0.467,
+    "best_recall": 0.2,
+    "samples": 533,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-02T01:07:30.690959",
+    "backend": "lgbm",
+    "auc": 0.5579,
+    "best_threshold": 0.6511,
+    "best_precision": 0.4,
+    "best_recall": 0.171,
+    "samples": 533,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-02T02:00:45.931227",
+    "backend": "lgbm",
+    "auc": 0.5752,
+    "best_threshold": 0.6307,
+    "best_precision": 0.471,
+    "best_recall": 0.229,
+    "samples": 533,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-02T14:51:09.101738",
+    "backend": "lgbm",
+    "auc": 0.5361,
+    "best_threshold": 0.5308,
+    "best_precision": 0.406,
+    "best_recall": 0.371,
+    "samples": 533,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": "models/tune_results_20260302_144749.json",
+    "lgbm_params": {
+      "n_estimators": 434,
+      "learning_rate": 0.123659,
+      "num_leaves": 14,
+      "min_child_samples": 10,
+      "subsample": 0.929062,
+      "colsample_bytree": 0.94633,
+      "reg_alpha": 0.573971,
+      "reg_lambda": 0.000157,
+      "max_depth": 6
+    },
+    "weight_scale": 1.783105
+  },
+  {
+    "date": "2026-03-02T18:10:27.584046",
+    "backend": "lgbm",
+    "auc": 0.5466,
+    "best_threshold": 0.6424,
+    "best_precision": 0.426,
+    "best_recall": 0.556,
+    "samples": 535,
+    "features": 23,
+    "time_weight_decay": 0.5,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": null,
+    "lgbm_params": {
+      "n_estimators": 434,
+      "learning_rate": 0.123659,
+      "max_depth": 6,
+      "num_leaves": 14,
+      "min_child_samples": 10,
+      "subsample": 0.929062,
+      "colsample_bytree": 0.94633,
+      "reg_alpha": 0.573971,
+      "reg_lambda": 0.000157
+    },
+    "weight_scale": 1.783105
+  },
+  {
+    "date": "2026-03-03T00:12:17.351458",
+    "backend": "lgbm",
+    "auc": 0.949,
+    "best_threshold": 0.42,
+    "best_precision": 0.56,
+    "best_recall": 0.538,
+    "samples": 1524,
+    "features": 23,
+    "time_weight_decay": 0.5,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": null,
+    "lgbm_params": {
+      "n_estimators": 434,
+      "learning_rate": 0.123659,
+      "max_depth": 6,
+      "num_leaves": 14,
+      "min_child_samples": 10,
+      "subsample": 0.929062,
+      "colsample_bytree": 0.94633,
+      "reg_alpha": 0.573971,
+      "reg_lambda": 0.000157
+    },
+    "weight_scale": 1.783105
+  },
+  {
+    "date": "2026-03-03T00:13:56.456518",
+    "backend": "lgbm",
+    "auc": 0.9439,
+    "best_threshold": 0.6558,
+    "best_precision": 0.667,
+    "best_recall": 0.154,
+    "samples": 1524,
+    "features": 23,
+    "time_weight_decay": 2.0,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": null,
+    "lgbm_params": {
+      "n_estimators": 434,
+      "learning_rate": 0.123659,
+      "max_depth": 6,
+      "num_leaves": 14,
+      "min_child_samples": 10,
+      "subsample": 0.929062,
+      "colsample_bytree": 0.94633,
+      "reg_alpha": 0.573971,
+      "reg_lambda": 0.000157
+    },
+    "weight_scale": 1.783105
+  },
+  {
+    "date": "2026-03-03T00:20:43.712971",
+    "backend": "lgbm",
+    "auc": 0.9473,
+    "best_threshold": 0.3015,
+    "best_precision": 0.465,
+    "best_recall": 0.769,
+    "samples": 1524,
+    "features": 23,
+    "time_weight_decay": 0.5,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": "models/active_lgbm_params.json",
+    "lgbm_params": {
+      "n_estimators": 195,
+      "learning_rate": 0.033934,
+      "max_depth": 3,
+      "num_leaves": 7,
+      "min_child_samples": 11,
+      "subsample": 0.998659,
+      "colsample_bytree": 0.837233,
+      "reg_alpha": 0.007008,
+      "reg_lambda": 0.80039
+    },
+    "weight_scale": 0.718348
+  },
+  {
+    "date": "2026-03-03T00:39:05.427160",
+    "backend": "lgbm",
+    "auc": 0.9436,
+    "best_threshold": 0.3041,
+    "best_precision": 0.467,
+    "best_recall": 0.269,
+    "samples": 1524,
+    "features": 23,
+    "time_weight_decay": 0.5,
+    "model_path": "models/lgbm_filter.pkl",
+    "tuned_params_path": "models/active_lgbm_params.json",
+    "lgbm_params": {
+      "n_estimators": 221,
+      "learning_rate": 0.031072,
+      "max_depth": 5,
+      "num_leaves": 20,
+      "min_child_samples": 39,
+      "subsample": 0.83244,
+      "colsample_bytree": 0.526349,
+      "reg_alpha": 0.062177,
+      "reg_lambda": 0.082872
+    },
+    "weight_scale": 1.431662
   }
 ]

requirements.txt

@@ -1,4 +1,4 @@
-python-binance==1.0.19
+python-binance>=1.0.28
 pandas>=2.3.2
 pandas-ta==0.4.71b0
 python-dotenv==1.0.0
@@ -12,3 +12,5 @@ lightgbm>=4.3.0
 scikit-learn>=1.4.0
 joblib>=1.3.0
 pyarrow>=15.0.0
+onnxruntime>=1.18.0
+optuna>=3.6.0

scripts/deploy_model.sh

@@ -1,66 +1,91 @@
 #!/usr/bin/env bash
 # 맥미니에서 학습한 모델을 LXC 컨테이너 볼륨 경로로 전송한다.
-# 사용법: bash scripts/deploy_model.sh [LXC_HOST] [LXC_MODELS_PATH]
+# 사용법: bash scripts/deploy_model.sh [lgbm|mlx]
 #
 # 예시:
-#   bash scripts/deploy_model.sh 10.1.10.28 /path/to/cointrader/models
-#   bash scripts/deploy_model.sh root@10.1.10.28 /root/cointrader/models
+#   bash scripts/deploy_model.sh        # LightGBM (기본값)
+#   bash scripts/deploy_model.sh mlx    # MLX 신경망
 
 set -euo pipefail
 
-LXC_HOST="${1:-root@10.1.10.24}"
-LXC_MODELS_PATH="${2:-/root/cointrader/models}"
-LOCAL_MODEL="models/lgbm_filter.pkl"
+BACKEND="${1:-lgbm}"
+LXC_HOST="root@10.1.10.24"
+LXC_MODELS_PATH="/root/cointrader/models"
 LOCAL_LOG="models/training_log.json"
 
-if [[ ! -f "$LOCAL_MODEL" ]]; then
-  echo "[오류] 모델 파일 없음: $LOCAL_MODEL"
-  echo "먼저 python scripts/train_model.py 를 실행하세요."
-  exit 1
+# ── 백엔드별 파일 목록 설정 ──────────────────────────────────────────────────
+# mlx: ONNX 파일만 전송 (Linux 서버는 onnxruntime으로 추론)
+# lgbm: pkl 파일 전송
+if [ "$BACKEND" = "mlx" ]; then
+  LOCAL_FILES=("models/mlx_filter.weights.onnx")
+else
+  LOCAL_FILES=("models/lgbm_filter.pkl")
 fi
 
-echo "=== 모델 전송 시작 ==="
-echo "  대상: ${LXC_HOST}:${LXC_MODELS_PATH}"
-echo "  파일: $LOCAL_MODEL"
-
-# 기존 모델을 prev로 백업 (원격)
-ssh "${LXC_HOST}" "
-  if [ -f '${LXC_MODELS_PATH}/lgbm_filter.pkl' ]; then
-    cp '${LXC_MODELS_PATH}/lgbm_filter.pkl' '${LXC_MODELS_PATH}/lgbm_filter_prev.pkl'
-    echo '  기존 모델 백업 완료'
+# ── 파일 존재 확인 ────────────────────────────────────────────────────────────
+for f in "${LOCAL_FILES[@]}"; do
+  if [[ ! -f "$f" ]]; then
+    echo "[오류] 모델 파일 없음: $f"
+    exit 1
   fi
+done
+
+echo "=== 모델 전송 시작 (백엔드: ${BACKEND}) ==="
+echo "  대상: ${LXC_HOST}:${LXC_MODELS_PATH}"
+
+# ── 원격 디렉터리 생성 + 백업 + 상대 백엔드 파일 제거 ───────────────────────
+# lgbm 배포 시: 기존 lgbm 백업 후 ONNX 파일 삭제 (ONNX 우선순위 때문에 lgbm이 무시되는 것 방지)
+# mlx 배포 시: lgbm 파일 삭제 (명시적으로 mlx만 사용)
+ssh "${LXC_HOST}" "
   mkdir -p '${LXC_MODELS_PATH}'
+  if [ '$BACKEND' = 'lgbm' ]; then
+    if [ -f '${LXC_MODELS_PATH}/lgbm_filter.pkl' ]; then
+      cp '${LXC_MODELS_PATH}/lgbm_filter.pkl' '${LXC_MODELS_PATH}/lgbm_filter_prev.pkl'
+      echo '  기존 lgbm 모델 백업 완료'
+    fi
+    if [ -f '${LXC_MODELS_PATH}/mlx_filter.weights.onnx' ]; then
+      rm '${LXC_MODELS_PATH}/mlx_filter.weights.onnx'
+      echo '  ONNX 파일 제거 완료 (lgbm 우선 적용)'
+    fi
+  else
+    if [ -f '${LXC_MODELS_PATH}/lgbm_filter.pkl' ]; then
+      rm '${LXC_MODELS_PATH}/lgbm_filter.pkl'
+      echo '  lgbm 파일 제거 완료 (mlx 우선 적용)'
+    fi
+  fi
 "
 
-# 모델 파일 전송 (rsync 우선, 없으면 scp 폴백)
-if command -v rsync &>/dev/null && ssh "${LXC_HOST}" "command -v rsync" &>/dev/null; then
-  rsync -avz --progress \
-    "$LOCAL_MODEL" \
-    "${LXC_HOST}:${LXC_MODELS_PATH}/lgbm_filter.pkl"
-else
-  echo "  rsync 없음 → scp 사용"
-  scp "$LOCAL_MODEL" "${LXC_HOST}:${LXC_MODELS_PATH}/lgbm_filter.pkl"
-fi
-
-# 학습 로그도 함께 전송 (있을 경우)
-if [[ -f "$LOCAL_LOG" ]]; then
+# ── 파일 전송 헬퍼 (rsync 우선, scp 폴백) ────────────────────────────────────
+_send() {
+  local src="$1" dst="$2"
+  echo "  전송: $src → ${LXC_HOST}:$dst"
   if command -v rsync &>/dev/null && ssh "${LXC_HOST}" "command -v rsync" &>/dev/null; then
-    rsync -avz "$LOCAL_LOG" "${LXC_HOST}:${LXC_MODELS_PATH}/training_log.json"
+    rsync -avz --progress "$src" "${LXC_HOST}:$dst"
   else
-    scp "$LOCAL_LOG" "${LXC_HOST}:${LXC_MODELS_PATH}/training_log.json"
+    scp "$src" "${LXC_HOST}:$dst"
   fi
+}
+
+# ── 모델 파일 전송 ────────────────────────────────────────────────────────────
+for f in "${LOCAL_FILES[@]}"; do
+  _send "$f" "${LXC_MODELS_PATH}/$(basename "$f")"
+done
+
+# ── 학습 로그 전송 ────────────────────────────────────────────────────────────
+if [[ -f "$LOCAL_LOG" ]]; then
+  _send "$LOCAL_LOG" "${LXC_MODELS_PATH}/training_log.json"
   echo "  학습 로그 전송 완료"
 fi
 
 echo "=== 전송 완료 ==="
 echo ""
 
-# 봇 컨테이너가 실행 중이면 모델 핫리로드, 아니면 건너뜀
-echo "=== 핫리로드 시도 ==="
+# ── 핫리로드 안내 ────────────────────────────────────────────────────────────
+# 봇이 캔들마다 모델 파일 mtime을 감지해 자동 리로드한다.
+# 컨테이너가 실행 중이면 다음 캔들(최대 1분) 안에 자동 적용된다.
+echo "=== 모델 전송 완료 — 봇이 다음 캔들에서 자동 리로드합니다 ==="
 if ssh "${LXC_HOST}" "docker inspect -f '{{.State.Running}}' cointrader 2>/dev/null | grep -q true"; then
-  ssh "${LXC_HOST}" "docker exec cointrader python -c \
-    \"from src.ml_filter import MLFilter; f=MLFilter(); f.reload_model(); print('리로드 완료')\""
-  echo "=== 핫리로드 완료 ==="
+  echo "  컨테이너 실행 중: 다음 캔들 마감 시 자동 핫리로드 예정"
 else
-  echo "  cointrader 컨테이너가 실행 중이 아닙니다. 건너뜁니다."
+  echo "  cointrader 컨테이너가 실행 중이 아닙니다."
 fi

scripts/fetch_history.py

@@ -2,6 +2,11 @@
 바이낸스 선물 REST API로 과거 캔들 데이터를 수집해 parquet으로 저장한다.
 사용법: python scripts/fetch_history.py --symbol XRPUSDT --interval 1m --days 90
        python scripts/fetch_history.py --symbols XRPUSDT BTCUSDT ETHUSDT --days 90
+
+OI/펀딩비 수집 제약:
+  - OI 히스토리: 바이낸스 API 제한으로 최근 30일치만 제공 (period=15m, limit=500/req)
+  - 펀딩비: 8시간 주기 → 15분봉에 forward-fill 병합
+  - 30일 이전 구간은 oi_change=0, funding_rate=0으로 채움
 """
 import sys
 from pathlib import Path
@@ -9,6 +14,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 import asyncio
 import argparse
+import aiohttp
 from datetime import datetime, timezone, timedelta
 import pandas as pd
 from binance import AsyncClient
@@ -21,6 +27,7 @@ load_dotenv()
 # 1500개씩 가져오므로 90일 1m 데이터 = ~65회 요청/심볼
 # 심볼 간 딜레이 없이 연속 요청하면 레이트 리밋(-1003) 발생
 _REQUEST_DELAY = 0.3  # 초당 ~3.3 req → 안전 마진 충분
+_FAPI_BASE = "https://fapi.binance.com"
 
 
 def _now_ms() -> int:
@@ -107,15 +114,223 @@ async def fetch_klines_all(
     return dfs
 
 
+async def _fetch_oi_hist(
+    session: aiohttp.ClientSession,
+    symbol: str,
+    period: str = "15m",
+) -> pd.DataFrame:
+    """
+    바이낸스 /futures/data/openInterestHist 엔드포인트로 OI 히스토리를 수집한다.
+    API 제한: 최근 30일치만 제공, 1회 최대 500개.
+    """
+    url = f"{_FAPI_BASE}/futures/data/openInterestHist"
+    all_rows = []
+    # 30일 전부터 현재까지 수집
+    start_ts = int((datetime.now(timezone.utc) - timedelta(days=30)).timestamp() * 1000)
+    now_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+
+    print(f"  [{symbol}] OI 히스토리 수집 중 (최근 30일)...")
+    while start_ts < now_ms:
+        params = {
+            "symbol": symbol,
+            "period": period,
+            "limit": 500,
+            "startTime": start_ts,
+        }
+        async with session.get(url, params=params) as resp:
+            data = await resp.json()
+
+        if not data or not isinstance(data, list):
+            break
+
+        all_rows.extend(data)
+        last_ts = int(data[-1]["timestamp"])
+        if last_ts >= now_ms or len(data) < 500:
+            break
+        start_ts = last_ts + 1
+        await asyncio.sleep(_REQUEST_DELAY)
+
+    if not all_rows:
+        print(f"  [{symbol}] OI 데이터 없음 — 빈 DataFrame 반환")
+        return pd.DataFrame(columns=["oi", "oi_value"])
+
+    df = pd.DataFrame(all_rows)
+    df["timestamp"] = pd.to_datetime(df["timestamp"].astype(int), unit="ms", utc=True)
+    df = df.set_index("timestamp")
+    df = df[["sumOpenInterest", "sumOpenInterestValue"]].copy()
+    df.columns = ["oi", "oi_value"]
+    df["oi"] = df["oi"].astype(float)
+    df["oi_value"] = df["oi_value"].astype(float)
+    # OI 변화율 (1캔들 전 대비)
+    df["oi_change"] = df["oi"].pct_change(1).fillna(0)
+    print(f"  [{symbol}] OI 수집 완료: {len(df):,}행")
+    return df[["oi_change"]]
+
+
+async def _fetch_funding_rate(
+    session: aiohttp.ClientSession,
+    symbol: str,
+    days: int,
+) -> pd.DataFrame:
+    """
+    바이낸스 /fapi/v1/fundingRate 엔드포인트로 펀딩비 히스토리를 수집한다.
+    8시간 주기 데이터 → 15분봉 인덱스에 forward-fill로 병합 예정.
+    """
+    url = f"{_FAPI_BASE}/fapi/v1/fundingRate"
+    all_rows = []
+    start_ts = int((datetime.now(timezone.utc) - timedelta(days=days)).timestamp() * 1000)
+    now_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+
+    print(f"  [{symbol}] 펀딩비 히스토리 수집 중 ({days}일)...")
+    while start_ts < now_ms:
+        params = {
+            "symbol": symbol,
+            "startTime": start_ts,
+            "limit": 1000,
+        }
+        async with session.get(url, params=params) as resp:
+            data = await resp.json()
+
+        if not data or not isinstance(data, list):
+            break
+
+        all_rows.extend(data)
+        last_ts = int(data[-1]["fundingTime"])
+        if last_ts >= now_ms or len(data) < 1000:
+            break
+        start_ts = last_ts + 1
+        await asyncio.sleep(_REQUEST_DELAY)
+
+    if not all_rows:
+        print(f"  [{symbol}] 펀딩비 데이터 없음 — 빈 DataFrame 반환")
+        return pd.DataFrame(columns=["funding_rate"])
+
+    df = pd.DataFrame(all_rows)
+    df["timestamp"] = pd.to_datetime(df["fundingTime"].astype(int), unit="ms", utc=True)
+    df = df.set_index("timestamp")
+    df["funding_rate"] = df["fundingRate"].astype(float)
+    print(f"  [{symbol}] 펀딩비 수집 완료: {len(df):,}행")
+    return df[["funding_rate"]]
+
+
+def _merge_oi_funding(
+    candles: pd.DataFrame,
+    oi_df: pd.DataFrame,
+    funding_df: pd.DataFrame,
+) -> pd.DataFrame:
+    """
+    캔들 DataFrame에 OI 변화율과 펀딩비를 병합한다.
+    - oi_change: 15분봉 인덱스에 nearest merge (없는 구간은 0)
+    - funding_rate: 8시간 주기 → forward-fill 후 병합 (없는 구간은 0)
+    """
+    result = candles.copy()
+
+    # OI 병합: 타임스탬프 기준 reindex + nearest fill
+    if not oi_df.empty:
+        oi_reindexed = oi_df.reindex(result.index, method="nearest", tolerance=pd.Timedelta("8min"))
+        result["oi_change"] = oi_reindexed["oi_change"].fillna(0).astype(float)
+    else:
+        result["oi_change"] = 0.0
+
+    # 펀딩비 병합: forward-fill (8시간 주기이므로 다음 펀딩 시점까지 이전 값 유지)
+    if not funding_df.empty:
+        funding_reindexed = funding_df.reindex(
+            result.index.union(funding_df.index)
+        ).sort_index()
+        funding_reindexed = funding_reindexed["funding_rate"].ffill()
+        result["funding_rate"] = funding_reindexed.reindex(result.index).fillna(0).astype(float)
+    else:
+        result["funding_rate"] = 0.0
+
+    return result
+
+
+async def _fetch_oi_and_funding(
+    symbol: str,
+    days: int,
+    candles: pd.DataFrame,
+) -> pd.DataFrame:
+    """단일 심볼의 OI + 펀딩비를 수집해 캔들에 병합한다."""
+    async with aiohttp.ClientSession() as session:
+        oi_df = await _fetch_oi_hist(session, symbol)
+        await asyncio.sleep(1)
+        funding_df = await _fetch_funding_rate(session, symbol, days)
+
+    return _merge_oi_funding(candles, oi_df, funding_df)
+
+
+def upsert_parquet(path: "Path | str", new_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    기존 parquet 파일에 신규 데이터를 Upsert(병합)한다.
+
+    규칙:
+    - 기존 행의 oi_change / funding_rate가 0.0이면 신규 값으로 덮어씀
+    - 기존 행의 oi_change / funding_rate가 이미 0이 아니면 유지
+    - 신규 타임스탬프 행은 그냥 추가
+    - 결과는 timestamp 기준 오름차순 정렬, 중복 제거
+
+    Args:
+        path: 기존 parquet 경로 (없으면 new_df 그대로 반환)
+        new_df: 새로 수집한 DataFrame (timestamp index)
+
+    Returns:
+        병합된 DataFrame
+    """
+    path = Path(path)
+    if not path.exists():
+        return new_df.sort_index()
+
+    existing = pd.read_parquet(path)
+
+    # timestamp index 통일 (tz-aware UTC)
+    if existing.index.tz is None:
+        existing.index = existing.index.tz_localize("UTC")
+    if new_df.index.tz is None:
+        new_df.index = new_df.index.tz_localize("UTC")
+
+    # 기존 데이터에서 oi_change / funding_rate가 0.0인 행만 신규 값으로 업데이트
+    UPSERT_COLS = ["oi_change", "funding_rate"]
+    overlap_idx = existing.index.intersection(new_df.index)
+
+    for col in UPSERT_COLS:
+        if col not in existing.columns or col not in new_df.columns:
+            continue
+        # 겹치는 행 중 기존 값이 0.0인 경우에만 신규 값으로 교체
+        zero_mask = existing.loc[overlap_idx, col] == 0.0
+        update_idx = overlap_idx[zero_mask]
+        if len(update_idx) > 0:
+            existing.loc[update_idx, col] = new_df.loc[update_idx, col]
+
+    # 신규 타임스탬프 행 추가 (기존에 없는 것만)
+    new_only_idx = new_df.index.difference(existing.index)
+    if len(new_only_idx) > 0:
+        existing = pd.concat([existing, new_df.loc[new_only_idx]])
+
+    # 컬럼 불일치(기존 parquet에 oi_change/funding_rate 없음)로 생긴 NaN을 0으로 채움
+    for col in UPSERT_COLS:
+        if col in existing.columns:
+            existing[col] = existing[col].fillna(0.0)
+
+    return existing.sort_index()
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="바이낸스 선물 과거 캔들 수집. 단일 심볼 또는 멀티 심볼 병합 저장."
     )
     parser.add_argument("--symbols", nargs="+", default=["XRPUSDT"])
     parser.add_argument("--symbol",   default=None, help="단일 심볼 (--symbols 미사용 시)")
-    parser.add_argument("--interval", default="1m")
-    parser.add_argument("--days",     type=int, default=90)
-    parser.add_argument("--output",   default="data/xrpusdt_1m.parquet")
+    parser.add_argument("--interval", default="15m")
+    parser.add_argument("--days",     type=int, default=365)
+    parser.add_argument("--output",   default="data/combined_15m.parquet")
+    parser.add_argument(
+        "--no-oi", action="store_true",
+        help="OI/펀딩비 수집을 건너뜀 (캔들 데이터만 저장)",
+    )
+    parser.add_argument(
+        "--no-upsert", action="store_true",
+        help="기존 parquet을 Upsert하지 않고 새로 덮어씀 (기본: Upsert 활성화)",
+    )
     args = parser.parse_args()
 
     # 하위 호환: --symbol 단독 사용 시 symbols로 통합
@@ -124,8 +339,13 @@ def main():
 
     if len(args.symbols) == 1:
         df = asyncio.run(fetch_klines(args.symbols[0], args.interval, args.days))
+        if not args.no_oi:
+            print(f"\n[OI/펀딩비] {args.symbols[0]} 수집 중...")
+            df = asyncio.run(_fetch_oi_and_funding(args.symbols[0], args.days, df))
+        if not args.no_upsert:
+            df = upsert_parquet(args.output, df)
         df.to_parquet(args.output)
-        print(f"저장 완료: {args.output} ({len(df):,}행)")
+        print(f"{'Upsert' if not args.no_upsert else '저장'} 완료: {args.output} ({len(df):,}행, {len(df.columns)}컬럼)")
     else:
         # 멀티 심볼: 단일 클라이언트로 순차 수집 후 타임스탬프 기준 inner join 병합
         dfs = asyncio.run(fetch_klines_all(args.symbols, args.interval, args.days))
@@ -139,9 +359,16 @@ def main():
                 how="inner",
             )
 
+        # 주 심볼(XRP)에 대해서만 OI/펀딩비 수집 후 병합
+        if not args.no_oi:
+            print(f"\n[OI/펀딩비] {primary} 수집 중...")
+            merged = asyncio.run(_fetch_oi_and_funding(primary, args.days, merged))
+
         output = args.output.replace("xrpusdt", "combined")
+        if not args.no_upsert:
+            merged = upsert_parquet(output, merged)
         merged.to_parquet(output)
-        print(f"\n병합 저장 완료: {output} ({len(merged):,}행, {len(merged.columns)}컬럼)")
+        print(f"\n{'Upsert' if not args.no_upsert else '병합 저장'} 완료: {output} ({len(merged):,}행, {len(merged.columns)}컬럼)")
 
 
 if __name__ == "__main__":

scripts/run_optuna.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Optuna로 LightGBM 하이퍼파라미터를 탐색하고 결과를 출력한다.
+# 사람이 결과를 확인·승인한 후 train_model.py에 수동으로 반영하는 방식.
+#
+# 사용법:
+#   bash scripts/run_optuna.sh              # 기본 (50 trials, 5폴드)
+#   bash scripts/run_optuna.sh 100          # 100 trials
+#   bash scripts/run_optuna.sh 100 3        # 100 trials, 3폴드
+#   bash scripts/run_optuna.sh 10 3 --no-baseline  # 빠른 테스트
+#
+# 결과 확인 후 승인하면:
+#   python scripts/train_model.py --tuned-params models/tune_results_YYYYMMDD_HHMMSS.json
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+VENV_PATH="${VENV_PATH:-$PROJECT_ROOT/.venv}"
+if [ -f "$VENV_PATH/bin/activate" ]; then
+    # shellcheck source=/dev/null
+    source "$VENV_PATH/bin/activate"
+else
+    echo "경고: 가상환경을 찾을 수 없습니다 ($VENV_PATH). 시스템 Python을 사용합니다." >&2
+fi
+
+TRIALS="${1:-50}"
+FOLDS="${2:-5}"
+EXTRA_ARGS="${3:-}"
+
+cd "$PROJECT_ROOT"
+
+echo "=== Optuna 하이퍼파라미터 탐색 ==="
+echo "  trials=${TRIALS}, folds=${FOLDS}"
+echo ""
+
+python scripts/tune_hyperparams.py \
+    --trials "$TRIALS" \
+    --folds  "$FOLDS" \
+    $EXTRA_ARGS
+
+echo ""
+echo "=== 탐색 완료 ==="
+echo ""
+echo "결과 JSON을 확인하고 승인하면 아래 명령으로 재학습하세요:"
+echo "  python scripts/train_model.py --tuned-params models/tune_results_<timestamp>.json"
+echo ""
+echo "Walk-Forward 검증과 함께 재학습:"
+echo "  python scripts/train_model.py --tuned-params models/tune_results_<timestamp>.json --wf"

scripts/run_tests.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# 전체 테스트 실행 스크립트
+#
+# 사용법:
+#   bash scripts/run_tests.sh           # 전체 실행
+#   bash scripts/run_tests.sh -k bot    # 특정 키워드 필터
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+VENV_PATH="${VENV_PATH:-$PROJECT_ROOT/.venv}"
+if [ -f "$VENV_PATH/bin/activate" ]; then
+    # shellcheck source=/dev/null
+    source "$VENV_PATH/bin/activate"
+else
+    echo "경고: 가상환경을 찾을 수 없습니다 ($VENV_PATH). 시스템 Python을 사용합니다." >&2
+fi
+
+cd "$PROJECT_ROOT"
+
+python -m pytest tests/ \
+    -v \
+    "$@"

scripts/test_reverse_reenter.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# 반대 시그널 재진입 기능 테스트 스크립트
+# 사용법: bash scripts/test_reverse_reenter.sh [task]
+#
+# 예시:
+#   bash scripts/test_reverse_reenter.sh          # 전체 태스크 순서대로 실행
+#   bash scripts/test_reverse_reenter.sh 1        # Task 1: 신규 테스트만 (실패 확인)
+#   bash scripts/test_reverse_reenter.sh 2        # Task 2: _close_and_reenter 메서드 테스트
+#   bash scripts/test_reverse_reenter.sh 3        # Task 3: process_candle 분기 테스트
+#   bash scripts/test_reverse_reenter.sh bot      # test_bot.py 전체
+#   bash scripts/test_reverse_reenter.sh all      # tests/ 전체
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+VENV_PATH="${VENV_PATH:-$PROJECT_ROOT/.venv}"
+if [ -f "$VENV_PATH/bin/activate" ]; then
+    # shellcheck source=/dev/null
+    source "$VENV_PATH/bin/activate"
+else
+    echo "경고: 가상환경을 찾을 수 없습니다 ($VENV_PATH). 시스템 Python을 사용합니다." >&2
+fi
+
+cd "$PROJECT_ROOT"
+
+TASK="${1:-all}"
+
+# ── 태스크별 테스트 이름 ──────────────────────────────────────────────────────
+TASK1_TESTS=(
+    "tests/test_bot.py::test_close_and_reenter_calls_open_when_ml_passes"
+    "tests/test_bot.py::test_close_and_reenter_skips_open_when_ml_blocks"
+    "tests/test_bot.py::test_close_and_reenter_skips_open_when_max_positions_reached"
+)
+
+TASK2_TESTS=(
+    "tests/test_bot.py::test_close_and_reenter_calls_open_when_ml_passes"
+    "tests/test_bot.py::test_close_and_reenter_skips_open_when_ml_blocks"
+    "tests/test_bot.py::test_close_and_reenter_skips_open_when_max_positions_reached"
+)
+
+TASK3_TESTS=(
+    "tests/test_bot.py::test_process_candle_calls_close_and_reenter_on_reverse_signal"
+)
+
+run_pytest() {
+    echo ""
+    echo "▶ pytest $*"
+    echo "────────────────────────────────────────"
+    python -m pytest "$@" -v
+}
+
+case "$TASK" in
+    1)
+        echo "=== Task 1: 신규 테스트 실행 (구현 전 → FAIL 예상) ==="
+        run_pytest "${TASK1_TESTS[@]}"
+        ;;
+    2)
+        echo "=== Task 2: _close_and_reenter 메서드 테스트 (구현 후 → PASS 예상) ==="
+        run_pytest "${TASK2_TESTS[@]}"
+        ;;
+    3)
+        echo "=== Task 3: process_candle 분기 테스트 (수정 후 → PASS 예상) ==="
+        run_pytest "${TASK3_TESTS[@]}"
+        ;;
+    bot)
+        echo "=== test_bot.py 전체 ==="
+        run_pytest tests/test_bot.py
+        ;;
+    all)
+        echo "=== 전체 테스트 스위트 ==="
+        run_pytest tests/
+        ;;
+    *)
+        echo "알 수 없는 태스크: $TASK"
+        echo "사용법: bash scripts/test_reverse_reenter.sh [1|2|3|bot|all]"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "=== 완료 ==="

scripts/train_and_deploy.sh

@@ -1,47 +1,90 @@
 #!/usr/bin/env bash
 # 맥미니에서 전체 학습 파이프라인을 실행하고 LXC로 배포한다.
-# 사용법: bash scripts/train_and_deploy.sh [LXC_HOST] [LXC_MODELS_PATH]
+# 사용법: bash scripts/train_and_deploy.sh [mlx|lgbm] [wf-splits]
 #
 # 예시:
-#   bash scripts/train_and_deploy.sh
-#   bash scripts/train_and_deploy.sh root@10.1.10.24 /root/cointrader/models
+#   bash scripts/train_and_deploy.sh             # LightGBM + Walk-Forward 5폴드 (기본값)
+#   bash scripts/train_and_deploy.sh mlx         # MLX GPU 학습 + Walk-Forward 5폴드
+#   bash scripts/train_and_deploy.sh lgbm 3      # LightGBM + Walk-Forward 3폴드
+#   bash scripts/train_and_deploy.sh mlx 0       # MLX 학습만 (Walk-Forward 건너뜀)
+#   bash scripts/train_and_deploy.sh lgbm 0      # LightGBM 학습만 (Walk-Forward 건너뜀)
 
 set -euo pipefail
 
-LXC_HOST="${1:-root@10.1.10.24}"
-LXC_MODELS_PATH="${2:-/root/cointrader/models}"
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+VENV_PATH="${VENV_PATH:-$PROJECT_ROOT/.venv}"
+if [ -f "$VENV_PATH/bin/activate" ]; then
+    # shellcheck source=/dev/null
+    source "$VENV_PATH/bin/activate"
+else
+    echo "경고: 가상환경을 찾을 수 없습니다 ($VENV_PATH). 시스템 Python을 사용합니다." >&2
+fi
+
+BACKEND="${1:-lgbm}"
+WF_SPLITS="${2:-5}"   # 두 번째 인자: Walk-Forward 폴드 수 (0이면 건너뜀)
+
 cd "$PROJECT_ROOT"
 
-echo "=== [1/3] 데이터 수집 (XRP + BTC + ETH 3심볼) ==="
+mkdir -p data
+
+PARQUET_FILE="data/combined_15m.parquet"
+
+echo "=== [1/3] 데이터 수집 (XRP + BTC + ETH 3심볼 + OI/펀딩비) ==="
+if [ ! -f "$PARQUET_FILE" ]; then
+    echo "  [최초 실행] 기존 데이터 없음 → 1년치(365일) 전체 수집 (--no-upsert)"
+    FETCH_DAYS=365
+    UPSERT_FLAG="--no-upsert"
+else
+    echo "  [일반 실행] 기존 데이터 존재 → 35일치 Upsert (OI/펀딩비 0.0 구간 보충)"
+    FETCH_DAYS=35
+    UPSERT_FLAG=""
+fi
+
 python scripts/fetch_history.py \
     --symbols XRPUSDT BTCUSDT ETHUSDT \
-    --interval 1m \
-    --days 90 \
-    --output data/xrpusdt_1m.parquet
-# 결과: data/combined_1m.parquet (타임스탬프 기준 병합)
+    --interval 15m \
+    --days "$FETCH_DAYS" \
+    $UPSERT_FLAG \
+    --output "$PARQUET_FILE"
 
 echo ""
-echo "=== [2/3] 모델 학습 (21개 피처: XRP 13 + BTC/ETH 상관관계 8) ==="
-# TRAIN_BACKEND=mlx 로 설정하면 Apple Silicon GPU(Metal)를 사용한다 (기본: lgbm)
-BACKEND="${TRAIN_BACKEND:-lgbm}"
+echo "=== [2/3] 모델 학습 (23개 피처: XRP 13 + BTC/ETH 8 + OI/펀딩비 2) ==="
+DECAY="${TIME_WEIGHT_DECAY:-2.0}"
 if [ "$BACKEND" = "mlx" ]; then
-    echo "  백엔드: MLX (Apple Silicon GPU)"
-    python scripts/train_mlx_model.py --data data/combined_1m.parquet
+    echo "  백엔드: MLX (Apple Silicon GPU), decay=${DECAY}"
+    python scripts/train_mlx_model.py --data data/combined_15m.parquet --decay "$DECAY"
 else
-    echo "  백엔드: LightGBM (CPU)"
-    python scripts/train_model.py --data data/combined_1m.parquet
+    echo "  백엔드: LightGBM (CPU), decay=${DECAY}"
+    python scripts/train_model.py --data data/combined_15m.parquet --decay "$DECAY"
+fi
+
+# Walk-Forward 검증 (WF_SPLITS > 0 인 경우)
+if [ "$WF_SPLITS" -gt 0 ] 2>/dev/null; then
+    echo ""
+    echo "=== [2.5/3] Walk-Forward 검증 (${WF_SPLITS}폴드) ==="
+    if [ "$BACKEND" = "mlx" ]; then
+        python scripts/train_mlx_model.py \
+            --data data/combined_15m.parquet \
+            --decay "$DECAY" \
+            --wf \
+            --wf-splits "$WF_SPLITS"
+    else
+        python scripts/train_model.py \
+            --data data/combined_15m.parquet \
+            --decay "$DECAY" \
+            --wf \
+            --wf-splits "$WF_SPLITS"
+    fi
 fi
 
 echo ""
 echo "=== [3/3] LXC 배포 ==="
-bash scripts/deploy_model.sh "$LXC_HOST" "$LXC_MODELS_PATH"
+bash scripts/deploy_model.sh "$BACKEND"
 
 echo ""
 echo "=== 전체 파이프라인 완료 ==="
 echo ""
 echo "봇 재시작이 필요하면:"
-echo "  ssh ${LXC_HOST} 'cd /root/cointrader && docker compose restart cointrader'"
+echo "  ssh root@10.1.10.24 'cd /root/cointrader && docker compose restart cointrader'"

scripts/train_mlx_model.py

@@ -25,14 +25,40 @@ MLX_MODEL_PATH = Path("models/mlx_filter.weights")
 LOG_PATH = Path("models/training_log.json")
 
 
-def train_mlx(data_path: str) -> float:
+def _split_combined(df: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame | None, pd.DataFrame | None]:
+    """combined parquet에서 XRP/BTC/ETH DataFrame을 분리한다."""
+    xrp_cols = ["open", "high", "low", "close", "volume"]
+    xrp_df = df[xrp_cols].copy()
+
+    btc_df = None
+    eth_df = None
+    btc_raw = [c for c in df.columns if c.endswith("_btc")]
+    eth_raw = [c for c in df.columns if c.endswith("_eth")]
+
+    if btc_raw:
+        btc_df = df[btc_raw].copy()
+        btc_df.columns = [c.replace("_btc", "") for c in btc_raw]
+    if eth_raw:
+        eth_df = df[eth_raw].copy()
+        eth_df.columns = [c.replace("_eth", "") for c in eth_raw]
+
+    return xrp_df, btc_df, eth_df
+
+
+def train_mlx(data_path: str, time_weight_decay: float = 2.0) -> float:
     print(f"데이터 로드: {data_path}")
-    df = pd.read_parquet(data_path)
-    print(f"캔들 수: {len(df)}")
+    raw = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(raw)}")
+
+    df, btc_df, eth_df = _split_combined(raw)
+    if btc_df is not None:
+        print(f"  BTC/ETH 피처 활성화 (21개 피처)")
+    else:
+        print(f"  XRP 단독 데이터 (13개 피처)")
 
     print("\n데이터셋 생성 중...")
     t0 = time.perf_counter()
-    dataset = generate_dataset_vectorized(df)
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=time_weight_decay)
     t1 = time.perf_counter()
     print(f"데이터셋 생성 완료: {t1 - t0:.1f}초, {len(dataset)}개 샘플")
 
@@ -44,12 +70,38 @@ def train_mlx(data_path: str) -> float:
     if len(dataset) < 200:
         raise ValueError(f"학습 샘플 부족: {len(dataset)}개 (최소 200 필요)")
 
+    actual_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    missing = [c for c in FEATURE_COLS if c not in dataset.columns]
+    if missing:
+        print(f"  경고: 데이터셋에 없는 피처 {missing} → 0으로 채움 (BTC/ETH 데이터 미제공)")
+        for col in missing:
+            dataset[col] = 0.0
     X = dataset[FEATURE_COLS]
     y = dataset["label"]
+    w = dataset["sample_weight"].values
 
     split = int(len(X) * 0.8)
     X_train, X_val = X.iloc[:split], X.iloc[split:]
     y_train, y_val = y.iloc[:split], y.iloc[split:]
+    w_train = w[:split]
+
+    # --- 클래스 불균형 처리: 언더샘플링 (가중치 인덱스 보존) ---
+    pos_idx = np.where(y_train == 1)[0]
+    neg_idx = np.where(y_train == 0)[0]
+
+    if len(neg_idx) > len(pos_idx):
+        np.random.seed(42)
+        neg_idx = np.random.choice(neg_idx, size=len(pos_idx), replace=False)
+
+    balanced_idx = np.concatenate([pos_idx, neg_idx])
+    np.random.shuffle(balanced_idx)
+
+    X_train = X_train.iloc[balanced_idx]
+    y_train = y_train.iloc[balanced_idx]
+    w_train = w_train[balanced_idx]
+
+    print(f"\n언더샘플링 적용 후 학습 데이터: {len(X_train)}개 (양성={y_train.sum()}, 음성={(y_train==0).sum()})")
+    # --------------------------------------
 
     print("\nMLX 신경망 학습 시작 (GPU)...")
     t2 = time.perf_counter()
@@ -60,14 +112,32 @@ def train_mlx(data_path: str) -> float:
         epochs=100,
         batch_size=256,
     )
-    model.fit(X_train, y_train)
+    model.fit(X_train, y_train, sample_weight=w_train)
     t3 = time.perf_counter()
     print(f"학습 완료: {t3 - t2:.1f}초")
 
     val_proba = model.predict_proba(X_val)
     auc = roc_auc_score(y_val, val_proba)
-    print(f"\n검증 AUC: {auc:.4f}")
-    print(classification_report(y_val, (val_proba >= 0.60).astype(int)))
+
+    # 최적 임계값 탐색: 최소 재현율(0.15) 조건부 정밀도 최대화
+    from sklearn.metrics import precision_recall_curve
+    precisions, recalls, thresholds = precision_recall_curve(y_val, val_proba)
+    precisions, recalls = precisions[:-1], recalls[:-1]
+
+    MIN_RECALL = 0.15
+    valid_idx = np.where(recalls >= MIN_RECALL)[0]
+    if len(valid_idx) > 0:
+        best_idx  = valid_idx[np.argmax(precisions[valid_idx])]
+        best_thr  = float(thresholds[best_idx])
+        best_prec = float(precisions[best_idx])
+        best_rec  = float(recalls[best_idx])
+    else:
+        best_thr, best_prec, best_rec = 0.50, 0.0, 0.0
+        print(f"  [경고] recall >= {MIN_RECALL} 조건 만족 임계값 없음 → 기본값 0.50 사용")
+
+    print(f"\n검증 AUC: {auc:.4f}  |  최적 임계값: {best_thr:.4f} "
+          f"(Precision={best_prec:.3f}, Recall={best_rec:.3f})")
+    print(classification_report(y_val, (val_proba >= best_thr).astype(int), zero_division=0))
 
     MLX_MODEL_PATH.parent.mkdir(exist_ok=True)
     model.save(MLX_MODEL_PATH)
@@ -81,8 +151,12 @@ def train_mlx(data_path: str) -> float:
         "date": datetime.now().isoformat(),
         "backend": "mlx",
         "auc": round(auc, 4),
+        "best_threshold": round(best_thr, 4),
+        "best_precision": round(best_prec, 3),
+        "best_recall":    round(best_rec, 3),
         "samples": len(dataset),
         "train_sec": round(t3 - t2, 1),
+        "time_weight_decay": time_weight_decay,
         "model_path": str(MLX_MODEL_PATH),
     })
     with open(LOG_PATH, "w") as f:
@@ -91,11 +165,107 @@ def train_mlx(data_path: str) -> float:
     return auc
 
 
+def walk_forward_auc(
+    data_path: str,
+    time_weight_decay: float = 2.0,
+    n_splits: int = 5,
+    train_ratio: float = 0.6,
+) -> None:
+    """Walk-Forward 검증: 슬라이딩 윈도우로 n_splits번 학습/검증 반복."""
+    print(f"\n=== Walk-Forward 검증 ({n_splits}폴드, decay={time_weight_decay}) ===")
+    raw = pd.read_parquet(data_path)
+    df, btc_df, eth_df = _split_combined(raw)
+
+    dataset = generate_dataset_vectorized(
+        df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=time_weight_decay
+    )
+    missing = [c for c in FEATURE_COLS if c not in dataset.columns]
+    for col in missing:
+        dataset[col] = 0.0
+
+    X_all = dataset[FEATURE_COLS].values.astype(np.float32)
+    y_all = dataset["label"].values.astype(np.float32)
+    w_all = dataset["sample_weight"].values.astype(np.float32)
+    n = len(dataset)
+
+    step = max(1, int(n * (1 - train_ratio) / n_splits))
+    train_end_start = int(n * train_ratio)
+
+    aucs = []
+    for i in range(n_splits):
+        tr_end = train_end_start + i * step
+        val_end = tr_end + step
+        if val_end > n:
+            break
+
+        X_tr_raw = X_all[:tr_end]
+        y_tr = y_all[:tr_end]
+        w_tr = w_all[:tr_end]
+        X_val_raw = X_all[tr_end:val_end]
+        y_val = y_all[tr_end:val_end]
+
+        pos_idx = np.where(y_tr == 1)[0]
+        neg_idx = np.where(y_tr == 0)[0]
+        if len(neg_idx) > len(pos_idx):
+            np.random.seed(42)
+            neg_idx = np.random.choice(neg_idx, size=len(pos_idx), replace=False)
+        bal_idx = np.sort(np.concatenate([pos_idx, neg_idx]))
+
+        X_tr_bal = X_tr_raw[bal_idx]
+        y_tr_bal = y_tr[bal_idx]
+        w_tr_bal = w_tr[bal_idx]
+
+        # 폴드별 정규화 (학습 데이터 기준으로 계산, 검증에도 동일 적용)
+        mean = X_tr_bal.mean(axis=0)
+        std = X_tr_bal.std(axis=0) + 1e-8
+        X_tr_norm = (X_tr_bal - mean) / std
+        X_val_norm = (X_val_raw - mean) / std
+
+        # DataFrame으로 래핑해서 MLXFilter.fit()에 전달
+        # fit() 내부 정규화가 덮어쓰지 않도록 이미 정규화된 데이터를 넘기고
+        # _mean=0, _std=1로 고정해 이중 정규화를 방지
+        X_tr_df = pd.DataFrame(X_tr_norm, columns=FEATURE_COLS)
+        X_val_df = pd.DataFrame(X_val_norm, columns=FEATURE_COLS)
+
+        model = MLXFilter(
+            input_dim=len(FEATURE_COLS),
+            hidden_dim=128,
+            lr=1e-3,
+            epochs=100,
+            batch_size=256,
+        )
+        model.fit(X_tr_df, pd.Series(y_tr_bal), sample_weight=w_tr_bal)
+        # fit()이 내부에서 다시 정규화하므로 저장된 mean/std를 항등 변환으로 교체
+        model._mean = np.zeros(len(FEATURE_COLS), dtype=np.float32)
+        model._std = np.ones(len(FEATURE_COLS), dtype=np.float32)
+
+        proba = model.predict_proba(X_val_df)
+        auc = roc_auc_score(y_val, proba) if len(np.unique(y_val)) > 1 else 0.5
+        aucs.append(auc)
+        print(
+            f"  폴드 {i+1}/{n_splits}: 학습={tr_end}개, "
+            f"검증={tr_end}~{val_end} ({step}개), AUC={auc:.4f}"
+        )
+
+    print(f"\n  Walk-Forward 평균 AUC: {np.mean(aucs):.4f} ± {np.std(aucs):.4f}")
+    print(f"  폴드별: {[round(a, 4) for a in aucs]}")
+
+
 def main():
     parser = argparse.ArgumentParser()
-    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    parser.add_argument("--data", default="data/combined_15m.parquet")
+    parser.add_argument(
+        "--decay", type=float, default=2.0,
+        help="시간 가중치 감쇠 강도 (0=균등, 2.0=최신이 ~7.4배 높음)",
+    )
+    parser.add_argument("--wf", action="store_true", help="Walk-Forward 검증 실행")
+    parser.add_argument("--wf-splits", type=int, default=5, help="Walk-Forward 폴드 수")
     args = parser.parse_args()
-    train_mlx(args.data)
+
+    if args.wf:
+        walk_forward_auc(args.data, time_weight_decay=args.decay, n_splits=args.wf_splits)
+    else:
+        train_mlx(args.data, time_weight_decay=args.decay)
 
 
 if __name__ == "__main__":

scripts/train_model.py

@@ -17,12 +17,12 @@ import joblib
 import lightgbm as lgb
 import numpy as np
 import pandas as pd
-from sklearn.metrics import roc_auc_score, classification_report
+from sklearn.metrics import roc_auc_score, classification_report, precision_recall_curve
 
 from src.indicators import Indicators
 from src.ml_features import build_features, FEATURE_COLS
 from src.label_builder import build_labels
-from src.dataset_builder import generate_dataset_vectorized
+from src.dataset_builder import generate_dataset_vectorized, stratified_undersample
 
 def _cgroup_cpu_count() -> int:
     """cgroup v1/v2 쿼터를 읽어 실제 할당된 CPU 수를 반환한다.
@@ -53,7 +53,7 @@ def _cgroup_cpu_count() -> int:
     return cpu_count()
 
 
-LOOKAHEAD = 60
+LOOKAHEAD = 24  # 15분봉 × 24 = 6시간 (dataset_builder.py와 동기화)
 ATR_SL_MULT = 1.5
 ATR_TP_MULT = 3.0
 MODEL_PATH = Path("models/lgbm_filter.pkl")
@@ -146,7 +146,52 @@ def generate_dataset(df: pd.DataFrame, n_jobs: int | None = None) -> pd.DataFram
     return pd.DataFrame(rows)
 
 
-def train(data_path: str):
+ACTIVE_PARAMS_PATH = Path("models/active_lgbm_params.json")
+
+
+def _load_lgbm_params(tuned_params_path: str | None) -> tuple[dict, float]:
+    """기본 LightGBM 파라미터를 반환하고, 튜닝 JSON이 주어지면 덮어쓴다.
+
+    우선순위:
+      1. --tuned-params 명시적 인자
+      2. models/active_lgbm_params.json (Optuna가 자동 갱신)
+      3. 코드 내 하드코딩 기본값 (fallback)
+    """
+    lgbm_params: dict = {
+        "n_estimators":      434,
+        "learning_rate":     0.123659,
+        "max_depth":         6,
+        "num_leaves":        14,
+        "min_child_samples": 10,
+        "subsample":         0.929062,
+        "colsample_bytree":  0.946330,
+        "reg_alpha":         0.573971,
+        "reg_lambda":        0.000157,
+    }
+    weight_scale = 1.783105
+
+    # 명시적 인자가 없으면 active 파일 자동 탐색
+    resolved_path = tuned_params_path or (
+        str(ACTIVE_PARAMS_PATH) if ACTIVE_PARAMS_PATH.exists() else None
+    )
+
+    if resolved_path:
+        with open(resolved_path, "r", encoding="utf-8") as f:
+            tune_data = json.load(f)
+        best_params = dict(tune_data["best_trial"]["params"])
+        weight_scale = float(best_params.pop("weight_scale", 1.0))
+        lgbm_params.update(best_params)
+        source = "명시적 인자" if tuned_params_path else "active 파일 자동 로드"
+        print(f"\n[Optuna] 튜닝 파라미터 로드 ({source}): {resolved_path}")
+        print(f"[Optuna] 적용 파라미터: {lgbm_params}")
+        print(f"[Optuna] weight_scale: {weight_scale}\n")
+    else:
+        print("[Optuna] active 파일 없음 → 코드 내 기본 파라미터 사용\n")
+
+    return lgbm_params, weight_scale
+
+
+def train(data_path: str, time_weight_decay: float = 2.0, tuned_params_path: str | None = None):
     print(f"데이터 로드: {data_path}")
     df_raw = pd.read_parquet(data_path)
     print(f"캔들 수: {len(df_raw)}, 컬럼: {list(df_raw.columns)}")
@@ -169,7 +214,11 @@ def train(data_path: str):
     df = df_raw[base_cols].copy()
 
     print("데이터셋 생성 중...")
-    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df)
+    dataset = generate_dataset_vectorized(
+        df, btc_df=btc_df, eth_df=eth_df,
+        time_weight_decay=time_weight_decay,
+        negative_ratio=5,
+    )
 
     if dataset.empty or "label" not in dataset.columns:
         raise ValueError(f"데이터셋 생성 실패: 샘플 0개. 위 오류 메시지를 확인하세요.")
@@ -183,32 +232,67 @@ def train(data_path: str):
     print(f"사용 피처: {len(actual_feature_cols)}개 {actual_feature_cols}")
     X = dataset[actual_feature_cols]
     y = dataset["label"]
+    w = dataset["sample_weight"].values
+    source = dataset["source"].values if "source" in dataset.columns else np.full(len(X), "signal")
 
     split = int(len(X) * 0.8)
     X_train, X_val = X.iloc[:split], X.iloc[split:]
     y_train, y_val = y.iloc[:split], y.iloc[split:]
 
-    model = lgb.LGBMClassifier(
-        n_estimators=300,
-        learning_rate=0.05,
-        num_leaves=31,
-        min_child_samples=20,
-        subsample=0.8,
-        colsample_bytree=0.8,
-        class_weight="balanced",
-        random_state=42,
-        verbose=-1,
-    )
+    # 튜닝 파라미터 로드 (없으면 기본값 사용)
+    lgbm_params, weight_scale = _load_lgbm_params(tuned_params_path)
+    w_train = (w[:split] * weight_scale).astype(np.float32)
+
+    # --- 계층적 샘플링: signal 전수 유지, HOLD negative만 양성 수 만큼 ---
+    source_train = source[:split]
+    balanced_idx = stratified_undersample(y_train.values, source_train, seed=42)
+
+    X_train = X_train.iloc[balanced_idx]
+    y_train = y_train.iloc[balanced_idx]
+    w_train = w_train[balanced_idx]
+
+    sig_count = (source_train[balanced_idx] == "signal").sum()
+    hold_count = (source_train[balanced_idx] == "hold_negative").sum()
+    print(f"\n계층적 샘플링 후 학습 데이터: {len(X_train)}개 "
+          f"(Signal={sig_count}, HOLD={hold_count}, "
+          f"양성={int(y_train.sum())}, 음성={int((y_train==0).sum())})")
+    print(f"검증 데이터: {len(X_val)}개 (양성={int(y_val.sum())}, 음성={int((y_val==0).sum())})")
+    # ---------------------------------------------------------------
+
+    model = lgb.LGBMClassifier(**lgbm_params, random_state=42, verbose=-1)
     model.fit(
         X_train, y_train,
+        sample_weight=w_train,
         eval_set=[(X_val, y_val)],
-        callbacks=[lgb.early_stopping(30, verbose=False), lgb.log_evaluation(50)],
+        eval_metric="auc",
+        callbacks=[
+            lgb.early_stopping(80, first_metric_only=True, verbose=False),
+            lgb.log_evaluation(50),
+        ],
     )
 
     val_proba = model.predict_proba(X_val)[:, 1]
     auc = roc_auc_score(y_val, val_proba)
-    print(f"\n검증 AUC: {auc:.4f}")
-    print(classification_report(y_val, (val_proba >= 0.60).astype(int)))
+
+    # 최적 임계값 탐색: 최소 재현율(0.15) 조건부 정밀도 최대화
+    precisions, recalls, thresholds = precision_recall_curve(y_val, val_proba)
+    # precision_recall_curve의 마지막 원소는 (1.0, 0.0)이므로 제외
+    precisions, recalls = precisions[:-1], recalls[:-1]
+
+    MIN_RECALL = 0.15
+    valid_idx = np.where(recalls >= MIN_RECALL)[0]
+    if len(valid_idx) > 0:
+        best_idx  = valid_idx[np.argmax(precisions[valid_idx])]
+        best_thr  = float(thresholds[best_idx])
+        best_prec = float(precisions[best_idx])
+        best_rec  = float(recalls[best_idx])
+    else:
+        best_thr, best_prec, best_rec = 0.50, 0.0, 0.0
+        print(f"  [경고] recall >= {MIN_RECALL} 조건 만족 임계값 없음 → 기본값 0.50 사용")
+
+    print(f"\n검증 AUC: {auc:.4f}  |  최적 임계값: {best_thr:.4f} "
+          f"(Precision={best_prec:.3f}, Recall={best_rec:.3f})")
+    print(classification_report(y_val, (val_proba >= best_thr).astype(int), zero_division=0))
 
     if MODEL_PATH.exists():
         import shutil
@@ -223,24 +307,145 @@ def train(data_path: str):
     if LOG_PATH.exists():
         with open(LOG_PATH) as f:
             log = json.load(f)
-    log.append({
+    log_entry: dict = {
         "date": datetime.now().isoformat(),
+        "backend": "lgbm",
         "auc": round(auc, 4),
+        "best_threshold": round(best_thr, 4),
+        "best_precision": round(best_prec, 3),
+        "best_recall":    round(best_rec, 3),
         "samples": len(dataset),
         "features": len(actual_feature_cols),
+        "time_weight_decay": time_weight_decay,
         "model_path": str(MODEL_PATH),
-    })
+        "tuned_params_path": tuned_params_path,
+        "lgbm_params": lgbm_params,
+        "weight_scale": weight_scale,
+    }
+    log.append(log_entry)
     with open(LOG_PATH, "w") as f:
         json.dump(log, f, indent=2)
 
     return auc
 
 
+def walk_forward_auc(
+    data_path: str,
+    time_weight_decay: float = 2.0,
+    n_splits: int = 5,
+    train_ratio: float = 0.6,
+    tuned_params_path: str | None = None,
+) -> None:
+    """Walk-Forward 검증: 슬라이딩 윈도우로 n_splits번 학습/검증 반복.
+
+    시계열 순서를 지키면서 매 폴드마다 학습 구간을 늘려가며 검증한다.
+    실제 미래 예측력의 평균 AUC를 측정하는 데 사용한다.
+    """
+    import warnings
+
+    print(f"\n=== Walk-Forward 검증 ({n_splits}폴드, decay={time_weight_decay}) ===")
+    df_raw = pd.read_parquet(data_path)
+    base_cols = ["open", "high", "low", "close", "volume"]
+    btc_df = eth_df = None
+    if "close_btc" in df_raw.columns:
+        btc_df = df_raw[[c + "_btc" for c in base_cols]].copy()
+        btc_df.columns = base_cols
+    if "close_eth" in df_raw.columns:
+        eth_df = df_raw[[c + "_eth" for c in base_cols]].copy()
+        eth_df.columns = base_cols
+    df = df_raw[base_cols].copy()
+
+    dataset = generate_dataset_vectorized(
+        df, btc_df=btc_df, eth_df=eth_df,
+        time_weight_decay=time_weight_decay,
+        negative_ratio=5,
+    )
+    actual_feature_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    X = dataset[actual_feature_cols].values
+    y = dataset["label"].values
+    w = dataset["sample_weight"].values
+    n = len(dataset)
+    source = dataset["source"].values if "source" in dataset.columns else np.full(n, "signal")
+
+    lgbm_params, weight_scale = _load_lgbm_params(tuned_params_path)
+    w = (w * weight_scale).astype(np.float32)
+
+    step = max(1, int(n * (1 - train_ratio) / n_splits))
+    train_end_start = int(n * train_ratio)
+
+    aucs = []
+    fold_metrics = []
+    for i in range(n_splits):
+        tr_end = train_end_start + i * step
+        val_end = tr_end + step
+        if val_end > n:
+            break
+
+        X_tr, y_tr, w_tr = X[:tr_end], y[:tr_end], w[:tr_end]
+        X_val, y_val = X[tr_end:val_end], y[tr_end:val_end]
+
+        source_tr = source[:tr_end]
+        idx = stratified_undersample(y_tr, source_tr, seed=42)
+
+        model = lgb.LGBMClassifier(**lgbm_params, random_state=42, verbose=-1)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model.fit(X_tr[idx], y_tr[idx], sample_weight=w_tr[idx])
+
+        proba = model.predict_proba(X_val)[:, 1]
+        auc = roc_auc_score(y_val, proba) if len(np.unique(y_val)) > 1 else 0.5
+        aucs.append(auc)
+
+        # 폴드별 최적 임계값 (recall >= 0.15 조건부 precision 최대화)
+        MIN_RECALL = 0.15
+        precs, recs, thrs = precision_recall_curve(y_val, proba)
+        precs, recs = precs[:-1], recs[:-1]
+        valid_idx = np.where(recs >= MIN_RECALL)[0]
+        if len(valid_idx) > 0:
+            best_i = valid_idx[np.argmax(precs[valid_idx])]
+            f_thr, f_prec, f_rec = float(thrs[best_i]), float(precs[best_i]), float(recs[best_i])
+        else:
+            f_thr, f_prec, f_rec = 0.50, 0.0, 0.0
+
+        fold_metrics.append({"auc": auc, "precision": f_prec, "recall": f_rec, "threshold": f_thr})
+        print(
+            f"  폴드 {i+1}/{n_splits}: 학습={tr_end}개, "
+            f"검증={tr_end}~{val_end} ({step}개), AUC={auc:.4f}  |  "
+            f"Thr={f_thr:.4f}  Prec={f_prec:.3f}  Rec={f_rec:.3f}"
+        )
+
+    mean_prec = np.mean([m["precision"] for m in fold_metrics])
+    mean_rec = np.mean([m["recall"] for m in fold_metrics])
+    mean_thr = np.mean([m["threshold"] for m in fold_metrics])
+    print(f"\n  Walk-Forward 평균 AUC: {np.mean(aucs):.4f} ± {np.std(aucs):.4f}")
+    print(f"  평균 Precision: {mean_prec:.3f}  |  평균 Recall: {mean_rec:.3f}  |  평균 Threshold: {mean_thr:.4f}")
+    print(f"  폴드별: {[round(a, 4) for a in aucs]}")
+
+
 def main():
     parser = argparse.ArgumentParser()
-    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    parser.add_argument("--data", default="data/combined_15m.parquet")
+    parser.add_argument(
+        "--decay", type=float, default=2.0,
+        help="시간 가중치 감쇠 강도 (0=균등, 2.0=최신이 ~7.4배 높음)",
+    )
+    parser.add_argument("--wf", action="store_true", help="Walk-Forward 검증 실행")
+    parser.add_argument("--wf-splits", type=int, default=5, help="Walk-Forward 폴드 수")
+    parser.add_argument(
+        "--tuned-params", type=str, default=None,
+        help="Optuna 튜닝 결과 JSON 경로 (지정 시 기본 파라미터를 덮어씀)",
+    )
     args = parser.parse_args()
-    train(args.data)
+
+    if args.wf:
+        walk_forward_auc(
+            args.data,
+            time_weight_decay=args.decay,
+            n_splits=args.wf_splits,
+            tuned_params_path=args.tuned_params,
+        )
+    else:
+        train(args.data, time_weight_decay=args.decay, tuned_params_path=args.tuned_params)
 
 
 if __name__ == "__main__":

scripts/tune_hyperparams.py

@@ -0,0 +1,625 @@
+#!/usr/bin/env python3
+"""
+Optuna를 사용한 LightGBM 하이퍼파라미터 자동 탐색.
+
+사용법:
+    python scripts/tune_hyperparams.py                          # 기본 (50 trials, 5폴드)
+    python scripts/tune_hyperparams.py --trials 10 --folds 3   # 빠른 테스트
+    python scripts/tune_hyperparams.py --data data/combined_15m.parquet --trials 100
+    python scripts/tune_hyperparams.py --no-baseline            # 베이스라인 측정 건너뜀
+    python scripts/tune_hyperparams.py --min-recall 0.4         # 최소 재현율 제약 조정
+
+결과:
+    - 콘솔: Best Params + Walk-Forward 리포트
+    - JSON: models/tune_results_YYYYMMDD_HHMMSS.json
+"""
+import sys
+import warnings
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import argparse
+import json
+import time
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+import lightgbm as lgb
+import optuna
+from optuna.samplers import TPESampler
+from optuna.pruners import MedianPruner
+from sklearn.metrics import roc_auc_score, precision_recall_curve
+
+from src.ml_features import FEATURE_COLS
+from src.dataset_builder import generate_dataset_vectorized, stratified_undersample
+
+
+# ──────────────────────────────────────────────
+# 데이터 로드 및 데이터셋 생성 (1회 캐싱)
+# ──────────────────────────────────────────────
+
+def load_dataset(data_path: str) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """
+    parquet 로드 → 벡터화 데이터셋 생성 → (X, y, w) numpy 배열 반환.
+    study 시작 전 1회만 호출하여 모든 trial이 공유한다.
+    """
+    print(f"데이터 로드: {data_path}")
+    df_raw = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df_raw):,}, 컬럼: {list(df_raw.columns)}")
+
+    base_cols = ["open", "high", "low", "close", "volume"]
+    btc_df = eth_df = None
+
+    if "close_btc" in df_raw.columns:
+        btc_df = df_raw[[c + "_btc" for c in base_cols]].copy()
+        btc_df.columns = base_cols
+        print("BTC 피처 활성화")
+
+    if "close_eth" in df_raw.columns:
+        eth_df = df_raw[[c + "_eth" for c in base_cols]].copy()
+        eth_df.columns = base_cols
+        print("ETH 피처 활성화")
+
+    df = df_raw[base_cols].copy()
+
+    print("\n데이터셋 생성 중 (1회만 실행)...")
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=0.0, negative_ratio=5)
+
+    if dataset.empty or "label" not in dataset.columns:
+        raise ValueError("데이터셋 생성 실패: 샘플 0개")
+
+    actual_feature_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    X = dataset[actual_feature_cols].values.astype(np.float32)
+    y = dataset["label"].values.astype(np.int8)
+    w = dataset["sample_weight"].values.astype(np.float32)
+    source = dataset["source"].values if "source" in dataset.columns else np.full(len(dataset), "signal")
+
+    pos = int(y.sum())
+    neg = int((y == 0).sum())
+    print(f"데이터셋 완성: {len(dataset):,}개 샘플 (양성={pos}, 음성={neg})")
+    print(f"사용 피처: {len(actual_feature_cols)}개\n")
+
+    return X, y, w, source
+
+
+# ──────────────────────────────────────────────
+# Precision 헬퍼
+# ──────────────────────────────────────────────
+
+def _find_best_precision_at_recall(
+    y_true: np.ndarray,
+    proba: np.ndarray,
+    min_recall: float = 0.35,
+) -> tuple[float, float, float]:
+    """
+    precision_recall_curve에서 recall >= min_recall 조건을 만족하는
+    최대 precision과 해당 threshold를 반환한다.
+
+    Returns:
+        (best_precision, best_recall, best_threshold)
+        조건 불만족 시 (0.0, 0.0, 0.50)
+    """
+    precisions, recalls, thresholds = precision_recall_curve(y_true, proba)
+    precisions, recalls = precisions[:-1], recalls[:-1]
+
+    valid_idx = np.where(recalls >= min_recall)[0]
+    if len(valid_idx) > 0:
+        best_idx = valid_idx[np.argmax(precisions[valid_idx])]
+        return (
+            float(precisions[best_idx]),
+            float(recalls[best_idx]),
+            float(thresholds[best_idx]),
+        )
+    return (0.0, 0.0, 0.50)
+
+
+# ──────────────────────────────────────────────
+# Walk-Forward 교차검증
+# ──────────────────────────────────────────────
+
+def _walk_forward_cv(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    source: np.ndarray,
+    params: dict,
+    n_splits: int,
+    train_ratio: float,
+    min_recall: float = 0.35,
+    trial: "optuna.Trial | None" = None,
+) -> tuple[float, dict]:
+    """
+    Walk-Forward 교차검증으로 precision 기반 복합 점수를 반환한다.
+    Score = mean_precision + mean_auc * 0.001 (AUC는 tiebreaker)
+
+    trial이 제공되면 각 폴드 후 Optuna에 중간 값을 보고하여 Pruning을 활성화한다.
+
+    Returns:
+        (mean_score, details) where details contains per-fold metrics.
+    """
+    n = len(X)
+    step = max(1, int(n * (1 - train_ratio) / n_splits))
+    train_end_start = int(n * train_ratio)
+
+    fold_aucs: list[float] = []
+    fold_precisions: list[float] = []
+    fold_recalls: list[float] = []
+    fold_thresholds: list[float] = []
+    fold_n_pos: list[int] = []
+    scores_so_far: list[float] = []
+
+    for fold_idx in range(n_splits):
+        tr_end = train_end_start + fold_idx * step
+        val_end = tr_end + step
+        if val_end > n:
+            break
+
+        X_tr, y_tr, w_tr = X[:tr_end], y[:tr_end], w[:tr_end]
+        X_val, y_val = X[tr_end:val_end], y[tr_end:val_end]
+
+        # 계층적 샘플링: signal 전수 유지, HOLD negative만 양성 수 만큼
+        source_tr = source[:tr_end]
+        bal_idx = stratified_undersample(y_tr, source_tr, seed=42)
+
+        n_pos = int(y_val.sum())
+
+        if len(bal_idx) < 20 or len(np.unique(y_val)) < 2:
+            fold_aucs.append(0.5)
+            fold_precisions.append(0.0)
+            fold_recalls.append(0.0)
+            fold_thresholds.append(0.50)
+            fold_n_pos.append(n_pos)
+            continue
+
+        model = lgb.LGBMClassifier(**params, random_state=42, verbose=-1)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model.fit(X_tr[bal_idx], y_tr[bal_idx], sample_weight=w_tr[bal_idx])
+
+        proba = model.predict_proba(X_val)[:, 1]
+        auc = roc_auc_score(y_val, proba) if len(np.unique(y_val)) > 1 else 0.5
+        fold_aucs.append(float(auc))
+
+        # Precision at recall-constrained threshold
+        if n_pos >= 3:
+            prec, rec, thr = _find_best_precision_at_recall(y_val, proba, min_recall)
+        else:
+            prec, rec, thr = 0.0, 0.0, 0.50
+
+        fold_precisions.append(prec)
+        fold_recalls.append(rec)
+        fold_thresholds.append(thr)
+        fold_n_pos.append(n_pos)
+
+        # Pruning: 양성 충분한 fold의 score만 보고
+        score = prec + auc * 0.001
+        scores_so_far.append(score)
+        if trial is not None and n_pos >= 3:
+            valid_scores = [s for s, np_ in zip(scores_so_far, fold_n_pos) if np_ >= 3]
+            if valid_scores:
+                trial.report(float(np.mean(valid_scores)), step=fold_idx)
+                if trial.should_prune():
+                    raise optuna.TrialPruned()
+
+    # 양성 충분한 fold만으로 precision 평균 계산
+    valid_precs = [p for p, np_ in zip(fold_precisions, fold_n_pos) if np_ >= 3]
+    mean_auc = float(np.mean(fold_aucs)) if fold_aucs else 0.5
+    mean_prec = float(np.mean(valid_precs)) if valid_precs else 0.0
+    valid_recs = [r for r, np_ in zip(fold_recalls, fold_n_pos) if np_ >= 3]
+    mean_rec = float(np.mean(valid_recs)) if valid_recs else 0.0
+    mean_score = mean_prec + mean_auc * 0.001
+
+    details = {
+        "fold_aucs":       fold_aucs,
+        "fold_precisions": fold_precisions,
+        "fold_recalls":    fold_recalls,
+        "fold_thresholds": fold_thresholds,
+        "fold_n_pos":      fold_n_pos,
+        "mean_auc":        mean_auc,
+        "mean_precision":  mean_prec,
+        "mean_recall":     mean_rec,
+    }
+
+    return mean_score, details
+
+
+# ──────────────────────────────────────────────
+# Optuna 목적 함수
+# ──────────────────────────────────────────────
+
+def make_objective(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    source: np.ndarray,
+    n_splits: int,
+    train_ratio: float,
+    min_recall: float = 0.35,
+):
+    """클로저로 데이터셋을 캡처한 목적 함수를 반환한다."""
+
+    def objective(trial: optuna.Trial) -> float:
+        # ── 하이퍼파라미터 샘플링 ──
+        n_estimators     = trial.suggest_int("n_estimators", 100, 600)
+        learning_rate    = trial.suggest_float("learning_rate", 0.01, 0.2, log=True)
+        max_depth        = trial.suggest_int("max_depth", 2, 7)
+
+        # 핵심 제약: num_leaves <= 2^max_depth - 1 (leaf-wise 과적합 방지)
+        # 360개 수준의 소규모 데이터셋에서 num_leaves가 크면 암기 발생
+        max_leaves_upper = min(31, 2 ** max_depth - 1)
+        num_leaves       = trial.suggest_int("num_leaves", 7, max(7, max_leaves_upper))
+
+        min_child_samples = trial.suggest_int("min_child_samples", 10, 50)
+        subsample         = trial.suggest_float("subsample", 0.5, 1.0)
+        colsample_bytree  = trial.suggest_float("colsample_bytree", 0.5, 1.0)
+        reg_alpha         = trial.suggest_float("reg_alpha", 1e-4, 1.0, log=True)
+        reg_lambda        = trial.suggest_float("reg_lambda", 1e-4, 1.0, log=True)
+
+        # weight_scale: 데이터셋을 1회 캐싱하는 구조이므로
+        # time_weight_decay 효과를 sample_weight 스케일로 근사한다.
+        weight_scale = trial.suggest_float("weight_scale", 0.5, 2.0)
+        w_scaled = (w * weight_scale).astype(np.float32)
+
+        params = {
+            "n_estimators":     n_estimators,
+            "learning_rate":    learning_rate,
+            "max_depth":        max_depth,
+            "num_leaves":       num_leaves,
+            "min_child_samples": min_child_samples,
+            "subsample":        subsample,
+            "colsample_bytree": colsample_bytree,
+            "reg_alpha":        reg_alpha,
+            "reg_lambda":       reg_lambda,
+        }
+
+        mean_score, details = _walk_forward_cv(
+            X, y, w_scaled, source, params,
+            n_splits=n_splits,
+            train_ratio=train_ratio,
+            min_recall=min_recall,
+            trial=trial,
+        )
+
+        # 폴드별 상세 메트릭을 user_attrs에 저장 (결과 리포트용)
+        trial.set_user_attr("fold_aucs", details["fold_aucs"])
+        trial.set_user_attr("fold_precisions", details["fold_precisions"])
+        trial.set_user_attr("fold_recalls", details["fold_recalls"])
+        trial.set_user_attr("fold_thresholds", details["fold_thresholds"])
+        trial.set_user_attr("fold_n_pos", details["fold_n_pos"])
+        trial.set_user_attr("mean_auc", details["mean_auc"])
+        trial.set_user_attr("mean_precision", details["mean_precision"])
+        trial.set_user_attr("mean_recall", details["mean_recall"])
+
+        return mean_score
+
+    return objective
+
+
+# ──────────────────────────────────────────────
+# 베이스라인 측정 (현재 고정 파라미터)
+# ──────────────────────────────────────────────
+
+def measure_baseline(
+    X: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    source: np.ndarray,
+    n_splits: int,
+    train_ratio: float,
+    min_recall: float = 0.35,
+) -> tuple[float, dict]:
+    """현재 실전 파라미터(active 파일 또는 하드코딩 기본값)로 베이스라인을 측정한다."""
+    active_path = Path("models/active_lgbm_params.json")
+
+    if active_path.exists():
+        with open(active_path, "r", encoding="utf-8") as f:
+            tune_data = json.load(f)
+        best_params = dict(tune_data["best_trial"]["params"])
+        best_params.pop("weight_scale", None)
+        baseline_params = best_params
+        print(f"베이스라인 측정 중 (active 파일: {active_path})...")
+    else:
+        baseline_params = {
+            "n_estimators":      434,
+            "learning_rate":     0.123659,
+            "max_depth":         6,
+            "num_leaves":        14,
+            "min_child_samples": 10,
+            "subsample":         0.929062,
+            "colsample_bytree":  0.946330,
+            "reg_alpha":         0.573971,
+            "reg_lambda":        0.000157,
+        }
+        print("베이스라인 측정 중 (active 파일 없음 → 코드 내 기본 파라미터)...")
+
+    return _walk_forward_cv(
+        X, y, w, source, baseline_params,
+        n_splits=n_splits, train_ratio=train_ratio,
+        min_recall=min_recall,
+    )
+
+
+# ──────────────────────────────────────────────
+# 결과 출력 및 저장
+# ──────────────────────────────────────────────
+
+def print_report(
+    study: optuna.Study,
+    baseline_score: float,
+    baseline_details: dict,
+    elapsed_sec: float,
+    output_path: Path,
+    min_recall: float,
+) -> None:
+    """콘솔에 최종 리포트를 출력한다."""
+    best = study.best_trial
+    best_score = best.value
+    best_prec = best.user_attrs.get("mean_precision", 0.0)
+    best_auc = best.user_attrs.get("mean_auc", 0.0)
+    best_rec = best.user_attrs.get("mean_recall", 0.0)
+
+    baseline_prec = baseline_details.get("mean_precision", 0.0)
+    baseline_auc = baseline_details.get("mean_auc", 0.0)
+
+    prec_improvement = best_prec - baseline_prec
+    prec_improvement_pct = (prec_improvement / baseline_prec * 100) if baseline_prec > 0 else 0.0
+
+    elapsed_min = int(elapsed_sec // 60)
+    elapsed_s   = int(elapsed_sec % 60)
+
+    sep  = "=" * 64
+    dash = "-" * 64
+
+    completed = [t for t in study.trials if t.state == optuna.trial.TrialState.COMPLETE]
+    pruned    = [t for t in study.trials if t.state == optuna.trial.TrialState.PRUNED]
+
+    print(f"\n{sep}")
+    print(f"  Optuna 튜닝 완료 | {len(study.trials)} trials "
+          f"(완료={len(completed)}, 조기종료={len(pruned)}) | "
+          f"소요: {elapsed_min}분 {elapsed_s}초")
+    print(sep)
+    print(f"  최적화 지표: Precision (recall >= {min_recall} 제약)")
+    print(f"  Best Prec : {best_prec:.4f}  (Trial #{best.number})")
+    print(f"  Best AUC  : {best_auc:.4f}")
+    print(f"  Best Recall: {best_rec:.4f}")
+    if baseline_score > 0:
+        sign = "+" if prec_improvement >= 0 else ""
+        print(dash)
+        print(f"  Baseline  : Prec={baseline_prec:.4f}, AUC={baseline_auc:.4f}")
+        print(f"  개선폭    : Precision {sign}{prec_improvement:.4f} ({sign}{prec_improvement_pct:.1f}%)")
+    print(dash)
+    print("  Best Parameters:")
+    for k, v in best.params.items():
+        if isinstance(v, float):
+            print(f"    {k:<22}: {v:.6f}")
+        else:
+            print(f"    {k:<22}: {v}")
+    print(dash)
+
+    # 폴드별 상세
+    fold_aucs = best.user_attrs.get("fold_aucs", [])
+    fold_precs = best.user_attrs.get("fold_precisions", [])
+    fold_recs = best.user_attrs.get("fold_recalls", [])
+    fold_thrs = best.user_attrs.get("fold_thresholds", [])
+    fold_npos = best.user_attrs.get("fold_n_pos", [])
+
+    print("  Walk-Forward 폴드별 상세 (Best Trial):")
+    for i, (auc, prec, rec, thr, npos) in enumerate(
+        zip(fold_aucs, fold_precs, fold_recs, fold_thrs, fold_npos), 1
+    ):
+        print(f"    폴드 {i}: AUC={auc:.4f} Prec={prec:.3f} Rec={rec:.3f} Thr={thr:.3f} (양성={npos})")
+    if fold_precs:
+        valid_precs = [p for p, np_ in zip(fold_precs, fold_npos) if np_ >= 3]
+        if valid_precs:
+            arr_p = np.array(valid_precs)
+            print(f"    평균 Precision: {arr_p.mean():.4f} ± {arr_p.std():.4f}")
+    if fold_aucs:
+        arr_a = np.array(fold_aucs)
+        print(f"    평균 AUC: {arr_a.mean():.4f} ± {arr_a.std():.4f}")
+
+    # 베이스라인 폴드별
+    bl_folds = baseline_details.get("fold_aucs", [])
+    bl_precs = baseline_details.get("fold_precisions", [])
+    bl_recs = baseline_details.get("fold_recalls", [])
+    bl_thrs = baseline_details.get("fold_thresholds", [])
+    bl_npos = baseline_details.get("fold_n_pos", [])
+    if bl_folds:
+        print(dash)
+        print("  Baseline 폴드별 상세:")
+        for i, (auc, prec, rec, thr, npos) in enumerate(
+            zip(bl_folds, bl_precs, bl_recs, bl_thrs, bl_npos), 1
+        ):
+            print(f"    폴드 {i}: AUC={auc:.4f} Prec={prec:.3f} Rec={rec:.3f} Thr={thr:.3f} (양성={npos})")
+
+    print(dash)
+    print(f"  결과 저장: {output_path}")
+    print(f"  다음 단계: python scripts/train_model.py  (파라미터 수동 반영 후)")
+    print(sep)
+
+
+def save_results(
+    study: optuna.Study,
+    baseline_score: float,
+    baseline_details: dict,
+    elapsed_sec: float,
+    data_path: str,
+    min_recall: float,
+) -> Path:
+    """결과를 JSON 파일로 저장하고 경로를 반환한다."""
+    timestamp   = datetime.now().strftime("%Y%m%d_%H%M%S")
+    output_path = Path(f"models/tune_results_{timestamp}.json")
+    output_path.parent.mkdir(exist_ok=True)
+
+    best = study.best_trial
+
+    all_trials = []
+    for t in study.trials:
+        if t.state == optuna.trial.TrialState.COMPLETE:
+            all_trials.append({
+                "number":    t.number,
+                "score":     round(t.value, 6),
+                "auc":       round(t.user_attrs.get("mean_auc", 0.0), 6),
+                "precision": round(t.user_attrs.get("mean_precision", 0.0), 6),
+                "recall":    round(t.user_attrs.get("mean_recall", 0.0), 6),
+                "fold_aucs": [round(a, 6) for a in t.user_attrs.get("fold_aucs", [])],
+                "fold_precisions": [round(p, 6) for p in t.user_attrs.get("fold_precisions", [])],
+                "params":    {
+                    k: (round(v, 6) if isinstance(v, float) else v)
+                    for k, v in t.params.items()
+                },
+            })
+
+    result = {
+        "timestamp":          datetime.now().isoformat(),
+        "data_path":          data_path,
+        "min_recall_constraint": min_recall,
+        "n_trials_total":     len(study.trials),
+        "n_trials_complete":  len(all_trials),
+        "elapsed_sec":        round(elapsed_sec, 1),
+        "baseline": {
+            "score":           round(baseline_score, 6),
+            "auc":             round(baseline_details.get("mean_auc", 0.0), 6),
+            "precision":       round(baseline_details.get("mean_precision", 0.0), 6),
+            "recall":          round(baseline_details.get("mean_recall", 0.0), 6),
+            "fold_aucs":       [round(a, 6) for a in baseline_details.get("fold_aucs", [])],
+            "fold_precisions": [round(p, 6) for p in baseline_details.get("fold_precisions", [])],
+            "fold_recalls":    [round(r, 6) for r in baseline_details.get("fold_recalls", [])],
+            "fold_thresholds": [round(t, 6) for t in baseline_details.get("fold_thresholds", [])],
+        },
+        "best_trial": {
+            "number":          best.number,
+            "score":           round(best.value, 6),
+            "auc":             round(best.user_attrs.get("mean_auc", 0.0), 6),
+            "precision":       round(best.user_attrs.get("mean_precision", 0.0), 6),
+            "recall":          round(best.user_attrs.get("mean_recall", 0.0), 6),
+            "fold_aucs":       [round(a, 6) for a in best.user_attrs.get("fold_aucs", [])],
+            "fold_precisions": [round(p, 6) for p in best.user_attrs.get("fold_precisions", [])],
+            "fold_recalls":    [round(r, 6) for r in best.user_attrs.get("fold_recalls", [])],
+            "fold_thresholds": [round(t, 6) for t in best.user_attrs.get("fold_thresholds", [])],
+            "fold_n_pos":      best.user_attrs.get("fold_n_pos", []),
+            "params":    {
+                k: (round(v, 6) if isinstance(v, float) else v)
+                for k, v in best.params.items()
+            },
+        },
+        "all_trials": all_trials,
+    }
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2, ensure_ascii=False)
+
+    return output_path
+
+
+# ──────────────────────────────────────────────
+# 메인
+# ──────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="Optuna LightGBM 하이퍼파라미터 튜닝")
+    parser.add_argument("--data",        default="data/combined_15m.parquet", help="학습 데이터 경로")
+    parser.add_argument("--trials",      type=int,   default=50,  help="Optuna trial 수 (기본: 50)")
+    parser.add_argument("--folds",       type=int,   default=5,   help="Walk-Forward 폴드 수 (기본: 5)")
+    parser.add_argument("--train-ratio", type=float, default=0.6, help="학습 구간 비율 (기본: 0.6)")
+    parser.add_argument("--min-recall",  type=float, default=0.35, help="최소 재현율 제약 (기본: 0.35)")
+    parser.add_argument("--no-baseline", action="store_true",     help="베이스라인 측정 건너뜀")
+    args = parser.parse_args()
+
+    # 1. 데이터셋 로드 (1회)
+    X, y, w, source = load_dataset(args.data)
+
+    # 2. 베이스라인 측정
+    if args.no_baseline:
+        baseline_score, baseline_details = 0.0, {}
+        print("베이스라인 측정 건너뜀 (--no-baseline)\n")
+    else:
+        baseline_score, baseline_details = measure_baseline(
+            X, y, w, source, args.folds, args.train_ratio, args.min_recall,
+        )
+        bl_prec = baseline_details.get("mean_precision", 0.0)
+        bl_auc = baseline_details.get("mean_auc", 0.0)
+        bl_rec = baseline_details.get("mean_recall", 0.0)
+        print(
+            f"베이스라인: Prec={bl_prec:.4f}, AUC={bl_auc:.4f}, Recall={bl_rec:.4f} "
+            f"(recall >= {args.min_recall} 제약)\n"
+        )
+
+    # 3. Optuna study 실행
+    optuna.logging.set_verbosity(optuna.logging.WARNING)
+    sampler = TPESampler(seed=42)
+    pruner  = MedianPruner(n_startup_trials=5, n_warmup_steps=3)
+    study   = optuna.create_study(
+        direction="maximize",
+        sampler=sampler,
+        pruner=pruner,
+        study_name="lgbm_wf_precision",
+    )
+
+    objective = make_objective(
+        X, y, w, source,
+        n_splits=args.folds,
+        train_ratio=args.train_ratio,
+        min_recall=args.min_recall,
+    )
+
+    print(f"Optuna 탐색 시작: {args.trials} trials, {args.folds}폴드 Walk-Forward")
+    print(f"최적화 지표: Precision (recall >= {args.min_recall} 제약)")
+    print("(trial 완료마다 진행 상황 출력)\n")
+
+    start_time = time.time()
+
+    def _progress_callback(study: optuna.Study, trial: optuna.trial.FrozenTrial) -> None:
+        if trial.state == optuna.trial.TrialState.COMPLETE:
+            best_so_far = study.best_value
+            prec = trial.user_attrs.get("mean_precision", 0.0)
+            auc  = trial.user_attrs.get("mean_auc", 0.0)
+            print(
+                f"  Trial #{trial.number:3d} | Prec={prec:.4f} AUC={auc:.4f} "
+                f"| Best={best_so_far:.4f} "
+                f"| leaves={trial.params.get('num_leaves', '?')} "
+                f"depth={trial.params.get('max_depth', '?')}"
+            )
+        elif trial.state == optuna.trial.TrialState.PRUNED:
+            print(f"  Trial #{trial.number:3d} | PRUNED (조기 종료)")
+
+    study.optimize(
+        objective,
+        n_trials=args.trials,
+        callbacks=[_progress_callback],
+        show_progress_bar=False,
+    )
+
+    elapsed = time.time() - start_time
+
+    # 4. 결과 저장 및 출력
+    output_path = save_results(
+        study, baseline_score, baseline_details, elapsed, args.data, args.min_recall,
+    )
+    print_report(
+        study, baseline_score, baseline_details, elapsed, output_path, args.min_recall,
+    )
+
+    # 5. 성능 개선 시 active 파일 자동 갱신
+    import shutil
+    active_path = Path("models/active_lgbm_params.json")
+    if not args.no_baseline and study.best_value > baseline_score:
+        shutil.copy(output_path, active_path)
+        best_prec = study.best_trial.user_attrs.get("mean_precision", 0.0)
+        bl_prec = baseline_details.get("mean_precision", 0.0)
+        improvement = best_prec - bl_prec
+        print(f"[MLOps] Precision +{improvement:.4f} 개선 → {active_path} 자동 갱신 완료")
+        print(f"[MLOps] 다음 train_model.py 실행 시 새 파라미터가 자동 적용됩니다.\n")
+    elif args.no_baseline:
+        print("[MLOps] --no-baseline 모드: 성능 비교 없이 active 파일 유지\n")
+    else:
+        best_prec = study.best_trial.user_attrs.get("mean_precision", 0.0)
+        bl_prec = baseline_details.get("mean_precision", 0.0)
+        print(
+            f"[MLOps] 성능 개선 없음 (Prec={best_prec:.4f} ≤ Baseline={bl_prec:.4f}) "
+            f"→ active 파일 유지\n"
+        )
+
+
+if __name__ == "__main__":
+    main()

src/bot.py

@@ -1,4 +1,5 @@
 import asyncio
+import pandas as pd
 from loguru import logger
 from src.config import Config
 from src.exchange import BinanceFuturesClient
@@ -8,6 +9,7 @@ from src.notifier import DiscordNotifier
 from src.risk_manager import RiskManager
 from src.ml_filter import MLFilter
 from src.ml_features import build_features
+from src.user_data_stream import UserDataStream
 
 
 class TradingBot:
@@ -18,18 +20,22 @@ class TradingBot:
         self.risk = RiskManager(config)
         self.ml_filter = MLFilter()
         self.current_trade_side: str | None = None  # "LONG" | "SHORT"
+        self._entry_price: float | None = None
+        self._entry_quantity: float | None = None
+        self._is_reentering: bool = False  # _close_and_reenter 중 콜백 상태 초기화 방지
+        self._prev_oi: float | None = None  # OI 변화율 계산용 이전 값
         self.stream = MultiSymbolStream(
             symbols=[config.symbol, "BTCUSDT", "ETHUSDT"],
-            interval="1m",
+            interval="15m",
             on_candle=self._on_candle_closed,
         )
 
-    def _on_candle_closed(self, candle: dict):
+    async def _on_candle_closed(self, candle: dict):
         xrp_df = self.stream.get_dataframe(self.config.symbol)
         btc_df = self.stream.get_dataframe("BTCUSDT")
         eth_df = self.stream.get_dataframe("ETHUSDT")
         if xrp_df is not None:
-            asyncio.create_task(self.process_candle(xrp_df, btc_df=btc_df, eth_df=eth_df))
+            await self.process_candle(xrp_df, btc_df=btc_df, eth_df=eth_df)
 
     async def _recover_position(self) -> None:
         """재시작 시 바이낸스에서 현재 포지션을 조회하여 상태 복구."""
@@ -37,6 +43,8 @@ class TradingBot:
         if position is not None:
             amt = float(position["positionAmt"])
             self.current_trade_side = "LONG" if amt > 0 else "SHORT"
+            self._entry_price = float(position["entryPrice"])
+            self._entry_quantity = abs(amt)
             entry = float(position["entryPrice"])
             logger.info(
                 f"기존 포지션 복구: {self.current_trade_side} | "
@@ -49,45 +57,85 @@ class TradingBot:
         else:
             logger.info("기존 포지션 없음 - 신규 진입 대기")
 
+    async def _fetch_market_microstructure(self) -> tuple[float, float]:
+        """OI 변화율과 펀딩비를 실시간으로 조회한다. 실패 시 0.0으로 폴백."""
+        oi_val, fr_val = await asyncio.gather(
+            self.exchange.get_open_interest(),
+            self.exchange.get_funding_rate(),
+            return_exceptions=True,
+        )
+        # None(API 실패) 또는 Exception이면 _calc_oi_change를 호출하지 않고 0.0 반환
+        if isinstance(oi_val, (int, float)) and oi_val > 0:
+            oi_change = self._calc_oi_change(float(oi_val))
+        else:
+            oi_change = 0.0
+        fr_float = float(fr_val) if isinstance(fr_val, (int, float)) else 0.0
+        logger.debug(f"OI={oi_val}, OI변화율={oi_change:.6f}, 펀딩비={fr_float:.6f}")
+        return oi_change, fr_float
+
+    def _calc_oi_change(self, current_oi: float) -> float:
+        """이전 OI 대비 변화율을 계산한다. 첫 캔들은 0.0 반환."""
+        if self._prev_oi is None or self._prev_oi == 0.0:
+            self._prev_oi = current_oi
+            return 0.0
+        change = (current_oi - self._prev_oi) / self._prev_oi
+        self._prev_oi = current_oi
+        return change
+
     async def process_candle(self, df, btc_df=None, eth_df=None):
+        self.ml_filter.check_and_reload()
+
+        # 캔들 마감 시 OI/펀딩비 실시간 조회 (실패해도 0으로 폴백)
+        oi_change, funding_rate = await self._fetch_market_microstructure()
+
         if not self.risk.is_trading_allowed():
             logger.warning("리스크 한도 초과 - 거래 중단")
             return
 
         ind = Indicators(df)
         df_with_indicators = ind.calculate_all()
-        signal = ind.get_signal(df_with_indicators)
-
-        if signal != "HOLD" and self.ml_filter.is_model_loaded():
-            features = build_features(df_with_indicators, signal, btc_df=btc_df, eth_df=eth_df)
-            if not self.ml_filter.should_enter(features):
-                logger.info(f"ML 필터 차단: {signal} 신호 무시")
-                signal = "HOLD"
+        raw_signal = ind.get_signal(df_with_indicators)
 
         current_price = df_with_indicators["close"].iloc[-1]
-        logger.info(f"신호: {signal} | 현재가: {current_price:.4f} USDT")
+        logger.info(f"신호: {raw_signal} | 현재가: {current_price:.4f} USDT")
 
         position = await self.exchange.get_position()
 
-        if position is None and signal != "HOLD":
+        if position is None and raw_signal != "HOLD":
             self.current_trade_side = None
             if not self.risk.can_open_new_position():
                 logger.info("최대 포지션 수 도달")
                 return
+            signal = raw_signal
+            features = build_features(
+                df_with_indicators, signal,
+                btc_df=btc_df, eth_df=eth_df,
+                oi_change=oi_change, funding_rate=funding_rate,
+            )
+            if self.ml_filter.is_model_loaded():
+                if not self.ml_filter.should_enter(features):
+                    logger.info(f"ML 필터 차단: {signal} 신호 무시")
+                    return
             await self._open_position(signal, df_with_indicators)
 
         elif position is not None:
             pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
-            if (pos_side == "LONG" and signal == "SHORT") or \
-               (pos_side == "SHORT" and signal == "LONG"):
-                await self._close_position(position)
+            if (pos_side == "LONG" and raw_signal == "SHORT") or \
+               (pos_side == "SHORT" and raw_signal == "LONG"):
+                await self._close_and_reenter(
+                    position, raw_signal, df_with_indicators,
+                    btc_df=btc_df, eth_df=eth_df,
+                    oi_change=oi_change, funding_rate=funding_rate,
+                )
 
     async def _open_position(self, signal: str, df):
         balance = await self.exchange.get_balance()
         price = df["close"].iloc[-1]
+        margin_ratio = self.risk.get_dynamic_margin_ratio(balance)
         quantity = self.exchange.calculate_quantity(
-            balance=balance, price=price, leverage=self.config.leverage
+            balance=balance, price=price, leverage=self.config.leverage, margin_ratio=margin_ratio
         )
+        logger.info(f"포지션 크기: 잔고={balance:.2f} USDT, 증거금비율={margin_ratio:.1%}, 수량={quantity}")
         stop_loss, take_profit = Indicators(df).get_atr_stop(df, signal, price)
 
         notional = quantity * price
@@ -104,12 +152,14 @@ class TradingBot:
 
         last_row = df.iloc[-1]
         signal_snapshot = {
-            "rsi":       float(last_row.get("rsi", 0)),
-            "macd_hist": float(last_row.get("macd_hist", 0)),
-            "atr":       float(last_row.get("atr", 0)),
+            "rsi":       float(last_row["rsi"])       if "rsi"       in last_row.index and pd.notna(last_row["rsi"])       else 0.0,
+            "macd_hist": float(last_row["macd_hist"]) if "macd_hist" in last_row.index and pd.notna(last_row["macd_hist"]) else 0.0,
+            "atr":       float(last_row["atr"])       if "atr"       in last_row.index and pd.notna(last_row["atr"])       else 0.0,
         }
 
         self.current_trade_side = signal
+        self._entry_price = price
+        self._entry_quantity = quantity
         self.notifier.notify_open(
             symbol=self.config.symbol,
             side=signal,
@@ -141,31 +191,111 @@ class TradingBot:
             reduce_only=True,
         )
 
-    async def _close_position(self, position: dict):
-        amt = abs(float(position["positionAmt"]))
-        side = "SELL" if float(position["positionAmt"]) > 0 else "BUY"
-        pos_side = "LONG" if side == "SELL" else "SHORT"
-        await self.exchange.cancel_all_orders()
-        await self.exchange.place_order(side=side, quantity=amt, reduce_only=True)
+    def _calc_estimated_pnl(self, exit_price: float) -> float:
+        """진입가·수량 기반 예상 PnL 계산 (수수료 미반영)."""
+        if self._entry_price is None or self._entry_quantity is None or self.current_trade_side is None:
+            return 0.0
+        if self.current_trade_side == "LONG":
+            return (exit_price - self._entry_price) * self._entry_quantity
+        return (self._entry_price - exit_price) * self._entry_quantity
 
-        entry = float(position["entryPrice"])
-        mark  = float(position["markPrice"])
-        pnl   = (mark - entry) * amt if side == "SELL" else (entry - mark) * amt
+    async def _on_position_closed(
+        self,
+        net_pnl: float,
+        close_reason: str,
+        exit_price: float,
+    ) -> None:
+        """User Data Stream에서 청산 감지 시 호출되는 콜백."""
+        estimated_pnl = self._calc_estimated_pnl(exit_price)
+        diff = net_pnl - estimated_pnl
+
+        self.risk.record_pnl(net_pnl)
 
         self.notifier.notify_close(
             symbol=self.config.symbol,
-            side=pos_side,
-            exit_price=mark,
-            pnl=pnl,
+            side=self.current_trade_side or "UNKNOWN",
+            close_reason=close_reason,
+            exit_price=exit_price,
+            estimated_pnl=estimated_pnl,
+            net_pnl=net_pnl,
+            diff=diff,
         )
-        self.risk.record_pnl(pnl)
+
+        logger.success(
+            f"포지션 청산({close_reason}): 예상={estimated_pnl:+.4f}, "
+            f"순수익={net_pnl:+.4f}, 차이={diff:+.4f} USDT"
+        )
+
+        # _close_and_reenter 중이면 신규 포지션 상태를 덮어쓰지 않는다
+        if self._is_reentering:
+            return
+
+        # Flat 상태로 초기화
         self.current_trade_side = None
-        logger.success(f"포지션 청산: PnL={pnl:.4f} USDT")
+        self._entry_price = None
+        self._entry_quantity = None
+
+    async def _close_position(self, position: dict):
+        """포지션 청산 주문만 실행한다. PnL 기록/알림은 _on_position_closed 콜백이 담당."""
+        amt = abs(float(position["positionAmt"]))
+        side = "SELL" if float(position["positionAmt"]) > 0 else "BUY"
+        await self.exchange.cancel_all_orders()
+        await self.exchange.place_order(side=side, quantity=amt, reduce_only=True)
+        logger.info(f"청산 주문 전송 완료 (side={side}, qty={amt})")
+
+    async def _close_and_reenter(
+        self,
+        position: dict,
+        signal: str,
+        df,
+        btc_df=None,
+        eth_df=None,
+        oi_change: float = 0.0,
+        funding_rate: float = 0.0,
+    ) -> None:
+        """기존 포지션을 청산하고, ML 필터 통과 시 반대 방향으로 즉시 재진입한다."""
+        # 재진입 플래그: User Data Stream 콜백이 신규 포지션 상태를 초기화하지 않도록 보호
+        self._is_reentering = True
+        try:
+            await self._close_position(position)
+
+            if not self.risk.can_open_new_position():
+                logger.info("최대 포지션 수 도달 — 재진입 건너뜀")
+                return
+
+            if self.ml_filter.is_model_loaded():
+                features = build_features(
+                    df, signal,
+                    btc_df=btc_df, eth_df=eth_df,
+                    oi_change=oi_change, funding_rate=funding_rate,
+                )
+                if not self.ml_filter.should_enter(features):
+                    logger.info(f"ML 필터 차단: {signal} 재진입 무시")
+                    return
+
+            await self._open_position(signal, df)
+        finally:
+            self._is_reentering = False
 
     async def run(self):
         logger.info(f"봇 시작: {self.config.symbol}, 레버리지 {self.config.leverage}x")
         await self._recover_position()
-        await self.stream.start(
-            api_key=self.config.api_key,
-            api_secret=self.config.api_secret,
+        balance = await self.exchange.get_balance()
+        self.risk.set_base_balance(balance)
+        logger.info(f"기준 잔고 설정: {balance:.2f} USDT (동적 증거금 비율 기준점)")
+
+        user_stream = UserDataStream(
+            symbol=self.config.symbol,
+            on_order_filled=self._on_position_closed,
+        )
+
+        await asyncio.gather(
+            self.stream.start(
+                api_key=self.config.api_key,
+                api_secret=self.config.api_secret,
+            ),
+            user_stream.start(
+                api_key=self.config.api_key,
+                api_secret=self.config.api_secret,
+            ),
         )

src/config.py

@@ -11,17 +11,21 @@ class Config:
     api_secret: str = ""
     symbol: str = "XRPUSDT"
     leverage: int = 10
-    risk_per_trade: float = 0.02
     max_positions: int = 3
     stop_loss_pct: float = 0.015    # 1.5%
     take_profit_pct: float = 0.045  # 4.5% (3:1 RR)
     trailing_stop_pct: float = 0.01  # 1%
     discord_webhook_url: str = ""
+    margin_max_ratio: float = 0.50
+    margin_min_ratio: float = 0.20
+    margin_decay_rate: float = 0.0006
 
     def __post_init__(self):
         self.api_key = os.getenv("BINANCE_API_KEY", "")
         self.api_secret = os.getenv("BINANCE_API_SECRET", "")
         self.symbol = os.getenv("SYMBOL", "XRPUSDT")
         self.leverage = int(os.getenv("LEVERAGE", "10"))
-        self.risk_per_trade = float(os.getenv("RISK_PER_TRADE", "0.02"))
         self.discord_webhook_url = os.getenv("DISCORD_WEBHOOK_URL", "")
+        self.margin_max_ratio = float(os.getenv("MARGIN_MAX_RATIO", "0.50"))
+        self.margin_min_ratio = float(os.getenv("MARGIN_MIN_RATIO", "0.20"))
+        self.margin_decay_rate = float(os.getenv("MARGIN_DECAY_RATE", "0.0006"))

src/data_stream.py

@@ -5,13 +5,21 @@ import pandas as pd
 from binance import AsyncClient, BinanceSocketManager
 from loguru import logger
 
+# 15분봉 기준 EMA50 안정화에 필요한 최소 캔들 수.
+# EMA50=50, StochRSI(14,14,3,3)=44, MACD(12,26,9)=33 중 최댓값에 여유분 추가.
+_MIN_CANDLES_FOR_SIGNAL = 100
+
+# 초기 구동 시 REST API로 가져올 과거 캔들 수.
+# 15분봉 200개 = 50시간치 — EMA50(12.5h) 대비 4배 여유.
+_PRELOAD_LIMIT = 200
+
 
 
 class KlineStream:
     def __init__(
         self,
         symbol: str,
-        interval: str = "1m",
+        interval: str = "15m",
         buffer_size: int = 200,
         on_candle: Callable = None,
     ):
@@ -32,21 +40,21 @@ class KlineStream:
             "is_closed": k["x"],
         }
 
-    def handle_message(self, msg: dict):
+    async def handle_message(self, msg: dict):
         candle = self.parse_kline(msg)
         if candle["is_closed"]:
             self.buffer.append(candle)
             if self.on_candle:
-                self.on_candle(candle)
+                await self.on_candle(candle)
 
     def get_dataframe(self) -> pd.DataFrame | None:
-        if len(self.buffer) < 50:
+        if len(self.buffer) < _MIN_CANDLES_FOR_SIGNAL:
             return None
         df = pd.DataFrame(list(self.buffer))
         df.set_index("timestamp", inplace=True)
         return df
 
-    async def _preload_history(self, client: AsyncClient, limit: int = 200):
+    async def _preload_history(self, client: AsyncClient, limit: int = _PRELOAD_LIMIT):
         """REST API로 과거 캔들 데이터를 버퍼에 미리 채운다."""
         logger.info(f"과거 캔들 {limit}개 로드 중...")
         klines = await client.futures_klines(
@@ -82,7 +90,7 @@ class KlineStream:
             ) as stream:
                 while True:
                     msg = await stream.recv()
-                    self.handle_message(msg)
+                    await self.handle_message(msg)
         finally:
             await client.close_connection()
 
@@ -96,7 +104,7 @@ class MultiSymbolStream:
     def __init__(
         self,
         symbols: list[str],
-        interval: str = "1m",
+        interval: str = "15m",
         buffer_size: int = 200,
         on_candle: Callable = None,
     ):
@@ -121,7 +129,7 @@ class MultiSymbolStream:
             "is_closed": k["x"],
         }
 
-    def handle_message(self, msg: dict):
+    async def handle_message(self, msg: dict):
         # Combined stream 메시지는 {"stream": "...", "data": {...}} 형태
         if "stream" in msg:
             data = msg["data"]
@@ -137,18 +145,18 @@ class MultiSymbolStream:
         if candle["is_closed"] and symbol in self.buffers:
             self.buffers[symbol].append(candle)
             if symbol == self.primary_symbol and self.on_candle:
-                self.on_candle(candle)
+                await self.on_candle(candle)
 
     def get_dataframe(self, symbol: str) -> pd.DataFrame | None:
         key = symbol.lower()
         buf = self.buffers.get(key)
-        if buf is None or len(buf) < 50:
+        if buf is None or len(buf) < _MIN_CANDLES_FOR_SIGNAL:
             return None
         df = pd.DataFrame(list(buf))
         df.set_index("timestamp", inplace=True)
         return df
 
-    async def _preload_history(self, client: AsyncClient, limit: int = 200):
+    async def _preload_history(self, client: AsyncClient, limit: int = _PRELOAD_LIMIT):
         """REST API로 모든 심볼의 과거 캔들을 버퍼에 미리 채운다."""
         for symbol in self.symbols:
             logger.info(f"{symbol.upper()} 과거 캔들 {limit}개 로드 중...")
@@ -184,6 +192,6 @@ class MultiSymbolStream:
             async with bm.futures_multiplex_socket(streams) as stream:
                 while True:
                     msg = await stream.recv()
-                    self.handle_message(msg)
+                    await self.handle_message(msg)
         finally:
             await client.close_connection()

src/dataset_builder.py

@@ -11,10 +11,10 @@ import pandas_ta as ta
 
 from src.ml_features import FEATURE_COLS
 
-LOOKAHEAD    = 60
+LOOKAHEAD    = 24   # 15분봉 × 24 = 6시간 뷰
 ATR_SL_MULT  = 1.5
-ATR_TP_MULT  = 3.0
-WARMUP       = 60   # 지표 안정화에 필요한 최소 행 수
+ATR_TP_MULT  = 2.0
+WARMUP       = 60   # 15분봉 기준 60캔들 = 15시간 (지표 안정화 충분)
 
 
 def _calc_indicators(df: pd.DataFrame) -> pd.DataFrame:
@@ -47,6 +47,10 @@ def _calc_indicators(df: pd.DataFrame) -> pd.DataFrame:
     d["stoch_k"] = stoch["STOCHRSIk_14_14_3_3"]
     d["stoch_d"] = stoch["STOCHRSId_14_14_3_3"]
 
+    # ADX (14) — 횡보장 필터
+    adx_df = ta.adx(high, low, close, length=14)
+    d["adx"] = adx_df["ADX_14"]
+
     return d
 
 
@@ -112,9 +116,27 @@ def _calc_signals(d: pd.DataFrame) -> np.ndarray:
     # 둘 다 해당하면 HOLD (충돌 방지)
     signal_arr[long_enter & short_enter] = "HOLD"
 
+    # ADX 횡보장 필터: ADX < 25이면 추세 부재로 판단하여 진입 차단
+    if "adx" in d.columns:
+        adx = d["adx"].values
+        low_adx = (~np.isnan(adx)) & (adx < 25)
+        signal_arr[low_adx] = "HOLD"
+
     return signal_arr
 
 
+def _rolling_zscore(arr: np.ndarray, window: int = 288) -> np.ndarray:
+    """rolling window z-score 정규화. nan은 전파된다(nan-safe).
+    15분봉 기준 3일(288캔들) 윈도우. min_periods=1로 초반 데이터도 활용."""
+    s = pd.Series(arr.astype(np.float64))
+    r = s.rolling(window=window, min_periods=1)
+    mean = r.mean()   # pandas rolling은 nan을 자동으로 건너뜀
+    std  = r.std(ddof=0)
+    std  = std.where(std >= 1e-8, other=1e-8)
+    z = (s - mean) / std
+    return z.values.astype(np.float32)
+
+
 def _calc_features_vectorized(
     d: pd.DataFrame,
     signal_arr: np.ndarray,
@@ -142,7 +164,7 @@ def _calc_features_vectorized(
     macd_sig = d["macd_signal"]
 
     bb_range = bb_upper - bb_lower
-    bb_pct = np.where(bb_range > 0, (close - bb_lower) / bb_range, 0.5)
+    bb_pct = (close - bb_lower) / (bb_range + 1e-8)
 
     ema_align = np.where(
         (ema9 > ema21) & (ema21 > ema50),  1,
@@ -151,13 +173,20 @@ def _calc_features_vectorized(
         )
     ).astype(np.float32)
 
-    atr_pct   = np.where(close > 0, atr / close, 0.0)
-    vol_ratio = np.where(vol_ma20 > 0, volume / vol_ma20, 1.0)
+    atr_pct   = atr / (close + 1e-8)
+    vol_ratio = volume / (vol_ma20 + 1e-8)
 
     ret_1 = close.pct_change(1).fillna(0).values
     ret_3 = close.pct_change(3).fillna(0).values
     ret_5 = close.pct_change(5).fillna(0).values
 
+    # 절대값 피처를 rolling z-score로 정규화 (레짐 변화에 강하게)
+    atr_pct_z   = _rolling_zscore(atr_pct)
+    vol_ratio_z = _rolling_zscore(vol_ratio)
+    ret_1_z     = _rolling_zscore(ret_1)
+    ret_3_z     = _rolling_zscore(ret_3)
+    ret_5_z     = _rolling_zscore(ret_5)
+
     prev_macd     = macd.shift(1).fillna(0).values
     prev_macd_sig = macd_sig.shift(1).fillna(0).values
 
@@ -190,11 +219,11 @@ def _calc_features_vectorized(
         "ema_align":       ema_align,
         "stoch_k":         stoch_k.values.astype(np.float32),
         "stoch_d":         stoch_d.values.astype(np.float32),
-        "atr_pct":         atr_pct.astype(np.float32),
-        "vol_ratio":       vol_ratio.astype(np.float32),
-        "ret_1":           ret_1.astype(np.float32),
-        "ret_3":           ret_3.astype(np.float32),
-        "ret_5":           ret_5.astype(np.float32),
+        "atr_pct":         atr_pct_z,
+        "vol_ratio":       vol_ratio_z,
+        "ret_1":           ret_1_z,
+        "ret_3":           ret_3_z,
+        "ret_5":           ret_5_z,
         "signal_strength": strength,
         "side":            side,
         "_signal":         signal_arr,   # 레이블 계산용 임시 컬럼
@@ -223,16 +252,45 @@ def _calc_features_vectorized(
         eth_r5 = _align(eth_ret_5, n).astype(np.float32)
 
         xrp_r1 = ret_1.astype(np.float32)
-        xrp_btc_rs = np.where(btc_r1 != 0, xrp_r1 / btc_r1, 0.0).astype(np.float32)
-        xrp_eth_rs = np.where(eth_r1 != 0, xrp_r1 / eth_r1, 0.0).astype(np.float32)
+        xrp_btc_rs_raw = np.divide(
+            xrp_r1, btc_r1,
+            out=np.zeros_like(xrp_r1),
+            where=(btc_r1 != 0),
+        ).astype(np.float32)
+        xrp_eth_rs_raw = np.divide(
+            xrp_r1, eth_r1,
+            out=np.zeros_like(xrp_r1),
+            where=(eth_r1 != 0),
+        ).astype(np.float32)
 
         extra = pd.DataFrame({
-            "btc_ret_1": btc_r1, "btc_ret_3": btc_r3, "btc_ret_5": btc_r5,
-            "eth_ret_1": eth_r1, "eth_ret_3": eth_r3, "eth_ret_5": eth_r5,
-            "xrp_btc_rs": xrp_btc_rs, "xrp_eth_rs": xrp_eth_rs,
+            "btc_ret_1":  _rolling_zscore(btc_r1),
+            "btc_ret_3":  _rolling_zscore(btc_r3),
+            "btc_ret_5":  _rolling_zscore(btc_r5),
+            "eth_ret_1":  _rolling_zscore(eth_r1),
+            "eth_ret_3":  _rolling_zscore(eth_r3),
+            "eth_ret_5":  _rolling_zscore(eth_r5),
+            "xrp_btc_rs": _rolling_zscore(xrp_btc_rs_raw),
+            "xrp_eth_rs": _rolling_zscore(xrp_eth_rs_raw),
         }, index=d.index)
         result = pd.concat([result, extra], axis=1)
 
+    # OI 변화율 / 펀딩비 피처
+    # 컬럼 없으면 전체 nan, 있으면 0.0 구간(데이터 미제공 구간)을 nan으로 마스킹
+    # LightGBM은 nan을 자체 처리; MLX는 fit()에서 nanmean/nanstd + nan_to_num 처리
+    if "oi_change" in d.columns:
+        oi_raw = np.where(d["oi_change"].values == 0.0, np.nan, d["oi_change"].values)
+    else:
+        oi_raw = np.full(len(d), np.nan)
+
+    if "funding_rate" in d.columns:
+        fr_raw = np.where(d["funding_rate"].values == 0.0, np.nan, d["funding_rate"].values)
+    else:
+        fr_raw = np.full(len(d), np.nan)
+
+    result["oi_change"]    = _rolling_zscore(oi_raw.astype(np.float64))
+    result["funding_rate"] = _rolling_zscore(fr_raw.astype(np.float64))
+
     return result
 
 
@@ -275,28 +333,26 @@ def _calc_labels_vectorized(
         fut_high = highs[idx + 1 : end]
         fut_low  = lows[idx + 1 : end]
 
-        label = None
+        label = 0  # 미도달(타임아웃) 시 실패로 간주
+
         for h, l in zip(fut_high, fut_low):
             if signal == "LONG":
-                if h >= tp:
-                    label = 1
-                    break
                 if l <= sl:
                     label = 0
                     break
-            else:
-                if l <= tp:
+                if h >= tp:
                     label = 1
                     break
+            else:  # SHORT
                 if h >= sl:
                     label = 0
                     break
+                if l <= tp:
+                    label = 1
+                    break
 
-        if label is None:
-            valid_mask.append(False)
-        else:
-            labels.append(label)
-            valid_mask.append(True)
+        labels.append(label)
+        valid_mask.append(True)
 
     return np.array(labels, dtype=np.int8), np.array(valid_mask, dtype=bool)
 
@@ -305,11 +361,21 @@ def generate_dataset_vectorized(
     df: pd.DataFrame,
     btc_df: pd.DataFrame | None = None,
     eth_df: pd.DataFrame | None = None,
+    time_weight_decay: float = 0.0,
+    negative_ratio: int = 0,
 ) -> pd.DataFrame:
     """
     전체 시계열을 1회 계산해 학습 데이터셋을 생성한다.
     기존 generate_dataset()의 drop-in 대체제.
     btc_df, eth_df가 제공되면 21개 피처로 확장한다.
+
+    time_weight_decay: 지수 감쇠 강도. 0이면 균등 가중치.
+        양수일수록 최신 샘플에 더 높은 가중치를 부여한다.
+        예) 2.0 → 최신 샘플이 가장 오래된 샘플보다 e^2 ≈ 7.4배 높은 가중치.
+        결과 DataFrame에 'sample_weight' 컬럼으로 포함된다.
+
+    negative_ratio: 시그널 샘플 대비 HOLD negative 샘플 비율.
+        0이면 기존 동작 (시그널만). 5면 시그널의 5배만큼 HOLD 샘플 추가.
     """
     print("  [1/3] 전체 시계열 지표 계산 (1회)...")
     d = _calc_indicators(df)
@@ -319,23 +385,107 @@ def generate_dataset_vectorized(
     feat_all   = _calc_features_vectorized(d, signal_arr, btc_df=btc_df, eth_df=eth_df)
 
     # 신호 발생 + NaN 없음 + 미래 데이터 충분한 인덱스만
-    available_cols_for_nan_check = [c for c in FEATURE_COLS if c in feat_all.columns]
-    valid_rows = (
-        (signal_arr != "HOLD") &
+    OPTIONAL_COLS = {"oi_change", "funding_rate"}
+    available_cols_for_nan_check = [
+        c for c in FEATURE_COLS
+        if c in feat_all.columns and c not in OPTIONAL_COLS
+    ]
+    base_valid = (
         (~feat_all[available_cols_for_nan_check].isna().any(axis=1).values) &
         (np.arange(len(d)) >= WARMUP) &
         (np.arange(len(d)) < len(d) - LOOKAHEAD)
     )
-    sig_idx = np.where(valid_rows)[0]
+
+    # --- 시그널 캔들 (기존 로직) ---
+    sig_valid = base_valid & (signal_arr != "HOLD")
+    sig_idx = np.where(sig_valid)[0]
     print(f"  신호 발생 인덱스: {len(sig_idx):,}개")
 
     print("  [3/3] 레이블 계산...")
     labels, valid_mask = _calc_labels_vectorized(d, feat_all, sig_idx)
 
-    final_idx = sig_idx[valid_mask]
-    # btc_df/eth_df 제공 여부에 따라 실제 존재하는 피처 컬럼만 선택
+    final_sig_idx = sig_idx[valid_mask]
     available_feature_cols = [c for c in FEATURE_COLS if c in feat_all.columns]
-    feat_final = feat_all.iloc[final_idx][available_feature_cols].copy()
-    feat_final["label"] = labels
+    feat_signal = feat_all.iloc[final_sig_idx][available_feature_cols].copy()
+    feat_signal["label"] = labels
+    feat_signal["source"] = "signal"
 
-    return feat_final.reset_index(drop=True)
+    # --- HOLD negative 캔들 ---
+    if negative_ratio > 0 and len(final_sig_idx) > 0:
+        hold_valid = base_valid & (signal_arr == "HOLD")
+        hold_candidates = np.where(hold_valid)[0]
+        n_neg = min(len(hold_candidates), len(final_sig_idx) * negative_ratio)
+
+        if n_neg > 0:
+            rng = np.random.default_rng(42)
+            hold_idx = rng.choice(hold_candidates, size=n_neg, replace=False)
+            hold_idx = np.sort(hold_idx)
+
+            feat_hold = feat_all.iloc[hold_idx][available_feature_cols].copy()
+            feat_hold["label"] = 0
+            feat_hold["source"] = "hold_negative"
+
+            # HOLD 캔들은 시그널이 없으므로 side를 랜덤 할당 (50:50)
+            sides = rng.integers(0, 2, size=len(feat_hold)).astype(np.float32)
+            feat_hold["side"] = sides
+
+            print(f"  HOLD negative 추가: {len(feat_hold):,}개 "
+                  f"(비율 1:{negative_ratio})")
+
+            feat_final = pd.concat([feat_signal, feat_hold], ignore_index=True)
+            # 시간 순서 복원 (원본 인덱스 기반 정렬)
+            original_order = np.concatenate([final_sig_idx, hold_idx])
+            sort_order = np.argsort(original_order)
+            feat_final = feat_final.iloc[sort_order].reset_index(drop=True)
+        else:
+            feat_final = feat_signal.reset_index(drop=True)
+    else:
+        feat_final = feat_signal.reset_index(drop=True)
+
+    # 시간 가중치
+    n = len(feat_final)
+    if time_weight_decay > 0 and n > 1:
+        weights = np.exp(time_weight_decay * np.linspace(0.0, 1.0, n)).astype(np.float32)
+        weights /= weights.mean()
+        print(f"  시간 가중치 적용 (decay={time_weight_decay}): "
+              f"min={weights.min():.3f}, max={weights.max():.3f}")
+    else:
+        weights = np.ones(n, dtype=np.float32)
+
+    feat_final["sample_weight"] = weights
+
+    total_sig = (feat_final["source"] == "signal").sum() if "source" in feat_final.columns else len(feat_final)
+    total_hold = (feat_final["source"] == "hold_negative").sum() if "source" in feat_final.columns else 0
+    print(f"  최종 데이터셋: {n:,}개 (시그널={total_sig:,}, HOLD={total_hold:,})")
+
+    return feat_final
+
+
+def stratified_undersample(
+    y: np.ndarray,
+    source: np.ndarray,
+    seed: int = 42,
+) -> np.ndarray:
+    """Signal 샘플 전수 유지 + HOLD negative만 양성 수 만큼 샘플링.
+
+    Args:
+        y: 라벨 배열 (0 or 1)
+        source: 소스 배열 ("signal" or "hold_negative")
+        seed: 랜덤 시드
+
+    Returns:
+        정렬된 인덱스 배열 (학습에 사용할 행 인덱스)
+    """
+    pos_idx = np.where(y == 1)[0]                                    # Signal Win
+    sig_neg_idx = np.where((y == 0) & (source == "signal"))[0]       # Signal Loss
+    hold_neg_idx = np.where(source == "hold_negative")[0]             # HOLD negative
+
+    # HOLD negative에서 양성 수 만큼만 샘플링
+    n_hold = min(len(hold_neg_idx), len(pos_idx))
+    rng = np.random.default_rng(seed)
+    if n_hold > 0:
+        hold_sampled = rng.choice(hold_neg_idx, size=n_hold, replace=False)
+    else:
+        hold_sampled = np.array([], dtype=np.intp)
+
+    return np.sort(np.concatenate([pos_idx, sig_neg_idx, hold_sampled]))

src/exchange.py

@@ -15,14 +15,12 @@ class BinanceFuturesClient:
 
     MIN_NOTIONAL = 5.0  # 바이낸스 선물 최소 명목금액 (USDT)
 
-    def calculate_quantity(self, balance: float, price: float, leverage: int) -> float:
-        """리스크 기반 포지션 크기 계산 (최소 명목금액 $5 보장)"""
-        risk_amount = balance * self.config.risk_per_trade
-        notional = risk_amount * leverage
+    def calculate_quantity(self, balance: float, price: float, leverage: int, margin_ratio: float) -> float:
+        """동적 증거금 비율 기반 포지션 크기 계산 (최소 명목금액 $5 보장)"""
+        notional = balance * margin_ratio * leverage
         if notional < self.MIN_NOTIONAL:
             notional = self.MIN_NOTIONAL
         quantity = notional / price
-        # XRP는 소수점 1자리, 단 최소 명목금액 충족 여부 재확인
         qty_rounded = round(quantity, 1)
         if qty_rounded * price < self.MIN_NOTIONAL:
             qty_rounded = round(self.MIN_NOTIONAL / price + 0.05, 1)
@@ -47,6 +45,8 @@ class BinanceFuturesClient:
                 return float(b["balance"])
         return 0.0
 
+    _ALGO_ORDER_TYPES = {"STOP_MARKET", "TAKE_PROFIT_MARKET", "STOP", "TAKE_PROFIT", "TRAILING_STOP_MARKET"}
+
     async def place_order(
         self,
         side: str,
@@ -57,6 +57,16 @@ class BinanceFuturesClient:
         reduce_only: bool = False,
     ) -> dict:
         loop = asyncio.get_event_loop()
+
+        if order_type in self._ALGO_ORDER_TYPES:
+            return await self._place_algo_order(
+                side=side,
+                quantity=quantity,
+                order_type=order_type,
+                stop_price=stop_price,
+                reduce_only=reduce_only,
+            )
+
         params = dict(
             symbol=self.config.symbol,
             side=side,
@@ -77,6 +87,34 @@ class BinanceFuturesClient:
             logger.error(f"주문 실패: {e}")
             raise
 
+    async def _place_algo_order(
+        self,
+        side: str,
+        quantity: float,
+        order_type: str,
+        stop_price: float = None,
+        reduce_only: bool = False,
+    ) -> dict:
+        """STOP_MARKET / TAKE_PROFIT_MARKET 등 Algo Order API(/fapi/v1/algoOrder)로 전송."""
+        loop = asyncio.get_event_loop()
+        params = dict(
+            symbol=self.config.symbol,
+            side=side,
+            algoType="CONDITIONAL",
+            type=order_type,
+            quantity=quantity,
+            reduceOnly="true" if reduce_only else "false",
+        )
+        if stop_price:
+            params["triggerPrice"] = stop_price
+        try:
+            return await loop.run_in_executor(
+                None, lambda: self.client.futures_create_algo_order(**params)
+            )
+        except BinanceAPIException as e:
+            logger.error(f"Algo 주문 실패: {e}")
+            raise
+
     async def get_position(self) -> dict | None:
         loop = asyncio.get_event_loop()
         positions = await loop.run_in_executor(
@@ -91,10 +129,74 @@ class BinanceFuturesClient:
         return None
 
     async def cancel_all_orders(self):
+        """일반 오픈 주문과 Algo 오픈 주문을 모두 취소한다."""
         loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(
+        await loop.run_in_executor(
             None,
             lambda: self.client.futures_cancel_all_open_orders(
                 symbol=self.config.symbol
             ),
         )
+        try:
+            await loop.run_in_executor(
+                None,
+                lambda: self.client.futures_cancel_all_algo_open_orders(
+                    symbol=self.config.symbol
+                ),
+            )
+        except Exception as e:
+            logger.warning(f"Algo 주문 전체 취소 실패 (무시): {e}")
+
+    async def get_open_interest(self) -> float | None:
+        """현재 미결제약정(OI)을 조회한다. 오류 시 None 반환."""
+        loop = asyncio.get_event_loop()
+        try:
+            result = await loop.run_in_executor(
+                None,
+                lambda: self.client.futures_open_interest(symbol=self.config.symbol),
+            )
+            return float(result["openInterest"])
+        except Exception as e:
+            logger.warning(f"OI 조회 실패 (무시): {e}")
+            return None
+
+    async def get_funding_rate(self) -> float | None:
+        """현재 펀딩비를 조회한다. 오류 시 None 반환."""
+        loop = asyncio.get_event_loop()
+        try:
+            result = await loop.run_in_executor(
+                None,
+                lambda: self.client.futures_mark_price(symbol=self.config.symbol),
+            )
+            return float(result["lastFundingRate"])
+        except Exception as e:
+            logger.warning(f"펀딩비 조회 실패 (무시): {e}")
+            return None
+
+    async def create_listen_key(self) -> str:
+        """POST /fapi/v1/listenKey — listenKey 신규 발급"""
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None,
+            lambda: self.client.futures_stream_get_listen_key(),
+        )
+        return result
+
+    async def keepalive_listen_key(self, listen_key: str) -> None:
+        """PUT /fapi/v1/listenKey — listenKey 만료 연장 (60분 → 리셋)"""
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: self.client.futures_stream_keepalive(listenKey=listen_key),
+        )
+
+    async def delete_listen_key(self, listen_key: str) -> None:
+        """DELETE /fapi/v1/listenKey — listenKey 삭제 (정상 종료 시)"""
+        loop = asyncio.get_event_loop()
+        try:
+            await loop.run_in_executor(
+                None,
+                lambda: self.client.futures_stream_close(listenKey=listen_key),
+            )
+        except Exception as e:
+            logger.warning(f"listenKey 삭제 실패 (무시): {e}")

src/indicators.py

@@ -43,6 +43,10 @@ class Indicators:
         df["stoch_k"] = stoch["STOCHRSIk_14_14_3_3"]
         df["stoch_d"] = stoch["STOCHRSId_14_14_3_3"]
 
+        # ADX (14) — 횡보장 필터
+        adx_df = ta.adx(df["high"], df["low"], df["close"], length=14)
+        df["adx"] = adx_df["ADX_14"]
+
         # 거래량 이동평균
         df["vol_ma20"] = ta.sma(df["volume"], length=20)
 
@@ -56,6 +60,12 @@ class Indicators:
         last = df.iloc[-1]
         prev = df.iloc[-2]
 
+        # ADX 횡보장 필터: ADX < 25이면 추세 부재로 판단하여 진입 차단
+        adx = last.get("adx", None)
+        if adx is not None and not pd.isna(adx) and adx < 25:
+            logger.debug(f"ADX 필터: {adx:.1f} < 25 — HOLD")
+            return "HOLD"
+
         long_signals  = 0
         short_signals = 0
 

src/label_builder.py

@@ -9,21 +9,17 @@ def build_labels(
     stop_loss: float,
     side: str,
 ) -> Optional[int]:
-    """
-    진입 이후 미래 캔들을 순서대로 확인해 TP/SL 도달 여부를 판단한다.
-    LONG: high >= TP → 1, low <= SL → 0
-    SHORT: low <= TP → 1, high >= SL → 0
-    둘 다 미도달 → None (학습 데이터에서 제외)
-    """
     for high, low in zip(future_highs, future_lows):
         if side == "LONG":
-            if high >= take_profit:
-                return 1
+            # 보수적 접근: 손절(SL)을 먼저 체크
             if low <= stop_loss:
                 return 0
-        else:  # SHORT
-            if low <= take_profit:
+            if high >= take_profit:
                 return 1
+        else:  # SHORT
+            # 보수적 접근: 손절(SL)을 먼저 체크
             if high >= stop_loss:
                 return 0
+            if low <= take_profit:
+                return 1
     return None

src/ml_features.py

@@ -8,6 +8,9 @@ FEATURE_COLS = [
     "btc_ret_1", "btc_ret_3", "btc_ret_5",
     "eth_ret_1", "eth_ret_3", "eth_ret_5",
     "xrp_btc_rs", "xrp_eth_rs",
+    # 시장 미시구조: OI 변화율(z-score), 펀딩비(z-score)
+    # parquet에 oi_change/funding_rate 컬럼이 없으면 dataset_builder에서 0으로 채움
+    "oi_change", "funding_rate",
 ]
 
 
@@ -31,11 +34,14 @@ def build_features(
     signal: str,
     btc_df: pd.DataFrame | None = None,
     eth_df: pd.DataFrame | None = None,
+    oi_change: float | None = None,
+    funding_rate: float | None = None,
 ) -> pd.Series:
     """
     기술 지표가 계산된 DataFrame의 마지막 행에서 ML 피처를 추출한다.
-    btc_df, eth_df가 제공되면 21개 피처를, 없으면 13개 피처를 반환한다.
+    btc_df, eth_df가 제공되면 23개 피처를, 없으면 15개 피처를 반환한다.
     signal: "LONG" | "SHORT"
+    oi_change, funding_rate: 실제 값이 제공되면 사용, 없으면 0.0으로 채운다.
     """
     last = df.iloc[-1]
     close = last["close"]
@@ -124,4 +130,8 @@ def build_features(
             "xrp_eth_rs": float(_calc_rs(ret_1, eth_ret_1)),
         })
 
+    # 실시간에서 실제 값이 제공되면 사용, 없으면 0으로 채운다
+    base["oi_change"]    = float(oi_change)    if oi_change    is not None else 0.0
+    base["funding_rate"] = float(funding_rate) if funding_rate is not None else 0.0
+
     return pd.Series(base)

src/ml_filter.py

@@ -1,50 +1,163 @@
+import os
 from pathlib import Path
 import joblib
+import numpy as np
 import pandas as pd
 from loguru import logger
 
+from src.ml_features import FEATURE_COLS
+
+ONNX_MODEL_PATH = Path("models/mlx_filter.weights.onnx")
+LGBM_MODEL_PATH = Path("models/lgbm_filter.pkl")
+
+
+def _mtime(path: Path) -> float:
+    """파일이 없으면 0.0 반환."""
+    try:
+        return path.stat().st_mtime
+    except FileNotFoundError:
+        return 0.0
+
 
 class MLFilter:
     """
-    LightGBM 모델을 로드하고 진입 여부를 판단한다.
-    모델 파일이 없으면 항상 진입을 허용한다 (폴백).
+    ML 필터. ONNX(MLX 신경망) 우선 로드, 없으면 LightGBM으로 폴백한다.
+    둘 다 없으면 항상 진입을 허용한다.
+
+    우선순위: ONNX > LightGBM > 폴백(항상 허용)
+
+    check_and_reload()를 주기적으로 호출하면 모델 파일 변경 시 자동 리로드된다.
     """
 
-    def __init__(self, model_path: str = "models/lgbm_filter.pkl", threshold: float = 0.60):
-        self._model_path = Path(model_path)
+    def __init__(
+        self,
+        onnx_path: str = str(ONNX_MODEL_PATH),
+        lgbm_path: str = str(LGBM_MODEL_PATH),
+        threshold: float = 0.60,
+    ):
+        self._disabled = os.environ.get("NO_ML_FILTER", "").lower() in ("1", "true", "yes")
+        self._onnx_path = Path(onnx_path)
+        self._lgbm_path = Path(lgbm_path)
         self._threshold = threshold
-        self._model = None
-        self._try_load()
+        self._onnx_session = None
+        self._lgbm_model = None
+        self._loaded_onnx_mtime: float = 0.0
+        self._loaded_lgbm_mtime: float = 0.0
+
+        if self._disabled:
+            logger.info("ML 필터 비활성화 모드 (NO_ML_FILTER=true) → 모든 신호 허용")
+        else:
+            self._try_load()
 
     def _try_load(self):
-        if self._model_path.exists():
+        # 로드 여부와 무관하게 두 파일의 현재 mtime을 항상 기록한다.
+        # 이렇게 해야 로드하지 않은 쪽 파일이 나중에 변경됐을 때만 리로드가 트리거된다.
+        self._loaded_onnx_mtime = _mtime(self._onnx_path)
+        self._loaded_lgbm_mtime = _mtime(self._lgbm_path)
+
+        # ONNX 우선 시도
+        if self._onnx_path.exists():
             try:
-                self._model = joblib.load(self._model_path)
-                logger.info(f"ML 필터 모델 로드 완료: {self._model_path}")
+                import onnxruntime as ort
+                sess_opts = ort.SessionOptions()
+                sess_opts.intra_op_num_threads = 1
+                sess_opts.inter_op_num_threads = 1
+                self._onnx_session = ort.InferenceSession(
+                    str(self._onnx_path),
+                    sess_options=sess_opts,
+                    providers=["CPUExecutionProvider"],
+                )
+                self._lgbm_model = None
+                logger.info(
+                    f"ML 필터 로드: ONNX ({self._onnx_path}) "
+                    f"| 임계값={self._threshold}"
+                )
+                return
             except Exception as e:
-                logger.warning(f"ML 필터 모델 로드 실패: {e}")
-                self._model = None
+                logger.warning(f"ONNX 모델 로드 실패: {e}")
+                self._onnx_session = None
+
+        # LightGBM 폴백
+        if self._lgbm_path.exists():
+            try:
+                self._lgbm_model = joblib.load(self._lgbm_path)
+                logger.info(
+                    f"ML 필터 로드: LightGBM ({self._lgbm_path}) "
+                    f"| 임계값={self._threshold}"
+                )
+            except Exception as e:
+                logger.warning(f"LightGBM 모델 로드 실패: {e}")
+                self._lgbm_model = None
+        else:
+            logger.warning("ML 필터: 모델 파일 없음 → 모든 신호 허용 (폴백)")
 
     def is_model_loaded(self) -> bool:
-        return self._model is not None
+        return self._onnx_session is not None or self._lgbm_model is not None
+
+    @property
+    def active_backend(self) -> str:
+        if self._onnx_session is not None:
+            return "ONNX"
+        if self._lgbm_model is not None:
+            return "LightGBM"
+        return "폴백(없음)"
+
+    def check_and_reload(self) -> bool:
+        """
+        모델 파일의 mtime을 확인해 변경됐으면 리로드한다.
+        실제로 리로드가 일어났으면 True 반환.
+        """
+        if self._disabled: return False
+        onnx_changed = _mtime(self._onnx_path) != self._loaded_onnx_mtime
+        lgbm_changed = _mtime(self._lgbm_path) != self._loaded_lgbm_mtime
+
+        if onnx_changed or lgbm_changed:
+            changed_files = []
+            if onnx_changed:
+                changed_files.append(str(self._onnx_path))
+            if lgbm_changed:
+                changed_files.append(str(self._lgbm_path))
+            logger.info(f"ML 필터: 모델 파일 변경 감지 → 리로드 ({', '.join(changed_files)})")
+            self._onnx_session = None
+            self._lgbm_model = None
+            self._try_load()
+            logger.info(f"ML 필터 핫리로드 완료: 백엔드={self.active_backend}")
+            return True
+        return False
 
     def should_enter(self, features: pd.Series) -> bool:
         """
         확률 >= threshold 이면 True (진입 허용).
-        모델 없으면 True 반환 (폴백).
+        NO_ML_FILTER=true 이거나 모델 없으면 True 반환 (폴백).
         """
+        if self._disabled:
+            logger.debug("ML 필터 비활성화 모드 → 진입 허용")
+            return True
         if not self.is_model_loaded():
             return True
         try:
-            X = features.to_frame().T
-            proba = self._model.predict_proba(X)[0][1]
-            logger.debug(f"ML 필터 확률: {proba:.3f} (임계값: {self._threshold})")
+            if self._onnx_session is not None:
+                input_name = self._onnx_session.get_inputs()[0].name
+                X = features[FEATURE_COLS].values.astype(np.float32).reshape(1, -1)
+                proba = float(self._onnx_session.run(None, {input_name: X})[0][0])
+            else:
+                X = features.to_frame().T
+                proba = float(self._lgbm_model.predict_proba(X)[0][1])
+            logger.debug(
+                f"ML 필터 [{self.active_backend}] 확률: {proba:.3f} "
+                f"(임계값: {self._threshold})"
+            )
             return bool(proba >= self._threshold)
         except Exception as e:
             logger.warning(f"ML 필터 예측 오류 (폴백 허용): {e}")
             return True
 
     def reload_model(self):
-        """재학습 후 모델을 핫 리로드한다."""
+        """외부에서 강제 리로드할 때 사용 (하위 호환)."""
+        prev_backend = self.active_backend
+        self._onnx_session = None
+        self._lgbm_model = None
         self._try_load()
-        logger.info("ML 필터 모델 리로드 완료")
+        logger.info(
+            f"ML 필터 강제 리로드 완료: {prev_backend} → {self.active_backend}"
+        )

src/mlx_filter.py

@@ -1,6 +1,7 @@
 """
 Apple MLX 기반 경량 신경망 필터.
 M4의 통합 GPU를 자동으로 활용한다.
+학습 후 ONNX로 export해 Linux 서버에서 onnxruntime으로 추론한다.
 """
 import numpy as np
 import pandas as pd
@@ -12,6 +13,88 @@ from pathlib import Path
 from src.ml_features import FEATURE_COLS
 
 
+def _export_onnx(
+    weights_npz: Path,
+    meta_npz: Path,
+    onnx_path: Path,
+) -> None:
+    """
+    MLX 가중치(.npz)를 읽어 ONNX 그래프로 변환한다.
+    네트워크 구조: fc1(ReLU) → dropout(추론 시 비활성) → fc2(ReLU) → fc3 → sigmoid
+    """
+    import onnx
+    from onnx import helper, TensorProto, numpy_helper
+
+    meta = np.load(meta_npz)
+    mean: np.ndarray = meta["mean"].astype(np.float32)
+    std: np.ndarray  = meta["std"].astype(np.float32)
+    input_dim  = int(meta["input_dim"])
+    hidden_dim = int(meta["hidden_dim"])
+
+    w = np.load(weights_npz)
+    # MLX save_weights 키 패턴: fc1.weight, fc1.bias, ...
+    fc1_w = w["fc1.weight"].astype(np.float32)   # (hidden, input)
+    fc1_b = w["fc1.bias"].astype(np.float32)
+    fc2_w = w["fc2.weight"].astype(np.float32)   # (hidden//2, hidden)
+    fc2_b = w["fc2.bias"].astype(np.float32)
+    fc3_w = w["fc3.weight"].astype(np.float32)   # (1, hidden//2)
+    fc3_b = w["fc3.bias"].astype(np.float32)
+
+    def _t(name: str, arr: np.ndarray) -> onnx.TensorProto:
+        return numpy_helper.from_array(arr, name=name)
+
+    initializers = [
+        _t("mean",  mean),
+        _t("std",   std),
+        _t("fc1_w", fc1_w),
+        _t("fc1_b", fc1_b),
+        _t("fc2_w", fc2_w),
+        _t("fc2_b", fc2_b),
+        _t("fc3_w", fc3_w),
+        _t("fc3_b", fc3_b),
+    ]
+
+    nodes = [
+        # 정규화: (x - mean) / std
+        helper.make_node("Sub",     ["X", "mean"],      ["x_sub"]),
+        helper.make_node("Div",     ["x_sub", "std"],   ["x_norm"]),
+        # fc1: x_norm @ fc1_w.T + fc1_b
+        helper.make_node("Gemm",    ["x_norm", "fc1_w", "fc1_b"], ["fc1_out"],
+                         transB=1),
+        helper.make_node("Relu",    ["fc1_out"],         ["relu1"]),
+        # fc2: relu1 @ fc2_w.T + fc2_b
+        helper.make_node("Gemm",    ["relu1",  "fc2_w", "fc2_b"], ["fc2_out"],
+                         transB=1),
+        helper.make_node("Relu",    ["fc2_out"],         ["relu2"]),
+        # fc3: relu2 @ fc3_w.T + fc3_b  → (N, 1)
+        helper.make_node("Gemm",    ["relu2",  "fc3_w", "fc3_b"], ["logits"],
+                         transB=1),
+        # sigmoid → (N, 1)
+        helper.make_node("Sigmoid", ["logits"],          ["proba_2d"]),
+        # squeeze: (N, 1) → (N,)  — axis=-1 로 마지막 차원만 제거
+        helper.make_node("Squeeze", ["proba_2d", "squeeze_axes"], ["proba"]),
+    ]
+
+    squeeze_axes = numpy_helper.from_array(
+        np.array([-1], dtype=np.int64), name="squeeze_axes"
+    )
+    initializers.append(squeeze_axes)
+
+    graph = helper.make_graph(
+        nodes,
+        "mlx_filter",
+        inputs=[helper.make_tensor_value_info("X", TensorProto.FLOAT, [None, input_dim])],
+        outputs=[helper.make_tensor_value_info("proba", TensorProto.FLOAT, [-1])],
+        initializer=initializers,
+    )
+    model_proto = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 17)])
+    model_proto.ir_version = 8
+    onnx.checker.check_model(model_proto)
+    onnx_path.parent.mkdir(exist_ok=True)
+    onnx.save(model_proto, str(onnx_path))
+    print(f"  ONNX export 완료: {onnx_path}")
+
+
 class _Net(nn.Module):
     """3층 MLP 이진 분류기."""
 
@@ -53,19 +136,38 @@ class MLXFilter:
         self._std: np.ndarray | None = None
         self._trained = False
 
-    def fit(self, X: pd.DataFrame, y: pd.Series) -> "MLXFilter":
+    def fit(
+        self,
+        X: pd.DataFrame,
+        y: pd.Series,
+        sample_weight: np.ndarray | None = None,
+    ) -> "MLXFilter":
         X_np = X[FEATURE_COLS].values.astype(np.float32)
         y_np = y.values.astype(np.float32)
 
-        self._mean = X_np.mean(axis=0)
-        self._std = X_np.std(axis=0) + 1e-8
+        # nan-safe 정규화: nanmean/nanstd로 통계 계산 후 nan → 0.0 대치
+        # (z-score 후 0.0 = 평균값, 신경망에 줄 수 있는 가장 무난한 결측 대치값)
+        mean_vals  = np.nanmean(X_np, axis=0)
+        self._mean = np.nan_to_num(mean_vals, nan=0.0)   # 전체-NaN 컬럼 → 평균 0.0
+        std_vals   = np.nanstd(X_np, axis=0)
+        self._std  = np.nan_to_num(std_vals, nan=1.0) + 1e-8  # 전체-NaN 컬럼 → std 1.0
         X_np = (X_np - self._mean) / self._std
+        X_np = np.nan_to_num(X_np, nan=0.0)
+
+        w_np = sample_weight.astype(np.float32) if sample_weight is not None else None
 
         optimizer = optim.Adam(learning_rate=self.lr)
 
-        def loss_fn(model: _Net, x: mx.array, y: mx.array) -> mx.array:
+        def loss_fn(
+            model: _Net, x: mx.array, y: mx.array, w: mx.array | None
+        ) -> mx.array:
             logits = model(x)
-            return nn.losses.binary_cross_entropy(logits, y, with_logits=True)
+            per_sample = nn.losses.binary_cross_entropy(
+                logits, y, with_logits=True, reduction="none"
+            )
+            if w is not None:
+                return (per_sample * w).sum() / w.sum()
+            return per_sample.mean()
 
         loss_and_grad = nn.value_and_grad(self._model, loss_fn)
 
@@ -78,7 +180,8 @@ class MLXFilter:
                 batch_idx = idx[start : start + self.batch_size]
                 x_batch = mx.array(X_np[batch_idx])
                 y_batch = mx.array(y_np[batch_idx])
-                loss, grads = loss_and_grad(self._model, x_batch, y_batch)
+                w_batch = mx.array(w_np[batch_idx]) if w_np is not None else None
+                loss, grads = loss_and_grad(self._model, x_batch, y_batch, w_batch)
                 optimizer.update(self._model, grads)
                 mx.eval(self._model.parameters(), optimizer.state)
                 epoch_loss += loss.item()
@@ -93,6 +196,7 @@ class MLXFilter:
         X_np = X[FEATURE_COLS].values.astype(np.float32)
         if self._trained and self._mean is not None:
             X_np = (X_np - self._mean) / self._std
+            X_np = np.nan_to_num(X_np, nan=0.0)
         x = mx.array(X_np)
         self._model.eval()
         logits = self._model(x)
@@ -114,6 +218,12 @@ class MLXFilter:
             input_dim=np.array(self.input_dim),
             hidden_dim=np.array(self.hidden_dim),
         )
+        # ONNX export: Linux 서버에서 onnxruntime으로 추론하기 위해 변환
+        try:
+            onnx_path = path.with_suffix(".onnx")
+            _export_onnx(weights_path, meta_path, onnx_path)
+        except ImportError:
+            print("  [경고] onnx 패키지 없음 → ONNX export 생략 (pip install onnx)")
 
     @classmethod
     def load(cls, path: str | Path) -> "MLXFilter":

src/notifier.py

@@ -49,13 +49,20 @@ class DiscordNotifier:
         self,
         symbol: str,
         side: str,
+        close_reason: str,
         exit_price: float,
-        pnl: float,
+        estimated_pnl: float,
+        net_pnl: float,
+        diff: float,
     ) -> None:
-        emoji = "✅" if pnl >= 0 else "❌"
+        emoji_map = {"TP": "✅", "SL": "❌", "MANUAL": "🔶"}
+        emoji = emoji_map.get(close_reason, "🔶")
         msg = (
-            f"{emoji} **[{symbol}] {side} 청산**\n"
-            f"청산가: `{exit_price:.4f}` | PnL: `{pnl:+.4f} USDT`"
+            f"{emoji} **[{symbol}] {side} {close_reason} 청산**\n"
+            f"청산가:               `{exit_price:.4f}`\n"
+            f"예상 수익:            `{estimated_pnl:+.4f} USDT`\n"
+            f"실제 순수익:          `{net_pnl:+.4f} USDT`\n"
+            f"차이(슬리피지+수수료): `{diff:+.4f} USDT`"
         )
         self._send(msg)
 

src/risk_manager.py

@@ -34,3 +34,14 @@ class RiskManager:
         """매일 자정 초기화"""
         self.daily_pnl = 0.0
         logger.info("일일 PnL 초기화")
+
+    def set_base_balance(self, balance: float) -> None:
+        """봇 시작 시 기준 잔고 설정 (동적 비율 계산 기준점)"""
+        self.initial_balance = balance
+
+    def get_dynamic_margin_ratio(self, balance: float) -> float:
+        """잔고에 따라 선형 감소하는 증거금 비율 반환"""
+        ratio = self.config.margin_max_ratio - (
+            (balance - self.initial_balance) * self.config.margin_decay_rate
+        )
+        return max(self.config.margin_min_ratio, min(self.config.margin_max_ratio, ratio))

src/user_data_stream.py

@@ -0,0 +1,114 @@
+import asyncio
+from typing import Callable
+from binance import AsyncClient, BinanceSocketManager
+from loguru import logger
+
+_RECONNECT_DELAY = 5  # 재연결 대기 초
+
+_CLOSE_ORDER_TYPES = {"TAKE_PROFIT_MARKET", "STOP_MARKET"}
+
+
+class UserDataStream:
+    """
+    Binance Futures User Data Stream을 구독하여 주문 체결 이벤트를 처리한다.
+
+    - python-binance BinanceSocketManager의 내장 keepalive 활용
+    - 네트워크 단절 시 무한 재연결 루프
+    - ORDER_TRADE_UPDATE 이벤트에서 지정 심볼의 청산 주문만 필터링하여 콜백 호출
+    """
+
+    def __init__(
+        self,
+        symbol: str,                     # 감시할 심볼 (예: "XRPUSDT")
+        on_order_filled: Callable,       # bot._on_position_closed 콜백
+    ):
+        self._symbol = symbol.upper()
+        self._on_order_filled = on_order_filled
+
+    async def start(self, api_key: str, api_secret: str) -> None:
+        """User Data Stream 메인 루프 — 봇 종료 시까지 실행."""
+        client = await AsyncClient.create(
+            api_key=api_key,
+            api_secret=api_secret,
+        )
+        bm = BinanceSocketManager(client)
+        try:
+            await self._run_loop(bm)
+        finally:
+            await client.close_connection()
+
+    async def _run_loop(self, bm: BinanceSocketManager) -> None:
+        """연결 → 재연결 무한 루프. BinanceSocketManager가 listenKey keepalive를 내부 처리한다."""
+        while True:
+            try:
+                async with bm.futures_user_socket() as stream:
+                    logger.info(f"User Data Stream 연결 완료 (심볼 필터: {self._symbol})")
+                    while True:
+                        msg = await stream.recv()
+
+                        if isinstance(msg, dict) and msg.get("e") == "error":
+                            logger.warning(
+                                f"웹소켓 내부 에러 수신: {msg.get('m', msg)} — "
+                                f"재연결을 위해 연결 종료"
+                            )
+                            break
+
+                        await self._handle_message(msg)
+
+            except asyncio.CancelledError:
+                logger.info("User Data Stream 정상 종료")
+                raise
+
+            except Exception as e:
+                logger.warning(
+                    f"User Data Stream 끊김: {e} — "
+                    f"{_RECONNECT_DELAY}초 후 재연결"
+                )
+                await asyncio.sleep(_RECONNECT_DELAY)
+
+    async def _handle_message(self, msg: dict) -> None:
+        """ORDER_TRADE_UPDATE 이벤트에서 청산 주문을 필터링하여 콜백을 호출한다."""
+        if msg.get("e") != "ORDER_TRADE_UPDATE":
+            return
+
+        order = msg.get("o", {})
+
+        # 심볼 필터링: 봇이 관리하는 심볼만 처리
+        if order.get("s", "") != self._symbol:
+            return
+
+        # x: Execution Type, X: Order Status
+        if order.get("x") != "TRADE" or order.get("X") != "FILLED":
+            return
+
+        order_type   = order.get("o", "")
+        is_reduce    = order.get("R", False)
+        realized_pnl = float(order.get("rp", "0"))
+
+        # 청산 주문 판별: reduceOnly이거나, TP/SL 타입이거나, rp != 0
+        is_close = is_reduce or order_type in _CLOSE_ORDER_TYPES or realized_pnl != 0
+        if not is_close:
+            return
+
+        commission = abs(float(order.get("n", "0")))
+        net_pnl    = realized_pnl - commission
+        exit_price = float(order.get("ap", "0"))
+
+        if order_type == "TAKE_PROFIT_MARKET":
+            close_reason = "TP"
+        elif order_type == "STOP_MARKET":
+            close_reason = "SL"
+        else:
+            close_reason = "MANUAL"
+
+        logger.info(
+            f"청산 감지({close_reason}): exit={exit_price:.4f}, "
+            f"rp={realized_pnl:+.4f}, commission={commission:.4f}, "
+            f"net_pnl={net_pnl:+.4f}"
+        )
+
+        await self._on_order_filled(
+            net_pnl=net_pnl,
+            close_reason=close_reason,
+            exit_price=exit_price,
+        )

tests/test_bot.py

@@ -17,6 +17,7 @@ def config():
         "RISK_PER_TRADE": "0.02",
         "NOTION_TOKEN": "secret_test",
         "NOTION_DATABASE_ID": "db_test",
+        "DISCORD_WEBHOOK_URL": "",
     })
     return Config()
 
@@ -69,3 +70,179 @@ async def test_bot_processes_signal(config, sample_df):
         mock_ind.get_atr_stop.return_value = (0.48, 0.56)
         MockInd.return_value = mock_ind
         await bot.process_candle(sample_df)
+
+
+@pytest.mark.asyncio
+async def test_close_and_reenter_calls_open_when_ml_passes(config, sample_df):
+    """반대 시그널 + ML 필터 통과 시 청산 후 재진입해야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.risk = MagicMock()
+    bot.risk.can_open_new_position.return_value = True
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True
+    bot.ml_filter.should_enter.return_value = True
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_awaited_once_with("SHORT", sample_df)
+
+
+@pytest.mark.asyncio
+async def test_close_and_reenter_skips_open_when_ml_blocks(config, sample_df):
+    """ML 필터 차단 시 청산만 하고 재진입하지 않아야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True
+    bot.ml_filter.should_enter.return_value = False
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_close_and_reenter_skips_open_when_max_positions_reached(config, sample_df):
+    """최대 포지션 수 도달 시 청산만 하고 재진입하지 않아야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot._close_position = AsyncMock()
+    bot._open_position = AsyncMock()
+    bot.risk = MagicMock()
+    bot.risk.can_open_new_position.return_value = False
+
+    position = {"positionAmt": "100", "entryPrice": "0.5", "markPrice": "0.52"}
+    await bot._close_and_reenter(position, "SHORT", sample_df)
+
+    bot._close_position.assert_awaited_once_with(position)
+    bot._open_position.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_process_candle_calls_close_and_reenter_on_reverse_signal(config, sample_df):
+    """반대 시그널 시 process_candle이 _close_and_reenter를 호출해야 한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_position = AsyncMock(return_value={
+        "positionAmt": "100",
+        "entryPrice": "0.5",
+        "markPrice": "0.52",
+    })
+    bot._close_and_reenter = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = False
+    bot.ml_filter.should_enter.return_value = True
+
+    with patch("src.bot.Indicators") as MockInd:
+        mock_ind = MagicMock()
+        mock_ind.calculate_all.return_value = sample_df
+        mock_ind.get_signal.return_value = "SHORT"  # 현재 LONG 포지션에 반대 시그널
+        MockInd.return_value = mock_ind
+        await bot.process_candle(sample_df)
+
+    bot._close_and_reenter.assert_awaited_once()
+    call_args = bot._close_and_reenter.call_args
+    assert call_args.args[1] == "SHORT"
+
+
+@pytest.mark.asyncio
+async def test_process_candle_passes_raw_signal_to_close_and_reenter_even_if_ml_loaded(config, sample_df):
+    """포지션 보유 시 ML 필터가 로드되어 있어도 process_candle은 raw signal을 _close_and_reenter에 전달한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_position = AsyncMock(return_value={
+        "positionAmt": "100",
+        "entryPrice": "0.5",
+        "markPrice": "0.52",
+    })
+    bot._close_and_reenter = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True  # 모델 로드됨
+    bot.ml_filter.should_enter.return_value = False    # ML이 차단하더라도
+
+    with patch("src.bot.Indicators") as MockInd:
+        mock_ind = MagicMock()
+        mock_ind.calculate_all.return_value = sample_df
+        mock_ind.get_signal.return_value = "SHORT"
+        MockInd.return_value = mock_ind
+        await bot.process_candle(sample_df)
+
+    # ML 필터가 차단해도 _close_and_reenter는 호출되어야 한다 (ML 재평가는 내부에서)
+    bot._close_and_reenter.assert_awaited_once()
+    call_args = bot._close_and_reenter.call_args
+    assert call_args.args[1] == "SHORT"
+    # process_candle에서 ml_filter.should_enter가 호출되지 않아야 한다
+    bot.ml_filter.should_enter.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_process_candle_fetches_oi_and_funding(config, sample_df):
+    """process_candle()이 OI와 펀딩비를 조회하고 build_features에 전달하는지 확인."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_balance = AsyncMock(return_value=1000.0)
+    bot.exchange.get_position = AsyncMock(return_value=None)
+    bot.exchange.place_order = AsyncMock(return_value={"orderId": "1"})
+    bot.exchange.set_leverage = AsyncMock()
+    bot.exchange.get_open_interest = AsyncMock(return_value=5000000.0)
+    bot.exchange.get_funding_rate = AsyncMock(return_value=0.0001)
+
+    # 신호를 LONG으로 강제해 build_features가 반드시 호출되도록 함
+    with patch("src.bot.Indicators") as mock_ind_cls:
+        mock_ind = MagicMock()
+        mock_ind.calculate_all.return_value = sample_df
+        mock_ind.get_signal.return_value = "LONG"
+        mock_ind_cls.return_value = mock_ind
+
+        with patch("src.bot.build_features") as mock_build:
+            from src.ml_features import FEATURE_COLS
+            mock_build.return_value = pd.Series({col: 0.0 for col in FEATURE_COLS})
+            bot.ml_filter.is_model_loaded = MagicMock(return_value=False)
+            # _open_position은 이 테스트의 관심사가 아니므로 mock 처리
+            bot._open_position = AsyncMock()
+            await bot.process_candle(sample_df)
+
+    assert mock_build.called
+    call_kwargs = mock_build.call_args.kwargs
+    assert "oi_change" in call_kwargs
+    assert "funding_rate" in call_kwargs
+
+
+def test_calc_oi_change_first_candle_returns_zero(config):
+    """첫 캔들은 0.0을 반환하고 _prev_oi를 설정한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+    assert bot._calc_oi_change(5000000.0) == 0.0
+    assert bot._prev_oi == 5000000.0
+
+
+def test_calc_oi_change_api_failure_does_not_corrupt_state(config):
+    """API 실패 시 _fetch_market_microstructure가 _calc_oi_change를 호출하지 않아 상태가 오염되지 않는다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+    bot._prev_oi = 5000000.0
+    # API 실패 시 _fetch_market_microstructure는 oi_val > 0 체크로 _calc_oi_change를 건너뜀
+    # _calc_oi_change(0.0)을 직접 호출하면 _prev_oi가 0.0으로 오염되는 이전 버그를 재현
+    # 수정 후에는 _fetch_market_microstructure에서 0.0을 직접 반환하므로 이 경로가 없음
+    # 대신 _calc_oi_change가 정상 값에서만 호출되는지 확인
+    result = bot._calc_oi_change(5100000.0)
+    assert abs(result - 0.02) < 1e-6  # (5100000 - 5000000) / 5000000 = 0.02
+    assert bot._prev_oi == 5100000.0

tests/test_config.py

@@ -6,16 +6,16 @@ from src.config import Config
 def test_config_loads_symbol():
     os.environ["SYMBOL"] = "XRPUSDT"
     os.environ["LEVERAGE"] = "10"
-    os.environ["RISK_PER_TRADE"] = "0.02"
     cfg = Config()
     assert cfg.symbol == "XRPUSDT"
     assert cfg.leverage == 10
-    assert cfg.risk_per_trade == 0.02
 
 
-def test_config_notion_keys():
-    os.environ["NOTION_TOKEN"] = "secret_test"
-    os.environ["NOTION_DATABASE_ID"] = "db_test_id"
+def test_config_dynamic_margin_params():
+    os.environ["MARGIN_MAX_RATIO"] = "0.50"
+    os.environ["MARGIN_MIN_RATIO"] = "0.20"
+    os.environ["MARGIN_DECAY_RATE"] = "0.0006"
     cfg = Config()
-    assert cfg.notion_token == "secret_test"
-    assert cfg.notion_database_id == "db_test_id"
+    assert cfg.margin_max_ratio == 0.50
+    assert cfg.margin_min_ratio == 0.20
+    assert cfg.margin_decay_rate == 0.0006

tests/test_data_stream.py

@@ -23,6 +23,7 @@ def test_multi_symbol_stream_get_dataframe_returns_none_when_empty():
 
 def test_multi_symbol_stream_get_dataframe_returns_df_when_full():
     import pandas as pd
+    from src.data_stream import _MIN_CANDLES_FOR_SIGNAL
     stream = MultiSymbolStream(
         symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
         interval="1m",
@@ -32,13 +33,13 @@ def test_multi_symbol_stream_get_dataframe_returns_df_when_full():
         "timestamp": 1000, "open": 1.0, "high": 1.1,
         "low": 0.9, "close": 1.05, "volume": 100.0, "is_closed": True,
     }
-    for i in range(50):
+    for i in range(_MIN_CANDLES_FOR_SIGNAL):
         c = candle.copy()
         c["timestamp"] = 1000 + i
         stream.buffers["xrpusdt"].append(c)
     df = stream.get_dataframe("XRPUSDT")
     assert df is not None
-    assert len(df) == 50
+    assert len(df) == _MIN_CANDLES_FOR_SIGNAL
 
 
 @pytest.mark.asyncio
@@ -62,11 +63,11 @@ async def test_kline_stream_parses_message():
 
 @pytest.mark.asyncio
 async def test_callback_called_on_closed_candle():
-    received = []
+    callback = AsyncMock()
     stream = KlineStream(
         symbol="XRPUSDT",
         interval="1m",
-        on_candle=lambda c: received.append(c),
+        on_candle=callback,
     )
     raw_msg = {
         "k": {
@@ -79,8 +80,8 @@ async def test_callback_called_on_closed_candle():
             "x": True,
         }
     }
-    stream.handle_message(raw_msg)
-    assert len(received) == 1
+    await stream.handle_message(raw_msg)
+    assert callback.call_count == 1
 
 
 @pytest.mark.asyncio

tests/test_database.py

@@ -1,42 +0,0 @@
-import pytest
-from unittest.mock import MagicMock, patch
-from src.database import TradeRepository
-
-
-@pytest.fixture
-def mock_repo():
-    with patch("src.database.Client") as mock_client_cls:
-        mock_client = MagicMock()
-        mock_client_cls.return_value = mock_client
-        repo = TradeRepository(token="secret_test", database_id="db_test")
-        repo.client = mock_client
-        yield repo
-
-
-def test_save_trade(mock_repo):
-    mock_repo.client.pages.create.return_value = {
-        "id": "abc123",
-        "properties": {},
-    }
-    result = mock_repo.save_trade(
-        symbol="XRPUSDT",
-        side="LONG",
-        entry_price=0.5,
-        quantity=400.0,
-        leverage=10,
-        signal_data={"rsi": 32, "macd_hist": 0.001},
-    )
-    assert result["id"] == "abc123"
-
-
-def test_close_trade(mock_repo):
-    mock_repo.client.pages.update.return_value = {
-        "id": "abc123",
-        "properties": {
-            "Status": {"select": {"name": "CLOSED"}},
-        },
-    }
-    result = mock_repo.close_trade(
-        trade_id="abc123", exit_price=0.55, pnl=20.0
-    )
-    assert result["id"] == "abc123"

tests/test_dataset_builder.py

@@ -70,7 +70,7 @@ def test_generate_dataset_vectorized_with_btc_eth_has_21_feature_cols():
     result = generate_dataset_vectorized(xrp_df, btc_df=btc_df, eth_df=eth_df)
     if not result.empty:
         assert set(FEATURE_COLS).issubset(set(result.columns))
-        assert len(result.columns) == len(FEATURE_COLS) + 1  # +1 for label
+        assert "label" in result.columns
 
 
 def test_matches_original_generate_dataset(sample_df):
@@ -91,3 +91,178 @@ def test_matches_original_generate_dataset(sample_df):
     assert 0.5 <= ratio <= 2.0, (
         f"샘플 수 차이가 너무 큼: 벡터화={len(vec)}, 기존={len(orig)}, 비율={ratio:.2f}"
     )
+
+
+def test_epsilon_no_division_by_zero():
+    """bb_range=0, close=0, vol_ma20=0 극단값에서 nan/inf가 발생하지 않아야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 100
+    # close를 모두 같은 값으로 → bb_range=0 유발
+    df = pd.DataFrame({
+        "open":   np.ones(n),
+        "high":   np.ones(n),
+        "low":    np.ones(n),
+        "close":  np.ones(n),
+        "volume": np.ones(n),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    numeric_cols = feat.select_dtypes(include=[np.number]).columns
+    assert not feat[numeric_cols].isin([np.inf, -np.inf]).any().any(), \
+        "inf 값이 있으면 안 됨"
+
+
+def test_oi_nan_masking_no_column():
+    """oi_change 컬럼이 없으면 전체가 nan이어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 100
+    np.random.seed(0)
+    df = pd.DataFrame({
+        "open":   np.random.uniform(1, 2, n),
+        "high":   np.random.uniform(2, 3, n),
+        "low":    np.random.uniform(0.5, 1, n),
+        "close":  np.random.uniform(1, 2, n),
+        "volume": np.random.uniform(1000, 5000, n),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    assert feat["oi_change"].isna().all(), "oi_change 컬럼 없을 때 전부 nan이어야 함"
+
+
+def test_oi_nan_masking_with_zeros():
+    """oi_change 컬럼이 있어도 0.0 구간은 nan으로 마스킹되어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 100
+    np.random.seed(0)
+    df = pd.DataFrame({
+        "open":      np.random.uniform(1, 2, n),
+        "high":      np.random.uniform(2, 3, n),
+        "low":       np.random.uniform(0.5, 1, n),
+        "close":     np.random.uniform(1, 2, n),
+        "volume":    np.random.uniform(1000, 5000, n),
+        "oi_change": np.concatenate([np.zeros(50), np.random.uniform(-0.1, 0.1, 50)]),
+    })
+    d = _calc_indicators(df)
+    sig = _calc_signals(d)
+    feat = _calc_features_vectorized(d, sig)
+
+    assert feat["oi_change"].iloc[50:].notna().any(), "실제 OI 값 구간에 유한값이 있어야 함"
+
+
+def test_rs_zero_denominator():
+    """btc_r1=0일 때 RS가 inf/nan이 아닌 0.0이어야 한다 (np.divide 방식 검증)."""
+    import numpy as np
+    import pandas as pd
+    from src.dataset_builder import _calc_features_vectorized, _calc_signals, _calc_indicators
+
+    n = 500
+    np.random.seed(7)
+    # XRP close: 약간의 변동
+    xrp_close = np.cumprod(1 + np.random.randn(n) * 0.001) * 1.0
+    xrp_df = pd.DataFrame({
+        "open":   xrp_close * 0.999,
+        "high":   xrp_close * 1.005,
+        "low":    xrp_close * 0.995,
+        "close":  xrp_close,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+    # BTC close: 완전히 고정 → btc_r1 = 0.0
+    btc_close = np.ones(n) * 50000.0
+    btc_df = pd.DataFrame({
+        "open":   btc_close,
+        "high":   btc_close,
+        "low":    btc_close,
+        "close":  btc_close,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+    # ETH close: 약간의 변동 (eth_df 없으면 BTC 피처 자체가 계산 안 됨)
+    eth_close = np.cumprod(1 + np.random.randn(n) * 0.001) * 3000.0
+    eth_df = pd.DataFrame({
+        "open":   eth_close * 0.999,
+        "high":   eth_close * 1.005,
+        "low":    eth_close * 0.995,
+        "close":  eth_close,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+
+    # _calc_features_vectorized를 직접 호출해 BTC/ETH 피처를 포함한 전체 피처를 검증
+    d = _calc_indicators(xrp_df)
+    signal_arr = _calc_signals(d)
+    feat = _calc_features_vectorized(d, signal_arr, btc_df=btc_df, eth_df=eth_df)
+
+    assert "xrp_btc_rs" in feat.columns, "xrp_btc_rs 컬럼이 있어야 함"
+    assert not feat["xrp_btc_rs"].isin([np.inf, -np.inf]).any(), \
+        "xrp_btc_rs에 inf가 있으면 안 됨"
+    assert not feat["xrp_btc_rs"].isna().all(), \
+        "xrp_btc_rs가 전부 nan이면 안 됨"
+
+
+@pytest.fixture
+def signal_producing_df():
+    """시그널이 반드시 발생하는 더미 데이터. 높은 변동성 + 거래량 급증."""
+    rng = np.random.default_rng(7)
+    n = 800
+    trend = np.linspace(1.5, 3.0, n)
+    noise = np.cumsum(rng.normal(0, 0.04, n))
+    close = np.clip(trend + noise, 0.01, None)
+    high  = close * (1 + rng.uniform(0, 0.015, n))
+    low   = close * (1 - rng.uniform(0, 0.015, n))
+    volume = rng.uniform(1e6, 3e6, n)
+    volume[::30] *= 3.0  # 30봉마다 거래량 급증
+    return pd.DataFrame({
+        "open": close, "high": high, "low": low,
+        "close": close, "volume": volume,
+    })
+
+
+def test_hold_negative_labels_are_all_zero(signal_producing_df):
+    """HOLD negative 샘플의 label은 전부 0이어야 한다."""
+    result = generate_dataset_vectorized(signal_producing_df, negative_ratio=3)
+    assert len(result) > 0, "시그널이 발생하지 않아 테스트 불가"
+    assert "source" in result.columns
+    hold_neg = result[result["source"] == "hold_negative"]
+    assert len(hold_neg) > 0, "HOLD negative 샘플이 0개"
+    assert (hold_neg["label"] == 0).all(), \
+        f"HOLD negative 중 label != 0인 샘플 존재: {hold_neg['label'].value_counts().to_dict()}"
+
+
+def test_signal_samples_preserved_after_sampling(signal_producing_df):
+    """계층적 샘플링 후 source='signal' 샘플이 하나도 버려지지 않아야 한다."""
+    result_signal_only = generate_dataset_vectorized(signal_producing_df, negative_ratio=0)
+    result_with_hold   = generate_dataset_vectorized(signal_producing_df, negative_ratio=3)
+
+    assert len(result_signal_only) > 0, "시그널이 발생하지 않아 테스트 불가"
+    assert "source" in result_with_hold.columns
+    signal_count = (result_with_hold["source"] == "signal").sum()
+    assert signal_count == len(result_signal_only), \
+        f"Signal 샘플 손실: 원본={len(result_signal_only)}, 유지={signal_count}"
+
+
+def test_stratified_undersample_preserves_signal():
+    """stratified_undersample은 signal 샘플을 전수 유지해야 한다."""
+    from src.dataset_builder import stratified_undersample
+
+    y      = np.array([1, 0, 0, 0, 0, 0, 0, 0, 1, 0])
+    source = np.array(["signal", "signal", "signal", "hold_negative",
+                        "hold_negative", "hold_negative", "hold_negative",
+                        "hold_negative", "signal", "signal"])
+
+    idx = stratified_undersample(y, source, seed=42)
+
+    # signal 인덱스: 0, 1, 2, 8, 9 → 전부 포함
+    signal_indices = np.where(source == "signal")[0]
+    for si in signal_indices:
+        assert si in idx, f"signal 인덱스 {si}가 누락됨"

tests/test_exchange.py

@@ -12,11 +12,34 @@ def config():
         "BINANCE_API_SECRET": "test_secret",
         "SYMBOL": "XRPUSDT",
         "LEVERAGE": "10",
-        "RISK_PER_TRADE": "0.02",
     })
     return Config()
 
 
+@pytest.fixture
+def client():
+    config = Config()
+    config.leverage = 10
+    c = BinanceFuturesClient.__new__(BinanceFuturesClient)
+    c.config = config
+    return c
+
+
+@pytest.fixture
+def exchange():
+    os.environ.update({
+        "BINANCE_API_KEY": "test_key",
+        "BINANCE_API_SECRET": "test_secret",
+        "SYMBOL": "XRPUSDT",
+        "LEVERAGE": "10",
+    })
+    config = Config()
+    c = BinanceFuturesClient.__new__(BinanceFuturesClient)
+    c.config = config
+    c.client = MagicMock()
+    return c
+
+
 @pytest.mark.asyncio
 async def test_set_leverage(config):
     with patch("src.exchange.Client") as MockClient:
@@ -28,11 +51,65 @@ async def test_set_leverage(config):
         assert result is not None
 
 
-def test_calculate_quantity(config):
-    with patch("src.exchange.Client") as MockClient:
-        MockClient.return_value = MagicMock()
-        client = BinanceFuturesClient(config)
-        # 잔고 1000 USDT, 리스크 2%, 레버리지 10, 가격 0.5
-        qty = client.calculate_quantity(balance=1000.0, price=0.5, leverage=10)
-        # 1000 * 0.02 * 10 / 0.5 = 400
-        assert qty == pytest.approx(400.0, rel=0.01)
+def test_calculate_quantity_basic(client):
+    """잔고 22, 비율 50%, 레버리지 10배 → 명목금액 110, XRP 가격 2.5 → 수량 44.0"""
+    qty = client.calculate_quantity(balance=22.0, price=2.5, leverage=10, margin_ratio=0.50)
+    # 명목금액 = 22 * 0.5 * 10 = 110, 수량 = 110 / 2.5 = 44.0
+    assert qty == pytest.approx(44.0, abs=0.1)
+
+
+def test_calculate_quantity_min_notional(client):
+    """명목금액이 최소(5 USDT) 미만이면 최소값으로 올림"""
+    qty = client.calculate_quantity(balance=1.0, price=2.5, leverage=1, margin_ratio=0.01)
+    # 명목금액 = 1 * 0.01 * 1 = 0.01 < 5 → 최소 5 USDT
+    assert qty * 2.5 >= 5.0
+
+
+def test_calculate_quantity_zero_balance(client):
+    """잔고 0이면 최소 명목금액 기반 수량 반환"""
+    qty = client.calculate_quantity(balance=0.0, price=2.5, leverage=10, margin_ratio=0.50)
+    assert qty > 0
+
+
+@pytest.mark.asyncio
+async def test_get_open_interest(exchange):
+    """get_open_interest()가 float을 반환하는지 확인."""
+    exchange.client.futures_open_interest = MagicMock(
+        return_value={"openInterest": "123456.789"}
+    )
+    result = await exchange.get_open_interest()
+    assert isinstance(result, float)
+    assert result == pytest.approx(123456.789)
+
+
+@pytest.mark.asyncio
+async def test_get_funding_rate(exchange):
+    """get_funding_rate()가 float을 반환하는지 확인."""
+    exchange.client.futures_mark_price = MagicMock(
+        return_value={"lastFundingRate": "0.0001"}
+    )
+    result = await exchange.get_funding_rate()
+    assert isinstance(result, float)
+    assert result == pytest.approx(0.0001)
+
+
+@pytest.mark.asyncio
+async def test_get_open_interest_error_returns_none(exchange):
+    """API 오류 시 None 반환 확인."""
+    from binance.exceptions import BinanceAPIException
+    exchange.client.futures_open_interest = MagicMock(
+        side_effect=BinanceAPIException(MagicMock(status_code=400), 400, '{"code":-1121,"msg":"Invalid symbol"}')
+    )
+    result = await exchange.get_open_interest()
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_get_funding_rate_error_returns_none(exchange):
+    """API 오류 시 None 반환 확인."""
+    from binance.exceptions import BinanceAPIException
+    exchange.client.futures_mark_price = MagicMock(
+        side_effect=BinanceAPIException(MagicMock(status_code=400), 400, '{"code":-1121,"msg":"Invalid symbol"}')
+    )
+    result = await exchange.get_funding_rate()
+    assert result is None

tests/test_fetch_history.py

@@ -0,0 +1,131 @@
+"""fetch_history.py의 upsert_parquet() 함수 테스트."""
+import pandas as pd
+import numpy as np
+import pytest
+from pathlib import Path
+
+
+def _make_parquet(tmp_path: Path, rows: dict) -> Path:
+    """테스트용 parquet 파일 생성 헬퍼."""
+    df = pd.DataFrame(rows)
+    df["timestamp"] = pd.to_datetime(df["timestamp"], utc=True)
+    df = df.set_index("timestamp")
+    path = tmp_path / "test.parquet"
+    df.to_parquet(path)
+    return path
+
+
+def test_upsert_fills_zero_oi_with_real_value(tmp_path):
+    """기존 행의 oi_change=0.0이 신규 데이터의 실제 값으로 덮어써진다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00", "2026-01-01 00:15"],
+        "close": [1.0, 1.1],
+        "oi_change": [0.0, 0.0],
+        "funding_rate": [0.0, 0.0],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1],
+        "oi_change": [0.05, 0.03],
+        "funding_rate": [0.0001, 0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00", "2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert result.loc["2026-01-01 00:00+00:00", "oi_change"] == pytest.approx(0.05)
+    assert result.loc["2026-01-01 00:15+00:00", "oi_change"] == pytest.approx(0.03)
+
+
+def test_upsert_appends_new_rows(tmp_path):
+    """신규 타임스탬프 행이 기존 데이터 아래에 추가된다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00"],
+        "close": [1.0],
+        "oi_change": [0.05],
+        "funding_rate": [0.0001],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.1],
+        "oi_change": [0.03],
+        "funding_rate": [0.0002],
+    }, index=pd.to_datetime(["2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert len(result) == 2
+    assert pd.Timestamp("2026-01-01 00:15", tz="UTC") in result.index
+
+
+def test_upsert_keeps_nonzero_existing_oi(tmp_path):
+    """기존 행의 oi_change가 이미 0이 아니면 덮어쓰지 않는다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:00"],
+        "close": [1.0],
+        "oi_change": [0.07],   # 이미 실제 값 존재
+        "funding_rate": [0.0003],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0],
+        "oi_change": [0.05],   # 다른 값으로 덮어쓰려 해도
+        "funding_rate": [0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    # 기존 값(0.07)이 유지되어야 한다
+    assert result.iloc[0]["oi_change"] == pytest.approx(0.07)
+
+
+def test_upsert_no_existing_file_returns_new_df(tmp_path):
+    """기존 parquet 파일이 없으면 신규 데이터를 그대로 반환한다."""
+    from scripts.fetch_history import upsert_parquet
+
+    nonexistent_path = tmp_path / "nonexistent.parquet"
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1],
+        "oi_change": [0.05, 0.03],
+        "funding_rate": [0.0001, 0.0001],
+    }, index=pd.to_datetime(["2026-01-01 00:00", "2026-01-01 00:15"], utc=True))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(nonexistent_path, new_df)
+
+    assert len(result) == 2
+    assert result.iloc[0]["oi_change"] == pytest.approx(0.05)
+
+
+def test_upsert_result_is_sorted_by_timestamp(tmp_path):
+    """결과 DataFrame이 timestamp 기준 오름차순 정렬되어 있다."""
+    from scripts.fetch_history import upsert_parquet
+
+    existing_path = _make_parquet(tmp_path, {
+        "timestamp": ["2026-01-01 00:15"],
+        "close": [1.1],
+        "oi_change": [0.0],
+        "funding_rate": [0.0],
+    })
+
+    new_df = pd.DataFrame({
+        "close": [1.0, 1.1, 1.2],
+        "oi_change": [0.05, 0.03, 0.02],
+        "funding_rate": [0.0001, 0.0001, 0.0002],
+    }, index=pd.to_datetime(
+        ["2026-01-01 00:00", "2026-01-01 00:15", "2026-01-01 00:30"], utc=True
+    ))
+    new_df.index.name = "timestamp"
+
+    result = upsert_parquet(existing_path, new_df)
+
+    assert result.index.is_monotonic_increasing
+    assert len(result) == 3

tests/test_indicators.py

@@ -45,6 +45,42 @@ def test_bollinger_bands(sample_df):
     assert (valid["bb_upper"] >= valid["bb_lower"]).all()
 
 
+def test_adx_column_exists(sample_df):
+    """calculate_all()이 adx 컬럼을 생성하는지 확인."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    assert "adx" in df.columns
+    valid = df["adx"].dropna()
+    assert (valid >= 0).all()
+
+
+def test_adx_filter_blocks_low_adx(sample_df):
+    """ADX < 25일 때 가중치와 무관하게 HOLD를 반환해야 한다."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    # 강한 LONG 신호가 나오도록 지표 조작
+    df.loc[df.index[-1], "rsi"] = 20              # RSI 과매도 → +1
+    df.loc[df.index[-2], "macd"] = -1             # MACD 골든크로스 → +2
+    df.loc[df.index[-2], "macd_signal"] = 0
+    df.loc[df.index[-1], "macd"] = 1
+    df.loc[df.index[-1], "macd_signal"] = 0
+    df.loc[df.index[-1], "volume"] = df.loc[df.index[-1], "vol_ma20"] * 2  # 거래량 서지
+    # ADX를 강제로 낮은 값으로 설정
+    df["adx"] = 15.0
+    signal = ind.get_signal(df)
+    assert signal == "HOLD"
+
+
+def test_adx_nan_falls_through(sample_df):
+    """ADX가 NaN(초기 캔들)이면 기존 가중치 로직으로 폴백해야 한다."""
+    ind = Indicators(sample_df)
+    df = ind.calculate_all()
+    df["adx"] = float("nan")
+    signal = ind.get_signal(df)
+    # NaN이면 차단하지 않고 기존 로직 실행 → LONG/SHORT/HOLD 중 하나
+    assert signal in ("LONG", "SHORT", "HOLD")
+
+
 def test_signal_returns_direction(sample_df):
     ind = Indicators(sample_df)
     df = ind.calculate_all()

tests/test_ml_features.py

@@ -25,12 +25,12 @@ def test_build_features_with_btc_eth_has_21_features():
     btc_df = _make_df(10, base_price=50000.0)
     eth_df = _make_df(10, base_price=3000.0)
     features = build_features(xrp_df, "LONG", btc_df=btc_df, eth_df=eth_df)
-    assert len(features) == 21
+    assert len(features) == 23
 
 def test_build_features_without_btc_eth_has_13_features():
     xrp_df = _make_df(10, base_price=1.0)
     features = build_features(xrp_df, "LONG")
-    assert len(features) == 13
+    assert len(features) == 15
 
 def test_build_features_btc_ret_1_correct():
     xrp_df = _make_df(10, base_price=1.0)
@@ -49,9 +49,9 @@ def test_build_features_rs_zero_when_btc_ret_zero():
     features = build_features(xrp_df, "LONG", btc_df=btc_df, eth_df=eth_df)
     assert features["xrp_btc_rs"] == 0.0
 
-def test_feature_cols_has_21_items():
+def test_feature_cols_has_23_items():
     from src.ml_features import FEATURE_COLS
-    assert len(FEATURE_COLS) == 21
+    assert len(FEATURE_COLS) == 23
 
 
 def make_df(n=100):
@@ -111,3 +111,30 @@ def test_side_encoding():
     short_feat = build_features(df_ind, signal="SHORT")
     assert long_feat["side"] == 1
     assert short_feat["side"] == 0
+
+
+@pytest.fixture
+def sample_df_with_indicators():
+    from src.indicators import Indicators
+    df = make_df(100)
+    ind = Indicators(df)
+    return ind.calculate_all()
+
+
+def test_build_features_uses_provided_oi_funding(sample_df_with_indicators):
+    """oi_change, funding_rate 파라미터가 제공되면 실제 값이 피처에 반영된다."""
+    feat = build_features(
+        sample_df_with_indicators,
+        signal="LONG",
+        oi_change=0.05,
+        funding_rate=0.0002,
+    )
+    assert feat["oi_change"] == pytest.approx(0.05)
+    assert feat["funding_rate"] == pytest.approx(0.0002)
+
+
+def test_build_features_defaults_to_zero_when_not_provided(sample_df_with_indicators):
+    """oi_change, funding_rate 파라미터 미제공 시 0.0으로 채워진다."""
+    feat = build_features(sample_df_with_indicators, signal="LONG")
+    assert feat["oi_change"] == pytest.approx(0.0)
+    assert feat["funding_rate"] == pytest.approx(0.0)

tests/test_ml_filter.py

@@ -12,13 +12,19 @@ def make_features(side="LONG") -> pd.Series:
 
 
 def test_no_model_file_is_not_loaded(tmp_path):
-    f = MLFilter(model_path=str(tmp_path / "nonexistent.pkl"))
+    f = MLFilter(
+        onnx_path=str(tmp_path / "nonexistent.onnx"),
+        lgbm_path=str(tmp_path / "nonexistent.pkl"),
+    )
     assert not f.is_model_loaded()
 
 
 def test_no_model_should_enter_returns_true(tmp_path):
     """모델 없으면 항상 진입 허용 (폴백)"""
-    f = MLFilter(model_path=str(tmp_path / "nonexistent.pkl"))
+    f = MLFilter(
+        onnx_path=str(tmp_path / "nonexistent.onnx"),
+        lgbm_path=str(tmp_path / "nonexistent.pkl"),
+    )
     features = make_features()
     assert f.should_enter(features) is True
 
@@ -28,7 +34,7 @@ def test_should_enter_above_threshold():
     f = MLFilter(threshold=0.60)
     mock_model = MagicMock()
     mock_model.predict_proba.return_value = np.array([[0.35, 0.65]])
-    f._model = mock_model
+    f._lgbm_model = mock_model
     features = make_features()
     assert f.should_enter(features) is True
 
@@ -38,7 +44,7 @@ def test_should_enter_below_threshold():
     f = MLFilter(threshold=0.60)
     mock_model = MagicMock()
     mock_model.predict_proba.return_value = np.array([[0.55, 0.45]])
-    f._model = mock_model
+    f._lgbm_model = mock_model
     features = make_features()
     assert f.should_enter(features) is False
 
@@ -48,16 +54,18 @@ def test_reload_model(tmp_path):
     import joblib
 
     # 모델 파일이 없는 상태에서 시작
-    model_path = tmp_path / "lgbm_filter.pkl"
-    f = MLFilter(model_path=str(model_path))
+    f = MLFilter(
+        onnx_path=str(tmp_path / "nonexistent.onnx"),
+        lgbm_path=str(tmp_path / "lgbm_filter.pkl"),
+    )
     assert not f.is_model_loaded()
 
-    # _model을 직접 주입해서 is_model_loaded가 True인지 확인
+    # _lgbm_model을 직접 주입해서 is_model_loaded가 True인지 확인
     mock_model = MagicMock()
-    f._model = mock_model
+    f._lgbm_model = mock_model
     assert f.is_model_loaded()
 
-    # reload_model 호출 시 파일이 없으면 _try_load가 _model을 변경하지 않음
-    # (기존 동작 유지 - 파일 없으면 None으로 초기화하지 않음)
+    # reload_model은 항상 _lgbm_model/_onnx_session을 초기화 후 재로드한다.
+    # 파일이 없으면 None으로 리셋되어 폴백 상태가 된다.
     f.reload_model()
-    assert f.is_model_loaded()  # mock_model이 유지됨
+    assert not f.is_model_loaded()  # 파일 없으므로 폴백 상태

tests/test_mlx_filter.py

@@ -10,23 +10,11 @@ mlx = pytest.importorskip("mlx.core", reason="MLX 미설치")
 
 
 def _make_X(n: int = 4) -> pd.DataFrame:
+    from src.ml_features import FEATURE_COLS
     rng = np.random.default_rng(0)
     return pd.DataFrame(
-        {
-            "rsi": rng.uniform(20, 80, n),
-            "macd_hist": rng.uniform(-0.1, 0.1, n),
-            "bb_pct": rng.uniform(0, 1, n),
-            "ema_align": rng.choice([-1.0, 0.0, 1.0], n),
-            "stoch_k": rng.uniform(0, 100, n),
-            "stoch_d": rng.uniform(0, 100, n),
-            "atr_pct": rng.uniform(0.001, 0.05, n),
-            "vol_ratio": rng.uniform(0.5, 3.0, n),
-            "ret_1": rng.uniform(-0.01, 0.01, n),
-            "ret_3": rng.uniform(-0.02, 0.02, n),
-            "ret_5": rng.uniform(-0.03, 0.03, n),
-            "signal_strength": rng.integers(0, 6, n).astype(float),
-            "side": rng.choice([0.0, 1.0], n),
-        }
+        rng.uniform(-1.0, 1.0, (n, len(FEATURE_COLS))).astype(np.float32),
+        columns=FEATURE_COLS,
     )
 
 
@@ -41,9 +29,10 @@ def test_mlx_gpu_device():
 def test_mlx_filter_predict_shape_untrained():
     """학습 전에도 predict_proba가 (N,) 형태를 반환해야 한다."""
     from src.mlx_filter import MLXFilter
+    from src.ml_features import FEATURE_COLS
 
     X = _make_X(4)
-    model = MLXFilter(input_dim=13, hidden_dim=32)
+    model = MLXFilter(input_dim=len(FEATURE_COLS), hidden_dim=32)
     proba = model.predict_proba(X)
     assert proba.shape == (4,)
     assert np.all((proba >= 0.0) & (proba <= 1.0))
@@ -52,12 +41,13 @@ def test_mlx_filter_predict_shape_untrained():
 def test_mlx_filter_fit_and_predict():
     """학습 후 predict_proba가 유효한 확률값을 반환해야 한다."""
     from src.mlx_filter import MLXFilter
+    from src.ml_features import FEATURE_COLS
 
     n = 100
     X = _make_X(n)
     y = pd.Series(np.random.randint(0, 2, n))
 
-    model = MLXFilter(input_dim=13, hidden_dim=32, epochs=5, batch_size=32)
+    model = MLXFilter(input_dim=len(FEATURE_COLS), hidden_dim=32, epochs=5, batch_size=32)
     model.fit(X, y)
     proba = model.predict_proba(X)
 
@@ -65,15 +55,41 @@ def test_mlx_filter_fit_and_predict():
     assert np.all((proba >= 0.0) & (proba <= 1.0))
 
 
+def test_fit_with_nan_features():
+    """oi_change 피처에 nan이 포함된 경우 학습이 정상 완료되어야 한다."""
+    import numpy as np
+    import pandas as pd
+    from src.mlx_filter import MLXFilter
+    from src.ml_features import FEATURE_COLS
+
+    n = 300
+    np.random.seed(42)
+    X = pd.DataFrame(
+        np.random.randn(n, len(FEATURE_COLS)).astype(np.float32),
+        columns=FEATURE_COLS,
+    )
+    # oi_change 앞 절반을 nan으로
+    X["oi_change"] = np.where(np.arange(n) < n // 2, np.nan, X["oi_change"])
+    y = pd.Series((np.random.rand(n) > 0.5).astype(np.float32))
+
+    model = MLXFilter(input_dim=len(FEATURE_COLS), hidden_dim=32, epochs=3)
+    model.fit(X, y)  # nan 있어도 예외 없이 완료되어야 함
+
+    proba = model.predict_proba(X)
+    assert not np.any(np.isnan(proba)), "예측 확률에 nan이 없어야 함"
+    assert proba.min() >= 0.0 and proba.max() <= 1.0
+
+
 def test_mlx_filter_save_load(tmp_path):
     """저장 후 로드한 모델이 동일한 예측값을 반환해야 한다."""
     from src.mlx_filter import MLXFilter
+    from src.ml_features import FEATURE_COLS
 
     n = 50
     X = _make_X(n)
     y = pd.Series(np.random.randint(0, 2, n))
 
-    model = MLXFilter(input_dim=13, hidden_dim=32, epochs=3, batch_size=32)
+    model = MLXFilter(input_dim=len(FEATURE_COLS), hidden_dim=32, epochs=3, batch_size=32)
     model.fit(X, y)
     proba_before = model.predict_proba(X)
 

tests/test_risk_manager.py

@@ -11,7 +11,6 @@ def config():
         "BINANCE_API_SECRET": "s",
         "SYMBOL": "XRPUSDT",
         "LEVERAGE": "10",
-        "RISK_PER_TRADE": "0.02",
     })
     return Config()
 
@@ -34,3 +33,51 @@ def test_position_size_capped(config):
     rm = RiskManager(config, max_daily_loss_pct=0.05)
     rm.open_positions = ["pos1", "pos2", "pos3"]
     assert rm.can_open_new_position() is False
+
+
+# --- 동적 증거금 비율 테스트 ---
+
+@pytest.fixture
+def dynamic_config():
+    c = Config()
+    c.margin_max_ratio = 0.50
+    c.margin_min_ratio = 0.20
+    c.margin_decay_rate = 0.0006
+    return c
+
+
+@pytest.fixture
+def risk(dynamic_config):
+    r = RiskManager(dynamic_config)
+    r.set_base_balance(22.0)
+    return r
+
+
+def test_set_base_balance(risk):
+    assert risk.initial_balance == 22.0
+
+
+def test_ratio_at_base_balance(risk):
+    """기준 잔고에서 최대 비율(50%) 반환"""
+    ratio = risk.get_dynamic_margin_ratio(22.0)
+    assert ratio == pytest.approx(0.50, abs=1e-6)
+
+
+def test_ratio_decreases_as_balance_grows(risk):
+    """잔고가 늘수록 비율 감소"""
+    ratio_100 = risk.get_dynamic_margin_ratio(100.0)
+    ratio_300 = risk.get_dynamic_margin_ratio(300.0)
+    assert ratio_100 < 0.50
+    assert ratio_300 < ratio_100
+
+
+def test_ratio_clamped_at_min(risk):
+    """잔고가 매우 커도 최소 비율(20%) 이하로 내려가지 않음"""
+    ratio = risk.get_dynamic_margin_ratio(10000.0)
+    assert ratio == pytest.approx(0.20, abs=1e-6)
+
+
+def test_ratio_clamped_at_max(risk):
+    """잔고가 기준보다 작아도 최대 비율(50%) 초과하지 않음"""
+    ratio = risk.get_dynamic_margin_ratio(5.0)
+    assert ratio == pytest.approx(0.50, abs=1e-6)