penti/docs/DEPLOYMENT_CHECKLIST.md

# Deployment Checklist

퇴직연금 리밸런싱 + Quant 플랫폼 배포 체크리스트

## 배포 전 준비 사항

### 1. 환경 설정

- [ ] `.env` 파일 생성 (`.env.example` 참고)
- [ ] 프로덕션용 데이터베이스 비밀번호 설정
- [ ] JWT 시크릿 키 생성 (필요한 경우)
- [ ] Redis 비밀번호 설정
- [ ] CORS 허용 도메인 설정

### 2. 데이터베이스

- [ ] PostgreSQL 15 설치 확인
- [ ] TimescaleDB 익스텐션 설치
- [ ] 데이터베이스 생성
- [ ] Alembic 마이그레이션 실행
- [ ] 인덱스 생성 확인

### 3. 데이터 수집

- [ ] MySQL에서 PostgreSQL로 데이터 마이그레이션 실행
- [ ] 티커 데이터 수집 실행
- [ ] 가격 데이터 수집 실행
- [ ] 재무제표 데이터 수집 실행
- [ ] 섹터 데이터 수집 실행

### 4. 테스트

- [ ] 단위 테스트 통과 (`pytest -m unit`)
- [ ] 통합 테스트 통과 (`pytest -m integration`)
- [ ] 백테스트 엔진 검증
- [ ] 전략 일관성 확인
- [ ] API 엔드포인트 테스트
- [ ] Frontend 빌드 성공

### 5. 성능 최적화

- [ ] 데이터베이스 쿼리 최적화
- [ ] 인덱스 튜닝
- [ ] Redis 캐싱 설정
- [ ] Nginx 설정 최적화
- [ ] 이미지 최적화 (Docker)

## Docker 배포

### 1. 이미지 빌드

```bash
# 전체 이미지 빌드
docker-compose build

# 특정 서비스만 빌드
docker-compose build backend
docker-compose build frontend
```

### 2. 서비스 시작

```bash
# 전체 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f
```

### 3. 서비스 확인

- [ ] PostgreSQL: `docker-compose ps postgres`
- [ ] Redis: `docker-compose ps redis`
- [ ] Backend: `http://localhost:8000/health`
- [ ] Frontend: `http://localhost:3000`
- [ ] Celery Worker: `docker-compose ps celery_worker`
- [ ] Celery Beat: `docker-compose ps celery_beat`
- [ ] Flower: `http://localhost:5555`
- [ ] Nginx: `http://localhost` (포트 80)

### 4. 데이터베이스 마이그레이션

```bash
docker-compose exec backend alembic upgrade head
```

### 5. 초기 데이터 수집

```bash
# 전체 데이터 수집
curl -X POST http://localhost:8000/api/v1/data/collect/all

# 또는 개별 수집
curl -X POST http://localhost:8000/api/v1/data/collect/ticker
curl -X POST http://localhost:8000/api/v1/data/collect/price
curl -X POST http://localhost:8000/api/v1/data/collect/financial
curl -X POST http://localhost:8000/api/v1/data/collect/sector
```

## 검증

### 1. 자동 검증 스크립트

```bash
python scripts/verify_deployment.py
```

### 2. 수동 검증

#### API 엔드포인트 테스트

```bash
# Health check
curl http://localhost:8000/health

# 전략 목록
curl http://localhost:8000/api/v1/backtest/strategies/list

# 데이터베이스 통계
curl http://localhost:8000/api/v1/data/stats

# 포트폴리오 목록
curl http://localhost:8000/api/v1/portfolios/?skip=0&limit=10
```

#### 백테스트 실행

```bash
curl -X POST http://localhost:8000/api/v1/backtest/run \
  -H "Content-Type: application/json" \
  -d @samples/backtest_config.json
```

#### 포트폴리오 생성

```bash
curl -X POST http://localhost:8000/api/v1/portfolios/ \
  -H "Content-Type: application/json" \
  -d @samples/portfolio_create.json
```

### 3. Frontend 테스트

- [ ] 브라우저에서 `http://localhost:3000` 접속
- [ ] 백테스트 탭 동작 확인
- [ ] 리밸런싱 탭 동작 확인
- [ ] 데이터 관리 탭 확인
- [ ] 차트 렌더링 확인

### 4. Celery 작업 확인

- [ ] Flower 대시보드 접속 (`http://localhost:5555`)
- [ ] 워커 상태 확인
- [ ] 태스크 히스토리 확인
- [ ] Beat 스케줄 확인 (평일 18시 자동 수집)

## 모니터링

### 1. 로그 확인

```bash
# 전체 로그
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f backend
docker-compose logs -f celery_worker
docker-compose logs -f postgres
```

### 2. 리소스 사용량

```bash
# Docker 컨테이너 리소스 사용량
docker stats

# 디스크 사용량
docker system df
```

