3. quant 프로젝트 회고

이번 글은 Python 엔진과 외부 라이브러리를 어떻게 연결해서 실제 퀀트 엔진 구조를 만들었는지에 대한 회고이다. 처음에는 "Python으로 백테스트만 돌리면 되지 않을까"라고 생각했다. 하지만 실제로는 전략 입력을 구조화하고, 장시간 작업을 큐로 넘기고, 외부 데이터 소스를 섞고, 결과를 다시 UI가 이해할 수 있는 형태로 돌려주는 과정까지 모두 설계해야 했다.

1. 주제 소개

[ 핵심 개념 ]

이 프로젝트에서 Python 엔진은 단순 계산 스크립트가 아니다. 실제 역할은 아래와 같다.

가격 데이터와 펀더멘털 데이터 적재
종목 후보 선별
백테스트 실행
전략 비교와 최적화
리스크 계산
뉴스와 이벤트 기반 보조 분석

즉, Python 엔진은 "숫자를 계산하는 함수 모음"이 아니라, 퀀트 도메인에 특화된 분석 서버라고 보는 편이 맞다.

[ 왜 별도 엔진으로 분리했는가? ]

가장 큰 이유는 계산 생태계 때문이다. pandas, numpy, scipy, vectorbt, yfinance 같은 도구는 Python에서 훨씬 자연스럽다. 반대로 화면에서 필요한 검증, 저장, 이력 관리, 응답 포맷 조합은 Spring Boot가 더 익숙하고 안정적이다.

그래서 구조를 아래처럼 나눴다.

Next.js -> Spring Boot -> Python Quant Engine -> 외부 데이터 소스

이 구조를 선택하면 장점이 있다. 프론트는 도메인 화면에 집중하고, Spring Boot는 플랫폼 API와 DB를 맡고, Python은 계산과 데이터 가공에 집중할 수 있다.

2. 실제로 어떤 흐름으로 연결했는가

[ Spring Boot에서 Python으로 요청을 넘기는 방식 ]

백테스트 요청은 바로 Python 함수 호출로 연결하지 않았다. 먼저 Spring Boot 쪽에서 전략, 기간, 스냅샷, 패턴 설정을 검증한 다음, Python 엔진이 이해할 수 있는 payload로 바꿔 넘기도록 만들었다.

실제 서비스 흐름은 대략 아래와 같다.

val payload = mutableMapOf<String, Any>(
    "strategyId" to request.strategyId,
    "startDate" to request.startDate.toString(),
    "endDate" to request.endDate.toString(),
    "factorWeightMode" to (snapshot?.factorWeightMode ?: "AUTO"),
    "factorWeights" to snapshotWeights,
)

resolveEffectiveUniverseScope(strategy, request.universeScope)
    ?.let { payload["universeScope"] = buildUniverseScopePayload(it) }

request.signalPlan?.let { signalPlan ->
    payload["signalPlan"] = mapOf(
        "buyMode" to signalPlan.buyMode,
        "sellMode" to signalPlan.sellMode,
        "holdMode" to signalPlan.holdMode,
    )
}

val result = pythonQuantEngineClient.runBacktest(payload)

이 코드가 의미하는 바는 단순하다. UI에서 들어온 요청을 그대로 Python으로 넘기는 것이 아니라, Spring Boot가 한 번 플랫폼 규칙에 맞게 정규화한다는 것이다. 여기서 중요한 점은 Python 엔진이 프론트 UI 구조에 직접 의존하지 않게 된다는 점이다.

즉, 화면이 바뀌더라도 Python 엔진은 strategyId, 기간, 유니버스, 패턴 정의, 시그널 계획 같은 안정적인 입력만 받으면 된다.

[ Python 엔진에서는 왜 바로 실행하지 않고 큐에 넣었는가 ]

백테스트는 짧게 끝날 수도 있지만, 기간이 길거나 패턴 계산이 많아지면 요청 시간이 길어진다. 그래서 Python 엔진에서는 요청을 받자마자 결과를 돌려주기보다, 작업을 등록하고 백그라운드에서 실행하는 방식으로 바꿨다.

실제 구조는 이런 식이다.

metadata = {
    "kind": "backtest",
    "strategyId": request.strategy_id,
    "startDate": request.start_date.isoformat(),
    "endDate": request.end_date.isoformat(),
    "progressPercent": 0,
    "stage": "queued",
    "stageLabel": "대기 중",
}

job = Job(
    job_type="backtest_dispatch",
    status="PENDING",
    message="백테스트를 대기열에 등록했습니다.",
    metadata_json=cls._serialize_metadata(metadata),
)

future = cls._executor.submit(cls._run_job, job_id, request.model_dump())

여기서 핵심은 두 가지이다.

첫째, 작업 자체를 Job으로 남긴다. 둘째, 진행률과 단계 정보도 함께 메타데이터로 저장한다. 그래서 프론트는 "요청이 성공했는가"만 보는 것이 아니라, 지금 어디까지 진행됐는지를 다시 조회할 수 있다.

[ 데이터 소스를 하나로 묶지 않고 합친 이유 ]

실제로 엔진을 만들면서 가장 많이 바뀐 부분은 데이터 적재 방식이었다. 처음에는 하나의 데이터 공급자만으로 끝낼 수 있을 것 같았다. 그런데 막상 해보니 가격, 종목 마스터, 공시, 뉴스가 서로 강점이 달랐다.

그래서 Python 엔진에서는 아래처럼 역할을 나눠 사용했다.

Yahoo Finance 계열 데이터
- 가격 이력, 심볼 검색, 일부 프로필, 이벤트 데이터
SEC
- 미국 종목의 공시 기반 펀더멘털
Nasdaq Trader / KRX KIND
- 종목 유니버스 마스터 목록
NewsAPI
- 뉴스 원문 수집

특히 펀더멘털 쪽은 SEC와 Yahoo 데이터를 병합하는 방향으로 설계했다. SEC 기반 공시 데이터가 있으면 그것을 우선 사용하고, 비어 있으면 Yahoo 측 데이터를 보조로 쓰는 식이다.

간단히 표현하면 이런 흐름이다.

sec_rows = self.sec_company_facts_service.build_fundamental_rows(symbol, exchange, history)

if not sec_rows:
    ticker = yf.Ticker(provider_symbol)
    info, profile = self._fetch_yahoo_profile(ticker, symbol)
    yahoo_rows = self._build_fundamental_rows(symbol, history, info, profile, ticker)
else:
    yahoo_rows = []

fundamental_rows = self._merge_fundamental_sources(sec_rows, yahoo_rows)