ZeroQuant

⚠️ 투자 관련 안내사항 (Disclaimer)

본 소프트웨어는 학습 및 연구 목적으로 개발되었습니다.

투자 권유가 아닙니다: 본 시스템의 신호, 분석, 전략은 투자 조언이나 권유가 아닙니다.

손실 위험: 모든 투자에는 원금 손실의 위험이 있습니다. 과거 성과가 미래 수익을 보장하지 않습니다.

자기 책임: 본 소프트웨어를 사용한 모든 투자 결정과 그 결과는 사용자 본인의 책임입니다.

전문가 상담 권장: 실제 투자 전 공인된 금융 전문가와 상담하시기 바랍니다.

테스트 권장: 실제 자금 투입 전 모의투자 환경에서 충분히 테스트하세요.

개발자는 본 소프트웨어 사용으로 인한 직접적, 간접적 손실에 대해 어떠한 책임도 지지 않습니다.

ZeroQuant

Rust 기반 고성능 다중 시장 자동화 트레이딩 시스템

주요 기능 • 지원 전략 • 설치 가이드 • 수집기 • 마이그레이션 • 전략 개발 • 문서

소개

ZeroQuant는 암호화폐와 주식 시장에서 24/7 자동화된 거래를 수행하는 트레이딩 시스템입니다.

검증된 16가지 통합 전략과 59개 ML 패턴 인식 (캔들스틱 35개 + 차트 패턴 24개)을 통해 그리드 트레이딩, 자산배분, 모멘텀 등 다양한 투자 방법론을 지원합니다. 웹 대시보드에서 실시간 모니터링과 전략 제어가 가능하며, 리스크 관리 시스템이 자동으로 자산을 보호합니다.

⚠️ v0.8.3 쿼리 최적화, 백테스트 타임프레임 폴백, UI 성능: OHLCV 배치 쿼리를 LATERAL JOIN + TimescaleDB 청크 프루닝으로 ~70% 최적화하고, 백테스트/CLI에 전략 기본 타임프레임 자동 폴백을 도입했습니다. 스크리닝 가상 스크롤(11,000+ 행 60fps), 상태/등급/점수 정렬, 매매일지 상세 통계가 추가되었습니다.

주요 기능

🏦 다중 시장 지원

시장	거래소	기능
암호화폐	Binance	현물 거래, WebSocket 실시간 시세
암호화폐 (KR)	Upbit, Bithumb	원화 마켓, WebSocket 실시간 시세
한국/미국 주식	한국투자증권 (KIS)	국내/해외 주식, WebSocket 실시간 시세, 모의투자 지원
한국 주식	DB금융투자, LS증권	국내 주식, WebSocket 실시간 시세

📝 Paper Trading (v0.8.0)

가상 계좌 시뮬레이션: 실시간 시세 기반 가상 거래 실행
전략 검증: 실제 자금 없이 전략 성과 검증
실시간 포지션 추적: 가상 포지션 및 체결 내역 실시간 모니터링
계좌 초기화: 가상 계좌 리셋 후 재시작 가능

📊 데이터 & 분석

다중 데이터 소스: KRX OPEN API, 네이버 금융 (국내), Yahoo Finance (해외/암호화폐)
- 데이터 프로바이더 토글 지원 (PROVIDER_KRX_API_ENABLED, PROVIDER_YAHOO_ENABLED, NAVER_FUNDAMENTAL_ENABLED)
- 네이버 금융 크롤링으로 국내 펀더멘털 데이터 수집 속도 개선
다중 타임프레임 분석: 여러 시간대 데이터 동시 분석 (1분~월봉)
- Look-Ahead Bias 방지 자동 정렬
- 크로스 타임프레임 시그널 결합
실시간 시세: WebSocket 기반 실시간 가격/호가/체결 (KIS 국내/해외 + Binance)
- Singleton 스트림 관리 (credential별 하나의 WebSocket)
- 동적 구독/해제 (전략 추가/삭제 시 런타임 반영)
- 프론트엔드 구독 → 거래소 스트림 자동 브릿지
OHLCV 배치 쿼리: LATERAL JOIN + TimescaleDB 청크 프루닝으로 2,500+ 심볼 동시 조회 300ms 이내
과거 데이터: TimescaleDB 시계열 저장, 백테스팅 지원
데이터셋 관리: Yahoo Finance 데이터 다운로드, 캔들 데이터 CRUD
백그라운드 수집: 펀더멘털 데이터 자동 수집, 심볼 자동 동기화 (KRX/Binance/Yahoo)
ML 패턴 인식: 캔들스틱 35개 + 차트 패턴 24개 (ONNX 추론)
ML 모델 훈련: XGBoost, LightGBM, RandomForest, 앙상블 지원
성과 지표: Sharpe Ratio, MDD, Win Rate, CAGR 등

🎯 고급 스코어링 시스템

Global Score Ranking: 7개 팩터 기반 종합 종목 평가
- VolumeQuality, Momentum, ValueFactor, RouteState 등
- 페널티 시스템 (LiquidityGate, MarketRegime 필터)
7Factor Scoring: 정규화된 다요인 분석 (0-100 점수)
- Momentum, Value, Quality, Volatility, Liquidity, Growth, Sentiment
RouteState Calculator: 진입 타이밍 자동 판단
- ATTACK (진입 적기), ARMED (대기), WAIT (관찰), OVERHEAT (과열)
- TTM Squeeze, 모멘텀, RSI, Range 종합 분석
Market Regime: 5단계 추세 분류 (STRONG_UPTREND → DOWNTREND)
Reality Check: 추천 종목 실제 성과 자동 검증
- 전일 추천 → 익일 성과 자동 계산
- 일별/소스별/랭크별 승률 통계

🤖 알림 & 모니터링

다채널 알림: Telegram, Discord, Slack, Email, SMS (Twilio) 지원
- 포지션 현황 및 손익 업데이트
- 거래 체결 알림
- 전략 신호 알림
Signal System: 백테스트/실거래 신호 저장
- 신호 마커 (차트 표시용)
- 알림 규칙 관리 (JSONB 필터)

🛡️ 리스크 관리

ExitConfig 통합 리스크 관리 (v0.8.2): 6가지 리스크 옵션을 전략별로 조합
- StopLoss: 고정 % 손절 또는 ATR(평균 진폭 범위) 기반 동적 손절
- TakeProfit: 고정 % 익절
- TrailingStop: 4가지 모드 (고정 %, ATR 기반, 단계별 Step, Parabolic SAR)
- ProfitLock: 수익 보호 — 목표 수익 달성 후 일정 비율 이하 하락 시 자동 청산
- DailyLossLimit: 일일 최대 손실 비율 초과 시 거래 중단
- 반대 신호 청산: 보유 중 반대 방향 신호 발생 시 즉시 청산
6가지 프리셋 제공 (day_trading, mean_reversion, grid, rebalancing, leverage, momentum)
전략마다 exit_config() trait 메서드로 리스크 설정을 엔진에 전달
enrich_signal(): Entry 신호에 SL/TP 가격 자동 계산, 트레일링/수익잠금은 metadata로 executor에 전달
Circuit Breaker 패턴 (에러 카테고리별 차등 임계치)
API 재시도 시스템 (지수 백오프, Rate Limit 대응)

