226 lines
5.6 KiB
Markdown
226 lines
5.6 KiB
Markdown
|
# 퇴직연금 리밸런싱 + 한국 주식 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. **저장소 클론**
|
||
|
|
```bash
|
||
|
|
git clone <repository-url>
|
||
|
|
cd pension-quant-platform
|
||
|
|
```
|
||
|
|
|
||
|
|
2. **환경 변수 설정**
|
||
|
|
```bash
|
||
|
|
cp .env.example .env
|
||
|
|
# .env 파일을 편집하여 필요한 값 설정
|
||
|
|
```
|
||
|
|
|
||
|
|
3. **Docker 컨테이너 실행**
|
||
|
|
```bash
|
||
|
|
docker-compose up -d
|
||
|
|
```
|
||
|
|
|
||
|
|
4. **서비스 확인**
|
||
|
|
- Backend API: http://localhost:8000
|
||
|
|
- API 문서: http://localhost:8000/docs
|
||
|
|
- Frontend: http://localhost:3000
|
||
|
|
- Flower (Celery 모니터링): http://localhost:5555
|
||
|
|
|
||
|
|
### 데이터베이스 초기화
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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 사용 예시**:
|
||
|
|
```bash
|
||
|
|
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 개발
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 의존성 설치
|
||
|
|
cd backend
|
||
|
|
pip install -r requirements.txt
|
||
|
|
|
||
|
|
# 로컬 실행
|
||
|
|
uvicorn app.main:app --reload
|
||
|
|
|
||
|
|
# 테스트
|
||
|
|
pytest
|
||
|
|
```
|
||
|
|
|
||
|
|
### Frontend 개발
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 의존성 설치
|
||
|
|
cd frontend
|
||
|
|
npm install
|
||
|
|
|
||
|
|
# 로컬 실행
|
||
|
|
npm start
|
||
|
|
|
||
|
|
# 빌드
|
||
|
|
npm run build
|
||
|
|
```
|
||
|
|
|
||
|
|
### Celery 워커 실행
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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)
|
||
|
|
|
||
|
|
- [x] Value 전략 추가 (PER, PBR)
|
||
|
|
- [x] Quality 전략 추가 (ROE, GPA, CFO)
|
||
|
|
- [x] All Value 전략 추가 (PER, PBR, PCR, PSR, DY)
|
||
|
|
- [x] Frontend 데이터 관리 탭 구현
|
||
|
|
- [x] 데이터 수집 상태 시각화
|
||
|
|
- [x] 공통 함수 리팩토링
|
||
|
|
|
||
|
|
## 🚧 향후 계획
|
||
|
|
|
||
|
|
- [ ] 전략별 성과 비교 차트
|
||
|
|
- [ ] 실시간 포트폴리오 모니터링
|
||
|
|
- [ ] 사용자 인증/권한 관리
|
||
|
|
- [ ] 알림 기능 (이메일, Slack)
|
||
|
|
- [ ] 성능 최적화 (Redis 캐싱)
|
||
|
|
|
||
|
|
## 📄 라이선스
|
||
|
|
|
||
|
|
MIT License
|
||
|
|
|
||
|
|
## 👥 기여
|
||
|
|
|
||
|
|
Pull Request를 환영합니다!
|
||
|
|
|
||
|
|
## 📞 문의
|
||
|
|
|
||
|
|
이슈를 통해 질문이나 버그를 보고해주세요.
|