From 841e68e3cd50748a572f40fc4634a75d70e04b44 Mon Sep 17 00:00:00 2001
From: I Luk Kim <yirugi@gmail.com>
Date: Sat, 14 Mar 2026 20:49:06 -0700
Subject: [PATCH] =?UTF-8?q?docs:=20just=20run=20dev=20=EB=AA=85=EB=A0=B9?=
 =?UTF-8?q?=EC=96=B4=20=EB=B0=8F=20index=20=EC=97=94=EB=93=9C=ED=8F=AC?=
 =?UTF-8?q?=EC=9D=B8=ED=8A=B8=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README/API_DOCUMENTATION에 `just run dev` 개발 서버 실행 방법 추가
- `GET /stocks/index/{index_name}` 엔드포인트 문서화 (sp500/nasdaq100)
- justfile을 프로젝트 파일로 문서에 포함

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 API_DOCUMENTATION.md | 54 ++++++++++++++++++++++++++++++++++++++++++++
 README.md            | 11 +++++++--
 justfile             |  6 +++++
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 justfile

diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md
index 0244aa4..136169b 100644
--- a/API_DOCUMENTATION.md
+++ b/API_DOCUMENTATION.md
@@ -8,6 +8,16 @@ Stock Oracle provides comprehensive financial, price, news, and social media dat
 
 ## 🚀 Quick Start
 
+### Running the API
+
+```bash
+# Start all services (first time)
+docker-compose up -d
+
+# Restart API after code changes
+just run dev
+```
+
 ### Base URL
 ```
 http://localhost:18001/api/v1
@@ -335,6 +345,50 @@ Download and ingest FINRA short volume file(s) for a specific date or date range
 
 ### Stock Market Data 🆕
 
+#### `GET /stocks/index/{index_name}`
+S&P 500 또는 Nasdaq 100 구성 종목을 Wikipedia에서 조회합니다.
+
+**Path Parameters:**
+- `index_name`: `sp500` 또는 `nasdaq100`
+
+**Query Parameters:**
+- `force_refresh`: `true`/`false` (default: `false`) — 캐시 무시하고 재조회
+
+**Caching:**
+- TTL: 24시간 (`Cache-Control: public, max-age=86400`)
+- `X-Cache: HIT` / `MISS`, `ETag` 헤더 포함
+
+**Response:**
+```json
+{
+  "success": true,
+  "index": "sp500",
+  "count": 503,
+  "constituents": [
+    {
+      "symbol": "AAPL",
+      "name": "Apple Inc.",
+      "sector": "Information Technology",
+      "industry": "Technology Hardware, Storage & Peripherals"
+    }
+  ]
+}
+```
+
+**Examples:**
+```
+GET /stocks/index/sp500        → S&P 500 구성 종목 (~503개)
+GET /stocks/index/nasdaq100    → Nasdaq 100 구성 종목 (~101개)
+GET /stocks/index/sp500?force_refresh=true  → 캐시 무시하고 재조회
+GET /stocks/index/foo          → 400 Bad Request
+```
+
+**Error Codes:**
+- `400`: 지원하지 않는 `index_name`
+- `504`: Wikipedia 응답 30초 초과
+
+---
+
 #### `GET /stocks/most-active`
 Most actively traded stocks from Yahoo Finance.
 
diff --git a/README.md b/README.md
index fcffe50..d3e6c09 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ Stock Oracle is a comprehensive investment analysis API that leverages SEC EDGAR
 ### Market Data Intelligence (NEW! 🆕)
 - **Most Active Stocks**: Real-time ~170 most actively traded stocks (sub-5s response)
 - **52-Week Gainers**: 1,350+ top gaining stocks with intelligent rate limiting (5-90s)
+- **Index Constituents**: S&P 500 / Nasdaq 100 구성 종목 조회 — Wikipedia 파싱, 24시간 캐시
 - **FRED Economic Data**: Federal Reserve economic indicators with smart caching (1000/day limit)
 - **Advanced Web Scraping**: curl_cffi + Chrome impersonation bypasses rate limits
 - **Smart Pagination**: Configurable page limits (1-10 pages) for performance tuning
@@ -94,10 +95,15 @@ pip install -r requirements-api.txt
 cp .env.example .env
 # Edit .env with your settings
 
-# Run the API
-python -m uvicorn app.main:app --host 0.0.0.0 --port 18000 --reload
+# Start all services (first time)
+docker-compose up -d
+
+# Restart API after code changes (code is volume-mounted, no rebuild needed)
+just run dev
 ```
 
+> **Note**: Always use `just run dev` to restart the API. The `app/` directory is volume-mounted into the container, so code changes take effect on restart without rebuilding the image.
+
 ## ⚡ Quick Examples
 
 ### Get Market Overview
@@ -733,6 +739,7 @@ curl "http://localhost:18001/api/v1/news/NVDA/social-only?days_back=3&max_social
 - `GET /api/v1/stocks/trending` - **Trending stocks combining most active + 52-week gainers** (🚀 Recommended)
 - `GET /api/v1/stocks/most-active` - Most actively traded stocks (optional limit parameter)
 - `GET /api/v1/stocks/52-week-gainers` - 52-week top gaining stocks with intelligent rate limiting
+- `GET /api/v1/stocks/index/{index_name}` - S&P 500 / Nasdaq 100 constituents from Wikipedia (24h cache)
 
 #### Alpaca Market Data (NEW! 🆕)
 - `GET /api/v1/alpaca/status` - Alpaca connection status and API key validation
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..b0c3e3a
--- /dev/null
+++ b/justfile
@@ -0,0 +1,6 @@
+# Stock Oracle dev commands
+
+# Restart API container (code is volume-mounted, so this picks up changes immediately)
+run dev:
+    docker restart stock_oracle_api
+    docker logs -f stock_oracle_api