🖥️ 웹 대시보드

실시간 포트폴리오 모니터링
전략 등록/시작/중지/설정 (SDUI 동적 폼)
데이터셋 관리 (심볼 데이터 다운로드/조회/삭제)
백테스트 실행 및 결과 저장/비교
ML 모델 훈련 및 관리
동기화된 멀티 차트 패널
거래소 API 키 관리 (AES-256-GCM 암호화)

📒 매매일지 (Trading Journal)

거래 내역을 체계적으로 관리하고 투자 성과를 분석합니다:

체결 내역 동기화: 거래소 API에서 자동 수집
종목별 보유 현황: 보유 수량, 평균 매입가, 투자 금액
물타기 자동 계산: 추가 매수 시 가중평균 매입가 자동 갱신
FIFO 실현손익: 선입선출 방식 실현손익 계산 (로트별 추적)
손익 분석: 실현/미실현 손익, 기간별 수익률
매매 패턴 분석: 빈도, 성공률, 평균 보유 기간
포트폴리오 비중: 종목별 비중 시각화 및 리밸런싱 추천
백테스트 인사이트: 매수/매도 건수, 총 거래량, 활성 거래일, 최대 수익/손실 등 상세 통계

지원 전략

통합 전략 (v0.7.0)

📈 단기/분할 전략

전략	설명
DCA	분할매수 전략 (그리드, 분할, 무한 매수)
Day Trading	단기 매매 전략
Mean Reversion	평균회귀 전략
Candle Pattern	캔들스틱 패턴 인식

📊 모멘텀/로테이션 전략

전략	설명
Rotation	모멘텀 로테이션 전략
Compound Momentum	공격/안전 자산 전환
Momentum Power	ETF 모멘텀 전략

🏦 자산배분 전략

전략	설명
Asset Allocation	자산배분 전략
Pension Portfolio	연금 포트폴리오 전략

🎯 기타 전략

전략	설명
Sector VB	변동성 돌파 전략
US 3X Leverage	레버리지 ETF 전략
Momentum Surge	급등 모멘텀 전략
Market BothSide	양방향 매매 전략
Small Cap Quant	소형주 퀀트 전략
Range Trading	구간별 분할 매매
RSI Multi Timeframe	다중 타임프레임 전략

전략 실행 아키텍처 (v0.8.0)

전략은 데이터 소스와 주문 실행 방식을 알 필요 없이, Signal만 발행하면 됩니다. 데이터와 실행은 의존성 주입으로 교체됩니다.

실행 흐름

┌─────────────────────────────────────────┐
│  DataProvider (교체 가능)                │
│  • ExchangeProvider (실시간 데이터)      │
│  • BacktestEngine (과거 데이터)          │
└─────────────────┬───────────────────────┘
                  ▼
           ┌─────────────┐
           │   Strategy   │ → Signal 발행
           └──────┬──────┘
                  ▼
┌─────────────────────────────────────────┐
│  SignalProcessor (교체 가능)             │
│  • LiveExecutor (실제 주문)              │
│  • SimulatedExecutor (가상 체결)         │
└─────────────────────────────────────────┘

실행 모드 조합

데이터 소스	Signal 처리	결과
ExchangeProvider	LiveExecutor	실거래
ExchangeProvider	SimulatedExecutor	페이퍼 트레이딩
BacktestEngine	SimulatedExecutor	백테스트

SignalProcessor trait

SignalProcessor는 전략이 발행한 Signal을 받아 주문을 실행하는 핵심 trait입니다.

#[async_trait]
pub trait SignalProcessor: Send + Sync {
    /// Signal 수신 → 주문 실행 → TradeResult 반환
    async fn process_signal(&mut self, signal: &Signal, price: Decimal) -> Result<Option<TradeResult>>;

    /// 잔고 / 포지션 / 체결 내역 조회
    fn balance(&self) -> Decimal;
    fn positions(&self) -> &HashMap<String, ProcessorPosition>;
    fn trades(&self) -> &[TradeResult];

    /// 그룹별 포지션 관리 (그리드/분할매수 전략용)
    fn positions_by_group(&self, group_id: &str) -> Vec<&ProcessorPosition>;
    fn position_keys_by_group(&self, group_id: &str) -> Vec<String>;
    fn group_unrealized_pnl(&self, group_id: &str, current_prices: &HashMap<String, Decimal>) -> Decimal;
}

구현체	위치	용도
`SimulatedExecutor`	`trader-execution/src/simulated_executor.rs`	백테스트, 페이퍼 트레이딩
`LiveExecutor`	`trader-execution/src/live_executor.rs`	실거래 (OrderExecutionProvider 주입) [v0.8.1]
`OrderExecutor` (레거시)	`trader-execution/src/executor.rs`	레거시 실행기

Position ID / Group ID 시스템

스프레드 기반 전략(그리드, 분할매수 등)에서 레벨별 독립 포지션 관리를 지원합니다.

Signal {
    ticker: "005930",              // 실제 거래 심볼
    position_id: "005930_grid_L1", // 개별 포지션 식별
    group_id: "grid_55000_1707..", // 관련 포지션 그룹
}

전략	position_id 형식	group_id 형식
Grid Trading	`{ticker}_grid_L{level}`	`grid_{base_price}_{timestamp}`
Magic Split	`{ticker}_split_L{level}`	`split_{ticker}_{timestamp}`
Infinity Bot	`{ticker}_inf_R{round}`	`inf_{ticker}_{timestamp}` [v0.8.1]

StrategyContext (전략 컨텍스트)

전략에 주입되는 Arc<RwLock<StrategyContext>>는 거래소 데이터와 분석 데이터를 통합 제공합니다.

StrategyContext
├── 거래소 데이터 (1~5초 갱신)
│   ├── account          # 계좌 정보 (잔고, 증거금)
│   ├── positions         # 보유 포지션
│   ├── pending_orders    # 미체결 주문
│   └── exchange_constraints # 거래소 제약 (최소 주문량, 수수료율)
│
├── 분석 데이터 (1~10분 갱신)
│   ├── global_scores     # 종목별 종합 점수 (7팩터)
│   ├── route_states      # 종목별 진입 상태 (ATTACK/ARMED/WAIT/OVERHEAT)
│   ├── screening_results # 스크리닝 결과
│   ├── structural_features # 구조적 피처 (추세, 변동성)
│   ├── trigger_results   # 진입 트리거 결과 (급등시동, 박스돌파 등)
│   ├── market_regime     # 시장 국면 (5단계)
│   ├── market_breadth    # 시장 폭 지표
│   └── macro_environment # 매크로 환경
│
└── 시장 데이터
    └── klines_by_timeframe # 멀티 타임프레임 캔들 데이터

전략별 권장 활용 (v0.8.1 재설계):

전략 유형	RouteState	GlobalScore	스크리닝
단일 티커	Overheat만 차단	미사용 또는 강도 조정	-
US ETF (자산배분/모멘텀)	Overheat만 차단	미사용 (자체 모멘텀)	-
로테이션 (KR)	Overheat만 차단	필터 유지	`get_tickers_by_global_score`
로테이션 (US)	Overheat만 차단	미사용	-
DCA (Grid/분할매수)	미사용 (순수 가격 기반)	미사용	-
캔들 패턴	Overheat만 차단	강도 조정 (0.75x~1.25x)	-

