feat: enhance trading bot functionality and documentation

- Updated README.md to reflect new features including dynamic margin ratio, model hot-reload, and multi-symbol streaming.
- Modified bot logic to ensure raw signals are passed to the `_close_and_reenter` method, even when the ML filter is loaded.
- Introduced a new script `run_tests.sh` for streamlined test execution.
- Improved test coverage for signal processing and re-entry logic, ensuring correct behavior under various conditions.

README.md

@@ -1,18 +1,23 @@
 # CoinTrader
 
-Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.
+Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / MLX 신경망)를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.
 
 ---
 
 ## 주요 기능
 
-- **복합 기술 지표 신호**: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 3개 이상 일치 시 진입
+- **복합 기술 지표 신호**: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 가중치 합계 ≥ 3 시 진입
-- **ML 필터 (LightGBM)**: 기술 지표 신호를 한 번 더 검증하여 오진입 차단 (모델 없으면 자동 폴백)
+- **ML 필터 (ONNX 우선 / LightGBM 폴백)**: 기술 지표 신호를 한 번 더 검증하여 오진입 차단. 우선순위: ONNX > LightGBM > 폴백(항상 허용)
+- **모델 핫리로드**: 캔들마다 모델 파일 mtime을 감지해 변경 시 자동 리로드 (봇 재시작 불필요)
+- **멀티심볼 스트림**: XRP/BTC/ETH 3개 심볼을 단일 Combined WebSocket으로 수신, BTC·ETH 상관관계 피처 활용
+- **23개 ML 피처**: XRP 기술 지표 13개 + BTC/ETH 수익률·상대강도 8개 + OI 변화율·펀딩비 2개
 - **ATR 기반 손절/익절**: 변동성에 따라 동적으로 SL/TP 계산 (1.5× / 3.0× ATR)
-- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도 제어
+- **동적 증거금 비율**: 잔고 증가에 따라 선형 감소 (최대 50% → 최소 20%)
+- **반대 시그널 재진입**: 보유 포지션과 반대 신호 발생 시 즉시 청산 후 ML 필터 통과 시 반대 방향 재진입
+- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도(5%) 제어
 - **포지션 복구**: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원
 - **Discord 알림**: 진입·청산·오류 이벤트 실시간 웹훅 알림
-- **CI/CD**: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포
+- **CI/CD**: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포 (LXC 운영 서버 자동 적용)
 
 ---
 
@@ -20,27 +25,33 @@ Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를
 
 ```
 cointrader/
-├── main.py                  # 진입점
+├── main.py                    # 진입점
 ├── src/
-│   ├── bot.py               # 메인 트레이딩 루프
+│   ├── bot.py                 # 메인 트레이딩 루프
-│   ├── config.py            # 환경변수 기반 설정
+│   ├── config.py              # 환경변수 기반 설정
-│   ├── exchange.py          # Binance Futures API 클라이언트
+│   ├── exchange.py            # Binance Futures API 클라이언트
-│   ├── data_stream.py       # WebSocket 1분봉 스트림
+│   ├── data_stream.py         # WebSocket 15분봉 멀티심볼 스트림 (XRP/BTC/ETH)
-│   ├── indicators.py        # 기술 지표 계산 및 신호 생성
+│   ├── indicators.py          # 기술 지표 계산 및 신호 생성
-│   ├── ml_filter.py         # LightGBM 진입 필터
+│   ├── ml_filter.py           # ML 필터 (ONNX 우선 / LightGBM 폴백 / 핫리로드)
-│   ├── ml_features.py       # ML 피처 빌더
+│   ├── ml_features.py         # ML 피처 빌더 (23개 피처)
-│   ├── label_builder.py     # 학습 레이블 생성
+│   ├── mlx_filter.py          # MLX 신경망 필터 (Apple Silicon GPU 학습 + ONNX export)
-│   ├── dataset_builder.py   # 벡터화 데이터셋 빌더 (학습용)
+│   ├── label_builder.py       # 학습 레이블 생성
-│   ├── risk_manager.py      # 리스크 관리
+│   ├── dataset_builder.py     # 벡터화 데이터셋 빌더 (학습용)
-│   ├── notifier.py          # Discord 웹훅 알림
+│   ├── risk_manager.py        # 리스크 관리 (일일 손실 한도, 동적 증거금 비율)
-│   └── logger_setup.py      # Loguru 로거 설정
+│   ├── notifier.py            # Discord 웹훅 알림
+│   └── logger_setup.py        # Loguru 로거 설정
 ├── scripts/
-│   ├── fetch_history.py     # 과거 데이터 수집
+│   ├── fetch_history.py       # 과거 데이터 수집 (XRP/BTC/ETH + OI/펀딩비)
-│   └── train_model.py       # ML 모델 수동 학습
+│   ├── train_model.py         # LightGBM 모델 학습 (CPU)
-├── models/                  # 학습된 모델 저장 (.pkl)
+│   ├── train_mlx_model.py     # MLX 신경망 학습 (Apple Silicon GPU)
-├── data/                    # 과거 데이터 캐시
+│   ├── train_and_deploy.sh    # 전체 파이프라인 (수집 → 학습 → LXC 배포)
-├── logs/                    # 로그 파일
+│   ├── deploy_model.sh        # 모델 파일 LXC 서버 전송
-├── tests/                   # 테스트 코드
+│   └── run_tests.sh           # 전체 테스트 실행
+├── models/                    # 학습된 모델 저장 (.pkl / .onnx)
+├── data/                      # 과거 데이터 캐시 (.parquet)
+├── logs/                      # 로그 파일
+├── docs/plans/                # 설계 문서 및 구현 플랜
+├── tests/                     # 테스트 코드
 ├── Dockerfile
 ├── docker-compose.yml
 ├── Jenkinsfile
@@ -64,7 +75,6 @@ BINANCE_API_KEY=your_api_key
 BINANCE_API_SECRET=your_api_secret
 SYMBOL=XRPUSDT
 LEVERAGE=10
-RISK_PER_TRADE=0.02
 DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
 ```
 
