From d43048788240c6560874374b054c0986c8c7483e Mon Sep 17 00:00:00 2001 From: I Luk Kim Date: Sun, 29 Mar 2026 16:21:55 -0700 Subject: [PATCH] =?UTF-8?q?chore:=20yfinance=5Fplus=20=EC=84=9C=EB=B8=8C?= =?UTF-8?q?=EB=AA=A8=EB=93=88=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20+?= =?UTF-8?q?=20API=20=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4?= =?UTF-8?q?=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - yfinance_plus: period=None 방어 코드, 테스트 파일 제거 - docs: insider/earnings/universe 엔드포인트 문서 추가 Co-Authored-By: Claude Sonnet 4.6 --- docs/DATA_COVERAGE.md | 176 +++++++++++++++++++++++++++++++++++++++++- yfinance_plus | 2 +- 2 files changed, 176 insertions(+), 2 deletions(-) diff --git a/docs/DATA_COVERAGE.md b/docs/DATA_COVERAGE.md index f00c23f..1c3e31a 100644 --- a/docs/DATA_COVERAGE.md +++ b/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§or=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§or=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; ``` diff --git a/yfinance_plus b/yfinance_plus index d18976d..df26cb7 160000 --- a/yfinance_plus +++ b/yfinance_plus @@ -1 +1 @@ -Subproject commit d18976d4aa58c9df58c55f47a77b568d8ce8581e +Subproject commit df26cb7e1923f7a7352fddc75ee0c62ee77d7881