Signal Filter 시스템 (v0.8.0)

전략이 발행한 Signal을 실행 전 다단계로 필터링합니다.

// CompositeFilter: 여러 필터를 체인으로 연결
let mut filter = CompositeFilter::new();
filter.add_filter(Box::new(VolumeFilter::new(1.5)));  // 거래량 150% 이상
filter.add_filter(Box::new(TrendFilter::new()));       // 추세 방향 일치

let result = filter.filter(&signal, &context);
if result.is_valid {
    // Signal 실행
}

필터	역할	조건
`VolumeFilter`	거래량 검증	평균 거래량 대비 최소 비율
`TrendFilter`	추세 방향 일치	매수 신호 + 상승 추세
`CompositeFilter`	다중 필터 체인	모든 필터 통과 시 유효
`ConfirmationPattern`	연속 확인	N회 연속 신호 발생 시 유효

Exchange Provider 추상화

거래소 연동은 두 가지 trait로 추상화되어, 전략과 거래소가 완전히 분리됩니다.

/// 계좌/포지션/주문 관리
#[async_trait]
pub trait ExchangeProvider: Send + Sync {
    async fn fetch_account(&self) -> Result<AccountInfo>;
    async fn fetch_positions(&self) -> Result<Vec<PositionInfo>>;
    async fn fetch_pending_orders(&self) -> Result<Vec<PendingOrder>>;
    async fn fetch_execution_history(&self, req: ExecutionHistoryRequest) -> Result<ExecutionHistoryResponse>;
}

/// 시세 조회
#[async_trait]
pub trait MarketDataProvider: Send + Sync {
    async fn get_quote(&self, symbol: &str) -> Result<QuoteData>;
    async fn get_quotes(&self, symbols: &[String]) -> Result<Vec<QuoteData>>;
}

Provider	구현	용도
`KisExchangeProvider`	`provider/kis.rs`	KIS 한국/미국 주식 (통합)
`BinanceExchangeProvider`	`provider/binance.rs`	Binance 암호화폐
`UpbitExchangeProvider`	`provider/upbit.rs`	Upbit 암호화폐 (원화 마켓)
`BithumbExchangeProvider`	`provider/bithumb.rs`	Bithumb 암호화폐 (원화 마켓)
`DbInvestmentExchangeProvider`	`provider/db_investment.rs`	DB금융투자 국내 주식
`LsSecExchangeProvider`	`provider/ls_sec.rs`	LS증권 국내 주식
`MockExchangeProvider`	`provider/mock.rs`	개발/테스트, Paper Trading

MarketStream 실시간 스트림 (v0.8.0)

[KIS WebSocket KR/US] ─── Bridge Task (mpsc) ──→ [UnifiedMarketStream]
                                                        │
                                            ┌───────────┤
                                            ▼           ▼
                                  [MarketDataAggregator] [동적 구독 command channel]
                                            │
                                            ▼
                                  [SubscriptionManager] → Frontend WebSocket

패턴	설명
Singleton	credential_id별 단일 스트림 (여러 전략이 공유)
Bridge Task	KR/US 개별 태스크 → mpsc 채널로 이벤트 통합
참조 카운트	구독 심볼의 사용자 수 추적, 0이면 구독 해제
Lazy 초기화	전략 시작 시 DB 자격증명 기반으로 스트림 자동 생성
동적 구독	연결 중에도 심볼 추가/해제 가능

전략 개발 가이드

ZeroQuant는 플러그인 기반 전략 시스템을 지원합니다. Strategy trait를 구현하여 새로운 전략을 추가할 수 있습니다.

Strategy Trait

#[async_trait]
pub trait Strategy: Send + Sync {
    // ── 필수 구현 ──────────────────────────────────────────
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn description(&self) -> &str;

    /// 설정으로 전략 초기화
    async fn initialize(&mut self, config: Value)
        -> Result<(), Box<dyn std::error::Error + Send + Sync>>;

    /// 새 시장 데이터 수신 시 호출 → 트레이딩 신호 반환
    async fn on_market_data(&mut self, data: &MarketData)
        -> Result<Vec<Signal>, Box<dyn std::error::Error + Send + Sync>>;

    /// 주문 체결 시 호출
    async fn on_order_filled(&mut self, order: &Order)
        -> Result<(), Box<dyn std::error::Error + Send + Sync>>;

    /// 포지션 업데이트 시 호출
    async fn on_position_update(&mut self, position: &Position)
        -> Result<(), Box<dyn std::error::Error + Send + Sync>>;

    /// 전략 종료 및 리소스 정리
    async fn shutdown(&mut self)
        -> Result<(), Box<dyn std::error::Error + Send + Sync>>;

    /// 현재 전략 상태 (모니터링용)
    fn get_state(&self) -> Value;

    // ── 기본 구현 제공 (선택적 오버라이드) ─────────────────
    /// StrategyContext 주입 (거래소 데이터, GlobalScore, RouteState 접근)
    fn set_context(&mut self, _context: Arc<RwLock<StrategyContext>>) {}

    /// 다중 타임프레임 설정 (None이면 단일 타임프레임)
    fn multi_timeframe_config(&self) -> Option<MultiTimeframeConfig> { None }

    /// 다중 타임프레임 데이터로 신호 생성 (기본: on_market_data 호출)
    async fn on_multi_timeframe_data(
        &mut self, primary_data: &MarketData,
        _secondary_data: &HashMap<Timeframe, Vec<Kline>>,
    ) -> Result<Vec<Signal>, Box<dyn std::error::Error + Send + Sync>>;

    /// 영속성을 위한 상태 저장/로드
    fn save_state(&self) -> Result<Vec<u8>, Box<dyn std::error::Error + Send + Sync>> { Ok(vec![]) }
    fn load_state(&mut self, _data: &[u8]) -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
}

새 전략 추가 방법

1. 전략 Config 정의 (SDUI 스키마 자동 생성)

crates/trader-strategy/src/strategies/my_strategy.rs

use crate::Strategy;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use trader_strategy_macro::StrategyConfig;  // SDUI 스키마 자동 생성 매크로

// 공통 모듈 임포트 (v0.7.0+)
use super::common::{
    ExitConfig, calculate_rsi, PositionSizer, RiskChecker,
};

/// 전략 설정 - SDUI 스키마 자동 생성
#[derive(Debug, Clone, Serialize, Deserialize, StrategyConfig)]
#[strategy(
    id = "my_strategy",                    // 전략 고유 ID (URL/API에서 사용)
    name = "나만의 RSI 전략",               // UI 표시명
    description = "RSI 과매수/과매도 평균회귀", // 전략 설명
    category = "Intraday"                  // 카테고리: Intraday, Swing, Position
)]
pub struct MyStrategyConfig {
    /// 거래 종목
    #[serde(default = "default_ticker")]
    #[schema(
        label = "거래 종목",      // UI 라벨
        field_type = "symbol",   // 필드 타입: symbol, number, integer, boolean, select
        default = "005930",      // 기본값
        section = "asset"        // UI 섹션 그룹
    )]
    pub ticker: String,

    /// 거래 금액
    #[serde(default = "default_amount")]
    #[schema(label = "거래 금액", field_type = "number", min = 10000, max = 100000000, default = 1000000, section = "asset")]
    pub amount: Decimal,

    /// RSI 기간
    #[serde(default = "default_rsi_period")]
    #[schema(label = "RSI 기간", field_type = "integer", min = 2, max = 100, default = 14, section = "indicator")]
    pub rsi_period: usize,

    /// 과매도 임계값
    #[serde(default = "default_oversold")]
    #[schema(label = "과매도 임계값", field_type = "number", min = 0, max = 50, default = 30, section = "indicator")]
    pub oversold: Decimal,

    /// 과매수 임계값
    #[serde(default = "default_overbought")]
    #[schema(label = "과매수 임계값", field_type = "number", min = 50, max = 100, default = 70, section = "indicator")]
    pub overbought: Decimal,

    /// 청산 설정 (공통 스키마 프래그먼트 참조)
    #[serde(default)]
    #[fragment("risk.exit_config")]
    pub exit_config: ExitConfig,

}