@@ -91,17 +101,50 @@ docker compose logs -f cointrader
 
 ## ML 모델 학습
 
-봇은 모델 파일(`models/lgbm_filter.pkl`)이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.
+봇은 모델 파일이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.
+
+### 전체 파이프라인 (권장)
+
+맥미니에서 데이터 수집 → 학습 → LXC 배포까지 한 번에 실행합니다.
 
 ```bash
-# 1. 과거 데이터 수집
+# LightGBM + Walk-Forward 5폴드 (기본값)
-python scripts/fetch_history.py
+bash scripts/train_and_deploy.sh
 
-# 2. 모델 학습 (LightGBM, CPU)
+# MLX GPU 학습 + Walk-Forward 5폴드
-python scripts/train_model.py
+bash scripts/train_and_deploy.sh mlx
+
+# LightGBM + Walk-Forward 3폴드
+bash scripts/train_and_deploy.sh lgbm 3
+
+# 학습만 (배포 없이)
+bash scripts/train_and_deploy.sh lgbm 0
 ```
 
-학습된 모델은 `models/lgbm_filter.pkl`에 저장됩니다. 재학습이 필요하면 맥미니에서 위 스크립트를 다시 실행하고 모델 파일을 컨테이너에 배포합니다.
+### 단계별 수동 실행
+
+```bash
+# 1. 과거 데이터 수집 (XRP/BTC/ETH 3심볼, 15분봉, 1년치 + OI/펀딩비)
+python scripts/fetch_history.py \
+    --symbols XRPUSDT BTCUSDT ETHUSDT \
+    --interval 15m \
+    --days 365 \
+    --output data/combined_15m.parquet
+
+# 2-A. LightGBM 모델 학습 (CPU)
+python scripts/train_model.py --data data/combined_15m.parquet
+
+# 2-B. MLX 신경망 학습 (Apple Silicon GPU)
+python scripts/train_mlx_model.py --data data/combined_15m.parquet
+
+# 3. LXC 서버에 모델 배포
+bash scripts/deploy_model.sh        # LightGBM
+bash scripts/deploy_model.sh mlx    # MLX (ONNX)
+```
+
+학습된 모델은 `models/lgbm_filter.pkl` (LightGBM) 또는 `models/mlx_filter.weights.onnx` (MLX) 에 저장됩니다.
+
+> **모델 핫리로드**: 봇이 실행 중일 때 모델 파일을 교체하면, 다음 캔들 마감 시 자동으로 감지해 리로드합니다. 봇 재시작이 필요 없습니다.
 
 ### Apple Silicon GPU 가속 학습 (M1/M2/M3/M4)
 