### 3. 데이터베이스 모니터링

```bash
# PostgreSQL 연결
docker-compose exec postgres psql -U postgres -d pension_quant

# 테이블 크기 확인
SELECT
    schemaname,
    tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

# 레코드 수 확인
SELECT
    'assets' as table_name, COUNT(*) FROM assets
UNION ALL
SELECT 'price_data', COUNT(*) FROM price_data
UNION ALL
SELECT 'financial_statements', COUNT(*) FROM financial_statements
UNION ALL
SELECT 'portfolios', COUNT(*) FROM portfolios;
```

## 백업

### 1. 데이터베이스 백업

```bash
# 백업 생성
docker-compose exec postgres pg_dump -U postgres pension_quant > backup_$(date +%Y%m%d).sql

# 백업 복원
docker-compose exec -T postgres psql -U postgres pension_quant < backup_20240101.sql
```

### 2. 자동 백업 설정

cron에 백업 스크립트 등록:

```bash
# /etc/cron.daily/pension-quant-backup
#!/bin/bash
cd /path/to/pension-quant-platform
docker-compose exec postgres pg_dump -U postgres pension_quant | gzip > /backups/pension_quant_$(date +%Y%m%d).sql.gz
find /backups -name "pension_quant_*.sql.gz" -mtime +30 -delete
```

## 문제 해결

### 컨테이너가 시작되지 않을 때

```bash
# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs [service_name]

# 재시작
docker-compose restart [service_name]
```

### 데이터베이스 연결 실패

```bash
# PostgreSQL 상태 확인
docker-compose exec postgres pg_isready -U postgres

# 연결 테스트
docker-compose exec postgres psql -U postgres -c "SELECT 1"
```

### Celery 워커 문제

```bash
# 워커 상태 확인
docker-compose exec celery_worker celery -A app.celery_app inspect ping

# 워커 재시작
docker-compose restart celery_worker celery_beat
```

### 디스크 공간 부족

```bash
# 사용하지 않는 Docker 리소스 정리
docker system prune -a

# 오래된 백업 삭제
find /backups -name "*.sql.gz" -mtime +90 -delete
```

## 보안 체크리스트

- [ ] 데이터베이스 비밀번호 변경 (기본값 사용 금지)
- [ ] Redis 비밀번호 설정
- [ ] 방화벽 설정 (필요한 포트만 개방)
- [ ] HTTPS 설정 (프로덕션 환경)
- [ ] CORS 허용 도메인 제한
- [ ] API Rate Limiting 설정
- [ ] 로그에 민감정보 노출 방지

## 성능 최적화

### 1. PostgreSQL 튜닝

```sql
-- shared_buffers 증가 (RAM의 25%)
ALTER SYSTEM SET shared_buffers = '4GB';

-- effective_cache_size 증가 (RAM의 50-75%)
ALTER SYSTEM SET effective_cache_size = '8GB';

-- work_mem 증가
ALTER SYSTEM SET work_mem = '64MB';

-- maintenance_work_mem 증가
ALTER SYSTEM SET maintenance_work_mem = '512MB';

-- 설정 재로드
SELECT pg_reload_conf();
```

### 2. 인덱스 생성

```sql
-- 자주 사용되는 쿼리에 인덱스 추가
CREATE INDEX idx_price_data_ticker_timestamp ON price_data (ticker, timestamp DESC);
CREATE INDEX idx_financial_ticker_date ON financial_statements (ticker, base_date DESC);
CREATE INDEX idx_assets_sector ON assets (sector) WHERE is_active = true;
```

### 3. TimescaleDB 압축

```sql
-- 압축 정책 활성화 (1년 이상 된 데이터)
ALTER TABLE price_data SET (
    timescaledb.compress,
    timescaledb.compress_segmentby = 'ticker'
);

SELECT add_compression_policy('price_data', INTERVAL '1 year');
```

## 업데이트 프로세스

### 1. 코드 업데이트

```bash
# Git pull
git pull origin main

# 이미지 재빌드
docker-compose build

# 서비스 재시작
docker-compose up -d
```

### 2. 데이터베이스 마이그레이션

```bash
# 마이그레이션 파일 생성 (필요한 경우)
docker-compose exec backend alembic revision --autogenerate -m "description"

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

### 3. 무중단 업데이트

```bash
# Blue-Green 배포 또는 Rolling 업데이트
# (Kubernetes, Docker Swarm 등 사용 시)
```

## 최종 확인

- [ ] 모든 서비스가 정상 동작
- [ ] 백테스트 실행 성공
- [ ] 데이터 수집 자동화 동작
- [ ] 리밸런싱 계산 정확성 확인
- [ ] Frontend 정상 렌더링
- [ ] Celery 작업 스케줄 확인
- [ ] 백업 설정 완료
- [ ] 모니터링 설정 완료
- [ ] 문서화 완료

배포 완료! 🚀