penti/QUICKSTART.md

빠른 시작 가이드

🚀 로컬 개발 환경 설정

1. 환경 변수 설정

# .env 파일 생성
cp .env.example .env

.env 파일 편집:

POSTGRES_USER=pension_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=pension_quant
SECRET_KEY=your-super-secret-key-min-32-chars-long
ENVIRONMENT=development

2. Docker 컨테이너 실행

# 모든 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 특정 서비스 로그 확인
docker-compose logs -f backend

3. 데이터베이스 초기화

# 데이터베이스 마이그레이션 실행
docker-compose exec backend alembic upgrade head

# TimescaleDB 확장 활성화 (수동으로 필요 시)
docker-compose exec postgres psql -U pension_user -d pension_quant -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

# price_data 테이블을 하이퍼테이블로 변환
docker-compose exec postgres psql -U pension_user -d pension_quant -c "SELECT create_hypertable('price_data', 'timestamp', if_not_exists => TRUE);"

4. 서비스 확인

모든 서비스가 정상적으로 실행되면 다음 URL에서 접근 가능합니다:

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

헬스체크:

curl http://localhost:8000/health

응답:

{
  "status": "healthy",
  "app_name": "Pension Quant Platform",
  "environment": "development"
}

📊 백테스트 실행 예시

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
    }
  }'

백테스트 결과 조회

# 백테스트 목록 조회
curl http://localhost:8000/api/v1/backtest/

# 특정 백테스트 조회 (ID는 위 실행 결과에서 반환됨)
curl http://localhost:8000/api/v1/backtest/{backtest_id}

사용 가능한 전략 목록 조회

curl http://localhost:8000/api/v1/backtest/strategies/list

응답:

{
  "strategies": [
    {
      "name": "multi_factor",
      "description": "Multi-Factor Strategy (Quality + Value + Momentum)"
    },
    {
      "name": "momentum",
      "description": "Momentum Strategy (12M Return + K-Ratio)"
    }
  ]
}

🗄️ 데이터 마이그레이션 (MySQL → PostgreSQL)

기존 make-quant-py의 MySQL 데이터를 PostgreSQL로 마이그레이션:

# 마이그레이션 스크립트 실행 (구현 예정)
docker-compose exec backend python scripts/migrate_mysql_to_postgres.py

🔧 개발 모드

Backend만 로컬 실행

cd backend

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 환경 변수 설정 (PostgreSQL, Redis는 Docker로 실행 중)
export DATABASE_URL=postgresql://pension_user:pension_password@localhost:5432/pension_quant
export REDIS_URL=redis://localhost:6379/0
export CELERY_BROKER_URL=redis://localhost:6379/1
export SECRET_KEY=your-secret-key

# FastAPI 실행
uvicorn app.main:app --reload

Frontend만 로컬 실행

cd frontend

# 의존성 설치
npm install

# 개발 서버 실행
npm start

Celery 워커 로컬 실행

cd backend

# 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

📈 데이터 수집

수동 데이터 수집 트리거

# API를 통한 수집 트리거 (구현 예정)
curl -X POST http://localhost:8000/api/v1/data/collect/trigger

Celery Beat 스케줄 확인

Flower UI (http://localhost:5555)에서 스케줄 확인 가능

🐛 문제 해결

컨테이너가 시작되지 않는 경우

# 모든 컨테이너 중지
docker-compose down

# 볼륨 포함 완전 삭제
docker-compose down -v

# 재시작
docker-compose up -d

데이터베이스 연결 오류

# PostgreSQL 컨테이너 상태 확인
docker-compose ps postgres

# PostgreSQL 로그 확인
docker-compose logs postgres

# 수동 연결 테스트
docker-compose exec postgres psql -U pension_user -d pension_quant

Backend 오류 확인

# Backend 로그 실시간 확인
docker-compose logs -f backend

# Backend 컨테이너 접속
docker-compose exec backend /bin/bash

# Python 패키지 확인
docker-compose exec backend pip list

🧪 테스트

# Backend 테스트
docker-compose exec backend pytest

# Coverage 포함
docker-compose exec backend pytest --cov=app --cov-report=html

📦 프로덕션 배포

# 프로덕션 모드로 빌드 및 실행
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# 환경 변수는 반드시 프로덕션용으로 변경
# - SECRET_KEY: 강력한 랜덤 문자열
# - POSTGRES_PASSWORD: 강력한 비밀번호
# - CORS 설정 제한

📝 다음 단계

1. ✅ 백테스트 엔진 동작 확인
2. ⬜ 샘플 데이터 추가 (scripts/seed_data.py)
3. ⬜ 추가 전략 구현 (Magic Formula, Super Quality)
4. ⬜ Frontend UI 개발
5. ⬜ 리밸런싱 기능 구현
6. ⬜ Celery 데이터 수집 구현

🆘 도움말

• API 문서: http://localhost:8000/docs
• 이슈 리포트: GitHub Issues
• 문의: [프로젝트 관리자 이메일]