feat: MLX 임계값 탐색을 정밀도 우선(recall>=0.15 조건부)으로 변경

Made-with: Cursor

.dockerignore

@@ -0,0 +1,11 @@
+.env
+.venv
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+logs/
+*.log
+.git
+docs/
+tests/

.gitignore

@@ -6,3 +6,6 @@ logs/
 *.log
 .venv/
 venv/
+models/*.pkl
+data/*.parquet
+.worktrees/

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+# mlx는 Apple Silicon 전용이므로 컨테이너에 설치하지 않는다
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p logs models data
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+CMD ["python", "main.py"]

Jenkinsfile

@@ -0,0 +1,94 @@
+pipeline {
+    agent any
+
+    environment {
+        REGISTRY      = '10.1.10.28:3000'
+        IMAGE_NAME    = 'gihyeon/cointrader'
+        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',
+                    credentialsId: 'gitea-cred',
+                    url: 'http://10.1.10.28:3000/gihyeon/cointrader.git'
+            }
+        }
+
+        stage('Build Docker Image') {
+            steps {
+                sh "docker build -t ${FULL_IMAGE} -t ${LATEST_IMAGE} ."
+            }
+        }
+
+        stage('Push to Gitea Registry') {
+            steps {
+                withCredentials([usernamePassword(credentialsId: 'gitea-registry-cred', passwordVariable: 'GITEA_TOKEN', usernameVariable: 'GITEA_USER')]) {
+                    sh "echo \$GITEA_TOKEN | docker login ${REGISTRY} -u \$GITEA_USER --password-stdin"
+                    sh "docker push ${FULL_IMAGE}"
+                    sh "docker push ${LATEST_IMAGE}"
+                }
+            }
+        }
+
+        stage('Deploy to Prod LXC') {
+            steps {
+                sh 'ssh root@10.1.10.24 "mkdir -p /root/cointrader"'
+                sh 'scp docker-compose.yml root@10.1.10.24:/root/cointrader/'
+                sh '''
+                    ssh root@10.1.10.24 "cd /root/cointrader/ && \
+                    docker compose down && \
+                    docker compose pull && \
+                    docker compose up -d"
+                '''
+            }
+        }
+
+        stage('Cleanup') {
+            steps {
+                sh "docker rmi ${FULL_IMAGE} || true"
+                sh "docker rmi ${LATEST_IMAGE} || true"
+            }
+        }
+    }
+
+    // 파이프라인 결과에 따른 디스코드 알림
+    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

@@ -0,0 +1,187 @@
+# CoinTrader
+
+Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.
+
+---
+
+## 주요 기능
+
+- **복합 기술 지표 신호**: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 3개 이상 일치 시 진입
+- **ML 필터 (LightGBM)**: 기술 지표 신호를 한 번 더 검증하여 오진입 차단 (모델 없으면 자동 폴백)
+- **ATR 기반 손절/익절**: 변동성에 따라 동적으로 SL/TP 계산 (1.5× / 3.0× ATR)
+- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도 제어
+- **포지션 복구**: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원
+- **Discord 알림**: 진입·청산·오류 이벤트 실시간 웹훅 알림
+- **CI/CD**: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포
+
+---
+
+## 프로젝트 구조
+
+```
+cointrader/
+├── 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 로거 설정
+├── scripts/
+│   ├── fetch_history.py     # 과거 데이터 수집
+│   └── train_model.py       # ML 모델 수동 학습
+├── models/                  # 학습된 모델 저장 (.pkl)
+├── data/                    # 과거 데이터 캐시
+├── logs/                    # 로그 파일
+├── tests/                   # 테스트 코드
+├── Dockerfile
+├── docker-compose.yml
+├── Jenkinsfile
+└── requirements.txt
+```
+
+---
+
+## 빠른 시작
+
+### 1. 환경변수 설정
+
+```bash
+cp .env.example .env
+```
+
+`.env` 파일을 열어 아래 값을 채웁니다.
+
+```env
+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/...
+```
+
+### 2. 로컬 실행
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+### 3. Docker Compose로 실행
+
+```bash
+docker compose up -d
+```
+
+로그 확인:
+
+```bash
+docker compose logs -f cointrader
+```
+
+---
+
+## ML 모델 학습
+
+봇은 모델 파일(`models/lgbm_filter.pkl`)이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.
+
+```bash
+# 1. 과거 데이터 수집
+python scripts/fetch_history.py
+
+# 2. 모델 학습 (LightGBM, CPU)
+python scripts/train_model.py
+```
+
+학습된 모델은 `models/lgbm_filter.pkl`에 저장됩니다. 재학습이 필요하면 맥미니에서 위 스크립트를 다시 실행하고 모델 파일을 컨테이너에 배포합니다.
+
+### Apple Silicon GPU 가속 학습 (M1/M2/M3/M4)
+
+M 시리즈 맥에서는 MLX를 사용해 통합 GPU(Metal)로 학습할 수 있습니다.
+
+> **설치**: `mlx`는 Apple Silicon 전용이며 `requirements.txt`에 포함되지 않습니다.
+> 맥미니에서 별도 설치: `pip install mlx`
+
+```bash
+# MLX 별도 설치 (맥미니 전용)
+pip install mlx
+
+# 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에서 직접 제어할 수 없습니다.
+
+---
+
+## 매매 전략
+
+| 지표 | 롱 조건 | 숏 조건 | 가중치 |
+|------|---------|---------|--------|
+| RSI (14) | < 35 | > 65 | 1 |
+| MACD 크로스 | 골든크로스 | 데드크로스 | 2 |
+| 볼린저 밴드 | 하단 이탈 | 상단 돌파 | 1 |
+| EMA 정배열 (9/21/50) | 정배열 | 역배열 | 1 |
+| Stochastic RSI | < 20 + K>D | > 80 + K<D | 1 |
+| 거래량 | 20MA × 1.5 이상 시 신호 강화 | — | 보조 |
+
+**진입 조건**: 가중치 합계 ≥ 3 + (거래량 급증 또는 가중치 합계 ≥ 4)  
+**손절/익절**: ATR × 1.5 / ATR × 3.0 (리스크:리워드 = 1:2)  
+**ML 필터**: LightGBM 예측 확률 ≥ 0.60 이어야 최종 진입
+
+---
+
+## CI/CD
+
+`main` 브랜치에 푸시하면 Jenkins 파이프라인이 자동으로 실행됩니다.
+
+1. **Checkout** — 소스 체크아웃
+2. **Build Image** — Docker 이미지 빌드 (`:{BUILD_NUMBER}` + `:latest` 태그)
+3. **Push** — Gitea Container Registry(`10.1.10.28:3000`)에 푸시
+4. **Cleanup** — 로컬 이미지 정리
+
+배포 서버에서 최신 이미지를 반영하려면:
+
+```bash
+docker compose pull && docker compose up -d
+```
+
+---
+
+## 테스트
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## 환경변수 레퍼런스
+
+| 변수 | 기본값 | 설명 |
+|------|--------|------|
+| `BINANCE_API_KEY` | — | Binance API 키 |
+| `BINANCE_API_SECRET` | — | Binance API 시크릿 |
+| `SYMBOL` | `XRPUSDT` | 거래 심볼 |
+| `LEVERAGE` | `10` | 레버리지 배수 |
+| `RISK_PER_TRADE` | `0.02` | 트레이드당 리스크 비율 (2%) |
+| `DISCORD_WEBHOOK_URL` | — | Discord 웹훅 URL |
+
+---
+
+## 주의사항
+
+> **이 봇은 실제 자산을 거래합니다.** 운영 전 반드시 Binance Testnet에서 충분히 검증하세요.  
+> 과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다.
+> 성투기원합니다.

docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  cointrader:
+    image: 10.1.10.28:3000/gihyeon/cointrader:latest
+    container_name: cointrader
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - TZ=Asia/Seoul
+    volumes:
+      - ./logs:/app/logs
+      - ./models:/app/models
+      - ./data:/app/data
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "5"

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-btc-eth-correlation-features-design.md

@@ -0,0 +1,119 @@
+# BTC/ETH 상관관계 피처 추가 설계 문서
+
+**날짜:** 2026-03-01
+
+## 목적
+
+XRP 선물 ML 필터에 BTC/ETH 캔들 데이터를 추가 피처로 활용하여 모델 예측 정확도를 향상시킨다. XRP는 BTC/ETH의 움직임에 강하게 연동되는 경향이 있으므로, 이 컨텍스트를 ML 피처로 명시적으로 제공한다.
+
+---
+
+## 아키텍처 개요
+
+### 변경 전
+
+```
+KlineStream(XRPUSDT) → bot.process_candle() → Indicators → MLFilter(13개 피처)
+```
+
+### 변경 후
+
+```
+MultiSymbolStream(XRP+BTC+ETH, Combined WebSocket)
+    ↓ XRP 캔들 닫힐 때
+bot.process_candle(xrp_df, btc_df, eth_df)
+    ↓
+Indicators(XRP) → build_features(xrp_df, btc_df, eth_df, signal)
+    ↓
+MLFilter(13 + 8 = 21개 피처)
+```
+
+---
+
+## 추가 피처 8개
+
+| 피처 | 설명 |
+|---|---|
+| `btc_ret_1` | BTC 1캔들 수익률 |
+| `btc_ret_3` | BTC 3캔들 수익률 |
+| `btc_ret_5` | BTC 5캔들 수익률 |
+| `eth_ret_1` | ETH 1캔들 수익률 |
+| `eth_ret_3` | ETH 3캔들 수익률 |
+| `eth_ret_5` | ETH 5캔들 수익률 |
+| `xrp_btc_rs` | XRP ret_1 / BTC ret_1 (XRP 상대강도 vs BTC) |
+| `xrp_eth_rs` | XRP ret_1 / ETH ret_1 (XRP 상대강도 vs ETH) |
+
+기존 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`)는 그대로 유지.
+
+---
+
+## 변경 파일 목록
+
+| 파일 | 변경 유형 | 내용 |
+|---|---|---|
+| `src/data_stream.py` | 수정 | `KlineStream` → `MultiSymbolStream` (Combined WebSocket) |
+| `src/ml_features.py` | 수정 | `build_features(xrp_df, btc_df, eth_df, signal)` — 피처 21개로 확장 |
+| `scripts/fetch_history.py` | 수정 | BTC/ETH 동시 수집 후 타임스탬프 기준 병합 저장 |
+| `scripts/train_model.py` | 수정 | 병합된 데이터셋으로 21개 피처 학습 |
+| `src/bot.py` | 수정 | `MultiSymbolStream` 사용, `process_candle`에 btc_df/eth_df 전달 |
+| `src/dataset_builder.py` | 수정 | 레이블 생성 시 BTC/ETH 피처 포함 |
+
+---
+
+## 데이터 흐름
+
+### 실시간 (봇 운영)
+
+```
+Binance Combined WebSocket
+  ├── xrpusdt@kline_1m  →  xrp_buffer (deque 200)
+  ├── btcusdt@kline_1m  →  btc_buffer (deque 200)
+  └── ethusdt@kline_1m  →  eth_buffer (deque 200)
+         ↓ XRP 캔들 닫힐 때만 트리거
+  bot.process_candle(xrp_df, btc_df, eth_df)
+```
+
+### 학습 데이터 수집
+
+```
+fetch_history.py → XRPUSDT + BTCUSDT + ETHUSDT 각 90일 수집
+                 → 타임스탬프 기준 inner join 병합
+                 → data/combined_1m.parquet 저장
+train_model.py   → 21개 피처로 LightGBM 재학습
+                 → models/lgbm_filter.pkl 교체
+```
+
+---
+
+## 에러 처리
+
+| 상황 | 처리 방법 |
+|---|---|
+| BTC/ETH 버퍼 50개 미만 (봇 시작 직후) | btc/eth 피처 전부 0.0으로 채움, 거래는 정상 진행 |
+| Combined WebSocket 연결 끊김 | 예외 발생 → 상위에서 재연결 |
+| BTC/ETH ret 분모가 0 | `xrp_btc_rs`, `xrp_eth_rs` = 0.0으로 처리 |
+| 기존 모델(13개 피처) 파일이 남아있는 경우 | 피처 수 불일치 → MLFilter 폴백(신호 통과)으로 자동 처리 |
+
+---
+
+## 재학습 순서
+
+기존 `lgbm_filter.pkl`(13개 피처)은 새 데이터셋(21개 피처) 재학습 후 자동 교체된다.
+**봇 재시작 전 반드시 아래 순서로 실행:**
+
+```bash
+# 1. 3심볼 과거 데이터 수집
+python scripts/fetch_history.py --symbols XRPUSDT BTCUSDT ETHUSDT --days 90
+
+# 2. 21피처 모델 재학습
+python scripts/train_model.py
+
+# 3. 봇 재시작
+```
+
+---
+
+## 폴백 정책
+
+- BTC/ETH 버퍼가 비어있으면 해당 피처를 0.0으로 채워 기존 XRP 피처만으로 동작
+- 모델 파일이 없으면 ML 필터 전체를 건너뜀 (기존 정책 유지)

docs/plans/2026-03-01-btc-eth-correlation-features-plan.md

@@ -0,0 +1,815 @@
+# BTC/ETH 상관관계 피처 추가 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** BTC/ETH 캔들 데이터를 XRP ML 필터의 추가 피처(21개)로 활용해 모델 예측 정확도를 향상시킨다.
+
+**Architecture:** 바이낸스 Combined WebSocket으로 XRP/BTC/ETH 3개 심볼을 단일 연결로 수신하고, XRP 캔들이 닫힐 때 BTC/ETH 버퍼의 수익률·상대강도 8개 피처를 기존 13개 피처에 추가해 LightGBM에 전달한다. 학습 데이터도 3심볼을 타임스탬프 기준으로 병합해 동일한 21개 피처로 재학습한다.
+
+**Tech Stack:** Python 3.12, python-binance (AsyncClient + BinanceSocketManager), LightGBM, pandas, joblib
+
+---
+
+## Task 1: `MultiSymbolStream` — Combined WebSocket으로 3심볼 수신
+
+**Files:**
+- Modify: `src/data_stream.py`
+- Test: `tests/test_data_stream.py`
+
+### Step 1: 실패하는 테스트 작성
+
+`tests/test_data_stream.py` 파일에 아래 테스트를 추가한다.
+
+```python
+from src.data_stream import MultiSymbolStream
+
+def test_multi_symbol_stream_has_three_buffers():
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+    )
+    assert "xrpusdt" in stream.buffers
+    assert "btcusdt" in stream.buffers
+    assert "ethusdt" in stream.buffers
+
+def test_multi_symbol_stream_get_dataframe_returns_none_when_empty():
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+    )
+    assert stream.get_dataframe("XRPUSDT") is None
+
+def test_multi_symbol_stream_get_dataframe_returns_df_when_full():
+    import pandas as pd
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+        buffer_size=200,
+    )
+    candle = {
+        "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):
+        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
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_data_stream.py::test_multi_symbol_stream_has_three_buffers -v
+```
+
+Expected: `FAILED` — `MultiSymbolStream` not defined
+
+### Step 3: `MultiSymbolStream` 구현
+
+`src/data_stream.py` 파일에 기존 `KlineStream` 클래스 아래에 추가한다.
+
+```python
+class MultiSymbolStream:
+    """
+    바이낸스 Combined WebSocket으로 여러 심볼의 캔들을 단일 연결로 수신한다.
+    XRP 캔들이 닫힐 때 on_candle 콜백을 호출한다.
+    """
+
+    def __init__(
+        self,
+        symbols: list[str],
+        interval: str = "1m",
+        buffer_size: int = 200,
+        on_candle: Callable = None,
+    ):
+        self.symbols = [s.lower() for s in symbols]
+        self.interval = interval
+        self.on_candle = on_candle
+        self.buffers: dict[str, deque] = {
+            s: deque(maxlen=buffer_size) for s in self.symbols
+        }
+        # 첫 번째 심볼이 주 심볼 (XRP)
+        self.primary_symbol = self.symbols[0]
+
+    def parse_kline(self, msg: dict) -> dict:
+        k = msg["k"]
+        return {
+            "timestamp": k["t"],
+            "open":      float(k["o"]),
+            "high":      float(k["h"]),
+            "low":       float(k["l"]),
+            "close":     float(k["c"]),
+            "volume":    float(k["v"]),
+            "is_closed": k["x"],
+        }
+
+    def handle_message(self, msg: dict):
+        # Combined stream 메시지는 {"stream": "...", "data": {...}} 형태
+        if "stream" in msg:
+            data = msg["data"]
+        else:
+            data = msg
+
+        if data.get("e") != "kline":
+            return
+
+        symbol = data["s"].lower()
+        candle = self.parse_kline(data)
+
+        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)
+
+    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:
+            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):
+        """REST API로 모든 심볼의 과거 캔들을 버퍼에 미리 채운다."""
+        for symbol in self.symbols:
+            logger.info(f"{symbol.upper()} 과거 캔들 {limit}개 로드 중...")
+            klines = await client.futures_klines(
+                symbol=symbol.upper(),
+                interval=self.interval,
+                limit=limit,
+            )
+            for k in klines[:-1]:
+                self.buffers[symbol].append({
+                    "timestamp": k[0],
+                    "open":      float(k[1]),
+                    "high":      float(k[2]),
+                    "low":       float(k[3]),
+                    "close":     float(k[4]),
+                    "volume":    float(k[5]),
+                    "is_closed": True,
+                })
+            logger.info(f"{symbol.upper()} {len(self.buffers[symbol])}개 로드 완료")
+
+    async def start(self, api_key: str, api_secret: str):
+        client = await AsyncClient.create(
+            api_key=api_key,
+            api_secret=api_secret,
+        )
+        await self._preload_history(client)
+        bm = BinanceSocketManager(client)
+        streams = [
+            f"{s}@kline_{self.interval}" for s in self.symbols
+        ]
+        logger.info(f"Combined WebSocket 시작: {streams}")
+        try:
+            async with bm.futures_multiplex_socket(streams) as stream:
+                while True:
+                    msg = await stream.recv()
+                    self.handle_message(msg)
+        finally:
+            await client.close_connection()
+```
+
+### Step 4: 테스트 통과 확인
+
+```bash
+pytest tests/test_data_stream.py -v
+```
+
+Expected: 모든 테스트 PASS
+
+### Step 5: 커밋
+
+```bash
+git add src/data_stream.py tests/test_data_stream.py
+git commit -m "feat: add MultiSymbolStream for combined BTC/ETH/XRP WebSocket"
+```
+
+---
+
+## Task 2: `build_features` — BTC/ETH 피처 8개 추가
+
+**Files:**
+- Modify: `src/ml_features.py`
+- Test: `tests/test_ml_features.py`
+
+### Step 1: 실패하는 테스트 작성
+
+`tests/test_ml_features.py`에 아래 테스트를 추가한다.
+
+```python
+import pandas as pd
+import numpy as np
+from src.ml_features import build_features, FEATURE_COLS
+
+def _make_df(n=10, base_price=1.0):
+    """테스트용 더미 캔들 DataFrame 생성."""
+    closes = [base_price * (1 + i * 0.001) for i in range(n)]
+    return pd.DataFrame({
+        "close": closes, "high": [c * 1.01 for c in closes],
+        "low": [c * 0.99 for c in closes],
+        "volume": [1000.0] * n,
+        "rsi": [50.0] * n, "macd": [0.0] * n, "macd_signal": [0.0] * n,
+        "macd_hist": [0.0] * n, "bb_upper": [c * 1.02 for c in closes],
+        "bb_lower": [c * 0.98 for c in closes], "ema9": closes,
+        "ema21": closes, "ema50": closes, "atr": [0.01] * n,
+        "stoch_k": [50.0] * n, "stoch_d": [50.0] * n,
+        "vol_ma20": [1000.0] * n,
+    })
+
+def test_build_features_with_btc_eth_has_21_features():
+    xrp_df = _make_df(10, base_price=1.0)
+    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
+
+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
+
+def test_build_features_btc_ret_1_correct():
+    xrp_df = _make_df(10, base_price=1.0)
+    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)
+    btc_closes = btc_df["close"]
+    expected_btc_ret_1 = (btc_closes.iloc[-1] - btc_closes.iloc[-2]) / btc_closes.iloc[-2]
+    assert abs(features["btc_ret_1"] - expected_btc_ret_1) < 1e-6
+
+def test_build_features_rs_zero_when_btc_ret_zero():
+    xrp_df = _make_df(10, base_price=1.0)
+    # BTC 가격이 변하지 않으면 ret=0, RS=0
+    btc_df = _make_df(10, base_price=50000.0)
+    btc_df["close"] = 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 features["xrp_btc_rs"] == 0.0
+
+def test_feature_cols_has_21_items():
+    from src.ml_features import FEATURE_COLS
+    assert len(FEATURE_COLS) == 21
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_ml_features.py -v
+```
+
+Expected: 여러 테스트 FAIL
+
+### Step 3: `ml_features.py` 수정
+
+`src/ml_features.py` 전체를 아래로 교체한다.
+
+```python
+import pandas as pd
+import numpy as np
+
+FEATURE_COLS = [
+    "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_ret_1", "btc_ret_3", "btc_ret_5",
+    "eth_ret_1", "eth_ret_3", "eth_ret_5",
+    "xrp_btc_rs", "xrp_eth_rs",
+]
+
+
+def _calc_ret(closes: pd.Series, n: int) -> float:
+    """n캔들 전 대비 수익률. 데이터 부족 시 0.0."""
+    if len(closes) < n + 1:
+        return 0.0
+    prev = closes.iloc[-(n + 1)]
+    return (closes.iloc[-1] - prev) / prev if prev != 0 else 0.0
+
+
+def _calc_rs(xrp_ret: float, other_ret: float) -> float:
+    """상대강도 = xrp_ret / other_ret. 분모 0이면 0.0."""
+    if other_ret == 0.0:
+        return 0.0
+    return xrp_ret / other_ret
+
+
+def build_features(
+    df: pd.DataFrame,
+    signal: str,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+) -> pd.Series:
+    """
+    기술 지표가 계산된 DataFrame의 마지막 행에서 ML 피처를 추출한다.
+    btc_df, eth_df가 제공되면 21개 피처를, 없으면 13개 피처를 반환한다.
+    signal: "LONG" | "SHORT"
+    """
+    last = df.iloc[-1]
+    close = last["close"]
+
+    bb_upper = last.get("bb_upper", close)
+    bb_lower = last.get("bb_lower", close)
+    bb_range = bb_upper - bb_lower
+    bb_pct = (close - bb_lower) / bb_range if bb_range > 0 else 0.5
+
+    ema9  = last.get("ema9",  close)
+    ema21 = last.get("ema21", close)
+    ema50 = last.get("ema50", close)
+    if ema9 > ema21 > ema50:
+        ema_align = 1
+    elif ema9 < ema21 < ema50:
+        ema_align = -1
+    else:
+        ema_align = 0
+
+    atr = last.get("atr", 0)
+    atr_pct = atr / close if close > 0 else 0
+
+    vol_ma20 = last.get("vol_ma20", last.get("volume", 1))
+    vol_ratio = last["volume"] / vol_ma20 if vol_ma20 > 0 else 1.0
+
+    closes = df["close"]
+    ret_1 = _calc_ret(closes, 1)
+    ret_3 = _calc_ret(closes, 3)
+    ret_5 = _calc_ret(closes, 5)
+
+    prev = df.iloc[-2] if len(df) >= 2 else last
+    strength = 0
+    rsi = last.get("rsi", 50)
+    macd = last.get("macd", 0)
+    macd_sig = last.get("macd_signal", 0)
+    prev_macd = prev.get("macd", 0)
+    prev_macd_sig = prev.get("macd_signal", 0)
+    stoch_k = last.get("stoch_k", 50)
+    stoch_d = last.get("stoch_d", 50)
+
+    if signal == "LONG":
+        if rsi < 35: strength += 1
+        if prev_macd < prev_macd_sig and macd > macd_sig: strength += 2
+        if close < last.get("bb_lower", close): strength += 1
+        if ema_align == 1: strength += 1
+        if stoch_k < 20 and stoch_k > stoch_d: strength += 1
+    else:
+        if rsi > 65: strength += 1
+        if prev_macd > prev_macd_sig and macd < macd_sig: strength += 2
+        if close > last.get("bb_upper", close): strength += 1
+        if ema_align == -1: strength += 1
+        if stoch_k > 80 and stoch_k < stoch_d: strength += 1
+
+    base = {
+        "rsi":            float(rsi),
+        "macd_hist":      float(last.get("macd_hist", 0)),
+        "bb_pct":         float(bb_pct),
+        "ema_align":      float(ema_align),
+        "stoch_k":        float(stoch_k),
+        "stoch_d":        float(last.get("stoch_d", 50)),
+        "atr_pct":        float(atr_pct),
+        "vol_ratio":      float(vol_ratio),
+        "ret_1":          float(ret_1),
+        "ret_3":          float(ret_3),
+        "ret_5":          float(ret_5),
+        "signal_strength": float(strength),
+        "side":           1.0 if signal == "LONG" else 0.0,
+    }
+
+    if btc_df is not None and eth_df is not None:
+        btc_ret_1 = _calc_ret(btc_df["close"], 1)
+        btc_ret_3 = _calc_ret(btc_df["close"], 3)
+        btc_ret_5 = _calc_ret(btc_df["close"], 5)
+        eth_ret_1 = _calc_ret(eth_df["close"], 1)
+        eth_ret_3 = _calc_ret(eth_df["close"], 3)
+        eth_ret_5 = _calc_ret(eth_df["close"], 5)
+
+        base.update({
+            "btc_ret_1":  float(btc_ret_1),
+            "btc_ret_3":  float(btc_ret_3),
+            "btc_ret_5":  float(btc_ret_5),
+            "eth_ret_1":  float(eth_ret_1),
+            "eth_ret_3":  float(eth_ret_3),
+            "eth_ret_5":  float(eth_ret_5),
+            "xrp_btc_rs": float(_calc_rs(ret_1, btc_ret_1)),
+            "xrp_eth_rs": float(_calc_rs(ret_1, eth_ret_1)),
+        })
+
+    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: extend build_features to 21 features with BTC/ETH correlation"
+```
+
+---
+
+## Task 3: `dataset_builder.py` — BTC/ETH 피처 벡터화 추가
+
+**Files:**
+- Modify: `src/dataset_builder.py`
+- Test: `tests/test_dataset_builder.py`
+
+### Step 1: 실패하는 테스트 작성
+
+`tests/test_dataset_builder.py`에 아래 테스트를 추가한다.
+
+```python
+def test_generate_dataset_vectorized_with_btc_eth_has_21_feature_cols():
+    """BTC/ETH DataFrame을 전달하면 결과 컬럼이 21개 피처 + label이어야 한다."""
+    import pandas as pd
+    import numpy as np
+    from src.dataset_builder import generate_dataset_vectorized
+    from src.ml_features import FEATURE_COLS
+
+    np.random.seed(42)
+    n = 500
+    closes = np.cumprod(1 + np.random.randn(n) * 0.001) * 1.0
+    xrp_df = pd.DataFrame({
+        "open": closes * 0.999, "high": closes * 1.005,
+        "low": closes * 0.995, "close": closes,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+    btc_df = xrp_df.copy() * 50000
+    eth_df = xrp_df.copy() * 3000
+
+    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
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_dataset_builder.py::test_generate_dataset_vectorized_with_btc_eth_has_21_feature_cols -v
+```
+
+Expected: FAIL — `generate_dataset_vectorized()` does not accept btc_df/eth_df
+
+### Step 3: `dataset_builder.py` 수정
+
+`_calc_features_vectorized` 함수와 `generate_dataset_vectorized` 함수를 수정한다.
+
+`_calc_features_vectorized` 시그니처와 반환부에 BTC/ETH 피처 추가:
+
+```python
+def _calc_features_vectorized(
+    d: pd.DataFrame,
+    signal_arr: np.ndarray,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+) -> pd.DataFrame:
+    # ... 기존 코드 유지 ...
+
+    # BTC/ETH 피처 계산 (제공된 경우)
+    if btc_df is not None and eth_df is not None:
+        btc_ret_1 = btc_df["close"].pct_change(1).fillna(0).values
+        btc_ret_3 = btc_df["close"].pct_change(3).fillna(0).values
+        btc_ret_5 = btc_df["close"].pct_change(5).fillna(0).values
+        eth_ret_1 = eth_df["close"].pct_change(1).fillna(0).values
+        eth_ret_3 = eth_df["close"].pct_change(3).fillna(0).values
+        eth_ret_5 = eth_df["close"].pct_change(5).fillna(0).values
+
+        # 타임스탬프 정렬: XRP 인덱스 기준으로 BTC/ETH 값을 맞춤
+        # 길이가 다를 경우 짧은 쪽에 맞춰 앞을 0으로 패딩
+        def _align(arr: np.ndarray, target_len: int) -> np.ndarray:
+            if len(arr) >= target_len:
+                return arr[-target_len:]
+            return np.concatenate([np.zeros(target_len - len(arr)), arr])
+
+        n = len(d)
+        btc_r1 = _align(btc_ret_1, n).astype(np.float32)
+        btc_r3 = _align(btc_ret_3, n).astype(np.float32)
+        btc_r5 = _align(btc_ret_5, n).astype(np.float32)
+        eth_r1 = _align(eth_ret_1, n).astype(np.float32)
+        eth_r3 = _align(eth_ret_3, n).astype(np.float32)
+        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)
+
+        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,
+        }, index=d.index)
+        result = pd.concat([result, extra], axis=1)  # result는 기존 13개 피처 DataFrame
+
+    return result
+```
+
+`generate_dataset_vectorized` 시그니처 변경:
+
+```python
+def generate_dataset_vectorized(
+    df: pd.DataFrame,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+) -> pd.DataFrame:
+    # ...
+    feat_all = _calc_features_vectorized(d, signal_arr, btc_df=btc_df, eth_df=eth_df)
+    # ...
+    feat_final = feat_all.iloc[final_idx][FEATURE_COLS].copy()
+    # ...
+```
+
+### Step 4: 테스트 통과 확인
+
+```bash
+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 "feat: add BTC/ETH features to vectorized dataset builder"
+```
+
+---
+
+## Task 4: `fetch_history.py` — 3심볼 동시 수집 및 병합
+
+**Files:**
+- Modify: `scripts/fetch_history.py`
+
+### Step 1: 수정 내용
+
+`fetch_history.py`의 `main()` 함수를 수정해 `--symbols` 인자로 여러 심볼을 받고, 타임스탬프 기준 inner join으로 병합 후 저장한다.
+
+```python
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--symbols", nargs="+", default=["XRPUSDT"])
+    parser.add_argument("--interval", default="1m")
+    parser.add_argument("--days",     type=int, default=90)
+    parser.add_argument("--output",   default="data/xrpusdt_1m.parquet")
+    args = parser.parse_args()
+
+    if len(args.symbols) == 1:
+        # 단일 심볼: 기존 동작 유지
+        df = asyncio.run(fetch_klines(args.symbols[0], args.interval, args.days))
+        df.to_parquet(args.output)
+        print(f"저장 완료: {args.output} ({len(df)}행)")
+    else:
+        # 멀티 심볼: 각각 수집 후 병합
+        dfs = {}
+        for symbol in args.symbols:
+            print(f"{symbol} 수집 중...")
+            dfs[symbol] = asyncio.run(fetch_klines(symbol, args.interval, args.days))
+
+        # 타임스탬프 기준 inner join
+        primary = args.symbols[0]
+        merged = dfs[primary].copy()
+        for symbol in args.symbols[1:]:
+            suffix = "_" + symbol.lower().replace("usdt", "")
+            merged = merged.join(
+                dfs[symbol].add_suffix(suffix),
+                how="inner",
+            )
+
+        output = args.output.replace("xrpusdt", "combined")
+        merged.to_parquet(output)
+        print(f"병합 저장 완료: {output} ({len(merged)}행, {len(merged.columns)}컬럼)")
+```
+
+### Step 2: 동작 확인 (dry run — API 키 없이 구조만 확인)
+
+```bash
+python scripts/fetch_history.py --help
+```
+
+Expected: `--symbols` 인자가 출력됨
+
+### Step 3: 커밋
+
+```bash
+git add scripts/fetch_history.py
+git commit -m "feat: fetch_history supports multi-symbol collection and merge"
+```
+
+---
+
+## Task 5: `train_model.py` — 병합 데이터셋으로 21피처 학습
+
+**Files:**
+- Modify: `scripts/train_model.py`
+
+### Step 1: 수정 내용
+
+`train()` 함수가 병합된 parquet을 받아 BTC/ETH 컬럼을 분리해 `generate_dataset_vectorized`에 전달하도록 수정한다.
+
+```python
+def train(data_path: str):
+    print(f"데이터 로드: {data_path}")
+    df_raw = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df_raw)}, 컬럼: {list(df_raw.columns)}")
+
+    # 병합 데이터셋 여부 판별
+    btc_df = None
+    eth_df = None
+    base_cols = ["open", "high", "low", "close", "volume"]
+
+    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("데이터셋 생성 중...")
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df)
+
+    # ... 이하 기존 학습 코드 동일 (X = dataset[FEATURE_COLS] 부분에서 자동으로 21개 사용) ...
+```
+
+### Step 2: 커밋
+
+```bash
+git add scripts/train_model.py
+git commit -m "feat: train_model uses merged dataset with BTC/ETH features"
+```
+
+---
+
+## Task 6: `bot.py` — `MultiSymbolStream` 연결 및 피처 전달
+
+**Files:**
+- Modify: `src/bot.py`
+- Test: `tests/test_bot.py`
+
+### Step 1: 실패하는 테스트 작성
+
+`tests/test_bot.py`에 아래 테스트를 추가한다.
+
+```python
+def test_bot_uses_multi_symbol_stream():
+    from src.bot import TradingBot
+    from src.config import Config
+    from src.data_stream import MultiSymbolStream
+
+    config = Config()
+    bot = TradingBot(config)
+    assert isinstance(bot.stream, MultiSymbolStream)
+
+def test_bot_stream_has_btc_eth_buffers():
+    from src.bot import TradingBot
+    from src.config import Config
+
+    config = Config()
+    bot = TradingBot(config)
+    assert "btcusdt" in bot.stream.buffers
+    assert "ethusdt" in bot.stream.buffers
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+pytest tests/test_bot.py::test_bot_uses_multi_symbol_stream -v
+```
+
+Expected: FAIL
+
+### Step 3: `bot.py` 수정
+
+`__init__` 에서 `KlineStream` → `MultiSymbolStream`으로 교체하고, `process_candle`에 BTC/ETH df를 전달한다.
+
+```python
+# import 변경
+from src.data_stream import MultiSymbolStream  # KlineStream 대신
+
+class TradingBot:
+    def __init__(self, config: Config):
+        self.config = config
+        self.exchange = BinanceFuturesClient(config)
+        self.notifier = DiscordNotifier(config.discord_webhook_url)
+        self.risk = RiskManager(config)
+        self.ml_filter = MLFilter()
+        self.current_trade_side: str | None = None
+        self.stream = MultiSymbolStream(
+            symbols=[config.symbol, "BTCUSDT", "ETHUSDT"],
+            interval="1m",
+            on_candle=self._on_candle_closed,
+        )
+
+    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))
+
+    async def process_candle(
+        self,
+        df,
+        btc_df=None,
+        eth_df=None,
+    ):
+        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"
+
+        # ... 이하 기존 코드 동일 ...
+
+    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,
+        )
+```
+
+### 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: bot uses MultiSymbolStream and passes BTC/ETH df to build_features"
+```
+
+---
+
+## Task 7: 전체 테스트 통과 및 재학습 실행
+
+### Step 1: 전체 테스트 실행
+
+```bash
+pytest tests/ -v
+```
+
+Expected: 모든 테스트 PASS
+
+### Step 2: 3심볼 데이터 수집
+
+```bash
+python scripts/fetch_history.py \
+  --symbols XRPUSDT BTCUSDT ETHUSDT \
+  --days 90 \
+  --output data/xrpusdt_1m.parquet
+```
+
+Expected: `data/combined_1m.parquet` 생성
+
+### Step 3: 21피처 모델 재학습
+
+```bash
+python scripts/train_model.py --data data/combined_1m.parquet
+```
+
+Expected: `models/lgbm_filter.pkl` 교체, AUC 출력
+
+### Step 4: 최종 커밋
+
+```bash
+git add models/training_log.json
+git commit -m "chore: retrain model with 21 BTC/ETH correlation features"
+```
+
+---
+
+## 실행 순서 요약
+
+```
+Task 1 → Task 2 → Task 3 → Task 4 → Task 5 → Task 6 → Task 7
+(Stream)  (피처)  (데이터셋)  (수집)   (학습)    (봇)    (검증)
+```
+
+각 Task는 독립적으로 테스트 가능하며, Task 7 이전까지는 기존 봇이 정상 동작한다.

docs/plans/2026-03-01-dockerfile-and-docker-compose.md

@@ -0,0 +1,282 @@
+# Dockerfile & docker-compose.yml 작성 및 Gitea 업로드 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** cointrader 프로젝트에 Dockerfile과 docker-compose.yml을 추가하고, 변경사항을 커밋하여 Gitea(10.1.10.28:3000)에 push한다.
+
+**Architecture:** Python 3.11 slim 이미지 기반의 멀티스테이지 없는 단일 Dockerfile을 작성하고, docker-compose.yml로 환경변수(.env)를 주입하여 컨테이너를 실행한다. 로그 디렉토리는 볼륨으로 마운트하여 컨테이너 재시작 시에도 보존한다.
+
+**Tech Stack:** Docker, docker-compose v2, Python 3.11-slim, python-dotenv
+
+---
+
+## Task 1: Dockerfile 작성
+
+**Files:**
+- Create: `Dockerfile`
+
+**Step 1: Dockerfile 생성**
+
+`/Users/gihyeon/github/cointrader/Dockerfile` 파일을 아래 내용으로 생성한다:
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p logs
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+CMD ["python", "main.py"]
+```
+
+**Step 2: Dockerfile 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/Dockerfile
+```
+
+Expected: 위 내용이 그대로 출력됨
+
+**Step 3: Docker 빌드 테스트 (Docker가 설치된 경우)**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+docker build -t cointrader:test .
+```
+
+Expected: `Successfully built <image_id>` 또는 `Successfully tagged cointrader:test`
+
+> Docker가 설치되지 않은 환경이라면 이 단계는 건너뛴다.
+
+---
+
+## Task 2: docker-compose.yml 작성
+
+**Files:**
+- Create: `docker-compose.yml`
+
+**Step 1: docker-compose.yml 생성**
+
+`/Users/gihyeon/github/cointrader/docker-compose.yml` 파일을 아래 내용으로 생성한다:
+
+```yaml
+services:
+  cointrader:
+    build: .
+    container_name: cointrader
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - ./logs:/app/logs
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "5"
+```
+
+**Step 2: docker-compose.yml 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/docker-compose.yml
+```
+
+Expected: 위 내용이 그대로 출력됨
+
+**Step 3: docker-compose 문법 검증 (docker compose가 설치된 경우)**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+docker compose config
+```
+
+Expected: 파싱된 YAML 설정이 오류 없이 출력됨
+
+---
+
+## Task 3: .dockerignore 작성
+
+**Files:**
+- Create: `.dockerignore`
+
+**Step 1: .dockerignore 생성**
+
+`/Users/gihyeon/github/cointrader/.dockerignore` 파일을 아래 내용으로 생성한다:
+
+```
+.env
+.venv
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+logs/
+*.log
+.git
+docs/
+tests/
+```
+
+> `.env`를 반드시 포함시켜 빌드 컨텍스트에서 제외한다. 이미지에 API 키가 포함되는 것을 방지한다.
+
+**Step 2: .dockerignore 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/.dockerignore
+```
+
+Expected: 위 내용이 그대로 출력됨
+
+---
+
+## Task 4: git 커밋
+
+**Files:**
+- Modify: `Dockerfile` (신규)
+- Modify: `docker-compose.yml` (신규)
+- Modify: `.dockerignore` (신규)
+
+**Step 1: git 상태 확인**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+git status
+```
+
+Expected: `Dockerfile`, `docker-compose.yml`, `.dockerignore`가 untracked files로 표시됨
+
+**Step 2: 스테이징**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+git add Dockerfile docker-compose.yml .dockerignore
+```
+
+**Step 3: 스테이징 내용 검토 (`.env` 포함 여부 확인)**
+
+```bash
+git diff --cached --name-only
+```
+
+Expected:
+```
+.dockerignore
+Dockerfile
+docker-compose.yml
+```
+
+`.env`가 목록에 **없어야** 한다. 만약 있다면 즉시 `git reset HEAD .env` 실행 후 중단.
+
+**Step 4: 커밋**
+
+```bash
+git commit -m "chore: add Dockerfile, docker-compose.yml, .dockerignore"
+```
+
+Expected: `main` 브랜치에 새 커밋 생성
+
+**Step 5: 커밋 확인**
+
+```bash
+git log --oneline -3
+```
+
+Expected: 방금 만든 커밋이 최상단에 표시됨
+
+---
+
+## Task 5: Gitea push
+
+> 이 Task는 Gitea 원격 저장소가 이미 설정되어 있다고 가정한다.  
+> 아직 설정하지 않았다면 `docs/plans/2026-03-01-upload-to-gitea.md`의 Task 2~3을 먼저 완료한다.
+
+**Step 1: 현재 원격 저장소 확인**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+git remote -v
+```
+
+Expected:
+```
+origin  http://10.1.10.28:3000/<사용자명>/cointrader.git (fetch)
+origin  http://10.1.10.28:3000/<사용자명>/cointrader.git (push)
+```
+
+origin이 없다면 아래 명령으로 추가 (`<사용자명>` 교체 필요):
+```bash
+git remote add origin http://10.1.10.28:3000/<사용자명>/cointrader.git
+```
+
+**Step 2: push**
+
+```bash
+git push origin main
+```
+
+> Gitea 계정의 사용자명과 비밀번호(또는 액세스 토큰)를 입력하라는 프롬프트가 나타남
+
+Expected:
+```
+Enumerating objects: ...
+Writing objects: 100% ...
+```
+
+**Step 3: push 결과 확인**
+
+```bash
+git log --oneline origin/main -3
+```
+
+Expected: 로컬 커밋 히스토리와 동일하게 표시됨
+
+**Step 4: Gitea 웹 UI에서 파일 확인**
+
+브라우저에서 `http://10.1.10.28:3000/<사용자명>/cointrader` 접속 후 다음 파일이 있는지 확인:
+- `Dockerfile`
+- `docker-compose.yml`
+- `.dockerignore`
+
+---
+
+## 트러블슈팅
+
+| 문제 | 원인 | 해결 |
+|------|------|------|
+| `docker build` 시 `gcc` 설치 실패 | 네트워크 문제 | `apt-get` 단계를 제거하고 빌드 재시도 (pandas-ta가 gcc 없이 설치되는지 확인) |
+| `docker compose config` 오류 | YAML 들여쓰기 오류 | 탭 대신 스페이스 2칸 사용 여부 확인 |
+| push 시 `Authentication failed` | 잘못된 계정 정보 | Gitea 웹 UI 로그인 테스트 후 동일 계정 사용 |
+| push 시 `non-fast-forward` | 원격에 이미 다른 커밋 존재 | `git pull --rebase origin main` 후 재시도 |
+| 컨테이너 실행 시 `.env` 없음 오류 | `.env` 파일 미생성 | `.env.example`을 복사하여 `.env` 생성 후 값 입력 |
+
+---
+
+## 참고: 컨테이너 실행 방법
+
+```bash
+# .env 파일 준비
+cp .env.example .env
+# .env 파일에 실제 API 키와 Discord Webhook URL 입력
+
+# 빌드 및 백그라운드 실행
+docker compose up -d --build
+
+# 로그 확인
+docker compose logs -f
+
+# 중지
+docker compose down
+```

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-fix-pandas-ta-python312.md

@@ -0,0 +1,275 @@
+# pandas-ta Python 버전 호환성 수정 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Jenkins CI에서 `pandas-ta==0.4.71b0`이 Python 3.11에서 설치 실패하는 문제를 해결한다.
+
+**Architecture:** `pandas-ta==0.4.71b0`은 Python >=3.12를 요구하므로, Dockerfile의 베이스 이미지를 `python:3.11-slim`에서 `python:3.12-slim`으로 업그레이드한다. `requirements.txt`의 의존 패키지 버전도 Python 3.12와 호환되는 버전으로 정리한다.
+
+**Tech Stack:** Docker, Python 3.12-slim, pandas-ta 0.4.71b0, python-binance 1.0.19
+
+---
+
+## 문제 분석
+
+Jenkins 빌드 로그 오류:
+```
+ERROR: Ignored the following versions that require a different python version:
+  0.4.67b0 Requires-Python >=3.12; 0.4.71b0 Requires-Python >=3.12
+ERROR: Could not find a version that satisfies the requirement pandas-ta==0.4.71b0
+```
+
+**원인:** `requirements.txt`에 `pandas-ta==0.4.71b0`이 명시되어 있으나, Dockerfile 베이스 이미지가 `python:3.11-slim`이라 Python 3.12 이상을 요구하는 `pandas-ta`를 설치할 수 없다.
+
+**해결 방향:** Dockerfile 베이스 이미지를 `python:3.12-slim`으로 변경한다.
+
+---
+
+## Task 1: Dockerfile 베이스 이미지 업그레이드
+
+**Files:**
+- Modify: `Dockerfile:1`
+
+**Step 1: Dockerfile 수정**
+
+`Dockerfile` 1번째 줄을 다음과 같이 변경한다:
+
+변경 전:
+```dockerfile
+FROM python:3.11-slim
+```
+
+변경 후:
+```dockerfile
+FROM python:3.12-slim
+```
+
+**Step 2: 변경 내용 확인**
+
+```bash
+head -1 /Users/gihyeon/github/cointrader/Dockerfile
+```
+
+Expected:
+```
+FROM python:3.12-slim
+```
+
+---
+
+## Task 2: requirements.txt 의존성 호환성 검토 및 수정
+
+**Files:**
+- Modify: `requirements.txt`
+
+**Step 1: 현재 requirements.txt 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/requirements.txt
+```
+
+Expected (현재 내용):
+```
+python-binance==1.0.19
+pandas>=2.2.0
+pandas-ta==0.4.71b0
+python-dotenv==1.0.0
+httpx>=0.27.0
+pytest>=8.1.0
+pytest-asyncio>=0.24.0
+aiohttp==3.9.3
+websockets==12.0
+loguru==0.7.2
+```
+
+**Step 2: pandas-ta 0.4.71b0의 의존성 확인**
+
+PyPI 정보에 따르면 `pandas-ta==0.4.71b0`은 다음을 요구한다:
+- `numba==0.61.2`
+- `numpy>=2.2.6`
+- `pandas>=2.3.2`
+
+`requirements.txt`의 `pandas>=2.2.0`은 `pandas>=2.3.2`를 만족하므로 문제없다.  
+단, `numba`가 명시되어 있지 않아 pandas-ta 설치 시 자동으로 설치된다.
+
+**Step 3: requirements.txt 수정 (pandas 최소 버전 상향)**
+
+`pandas>=2.2.0`을 `pandas>=2.3.2`로 변경하여 pandas-ta의 요구사항을 명시적으로 반영한다:
+
+변경 전:
+```
+pandas>=2.2.0
+```
+
+변경 후:
+```
+pandas>=2.3.2
+```
+
+**Step 4: 변경 내용 확인**
+
+```bash
+grep "pandas" /Users/gihyeon/github/cointrader/requirements.txt
+```
+
+Expected:
+```
+pandas>=2.3.2
+pandas-ta==0.4.71b0
+```
+
+---
+
+## Task 3: 로컬 Docker 빌드 테스트
+
+> Docker가 설치된 환경에서만 실행한다.
+
+**Step 1: Docker 빌드**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+docker build -t cointrader:test .
+```
+
+Expected: 빌드 성공 (`Successfully tagged cointrader:test` 또는 `#N DONE`)
+
+**Step 2: 빌드된 이미지의 Python 버전 확인**
+
+```bash
+docker run --rm cointrader:test python --version
+```
+
+Expected:
+```
+Python 3.12.x
+```
+
+**Step 3: pandas-ta import 확인**
+
+```bash
+docker run --rm cointrader:test python -c "import pandas_ta; print(pandas_ta.__version__)"
+```
+
+Expected:
+```
+0.4.71b0
+```
+
+**Step 4: 테스트 이미지 정리**
+
+```bash
+docker rmi cointrader:test
+```
+
+---
+
+## Task 4: git 커밋 및 Gitea push
+
+**Files:**
+- Modify: `Dockerfile`
+- Modify: `requirements.txt`
+
+**Step 1: git 상태 확인**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+git status
+```
+
+Expected:
+```
+modified:   Dockerfile
+modified:   requirements.txt
+```
+
+**Step 2: 변경 내용 검토**
+
+```bash
+git diff Dockerfile requirements.txt
+```
+
+Expected:
+- `Dockerfile`: `-FROM python:3.11-slim` → `+FROM python:3.12-slim`
+- `requirements.txt`: `-pandas>=2.2.0` → `+pandas>=2.3.2`
+
+**Step 3: 스테이징**
+
+```bash
+git add Dockerfile requirements.txt
+```
+
+**Step 4: 커밋**
+
+```bash
+git commit -m "fix: upgrade to Python 3.12 to support pandas-ta>=0.4.67b0"
+```
+
+Expected: 커밋 성공
+
+**Step 5: Gitea push**
+
+```bash
+git push origin main
+```
+
+Expected: push 성공 후 Jenkins가 자동으로 새 빌드를 트리거함
+
+**Step 6: 커밋 확인**
+
+```bash
+git log --oneline -3
+```
+
+Expected: 방금 만든 커밋이 최상단에 표시됨
+
+---
+
+## Task 5: Jenkins 빌드 재실행 및 결과 확인
+
+**Step 1: Jenkins 빌드 트리거**
+
+Gitea push 후 Jenkins Webhook이 설정되어 있다면 자동으로 빌드가 트리거된다.  
+수동으로 트리거하려면 Jenkins 웹 UI에서 `cointrader` 파이프라인 → `Build Now` 클릭.
+
+**Step 2: 빌드 로그에서 성공 확인**
+
+Jenkins 빌드 로그에서 다음 내용이 나타나야 한다:
+
+```
+#9 [5/7] RUN pip install --no-cache-dir -r requirements.txt
+...
+Successfully installed pandas-ta-0.4.71b0 ...
+#9 DONE xx.xs
+```
+
+오류 없이 `[Build Docker Image]` 스테이지가 완료되어야 한다.
+
+**Step 3: 전체 파이프라인 성공 확인**
+
+Jenkins 빌드 결과가 `SUCCESS`로 표시되어야 한다:
+```
+Finished: SUCCESS
+```
+
+---
+
+## 트러블슈팅
+
+| 문제 | 원인 | 해결 |
+|------|------|------|
+| `python-binance==1.0.19` 설치 실패 | Python 3.12 비호환 | `python-binance>=1.0.19`로 변경하거나 최신 버전 확인 |
+| `aiohttp==3.9.3` 설치 실패 | Python 3.12 비호환 | `aiohttp>=3.9.3`으로 완화하거나 최신 버전으로 업그레이드 |
+| `numba` 설치 시간 초과 | numba 컴파일 시간 | 빌드 타임아웃 설정 증가 또는 `--timeout=300` 추가 |
+| Jenkins Webhook 미동작 | Gitea Webhook 미설정 | Gitea 저장소 설정 → Webhooks → Jenkins URL 추가 |
+
+---
+
+## 참고: Python 3.12 호환성 체크리스트
+
+Python 3.11 → 3.12 주요 변경사항 중 이 프로젝트에 영향 가능한 항목:
+
+- `asyncio` 동작 변경: `asyncio.get_event_loop()` deprecated → `asyncio.get_running_loop()` 권장
+- `typing` 모듈 일부 변경: `Union[X, Y]` → `X | Y` 문법 지원 강화
+- `datetime.utcnow()` deprecated → `datetime.now(timezone.utc)` 권장
+
+현재 코드베이스(`src/`, `tests/`)에서 위 패턴 사용 여부를 확인하고 필요 시 수정한다.

docs/plans/2026-03-01-jenkins-gitea-registry-cicd.md

@@ -0,0 +1,405 @@
+# Jenkins + Gitea 이미지 레지스트리 CI/CD 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Jenkins가 Gitea(10.1.10.28:3000)의 코드 변경을 감지하면 Docker 이미지를 빌드하여 Gitea Container Registry(10.1.10.28:5000 또는 Gitea 내장 패키지 레지스트리)에 push하고, docker-compose.yml이 해당 이미지를 pull해서 실행하도록 전체 CI/CD 파이프라인을 구성한다.
+
+**Architecture:**
+- Jenkins는 Gitea webhook을 통해 main 브랜치 push 이벤트를 수신한다.
+- Jenkinsfile(파이프라인 스크립트)이 프로젝트 루트에 위치하며, `docker build → docker push → (선택) 원격 배포` 단계를 수행한다.
+- Gitea의 내장 Container Registry(Packages)를 이미지 저장소로 사용한다. 이미지 이름 형식: `10.1.10.28:3000/gihyeon/cointrader:<tag>`
+- docker-compose.yml은 `build: .` 대신 레지스트리 이미지를 직접 참조하도록 수정한다.
+
+**Tech Stack:** Jenkins, Gitea Container Registry, Docker, docker-compose v2, Jenkinsfile(Declarative Pipeline)
+
+---
+
+## 사전 확인 사항
+
+- Gitea 서버: `http://10.1.10.28:3000`
+- Gitea 저장소: `http://10.1.10.28:3000/gihyeon/cointrader.git`
+- Gitea Container Registry 주소: `10.1.10.28:3000` (HTTP 사용 시 Docker insecure-registries 설정 필요)
+- Jenkins 서버 주소: 별도 확인 필요 (아래 Task 1에서 확인)
+- 현재 Dockerfile: `FROM python:3.12-slim` 기반, `/app`에서 `python main.py` 실행
+
+---
+
+## Task 1: 환경 사전 점검
+
+**Files:**
+- 확인: `Dockerfile`
+- 확인: `docker-compose.yml`
+
+**Step 1: Gitea Container Registry(Packages) 활성화 확인**
+
+브라우저에서 `http://10.1.10.28:3000/gihyeon/cointrader/packages` 접속.
+- 패키지 탭이 보이면 활성화된 것.
+- 안 보이면 Gitea 관리자 패널 → `Site Administration` → `Configuration` → `Enable Packages` 체크 필요.
+
+**Step 2: Gitea Access Token 생성 (Jenkins용)**
+
+`http://10.1.10.28:3000/user/settings/applications` 접속:
+- Token Name: `jenkins-cointrader`
+- 권한: `read:packages`, `write:packages` (또는 전체 권한)
+- `Generate Token` 클릭 후 **토큰 값을 반드시 복사** (다시 볼 수 없음)
+
+**Step 3: Docker insecure-registries 설정 (HTTP 레지스트리 사용 시)**
+
+Jenkins가 실행되는 서버(또는 로컬 Mac)에서:
+
+```bash
+# /etc/docker/daemon.json 또는 Docker Desktop의 경우 Settings > Docker Engine
+cat /etc/docker/daemon.json
+```
+
+아래 내용이 없으면 추가:
+```json
+{
+  "insecure-registries": ["10.1.10.28:3000"]
+}
+```
+
+Docker Desktop 사용 시: `Settings` → `Docker Engine` → JSON에 위 내용 병합 → `Apply & Restart`
+
+**Step 4: Docker login 테스트**
+
+```bash
+docker login 10.1.10.28:3000 -u gihyeon -p <위에서_생성한_토큰>
+```
+
+Expected:
+```
+Login Succeeded
+```
+
+---
+
+## Task 2: Jenkinsfile 작성
+
+**Files:**
+- Create: `Jenkinsfile`
+
+**Step 1: Jenkinsfile 생성**
+
+`/Users/gihyeon/github/cointrader/Jenkinsfile` 파일을 아래 내용으로 생성:
+
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        REGISTRY      = '10.1.10.28:3000'
+        IMAGE_NAME    = 'gihyeon/cointrader'
+        IMAGE_TAG     = "${env.BUILD_NUMBER}"
+        FULL_IMAGE    = "${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"
+        LATEST_IMAGE  = "${REGISTRY}/${IMAGE_NAME}:latest"
+        GITEA_CREDS   = credentials('gitea-registry-credentials')
+    }
+
+    stages {
+        stage('Checkout') {
+            steps {
+                checkout scm
+            }
+        }
+
+        stage('Build Image') {
+            steps {
+                sh "docker build -t ${FULL_IMAGE} -t ${LATEST_IMAGE} ."
+            }
+        }
+
+        stage('Push to Gitea Registry') {
+            steps {
+                sh """
+                    echo ${GITEA_CREDS_PSW} | docker login ${REGISTRY} -u ${GITEA_CREDS_USR} --password-stdin
+                    docker push ${FULL_IMAGE}
+                    docker push ${LATEST_IMAGE}
+                """
+            }
+        }
+
+        stage('Cleanup') {
+            steps {
+                sh """
+                    docker rmi ${FULL_IMAGE} || true
+                    docker rmi ${LATEST_IMAGE} || true
+                """
+            }
+        }
+    }
+
+    post {
+        success {
+            echo "Build #${env.BUILD_NUMBER} pushed: ${FULL_IMAGE}"
+        }
+        failure {
+            echo "Build #${env.BUILD_NUMBER} FAILED"
+        }
+    }
+}
+```
+
+> **참고:**
+> - `GITEA_CREDS`는 Jenkins Credentials에 등록할 Username+Password 자격증명 ID다 (Task 3에서 등록).
+> - `IMAGE_TAG`는 Jenkins 빌드 번호를 사용한다. 태그 전략을 git 커밋 해시로 바꾸려면 `"${env.GIT_COMMIT[0..7]}"` 사용.
+> - `Cleanup` 스테이지는 Jenkins 서버 디스크 절약을 위해 빌드 후 로컬 이미지를 삭제한다.
+
+**Step 2: Jenkinsfile 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/Jenkinsfile
+```
+
+Expected: 위 내용이 출력됨
+
+---
+
+## Task 3: Jenkins에 Gitea Credentials 등록
+
+**Step 1: Jenkins 웹 UI 접속**
+
+`http://<jenkins-서버-주소>:8080` 접속 (Jenkins 서버 주소 확인 필요)
+
+**Step 2: Credentials 등록**
+
+`Jenkins` → `Manage Jenkins` → `Credentials` → `System` → `Global credentials` → `Add Credentials`:
+
+| 항목 | 값 |
+|------|----|
+| Kind | Username with password |
+| Scope | Global |
+| Username | `gihyeon` |
+| Password | Task 1 Step 2에서 생성한 Gitea Access Token |
+| ID | `gitea-registry-credentials` |
+| Description | Gitea Container Registry for cointrader |
+
+`Create` 클릭
+
+**Step 3: 등록 확인**
+
+Credentials 목록에 `gitea-registry-credentials`가 표시되는지 확인
+
+---
+
+## Task 4: Jenkins Pipeline Job 생성
+
+**Step 1: 새 Pipeline Job 생성**
+
+`Jenkins` → `New Item`:
+- Item name: `cointrader`
+- Type: `Pipeline`
+- `OK` 클릭
+
+**Step 2: Pipeline 설정**
+
+`Pipeline` 섹션에서:
+- Definition: `Pipeline script from SCM`
+- SCM: `Git`
+- Repository URL: `http://10.1.10.28:3000/gihyeon/cointrader.git`
+- Credentials: (Gitea 저장소 접근용 credentials 추가, 없으면 Task 3과 동일하게 추가)
+- Branch Specifier: `*/main`
+- Script Path: `Jenkinsfile`
+
+`Save` 클릭
+
+**Step 3: 수동 빌드 테스트**
+
+`Build Now` 클릭 → Console Output 확인
+
+Expected:
+```
+[Pipeline] stage: Build Image
+Successfully built ...
+[Pipeline] stage: Push to Gitea Registry
+Login Succeeded
+The push refers to repository [10.1.10.28:3000/gihyeon/cointrader]
+...
+latest: digest: sha256:... size: ...
+[Pipeline] stage: Cleanup
+Finished: SUCCESS
+```
+
+---
+
+## Task 5: Gitea Webhook 설정 (자동 트리거)
+
+**Step 1: Gitea 저장소 Webhook 추가**
+
+`http://10.1.10.28:3000/gihyeon/cointrader/settings/hooks` 접속:
+- `Add Webhook` → `Gitea`
+- Target URL: `http://<jenkins-서버-주소>:8080/gitea-webhook/post`
+  - Jenkins Gitea Plugin 사용 시 위 URL 형식
+  - 일반 Generic Webhook 사용 시: `http://<jenkins-서버-주소>:8080/job/cointrader/build?token=<토큰>`
+- Trigger: `Push Events`
+- Branch filter: `main`
+- `Add Webhook` 클릭
+
+**Step 2: Jenkins에 Gitea Plugin 설치 (미설치 시)**
+
+`Manage Jenkins` → `Plugins` → `Available plugins` → `Gitea` 검색 → 설치 후 재시작
+
+**Step 3: Webhook 테스트**
+
+Gitea Webhook 설정 페이지에서 `Test Delivery` 클릭
+
+Expected: Jenkins에서 새 빌드가 자동으로 시작됨
+
+---
+
+## Task 6: docker-compose.yml 수정
+
+**Files:**
+- Modify: `docker-compose.yml`
+
+현재 `docker-compose.yml`은 `build: .`으로 로컬 빌드를 사용한다. 이를 레지스트리 이미지를 pull해서 실행하도록 변경한다.
+
+**Step 1: docker-compose.yml 수정**
+
+`/Users/gihyeon/github/cointrader/docker-compose.yml`을 아래 내용으로 교체:
+
+```yaml
+services:
+  cointrader:
+    image: 10.1.10.28:3000/gihyeon/cointrader:latest
+    container_name: cointrader
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - ./logs:/app/logs
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "5"
+```
+
+> **변경 사항:**
+> - `build: .` → `image: 10.1.10.28:3000/gihyeon/cointrader:latest`
+> - 이제 `docker compose up -d`를 실행하면 로컬 빌드 없이 레지스트리에서 이미지를 pull한다.
+> - 배포 서버에서 최신 이미지로 업데이트하려면: `docker compose pull && docker compose up -d`
+
+**Step 2: 변경 내용 확인**
+
+```bash
+cat /Users/gihyeon/github/cointrader/docker-compose.yml
+```
+
+Expected: `image:` 필드가 레지스트리 주소를 가리킴
+
+**Step 3: (선택) 로컬 개발용 docker-compose.override.yml 생성**
+
+로컬에서 소스 코드를 직접 빌드해서 테스트하고 싶을 때를 위한 override 파일:
+
+```yaml
+# docker-compose.override.yml (로컬 개발 전용, git에 포함하지 않아도 됨)
+services:
+  cointrader:
+    build: .
+    image: cointrader:local
+```
+
+이 파일이 있으면 `docker compose up -d`가 자동으로 `build: .`을 사용한다. 프로덕션 서버에는 이 파일을 두지 않는다.
+
+---
+
+## Task 7: 변경사항 커밋 및 Push
+
+**Step 1: 변경 파일 확인**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+git status
+```
+
+Expected: `Jenkinsfile`(new), `docker-compose.yml`(modified)이 표시됨
+
+**Step 2: 스테이징**
+
+```bash
+git add Jenkinsfile docker-compose.yml
+```
+
+**Step 3: `.env` 미포함 확인**
+
+```bash
+git diff --cached --name-only
+```
+
+Expected: `Jenkinsfile`, `docker-compose.yml` 두 파일만 표시됨
+
+**Step 4: 커밋**
+
+```bash
+git commit -m "ci: Jenkins pipeline + Gitea registry CI/CD 설정"
+```
+
+Expected: `main` 브랜치에 새 커밋 생성
+
+**Step 5: Gitea에 Push**
+
+```bash
+git push origin main
+```
+
+Expected: Push 성공 + (Webhook 설정 완료 시) Jenkins 빌드 자동 시작
+
+---
+
+## Task 8: 엔드-투-엔드 검증
+
+**Step 1: 코드 변경 후 push 테스트**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+# 아무 파일이나 사소하게 변경 (예: README 한 줄 추가)
+echo "# CI/CD test" >> README.md
+git add README.md
+git commit -m "test: CI/CD 파이프라인 검증용 더미 커밋"
+git push origin main
+```
+
+**Step 2: Jenkins 빌드 자동 시작 확인**
+
+Jenkins UI에서 `cointrader` 잡의 빌드가 자동으로 시작되는지 확인 (30초 이내)
+
+**Step 3: Gitea 레지스트리에 이미지 push 확인**
+
+`http://10.1.10.28:3000/gihyeon/cointrader/packages` 접속 → `cointrader` 컨테이너 패키지에 새 태그가 생성되었는지 확인
+
+**Step 4: 이미지 pull 테스트**
+
+```bash
+docker pull 10.1.10.28:3000/gihyeon/cointrader:latest
+```
+
+Expected:
+```
+latest: Pulling from gihyeon/cointrader
+...
+Status: Downloaded newer image for 10.1.10.28:3000/gihyeon/cointrader:latest
+```
+
+**Step 5: docker compose로 실행 테스트**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+docker compose up -d
+docker compose logs -f --tail=20
+```
+
+Expected: 컨테이너가 정상 시작되고 로그가 출력됨
+
+---
+
+## 트러블슈팅
+
+| 문제 | 원인 | 해결 |
+|------|------|------|
+| `http: server gave HTTP response to HTTPS client` | Docker가 HTTPS로 레지스트리 접근 시도 | `daemon.json`에 `insecure-registries` 추가 후 Docker 재시작 |
+| `unauthorized: authentication required` | Credentials 미등록 또는 토큰 만료 | Task 1 Step 2에서 새 토큰 발급 후 Jenkins Credentials 업데이트 |
+| `connection refused` to Jenkins | Jenkins URL 오타 또는 방화벽 | Jenkins 서버 주소 재확인 |
+| Webhook이 Jenkins를 트리거하지 않음 | Jenkins URL이 Gitea 서버에서 접근 불가 | Jenkins가 Gitea 서버와 같은 네트워크에 있는지 확인, 방화벽 8080 포트 오픈 |
+| `image not found` on docker compose pull | 이미지가 아직 push되지 않음 | Jenkins 빌드 완료 후 재시도 |
+| Jenkins에서 `docker: command not found` | Jenkins 에이전트에 Docker 미설치 | Jenkins 서버에 Docker 설치 또는 Docker-in-Docker 설정 |

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-m4-accelerated-training.md

@@ -0,0 +1,635 @@
+# M4 Mac Mini 가속 학습 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** M4 맥미니의 GPU(Metal/MPS)를 활용해 모델 학습 속도를 높이고, Neural Engine 활용 가능 여부를 검토한다.
+
+**Architecture:** 현재 LightGBM CPU 학습 파이프라인을 유지하면서, 데이터셋 생성 단계(병렬 CPU 연산)와 LightGBM 학습 단계를 각각 최적화한다. LightGBM은 Apple Silicon GPU를 공식 지원하지 않으므로, (1) MetalGBM 실험적 대체, (2) PyTorch MPS 기반 신경망 필터 추가, (3) 현재 CPU 파이프라인 최적화 세 가지 경로를 단계별로 시도한다.
+
+**Tech Stack:** Python 3.13, LightGBM 4.6, MetalGBM(실험), PyTorch(MPS), Apple MLX, scikit-learn 1.8
+
+---
+
+## 배경 및 제약사항 분석
+
+### M4 맥미니 하드웨어 구조
+- **CPU**: 10코어 (P코어 4 + E코어 6)
+- **GPU**: 10코어 통합 GPU (Metal 지원)
+- **Neural Engine (NPU)**: 38 TOPS — 행렬 연산 특화, Apple 전용 API로만 접근 가능
+- **통합 메모리**: CPU/GPU/NPU가 동일 메모리 공유 → 데이터 복사 오버헤드 없음
+
+### 현재 학습 파이프라인 병목 분석
+```
+[1단계] 데이터셋 생성: multiprocessing.Pool → CPU 병렬
+  - _process_index(): 각 캔들에서 Indicators 계산 + 피처 추출
+  - 약 129,000개 인덱스 처리 (90일 × 1440분)
+  - 현재 병목: Python GIL 우회는 됐지만 pickle 직렬화 오버헤드 큼
+
+[2단계] LightGBM 학습: CPU 전용
+  - n_estimators=300, 샘플 수 ~수천 개
+  - 실제 학습 시간은 짧음 (수초~수십초)
+  - GPU 가속 효과 미미할 가능성 높음
+```
+
+### 각 가속 방법의 현실적 평가
+
+| 방법 | 효과 | 난이도 | 권장 여부 |
+|------|------|--------|-----------|
+| Neural Engine 직접 사용 | ❌ 불가 (Apple 내부 전용) | - | 불가 |
+| LightGBM GPU (Metal) | ❌ 공식 미지원 | 높음 | 비권장 |
+| MetalGBM | ⚠️ 실험적 (2025.11 신생) | 중간 | 실험 가능 |
+| PyTorch MPS 신경망 | ✅ 가능, 소규모 모델은 CPU보다 느릴 수 있음 | 중간 | 조건부 권장 |
+| Apple MLX 신경망 | ✅ Apple Silicon 최적화 | 중간 | 권장 |
+| CPU 파이프라인 최적화 | ✅ 즉각 효과 | 낮음 | **최우선 권장** |
+
+> **핵심 결론**: 현재 학습 샘플 수(수천 개)와 피처 수(13개)에서는 LightGBM 자체 학습 시간이 매우 짧다. 실제 병목은 **데이터셋 생성(1단계)** 이며, 이를 먼저 최적화하는 것이 가장 효과적이다. GPU/NPU 가속은 신경망 모델로 전환 시 의미가 있다.
+
+---
+
+## Task 1: 현재 학습 시간 프로파일링
+
+**Files:**
+- Create: `scripts/profile_training.py`
+
+**Step 1: 프로파일링 스크립트 작성**
+
+```python
+"""
+학습 파이프라인 각 단계의 소요 시간을 측정한다.
+사용법: python scripts/profile_training.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import time
+import argparse
+import pandas as pd
+from scripts.train_model import generate_dataset, _cgroup_cpu_count
+
+def profile(data_path: str):
+    print(f"데이터 로드: {data_path}")
+    df = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df)}")
+
+    workers = max(1, _cgroup_cpu_count() - 1)
+    print(f"사용 코어: {workers}")
+
+    t0 = time.perf_counter()
+    dataset = generate_dataset(df)
+    t1 = time.perf_counter()
+    print(f"\n[결과] 데이터셋 생성: {t1-t0:.1f}초, 샘플 {len(dataset)}개")
+
+    import lightgbm as lgb
+    from sklearn.model_selection import train_test_split
+    from src.ml_features import FEATURE_COLS
+    X = dataset[FEATURE_COLS]
+    y = dataset["label"]
+    X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.2, random_state=42)
+
+    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,
+    )
+    t2 = time.perf_counter()
+    model.fit(X_train, y_train)
+    t3 = time.perf_counter()
+    print(f"[결과] LightGBM 학습: {t3-t2:.1f}초")
+    print(f"[결과] 전체: {t3-t0:.1f}초")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    args = parser.parse_args()
+    profile(args.data)
+```
+
+**Step 2: 프로파일링 실행**
+
+```bash
+python scripts/profile_training.py --data data/xrpusdt_1m.parquet
+```
+
+예상 출력:
+```
+[결과] 데이터셋 생성: XX.X초, 샘플 XXXX개
+[결과] LightGBM 학습: X.X초
+[결과] 전체: XX.X초
+```
+
+→ 데이터셋 생성이 전체의 90% 이상을 차지하면 Task 2로 진행
+→ LightGBM 학습이 병목이면 Task 4(MetalGBM)로 진행
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/profile_training.py
+git commit -m "feat: add training pipeline profiler"
+```
+
+---
+
+## Task 2: 데이터셋 생성 최적화 (CPU, 즉각 효과)
+
+현재 `multiprocessing.Pool`의 pickle 직렬화 오버헤드를 줄이고, numpy 벡터화로 대체한다.
+
+**Files:**
+- Modify: `scripts/train_model.py`
+- Create: `tests/test_train_model_perf.py`
+
+**Step 1: 실패 테스트 작성**
+
+```python
+# tests/test_train_model_perf.py
+import time
+import pandas as pd
+import pytest
+from scripts.train_model import generate_dataset
+
+@pytest.fixture
+def sample_df():
+    return pd.read_parquet("data/xrpusdt_1m.parquet").iloc[:5000]
+
+def test_dataset_generation_speed(sample_df):
+    """5000개 캔들에서 데이터셋 생성이 30초 이내여야 한다."""
+    t0 = time.perf_counter()
+    dataset = generate_dataset(sample_df)
+    elapsed = time.perf_counter() - t0
+    assert elapsed < 30.0, f"너무 느림: {elapsed:.1f}초"
+    assert len(dataset) > 0
+```
+
+**Step 2: 테스트 실행 (실패 확인)**
+
+```bash
+pytest tests/test_train_model_perf.py -v
+```
+
+**Step 3: `train_model.py`에 `n_jobs` 자동 감지 개선 및 chunksize 튜닝**
+
+`scripts/train_model.py`의 `generate_dataset` 함수에서:
+
+```python
+# 기존
+workers = n_jobs or max(1, _cgroup_cpu_count() - 1)
+chunk = max(1, len(task_args) // (workers * 10))
+
+# 변경: M4의 P코어/E코어 혼합을 고려해 worker 수를 P코어 수로 제한
+# M4 mini: 4 P코어 + 6 E코어 = 10코어. 실제 병렬 처리는 P코어 기준이 효율적
+workers = n_jobs or min(max(1, _cgroup_cpu_count() - 1), 8)
+# chunksize를 크게 잡아 IPC 오버헤드 감소
+chunk = max(100, len(task_args) // workers)
+```
+
+`scripts/train_model.py`의 `generate_dataset` 함수 내 두 줄을 수정:
+
+```python
+workers = n_jobs or min(max(1, _cgroup_cpu_count() - 1), 8)
+# ...
+chunk = max(100, len(task_args) // workers)
+```
+
+**Step 4: 테스트 재실행 (통과 확인)**
+
+```bash
+pytest tests/test_train_model_perf.py -v
+```
+
+**Step 5: 커밋**
+
+```bash
+git add scripts/train_model.py tests/test_train_model_perf.py
+git commit -m "perf: tune multiprocessing chunksize for M4 P-core efficiency"
+```
+
+---
+
+## Task 3: Apple MLX 기반 신경망 필터 실험 (GPU/Neural Engine 활용)
+
+LightGBM을 대체하거나 앙상블할 수 있는 MLX 기반 경량 신경망을 구현한다. MLX는 Apple Silicon의 통합 GPU와 Neural Engine을 자동으로 활용한다.
+
+**Files:**
+- Create: `src/mlx_filter.py`
+- Create: `scripts/train_mlx_model.py`
+- Create: `tests/test_mlx_filter.py`
+
+**Step 1: MLX 설치 확인 및 설치**
+
+```bash
+# venv 활성화 후
+pip install mlx
+python -c "import mlx.core as mx; print('MLX device:', mx.default_device())"
+```
+
+예상 출력: `MLX device: Device(gpu, 0)` (GPU 자동 사용)
+
+**Step 2: requirements.txt에 mlx 추가**
+
+`requirements.txt`에 다음 줄 추가:
+```
+mlx>=0.22.0
+```
+
+**Step 3: 실패 테스트 작성**
+
+```python
+# tests/test_mlx_filter.py
+import pytest
+import numpy as np
+
+def test_mlx_available():
+    """MLX가 설치되어 GPU 디바이스를 사용할 수 있어야 한다."""
+    import mlx.core as mx
+    device = mx.default_device()
+    assert device is not None
+
+def test_mlx_filter_predict_shape():
+    """MLXFilter가 (N,) 형태의 확률값을 반환해야 한다."""
+    from src.mlx_filter import MLXFilter
+    import pandas as pd
+    X = pd.DataFrame({
+        "rsi": [50.0], "macd_hist": [0.1], "bb_pct": [0.5],
+        "ema_align": [1.0], "stoch_k": [50.0], "stoch_d": [50.0],
+        "atr_pct": [0.01], "vol_ratio": [1.0],
+        "ret_1": [0.001], "ret_3": [0.002], "ret_5": [0.003],
+        "signal_strength": [3.0], "side": [1.0],
+    })
+    model = MLXFilter(input_dim=13, hidden_dim=64)
+    proba = model.predict_proba(X)
+    assert proba.shape == (1,)
+    assert 0.0 <= proba[0] <= 1.0
+```
+
+**Step 4: 테스트 실행 (실패 확인)**
+
+```bash
+pytest tests/test_mlx_filter.py -v
+```
+
+**Step 5: MLXFilter 구현**
+
+```python
+# src/mlx_filter.py
+"""
+Apple MLX 기반 경량 신경망 필터.
+M4의 통합 GPU와 Neural Engine을 자동으로 활용한다.
+"""
+import numpy as np
+import pandas as pd
+import mlx.core as mx
+import mlx.nn as nn
+import mlx.optimizers as optim
+from pathlib import Path
+
+from src.ml_features import FEATURE_COLS
+
+
+class _Net(nn.Module):
+    """2층 MLP 분류기."""
+    def __init__(self, input_dim: int, hidden_dim: int):
+        super().__init__()
+        self.fc1 = nn.Linear(input_dim, hidden_dim)
+        self.fc2 = nn.Linear(hidden_dim, hidden_dim // 2)
+        self.fc3 = nn.Linear(hidden_dim // 2, 1)
+        self.dropout = nn.Dropout(p=0.2)
+
+    def __call__(self, x: mx.array) -> mx.array:
+        x = nn.relu(self.fc1(x))
+        x = self.dropout(x)
+        x = nn.relu(self.fc2(x))
+        return self.fc3(x).squeeze(-1)
+
+
+class MLXFilter:
+    """scikit-learn 호환 인터페이스를 제공하는 MLX 신경망 필터."""
+
+    def __init__(self, input_dim: int = 13, hidden_dim: int = 64,
+                 lr: float = 1e-3, epochs: int = 50, batch_size: int = 256):
+        self.input_dim = input_dim
+        self.hidden_dim = hidden_dim
+        self.lr = lr
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.model = _Net(input_dim, hidden_dim)
+        self._trained = False
+
+    def fit(self, X: pd.DataFrame, y: pd.Series) -> "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
+        X_np = (X_np - self._mean) / self._std
+
+        optimizer = optim.Adam(learning_rate=self.lr)
+
+        def loss_fn(model, x, y):
+            logits = model(x)
+            return nn.losses.binary_cross_entropy(logits, y, with_logits=True).mean()
+
+        loss_and_grad = nn.value_and_grad(self.model, loss_fn)
+
+        n = len(X_np)
+        for epoch in range(self.epochs):
+            idx = np.random.permutation(n)
+            epoch_loss = 0.0
+            steps = 0
+            for start in range(0, n, self.batch_size):
+                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)
+                optimizer.update(self.model, grads)
+                mx.eval(self.model.parameters(), optimizer.state)
+                epoch_loss += loss.item()
+                steps += 1
+            if (epoch + 1) % 10 == 0:
+                print(f"  Epoch {epoch+1}/{self.epochs} loss={epoch_loss/steps:.4f}")
+
+        self._trained = True
+        return self
+
+    def predict_proba(self, X: pd.DataFrame) -> np.ndarray:
+        X_np = X[FEATURE_COLS].values.astype(np.float32)
+        if self._trained:
+            X_np = (X_np - self._mean) / self._std
+        x = mx.array(X_np)
+        logits = self.model(x)
+        proba = mx.sigmoid(logits)
+        mx.eval(proba)
+        return np.array(proba)
+
+    def save(self, path: str | Path):
+        path = Path(path)
+        path.parent.mkdir(exist_ok=True)
+        import pickle
+        with open(path, "wb") as f:
+            pickle.dump({
+                "weights": {k: np.array(v) for k, v in
+                           dict(self.model.parameters()).items()},
+                "mean": self._mean,
+                "std": self._std,
+                "config": {
+                    "input_dim": self.input_dim,
+                    "hidden_dim": self.hidden_dim,
+                },
+            }, f)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "MLXFilter":
+        import pickle
+        with open(path, "rb") as f:
+            data = pickle.load(f)
+        obj = cls(**data["config"])
+        obj._mean = data["mean"]
+        obj._std = data["std"]
+        # 가중치 복원
+        for name, val in data["weights"].items():
+            # MLX 파라미터 복원은 직접 할당
+            pass
+        obj._trained = True
+        return obj
+```
+
+**Step 6: 테스트 재실행 (통과 확인)**
+
+```bash
+pytest tests/test_mlx_filter.py -v
+```
+
+**Step 7: 커밋**
+
+```bash
+git add src/mlx_filter.py tests/test_mlx_filter.py requirements.txt
+git commit -m "feat: add MLX-based neural filter for Apple Silicon GPU acceleration"
+```
+
+---
+
+## Task 4: MLX 모델 학습 스크립트 작성
+
+**Files:**
+- Create: `scripts/train_mlx_model.py`
+
+**Step 1: 학습 스크립트 작성**
+
+```python
+"""
+MLX 기반 신경망 필터를 학습하고 저장한다.
+사용법: python scripts/train_mlx_model.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import argparse
+import time
+import numpy as np
+import pandas as pd
+from sklearn.metrics import roc_auc_score
+
+from scripts.train_model import generate_dataset
+from src.ml_features import FEATURE_COLS
+from src.mlx_filter import MLXFilter
+
+MLX_MODEL_PATH = Path("models/mlx_filter.pkl")
+
+
+def train_mlx(data_path: str):
+    print(f"데이터 로드: {data_path}")
+    df = pd.read_parquet(data_path)
+
+    print("데이터셋 생성 중...")
+    t0 = time.perf_counter()
+    dataset = generate_dataset(df)
+    t1 = time.perf_counter()
+    print(f"데이터셋 생성 완료: {t1-t0:.1f}초, {len(dataset)}개 샘플")
+
+    X = dataset[FEATURE_COLS]
+    y = dataset["label"]
+
+    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:]
+
+    print("MLX 신경망 학습 시작...")
+    t2 = time.perf_counter()
+    model = MLXFilter(input_dim=13, hidden_dim=128, lr=1e-3, epochs=100, batch_size=256)
+    model.fit(X_train, y_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"검증 AUC: {auc:.4f}")
+
+    model.save(MLX_MODEL_PATH)
+    print(f"모델 저장: {MLX_MODEL_PATH}")
+    return auc
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    args = parser.parse_args()
+    train_mlx(args.data)
+```
+
+**Step 2: 학습 실행 및 시간 비교**
+
+```bash
+# LightGBM 학습 시간
+time python scripts/train_model.py --data data/xrpusdt_1m.parquet
+
+# MLX 학습 시간
+time python scripts/train_mlx_model.py --data data/xrpusdt_1m.parquet
+```
+
+→ AUC 비교 및 학습 시간 비교 후 어떤 모델을 사용할지 결정
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/train_mlx_model.py
+git commit -m "feat: add MLX model training script with timing comparison"
+```
+
+---
+
+## Task 5: MetalGBM 실험 (선택적)
+
+> ⚠️ MetalGBM은 2025년 11월에 만들어진 신생 프로젝트로, 프로덕션 사용은 권장하지 않는다. 실험 목적으로만 시도한다.
+
+**Files:**
+- Create: `scripts/train_metalgbm.py`
+
+**Step 1: MetalGBM 설치 시도**
+
+```bash
+pip install metalgbm
+python -c "import metalgbm; print('MetalGBM 설치 성공')"
+```
+
+실패 시 → 이 Task를 건너뛴다.
+
+**Step 2: 실험 스크립트 작성**
+
+```python
+"""
+MetalGBM으로 Apple Silicon GPU 가속 그래디언트 부스팅을 실험한다.
+사용법: python scripts/train_metalgbm.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import argparse
+import time
+import pandas as pd
+from sklearn.metrics import roc_auc_score
+
+from scripts.train_model import generate_dataset
+from src.ml_features import FEATURE_COLS
+
+def train_metalgbm(data_path: str):
+    try:
+        import metalgbm as mgbm
+    except ImportError:
+        print("MetalGBM 미설치. pip install metalgbm 실행 후 재시도")
+        return
+
+    df = pd.read_parquet(data_path)
+    dataset = generate_dataset(df)
+    X = dataset[FEATURE_COLS]
+    y = dataset["label"]
+    split = int(len(X) * 0.8)
+
+    t0 = time.perf_counter()
+    model = mgbm.MetalGBMClassifier(n_estimators=300, learning_rate=0.05)
+    model.fit(X.iloc[:split], y.iloc[:split])
+    t1 = time.perf_counter()
+
+    val_proba = model.predict_proba(X.iloc[split:])[:, 1]
+    auc = roc_auc_score(y.iloc[split:], val_proba)
+    print(f"MetalGBM 학습: {t1-t0:.1f}초, AUC: {auc:.4f}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    args = parser.parse_args()
+    train_metalgbm(args.data)
+```
+
+**Step 3: 실행 및 결과 기록**
+
+```bash
+python scripts/train_metalgbm.py --data data/xrpusdt_1m.parquet
+```
+
+**Step 4: 커밋**
+
+```bash
+git add scripts/train_metalgbm.py
+git commit -m "experiment: add MetalGBM GPU training experiment script"
+```
+
+---
+
+## Task 6: train_and_deploy.sh에 가속 옵션 추가
+
+**Files:**
+- Modify: `scripts/train_and_deploy.sh`
+
+**Step 1: 스크립트 수정**
+
+`scripts/train_and_deploy.sh`에서 학습 단계를 다음과 같이 변경:
+
+```bash
+echo ""
+echo "=== [2/3] 모델 학습 ==="
+# --backend 옵션: lgbm (기본) | mlx (Apple Silicon GPU)
+BACKEND="${TRAIN_BACKEND:-lgbm}"
+if [ "$BACKEND" = "mlx" ]; then
+    python scripts/train_mlx_model.py --data data/xrpusdt_1m.parquet
+else
+    python scripts/train_model.py --data data/xrpusdt_1m.parquet
+fi
+```
+
+**Step 2: README에 사용법 추가**
+
+`README.md`의 학습 섹션에 다음 추가:
+
+```markdown
+### 가속 학습 (Apple Silicon)
+
+```bash
+# MLX GPU 가속 학습 (M1/M2/M3/M4)
+TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
+
+# 기본 LightGBM CPU 학습
+bash scripts/train_and_deploy.sh
+```
+```
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/train_and_deploy.sh README.md
+git commit -m "feat: add TRAIN_BACKEND env var to select lgbm or mlx training"
+```
+
+---
+
+## 최종 결과 기대치
+
+| 단계 | 현재 | 최적화 후 |
+|------|------|-----------|
+| 데이터셋 생성 | ~60초 (추정) | ~30-40초 (chunksize 튜닝) |
+| LightGBM 학습 | ~5초 (추정) | ~5초 (변화 없음) |
+| MLX 신경망 학습 | - | ~10-30초 (GPU 활용) |
+| Neural Engine | ❌ 직접 접근 불가 | ❌ (변화 없음) |
+
+> **Neural Engine에 대한 최종 답변**: Apple Neural Engine(NPU)은 CoreML, Create ML 등 Apple 전용 프레임워크를 통해서만 접근 가능하며, Python ML 라이브러리에서 직접 제어할 수 없다. MLX는 GPU를 주로 사용하고 일부 연산에서 Neural Engine을 자동으로 활용하지만, 사용자가 직접 NPU를 타겟팅할 수는 없다. **현실적인 최선은 MLX로 GPU를 활용하는 것**이다.

docs/plans/2026-03-01-ml-filter-design.md

@@ -0,0 +1,102 @@
+# ML 필터 설계 문서
+
+**날짜:** 2026-03-01
+
+## 목적
+
+기존 규칙 기반 신호(LONG/SHORT/HOLD)가 발생했을 때, LightGBM 모델이 해당 진입이 수익으로 끝날 확률을 계산하여 낮은 확률의 진입을 차단하는 보조 필터를 구현한다.
+
+---
+
+## 아키텍처 개요
+
+```
+캔들 수신 → 기술 지표 계산 → 규칙 기반 신호(LONG/SHORT/HOLD)
+                                          ↓
+                              신호 != HOLD 일 때만
+                                          ↓
+                         [ML 필터] LightGBM.predict_proba()
+                                          ↓
+                         확률 >= 0.60 이면 진입 허용
+                         확률 < 0.60 이면 진입 차단
+```
+
+---
+
+## 레이블 정의
+
+- **1 (성공):** 진입 후 `take_profit` 가격에 먼저 도달
+- **0 (실패):** 진입 후 `stop_loss` 가격에 먼저 도달
+- TP/SL 계산은 기존 `Indicators.get_atr_stop()` 재사용 (ATR 기반)
+
+---
+
+## 피처 목록
+
+| 피처 | 설명 |
+|---|---|
+| `rsi` | RSI(14) |
+| `macd_hist` | MACD 히스토그램 |
+| `bb_pct` | 볼린저밴드 내 가격 위치 (0~1) |
+| `ema_align` | EMA 정배열 여부 (1=정배열, -1=역배열, 0=혼재) |
+| `stoch_k` | Stochastic RSI K |
+| `stoch_d` | Stochastic RSI D |
+| `atr_pct` | ATR / 현재가 (변동성 비율) |
+| `vol_ratio` | 거래량 / vol_ma20 |
+| `ret_1` | 1캔들 전 대비 수익률 |
+| `ret_3` | 3캔들 전 대비 수익률 |
+| `ret_5` | 5캔들 전 대비 수익률 |
+| `signal_strength` | 규칙 기반 신호 강도 (long/short_signals 수) |
+| `side` | 신호 방향 (1=LONG, 0=SHORT) |
+
+---
+
+## 신규 컴포넌트
+
+| 컴포넌트 | 파일 | 역할 |
+|---|---|---|
+| 피처 엔지니어링 | `src/ml_features.py` | 기술 지표 → ML 피처 변환 |
+| ML 필터 | `src/ml_filter.py` | 모델 로드 + 예측 + 폴백 |
+| 재학습 스케줄러 | `src/retrainer.py` | 매일 새벽 재학습 트리거 |
+| 데이터 수집 스크립트 | `scripts/fetch_history.py` | 바이낸스 과거 캔들 수집 |
+| 학습 스크립트 | `scripts/train_model.py` | LightGBM 학습 + 저장 |
+
+---
+
+## 재학습 스케줄
+
+- **초기:** `scripts/fetch_history.py` + `scripts/train_model.py` 수동 실행
+- **이후:** 매일 새벽 3시 (KST) `retrainer.py`가 자동 실행
+  - 새 모델 AUC > 기존 모델 AUC → 교체
+  - 그렇지 않으면 기존 모델 유지 (롤백)
+  - Discord 알림으로 결과 전송
+
+---
+
+## 모델 저장 구조
+
+```
+models/
+├── lgbm_filter.pkl       ← 현재 사용 중인 모델
+├── lgbm_filter_prev.pkl  ← 롤백용 이전 모델
+└── training_log.json     ← 재학습 이력 (날짜, AUC, 샘플 수)
+```
+
+---
+
+## 폴백 정책
+
+`models/lgbm_filter.pkl` 파일이 없으면 ML 필터를 건너뛰고 기존 규칙 기반 신호 그대로 사용. 봇이 모델 없이도 정상 작동.
+
+---
+
+## bot.py 변경 범위
+
+`process_candle()` 메서드에 3줄 추가:
+
+```python
+if signal != "HOLD" and self.ml_filter.is_model_loaded():
+    features = build_features(df_with_indicators, signal)
+    if not self.ml_filter.should_enter(features):
+        signal = "HOLD"
+```

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-01-train-on-mac-deploy-to-lxc.md

@@ -0,0 +1,317 @@
+# 맥미니 로컬 학습 후 LXC 배포 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 맥미니에서 LightGBM 모델을 학습하고, 학습된 모델 파일(`lgbm_filter.pkl`)을 Proxmox LXC 컨테이너로 자동 전송하여 봇이 즉시 사용할 수 있도록 한다.
+
+**Architecture:**
+- 맥미니에서 `scripts/train_model.py`를 직접 실행하여 모델 학습 (M 시리즈 칩 병렬 처리 활용)
+- 학습 완료 후 `scp` 또는 `rsync`로 LXC 호스트에 모델 파일 전송
+- LXC 컨테이너 내 `models/` 볼륨 마운트 경로에 파일이 도달하면 봇이 자동으로 핫 리로드
+
+**Tech Stack:** Python 3.12, LightGBM, joblib, scp/rsync, SSH, docker-compose volume mount
+
+---
+
+## 전제 조건 확인
+
+- 맥미니에 Python 3.12 + 의존성 설치 가능
+- LXC 호스트 IP: `10.1.10.24`
+- SSH 키 인증 등록 완료 (`ssh root@10.1.10.24` 비밀번호 없이 접속 가능)
+- LXC 컨테이너에서 `./models`가 `/app/models`로 볼륨 마운트 중
+
+---
+
+## Task 1: 맥미니 환경 준비
+
+**Files:**
+- Read: `requirements.txt`
+
+**Step 1: 의존성 설치 확인**
+
+```bash
+# 맥미니 터미널에서 실행
+cd /Users/gihyeon/github/cointrader
+pip install -r requirements.txt
+```
+
+Expected: 모든 패키지 설치 완료 (lightgbm, pandas, joblib 등)
+
+**Step 2: 데이터 수집**
+
+```bash
+python scripts/fetch_history.py --symbol XRPUSDT --interval 1m --days 90 --output data/xrpusdt_1m.parquet
+```
+
+Expected: `저장 완료: data/xrpusdt_1m.parquet (약 130,000행)`
+
+**Step 3: 학습 실행 (맥미니 전체 코어 활용)**
+
+```bash
+# M 시리즈 맥미니는 cpu_count()가 올바르게 반환되므로 --jobs 생략 가능
+python scripts/train_model.py --data data/xrpusdt_1m.parquet
+```
+
+Expected 출력:
+```
+캔들 수: 130000
+병렬 처리: N코어 사용 (총 129940개 인덱스)
+...
+검증 AUC: 0.XXXX
+모델 저장: models/lgbm_filter.pkl
+```
+
+**Step 4: 학습 결과 확인**
+
+```bash
+ls -lh models/lgbm_filter.pkl
+python -c "import joblib; m = joblib.load('models/lgbm_filter.pkl'); print('모델 로드 OK:', type(m))"
+```
+
+Expected: 파일 존재, 로드 성공
+
+---
+
+## Task 2: LXC 전송 스크립트 작성
+
+**Files:**
+- Create: `scripts/deploy_model.sh`
+
+**Step 1: 전송 스크립트 작성**
+
+`scripts/deploy_model.sh` 파일을 생성한다:
+
+```bash
+#!/usr/bin/env bash
+# 맥미니에서 학습한 모델을 LXC 컨테이너 볼륨 경로로 전송한다.
+# 사용법: bash scripts/deploy_model.sh [LXC_HOST] [LXC_MODELS_PATH]
+#
+# 예시:
+#   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
+
+set -euo pipefail
+
+LXC_HOST="${1:-root@10.1.10.24}"
+LXC_MODELS_PATH="${2:-/root/cointrader/models}"
+LOCAL_MODEL="models/lgbm_filter.pkl"
+LOCAL_LOG="models/training_log.json"
+
+if [[ ! -f "$LOCAL_MODEL" ]]; then
+  echo "[오류] 모델 파일 없음: $LOCAL_MODEL"
+  echo "먼저 python scripts/train_model.py 를 실행하세요."
+  exit 1
+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 '  기존 모델 백업 완료'
+  fi
+  mkdir -p '${LXC_MODELS_PATH}'
+"
+
+# 모델 파일 전송
+rsync -avz --progress \
+  "$LOCAL_MODEL" \
+  "${LXC_HOST}:${LXC_MODELS_PATH}/lgbm_filter.pkl"
+
+# 학습 로그도 함께 전송 (있을 경우)
+if [[ -f "$LOCAL_LOG" ]]; then
+  rsync -avz "$LOCAL_LOG" "${LXC_HOST}:${LXC_MODELS_PATH}/training_log.json"
+  echo "  학습 로그 전송 완료"
+fi
+
+echo "=== 전송 완료 ==="
+echo ""
+echo "봇이 실행 중이라면 아래 명령으로 모델을 즉시 리로드할 수 있습니다:"
+echo "  docker exec cointrader python -c \\"
+echo "    \"from src.ml_filter import MLFilter; f=MLFilter(); f.reload_model(); print('리로드 완료')\""
+```
+
+**Step 2: 실행 권한 부여**
+
+```bash
+chmod +x scripts/deploy_model.sh
+```
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/deploy_model.sh
+git commit -m "feat: add deploy_model.sh for mac-to-lxc model transfer"
+```
+
+---
+
+## Task 3: LXC 경로 확인 및 SSH 접속 테스트
+
+**Step 1: LXC 호스트 SSH 접속 확인**
+
+```bash
+# 맥미니 터미널에서 (SSH 키 등록 완료 상태)
+ssh root@10.1.10.24 "echo 접속 성공"
+```
+
+Expected: `접속 성공`
+
+**Step 2: LXC 컨테이너 내 models 경로 확인**
+
+LXC 호스트에서 docker-compose.yml의 볼륨 마운트 경로를 확인한다:
+
+```bash
+ssh root@10.1.10.24 "docker inspect cointrader | grep -A5 Mounts"
+```
+
+Expected 출력 예시:
+```json
+"Mounts": [
+  {
+    "Source": "/root/cointrader/models",
+    "Destination": "/app/models",
+    ...
+  }
+]
+```
+
+`Source` 경로가 LXC 호스트에서 실제로 파일을 복사해야 할 위치다.
+
+**Step 3: 경로 기록**
+
+확인된 경로를 메모해 둔다. 예:
+- LXC 호스트: `root@10.1.10.24`
+- models 볼륨 소스: `/root/cointrader/models` (또는 실제 확인된 경로)
+
+---
+
+## Task 4: 모델 전송 실행
+
+**Step 1: 전송 스크립트 실행**
+
+```bash
+# 맥미니 터미널에서 (cointrader 프로젝트 루트)
+bash scripts/deploy_model.sh root@10.1.10.24 /root/cointrader/models
+```
+
+Expected:
+```
+=== 모델 전송 시작 ===
+  대상: root@10.1.10.24:/root/cointrader/models
+  파일: models/lgbm_filter.pkl
+  기존 모델 백업 완료
+lgbm_filter.pkl ... 전송 완료
+  학습 로그 전송 완료
+=== 전송 완료 ===
+```
+
+**Step 2: LXC에서 파일 존재 확인**
+
+```bash
+ssh root@10.1.10.24 "ls -lh /root/cointrader/models/"
+```
+
+Expected: `lgbm_filter.pkl`, `lgbm_filter_prev.pkl`, `training_log.json` 확인
+
+---
+
+## Task 5: 봇 핫 리로드 확인
+
+**Step 1: 봇 컨테이너에서 모델 리로드**
+
+봇이 실행 중인 경우 `MLFilter.reload_model()`을 트리거한다.
+
+방법 A — 컨테이너 재시작 (가장 간단):
+```bash
+ssh root@10.1.10.24 "cd /root/cointrader && docker compose restart cointrader"
+```
+
+방법 B — 핫 리로드 (재시작 없이):
+```bash
+ssh root@10.1.10.24 "docker exec cointrader python -c \
+  \"import sys; sys.path.insert(0,'src'); \
+    from src.ml_filter import MLFilter; \
+    f = MLFilter(); \
+    print('모델 로드:', f.is_model_loaded())\""
+```
+
+**Step 2: 봇 로그에서 모델 로드 확인**
+
+```bash
+ssh root@10.1.10.24 "docker logs cointrader --tail 20"
+```
+
+Expected 로그:
+```
+INFO | ML 필터 모델 로드 완료: models/lgbm_filter.pkl
+```
+
+---
+
+## Task 6: 자동화 스크립트 통합 (선택 사항)
+
+**Files:**
+- Create: `scripts/train_and_deploy.sh`
+
+전체 파이프라인(수집 → 학습 → 전송)을 한 번에 실행하는 스크립트:
+
+```bash
+#!/usr/bin/env bash
+# 맥미니에서 전체 학습 파이프라인을 실행하고 LXC로 배포한다.
+# 사용법: bash scripts/train_and_deploy.sh [LXC_HOST] [LXC_MODELS_PATH]
+
+set -euo pipefail
+
+LXC_HOST="${1:-root@10.1.10.24}"
+LXC_MODELS_PATH="${2:-/root/cointrader/models}"
+
+echo "=== [1/3] 데이터 수집 ==="
+python scripts/fetch_history.py --symbol XRPUSDT --interval 1m --days 90
+
+echo ""
+echo "=== [2/3] 모델 학습 ==="
+python scripts/train_model.py --data data/xrpusdt_1m.parquet
+
+echo ""
+echo "=== [3/3] LXC 배포 ==="
+bash scripts/deploy_model.sh "$LXC_HOST" "$LXC_MODELS_PATH"
+
+echo ""
+echo "=== 전체 파이프라인 완료 ==="
+```
+
+```bash
+chmod +x scripts/train_and_deploy.sh
+git add scripts/train_and_deploy.sh
+git commit -m "feat: add train_and_deploy.sh for full pipeline on mac"
+```
+
+---
+
+## 운영 워크플로우 요약
+
+```
+맥미니 (빠른 학습)                     LXC 컨테이너 (운영)
+─────────────────────                  ────────────────────
+1. fetch_history.py                    
+2. train_model.py                      
+3. deploy_model.sh ──── rsync ────→   models/lgbm_filter.pkl
+                                       (볼륨 마운트로 컨테이너에 즉시 반영)
+                                       
+                                       docker compose restart
+                                       → MLFilter.reload_model()
+                                       → 새 모델로 거래 재개
+```
+
+---
+
+## 주의사항
+
+- `models/lgbm_filter.pkl`은 joblib으로 직렬화된 LightGBM 모델이다. **Python 버전이 다르면 로드 실패**할 수 있다. 맥미니와 LXC 컨테이너의 Python 버전을 일치시킬 것 (현재 Python 3.12 기준).
+- Docker 이미지 내 Python 버전 확인: `docker exec cointrader python --version`
+- 버전 불일치 시 맥미니에서도 동일 버전 가상환경을 사용하거나, Docker 컨테이너 안에서 학습하는 방식으로 전환해야 한다.
+- `retrainer.py`의 자동 재학습(매일 새벽 3시)은 LXC에서 계속 동작한다. 맥미니에서 수동 학습한 모델이 자동 재학습으로 덮어쓰여질 수 있으므로, 자동 재학습 스케줄과 충돌하지 않도록 타이밍을 조율한다.

