chore: yfinance_plus 서브모듈 업데이트 + API 문서 업데이트

- yfinance_plus: period=None 방어 코드, 테스트 파일 제거
- docs: insider/earnings/universe 엔드포인트 문서 추가

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/DATA_COVERAGE.md

@@ -2,7 +2,7 @@
 
 각 API 엔드포인트의 **실제 DB 보유 데이터 범위**와 **과거 데이터 백필 방법**을 정리한 문서입니다.
 
-> 마지막 업데이트: 2026-03-23
+> 마지막 업데이트: 2026-03-29
 > DB 실측 기준
 
 ---
@@ -22,6 +22,9 @@
 | `/overlay/{symbol}` | Yahoo/YouTube/Wikipedia/FINRA | ✅ | 2026-03-17 ~ 현재 (50 심볼) | 서비스 시작 이후 | 과거 백필 불가 |
 | `/overlay/{symbol}/headlines` | Yahoo Finance RSS | ✅ | 2026-02-24 ~ 현재 | 서비스 시작 이후 | 과거 백필 불가 |
 | `/overlay/{symbol}/wiki` | Wikipedia Pageviews API | ✅ | 2015-12-26 ~ 현재 | 2015년~ | 자동 수집됨 |
+| `/insider/transactions` | SEC EDGAR Form 4 | ✅ | 요청 기반 자동 누적 | 2004년~ | 요청 기반 자동 누적 |
+| `/earnings/surprise` | yfinance-plus earnings_dates | ✅ | 요청 기반 자동 누적 | ~25분기 (6년+) | 요청 기반 자동 누적 |
+| `/universe/screen` | SEC EDGAR + yfinance 월별 스냅샷 | ✅ (사전 빌드 필요) | admin 빌드 후 사용 가능 | 2010년~ | **⚠️ 사전 빌드 필요** |
 
 ---
 
@@ -205,11 +208,166 @@ GET /api/v1/overlay/admin/health
 
 ---
 
