docs: README/CHANGELOG 업데이트 — Attention 서브시스템 및 ETF 날짜 수정 반영

- CHANGELOG: v3.0.2 (Attention 서브시스템), v3.0.3 (ETF as_of_date 버그 수정) 항목 추가
- README: ETF Holdings 섹션에 정확한 날짜 매칭 / stale 방지 설명 추가
- README: Attention 서브시스템 Features 및 Available Endpoints 섹션 추가

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

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to Stock Oracle API will be documented in this file.
 
+## [3.0.3] - 2026-03-18
+
+### Fixed
+- **ETF Holdings `as_of_date` 정확도**: 요청 날짜에 가장 가까운 파일링을 반환하도록 수정
+  - `_load_snapshot_holdings()`: DB 캐시 스냅샷과 `as_of_date` 간격이 120일 초과 시 stale 판단, SEC 신규 fetch 트리거
+  - `_find_best_filing_and_xml()`: eligible 후보 필터에 365일 하한 추가 — target_date 기준 1년 이내 파일링 우선 탐색
+  - 수정 전: `SPY?as_of_date=2021-06-30` → 2019-11-18 (19개월 stale)
+  - 수정 후: `SPY?as_of_date=2021-06-30` → 2021-05-28 (정상)
+
+## [3.0.2] - 2026-03-17
+
+### Added
+- **Attention 서브시스템**: 이벤트 중심 Wikipedia/GDELT 관심도 피처 (백테스팅용)
+  - `GET /api/v1/attention/event/{ticker}?event_date=YYYY-MM-DD` — 이벤트 날짜 기준 관심도 피처 조회
+  - `GET /api/v1/attention/entity/{ticker}` — 티커 → 캐노니컬 엔티티 정보 조회
+  - `POST /api/v1/attention/admin/resolve/{ticker}` — 티커 → 캐노니컬 엔티티 해석
+  - `POST /api/v1/attention/admin/collect/wiki/{ticker}` — Wikipedia 페이지뷰 수집
+  - `POST /api/v1/attention/admin/collect/gdelt/{ticker}` — GDELT 뉴스 아티클 수집
+  - Wikipedia 일별 페이지뷰 스파이크 / z-score 계산
+  - GDELT GKG 아티클 수 기반 언론 노출 지표
+
 ## [3.0.1] - 2026-03-14
 
 ### Added

README.md

@@ -34,6 +34,13 @@ Stock Oracle is a comprehensive investment analysis API that leverages SEC EDGAR
 - **Error Handling**: Detailed error categorization and reporting
 - **Migration Support**: Database transfer capabilities
 
+### Attention Subsystem (NEW! 🆕)
+- **Event-Centric Features**: Wikipedia pageviews + GDELT news coverage for backtesting
+- **Spike Detection**: Daily pageview spike ratio and z-score vs. rolling baseline
+- **GDELT Integration**: News article count from GDELT GKG (global knowledge graph)
+- **Entity Resolution**: Ticker → canonical Wikipedia entity mapping
+- **On-Demand Collection**: Collect data per event date without full precomputation
+
 ### Alpaca Market Data (NEW! 🆕)
 - **Official REST API**: Alpaca Market Data v2 with proper authentication
 - **OHLCV + VWAP**: Daily/intraday bars with volume-weighted average price
@@ -580,19 +587,24 @@ curl "http://localhost:18001/api/v1/fred/stats/usage"      # Monitor API usage (
 # Get latest holdings for QQQ
 curl "http://localhost:18001/api/v1/etf/holdings/QQQ"
 
-# Get holdings for specific date
+# Get holdings for specific date (returns closest prior NPORT-P filing)
-curl "http://localhost:18001/api/v1/etf/holdings/QQQM?as_of_date=2024-01-01"
+curl "http://localhost:18001/api/v1/etf/holdings/SPY?as_of_date=2021-06-30"
 
 # Without detailed holdings (metadata only)
 curl "http://localhost:18001/api/v1/etf/holdings/SPY?include_holdings=false"
+
+# Bypass Redis cache to force fresh fetch
+curl "http://localhost:18001/api/v1/etf/holdings/SPY?as_of_date=2021-06-30&force_refresh=true"
 ```
 
 #### Key Features
 - **Automatic CIK Lookup**: No need to know CIK numbers - just use ticker symbols
 - **Historical Data Support**: Access NPORT filings from 2019 onwards
+- **Accurate Date Matching**: Returns the closest NPORT-P filing ≤ `as_of_date` within 365-day window
+- **Stale Cache Prevention**: DB snapshots >120 days from requested date trigger fresh SEC fetch
 - **Date Validation**: Automatically checks if ETF existed on requested date
 - **Availability Info**: Returns available date ranges when data not found
-- **Fast Performance**: <0.1s response time with launch date caching
+- **Fast Performance**: <0.1s response time for cached results; Redis-backed 1-hour cache
 
 #### Response with Availability Information
 ```json
@@ -758,9 +770,16 @@ curl "http://localhost:18001/api/v1/news/NVDA/social-only?days_back=3&max_social
 - `GET /api/v1/fred/stats/usage` - API usage statistics and daily limit monitoring
 
 #### ETF Holdings
-- `GET /api/v1/etf/holdings/{ticker}` - Get ETF holdings with date support
+- `GET /api/v1/etf/holdings/{ticker}` - Get ETF holdings with date support (closest NPORT-P filing)
 - `POST /api/v1/etf/admin/refresh-maps` - Refresh ETF CIK mappings
 
+#### Attention (Backtesting Features)
+- `GET /api/v1/attention/event/{ticker}` - Event-date attention features (Wikipedia pageviews + GDELT coverage)
+- `GET /api/v1/attention/entity/{ticker}` - Canonical entity info for ticker
+- `POST /api/v1/attention/admin/resolve/{ticker}` - Resolve ticker → canonical entity
+- `POST /api/v1/attention/admin/collect/wiki/{ticker}` - Collect Wikipedia pageview data
+- `POST /api/v1/attention/admin/collect/gdelt/{ticker}` - Collect GDELT news article data
+
 #### Financial Data
 - `GET /api/v1/financial/data/{ticker}` - Simple financial data with query parameters
 - `POST /api/v1/financial/data` - Detailed financial data request