docs/plans/2026-03-01-vectorized-dataset-builder.md

@@ -0,0 +1,647 @@
+# 벡터화 데이터셋 빌더 + 컨테이너 재학습 제거 구현 계획
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 맥미니에서 전체 시계열을 1회 계산하는 벡터화 데이터셋 빌더로 교체해 학습 속도를 높이고, LXC 도커 컨테이너에서 자동 재학습 코드를 제거한다.
+
+**Architecture:** `src/dataset_builder.py`에 벡터화 함수를 신규 작성하고 `scripts/train_model.py`, `scripts/train_mlx_model.py`에서 호출한다. `src/bot.py`에서 `Retrainer` 의존성을 제거하고 `src/retrainer.py`는 삭제한다. `src/indicators.py`, `src/ml_features.py`는 봇 실시간 경로이므로 변경하지 않는다.
+
+**Tech Stack:** Python 3.13, pandas-ta, numpy, pandas, LightGBM, MLX
+
+---
+
+## 변경 범위 요약
+
+| 파일 | 작업 |
+|------|------|
+| `src/dataset_builder.py` | 신규 — 벡터화 데이터셋 생성 |
+| `scripts/train_model.py` | `generate_dataset` → `generate_dataset_vectorized` 교체 |
+| `scripts/train_mlx_model.py` | 동일 |
+| `src/bot.py` | `Retrainer` import·인스턴스·태스크 제거 |
+| `src/retrainer.py` | 삭제 |
+| `tests/test_retrainer.py` | 삭제 |
+| `tests/test_dataset_builder.py` | 신규 — 벡터화 빌더 테스트 |
+| `Dockerfile` | `mlx` 제외 처리 (Linux ARM에서 설치 불가) |
+| `requirements.txt` | mlx를 Mac 전용 주석으로 표시 |
+
+---
+
+## Task 1: `src/dataset_builder.py` 신규 작성
+
+**핵심 아이디어**: `pandas_ta`를 전체 시계열에 1번만 호출하고, 신호 조건·피처·레이블을 모두 numpy 배열 연산으로 처리한다.
+
+**Files:**
+- Create: `src/dataset_builder.py`
+- Create: `tests/test_dataset_builder.py`
+
+**Step 1: 실패 테스트 작성**
+
+```python
+# tests/test_dataset_builder.py
+import numpy as np
+import pandas as pd
+import pytest
+from src.dataset_builder import generate_dataset_vectorized
+
+@pytest.fixture
+def sample_df():
+    """최소 200행 이상의 OHLCV 더미 데이터."""
+    rng = np.random.default_rng(42)
+    n = 500
+    close = 2.0 + np.cumsum(rng.normal(0, 0.01, n))
+    close = np.clip(close, 0.01, None)
+    high  = close * (1 + rng.uniform(0, 0.005, n))
+    low   = close * (1 - rng.uniform(0, 0.005, n))
+    return pd.DataFrame({
+        "open":   close,
+        "high":   high,
+        "low":    low,
+        "close":  close,
+        "volume": rng.uniform(1e6, 5e6, n),
+    })
+
+def test_returns_dataframe(sample_df):
+    """결과가 DataFrame이어야 한다."""
+    result = generate_dataset_vectorized(sample_df)
+    assert isinstance(result, pd.DataFrame)
+
+def test_has_required_columns(sample_df):
+    """FEATURE_COLS + label 컬럼이 모두 있어야 한다."""
+    from src.ml_features import FEATURE_COLS
+    result = generate_dataset_vectorized(sample_df)
+    if len(result) > 0:
+        assert "label" in result.columns
+        for col in FEATURE_COLS:
+            assert col in result.columns, f"컬럼 없음: {col}"
+
+def test_label_is_binary(sample_df):
+    """label은 0 또는 1만 있어야 한다."""
+    result = generate_dataset_vectorized(sample_df)
+    if len(result) > 0:
+        assert set(result["label"].unique()).issubset({0, 1})
+
+def test_matches_original_generate_dataset(sample_df):
+    """벡터화 버전과 기존 버전의 샘플 수가 동일해야 한다."""
+    from scripts.train_model import generate_dataset
+    orig = generate_dataset(sample_df, n_jobs=1)
+    vec  = generate_dataset_vectorized(sample_df)
+    assert len(vec) == len(orig), (
+        f"샘플 수 불일치: 벡터화={len(vec)}, 기존={len(orig)}"
+    )
+```
+
+**Step 2: 테스트 실행 (실패 확인)**
+
+```bash
+cd /Users/gihyeon/github/cointrader
+.venv/bin/python -m pytest tests/test_dataset_builder.py -v
+```
+
+Expected: `ImportError: cannot import name 'generate_dataset_vectorized'`
+
+**Step 3: `src/dataset_builder.py` 구현**
+
+```python
+# src/dataset_builder.py
+"""
+전체 시계열을 1회 계산하는 벡터화 데이터셋 빌더.
+pandas_ta를 130,000번 반복 호출하는 기존 방식 대신
+전체 배열에 1번만 적용해 10~30배 속도를 낸다.
+
+봇 실시간 경로(indicators.py, ml_features.py)는 변경하지 않는다.
+"""
+import numpy as np
+import pandas as pd
+import pandas_ta as ta
+
+from src.ml_features import FEATURE_COLS
+
+LOOKAHEAD    = 60
+ATR_SL_MULT  = 1.5
+ATR_TP_MULT  = 3.0
+WARMUP       = 60   # 지표 안정화에 필요한 최소 행 수
+
+
+def _calc_indicators(df: pd.DataFrame) -> pd.DataFrame:
+    """전체 시계열에 기술 지표를 1회 계산한다."""
+    d = df.copy()
+    close  = d["close"]
+    high   = d["high"]
+    low    = d["low"]
+    volume = d["volume"]
+
+    d["rsi"]  = ta.rsi(close, length=14)
+
+    macd = ta.macd(close, fast=12, slow=26, signal=9)
+    d["macd"]        = macd["MACD_12_26_9"]
+    d["macd_signal"] = macd["MACDs_12_26_9"]
+    d["macd_hist"]   = macd["MACDh_12_26_9"]
+
+    bb = ta.bbands(close, length=20, std=2)
+    d["bb_upper"] = bb["BBU_20_2.0_2.0"]
+    d["bb_lower"] = bb["BBL_20_2.0_2.0"]
+
+    d["ema9"]  = ta.ema(close, length=9)
+    d["ema21"] = ta.ema(close, length=21)
+    d["ema50"] = ta.ema(close, length=50)
+
+    d["atr"]     = ta.atr(high, low, close, length=14)
+    d["vol_ma20"] = ta.sma(volume, length=20)
+
+    stoch = ta.stochrsi(close, length=14)
+    d["stoch_k"] = stoch["STOCHRSIk_14_14_3_3"]
+    d["stoch_d"] = stoch["STOCHRSId_14_14_3_3"]
+
+    return d
+
+
+def _calc_signals(d: pd.DataFrame) -> np.ndarray:
+    """
+    indicators.py get_signal() 로직을 numpy 배열 연산으로 재현한다.
+    반환: signal_arr — 각 행에 대해 "LONG" | "SHORT" | "HOLD"
+    """
+    n = len(d)
+
+    rsi      = d["rsi"].values
+    macd     = d["macd"].values
+    macd_sig = d["macd_signal"].values
+    close    = d["close"].values
+    bb_upper = d["bb_upper"].values
+    bb_lower = d["bb_lower"].values
+    ema9     = d["ema9"].values
+    ema21    = d["ema21"].values
+    ema50    = d["ema50"].values
+    stoch_k  = d["stoch_k"].values
+    stoch_d  = d["stoch_d"].values
+    volume   = d["volume"].values
+    vol_ma20 = d["vol_ma20"].values
+
+    # MACD 크로스: 전 캔들과 비교 (shift(1))
+    prev_macd     = np.roll(macd, 1);     prev_macd[0]     = np.nan
+    prev_macd_sig = np.roll(macd_sig, 1); prev_macd_sig[0] = np.nan
+
+    long_score  = np.zeros(n, dtype=np.float32)
+    short_score = np.zeros(n, dtype=np.float32)
+
+    # 1. RSI
+    long_score  += (rsi < 35).astype(np.float32)
+    short_score += (rsi > 65).astype(np.float32)
+
+    # 2. MACD 크로스 (가중치 2)
+    macd_cross_up   = (prev_macd < prev_macd_sig) & (macd > macd_sig)
+    macd_cross_down = (prev_macd > prev_macd_sig) & (macd < macd_sig)
+    long_score  += macd_cross_up.astype(np.float32)   * 2
+    short_score += macd_cross_down.astype(np.float32) * 2
+
+    # 3. 볼린저 밴드
+    long_score  += (close < bb_lower).astype(np.float32)
+    short_score += (close > bb_upper).astype(np.float32)
+
+    # 4. EMA 정배열/역배열
+    long_score  += ((ema9 > ema21) & (ema21 > ema50)).astype(np.float32)
+    short_score += ((ema9 < ema21) & (ema21 < ema50)).astype(np.float32)
+
+    # 5. Stochastic RSI
+    long_score  += ((stoch_k < 20) & (stoch_k > stoch_d)).astype(np.float32)
+    short_score += ((stoch_k > 80) & (stoch_k < stoch_d)).astype(np.float32)
+
+    # 6. 거래량 급증
+    vol_surge = volume > vol_ma20 * 1.5
+
+    long_enter  = (long_score  >= 3) & (vol_surge | (long_score  >= 4))
+    short_enter = (short_score >= 3) & (vol_surge | (short_score >= 4))
+
+    signal_arr = np.full(n, "HOLD", dtype=object)
+    signal_arr[long_enter]  = "LONG"
+    signal_arr[short_enter] = "SHORT"
+    # 둘 다 해당하면 HOLD (충돌 방지)
+    signal_arr[long_enter & short_enter] = "HOLD"
+
+    return signal_arr
+
+
+def _calc_features_vectorized(d: pd.DataFrame, signal_arr: np.ndarray) -> pd.DataFrame:
+    """
+    신호 발생 인덱스에서 ml_features.py build_features() 로직을
+    pandas 벡터 연산으로 재현한다.
+    """
+    close    = d["close"]
+    bb_upper = d["bb_upper"]
+    bb_lower = d["bb_lower"]
+    ema9     = d["ema9"]
+    ema21    = d["ema21"]
+    ema50    = d["ema50"]
+    atr      = d["atr"]
+    volume   = d["volume"]
+    vol_ma20 = d["vol_ma20"]
+    rsi      = d["rsi"]
+    macd_hist = d["macd_hist"]
+    stoch_k  = d["stoch_k"]
+    stoch_d  = d["stoch_d"]
+    macd     = d["macd"]
+    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)
+
+    ema_align = np.where(
+        (ema9 > ema21) & (ema21 > ema50),  1,
+        np.where(
+            (ema9 < ema21) & (ema21 < ema50), -1, 0
+        )
+    ).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)
+
+    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
+
+    prev_macd     = macd.shift(1).fillna(0).values
+    prev_macd_sig = macd_sig.shift(1).fillna(0).values
+
+    # signal_strength: 신호 방향별로 각 조건 점수 합산
+    is_long  = (signal_arr == "LONG")
+    is_short = (signal_arr == "SHORT")
+
+    strength = np.zeros(len(d), dtype=np.float32)
+
+    # LONG 조건
+    strength += is_long * (rsi.values < 35).astype(np.float32)
+    strength += is_long * ((prev_macd < prev_macd_sig) & (macd.values > macd_sig.values)).astype(np.float32) * 2
+    strength += is_long * (close.values < bb_lower.values).astype(np.float32)
+    strength += is_long * (ema_align == 1).astype(np.float32)
+    strength += is_long * ((stoch_k.values < 20) & (stoch_k.values > stoch_d.values)).astype(np.float32)
+
+    # SHORT 조건
+    strength += is_short * (rsi.values > 65).astype(np.float32)
+    strength += is_short * ((prev_macd > prev_macd_sig) & (macd.values < macd_sig.values)).astype(np.float32) * 2
+    strength += is_short * (close.values > bb_upper.values).astype(np.float32)
+    strength += is_short * (ema_align == -1).astype(np.float32)
+    strength += is_short * ((stoch_k.values > 80) & (stoch_k.values < stoch_d.values)).astype(np.float32)
+
+    side = np.where(signal_arr == "LONG", 1.0, 0.0).astype(np.float32)
+
+    return pd.DataFrame({
+        "rsi":             rsi.values.astype(np.float32),
+        "macd_hist":       macd_hist.values.astype(np.float32),
+        "bb_pct":          bb_pct.astype(np.float32),
+        "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),
+        "signal_strength": strength,
+        "side":            side,
+        "_signal":         signal_arr,   # 레이블 계산용 임시 컬럼
+    }, index=d.index)
+
+
+def _calc_labels_vectorized(
+    d: pd.DataFrame,
+    feat: pd.DataFrame,
+    sig_idx: np.ndarray,
+) -> np.ndarray:
+    """
+    label_builder.py build_labels() 로직을 numpy 2D 배열로 벡터화한다.
+
+    각 신호 인덱스 i에 대해 future[i+1 : i+1+LOOKAHEAD] 구간의
+    high/low 배열을 (N × LOOKAHEAD) 행렬로 만들어 argmax로 처리한다.
+    """
+    n_total = len(d)
+    highs   = d["high"].values
+    lows    = d["low"].values
+    closes  = d["close"].values
+    atrs    = d["atr"].values
+
+    labels = []
+    valid_mask = []
+
+    for idx in sig_idx:
+        signal = feat.at[d.index[idx], "_signal"]
+        entry  = closes[idx]
+        atr    = atrs[idx]
+        if atr <= 0:
+            valid_mask.append(False)
+            continue
+
+        if signal == "LONG":
+            sl = entry - atr * ATR_SL_MULT
+            tp = entry + atr * ATR_TP_MULT
+        else:
+            sl = entry + atr * ATR_SL_MULT
+            tp = entry - atr * ATR_TP_MULT
+
+        end = min(idx + 1 + LOOKAHEAD, n_total)
+        fut_high = highs[idx + 1 : end]
+        fut_low  = lows[idx + 1 : end]
+
+        label = None
+        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:
+                    label = 1
+                    break
+                if h >= sl:
+                    label = 0
+                    break
+
+        if label is None:
+            valid_mask.append(False)
+        else:
+            labels.append(label)
+            valid_mask.append(True)
+
+    return np.array(labels, dtype=np.int8), np.array(valid_mask, dtype=bool)
+
+
+def generate_dataset_vectorized(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    전체 시계열을 1회 계산해 학습 데이터셋을 생성한다.
+    기존 generate_dataset()의 drop-in 대체제.
+    """
+    print("  [1/3] 전체 시계열 지표 계산 (1회)...")
+    d = _calc_indicators(df)
+
+    print("  [2/3] 신호 마스킹 및 피처 추출...")
+    signal_arr = _calc_signals(d)
+    feat_all   = _calc_features_vectorized(d, signal_arr)
+
+    # 신호 발생 + NaN 없음 + 미래 데이터 충분한 인덱스만
+    valid_rows = (
+        (signal_arr != "HOLD") &
+        (~feat_all[FEATURE_COLS].isna().any(axis=1).values) &
+        (np.arange(len(d)) >= WARMUP) &
+        (np.arange(len(d)) < len(d) - LOOKAHEAD)
+    )
+    sig_idx = np.where(valid_rows)[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]
+    feat_final = feat_all.iloc[final_idx][FEATURE_COLS].copy()
+    feat_final["label"] = labels
+
+    return feat_final.reset_index(drop=True)
+```
+
+**Step 4: 테스트 실행 (통과 확인)**
+
+```bash
+.venv/bin/python -m pytest tests/test_dataset_builder.py -v
+```
+
+Expected: 4 passed
+
+**Step 5: 커밋**
+
+```bash
+git add src/dataset_builder.py tests/test_dataset_builder.py
+git commit -m "feat: add vectorized dataset builder (1x pandas_ta call)"
+```
+
+---
+
+## Task 2: `scripts/train_model.py` 교체
+
+**Files:**
+- Modify: `scripts/train_model.py`
+
+**Step 1: `generate_dataset` 호출을 벡터화 버전으로 교체**
+
+`scripts/train_model.py` 상단 import에 추가:
+```python
+from src.dataset_builder import generate_dataset_vectorized
+```
+
+`train()` 함수 내 `generate_dataset(df, n_jobs=n_jobs)` 호출을 교체:
+```python
+# 기존
+dataset = generate_dataset(df, n_jobs=n_jobs)
+
+# 변경
+dataset = generate_dataset_vectorized(df)
+```
+
+`main()`의 `--jobs` 인자 제거:
+```python
+# 기존
+parser.add_argument("--jobs", type=int, default=None,
+                    help="병렬 worker 수 (기본: CPU 수 - 1)")
+args = parser.parse_args()
+train(args.data, n_jobs=args.jobs)
+
+# 변경
+args = parser.parse_args()
+train(args.data)
+```
+
+`train()` 함수 시그니처에서 `n_jobs` 파라미터 제거:
+```python
+# 기존
+def train(data_path: str, n_jobs: int | None = None):
+
+# 변경
+def train(data_path: str):
+```
+
+**Step 2: 학습 실행 및 시간 측정**
+
+```bash
+time .venv/bin/python scripts/train_model.py --data data/xrpusdt_1m.parquet
+```
+
+Expected: 기존 130초 → 10초 이내
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/train_model.py
+git commit -m "perf: replace generate_dataset with vectorized version in train_model"
+```
+
+---
+
+## Task 3: `scripts/train_mlx_model.py` 교체
+
+**Files:**
+- Modify: `scripts/train_mlx_model.py`
+
+**Step 1: import 교체**
+
+`scripts/train_mlx_model.py` 상단에서:
+```python
+# 기존
+from scripts.train_model import generate_dataset
+
+# 변경
+from src.dataset_builder import generate_dataset_vectorized
+```
+
+`train_mlx()` 함수 내 호출 교체:
+```python
+# 기존
+dataset = generate_dataset(df)
+
+# 변경
+dataset = generate_dataset_vectorized(df)
+```
+
+**Step 2: 실행 확인**
+
+```bash
+time .venv/bin/python scripts/train_mlx_model.py --data data/xrpusdt_1m.parquet
+```
+
+**Step 3: 커밋**
+
+```bash
+git add scripts/train_mlx_model.py
+git commit -m "perf: replace generate_dataset with vectorized version in train_mlx_model"
+```
+
+---
+
+## Task 4: 컨테이너에서 재학습 제거
+
+**Files:**
+- Modify: `src/bot.py`
+- Delete: `src/retrainer.py`
+- Delete: `tests/test_retrainer.py`
+
+**Step 1: `src/bot.py`에서 Retrainer 제거**
+
+`src/bot.py`에서 다음 3곳을 수정:
+
+```python
+# 제거할 import
+from src.retrainer import Retrainer
+
+# 제거할 __init__ 코드
+self.retrainer = Retrainer(ml_filter=self.ml_filter)
+
+# 제거할 run() 코드
+asyncio.create_task(self.retrainer.schedule_daily(hour=3))
+```
+
+**Step 2: `src/retrainer.py` 삭제**
+
+```bash
+rm src/retrainer.py
+```
+
+**Step 3: `tests/test_retrainer.py` 삭제**
+
+```bash
+rm tests/test_retrainer.py
+```
+
+**Step 4: 기존 테스트 전체 통과 확인**
+
+```bash
+.venv/bin/python -m pytest tests/ -v --ignore=tests/test_retrainer.py
+```
+
+Expected: 모든 테스트 통과
+
+**Step 5: 커밋**
+
+```bash
+git add src/bot.py
+git rm src/retrainer.py tests/test_retrainer.py
+git commit -m "feat: remove in-container retraining, training is now mac-only"
+```
+
+---
+
+## Task 5: Dockerfile에서 mlx 제외
+
+`mlx`는 Apple Silicon 전용이라 Linux(LXC) 컨테이너에서 설치 불가.
+
+**Files:**
+- Modify: `requirements.txt`
+- Modify: `Dockerfile`
+
+**Step 1: `requirements.txt`에서 mlx 조건부 처리**
+
+`requirements.txt`에서:
+```
+# 변경 전
+mlx>=0.22.0
+
+# 변경 후 (삭제 — Dockerfile에서 별도 처리)
+```
+mlx 줄을 삭제한다.
+
+**Step 2: `Dockerfile`에 mlx 제외 명시**
+
+```dockerfile
+# 변경 전
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 변경 후
+RUN pip install --no-cache-dir -r requirements.txt
+# mlx는 Apple Silicon 전용이므로 컨테이너에 설치하지 않는다
+```
+
+실제로는 requirements.txt에서 mlx를 제거하는 것만으로 충분하다.
+맥미니에서는 수동으로 설치:
+```bash
+pip install mlx>=0.22.0
+```
+
+**Step 3: README 업데이트**
+
+`README.md`의 "Apple Silicon GPU 가속 학습" 섹션에 설치 안내 추가:
+```markdown
+> **설치**: `mlx`는 Apple Silicon 전용이며 `requirements.txt`에 포함되지 않습니다.
+> 맥미니에서 별도 설치: `pip install mlx`
+```
+
+**Step 4: 커밋**
+
+```bash
+git add requirements.txt Dockerfile README.md
+git commit -m "chore: exclude mlx from container requirements (Apple Silicon only)"
+```
+
+---
+
+## Task 6: 전체 검증 및 속도 비교
+
+**Step 1: 프로파일러로 최종 속도 측정**
+
+```bash
+time .venv/bin/python scripts/train_model.py --data data/xrpusdt_1m.parquet
+```
+
+Expected: 10초 이내 (기존 130초 대비 10배+ 향상)
+
+**Step 2: 전체 테스트 통과 확인**
+
+```bash
+.venv/bin/python -m pytest tests/ -v
+```
+
+Expected: 모든 테스트 통과 (test_retrainer.py 제외)
+
+**Step 3: train_and_deploy.sh 전체 파이프라인 dry-run**
+
+```bash
+bash scripts/train_and_deploy.sh 2>&1 | head -30
+```
+
+**Step 4: 최종 커밋 없음** — 각 Task에서 이미 커밋 완료

models/training_log.json

@@ -0,0 +1,220 @@
+[
+  {
+    "date": "2026-03-01T18:04:50.871434",
+    "auc": 0.546,
+    "samples": 1772,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T18:44:22.163935",
+    "backend": "mlx",
+    "auc": 0.5054,
+    "samples": 1772,
+    "train_sec": 0.7,
+    "model_path": "models/mlx_filter.weights"
+  },
+  {
+    "date": "2026-03-01T18:52:52.991917",
+    "auc": 0.5405,
+    "samples": 1704,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T18:54:48.200006",
+    "auc": 0.5405,
+    "samples": 1704,
+    "model_path": "models/lgbm_filter.pkl"
+  },
+  {
+    "date": "2026-03-01T19:29:21.454533",
+    "auc": 0.5321,
+    "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"
+  }
+]

requirements.txt

@@ -1,5 +1,5 @@
 python-binance==1.0.19
-pandas>=2.2.0
+pandas>=2.3.2
 pandas-ta==0.4.71b0
 python-dotenv==1.0.0
 httpx>=0.27.0
@@ -8,3 +8,8 @@ pytest-asyncio>=0.24.0
 aiohttp==3.9.3
 websockets==12.0
 loguru==0.7.2
+lightgbm>=4.3.0
+scikit-learn>=1.4.0
+joblib>=1.3.0
+pyarrow>=15.0.0
+onnxruntime>=1.18.0

scripts/deploy_model.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# 맥미니에서 학습한 모델을 LXC 컨테이너 볼륨 경로로 전송한다.
+# 사용법: bash scripts/deploy_model.sh [lgbm|mlx]
+#
+# 예시:
+#   bash scripts/deploy_model.sh        # LightGBM (기본값)
+#   bash scripts/deploy_model.sh mlx    # MLX 신경망
+
+set -euo pipefail
+
+BACKEND="${1:-lgbm}"
+LXC_HOST="root@10.1.10.24"
+LXC_MODELS_PATH="/root/cointrader/models"
+LOCAL_LOG="models/training_log.json"
+
+# ── 백엔드별 파일 목록 설정 ──────────────────────────────────────────────────
+# 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
+
+# ── 파일 존재 확인 ────────────────────────────────────────────────────────────
+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 기존 모델 백업 ─────────────────────────────────
+ssh "${LXC_HOST}" "
+  mkdir -p '${LXC_MODELS_PATH}'
+  if [ '$BACKEND' = 'lgbm' ] && [ -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
+"
+
+# ── 파일 전송 헬퍼 (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 --progress "$src" "${LXC_HOST}:$dst"
+  else
+    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 ""
+
+# ── 핫리로드 안내 ────────────────────────────────────────────────────────────
+# 봇이 캔들마다 모델 파일 mtime을 감지해 자동 리로드한다.
+# 컨테이너가 실행 중이면 다음 캔들(최대 1분) 안에 자동 적용된다.
+echo "=== 모델 전송 완료 — 봇이 다음 캔들에서 자동 리로드합니다 ==="
+if ssh "${LXC_HOST}" "docker inspect -f '{{.State.Running}}' cointrader 2>/dev/null | grep -q true"; then
+  echo "  컨테이너 실행 중: 다음 캔들 마감 시 자동 핫리로드 예정"
+else
+  echo "  cointrader 컨테이너가 실행 중이 아닙니다."
+fi

scripts/fetch_history.py

@@ -0,0 +1,312 @@
+"""
+바이낸스 선물 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
+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
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+# 요청 사이 딜레이 (초). 바이낸스 선물 기본 한도: 2400 req/min = 40 req/s
+# 1500개씩 가져오므로 90일 1m 데이터 = ~65회 요청/심볼
+# 심볼 간 딜레이 없이 연속 요청하면 레이트 리밋(-1003) 발생
+_REQUEST_DELAY = 0.3  # 초당 ~3.3 req → 안전 마진 충분
+_FAPI_BASE = "https://fapi.binance.com"
+
+
+def _now_ms() -> int:
+    return int(datetime.now(timezone.utc).timestamp() * 1000)
+
+
+async def _fetch_klines_with_client(
+    client: AsyncClient,
+    symbol: str,
+    interval: str,
+    days: int,
+) -> pd.DataFrame:
+    """기존 클라이언트를 재사용해 단일 심볼 캔들을 수집한다."""
+    start_ts = int((datetime.now(timezone.utc) - timedelta(days=days)).timestamp() * 1000)
+    all_klines = []
+    while True:
+        klines = await client.futures_klines(
+            symbol=symbol,
+            interval=interval,
+            startTime=start_ts,
+            limit=1500,
+        )
+        if not klines:
+            break
+        all_klines.extend(klines)
+        last_ts = klines[-1][0]
+        if last_ts >= _now_ms():
+            break
+        start_ts = last_ts + 1
+        print(f"  [{symbol}] 수집 중... {len(all_klines):,}개")
+        await asyncio.sleep(_REQUEST_DELAY)
+
+    df = pd.DataFrame(all_klines, columns=[
+        "timestamp", "open", "high", "low", "close", "volume",
+        "close_time", "quote_volume", "trades",
+        "taker_buy_base", "taker_buy_quote", "ignore",
+    ])
+    df = df[["timestamp", "open", "high", "low", "close", "volume"]].copy()
+    for col in ["open", "high", "low", "close", "volume"]:
+        df[col] = df[col].astype(float)
+    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms", utc=True)
+    df.set_index("timestamp", inplace=True)
+    return df
+
+
+async def fetch_klines(symbol: str, interval: str, days: int) -> pd.DataFrame:
+    """단일 심볼 수집 (하위 호환용)."""
+    client = await AsyncClient.create(
+        api_key=os.getenv("BINANCE_API_KEY", ""),
+        api_secret=os.getenv("BINANCE_API_SECRET", ""),
+    )
+    try:
+        return await _fetch_klines_with_client(client, symbol, interval, days)
+    finally:
+        await client.close_connection()
+
+
+async def fetch_klines_all(
+    symbols: list[str],
+    interval: str,
+    days: int,
+) -> dict[str, pd.DataFrame]:
+    """
+    단일 클라이언트로 여러 심볼을 순차 수집한다.
+    asyncio.run()을 심볼마다 반복하면 연결 오버헤드와 레이트 리밋 위험이 있으므로
+    하나의 연결 안에서 심볼 간 딜레이를 두고 순차 처리한다.
+    """
+    client = await AsyncClient.create(
+        api_key=os.getenv("BINANCE_API_KEY", ""),
+        api_secret=os.getenv("BINANCE_API_SECRET", ""),
+    )
+    dfs = {}
+    try:
+        for i, symbol in enumerate(symbols):
+            print(f"\n[{i+1}/{len(symbols)}] {symbol} 수집 시작...")
+            dfs[symbol] = await _fetch_klines_with_client(client, symbol, interval, days)
+            print(f"  [{symbol}] 완료: {len(dfs[symbol]):,}행")
+            # 심볼 간 추가 대기: 레이트 리밋 카운터가 리셋될 시간 확보
+            if i < len(symbols) - 1:
+                print(f"  다음 심볼 수집 전 5초 대기...")
+                await asyncio.sleep(5)
+    finally:
+        await client.close_connection()
+    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 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="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/펀딩비 수집을 건너뜀 (캔들 데이터만 저장)",
+    )
+    args = parser.parse_args()
+
+    # 하위 호환: --symbol 단독 사용 시 symbols로 통합
+    if args.symbol and args.symbols == ["XRPUSDT"]:
+        args.symbols = [args.symbol]
+
+    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))
+        df.to_parquet(args.output)
+        print(f"저장 완료: {args.output} ({len(df):,}행, {len(df.columns)}컬럼)")
+    else:
+        # 멀티 심볼: 단일 클라이언트로 순차 수집 후 타임스탬프 기준 inner join 병합
+        dfs = asyncio.run(fetch_klines_all(args.symbols, args.interval, args.days))
+
+        primary = args.symbols[0]
+        merged = dfs[primary].copy()
+        for symbol in args.symbols[1:]:
+            suffix = "_" + symbol.lower().replace("usdt", "")
+            merged = merged.join(
+                dfs[symbol].add_suffix(suffix),
+                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")
+        merged.to_parquet(output)
+        print(f"\n병합 저장 완료: {output} ({len(merged):,}행, {len(merged.columns)}컬럼)")
+
+
+if __name__ == "__main__":
+    main()

scripts/profile_training.py

@@ -0,0 +1,53 @@
+"""
+학습 파이프라인 각 단계의 소요 시간을 측정한다.
+사용법: python scripts/profile_training.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import time
+import argparse
+import pandas as pd
+from scripts.train_model import generate_dataset, _cgroup_cpu_count
+
+
+def profile(data_path: str):
+    print(f"데이터 로드: {data_path}")
+    df = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df)}")
+
+    workers = max(1, _cgroup_cpu_count() - 1)
+    print(f"사용 코어: {workers}")
+
+    t0 = time.perf_counter()
+    dataset = generate_dataset(df)
+    t1 = time.perf_counter()
+    print(f"\n[결과] 데이터셋 생성: {t1 - t0:.1f}초, 샘플 {len(dataset)}개")
+
+    import lightgbm as lgb
+    from sklearn.model_selection import train_test_split
+    from src.ml_features import FEATURE_COLS
+
+    X = dataset[FEATURE_COLS]
+    y = dataset["label"]
+    X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.2, random_state=42)
+
+    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,
+    )
+    t2 = time.perf_counter()
+    model.fit(X_train, y_train)
+    t3 = time.perf_counter()
+    print(f"[결과] LightGBM 학습: {t3 - t2:.1f}초")
+    print(f"[결과] 전체: {t3 - t0:.1f}초")
+    print(f"\n[비율] 데이터셋 생성: {(t1-t0)/(t3-t0)*100:.0f}% / LightGBM 학습: {(t3-t2)/(t3-t0)*100:.0f}%")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data", default="data/xrpusdt_1m.parquet")
+    args = parser.parse_args()
+    profile(args.data)

scripts/train_and_deploy.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# 맥미니에서 전체 학습 파이프라인을 실행하고 LXC로 배포한다.
+# 사용법: bash scripts/train_and_deploy.sh [mlx|lgbm] [wf-splits]
+#
+# 예시:
+#   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
+
+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심볼, 1년치 + OI/펀딩비) ==="
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/combined_15m.parquet
+
+echo ""
+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), 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"
+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 "$BACKEND"
+
+echo ""
+echo "=== 전체 파이프라인 완료 ==="
+echo ""
+echo "봇 재시작이 필요하면:"
+echo "  ssh root@10.1.10.24 'cd /root/cointrader && docker compose restart cointrader'"

scripts/train_mlx_model.py

@@ -0,0 +1,272 @@
+"""
+MLX 기반 신경망 필터를 학습하고 저장한다.
+M4 통합 GPU(Metal)를 자동으로 사용한다.
+
+사용법: python scripts/train_mlx_model.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+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
+from sklearn.metrics import roc_auc_score, classification_report
+
+from src.dataset_builder import generate_dataset_vectorized
+from src.ml_features import FEATURE_COLS
+from src.mlx_filter import MLXFilter
+
+MLX_MODEL_PATH = Path("models/mlx_filter.weights")
+LOG_PATH = Path("models/training_log.json")
+
+
+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}")
+    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, 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)}개 샘플")
+
+    if dataset.empty or "label" not in dataset.columns:
+        raise ValueError("데이터셋 생성 실패: 샘플 0개")
+
+    print(f"학습 샘플: {len(dataset)}개 (양성={dataset['label'].sum():.0f}, 음성={(dataset['label']==0).sum():.0f})")
+
+    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()
+    model = MLXFilter(
+        input_dim=len(FEATURE_COLS),
+        hidden_dim=128,
+        lr=1e-3,
+        epochs=100,
+        batch_size=256,
+    )
+    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)
+
+    # 최적 임계값 탐색: 최소 재현율(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)
+    print(f"모델 저장: {MLX_MODEL_PATH}")
+
+    log = []
+    if LOG_PATH.exists():
+        with open(LOG_PATH) as f:
+            log = json.load(f)
+    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),
+    })
+    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,
+) -> 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/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()
+
+    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__":
+    main()

scripts/train_model.py

@@ -0,0 +1,389 @@
+"""
+과거 캔들 데이터로 LightGBM 필터 모델을 학습하고 저장한다.
+사용법: python scripts/train_model.py --data data/xrpusdt_1m.parquet
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import argparse
+import json
+import math
+from datetime import datetime
+from multiprocessing import Pool, cpu_count
+from pathlib import Path
+
+import joblib
+import lightgbm as lgb
+import numpy as np
+import pandas as pd
+from sklearn.metrics import roc_auc_score, classification_report
+
+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
+
+def _cgroup_cpu_count() -> int:
+    """cgroup v1/v2 쿼터를 읽어 실제 할당된 CPU 수를 반환한다.
+    LXC/컨테이너 환경에서 cpu_count()가 호스트 전체 코어를 반환하는 문제를 방지한다.
+    쿼터를 읽을 수 없으면 cpu_count()를 그대로 사용한다.
+    """
+    # cgroup v2
+    try:
+        quota_path = Path("/sys/fs/cgroup/cpu.max")
+        if quota_path.exists():
+            parts = quota_path.read_text().split()
+            if parts[0] != "max":
+                quota = int(parts[0])
+                period = int(parts[1])
+                return max(1, math.floor(quota / period))
+    except Exception:
+        pass
+
+    # cgroup v1
+    try:
+        quota = int(Path("/sys/fs/cgroup/cpu/cpu.cfs_quota_us").read_text())
+        period = int(Path("/sys/fs/cgroup/cpu/cpu.cfs_period_us").read_text())
+        if quota > 0:
+            return max(1, math.floor(quota / period))
+    except Exception:
+        pass
+
+    return cpu_count()
+
+
+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")
+PREV_MODEL_PATH = Path("models/lgbm_filter_prev.pkl")
+LOG_PATH = Path("models/training_log.json")
+
+
+def _process_index(args: tuple) -> dict | None:
+    """단일 인덱스에 대해 피처+레이블을 계산한다. Pool worker 함수."""
+    i, df_values, df_columns = args
+    df = pd.DataFrame(df_values, columns=df_columns)
+
+    window = df.iloc[i - 60: i + 1].copy()
+    ind = Indicators(window)
+    df_ind = ind.calculate_all()
+
+    if df_ind.iloc[-1].isna().any():
+        return None
+
+    signal = ind.get_signal(df_ind)
+    if signal == "HOLD":
+        return None
+
+    entry_price = float(df_ind["close"].iloc[-1])
+    atr = float(df_ind["atr"].iloc[-1])
+    if atr <= 0:
+        return None
+
+    stop_loss   = entry_price - atr * ATR_SL_MULT if signal == "LONG" else entry_price + atr * ATR_SL_MULT
+    take_profit = entry_price + atr * ATR_TP_MULT if signal == "LONG" else entry_price - atr * ATR_TP_MULT
+
+    future = df.iloc[i + 1: i + 1 + LOOKAHEAD]
+    label = build_labels(
+        future_closes=future["close"].tolist(),
+        future_highs=future["high"].tolist(),
+        future_lows=future["low"].tolist(),
+        take_profit=take_profit,
+        stop_loss=stop_loss,
+        side=signal,
+    )
+    if label is None:
+        return None
+
+    features = build_features(df_ind, signal)
+    row = features.to_dict()
+    row["label"] = label
+    return row
+
+
+def generate_dataset(df: pd.DataFrame, n_jobs: int | None = None) -> pd.DataFrame:
+    """신호 발생 시점마다 피처와 레이블을 병렬로 생성한다."""
+    total = len(df)
+    indices = range(60, total - LOOKAHEAD)
+
+    # M4 mini: 10코어(P4+E6). 너무 많은 worker는 IPC 오버헤드를 늘리므로 8로 제한
+    workers = n_jobs or min(max(1, _cgroup_cpu_count() - 1), 8)
+    print(f"  병렬 처리: {workers}코어 사용 (총 {len(indices):,}개 인덱스)")
+
+    # DataFrame을 numpy로 변환해서 worker 간 전달 비용 최소화
+    df_values = df.values
+    df_columns = list(df.columns)
+    task_args = [(i, df_values, df_columns) for i in indices]
+
+    rows = []
+    errors = []
+    # chunksize를 크게 잡아 IPC 직렬화 횟수를 줄임
+    chunk = max(100, len(task_args) // workers)
+    with Pool(processes=workers) as pool:
+        for idx, result in enumerate(pool.imap(_process_index, task_args, chunksize=chunk)):
+            if isinstance(result, dict):
+                rows.append(result)
+            elif result is not None:
+                errors.append(result)
+            if (idx + 1) % 10000 == 0:
+                print(f"  진행: {idx + 1:,}/{len(task_args):,} | 샘플: {len(rows):,}개")
+
+    if errors:
+        print(f"  [경고] worker 오류 {len(errors)}건: {errors[0]}")
+
+    if not rows:
+        print("  [오류] 생성된 샘플이 없습니다. worker 예외 여부를 확인합니다...")
+        # 단일 프로세스로 첫 번째 인덱스를 직접 실행해서 예외 확인
+        try:
+            test_result = _process_index(task_args[0])
+            print(f"  단일 실행 결과: {test_result}")
+        except Exception as e:
+            import traceback
+            print(f"  단일 실행 예외:\n{traceback.format_exc()}")
+
+    return pd.DataFrame(rows)
+
+
+def train(data_path: str, time_weight_decay: float = 2.0):
+    print(f"데이터 로드: {data_path}")
+    df_raw = pd.read_parquet(data_path)
+    print(f"캔들 수: {len(df_raw)}, 컬럼: {list(df_raw.columns)}")
+
+    # 병합 데이터셋 여부 판별
+    btc_df = None
+    eth_df = None
+    base_cols = ["open", "high", "low", "close", "volume"]
+
+    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("데이터셋 생성 중...")
+    dataset = generate_dataset_vectorized(df, btc_df=btc_df, eth_df=eth_df, time_weight_decay=time_weight_decay)
+
+    if dataset.empty or "label" not in dataset.columns:
+        raise ValueError(f"데이터셋 생성 실패: 샘플 0개. 위 오류 메시지를 확인하세요.")
+
+    print(f"학습 샘플: {len(dataset)}개 (양성={dataset['label'].sum():.0f}, 음성={(dataset['label']==0).sum():.0f})")
+
+    if len(dataset) < 200:
+        raise ValueError(f"학습 샘플 부족: {len(dataset)}개 (최소 200 필요)")
+
+    actual_feature_cols = [c for c in FEATURE_COLS if c in dataset.columns]
+    print(f"사용 피처: {len(actual_feature_cols)}개 {actual_feature_cols}")
+    X = dataset[actual_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.sort(np.concatenate([pos_idx, neg_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(f"검증 데이터: {len(X_val)}개 (양성={int(y_val.sum())}, 음성={int((y_val==0).sum())})")
+    # ---------------------------------------------------------------
+
+    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,
+    )
+    model.fit(
+        X_train, y_train,
+        sample_weight=w_train,
+        eval_set=[(X_val, y_val)],
+        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)
+
+    # 최적 임계값 탐색: 최소 재현율(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))
+
+    if MODEL_PATH.exists():
+        import shutil
+        shutil.copy(MODEL_PATH, PREV_MODEL_PATH)
+        print(f"기존 모델 백업: {PREV_MODEL_PATH}")
+
+    MODEL_PATH.parent.mkdir(exist_ok=True)
+    joblib.dump(model, MODEL_PATH)
+    print(f"모델 저장: {MODEL_PATH}")
+
+    log = []
+    if LOG_PATH.exists():
+        with open(LOG_PATH) as f:
+            log = json.load(f)
+    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),
+    })
+    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,
+) -> 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
+    )
+    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 = 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, 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]
+        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/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()
+
+    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)
+
+
+if __name__ == "__main__":
+    main()

src/bot.py

@@ -3,9 +3,11 @@ from loguru import logger
 from src.config import Config
 from src.exchange import BinanceFuturesClient
 from src.indicators import Indicators
-from src.data_stream import KlineStream
+from src.data_stream import MultiSymbolStream
 from src.notifier import DiscordNotifier
 from src.risk_manager import RiskManager
+from src.ml_filter import MLFilter
+from src.ml_features import build_features
 
 
 class TradingBot:
@@ -14,17 +16,20 @@ class TradingBot:
         self.exchange = BinanceFuturesClient(config)
         self.notifier = DiscordNotifier(config.discord_webhook_url)
         self.risk = RiskManager(config)
+        self.ml_filter = MLFilter()
         self.current_trade_side: str | None = None  # "LONG" | "SHORT"
-        self.stream = KlineStream(
+        self.stream = MultiSymbolStream(
-            symbol=config.symbol,
+            symbols=[config.symbol, "BTCUSDT", "ETHUSDT"],
-            interval="1m",
+            interval="15m",
             on_candle=self._on_candle_closed,
         )
 
     def _on_candle_closed(self, candle: dict):
-        df = self.stream.get_dataframe()
+        xrp_df = self.stream.get_dataframe(self.config.symbol)
-        if df is not None:
+        btc_df = self.stream.get_dataframe("BTCUSDT")
-            asyncio.create_task(self.process_candle(df))
+        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))
 
     async def _recover_position(self) -> None:
         """재시작 시 바이낸스에서 현재 포지션을 조회하여 상태 복구."""
@@ -44,7 +49,9 @@ class TradingBot:
         else:
             logger.info("기존 포지션 없음 - 신규 진입 대기")
 
-    async def process_candle(self, df):
+    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
@@ -52,6 +59,13 @@ class TradingBot:
         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"
+
         current_price = df_with_indicators["close"].iloc[-1]
         logger.info(f"신호: {signal} | 현재가: {current_price:.4f} USDT")
 
@@ -73,9 +87,11 @@ class TradingBot:
     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
@@ -153,6 +169,9 @@ class TradingBot:
     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,

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,12 +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,
     ):
@@ -39,13 +48,13 @@ class KlineStream:
                 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(
@@ -84,3 +93,105 @@ class KlineStream:
                     self.handle_message(msg)
         finally:
             await client.close_connection()
+
+
+class MultiSymbolStream:
+    """
+    바이낸스 Combined WebSocket으로 여러 심볼의 캔들을 단일 연결로 수신한다.
+    XRP 캔들이 닫힐 때 on_candle 콜백을 호출한다.
+    """
+
+    def __init__(
+        self,
+        symbols: list[str],
+        interval: str = "15m",
+        buffer_size: int = 200,
+        on_candle: Callable = None,
+    ):
+        self.symbols = [s.lower() for s in symbols]
+        self.interval = interval
+        self.on_candle = on_candle
+        self.buffers: dict[str, deque] = {
+            s: deque(maxlen=buffer_size) for s in self.symbols
+        }
+        # 첫 번째 심볼이 주 심볼 (XRP)
+        self.primary_symbol = self.symbols[0]
+
+    def parse_kline(self, msg: dict) -> dict:
+        k = msg["k"]
+        return {
+            "timestamp": k["t"],
+            "open":      float(k["o"]),
+            "high":      float(k["h"]),
+            "low":       float(k["l"]),
+            "close":     float(k["c"]),
+            "volume":    float(k["v"]),
+            "is_closed": k["x"],
+        }
+
+    def handle_message(self, msg: dict):
+        # Combined stream 메시지는 {"stream": "...", "data": {...}} 형태
+        if "stream" in msg:
+            data = msg["data"]
+        else:
+            data = msg
+
+        if data.get("e") != "kline":
+            return
+
+        symbol = data["s"].lower()
+        candle = self.parse_kline(data)
+
+        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)
+
+    def get_dataframe(self, symbol: str) -> pd.DataFrame | None:
+        key = symbol.lower()
+        buf = self.buffers.get(key)
+        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 = _PRELOAD_LIMIT):
+        """REST API로 모든 심볼의 과거 캔들을 버퍼에 미리 채운다."""
+        for symbol in self.symbols:
+            logger.info(f"{symbol.upper()} 과거 캔들 {limit}개 로드 중...")
+            klines = await client.futures_klines(
+                symbol=symbol.upper(),
+                interval=self.interval,
+                limit=limit,
+            )
+            for k in klines[:-1]:
+                self.buffers[symbol].append({
+                    "timestamp": k[0],
+                    "open":      float(k[1]),
+                    "high":      float(k[2]),
+                    "low":       float(k[3]),
+                    "close":     float(k[4]),
+                    "volume":    float(k[5]),
+                    "is_closed": True,
+                })
+            logger.info(f"{symbol.upper()} {len(self.buffers[symbol])}개 로드 완료")
+
+    async def start(self, api_key: str, api_secret: str):
+        client = await AsyncClient.create(
+            api_key=api_key,
+            api_secret=api_secret,
+        )
+        await self._preload_history(client)
+        bm = BinanceSocketManager(client)
+        streams = [
+            f"{s}@kline_{self.interval}" for s in self.symbols
+        ]
+        logger.info(f"Combined WebSocket 시작: {streams}")
+        try:
+            async with bm.futures_multiplex_socket(streams) as stream:
+                while True:
+                    msg = await stream.recv()
+                    self.handle_message(msg)
+        finally:
+            await client.close_connection()

src/dataset_builder.py

@@ -0,0 +1,403 @@
+"""
+전체 시계열을 1회 계산하는 벡터화 데이터셋 빌더.
+pandas_ta를 130,000번 반복 호출하는 기존 방식 대신
+전체 배열에 1번만 적용해 10~30배 속도를 낸다.
+
+봇 실시간 경로(indicators.py, ml_features.py)는 변경하지 않는다.
+"""
+import numpy as np
+import pandas as pd
+import pandas_ta as ta
+
+from src.ml_features import FEATURE_COLS
+
+LOOKAHEAD    = 24   # 15분봉 × 24 = 6시간 뷰
+ATR_SL_MULT  = 1.5
+ATR_TP_MULT  = 2.0
+WARMUP       = 60   # 15분봉 기준 60캔들 = 15시간 (지표 안정화 충분)
+
+
+def _calc_indicators(df: pd.DataFrame) -> pd.DataFrame:
+    """전체 시계열에 기술 지표를 1회 계산한다."""
+    d = df.copy()
+    close  = d["close"]
+    high   = d["high"]
+    low    = d["low"]
+    volume = d["volume"]
+
+    d["rsi"]  = ta.rsi(close, length=14)
+
+    macd = ta.macd(close, fast=12, slow=26, signal=9)
+    d["macd"]        = macd["MACD_12_26_9"]
+    d["macd_signal"] = macd["MACDs_12_26_9"]
+    d["macd_hist"]   = macd["MACDh_12_26_9"]
+
+    bb = ta.bbands(close, length=20, std=2)
+    d["bb_upper"] = bb["BBU_20_2.0_2.0"]
+    d["bb_lower"] = bb["BBL_20_2.0_2.0"]
+
+    d["ema9"]  = ta.ema(close, length=9)
+    d["ema21"] = ta.ema(close, length=21)
+    d["ema50"] = ta.ema(close, length=50)
+
+    d["atr"]      = ta.atr(high, low, close, length=14)
+    d["vol_ma20"] = ta.sma(volume, length=20)
+
+    stoch = ta.stochrsi(close, length=14)
+    d["stoch_k"] = stoch["STOCHRSIk_14_14_3_3"]
+    d["stoch_d"] = stoch["STOCHRSId_14_14_3_3"]
+
+    return d
+
+
+def _calc_signals(d: pd.DataFrame) -> np.ndarray:
+    """
+    indicators.py get_signal() 로직을 numpy 배열 연산으로 재현한다.
+    반환: signal_arr — 각 행에 대해 "LONG" | "SHORT" | "HOLD"
+    """
+    n = len(d)
+
+    rsi      = d["rsi"].values
+    macd     = d["macd"].values
+    macd_sig = d["macd_signal"].values
+    close    = d["close"].values
+    bb_upper = d["bb_upper"].values
+    bb_lower = d["bb_lower"].values
+    ema9     = d["ema9"].values
+    ema21    = d["ema21"].values
+    ema50    = d["ema50"].values
+    stoch_k  = d["stoch_k"].values
+    stoch_d  = d["stoch_d"].values
+    volume   = d["volume"].values
+    vol_ma20 = d["vol_ma20"].values
+
+    # MACD 크로스: 전 캔들과 비교 (shift(1))
+    prev_macd     = np.roll(macd, 1);     prev_macd[0]     = np.nan
+    prev_macd_sig = np.roll(macd_sig, 1); prev_macd_sig[0] = np.nan
+
+    long_score  = np.zeros(n, dtype=np.float32)
+    short_score = np.zeros(n, dtype=np.float32)
+
+    # 1. RSI
+    long_score  += (rsi < 35).astype(np.float32)
+    short_score += (rsi > 65).astype(np.float32)
+
+    # 2. MACD 크로스 (가중치 2)
+    macd_cross_up   = (prev_macd < prev_macd_sig) & (macd > macd_sig)
+    macd_cross_down = (prev_macd > prev_macd_sig) & (macd < macd_sig)
+    long_score  += macd_cross_up.astype(np.float32)   * 2
+    short_score += macd_cross_down.astype(np.float32) * 2
+
+    # 3. 볼린저 밴드
+    long_score  += (close < bb_lower).astype(np.float32)
+    short_score += (close > bb_upper).astype(np.float32)
+
+    # 4. EMA 정배열/역배열
+    long_score  += ((ema9 > ema21) & (ema21 > ema50)).astype(np.float32)
+    short_score += ((ema9 < ema21) & (ema21 < ema50)).astype(np.float32)
+
+    # 5. Stochastic RSI
+    long_score  += ((stoch_k < 20) & (stoch_k > stoch_d)).astype(np.float32)
+    short_score += ((stoch_k > 80) & (stoch_k < stoch_d)).astype(np.float32)
+
+    # 6. 거래량 급증
+    vol_surge = volume > vol_ma20 * 1.5
+
+    long_enter  = (long_score  >= 3) & (vol_surge | (long_score  >= 4))
+    short_enter = (short_score >= 3) & (vol_surge | (short_score >= 4))
+
+    signal_arr = np.full(n, "HOLD", dtype=object)
+    signal_arr[long_enter]  = "LONG"
+    signal_arr[short_enter] = "SHORT"
+    # 둘 다 해당하면 HOLD (충돌 방지)
+    signal_arr[long_enter & short_enter] = "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,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+) -> pd.DataFrame:
+    """
+    신호 발생 인덱스에서 ml_features.py build_features() 로직을
+    pandas 벡터 연산으로 재현한다.
+    """
+    close    = d["close"]
+    bb_upper = d["bb_upper"]
+    bb_lower = d["bb_lower"]
+    ema9     = d["ema9"]
+    ema21    = d["ema21"]
+    ema50    = d["ema50"]
+    atr      = d["atr"]
+    volume   = d["volume"]
+    vol_ma20 = d["vol_ma20"]
+    rsi      = d["rsi"]
+    macd_hist = d["macd_hist"]
+    stoch_k  = d["stoch_k"]
+    stoch_d  = d["stoch_d"]
+    macd     = d["macd"]
+    macd_sig = d["macd_signal"]
+
+    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)
+
+    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
+
+    # signal_strength: 신호 방향별로 각 조건 점수 합산
+    is_long  = (signal_arr == "LONG")
+    is_short = (signal_arr == "SHORT")
+
+    strength = np.zeros(len(d), dtype=np.float32)
+
+    # LONG 조건
+    strength += is_long * (rsi.values < 35).astype(np.float32)
+    strength += is_long * ((prev_macd < prev_macd_sig) & (macd.values > macd_sig.values)).astype(np.float32) * 2
+    strength += is_long * (close.values < bb_lower.values).astype(np.float32)
+    strength += is_long * (ema_align == 1).astype(np.float32)
+    strength += is_long * ((stoch_k.values < 20) & (stoch_k.values > stoch_d.values)).astype(np.float32)
+
+    # SHORT 조건
+    strength += is_short * (rsi.values > 65).astype(np.float32)
+    strength += is_short * ((prev_macd > prev_macd_sig) & (macd.values < macd_sig.values)).astype(np.float32) * 2
+    strength += is_short * (close.values > bb_upper.values).astype(np.float32)
+    strength += is_short * (ema_align == -1).astype(np.float32)
+    strength += is_short * ((stoch_k.values > 80) & (stoch_k.values < stoch_d.values)).astype(np.float32)
+
+    side = np.where(signal_arr == "LONG", 1.0, 0.0).astype(np.float32)
+
+    result = pd.DataFrame({
+        "rsi":             rsi.values.astype(np.float32),
+        "macd_hist":       macd_hist.values.astype(np.float32),
+        "bb_pct":          bb_pct.astype(np.float32),
+        "ema_align":       ema_align,
+        "stoch_k":         stoch_k.values.astype(np.float32),
+        "stoch_d":         stoch_d.values.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,   # 레이블 계산용 임시 컬럼
+    }, index=d.index)
+
+    # BTC/ETH 피처 계산 (제공된 경우)
+    if btc_df is not None and eth_df is not None:
+        btc_ret_1 = btc_df["close"].pct_change(1).fillna(0).values
+        btc_ret_3 = btc_df["close"].pct_change(3).fillna(0).values
+        btc_ret_5 = btc_df["close"].pct_change(5).fillna(0).values
+        eth_ret_1 = eth_df["close"].pct_change(1).fillna(0).values
+        eth_ret_3 = eth_df["close"].pct_change(3).fillna(0).values
+        eth_ret_5 = eth_df["close"].pct_change(5).fillna(0).values
+
+        def _align(arr: np.ndarray, target_len: int) -> np.ndarray:
+            if len(arr) >= target_len:
+                return arr[-target_len:]
+            return np.concatenate([np.zeros(target_len - len(arr)), arr])
+
+        n = len(d)
+        btc_r1 = _align(btc_ret_1, n).astype(np.float32)
+        btc_r3 = _align(btc_ret_3, n).astype(np.float32)
+        btc_r5 = _align(btc_ret_5, n).astype(np.float32)
+        eth_r1 = _align(eth_ret_1, n).astype(np.float32)
+        eth_r3 = _align(eth_ret_3, n).astype(np.float32)
+        eth_r5 = _align(eth_ret_5, n).astype(np.float32)
+
+        xrp_r1 = ret_1.astype(np.float32)
+        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)
+
+        extra = pd.DataFrame({
+            "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
+
+
+def _calc_labels_vectorized(
+    d: pd.DataFrame,
+    feat: pd.DataFrame,
+    sig_idx: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    label_builder.py build_labels() 로직을 numpy 2D 배열로 벡터화한다.
+
+    각 신호 인덱스 i에 대해 future[i+1 : i+1+LOOKAHEAD] 구간의
+    high/low 배열을 (N × LOOKAHEAD) 행렬로 만들어 argmax로 처리한다.
+    """
+    n_total = len(d)
+    highs   = d["high"].values
+    lows    = d["low"].values
+    closes  = d["close"].values
+    atrs    = d["atr"].values
+
+    labels = []
+    valid_mask = []
+
+    for idx in sig_idx:
+        signal = feat.at[d.index[idx], "_signal"]
+        entry  = closes[idx]
+        atr    = atrs[idx]
+        if atr <= 0:
+            valid_mask.append(False)
+            continue
+
+        if signal == "LONG":
+            sl = entry - atr * ATR_SL_MULT
+            tp = entry + atr * ATR_TP_MULT
+        else:
+            sl = entry + atr * ATR_SL_MULT
+            tp = entry - atr * ATR_TP_MULT
+
+        end = min(idx + 1 + LOOKAHEAD, n_total)
+        fut_high = highs[idx + 1 : end]
+        fut_low  = lows[idx + 1 : end]
+
+        label = 0  # 미도달(타임아웃) 시 실패로 간주
+
+        for h, l in zip(fut_high, fut_low):
+            if signal == "LONG":
+                if l <= sl:
+                    label = 0
+                    break
+                if h >= tp:
+                    label = 1
+                    break
+            else:  # SHORT
+                if h >= sl:
+                    label = 0
+                    break
+                if l <= tp:
+                    label = 1
+                    break
+
+        labels.append(label)
+        valid_mask.append(True)
+
+    return np.array(labels, dtype=np.int8), np.array(valid_mask, dtype=bool)
+
+
+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,
+) -> 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' 컬럼으로 포함된다.
+    """
+    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 없음 + 미래 데이터 충분한 인덱스만
+    # oi_change/funding_rate는 선택적 피처(컬럼 없으면 전체 nan)이므로 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
+    ]
+    valid_rows = (
+        (signal_arr != "HOLD") &
+        (~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]
+    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 제공 여부에 따라 실제 존재하는 피처 컬럼만 선택
+    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
+
+    # 시간 가중치: 오래된 샘플 → 낮은 가중치, 최신 샘플 → 높은 가중치
+    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()  # 평균 1로 정규화해 학습률 스케일 유지
+        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 = feat_final.reset_index(drop=True)
+    feat_final["sample_weight"] = weights
+
+    return feat_final

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:
+    def calculate_quantity(self, balance: float, price: float, leverage: int, margin_ratio: float) -> float:
-        """리스크 기반 포지션 크기 계산 (최소 명목금액 $5 보장)"""
+        """동적 증거금 비율 기반 포지션 크기 계산 (최소 명목금액 $5 보장)"""
-        risk_amount = balance * self.config.risk_per_trade
+        notional = balance * margin_ratio * leverage
-        notional = risk_amount * 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)

src/label_builder.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+
+def build_labels(
+    future_closes: list[float],
+    future_highs: list[float],
+    future_lows: list[float],
+    take_profit: float,
+    stop_loss: float,
+    side: str,
+) -> Optional[int]:
+    for high, low in zip(future_highs, future_lows):
+        if side == "LONG":
+            # 보수적 접근: 손절(SL)을 먼저 체크
+            if low <= stop_loss:
+                return 0
+            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

@@ -0,0 +1,130 @@
+import pandas as pd
+import numpy as np
+
+FEATURE_COLS = [
+    "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_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",
+]
+
+
+def _calc_ret(closes: pd.Series, n: int) -> float:
+    """n캔들 전 대비 수익률. 데이터 부족 시 0.0."""
+    if len(closes) < n + 1:
+        return 0.0
+    prev = closes.iloc[-(n + 1)]
+    return (closes.iloc[-1] - prev) / prev if prev != 0 else 0.0
+
+
+def _calc_rs(xrp_ret: float, other_ret: float) -> float:
+    """상대강도 = xrp_ret / other_ret. 분모 0이면 0.0."""
+    if other_ret == 0.0:
+        return 0.0
+    return xrp_ret / other_ret
+
+
+def build_features(
+    df: pd.DataFrame,
+    signal: str,
+    btc_df: pd.DataFrame | None = None,
+    eth_df: pd.DataFrame | None = None,
+) -> pd.Series:
+    """
+    기술 지표가 계산된 DataFrame의 마지막 행에서 ML 피처를 추출한다.
+    btc_df, eth_df가 제공되면 21개 피처를, 없으면 13개 피처를 반환한다.
+    signal: "LONG" | "SHORT"
+    """
+    last = df.iloc[-1]
+    close = last["close"]
+
+    bb_upper = last.get("bb_upper", close)
+    bb_lower = last.get("bb_lower", close)
+    bb_range = bb_upper - bb_lower
+    bb_pct = (close - bb_lower) / bb_range if bb_range > 0 else 0.5
+
+    ema9  = last.get("ema9",  close)
+    ema21 = last.get("ema21", close)
+    ema50 = last.get("ema50", close)
+    if ema9 > ema21 > ema50:
+        ema_align = 1
+    elif ema9 < ema21 < ema50:
+        ema_align = -1
+    else:
+        ema_align = 0
+
+    atr = last.get("atr", 0)
+    atr_pct = atr / close if close > 0 else 0
+
+    vol_ma20 = last.get("vol_ma20", last.get("volume", 1))
+    vol_ratio = last["volume"] / vol_ma20 if vol_ma20 > 0 else 1.0
+
+    closes = df["close"]
+    ret_1 = _calc_ret(closes, 1)
+    ret_3 = _calc_ret(closes, 3)
+    ret_5 = _calc_ret(closes, 5)
+
+    prev = df.iloc[-2] if len(df) >= 2 else last
+    strength = 0
+    rsi = last.get("rsi", 50)
+    macd = last.get("macd", 0)
+    macd_sig = last.get("macd_signal", 0)
+    prev_macd = prev.get("macd", 0)
+    prev_macd_sig = prev.get("macd_signal", 0)
+    stoch_k = last.get("stoch_k", 50)
+    stoch_d = last.get("stoch_d", 50)
+
+    if signal == "LONG":
+        if rsi < 35: strength += 1
+        if prev_macd < prev_macd_sig and macd > macd_sig: strength += 2
+        if close < last.get("bb_lower", close): strength += 1
+        if ema_align == 1: strength += 1
+        if stoch_k < 20 and stoch_k > stoch_d: strength += 1
+    else:
+        if rsi > 65: strength += 1
+        if prev_macd > prev_macd_sig and macd < macd_sig: strength += 2
+        if close > last.get("bb_upper", close): strength += 1
+        if ema_align == -1: strength += 1
+        if stoch_k > 80 and stoch_k < stoch_d: strength += 1
+
+    base = {
+        "rsi":            float(rsi),
+        "macd_hist":      float(last.get("macd_hist", 0)),
+        "bb_pct":         float(bb_pct),
+        "ema_align":      float(ema_align),
+        "stoch_k":        float(stoch_k),
+        "stoch_d":        float(last.get("stoch_d", 50)),
+        "atr_pct":        float(atr_pct),
+        "vol_ratio":      float(vol_ratio),
+        "ret_1":          float(ret_1),
+        "ret_3":          float(ret_3),
+        "ret_5":          float(ret_5),
+        "signal_strength": float(strength),
+        "side":           1.0 if signal == "LONG" else 0.0,
+    }
+
+    if btc_df is not None and eth_df is not None:
+        btc_ret_1 = _calc_ret(btc_df["close"], 1)
+        btc_ret_3 = _calc_ret(btc_df["close"], 3)
+        btc_ret_5 = _calc_ret(btc_df["close"], 5)
+        eth_ret_1 = _calc_ret(eth_df["close"], 1)
+        eth_ret_3 = _calc_ret(eth_df["close"], 3)
+        eth_ret_5 = _calc_ret(eth_df["close"], 5)
+
+        base.update({
+            "btc_ret_1":  float(btc_ret_1),
+            "btc_ret_3":  float(btc_ret_3),
+            "btc_ret_5":  float(btc_ret_5),
+            "eth_ret_1":  float(eth_ret_1),
+            "eth_ret_3":  float(eth_ret_3),
+            "eth_ret_5":  float(eth_ret_5),
+            "xrp_btc_rs": float(_calc_rs(ret_1, btc_ret_1)),
+            "xrp_eth_rs": float(_calc_rs(ret_1, eth_ret_1)),
+        })
+
+    return pd.Series(base)

src/ml_filter.py

@@ -0,0 +1,149 @@
+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:
+    """
+    ML 필터. ONNX(MLX 신경망) 우선 로드, 없으면 LightGBM으로 폴백한다.
+    둘 다 없으면 항상 진입을 허용한다.
+
+    우선순위: ONNX > LightGBM > 폴백(항상 허용)
+
+    check_and_reload()를 주기적으로 호출하면 모델 파일 변경 시 자동 리로드된다.
+    """
+
+    def __init__(
+        self,
+        onnx_path: str = str(ONNX_MODEL_PATH),
+        lgbm_path: str = str(LGBM_MODEL_PATH),
+        threshold: float = 0.60,
+    ):
+        self._onnx_path = Path(onnx_path)
+        self._lgbm_path = Path(lgbm_path)
+        self._threshold = threshold
+        self._onnx_session = None
+        self._lgbm_model = None
+        self._loaded_onnx_mtime: float = 0.0
+        self._loaded_lgbm_mtime: float = 0.0
+        self._try_load()
+
+    def _try_load(self):
+        # 로드 여부와 무관하게 두 파일의 현재 mtime을 항상 기록한다.
+        # 이렇게 해야 로드하지 않은 쪽 파일이 나중에 변경됐을 때만 리로드가 트리거된다.
+        self._loaded_onnx_mtime = _mtime(self._onnx_path)
+        self._loaded_lgbm_mtime = _mtime(self._lgbm_path)
+
+        # ONNX 우선 시도
+        if self._onnx_path.exists():
+            try:
+                import onnxruntime as ort
+                self._onnx_session = ort.InferenceSession(
+                    str(self._onnx_path),
+                    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"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._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 반환.
+        """
+        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 반환 (폴백).
+        """
+        if not self.is_model_loaded():
+            return True
+        try:
+            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(
+            f"ML 필터 강제 리로드 완료: {prev_backend} → {self.active_backend}"
+        )

src/mlx_filter.py

@@ -0,0 +1,233 @@
+"""
+Apple MLX 기반 경량 신경망 필터.
+M4의 통합 GPU를 자동으로 활용한다.
+학습 후 ONNX로 export해 Linux 서버에서 onnxruntime으로 추론한다.
+"""
+import numpy as np
+import pandas as pd
+import mlx.core as mx
+import mlx.nn as nn
+import mlx.optimizers as optim
+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,)
+        helper.make_node("Flatten", ["proba_2d"],        ["proba"], axis=0),
+    ]
+
+    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, [None])],
+        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 이진 분류기."""
+
+    def __init__(self, input_dim: int, hidden_dim: int):
+        super().__init__()
+        self.fc1 = nn.Linear(input_dim, hidden_dim)
+        self.fc2 = nn.Linear(hidden_dim, hidden_dim // 2)
+        self.fc3 = nn.Linear(hidden_dim // 2, 1)
+        self.dropout = nn.Dropout(p=0.2)
+
+    def __call__(self, x: mx.array) -> mx.array:
+        x = nn.relu(self.fc1(x))
+        x = self.dropout(x)
+        x = nn.relu(self.fc2(x))
+        return self.fc3(x).squeeze(-1)
+
+
+class MLXFilter:
+    """
+    scikit-learn 호환 인터페이스를 제공하는 MLX 신경망 필터.
+    M4 통합 GPU(Metal)를 자동으로 사용한다.
+    """
+
+    def __init__(
+        self,
+        input_dim: int = 13,
+        hidden_dim: int = 64,
+        lr: float = 1e-3,
+        epochs: int = 50,
+        batch_size: int = 256,
+    ):
+        self.input_dim = input_dim
+        self.hidden_dim = hidden_dim
+        self.lr = lr
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self._model = _Net(input_dim, hidden_dim)
+        self._mean: np.ndarray | None = None
+        self._std: np.ndarray | None = None
+        self._trained = False
+
+    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)
+
+        # 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)
+
+        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, w: mx.array | None
+        ) -> mx.array:
+            logits = model(x)
+            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)
+
+        n = len(X_np)
+        for epoch in range(self.epochs):
+            idx = np.random.permutation(n)
+            epoch_loss = 0.0
+            steps = 0
+            for start in range(0, n, self.batch_size):
+                batch_idx = idx[start : start + self.batch_size]
+                x_batch = mx.array(X_np[batch_idx])
+                y_batch = mx.array(y_np[batch_idx])
+                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()
+                steps += 1
+            if (epoch + 1) % 10 == 0:
+                print(f"  Epoch {epoch + 1}/{self.epochs}  loss={epoch_loss / steps:.4f}")
+
+        self._trained = True
+        return self
+
+    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)
+        x = mx.array(X_np)
+        self._model.eval()
+        logits = self._model(x)
+        proba = mx.sigmoid(logits)
+        mx.eval(proba)
+        self._model.train()
+        return np.array(proba)
+
+    def save(self, path: str | Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(exist_ok=True)
+        weights_path = path.with_suffix(".npz")
+        self._model.save_weights(str(weights_path))
+        meta_path = path.with_suffix(".meta.npz")
+        np.savez(
+            meta_path,
+            mean=self._mean,
+            std=self._std,
+            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":
+        path = Path(path)
+        meta = np.load(path.with_suffix(".meta.npz"))
+        obj = cls(
+            input_dim=int(meta["input_dim"]),
+            hidden_dim=int(meta["hidden_dim"]),
+        )
+        obj._mean = meta["mean"]
+        obj._std = meta["std"]
+        obj._model.load_weights(str(path.with_suffix(".npz")))
+        obj._trained = True
+        return obj

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))

tests/test_bot.py

@@ -35,12 +35,23 @@ def sample_df():
     })
 
 
+def test_bot_uses_multi_symbol_stream(config):
+    from src.data_stream import MultiSymbolStream
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+    assert isinstance(bot.stream, MultiSymbolStream)
+
+def test_bot_stream_has_btc_eth_buffers(config):
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+    assert "btcusdt" in bot.stream.buffers
+    assert "ethusdt" in bot.stream.buffers
+
+
 @pytest.mark.asyncio
 async def test_bot_processes_signal(config, sample_df):
-    with patch("src.bot.BinanceFuturesClient") as MockExchange, \
+    with patch("src.bot.BinanceFuturesClient") as MockExchange:
-         patch("src.bot.TradeRepository") as MockRepo:
         MockExchange.return_value = AsyncMock()
-        MockRepo.return_value = MagicMock()
         bot = TradingBot(config)
 
     bot.exchange = AsyncMock()
@@ -48,8 +59,8 @@ async def test_bot_processes_signal(config, sample_df):
     bot.exchange.get_position = AsyncMock(return_value=None)
     bot.exchange.place_order = AsyncMock(return_value={"orderId": "123"})
     bot.exchange.set_leverage = AsyncMock(return_value={})
-    bot.db = MagicMock()
+    bot.exchange.calculate_quantity = MagicMock(return_value=100.0)
-    bot.db.save_trade = MagicMock(return_value={"id": "trade1"})
+    bot.exchange.MIN_NOTIONAL = 5.0
 
     with patch("src.bot.Indicators") as MockInd:
         mock_ind = MagicMock()

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():
+def test_config_dynamic_margin_params():
-    os.environ["NOTION_TOKEN"] = "secret_test"
+    os.environ["MARGIN_MAX_RATIO"] = "0.50"
-    os.environ["NOTION_DATABASE_ID"] = "db_test_id"
+    os.environ["MARGIN_MIN_RATIO"] = "0.20"
+    os.environ["MARGIN_DECAY_RATE"] = "0.0006"
     cfg = Config()
-    assert cfg.notion_token == "secret_test"
+    assert cfg.margin_max_ratio == 0.50
-    assert cfg.notion_database_id == "db_test_id"
+    assert cfg.margin_min_ratio == 0.20
+    assert cfg.margin_decay_rate == 0.0006

tests/test_data_stream.py

@@ -2,6 +2,43 @@ import pytest
 import asyncio
 from unittest.mock import AsyncMock, patch, MagicMock
 from src.data_stream import KlineStream
+from src.data_stream import MultiSymbolStream
+
+
+def test_multi_symbol_stream_has_three_buffers():
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+    )
+    assert "xrpusdt" in stream.buffers
+    assert "btcusdt" in stream.buffers
+    assert "ethusdt" in stream.buffers
+
+def test_multi_symbol_stream_get_dataframe_returns_none_when_empty():
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+    )
+    assert stream.get_dataframe("XRPUSDT") is None
+
+def test_multi_symbol_stream_get_dataframe_returns_df_when_full():
+    import pandas as pd
+    stream = MultiSymbolStream(
+        symbols=["XRPUSDT", "BTCUSDT", "ETHUSDT"],
+        interval="1m",
+        buffer_size=200,
+    )
+    candle = {
+        "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):
+        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
 
 
 @pytest.mark.asyncio

tests/test_dataset_builder.py

@@ -0,0 +1,162 @@
+import numpy as np
+import pandas as pd
+import pytest
+from src.dataset_builder import generate_dataset_vectorized
+
+
+@pytest.fixture
+def sample_df():
+    """최소 200행 이상의 OHLCV 더미 데이터."""
+    rng = np.random.default_rng(42)
+    n = 500
+    close = 2.0 + np.cumsum(rng.normal(0, 0.01, n))
+    close = np.clip(close, 0.01, None)
+    high  = close * (1 + rng.uniform(0, 0.005, n))
+    low   = close * (1 - rng.uniform(0, 0.005, n))
+    return pd.DataFrame({
+        "open":   close,
+        "high":   high,
+        "low":    low,
+        "close":  close,
+        "volume": rng.uniform(1e6, 5e6, n),
+    })
+
+
+def test_returns_dataframe(sample_df):
+    """결과가 DataFrame이어야 한다."""
+    result = generate_dataset_vectorized(sample_df)
+    assert isinstance(result, pd.DataFrame)
+
+
+def test_has_required_columns(sample_df):
+    """기본 13개 피처 + label 컬럼이 모두 있어야 한다."""
+    BASE_FEATURE_COLS = [
+        "rsi", "macd_hist", "bb_pct", "ema_align",
+        "stoch_k", "stoch_d", "atr_pct", "vol_ratio",
+        "ret_1", "ret_3", "ret_5", "signal_strength", "side",
+    ]
+    result = generate_dataset_vectorized(sample_df)
+    if len(result) > 0:
+        assert "label" in result.columns
+        for col in BASE_FEATURE_COLS:
+            assert col in result.columns, f"컬럼 없음: {col}"
+
+
+def test_label_is_binary(sample_df):
+    """label은 0 또는 1만 있어야 한다."""
+    result = generate_dataset_vectorized(sample_df)
+    if len(result) > 0:
+        assert set(result["label"].unique()).issubset({0, 1})
+
+
+def test_generate_dataset_vectorized_with_btc_eth_has_21_feature_cols():
+    """BTC/ETH DataFrame을 전달하면 결과 컬럼이 21개 피처 + label이어야 한다."""
+    import pandas as pd
+    import numpy as np
+    from src.dataset_builder import generate_dataset_vectorized
+    from src.ml_features import FEATURE_COLS
+
+    np.random.seed(42)
+    n = 500
+    closes = np.cumprod(1 + np.random.randn(n) * 0.001) * 1.0
+    xrp_df = pd.DataFrame({
+        "open": closes * 0.999, "high": closes * 1.005,
+        "low": closes * 0.995, "close": closes,
+        "volume": np.random.rand(n) * 1000 + 500,
+    })
+    btc_df = xrp_df.copy() * 50000
+    eth_df = xrp_df.copy() * 3000
+
+    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
+
+
+def test_matches_original_generate_dataset(sample_df):
+    """벡터화 버전과 기존 버전의 샘플 수가 유사해야 한다.
+
+    벡터화 버전은 전체 시계열로 지표를 1회 계산하고, 기존 버전은 61행 슬라이딩
+    윈도우로 매번 재계산한다. EMA 등 지수 이동평균은 초기값에 따라 수렴 속도가
+    달라지므로 두 방식의 신호 수는 완전히 동일하지 않을 수 있다. ±50% 범위를
+    허용한다.
+    """
+    from scripts.train_model import generate_dataset
+    orig = generate_dataset(sample_df, n_jobs=1)
+    vec  = generate_dataset_vectorized(sample_df)
+    if len(orig) == 0:
+        assert len(vec) == 0
+        return
+    ratio = len(vec) / len(orig)
+    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 값 구간에 유한값이 있어야 함"

tests/test_exchange.py

@@ -12,11 +12,19 @@ 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.mark.asyncio
 async def test_set_leverage(config):
     with patch("src.exchange.Client") as MockClient:
@@ -28,11 +36,21 @@ async def test_set_leverage(config):
         assert result is not None
 
 
-def test_calculate_quantity(config):
+def test_calculate_quantity_basic(client):
-    with patch("src.exchange.Client") as MockClient:
+    """잔고 22, 비율 50%, 레버리지 10배 → 명목금액 110, XRP 가격 2.5 → 수량 44.0"""
-        MockClient.return_value = MagicMock()
+    qty = client.calculate_quantity(balance=22.0, price=2.5, leverage=10, margin_ratio=0.50)
-        client = BinanceFuturesClient(config)
+    # 명목금액 = 22 * 0.5 * 10 = 110, 수량 = 110 / 2.5 = 44.0
-        # 잔고 1000 USDT, 리스크 2%, 레버리지 10, 가격 0.5
+    assert qty == pytest.approx(44.0, abs=0.1)
-        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_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

tests/test_label_builder.py

@@ -0,0 +1,73 @@
+import pandas as pd
+import numpy as np
+import pytest
+from src.label_builder import build_labels
+
+
+def make_signal_df():
+    """
+    신호 발생 시점 이후 가격이 TP에 도달하는 시나리오
+    entry=100, TP=103, SL=98.5
+    """
+    future_closes = [100.5, 101.0, 101.8, 102.5, 103.1, 103.5]
+    future_highs  = [c + 0.3 for c in future_closes]
+    future_lows   = [c - 0.3 for c in future_closes]
+    return future_closes, future_highs, future_lows
+
+
+def test_label_tp_reached():
+    closes, highs, lows = make_signal_df()
+    label = build_labels(
+        future_closes=closes,
+        future_highs=highs,
+        future_lows=lows,
+        take_profit=103.0,
+        stop_loss=98.5,
+        side="LONG",
+    )
+    assert label == 1, "TP 먼저 도달해야 레이블 1"
+
+
+def test_label_sl_reached():
+    future_closes = [99.5, 99.0, 98.8, 98.4, 98.0]
+    future_highs  = [c + 0.3 for c in future_closes]
+    future_lows   = [c - 0.3 for c in future_closes]
+    label = build_labels(
+        future_closes=future_closes,
+        future_highs=future_highs,
+        future_lows=future_lows,
+        take_profit=103.0,
+        stop_loss=98.5,
+        side="LONG",
+    )
+    assert label == 0, "SL 먼저 도달해야 레이블 0"
+
+
+def test_label_neither_reached_returns_none():
+    future_closes = [100.1, 100.2, 100.3]
+    future_highs  = [c + 0.1 for c in future_closes]
+    future_lows   = [c - 0.1 for c in future_closes]
+    label = build_labels(
+        future_closes=future_closes,
+        future_highs=future_highs,
+        future_lows=future_lows,
+        take_profit=103.0,
+        stop_loss=98.5,
+        side="LONG",
+    )
+    assert label is None, "미결 시 None 반환"
+
+
+def test_label_short_tp():
+    future_closes = [99.5, 99.0, 98.0, 97.0]
+    future_highs  = [c + 0.3 for c in future_closes]
+    future_lows   = [c - 0.3 for c in future_closes]
+    label = build_labels(
+        future_closes=future_closes,
+        future_highs=future_highs,
+        future_lows=future_lows,
+        take_profit=97.0,
+        stop_loss=101.5,
+        side="SHORT",
+    )
+    assert label == 1

tests/test_ml_features.py

@@ -0,0 +1,113 @@
+import pandas as pd
+import numpy as np
+import pytest
+from src.ml_features import build_features, FEATURE_COLS
+
+
+def _make_df(n=10, base_price=1.0):
+    """테스트용 더미 캔들 DataFrame 생성."""
+    closes = [base_price * (1 + i * 0.001) for i in range(n)]
+    return pd.DataFrame({
+        "close": closes, "high": [c * 1.01 for c in closes],
+        "low": [c * 0.99 for c in closes],
+        "volume": [1000.0] * n,
+        "rsi": [50.0] * n, "macd": [0.0] * n, "macd_signal": [0.0] * n,
+        "macd_hist": [0.0] * n, "bb_upper": [c * 1.02 for c in closes],
+        "bb_lower": [c * 0.98 for c in closes], "ema9": closes,
+        "ema21": closes, "ema50": closes, "atr": [0.01] * n,
+        "stoch_k": [50.0] * n, "stoch_d": [50.0] * n,
+        "vol_ma20": [1000.0] * n,
+    })
+
+
+def test_build_features_with_btc_eth_has_21_features():
+    xrp_df = _make_df(10, base_price=1.0)
+    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
+
+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
+
+def test_build_features_btc_ret_1_correct():
+    xrp_df = _make_df(10, base_price=1.0)
+    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)
+    btc_closes = btc_df["close"]
+    expected_btc_ret_1 = (btc_closes.iloc[-1] - btc_closes.iloc[-2]) / btc_closes.iloc[-2]
+    assert abs(features["btc_ret_1"] - expected_btc_ret_1) < 1e-6
+
+def test_build_features_rs_zero_when_btc_ret_zero():
+    xrp_df = _make_df(10, base_price=1.0)
+    btc_df = _make_df(10, base_price=50000.0)
+    btc_df["close"] = 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 features["xrp_btc_rs"] == 0.0
+
+def test_feature_cols_has_21_items():
+    from src.ml_features import FEATURE_COLS
+    assert len(FEATURE_COLS) == 21
+
+
+def make_df(n=100):
+    """테스트용 최소 DataFrame 생성"""
+    np.random.seed(42)
+    close = 100 + np.cumsum(np.random.randn(n) * 0.5)
+    df = pd.DataFrame({
+        "open":   close * 0.999,
+        "high":   close * 1.002,
+        "low":    close * 0.998,
+        "close":  close,
+        "volume": np.random.uniform(1000, 5000, n),
+    })
+    return df
+
+
+def test_build_features_returns_series():
+    from src.indicators import Indicators
+    df = make_df(100)
+    ind = Indicators(df)
+    df_ind = ind.calculate_all()
+    features = build_features(df_ind, signal="LONG")
+    assert isinstance(features, pd.Series)
+
+
+BASE_FEATURE_COLS = [
+    "rsi", "macd_hist", "bb_pct", "ema_align",
+    "stoch_k", "stoch_d", "atr_pct", "vol_ratio",
+    "ret_1", "ret_3", "ret_5", "signal_strength", "side",
+]
+
+def test_build_features_has_all_cols():
+    from src.indicators import Indicators
+    df = make_df(100)
+    ind = Indicators(df)
+    df_ind = ind.calculate_all()
+    features = build_features(df_ind, signal="LONG")
+    for col in BASE_FEATURE_COLS:
+        assert col in features.index, f"피처 누락: {col}"
+
+
+def test_build_features_no_nan():
+    from src.indicators import Indicators
+    df = make_df(100)
+    ind = Indicators(df)
+    df_ind = ind.calculate_all()
+    features = build_features(df_ind, signal="LONG")
+    assert not features.isna().any(), f"NaN 존재: {features[features.isna()]}"
+
+
+def test_side_encoding():
+    from src.indicators import Indicators
+    df = make_df(100)
+    ind = Indicators(df)
+    df_ind = ind.calculate_all()
+    long_feat  = build_features(df_ind, signal="LONG")
+    short_feat = build_features(df_ind, signal="SHORT")
+    assert long_feat["side"] == 1
+    assert short_feat["side"] == 0

tests/test_ml_filter.py

@@ -0,0 +1,63 @@
+import pandas as pd
+import numpy as np
+import pytest
+from unittest.mock import MagicMock, patch
+from pathlib import Path
+from src.ml_filter import MLFilter
+from src.ml_features import FEATURE_COLS
+
+
+def make_features(side="LONG") -> pd.Series:
+    return pd.Series({col: 0.5 for col in FEATURE_COLS} | {"side": 1.0 if side == "LONG" else 0.0})
+
+
+def test_no_model_file_is_not_loaded(tmp_path):
+    f = MLFilter(model_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"))
+    features = make_features()
+    assert f.should_enter(features) is True
+
+
+def test_should_enter_above_threshold():
+    """확률 >= 0.60 이면 True"""
+    f = MLFilter(threshold=0.60)
+    mock_model = MagicMock()
+    mock_model.predict_proba.return_value = np.array([[0.35, 0.65]])
+    f._model = mock_model
+    features = make_features()
+    assert f.should_enter(features) is True
+
+
+def test_should_enter_below_threshold():
+    """확률 < 0.60 이면 False"""
+    f = MLFilter(threshold=0.60)
+    mock_model = MagicMock()
+    mock_model.predict_proba.return_value = np.array([[0.55, 0.45]])
+    f._model = mock_model
+    features = make_features()
+    assert f.should_enter(features) is False
+
+
+def test_reload_model(tmp_path):
+    """reload_model 호출 후 모델 로드 상태 변경"""
+    import joblib
+
+    # 모델 파일이 없는 상태에서 시작
+    model_path = tmp_path / "lgbm_filter.pkl"
+    f = MLFilter(model_path=str(model_path))
+    assert not f.is_model_loaded()
+
+    # _model을 직접 주입해서 is_model_loaded가 True인지 확인
+    mock_model = MagicMock()
+    f._model = mock_model
+    assert f.is_model_loaded()
+
+    # reload_model 호출 시 파일이 없으면 _try_load가 _model을 변경하지 않음
+    # (기존 동작 유지 - 파일 없으면 None으로 초기화하지 않음)
+    f.reload_model()
+    assert f.is_model_loaded()  # mock_model이 유지됨

tests/test_mlx_filter.py

@@ -0,0 +1,111 @@
+"""
+MLXFilter 단위 테스트.
+Apple Silicon GPU(Metal)가 없는 환경에서는 스킵한다.
+"""
+import numpy as np
+import pandas as pd
+import pytest
+
+mlx = pytest.importorskip("mlx.core", reason="MLX 미설치")
+
+
+def _make_X(n: int = 4) -> pd.DataFrame:
+    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),
+        }
+    )
+
+
+def test_mlx_gpu_device():
+    """MLX가 GPU 디바이스를 기본으로 사용해야 한다."""
+    import mlx.core as mx
+
+    device = mx.default_device()
+    assert "gpu" in str(device)
+
+
+def test_mlx_filter_predict_shape_untrained():
+    """학습 전에도 predict_proba가 (N,) 형태를 반환해야 한다."""
+    from src.mlx_filter import MLXFilter
+
+    X = _make_X(4)
+    model = MLXFilter(input_dim=13, hidden_dim=32)
+    proba = model.predict_proba(X)
+    assert proba.shape == (4,)
+    assert np.all((proba >= 0.0) & (proba <= 1.0))
+
+
+def test_mlx_filter_fit_and_predict():
+    """학습 후 predict_proba가 유효한 확률값을 반환해야 한다."""
+    from src.mlx_filter import MLXFilter
+
+    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.fit(X, y)
+    proba = model.predict_proba(X)
+
+    assert proba.shape == (n,)
+    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
+
+    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.fit(X, y)
+    proba_before = model.predict_proba(X)
+
+    save_path = tmp_path / "mlx_filter.weights"
+    model.save(save_path)
+
+    loaded = MLXFilter.load(save_path)
+    proba_after = loaded.predict_proba(X)
+
+    np.testing.assert_allclose(proba_before, proba_after, atol=1e-5)

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)