+### `/api/v1/insider` — 내부자 거래 (SEC Form 4)
+
+**현재 DB 보유**: 요청 기반 자동 누적 (첫 조회 시 자동 인덱싱)
+
+**이론적 범위**: 2004년~ (EDGAR 전자 파일링 이후). 실제 커버리지는 기업마다 다름.
+
+**조회 파라미터**:
+- `GET /insider/transactions/{symbol}?days=90&transaction_type=P-Purchase`
+- `GET /insider/summary/{symbol}?period=90d`: 집계 요약 (매수/매도 금액, 순매수)
+
+**지원 거래 유형**: `P-Purchase`, `S-Sale`, `A-Award`, `D-Return`, `F-TaxWithholding`, `G-Gift`, `M-OptionExercise`
+
+**동작 방식**: 첫 조회 시 SEC EDGAR Form 4 XML 자동 파싱 → DB 저장. 이후 캐시.
+
+```bash
+# 최근 90일 내부자 거래 조회 (자동 인덱싱)
+curl "http://localhost:18001/api/v1/insider/transactions/NVDA?days=90"
+
+# 내부자 매매 요약 (순매수/매도 금액)
+curl "http://localhost:18001/api/v1/insider/summary/AAPL?period=90d"
+```
+
+---
+
+### `/api/v1/earnings` — 어닝 서프라이즈 (yfinance-plus)
+
+**현재 DB 보유**: 요청 기반 자동 누적 (첫 조회 시 자동 인덱싱)
+
+**이론적 범위**: 약 25분기 (6년+). yfinance `earnings_dates` 데이터 기준.
+
+**조회 파라미터**:
+- `GET /earnings/surprise/{symbol}?limit=20`: 분기별 EPS surprise 이력
+
+**반환 필드**: `reported_eps`, `estimated_eps`, `surprise`, `surprise_percentage`, `streak`
+- `surprise` = reported_eps − estimated_eps
+- `surprise_percentage` = (surprise / estimated) × 100
+- `streak`: 연속 beat(+) 또는 miss(−) 횟수
+
+**동작 방식**: 첫 조회 시 yfinance `earnings_dates` 자동 인제스트 → DB 저장. 이후 1시간 Redis 캐시.
+
+```bash
+# 어닝 서프라이즈 이력 조회 (자동 인덱싱)
+curl "http://localhost:18001/api/v1/earnings/surprise/AAPL?limit=20"
+```
+
+---
+
+### `/api/v1/universe` — 과거 주식 유니버스 (백테스팅)
+
+**현재 DB 보유**: admin 엔드포인트로 사전 빌드 필요 (초기에는 빈 상태)
+
+**이론적 범위**: 2010년~ (SEC EDGAR 데이터 + yfinance 가격 데이터 가용 범위)
+
+**데이터 소스**: SEC EDGAR `companyfacts` (shares_outstanding) × yfinance 월별 종가 → 월별 시총 계산
+
+> **Survivorship bias 주의**: 현재 상장된 종목만 포함. 상폐 종목 미포함.
+> **정확도**: 시총 오차 ±10~20% (buyback 반영 지연, SEC 분기별 업데이트 때문).
+
+#### 워크플로우
+
+```
+1단계: 유니버스 등록 (1~5분)
+POST /universe/admin/discover?market_cap_min=100000000
+→ yfinance screener로 ~3000~5000 종목 발견
+→ universe_ticker_registry 테이블에 저장
+
+2단계: 스냅샷 빌드 (30~60분, 백그라운드)
+POST /universe/admin/build-snapshots
+→ SEC EDGAR shares_outstanding × yfinance 월별 종가 = 월별 시총
+→ universe_snapshot 테이블에 ~480K 행 저장 (4000 × 120개월)
+
+3단계: 과거 스크리닝
+GET /universe/screen?date=2018-01-01&market_cap_min=2e9&market_cap_max=20e9
+→ 2018년 초 기준 시총 $2B~$20B 종목 목록 반환
+```
+
+#### 엔드포인트 상세
+
+**`GET /universe/screen`** — 과거 시점 기준 종목 스크리닝
+
+| 파라미터 | 필수 | 설명 |
+|---|---|---|
+| `date` | ✅ | 기준 날짜 YYYY-MM-DD (월초로 자동 반올림) |
+| `market_cap_min` | - | 최소 시총 (USD), 예: `2e9` = $2B |
+| `market_cap_max` | - | 최대 시총 (USD), 예: `20e9` = $20B |
+| `sector` | - | 섹터 필터 (예: `Technology`, `Healthcare`) |
+| `exchange` | - | 거래소 필터 (`NYSE`, `NASDAQ`, `AMEX`) |
+| `page` / `page_size` | - | 페이지네이션 (기본 100, 최대 500) |
+| `sort_by` | - | 정렬 기준 (`market_cap` 또는 `ticker`) |
+
+```bash
+# 2018년 초 시총 $2B~$20B 종목 (Small/Mid Cap)
+curl "http://localhost:18001/api/v1/universe/screen?date=2018-01-01&market_cap_min=2000000000&market_cap_max=20000000000"
+
+# 2020년 기준 Technology 섹터 Large Cap ($10B+)
+curl "http://localhost:18001/api/v1/universe/screen?date=2020-01-01&market_cap_min=10000000000&sector=Technology"
+
+# 2023년 기준 Top 100 시총 순위
+curl "http://localhost:18001/api/v1/universe/screen?date=2023-01-01&sort_by=market_cap&sort_ascending=false&page_size=100"
+```
+
+**`GET /universe/registry`** — 등록된 종목 목록 조회
+
+```bash
+# 등록된 전체 종목 조회
+curl "http://localhost:18001/api/v1/universe/registry?page_size=200"
+
+# NASDAQ 기술주 필터
+curl "http://localhost:18001/api/v1/universe/registry?exchange=NASDAQ&sector=Technology"
+```
+
+**`POST /universe/admin/discover`** — 종목 발견 및 등록
+
+```bash
+# $100M 이상 ~3000~5000 종목 등록 (1~5분 소요)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/discover?market_cap_min=100000000"
+
+# 소규모 테스트 ($1T 이상, ~50 종목)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/discover?market_cap_min=1000000000000"
+```
+
+**`POST /universe/admin/build-snapshots`** — 월별 시총 스냅샷 빌드
+
+```bash
+# 소규모 테스트 (3 종목 × 2년, 즉시 반환)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/build-snapshots" \
+  -H "Content-Type: application/json" \
+  -d '{"tickers":["AAPL","MSFT","NVDA"],"start_date":"2023-01-01","end_date":"2024-12-01"}'
+
+# 전체 유니버스 × 10년 빌드 (백그라운드, 30~60분)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/build-snapshots" \
+  -H "Content-Type: application/json" \
+  -d '{"start_date":"2015-01-01","end_date":"2025-12-01","force_rebuild":false}'
+```
+
+> `tickers` 생략 시 registry 전체 대상. 20개 이하면 동기 실행(즉시 결과), 21개 이상이면 백그라운드 실행.
+
+#### 초기 세팅 권장 순서
+
+```bash
+# 1. 유니버스 등록 ($100M+ → ~4000 종목)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/discover?market_cap_min=100000000"
+
+# 2. 전체 스냅샷 빌드 (백그라운드 시작)
+curl -X POST "http://localhost:18001/api/v1/universe/admin/build-snapshots" \
+  -H "Content-Type: application/json" \
+  -d '{"start_date":"2015-01-01","end_date":"2025-12-01"}'
+
+# 3. 빌드 완료 후 스크리닝 테스트
+curl "http://localhost:18001/api/v1/universe/screen?date=2020-01-01&market_cap_min=10000000000"
+```
+
+---
+
 ## 백필 우선순위 권장 사항
 
 | 우선순위 | 대상 | 이유 | 예상 소요 시간 |
 |---|---|---|---|
 | 🔴 높음 | FINRA 1년치 (2025년) | z-score 계산 윈도우(30일)가 너무 짧아 신호 품질 저하 | 20-40분 |