// 기본값 함수들
fn default_ticker() -> String { "005930".to_string() }
fn default_amount() -> Decimal { dec!(1000000) }
fn default_rsi_period() -> usize { 14 }
fn default_oversold() -> Decimal { dec!(30) }
fn default_overbought() -> Decimal { dec!(70) }

impl Default for MyStrategyConfig {
    fn default() -> Self {
        Self {
            ticker: default_ticker(),
            amount: default_amount(),
            rsi_period: default_rsi_period(),
            oversold: default_oversold(),
            overbought: default_overbought(),
            exit_config: ExitConfig::default(),
        }
    }
}

2. Strategy Trait 구현

pub struct MyStrategy {
    config: MyStrategyConfig,
    context: Option<Arc<RwLock<StrategyContext>>>,  // RouteState 접근용
}

#[async_trait]
impl Strategy for MyStrategy {
    fn name(&self) -> &str { "my_strategy" }
    fn version(&self) -> &str { "1.0.0" }
    fn description(&self) -> &str { "RSI 기반 평균회귀 전략" }

    // StrategyContext 주입 (GlobalScore, RouteState 접근용)
    fn set_context(&mut self, ctx: Arc<RwLock<StrategyContext>>) {
        self.context = Some(ctx);
    }

    async fn on_market_data(&mut self, data: &MarketData)
        -> Result<Vec<Signal>, Box<dyn std::error::Error + Send + Sync>> {
        let mut signals = vec![];

        // RouteState 과열 차단 (v0.8.1 공통 패턴)
        if let Some(ctx) = &self.context {
            let ctx = ctx.read().await;
            if let Some(state) = ctx.get_route_state(&self.config.ticker) {
                if state == RouteState::Overheat {
                    return Ok(vec![]); // 과열 종목 진입 차단
                }
            }
        }

        // RSI 계산 및 신호 생성
        let rsi = calculate_rsi(&data.closes, self.config.rsi_period)?;

        if rsi < self.config.oversold {
            signals.push(Signal::buy(&self.config.ticker, data.close));
        } else if rsi > self.config.overbought {
            signals.push(Signal::sell(&self.config.ticker, data.close));
        }

        Ok(signals)
    }
    // ... 나머지 필수 구현 (initialize, on_order_filled, on_position_update, shutdown, get_state)
}

3. 모듈 및 레지스트리 등록

모듈 등록: crates/trader-strategy/src/strategies/mod.rs

pub mod my_strategy;
pub use my_strategy::*;

전략 레지스트리 등록: 파일 하단에 register_strategy! 매크로 호출

// inventory 기반 자동 등록 (컴파일 타임에 StrategyMeta 생성)
register_strategy! {
    id: "my_strategy",
    aliases: ["my_rsi"],
    name: "나만의 RSI 전략",
    description: "RSI 과매수/과매도 평균회귀",
    timeframe: "15m",
    tickers: [],                              // 빈 배열 = 사용자 지정
    category: Intraday,                       // Realtime, Intraday, Daily, Monthly
    markets: [Crypto, Stock],                 // 지원 시장
    type: MyStrategy,                         // ::new()로 생성 (또는 factory: MyStrategy::variant)
    config: MyStrategyConfig                  // SDUI 스키마 자동 생성
}

4. ExitConfig 통합 리스크 관리 (v0.8.2)

전략별로 6가지 리스크 옵션을 enabled: bool로 독립 활성화/비활성화하여 조합합니다. Strategy trait의 exit_config() 메서드로 엔진에 전달하면, enrich_signal()이 Entry 신호에 SL/TP 가격과 metadata를 자동 적용합니다.

리스크 옵션 상세:

옵션	설명	모드/파라미터	동작 방식
StopLoss	손절	`Fixed` (고정 %), `AtrBased` (ATR 배수)	Fixed: entry_price ± pct% / ATR: executor에서 ATR 값으로 동적 계산
TakeProfit	익절	`pct` (고정 %)	entry_price ± pct%
TrailingStop	트레일링 스톱	`FixedPercentage`, `AtrBased`, `Step`, `ParabolicSar`	trigger_pct 도달 후 고점 대비 stop_pct 하락 시 청산
ProfitLock	수익 잠금	`threshold_pct`, `lock_pct`	수익이 threshold 달성 → 수익의 lock% 이하 하락 시 청산 (예: 5%수익, 80%잠금 → 4% 이하면 청산)
DailyLossLimit	일일 손실 한도	`max_loss_pct`	계좌 대비 일일 손실이 max_loss_pct 초과 시 거래 중단
반대 신호 청산	exit_on_opposite_signal	`bool`	보유 중 반대 방향 Entry 발생 시 기존 포지션 즉시 청산

TrailingStop 4가지 모드:

모드	설명	파라미터
`FixedPercentage`	고정 % 트레일링	trigger_pct (시작 수익률), stop_pct (고점 대비 하락폭)
`AtrBased`	ATR 기반 동적 트레일링	trigger_pct, atr_multiplier (ATR × 배수만큼 트레일)
`Step`	단계별 트레일링	step_levels: [{profit_pct, trail_pct}, ...] 수익 구간별 차등 트레일
`ParabolicSar`	Parabolic SAR 지표 기반	지표가 가격과 교차 시 청산

6가지 프리셋:

프리셋	손절	익절	트레일링	반대 청산	적용 대상
`for_day_trading()`	2% Fixed	4%	❌	✅	day_trading, sector_vb, momentum_surge
`for_mean_reversion()`	3% Fixed	6%	❌	✅	mean_reversion, range_trading, candle_pattern
`for_grid_trading()`	❌	3%	❌	❌	DCA (grid, magic_split, infinity_bot)
`for_rebalancing()`	❌	❌	❌	❌	asset_allocation, rotation, pension_bot
`for_leverage()`	5% Fixed	10%	✅ (5%→2%)	✅	us_3x_leverage, market_bothside
`for_momentum()`	5% Fixed	15%	✅ (8%→3%)	✅	compound_momentum, momentum_power, rsi_multi_tf

// Strategy trait에서 exit_config() 반환 → 엔진이 enrich_signal() 자동 적용
fn exit_config(&self) -> Option<&ExitConfig> {
    Some(&self.config.exit_config)
}

