퇴직연금 리밸런싱 + 한국 주식 Quant 분석 통합 플랫폼

퇴직연금 리밸런싱 기능과 한국 주식 Quant 분석을 통합한 프로덕션 수준의 웹 플랫폼

📋 프로젝트 개요

핵심 기능

1. 백테스트 엔진 - 다양한 Quant 전략의 성과 검증
2. 퇴직연금 리밸런싱 - 포트폴리오 자동 리밸런싱 계산
3. 데이터 수집 자동화 - Celery 기반 일별 데이터 수집
4. 실시간 포트폴리오 모니터링 - 현재 포트폴리오 가치 추적

기술 스택

• Backend: FastAPI + Python 3.11+
• Frontend: React 18 + TypeScript + shadcn/ui
• Database: PostgreSQL 15 + TimescaleDB
• Task Queue: Celery + Redis
• Deployment: Docker + Docker Compose
• Web Server: Nginx (Reverse Proxy)

🚀 빠른 시작

사전 요구사항

• Docker & Docker Compose
• Git

설치 및 실행

1. 저장소 클론

git clone <repository-url>
cd pension-quant-platform

2. 환경 변수 설정

cp .env.example .env
# .env 파일을 편집하여 필요한 값 설정

3. Docker 컨테이너 실행

docker-compose up -d

4. 서비스 확인

• Backend API: http://localhost:8000
• API 문서: http://localhost:8000/docs
• Frontend: http://localhost:3000
• Flower (Celery 모니터링): http://localhost:5555

데이터베이스 초기화

# Alembic 마이그레이션 실행
docker-compose exec backend alembic upgrade head

# (선택) MySQL 데이터 마이그레이션
docker-compose exec backend python scripts/migrate_mysql_to_postgres.py

📂 프로젝트 구조

pension-quant-platform/
├── backend/                    # FastAPI 백엔드
│   ├── app/
│   │   ├── api/v1/            # API 라우터
│   │   ├── backtest/          # 백테스트 엔진 (핵심)
│   │   ├── models/            # SQLAlchemy 모델
│   │   ├── schemas/           # Pydantic 스키마
│   │   ├── services/          # 비즈니스 로직
│   │   ├── strategies/        # Quant 전략
│   │   └── tasks/             # Celery 태스크
│   └── alembic/               # DB 마이그레이션
├── frontend/                  # React 프론트엔드
├── nginx/                     # Nginx 설정
├── scripts/                   # 유틸리티 스크립트
└── docker-compose.yml         # Docker 설정

🎯 주요 기능

1. 백테스트 엔진

지원 전략:

• Multi-Factor (Quality + Value + Momentum) - 복합 팩터 전략
• Momentum (12M Return + K-Ratio) - 모멘텀 전략
• Value (PER, PBR) - 가치 투자 전략
• Quality (ROE, GPA, CFO) - 우량주 전략
• All Value (PER, PBR, PCR, PSR, DY) - 종합 가치 투자
• Magic Formula - 마법 공식
• Super Quality - 슈퍼 퀄리티
• F-Score - 피오트로스키 F-Score

성과 지표:

• Total Return (총 수익률)
• CAGR (연평균 복리 수익률)
• Sharpe Ratio (샤프 비율)
• Sortino Ratio (소르티노 비율)
• Maximum Drawdown (MDD)
• Win Rate (승률)
• Calmar Ratio (칼마 비율)

API 사용 예시:

curl -X POST "http://localhost:8000/api/v1/backtest/run" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Multi-Factor 백테스트",
    "strategy_name": "multi_factor",
    "start_date": "2020-01-01",
    "end_date": "2023-12-31",
    "initial_capital": 10000000,
    "commission_rate": 0.0015,
    "rebalance_frequency": "monthly",
    "strategy_config": {
      "count": 20,
      "quality_weight": 0.3,
      "value_weight": 0.3,
      "momentum_weight": 0.4
    }
  }'

2. 데이터 수집 자동화

Celery Beat를 통한 일일 데이터 자동 수집 (평일 18시):

• KRX 종목 데이터
• 주가 데이터
• 재무제표 데이터
• 섹터 분류

3. 퇴직연금 리밸런싱

현재 보유 자산과 목표 비율을 기반으로 매수/매도 추천 계산

🗄️ 데이터베이스 스키마

주요 테이블

• assets - 종목 정보
• price_data - 시계열 가격 (TimescaleDB 하이퍼테이블)
• financial_statements - 재무제표
• portfolios - 포트폴리오
• backtest_runs - 백테스트 실행 기록
• backtest_trades - 백테스트 거래 내역

🔧 개발 가이드

Backend 개발

# 의존성 설치
cd backend
pip install -r requirements.txt

# 로컬 실행
uvicorn app.main:app --reload

# 테스트
pytest

Frontend 개발

# 의존성 설치
cd frontend
npm install

# 로컬 실행
npm start

# 빌드
npm run build

Celery 워커 실행

# Worker
celery -A app.celery_worker worker --loglevel=info

# Beat (스케줄러)
celery -A app.celery_worker beat --loglevel=info

# Flower (모니터링)
celery -A app.celery_worker flower

📊 성능 지표

• 백테스트 실행 시간: < 30초 (3년 데이터)
• 데이터 수집 완료: < 2시간
• API 응답 시간: < 1초
• 동시 접속: 100명 처리

✅ 최근 업데이트 (2026-01-30)

• Value 전략 추가 (PER, PBR)
• Quality 전략 추가 (ROE, GPA, CFO)
• All Value 전략 추가 (PER, PBR, PCR, PSR, DY)
• Frontend 데이터 관리 탭 구현
• 데이터 수집 상태 시각화
• 공통 함수 리팩토링

🚧 향후 계획

• 전략별 성과 비교 차트
• 실시간 포트폴리오 모니터링
• 사용자 인증/권한 관리
• 알림 기능 (이메일, Slack)
• 성능 최적화 (Redis 캐싱)

📄 라이선스

MIT License

👥 기여

Pull Request를 환영합니다!

📞 문의

이슈를 통해 질문이나 버그를 보고해주세요.