@@ -110,23 +153,16 @@ M 시리즈 맥에서는 MLX를 사용해 통합 GPU(Metal)로 학습할 수 있
 > **설치**: `mlx`는 Apple Silicon 전용이며 `requirements.txt`에 포함되지 않습니다.
 > 맥미니에서 별도 설치: `pip install mlx`
 
-```bash
+MLX로 학습한 모델은 ONNX 포맷으로 export되어 Linux 서버에서 `onnxruntime`으로 추론합니다.
-# MLX 별도 설치 (맥미니 전용)
-pip install mlx
 
-# MLX 신경망 필터 학습 (GPU 자동 사용)
+> **참고**: LightGBM은 Apple Silicon GPU를 공식 지원하지 않습니다. MLX는 Apple이 만든 ML 프레임워크로 통합 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에서 직접 제어할 수 없습니다.
 
 ---
 
 ## 매매 전략
 
+### 기술 지표 신호 (15분봉)
+
 | 지표 | 롱 조건 | 숏 조건 | 가중치 |
 |------|---------|---------|--------|
 | RSI (14) | < 35 | > 65 | 1 |
@@ -138,7 +174,13 @@ TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
 
 **진입 조건**: 가중치 합계 ≥ 3 + (거래량 급증 또는 가중치 합계 ≥ 4)  
 **손절/익절**: ATR × 1.5 / ATR × 3.0 (리스크:리워드 = 1:2)  
-**ML 필터**: LightGBM 예측 확률 ≥ 0.60 이어야 최종 진입
+**ML 필터**: 예측 확률 ≥ 0.60 이어야 최종 진입
+
+### 반대 시그널 재진입
+
+보유 포지션과 반대 방향 신호가 발생하면:
+1. 기존 포지션 즉시 청산 (미체결 SL/TP 주문 취소 포함)
+2. ML 필터 통과 시 반대 방향으로 즉시 재진입
 
 ---
 
@@ -146,22 +188,27 @@ TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh
 
 `main` 브랜치에 푸시하면 Jenkins 파이프라인이 자동으로 실행됩니다.
 
-1. **Checkout** — 소스 체크아웃
+1. **Notify Build Start** — Discord 빌드 시작 알림
-2. **Build Image** — Docker 이미지 빌드 (`:{BUILD_NUMBER}` + `:latest` 태그)
+2. **Git Clone from Gitea** — 소스 체크아웃
-3. **Push** — Gitea Container Registry(`10.1.10.28:3000`)에 푸시
+3. **Build Docker Image** — Docker 이미지 빌드 (`:{BUILD_NUMBER}` + `:latest` 태그)
-4. **Cleanup** — 로컬 이미지 정리
+4. **Push to Gitea Registry** — Gitea Container Registry(`10.1.10.28:3000`)에 푸시
+5. **Deploy to Prod LXC** — 운영 LXC 서버(`10.1.10.24`)에 자동 배포 (`docker compose pull && up -d`)
+6. **Cleanup** — 빌드 서버 로컬 이미지 정리
 
-배포 서버에서 최신 이미지를 반영하려면:
+빌드 성공/실패 결과는 Discord로 자동 알림됩니다.
-
-```bash
-docker compose pull && docker compose up -d
-```
 
 ---
 
 ## 테스트
 
 ```bash