// 커스텀 빌더 패턴
let config = ExitConfig::for_momentum()
    .stop_loss(StopLossConfig { mode: StopLossMode::AtrBased, atr_multiplier: dec!(2.0), ..Default::default() })
    .trailing_stop(TrailingStopConfig { mode: TrailingMode::Step, step_levels: vec![
        StepLevel { profit_pct: dec!(5), trail_pct: dec!(3) },
        StepLevel { profit_pct: dec!(10), trail_pct: dec!(2) },
    ], ..Default::default() });

CLI로 전략 테스트 (v0.7.0+)

# 단일 심볼 테스트
trader strategy-test --strategy my_strategy --symbol 005930 --market KR

# 다중 심볼 테스트 (로테이션 전략)
trader strategy-test --strategy rotation --symbols "SPY,QQQ,IWM" --market US

# JSON config로 상세 테스트
trader strategy-test --strategy my_strategy --config '{"ticker":"005930","rsi_period":14}'

# 디버그 모드 (상세 진단 정보 출력)
trader strategy-test --strategy my_strategy --symbol 005930 --debug

백테스트 CLI (v0.8.1+)

# TOML 설정 파일로 백테스트 실행
trader backtest --config config/backtest/rsi.toml

# 자동 차트 생성 (equity curve, drawdown, trade markers)
trader backtest --config config/backtest/grid.toml --chart

# 멀티에셋 전략 (HAA, XAA, StockRotation 등 자동 감지)
trader backtest --config config/backtest/haa.toml

# 사전 정의 설정 파일 (config/backtest/)
# rsi.toml, bollinger.toml, grid.toml, magic_split.toml, infinity_bot.toml,
# haa.toml, xaa.toml, compound_momentum.toml, stock_rotation.toml, volatility.toml

기능:

멀티에셋 자동 감지: 다중 심볼 전략은 StrategyContext와 함께 자동 실행
스마트 심볼 해석: KR 종목코드를 .KS/.KQ 접미사로 자동 변환
Signal Analysis Report: Entry/Exit 균형, 레벨별 분포, 검증 체크리스트 자동 출력
회귀 차트: --chart 옵션으로 equity curve, drawdown, 거래 마커 포함 PNG 생성
타임프레임 자동 폴백: 전략 기본 타임프레임 → secondary → 일반(1m~1d) 순서로 가용 데이터 자동 탐색

전략 구조

crates/trader-strategy/
├── src/
│   ├── lib.rs              # 모듈 진입점
│   ├── traits.rs           # Strategy trait 정의
│   ├── engine.rs           # 전략 엔진 (로딩/실행)
│   ├── plugin/             # 동적 플러그인 로더
│   └── strategies/
│       ├── mod.rs          # 전략 모듈 목록
│       ├── common/         # 공통 유틸리티 (v0.7.0 대폭 확장)
│       │   ├── exit_config.rs      # 통합 리스크 관리 설정 (5가지 타입) [v0.8.2]
│       │   ├── global_score_utils.rs # GlobalScore 유틸리티
│       │   ├── indicators.rs       # 기술 지표 (RSI, SMA, BB 등)
│       │   ├── position_sizing.rs  # 포지션 사이징
│       │   ├── risk_checks.rs      # 리스크 검증
│       │   └── signal_filters.rs   # 신호 필터링
│       ├── day_trading.rs      # 단타/그리드 전략
│       ├── mean_reversion.rs   # RSI/볼린저 평균회귀
│       ├── rotation.rs         # 모멘텀 로테이션
│       ├── asset_allocation.rs # 자산배분 (HAA/XAA/BAA)
│       └── ...                 # 기타 통합 전략들

아키텍처

zeroquant/
├── crates/
│   ├── trader-core/         # 도메인 모델, 공통 유틸리티
│   │   └── domain/          # Account, ExchangeTypes, Signal, Context [v0.8.0]
│   ├── trader-exchange/     # 거래소 연동 (KIS, Binance, Upbit, Bithumb, DB금융투자, LS증권)
│   │   ├── provider/        # ExchangeProvider (KIS, Binance, Upbit, Bithumb, DB금투, LS증권, Mock)
│   │   ├── connector/       # 거래소 커넥터
│   │   │   ├── kis/         # KIS 커넥터 (WebSocket 동적 구독)
│   │   │   ├── upbit/       # Upbit 커넥터
│   │   │   ├── bithumb/     # Bithumb 커넥터
│   │   │   ├── db_investment/ # DB금융투자 커넥터
│   │   │   └── ls_sec/      # LS증권 커넥터
│   │   ├── stream.rs        # UnifiedMarketStream (Bridge Task 패턴)
│   │   └── simulated/       # 시뮬레이션 거래소
│   ├── trader-strategy/     # 전략 엔진, 16개 통합 전략
│   │   └── strategies/common/ # 공통 모듈 (exit_config, global_score_utils 등)
│   ├── trader-risk/         # 리스크 관리
│   ├── trader-execution/    # 주문 실행 엔진 (LiveExecutor, SimulatedExecutor) [v0.8.1]
│   ├── trader-data/         # 데이터 수집/저장 (OHLCV)
│   │   └── provider/        # 데이터 프로바이더
│   │       ├── naver.rs         # 네이버 금융 (국내)
│   │       ├── yahoo_fundamental.rs # Yahoo 펀더멘털 (해외)
│   │       └── krx_api.rs       # KRX OPEN API
│   ├── trader-analytics/    # ML 추론, 성과 분석, 패턴 인식, CandleProcessor [v0.8.2]
│   ├── trader-api/          # REST/WebSocket API (OpenAPI 3.0 문서화)
│   │   ├── repository/      # 데이터 접근 계층 (12개 Repository)
│   │   ├── routes/          # 모듈화된 라우트 (paper_trading 추가) [v0.8.0]
│   │   ├── services/        # MarketStreamHandle, SignalProcessor [v0.8.0]
│   │   └── websocket/       # 실시간 연동 (Aggregator, Handler) [v0.8.0]
│   ├── trader-cli/          # CLI 도구
│   │   └── commands/
│   │       ├── strategy_test.rs # 전략 통합 테스트 (v0.7.0 신규)
│   │       └── download.rs      # 데이터 다운로드
│   ├── trader-collector/    # Standalone 데이터 수집기
│   │   └── modules/         # 수집 모듈 (ohlcv, indicator, global_score, market_breadth) [v0.8.0]
│   └── trader-notification/ # 알림 (Telegram, Discord, Slack, Email, SMS)
├── frontend/                # SolidJS + TypeScript + Vite
│   ├── src/pages/
│   │   ├── Dashboard.tsx    # 포트폴리오 모니터링
│   │   ├── Strategies.tsx   # 전략 등록/관리 (SDUI)
│   │   ├── Dataset.tsx      # 데이터셋 관리
│   │   ├── Backtest.tsx     # 백테스트 실행
│   │   ├── Simulation.tsx   # 시뮬레이션 + Paper Trading [v0.8.0]
│   │   ├── MLTraining.tsx   # ML 모델 훈련
│   │   ├── Screening.tsx   # 종목 스크리닝 (가상 스크롤, 정렬) [v0.8.3]
│   │   ├── TradingJournal.tsx # 매매일지 (상세 인사이트) [v0.8.3]
│   │   ├── GlobalRanking.tsx  # 글로벌 랭킹
│   │   └── Settings.tsx     # 설정 (API 키, 알림, 자격증명)
│   ├── src/components/
│   │   └── simulation/      # Paper Trading 컴포넌트 [v0.8.0]
│   └── src/types/generated/ # ts-rs 자동 생성 타입 (paper_trading 추가)
├── migrations_v2/           # 통합 마이그레이션 (9개)
├── scripts/                 # ML 훈련 파이프라인
└── docs/                    # 프로젝트 문서

