# 📦 SightRay 데이터 수집 엔진 – 기능 요약 및 MVP 충족도 평가

---

## ✅ 엔진 개요

**SightRay 데이터 수집 엔진**은 외부 주가 API(Polygon 등)를 통해 종목별 OHLCV 데이터를 수집하고,
분석 엔진이 바로 사용할 수 있도록 정제된 CDS(Complete Data Set)를 생성하는 핵심 모듈입니다.

- **입력:** 종목 코드, 날짜 범위
- **출력:** 정제된 CDS 파일 (CSV 형식)
- **사용자 입력 기반 동작 (CLI)**
- **기술 지표 생성은 포함하지 않음 → 분석 엔진에서 처리**

---

## 🧩 디렉토리 구조 및 구성 파일

```plaintext
sightray/
└── data_collection_engine/
    ├── engine.py                 # 수집 실행을 담당하는 통합 엔진 클래스
    └── modules/
        ├── fetchers/
        │   └── polygon.py        # Polygon API를 통한 주가 수집 기능
        └── preprocessors.py     # 결측/중복 제거, timestamp 정제 등 전처리
```

| 파일명 | 역할 | 계층 |
|--------|------|------|
| `engine.py` | 사용자 입력 → 수집 → 전처리 → 저장 흐름 실행 | Engine Layer |
| `fetchers/polygon.py` | Polygon API로 OHLCV 데이터 수집 | Module Layer |
| `preprocessors.py` | 데이터 클렌징 및 CDS 구조 정제 | Module Layer |

---

## 🔁 데이터 흐름

```plaintext
[사용자 입력: 종목, 날짜 범위]
   ↓
fetchers/polygon.py → Polygon API 호출
   ↓
preprocessors.py → DataFrame 정제 및 컬럼 리네이밍
   ↓
engine.py → 전체 흐름 제어 및 CSV 저장 (data/SYMBOL_ohlcv.csv)
```

---

## ✅ 구현된 기능 목록

| 기능 항목 | 구현 여부 | 설명 |
|-----------|-----------|--------|
| 사용자 입력 처리 | ✅ | 종목코드, 날짜 범위 입력 가능 (CLI 기반) |
| 외부 API 연동 | ✅ | Polygon API 연동 및 에러 핸들링 포함 |
| 결측치/중복 제거 | ✅ | DataFrame 전처리 수행 |
| 컬럼 정제 및 타입 변환 | ✅ | 컬럼 이름 변경, datetime 변환 포함 |
| 정렬 및 저장 | ✅ | timestamp 기준 정렬 후 CSV 저장 |
| 디렉토리 구조화 | ✅ | fetcher / preprocessor 모듈 분리 구조 적용 |
| 환경변수 관리 | ✅ | `.env` 파일로 API 키 분리 |
| CDS 정의 준수 | ✅ | 분석 엔진이 바로 사용할 수 있는 포맷 제공 |

---

## 📄 생성되는 CDS 예시

| timestamp | open | high | low | close | volume | vw | n |
|-----------|------|------|-----|-------|--------|----|---|
| 2024-01-02 | 187.15 | 188.44 | 183.88 | 185.64 | 81964874 | 185.9465 | 1008871 |

- timestamp는 정렬 및 datetime 형식 변환 완료
- 분석용 OHLCV 컬럼 포함
- 거래량(volume), 체결 수(n), 거래량 가중 평균가(vw) 포함

### 🔍 `vw` 컬럼 (거래량 가중 평균가, VWAP)
- 해당 기간 동안 체결된 가격과 거래량을 기반으로 산출된 **실질적인 평균 매수/매도 가격**
- 계산식 예시:  
  \[
  VWAP = \\frac{\\sum (\\text{가격} \\times \\text{거래량})}{\\sum \\text{거래량}}
  \]
- **기술 지표로도 활용됨** (지지선/저항선 판단 근거로 자주 사용)
- `Polygon.io`의 응답에 포함된 기본 컬럼으로, SightRay는 그대로 CDS에 반영


---

## 🎯 MVP 충족도 평가

| 항목 | 달성률 | 설명 |
|-------|---------|------------------------|
| CDS 수집 및 저장 | ✅ 100% | 분석에 활용 가능한 형식으로 저장 완료 |
| CLI 실행 및 구조화 | ✅ | 사용자 친화적 구조로 엔진 실행 가능 |
| 지표 생성 미포함 | ⛔ | 지표는 분석 엔진에서 처리 예정 |
| API 오류 대응 | ✅ | 응답 코드 체크 및 예외 처리 구현 |
| 확장 가능성 (다중 종목, 자동화) | 🔜 | 향후 배치 처리 및 스케줄링 가능성 고려됨 |

---

## ✅ 결론

SightRay의 데이터 수집 엔진은 MVP 기준에서 요구되는 **CDS 생성 기능을 완전히 충족**하고 있으며,
다음 단계인 분석 엔진, 리스크 엔진으로 원활하게 데이터를 공급할 수 있는 상태입니다.

> 🚀 이후 확장 과제로는 다중 종목 수집, 자동화 실행 스케줄링, DB 저장 연계 기능이 고려될 수 있습니다.