+# 전체 테스트
+bash scripts/run_tests.sh
+
+# 특정 키워드 필터
+bash scripts/run_tests.sh -k bot
+
+# pytest 직접 실행
 pytest tests/ -v
 ```
 
@@ -175,13 +222,15 @@ pytest tests/ -v
 | `BINANCE_API_SECRET` | — | Binance API 시크릿 |
 | `SYMBOL` | `XRPUSDT` | 거래 심볼 |
 | `LEVERAGE` | `10` | 레버리지 배수 |
-| `RISK_PER_TRADE` | `0.02` | 트레이드당 리스크 비율 (2%) |
 | `DISCORD_WEBHOOK_URL` | — | Discord 웹훅 URL |
+| `MARGIN_MAX_RATIO` | `0.50` | 최대 증거금 비율 (잔고 대비 50%) |
+| `MARGIN_MIN_RATIO` | `0.20` | 최소 증거금 비율 (잔고 대비 20%) |
+| `MARGIN_DECAY_RATE` | `0.0006` | 잔고 증가 시 증거금 비율 감소 속도 |
 
 ---
 
 ## 주의사항
 
 > **이 봇은 실제 자산을 거래합니다.** 운영 전 반드시 Binance Testnet에서 충분히 검증하세요.  
-> 과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다.
+> 과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다.  
 > 성투기원합니다.

scripts/run_tests.sh

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

src/bot.py

@@ -58,32 +58,32 @@ class TradingBot:
 
         ind = Indicators(df)
         df_with_indicators = ind.calculate_all()
-        signal = ind.get_signal(df_with_indicators)
+        raw_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")
+        logger.info(f"신호: {raw_signal} | 현재가: {current_price:.4f} USDT")
 
         position = await self.exchange.get_position()
 
-        if position is None and signal != "HOLD":
+        if position is None and raw_signal != "HOLD":
             self.current_trade_side = None
             if not self.risk.can_open_new_position():
                 logger.info("최대 포지션 수 도달")
                 return
+            signal = raw_signal
+            if 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} 신호 무시")
+                    return
             await self._open_position(signal, df_with_indicators)
 
         elif position is not None:
             pos_side = "LONG" if float(position["positionAmt"]) > 0 else "SHORT"
-            if (pos_side == "LONG" and signal == "SHORT") or \
+            if (pos_side == "LONG" and raw_signal == "SHORT") or \
-               (pos_side == "SHORT" and signal == "LONG"):
+               (pos_side == "SHORT" and raw_signal == "LONG"):
                 await self._close_and_reenter(
-                    position, signal, df_with_indicators, btc_df=btc_df, eth_df=eth_df
+                    position, raw_signal, df_with_indicators, btc_df=btc_df, eth_df=eth_df
                 )
 
     async def _open_position(self, signal: str, df):

tests/test_bot.py

@@ -79,6 +79,8 @@ async def test_close_and_reenter_calls_open_when_ml_passes(config, sample_df):
 
     bot._close_position = AsyncMock()
     bot._open_position = AsyncMock()
+    bot.risk = MagicMock()
+    bot.risk.can_open_new_position.return_value = True
     bot.ml_filter = MagicMock()
     bot.ml_filter.is_model_loaded.return_value = True
     bot.ml_filter.should_enter.return_value = True
@@ -154,3 +156,35 @@ async def test_process_candle_calls_close_and_reenter_on_reverse_signal(config,
     bot._close_and_reenter.assert_awaited_once()
     call_args = bot._close_and_reenter.call_args
     assert call_args.args[1] == "SHORT"
+
+
+@pytest.mark.asyncio
+async def test_process_candle_passes_raw_signal_to_close_and_reenter_even_if_ml_loaded(config, sample_df):
+    """포지션 보유 시 ML 필터가 로드되어 있어도 process_candle은 raw signal을 _close_and_reenter에 전달한다."""
+    with patch("src.bot.BinanceFuturesClient"):
+        bot = TradingBot(config)
+
+    bot.exchange = AsyncMock()
+    bot.exchange.get_position = AsyncMock(return_value={
+        "positionAmt": "100",
+        "entryPrice": "0.5",
+        "markPrice": "0.52",
+    })
+    bot._close_and_reenter = AsyncMock()
+    bot.ml_filter = MagicMock()
+    bot.ml_filter.is_model_loaded.return_value = True  # 모델 로드됨
+    bot.ml_filter.should_enter.return_value = False    # ML이 차단하더라도
+
+    with patch("src.bot.Indicators") as MockInd:
+        mock_ind = MagicMock()
+        mock_ind.calculate_all.return_value = sample_df
+        mock_ind.get_signal.return_value = "SHORT"
+        MockInd.return_value = mock_ind
+        await bot.process_candle(sample_df)
+
+    # ML 필터가 차단해도 _close_and_reenter는 호출되어야 한다 (ML 재평가는 내부에서)
+    bot._close_and_reenter.assert_awaited_once()
+    call_args = bot._close_and_reenter.call_args
+    assert call_args.args[1] == "SHORT"
+    # process_candle에서 ml_filter.should_enter가 호출되지 않아야 한다
+    bot.ml_filter.should_enter.assert_not_called()