기술 스택

영역	기술
Backend	Rust, Tokio, Axum, WebSocket (실시간 시세)
Database	PostgreSQL (TimescaleDB), Redis
Frontend	SolidJS, TypeScript, Vite
ML	ONNX Runtime, XGBoost, LightGBM, RandomForest
Exchange	KIS (KR/US 통합), Binance, Upbit, Bithumb, DB금융투자, LS증권, Mock Provider
Testing	Playwright (E2E), pytest (ML)
Infrastructure	Podman/Docker, TimescaleDB, Redis

빠른 시작

요구사항

Rust 1.83+ (ONNX Runtime 호환)
Node.js 18+
Podman (권장) 또는 Docker & Docker Compose
PostgreSQL 15+ (TimescaleDB) / Redis 7+

설치

# 저장소 클론
git clone https://github.com/berrzebb/zeroquant.git
cd zeroquant

# 환경 설정
cp .env.example .env

Podman 설정 (Windows)

# Podman 설치
winget install RedHat.Podman

# Podman Machine 초기화 및 시작
podman machine init --cpus=2 --memory=2048 --disk-size=20
podman machine start

실행 (인프라 + 로컬 개발)

# 1. 인프라 시작 (DB, Redis) - Podman 또는 Docker 모두 지원
podman compose up -d    # Podman 사용 시
# docker-compose up -d  # Docker 사용 시

# 2. 백엔드 실행 (로컬)
export DATABASE_URL=postgresql://trader:trader_secret@localhost:5432/trader
export REDIS_URL=redis://localhost:6379
cargo run --bin trader-api --features ml --release  # ML 기능 포함

# 3. 프론트엔드 실행 (로컬)
cd frontend && npm install && npm run dev

명령어 매핑 (Docker ↔ Podman)

Docker	Podman
`docker-compose up -d`	`podman compose up -d`
`docker-compose down`	`podman compose down`
`docker-compose logs -f`	`podman compose logs -f`
`docker exec -it`	`podman exec -it`
`docker ps`	`podman ps`

ML 모델 훈련

# Podman으로 ML 훈련 실행
podman compose --profile ml run --rm trader-ml \
  python scripts/train_ml_model.py --symbol SPY --model xgboost

# 사용 가능한 심볼 목록
podman compose --profile ml run --rm trader-ml \
  python scripts/train_ml_model.py --list-symbols

E2E 테스트

# Playwright 설치
cd frontend && npx playwright install

# E2E 테스트 실행
npm run test:e2e

# 특정 테스트 실행
npx playwright test risk-management-ui.spec.ts

데이터 수집기 (Collector)

trader-collector는 시장 데이터를 자동으로 수집하고 분석 지표를 계산하는 독립 실행형 CLI 도구입니다.

워크플로우 구조

┌─────────────────────────────────────────────────────────────────┐
│                    Group A: 외부 API 워크플로우                   │
│                    (Rate Limited - 60분 주기)                    │
├─────────────────────────────────────────────────────────────────┤
│  1. 심볼 동기화     → KRX, Binance, Yahoo에서 종목 목록 수집      │
│  2. Fundamental    → PER, PBR, ROE, 섹터, 시가총액 등            │
│  3. OHLCV 수집     → 일봉/시간봉/분봉 데이터 수집                 │
│     └── KRX API 직접 수집 (v0.8.0): 누락 범위 자동 감지 + 배치 저장│
│  4. 매크로 데이터   → 환율, 금리, 유가 등 매크로 지표 (Redis 캐시)   │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Group B: 내부 계산 워크플로우                   │
│                    (No Rate Limit - 15분 주기)                   │
├─────────────────────────────────────────────────────────────────┤
│  1. 지표 동기화     → RouteState, MarketRegime, TTM Squeeze      │
│  2. GlobalScore    → 7개 팩터 기반 종합 점수 계산                 │
│  3. 스크리닝 뷰     → Materialized View 갱신                     │
│  4. 신호 성과       → 과거 신호의 N일 후 수익률 계산               │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Group C: 실시간 데이터 워크플로우                 │
│                    (5분 주기)                                    │
├─────────────────────────────────────────────────────────────────┤
│  1. 시장 폭 지표   → 전종목 등락 비율 (KOSPI/KOSDAQ/전체)          │
│  2. 매크로 데이터   → 환율, 금리, 유가 → Redis 캐싱                │
└─────────────────────────────────────────────────────────────────┘

CLI 명령어

# 빌드
cargo build -p trader-collector --release

# 실행 (환경변수 설정 후)
./target/release/trader-collector <command>

데이터 수집 명령어

명령어	설명	예시
`sync-symbols`	심볼 정보 동기화	`collector sync-symbols`
`collect-ohlcv`	OHLCV 데이터 수집	`collector collect-ohlcv --stale-hours 24`
`sync-naver-fundamentals`	네이버 금융 데이터 수집 (KR)	`collector sync-naver-fundamentals`
`sync-yahoo-fundamentals`	Yahoo 펀더멘털 수집 (US/글로벌)	`collector sync-yahoo-fundamentals --market US`
`sync-krx-fundamentals`	KRX API 데이터 수집	`collector sync-krx-fundamentals`

분석 지표 명령어

명령어	설명	예시
`sync-indicators`	기술 지표 동기화	`collector sync-indicators`
`sync-global-scores`	GlobalScore 계산	`collector sync-global-scores`
`refresh-screening`	스크리닝 뷰 갱신	`collector refresh-screening`
`sync-signal-performance`	신호 성과 계산	`collector sync-signal-performance --max-days 20`

운영 명령어

명령어	설명	예시
`run-all`	전체 워크플로우 1회 실행	`collector run-all`
`daemon`	데몬 모드 (주기적 실행)	`collector daemon`
`checkpoint list`	체크포인트 상태 조회	`collector checkpoint list`
`checkpoint clear`	체크포인트 삭제	`collector checkpoint clear naver_fundamental`
`scheduler-status`	스케줄러 상태 확인	`collector scheduler-status --market KR`

모듈 구조 (v0.8.0)

trader-collector/src/modules/
├── symbol_sync.rs           # 심볼 정보 동기화 (KRX, Binance, Yahoo)
├── fundamental_sync.rs      # 펀더멘털 데이터 (Naver, Yahoo, KRX)
├── ohlcv_collect.rs         # OHLCV 수집 (KRX API 직접 수집, 누락 범위 감지)
├── indicator_sync.rs        # 기술 지표 계산 (RouteState, MarketRegime)
├── global_score_sync.rs     # GlobalScore 7팩터 종합 점수
├── market_breadth_sync.rs   # 시장 폭 지표 (전종목 등락 비율) [v0.8.0 신규]
├── macro_data_sync.rs       # 매크로 경제 데이터 (환율, 금리, 유가)
├── screening_refresh.rs     # Materialized View 갱신
├── signal_performance_sync.rs # 신호 성과 추적
├── scheduler.rs             # 시장 운영 시간 기반 스케줄링
├── checkpoint.rs            # 수집 중단/재개 체크포인트
├── watchlist_helper.rs      # 관심종목 데이터 우선 수집 (Strategy Watched Tickers 연동) [v0.8.1]
└── utils.rs                 # 공통 유틸리티