+| 🔴 높음 | Universe 스냅샷 빌드 | 백테스팅 유니버스 기능 사용 전 필수 1회 실행 | 30-60분 (4000 종목 × 10년) |
 | 🟡 중간 | FINRA 2년치 (2024년) | 더 긴 추세 분석 가능 | 1-2시간 |
 | 🟢 낮음 | Alpaca 데이터 | Yahoo Finance와 중복, API 키 필요 | 필요시 |
 
@@ -239,5 +397,21 @@ UNION ALL
 SELECT 'sec_filings', MIN(filing_date)::date, MAX(filing_date)::date, COUNT(DISTINCT filing_date::date), COUNT(DISTINCT ticker) FROM sec_filings
 UNION ALL
 SELECT 'overlay_feature_records', MIN(as_of_ts)::date, MAX(as_of_ts)::date, COUNT(DISTINCT as_of_ts::date), COUNT(DISTINCT symbol) FROM overlay_feature_records
+UNION ALL
+SELECT 'insider_transactions', MIN(transaction_date)::date, MAX(transaction_date)::date, COUNT(DISTINCT transaction_date::date), COUNT(DISTINCT ticker) FROM insider_transactions
+UNION ALL
+SELECT 'earnings_surprise', MIN(earnings_date)::date, MAX(earnings_date)::date, COUNT(DISTINCT earnings_date::date), COUNT(DISTINCT ticker) FROM earnings_surprise
 ORDER BY tbl;
+
+-- Universe 스냅샷 상태 확인
+SELECT
+  COUNT(DISTINCT ticker) AS tickers,
+  COUNT(*) AS snapshots,
+  MIN(snapshot_date)::date AS earliest,
+  MAX(snapshot_date)::date AS latest
+FROM universe_snapshot;
+
+-- Universe 등록 종목 수
+SELECT COUNT(*) AS registered, COUNT(*) FILTER (WHERE is_active) AS active
+FROM universe_ticker_registry;
 ```

yfinance_plus

@@ -1 +1 @@
-Subproject commit d18976d4aa58c9df58c55f47a77b568d8ce8581e
+Subproject commit df26cb7e1923f7a7352fddc75ee0c62ee77d7881