# 퇴직연금 리밸런싱 + 한국 주식 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를 환영합니다!

## 📞 문의

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