v0.8.0 OHLCV 수집 개선:

KRX API 직접 수집으로 국내 주식 데이터 정확도 향상
기존 데이터와 비교하여 누락 범위 자동 감지 (calculate_missing_ranges)
배치 저장으로 DB I/O 최적화 (save_krx_ohlcv_batch)
시가총액/발행주식수 동시 업데이트 (update_market_info_batch)
수집 진행률 실시간 표시 (ProgressTracker)

데몬 모드

# 백그라운드 실행 (systemd 또는 nohup)
nohup ./target/release/trader-collector daemon > collector.log 2>&1 &

# 또는 systemd 서비스로 등록
sudo systemctl enable trader-collector
sudo systemctl start trader-collector

데몬 모드 동작:

Group A (외부 API): 60분마다 실행 (DAEMON_INTERVAL_MINUTES)
Group B (내부 계산): 15분마다 실행 (RANKING_INTERVAL_MINUTES)
Group C (실시간 데이터): 5분마다 실행 (REALTIME_INTERVAL_MINUTES)
시장 운영 시간 기반 스케줄링 지원 (SCHEDULING_ENABLED=true)

증분 수집

# 24시간 이상 지난 심볼만 OHLCV 수집
collector collect-ohlcv --stale-hours 24

# 특정 심볼만 수집
collector collect-ohlcv --symbols "005930,000660,035720"

# 중단점부터 재개 (네이버 펀더멘털)
collector sync-naver-fundamentals --resume

체크포인트 시스템

대용량 수집 작업의 중단/재개를 지원합니다.

# 현재 체크포인트 상태 확인
collector checkpoint list

# 출력 예시:
# 📋 체크포인트 상태:
# --------------------------------------------------------------------------------
#   naver_fundamental         | 상태: running      | 처리:  1234개 | 마지막: 005930
#   indicator_sync            | 상태: completed    | 처리:  2500개 | 마지막: 999999
# --------------------------------------------------------------------------------

# 특정 워크플로우 체크포인트 삭제 (처음부터 다시 시작)
collector checkpoint clear naver_fundamental

# 실행 중인 워크플로우를 interrupted로 마킹
collector checkpoint interrupt naver_fundamental

스케줄링 (시장 운영 시간 기반)

# 환경변수 설정
SCHEDULING_ENABLED=true
SCHEDULING_KRX_DELAY_MINUTES=60    # 장마감 후 60분 대기
SCHEDULING_SKIP_WEEKENDS=true
SCHEDULING_SKIP_HOLIDAYS=true

# 스케줄러 상태 확인
collector scheduler-status --market KR

# 출력 예시:
# 📅 KR 시장 스케줄러 상태:
#   현재 시간: 2026-02-06 16:30:00 KST
#   장 상태: 마감
#   다음 수집: 2026-02-07 09:00:00 KST

설정

환경 변수

DATABASE_URL=postgresql://trader:password@localhost:5432/trader
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
ENCRYPTION_MASTER_KEY=your-32-byte-key-base64

거래소 API 키

웹 대시보드 설정 > API 키 관리에서 등록합니다. 모든 키는 AES-256-GCM으로 암호화 저장됩니다.

설치 가이드

시스템 요구사항

항목	최소	권장
OS	Windows 10, Ubuntu 20.04, macOS 12	Windows 11, Ubuntu 22.04, macOS 14
CPU	4 코어	8 코어 이상
메모리	8GB	16GB 이상
저장공간	20GB	50GB+ (시계열 데이터)
Rust	1.83+	최신 stable
Node.js	18+	20+
PostgreSQL	15+ (TimescaleDB)	16+

1단계: 필수 도구 설치

Windows

# Rust 설치
winget install Rustlang.Rust.MSVC

# Node.js 설치
winget install OpenJS.NodeJS.LTS

# Podman 설치 (권장)
winget install RedHat.Podman

# Visual Studio Build Tools (C++ 빌드 필수)
winget install Microsoft.VisualStudio.2022.BuildTools

Linux (Ubuntu/Debian)

# Rust 설치
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Node.js 설치
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Podman 설치
sudo apt install -y podman podman-compose

# 빌드 도구
sudo apt install -y build-essential pkg-config libssl-dev

macOS

# Homebrew로 설치
brew install rust node podman

# Podman 초기화
podman machine init
podman machine start

2단계: 프로젝트 설정

# 저장소 클론
git clone https://github.com/berrzebb/zeroquant.git
cd zeroquant

# 환경 설정
cp .env.example .env

# .env 파일 편집 (필수 값 설정)
# DATABASE_URL=postgresql://trader:trader_secret@localhost:5432/trader
# REDIS_URL=redis://localhost:6379
# JWT_SECRET=your-secret-key-min-32-chars
# ENCRYPTION_MASTER_KEY=your-32-byte-encryption-key-base64

3단계: 인프라 실행

# Podman 컨테이너 시작 (TimescaleDB + Redis)
podman compose up -d

# 컨테이너 상태 확인
podman ps

# 로그 확인
podman compose logs -f

4단계: 데이터베이스 마이그레이션

# 마이그레이션 검증
cargo run -p trader-cli -- migrate verify

# 마이그레이션 적용
cargo run -p trader-cli -- migrate apply --dir migrations_v2

5단계: 애플리케이션 빌드 및 실행

# 백엔드 빌드 (Release + ML 기능)
cargo build --bin trader-api --features ml --release

# 백엔드 실행
./target/release/trader-api

# 또는 개발 모드
cargo run --bin trader-api --features ml

# 프론트엔드 설치 및 실행 (새 터미널)
cd frontend
npm install
npm run dev

6단계: 접속 확인

서비스	URL
웹 대시보드	http://localhost:5173
API 서버	http://localhost:3000
API 문서 (Swagger)	http://localhost:3000/swagger-ui
TimescaleDB	localhost:5432
Redis	localhost:6379

문제 해결

Podman Machine 시작 실패 (Windows)

# WSL2 설치 확인
wsl --install

# Podman Machine 재초기화
podman machine stop
podman machine rm
podman machine init --cpus=2 --memory=4096
podman machine start

빌드 에러: ONNX Runtime

# Windows: Visual C++ Redistributable 설치
winget install Microsoft.VCRedist.2015+.x64

# Linux: 라이브러리 설치
sudo apt install -y libonnxruntime-dev

데이터베이스 연결 실패

# 컨테이너 상태 확인
podman ps -a

# TimescaleDB 로그 확인
podman logs trader-timescaledb

# 직접 연결 테스트
podman exec -it trader-timescaledb psql -U trader -d trader

마이그레이션 가이드

ZeroQuant는 데이터 안전성을 보장하는 마이그레이션 관리 도구를 제공합니다.

핵심 기능

기능	설명
자동 검증	중복 정의, CASCADE 사용, 순환 의존성 자동 검출
멱등성 보장	IF NOT EXISTS 자동 주입으로 재실행 안전
통합 계획	19개 → 9개 논리적 그룹 통합
의존성 시각화	Mermaid/DOT/Text 형식 그래프 생성

