From 10b15a4563cfff6337043b48663b6ca11245cd5d Mon Sep 17 00:00:00 2001
From: agentson <agentson@localhost>
Date: Tue, 17 Feb 2026 05:57:56 +0900
Subject: [PATCH] docs: reflect overseas ranking integration and
 volatility-first selection

---
 docs/architecture.md     | 37 +++++++++++++++++++++++++++----------
 docs/requirements-log.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 10 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index e31ea9c..a75f1b9 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -68,6 +68,10 @@ High-frequency trading with individual stock analysis:
 - `fetch_market_rankings()` — Fetch volume surge rankings from KIS API
 - `get_daily_prices()` — Fetch OHLCV history for technical analysis
 
+**Overseas Ranking API Methods** (added in v0.10.x):
+- `fetch_overseas_rankings()` — Fetch overseas ranking universe (fluctuation / volume)
+- Ranking endpoint paths and TR_IDs are configurable via environment variables
+
 ### 2. Analysis (`src/analysis/`)
 
 **VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations
@@ -81,14 +85,20 @@ High-frequency trading with individual stock analysis:
 
 **SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline
 
-- **Step 1**: Fetch volume rankings from KIS API (top 30 stocks)
-- **Step 2**: Calculate RSI and volume ratio for each stock
-- **Step 3**: Apply filters:
+- **Domestic (KR)**:
+  - **Step 1**: Fetch volume rankings from KIS API (top 30 stocks)
+  - **Step 2**: Calculate RSI and volume ratio for each stock
+  - **Step 3**: Apply filters:
   - Volume ratio >= `VOL_MULTIPLIER` (default 2.0x previous day)
   - RSI < `RSI_OVERSOLD_THRESHOLD` (30) OR RSI > `RSI_MOMENTUM_THRESHOLD` (70)
-- **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%)
-- **Step 5**: Return top N candidates (default 3) for AI analysis
-- **Fallback**: Uses static watchlist if ranking API unavailable
+  - **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%)
+- **Overseas (US/JP/HK/CN/VN)**:
+  - **Step 1**: Fetch overseas ranking universe (fluctuation rank + volume rank bonus)
+  - **Step 2**: Compute volatility-first score (max of daily change% and intraday range%)
+  - **Step 3**: Apply liquidity bonus from volume ranking
+  - **Step 4**: Return top N candidates (default 3)
+- **Fallback (overseas only)**: If ranking API is unavailable, uses dynamic universe
+  from runtime active symbols + recent traded symbols + current holdings (no static watchlist)
 - **Realtime mode only**: Daily mode uses batch processing for API efficiency
 
 **Benefits:**
@@ -167,10 +177,10 @@ High-frequency trading with individual stock analysis:
                            ▼
         ┌──────────────────────────────────┐
         │ Smart Scanner (Python-first)      │
-        │ - Fetch volume rankings (KIS)    │
-        │ - Get 20d price history per stock│
-        │ - Calculate RSI(14) + vol ratio  │
-        │ - Filter: vol>2x AND RSI extreme │
+        │ - Domestic: volume rank + RSI    │
+        │ - Overseas: ranking universe     │
+        │   + volatility-first scoring     │
+        │ - Fallback: dynamic universe     │
         │ - Return top 3 qualified stocks  │
         └──────────────────┬────────────────┘
                            │
@@ -307,6 +317,13 @@ RSI_OVERSOLD_THRESHOLD=30    # 0-50, oversold threshold
 RSI_MOMENTUM_THRESHOLD=70    # 50-100, momentum threshold
 VOL_MULTIPLIER=2.0           # Minimum volume ratio (2.0 = 200%)
 SCANNER_TOP_N=3              # Max qualified candidates per scan
+
+# Overseas Ranking API (optional override; account-dependent)
+OVERSEAS_RANKING_ENABLED=true
+OVERSEAS_RANKING_FLUCT_TR_ID=HHDFS76200100
+OVERSEAS_RANKING_VOLUME_TR_ID=HHDFS76200200
+OVERSEAS_RANKING_FLUCT_PATH=/uapi/overseas-price/v1/quotations/inquire-updown-rank
+OVERSEAS_RANKING_VOLUME_PATH=/uapi/overseas-price/v1/quotations/inquire-volume-rank
 ```
 
 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.
diff --git a/docs/requirements-log.md b/docs/requirements-log.md
index 59a0eae..be82053 100644
--- a/docs/requirements-log.md
+++ b/docs/requirements-log.md
@@ -86,3 +86,35 @@
   - Plan Consistency (필수), Safety & Constraints, Quality, Workflow 4개 카테고리
 
 **이슈/PR:** #114
+
+---
+
+## 2026-02-16
+
+### 해외 스캐너 개선: 랭킹 연동 + 변동성 우선 선별
+
+**배경:**
+- `run_overnight` 실운영에서 미국장 동안 거래가 0건 지속
+- 원인: 해외 시장에서도 국내 랭킹/일봉 API 경로를 사용하던 구조적 불일치
+
+**요구사항:**
+1. 해외 시장도 랭킹 API 기반 유니버스 탐색 지원
+2. 단순 상승률/거래대금 상위가 아니라, **변동성이 큰 종목**을 우선 선별
+3. 고정 티커 fallback 금지
+
+**구현 결과:**
+- `src/broker/overseas.py`
+  - `fetch_overseas_rankings()` 추가 (fluctuation / volume)
+  - 해외 랭킹 API 경로/TR_ID를 설정값으로 오버라이드 가능하게 구현
+- `src/analysis/smart_scanner.py`
+  - market-aware 스캔(국내/해외 분리)
+  - 해외: 랭킹 API 유니버스 + 변동성 우선 점수(일변동률 vs 장중 고저폭)
+  - 거래대금/거래량 랭킹은 유동성 보정 점수로 활용
+  - 랭킹 실패 시에는 동적 유니버스(active/recent/holdings)만 사용
+- `src/config.py`
+  - `OVERSEAS_RANKING_*` 설정 추가
+
+**효과:**
+- 해외 시장에서 스캐너 후보 0개로 정지되는 상황 완화
+- 종목 선정 기준이 단순 상승률 중심에서 변동성 중심으로 개선
+- 고정 티커 없이도 시장 주도 변동 종목 탐지 가능