penti/docs/QUICKSTART.md

# 빠른 시작 가이드

## 🚀 로컬 개발 환경 설정

### 1. 환경 변수 설정

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

`.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 컨테이너 실행

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

# 로그 확인
docker-compose logs -f

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

### 3. 데이터베이스 초기화

```bash
# 데이터베이스 마이그레이션 실행
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

헬스체크:
```bash
curl http://localhost:8000/health
```

응답:
```json
{
  "status": "healthy",
  "app_name": "Pension Quant Platform",
  "environment": "development"
}
```

## 📊 백테스트 실행 예시

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

### 백테스트 결과 조회

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

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

### 사용 가능한 전략 목록 조회

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

응답:
```json
{
  "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로 마이그레이션:

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

## 🔧 개발 모드

### Backend만 로컬 실행

```bash
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만 로컬 실행

```bash
cd frontend

# 의존성 설치
npm install

# 개발 서버 실행
npm start
```

### Celery 워커 로컬 실행

```bash
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
```

## 📈 데이터 수집

### 수동 데이터 수집 트리거

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

### Celery Beat 스케줄 확인

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

## 🐛 문제 해결

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

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

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

# 재시작
docker-compose up -d
```

### 데이터베이스 연결 오류

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

# PostgreSQL 로그 확인
docker-compose logs postgres

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

### Backend 오류 확인

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

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

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

## 🧪 테스트

```bash
# Backend 테스트
docker-compose exec backend pytest

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

## 📦 프로덕션 배포

```bash
# 프로덕션 모드로 빌드 및 실행
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
- 문의: [프로젝트 관리자 이메일]