CLI 명령어

# 마이그레이션 검증
trader migrate verify [--verbose] [--dir migrations_v2]

# 통합 계획 생성 (dry-run)
trader migrate consolidate --dry-run

# 통합 마이그레이션 생성
trader migrate consolidate --output migrations_v2

# 의존성 그래프 시각화
trader migrate graph [--format mermaid|dot|text]

# 마이그레이션 적용
trader migrate apply --db-url "postgres://..." --dir migrations_v2

# 적용 상태 확인
trader migrate status --db-url "postgres://..."

검출 코드

코드	심각도	설명	해결 방법
`DUP001`	⚠️ WARNING	중복 정의	최신 버전만 유지
`CASC001`	⚠️ WARNING	CASCADE 사용	명시적 삭제 순서로 변경
`CIRC001`	🔴 ERROR	순환 의존성	의존성 구조 재설계
`IDEM001`	ℹ️ INFO	IF NOT EXISTS 누락	자동 주입 또는 수동 추가
`DCPAT001`	⚠️ WARNING	DROP 후 CREATE 패턴	데이터 백업 후 진행
`DATA001-003`	⚠️ WARNING	데이터 손실 위험	사전 백업 필수

통합 마이그레이션 구조

migrations_v2/
├── 01_core_foundation.sql        # Extensions, ENUM, symbols, credentials
├── 02_data_management.sql        # symbol_info, ohlcv, fundamental, 뷰
├── 03_trading_analytics.sql      # trade_executions, position_snapshots
├── 04_strategy_signals.sql       # signal_marker, alert_rule, alert_history
├── 05_evaluation_ranking.sql     # global_score, reality_check, score_history
├── 06_user_settings.sql          # watchlist, preset, notification, checkpoint
├── 07_performance_optimization.sql # 인덱스, Materialized View, Hypertable
├── 08_paper_trading.sql          # Mock 거래소, 전략-계정 연결, Paper Trading 세션 [v0.8.0]
└── 09_strategy_watched_tickers.sql # 전략별 관심 종목, Collector 우선순위 연동 [v0.8.1]

안전한 마이그레이션 절차

# 1. 현재 스키마 백업
podman exec -it trader-timescaledb pg_dump -U trader -s trader > schema_backup.sql

# 2. 중요 데이터 백업
podman exec -it trader-timescaledb pg_dump -U trader -t symbols -t ohlcv -t trade_executions trader > data_backup.sql

# 3. 마이그레이션 검증
trader migrate verify --verbose

# 4. 테스트 DB에서 먼저 적용
trader migrate apply --db-url "postgres://test_db..." --dir migrations_v2

# 5. 스키마 비교 후 운영 적용
trader migrate apply --dir migrations_v2

프로그래매틱 마이그레이션

use trader_core::migration::{SafeMigrationBuilder, MigrationValidator};

// 안전한 마이그레이션 빌더
let migration = SafeMigrationBuilder::new()
    .with_backup("symbols", "symbols_backup")
    .create_table("new_table", r#"
        CREATE TABLE IF NOT EXISTS new_table (
            id SERIAL PRIMARY KEY,
            name TEXT NOT NULL
        )
    "#)
    .add_index("new_table", "idx_new_table_name", &["name"])
    .build();

// 검증 후 적용
let validator = MigrationValidator::new(&files);
let report = validator.validate();
if report.has_errors() {
    eprintln!("{}", report);
    return Err("마이그레이션 검증 실패");
}

📖 상세 가이드: docs/migration_guide.md

문서

문서	설명
API 문서	REST/WebSocket API 레퍼런스
아키텍처	시스템 아키텍처 상세
마이그레이션 가이드	데이터베이스 마이그레이션 관리
설치/배포 가이드	인프라, 환경설정, 배포
운영 가이드	일일 운영, 모니터링, 백업
데이터 수집	Collector, 내부 시스템
트러블슈팅	문제 해결 가이드
개발 규칙	코드 작성 규칙 및 가이드라인
전략 가이드	전략별 상세 파라미터 및 데이터 연동
Claude 가이드	AI 세션 컨텍스트

라이선스

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.claude		.claude
.github/workflows		.github/workflows
.sqlx		.sqlx
agents		agents
config		config
crates		crates
docs		docs
frontend		frontend
migrations		migrations
migrations_v2		migrations_v2
release		release
scripts		scripts
tests		tests
tools/ml		tools/ml
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.rustfmt.toml		.rustfmt.toml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
Dockerfile.ml		Dockerfile.ml
DTraderclippy-current.txt		DTraderclippy-current.txt
LICENSE		LICENSE
README.md		README.md
clippy.toml		clippy.toml
docker-compose.yml		docker-compose.yml
podman-compose.ps1		podman-compose.ps1
podman-compose.sh		podman-compose.sh
pyproject.toml		pyproject.toml

License

berrzebb/zeroquant

Folders and files

Latest commit

History

Repository files navigation

ZeroQuant

소개

주요 기능

🏦 다중 시장 지원

📝 Paper Trading (v0.8.0)

📊 데이터 & 분석

🎯 고급 스코어링 시스템

🤖 알림 & 모니터링

🛡️ 리스크 관리

🖥️ 웹 대시보드

📒 매매일지 (Trading Journal)

지원 전략

통합 전략 (v0.7.0)

📈 단기/분할 전략

📊 모멘텀/로테이션 전략

🏦 자산배분 전략

🎯 기타 전략

전략 실행 아키텍처 (v0.8.0)

실행 흐름

실행 모드 조합

SignalProcessor trait

Position ID / Group ID 시스템

StrategyContext (전략 컨텍스트)

Signal Filter 시스템 (v0.8.0)

Exchange Provider 추상화

MarketStream 실시간 스트림 (v0.8.0)

전략 개발 가이드

Strategy Trait

새 전략 추가 방법

1. 전략 Config 정의 (SDUI 스키마 자동 생성)

2. Strategy Trait 구현

3. 모듈 및 레지스트리 등록

4. ExitConfig 통합 리스크 관리 (v0.8.2)

CLI로 전략 테스트 (v0.7.0+)

백테스트 CLI (v0.8.1+)

전략 구조

아키텍처

기술 스택

빠른 시작

요구사항

설치

Podman 설정 (Windows)

실행 (인프라 + 로컬 개발)

명령어 매핑 (Docker ↔ Podman)

ML 모델 훈련

E2E 테스트

데이터 수집기 (Collector)

워크플로우 구조

CLI 명령어

데이터 수집 명령어

분석 지표 명령어

운영 명령어

모듈 구조 (v0.8.0)

데몬 모드

증분 수집

체크포인트 시스템

스케줄링 (시장 운영 시간 기반)

설정

환경 변수

거래소 API 키

설치 가이드

시스템 요구사항

1단계: 필수 도구 설치

Windows

Linux (Ubuntu/Debian)

macOS

2단계: 프로젝트 설정

3단계: 인프라 실행

4단계: 데이터베이스 마이그레이션

5단계: 애플리케이션 빌드 및 실행

6단계: 접속 확인

문제 해결

Podman Machine 시작 실패 (Windows)

빌드 에러: ONNX Runtime

Packages