최근 주식 투자가 대중화되며 많은 사람들이 투자에 뛰어들고 있습니다. 그러나 한국의 디지털 금융 이해도는 OECD 평균보다 낮은 수준이며, 특히 MZ세대 초보 투자자들은 충분한 기초 지식 없이 투자를 시작하는 경우가 많습니다. 이 과정에서 검증되지 않은 개인 방송이나 단편적인 콘텐츠에 의존해 투자 결정을 내리기도 합니다. 큐빗은 '초보 투자자들이 올바른 투자 지식과 기준 없이 투자 결정을 내리는 것이 과연 괜찮은가' 라는 문제의식에서 출발했습니다.
저희 팀은 MVP 단계에서 개발 효율과 서비스 완성도를 고려해 하나의 시장에 집중하기로 했습니다. 미국 주식 시장은 장기적인 우상향 구조를 가지고 있으며, 애플·엔비디아와 같은 글로벌 대표 기업들이 포진해 있어 많은 한국 개인 투자자들이 실제로 참여하고 있는 해외 투자 시장입니다. 또한 Alpaca(미국 주식 모의·실거래 주문 및 계좌 관리를 위한 트레이딩 API), Massive.io(미국 주식의 실시간·과거 가격, 거래량 등 금융 데이터 제공 API) 등 안정적인 API 인프라를 활용할 수 있어 기술적 제약이 상대적으로 적습니다. 이러한 시장 특성과 기술적 환경을 바탕으로 큐빗은 미국 주식 투자에 관심은 있지만 경험과 지식이 부족한 초보 투자자를 타겟 유저로 설정했습니다.
이들은 다음과 같은 어려움을 겪습니다:
- 투자 학습의 막막함: 기초 개념조차 몰라서 어디서부터 투자 공부를 시작해야 할지 모름
- 이론과 실전의 괴리: 단순 이론 학습은 지루하게 느끼며, 실제 투자와의 연결고리가 부족해 지속적인 학습으로 이어지기 어려움
- 해외 주식 투자의 어려움: 해외 종목 뉴스는 영어로 제공되며 국내 기업이 아니어서 낯설기에 핵심 이슈와 종목 간 연관성 파악이 어려움
큐빗의 이론학습 → 모의투자 → 보유 종목 뉴스 확인 → 복기(AI 매매 분석 리포트 & 매매 일지) 의 투자 학습 사이클을 통해, 사용자가 자신만의 기준을 갖춘 성숙한 투자자로 성장할 수 있습니다.
- 카드 형식의 쉬운 이론 학습: 복잡한 투자 지식을 카드 형식으로 단계별 학습할 수 있도록 구성
- 실시간 시세 기반 모의투자: 실제 주식 거래 환경과 유사한 UI와 WebSocket 기반 실시간 데이터 스트림
- AI 매매 분석 리포트: ChatGPT 기반 모델이 사용자의 매매 패턴과 리스크 요인을 분석하고 추천 이론 학습 제공
- 맞춤 해외 뉴스 칼럼: 보유 종목과 연관 종목을 분석해 자동으로 맞춤 해외 뉴스를 번역하고 재가공한 컬럼 제공
큐빗 서비스는 3개의 백엔드 서버로 구성되어 있으며, 이 리포지토리(QBIT-BE)는 그 중 qbit-api Server와 qbit-realtime Server 두 개의 서버 코드를 포함함합니다.
주요 서비스 동작 관리를 담당하는 REST API 서버입니다. 사용자 인증, 종목 검색, 모의 거래, 포트폴리오 관리 등 큐빗 서비스의 핵심 비즈니스 로직을 처리합니다. PostgreSQL을 사용하여 사용자 정보와 체결 정보 등을 저장하고, Redis를 활용하여 시세 캐싱과 세션 관리를 수행합니다.
Trade Cycle 관리 및 실시간 시세 로드를 담당하는 서버입니다. WebSocket을 통해 실시간 시세 데이터를 클라이언트에 스트리밍하여 실제 거래 환경과 유사한 경험을 제공합니다. 주문 체결 이벤트를 처리하고 Trade Cycle을 관리하여 사용자의 거래 내역을 추적합니다.
참고: 리포트 및 컬럼 생성 기능은 별도의
qbit-content Server(Python/FastAPI 기반)에서 담당합니다.
QBIT-BE는 Spring Boot 기반의 멀티 모듈 아키텍처로 구성되어 있습니다. 도메인 로직은 qbit-domain 모듈에 패키지 단위로 분리되어 있으며(order, tradecycle, portfolio, journal 등), 각 도메인은 엔티티, 리포지토리, 도메인 서비스를 포함합니다. 복잡도가 높은 거래 영역에 대해서는 헥사고날 아키텍처의 포트-어댑터 패턴을 적용하여 TradingPort를 통해 외부 API 의존성을 추상화했으며, 단순한 조회 기능은 직접 접근하는 하이브리드 방식을 채택했습니다.
- Backend: Spring Boot 3.x, Java 17
- Build Tool: Gradle 8.5
- Database: PostgreSQL 12+
- Cache: Redis 6.0+
- 외부 API: Alpaca (거래), Massive.io (시장 데이터), Binance (암호화폐), Yahoo Finance (지수)
- 인증: Spring Security, JWT, OAuth2 (Google, Alpaca)
- API 문서: Swagger/OpenAPI
프로젝트의 모든 빌드 및 실행 명령어는 Makefile을 통해 제공됩니다.
사전 준비: Java 17, PostgreSQL 12+, Redis 6.0+
git clone https://github.com/Curihous/QBIT-BE
cd QBIT-BE프로젝트 루트에 .env.example 파일을 복사하여 .env 파일을 만들고, 각 환경 변수에 적절한 값을 입력합니다.
PostgreSQL과 Redis를 실행한 후 데이터베이스를 생성합니다:
make setup-db# 의존성 설치 및 빌드
make install
# API 애플리케이션 실행 (포트 8080)
make run-api
# Realtime 애플리케이션 실행 (포트 8081, 별도 터미널)
make run-realtime애플리케이션이 실행되면 다음 주소에서 접근할 수 있습니다:
- API 서버: http://localhost:8080
- Swagger UI: http://localhost:8080/swagger-ui.html
QBIT-BE는 다음 REST API를 제공합니다. 상세 API 명세는 API 문서를 참고하세요.
사용자 인증과 계정 관리를 담당하는 API입니다.
- 소셜 로그인 (
AuthController): Kakao, Google 네이티브 앱에서 발급받은 액세스 토큰으로 로그인합니다. 신규 사용자는 자동으로 회원가입되며, JWT 액세스 토큰과 리프레시 토큰을 발급받습니다. - Alpaca OAuth 연동 (
AlpacaOAuthController): 모의 거래를 위해 Alpaca Paper Trading 계정을 연동합니다. OAuth 2.0 플로우를 통해 사용자의 Alpaca 계정에 접근 권한을 얻고, 이후 모든 거래는 Alpaca API를 통해 실제 모의 거래 환경에서 실행됩니다. 필요시 계정 연결을 해제할 수 있습니다. - 사용자 정보 관리 (
UserController): 현재 로그인한 사용자의 정보를 조회하거나, 서비스 탈퇴를 진행할 수 있습니다. - Alpaca 계정 정보 (
AlpacaController): 연동된 Alpaca Paper Trading 계정의 실시간 자산 정보(현금 잔고, 포트폴리오 가치 등)를 조회합니다.
투자 종목 검색과 시장 데이터 조회를 제공하는 API입니다. 본 프로젝트는 미국 주식을 주요 타겟으로 하되, 미국 주식 시장이 한국 기준 밤 11시에 개장하고 주말에는 휴장되어 개발 및 테스트 과정에서 실시간 데이터 검증에 제약이 있는 점을 고려해, 24시간 거래되는 암호화폐 시장을 개발 및 테스트 용도로 함께 활용했습니다.
- 종목 검색 (
StockController): 종목명(예: "Apple") 또는 심볼(예: "AAPL")로 검색합니다. 주요 종목들은 배치 작업을 통해 미리 DB에 저장되어 있으며, DB에 없는 종목은 Alpaca API에서 조회 후 검색 결과를 반환 및 저장합니다. 자산 클래스(미국 주식, 암호화폐)로 필터링이 가능합니다. - 종목 상세 정보 (
StockController): 특정 종목의 상세 정보(시가총액, 거래 가능 여부 등)를 조회합니다. Cache-Aside 패턴을 적용하여 DB 캐시를 우선 조회하고, 없을 경우 Alpaca API에서 조회 후 캐시에 저장합니다. - 종목 랭킹 (
StockController): 상승률순, 거래량순, 변동성순으로 종목을 랭킹하여 조회합니다. Redis 캐싱을 통해 빠른 응답 속도를 제공합니다. - 실시간 시세 (
StockMarketDataController):- 암호화폐: Binance API를 통해 암호화폐의 실시간 시세(현재가, 고가, 저가, 전일 대비 등)와 차트 데이터(1분봉, 5분봉, 1시간봉, 일봉 등)를 조회합니다.
- 미국 주식: Massive.io API를 통해 미국 주식의 실시간 시세(15분 지연)와 차트 데이터를 조회합니다. 다양한 시간 단위(분봉, 시간봉, 일봉 등)를 지원하며, 분할/배당 반영 여부를 선택할 수 있습니다.
- 해외 주요 지수 (
MarketIndexController): Yahoo Finance API를 통해 S&P 500, 나스닥, 다우존스 등 해외 주요 지수의 목록, 상세 정보, 과거 데이터를 조회합니다. 홈 화면에서 주요 지수 현황을 한눈에 확인할 수 있습니다.
Alpaca Paper Trading을 활용한 모의 주식 거래 API입니다.
- 주문 관리 (
TradingController):- 주문 생성: 매수/매도 주문을 생성합니다. 시장가, 지정가, 손절 지정가 등 다양한 주문 유형을 지원하며, 미국 주식의 경우 정규장 시간(한국 시간 기준 23:30~06:00)에만 주문이 가능합니다. 최소 주문 수량, 소수점 거래 가능 여부 등 종목별 제약사항을 검증합니다.
- 주문 수정: 미체결 또는 부분 체결된 주문의 수량, 가격, 유효기간을 수정할 수 있습니다.
- 주문 조회: 사용자의 모든 주문 내역을 조회합니다.
- 주문 취소: 미체결 또는 부분 체결된 주문을 취소할 수 있습니다. 완전히 체결된 주문은 취소할 수 없습니다.
- 주문 필터링 (
TradingController): 심볼, 거래 방향(매수/매도), 자산 클래스(미국 주식/암호화폐), 매매 일지 작성 여부 등 다양한 조건으로 주문을 필터링하여 조회할 수 있습니다. - 거래 사이클 (
TradingController): 매수와 매도가 완료되어 종료된 거래 사이클 목록을 조회합니다. 각 사이클은 수익률, 보유 기간 등의 정보를 포함합니다. - 거래 통계 (
TradingController): 월별 거래 통계를 조회합니다. 총 거래 횟수, 평균 수익률, 누적 손익 등의 정보를 제공하여 사용자의 거래 성과를 분석할 수 있습니다.
사용자의 현재 보유 포지션과 포트폴리오 현황을 관리하는 API입니다.
- 보유 포지션 조회 (
PortfolioController): 현재 보유 중인 모든 주식 포지션 목록을 조회합니다. 각 포지션은 종목명, 보유 수량, 평균 매수가, 현재가, 평가 손익 등의 정보를 포함합니다. 자산 클래스(미국 주식/암호화폐)로 필터링할 수 있습니다. - 포지션 상세 조회 (
PortfolioController): 특정 종목의 포지션 정보와 계정 정보를 상세 조회합니다. 프론트엔드의 매매 주문 입력 화면에서 사용되며, 매도 시 최대 수량과 매수 시 최대 구매 가능 금액을 계산하여 사용자가 주문 수량을 입력할 때의 유효성을 검증합니다. - 포트폴리오 오버뷰 (
PortfolioController): 자산 변동 추이를 시각화하기 위한 포트폴리오 오버뷰 데이터를 선택한 조회 기간(1일, 1주, 1개월, 1년)에 따라 조회합니다.
거래에 대한 매매 일지를 작성하고 관리하는 API입니다.
- 일지 작성 (
TradeJournalController): 완료된 주문에 대해 매매 일지를 작성합니다. 거래 당시의 판단 근거와 감정(기쁨, 후회, 불안 등)을 기록할 수 있습니다. - 일지 조회 (
TradeJournalController): 작성한 매매 일지를 월별로 조회하거나, 특정 일지의 상세 내용을 조회할 수 있습니다. 월별 조회 시 거래 방향(매수/매도)으로 필터링할 수 있습니다. - 일지 수정 및 삭제 (
TradeJournalController): 작성한 매매 일지의 내용과 감정을 수정하거나 매매 일지를 삭제할 수 있습니다.
AI 분석 리포트 생성을 위한 데이터를 제공하는 API입니다.
- TradeCycle 데이터 제공 (
AiDataController): qbit-content 서버에서 AI 매매 분석 리포트를 생성하기 위해 필요한 TradeCycle 데이터를 조회합니다. 인증 없이 접근 가능하며, 특정 거래 사이클의 상세 정보를 제공합니다.
프로젝트는 다음과 같은 테스트 및 성능 개선 과정을 포함하고 있습니다:
- Redis Streams 성능 테스트: 고부하 처리 능력 검증 및 장애 복구 검증
- N+1 쿼리 최적화 테스트: Trade Update 이벤트 처리 시 발생했던 중복 쿼리 제거를 통한 성능 개선
상세한 테스트 내용과 결과는 Redis Streams 성능 테스트 문서와 N+1 쿼리 최적화 문서를 참고하세요.
- Spring Boot (3.5.6) - Apache License 2.0
- PostgreSQL Driver - BSD License
- JWT (jjwt) (0.13.0) - Apache License 2.0