feat: add overseas ranking integration with dynamic fallback

src/analysis/smart_scanner.py

@@ -12,7 +12,9 @@ from typing import Any
 
 from src.analysis.volatility import VolatilityAnalyzer
 from src.broker.kis_api import KISBroker
+from src.broker.overseas import OverseasBroker
 from src.config import Settings
+from src.markets.schedule import MarketInfo
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +47,7 @@ class SmartVolatilityScanner:
     def __init__(
         self,
         broker: KISBroker,
+        overseas_broker: OverseasBroker | None,
         volatility_analyzer: VolatilityAnalyzer,
         settings: Settings,
     ) -> None:
@@ -56,6 +59,7 @@ class SmartVolatilityScanner:
             settings: Application settings
         """
         self.broker = broker
+        self.overseas_broker = overseas_broker
         self.analyzer = volatility_analyzer
         self.settings = settings
 
@@ -67,16 +71,28 @@ class SmartVolatilityScanner:
 
     async def scan(
         self,
+        market: MarketInfo | None = None,
         fallback_stocks: list[str] | None = None,
     ) -> list[ScanCandidate]:
         """Execute smart scan and return qualified candidates.
 
         Args:
+            market: Target market info (domestic vs overseas behavior)
             fallback_stocks: Stock codes to use if ranking API fails
 
         Returns:
             List of ScanCandidate, sorted by score, up to top_n items
         """
+        if market and not market.is_domestic:
+            return await self._scan_overseas(market, fallback_stocks)
+
+        return await self._scan_domestic(fallback_stocks)
+
+    async def _scan_domestic(
+        self,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Scan domestic market using ranking API + RSI/volume filters."""
         # Step 1: Fetch rankings
         try:
             rankings = await self.broker.fetch_market_rankings(
@@ -180,6 +196,157 @@ class SmartVolatilityScanner:
         candidates.sort(key=lambda c: c.score, reverse=True)
         return candidates[: self.top_n]
 
+    async def _scan_overseas(
+        self,
+        market: MarketInfo,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Scan overseas symbols using ranking API first, then fallback universe."""
+        if self.overseas_broker is None:
+            logger.warning(
+                "Overseas scanner unavailable for %s: overseas broker not configured",
+                market.name,
+            )
+            return []
+
+        candidates = await self._scan_overseas_from_rankings(market)
+        if not candidates:
+            candidates = await self._scan_overseas_from_symbols(market, fallback_stocks)
+
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        return candidates[: self.top_n]
+
+    async def _scan_overseas_from_rankings(
+        self,
+        market: MarketInfo,
+    ) -> list[ScanCandidate]:
+        """Build overseas candidates from ranking APIs."""
+        assert self.overseas_broker is not None
+        try:
+            fluct_rows = await self.overseas_broker.fetch_overseas_rankings(
+                exchange_code=market.exchange_code,
+                ranking_type="fluctuation",
+                limit=50,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Overseas fluctuation ranking failed for %s: %s", market.code, exc
+            )
+            fluct_rows = []
+
+        if not fluct_rows:
+            return []
+
+        candidates: list[ScanCandidate] = []
+        for row in fluct_rows:
+            stock_code = (
+                str(
+                    row.get("symb")
+                    or row.get("ovrs_pdno")
+                    or row.get("stock_code")
+                    or row.get("pdno")
+                    or ""
+                )
+                .strip()
+                .upper()
+            )
+            if not stock_code:
+                continue
+
+            price = _safe_float(
+                row.get("last")
+                or row.get("ovrs_nmix_prpr")
+                or row.get("stck_prpr")
+            )
+            change_rate = _safe_float(
+                row.get("rate")
+                or row.get("prdy_ctrt")
+                or row.get("evlu_pfls_rt")
+                or row.get("chg_rt")
+            )
+            volume = _safe_float(row.get("tvol") or row.get("acml_vol") or row.get("vol"))
+
+            if price <= 0 or abs(change_rate) < 0.8:
+                continue
+
+            score = min(abs(change_rate) / 8.0, 1.0) * 100.0
+            signal = "momentum" if change_rate >= 0 else "oversold"
+            implied_rsi = max(0.0, min(100.0, 50.0 + (change_rate * 4.0)))
+            candidates.append(
+                ScanCandidate(
+                    stock_code=stock_code,
+                    name=str(row.get("name") or row.get("ovrs_item_name") or stock_code),
+                    price=price,
+                    volume=volume,
+                    volume_ratio=max(1.0, abs(change_rate) / 2.0),
+                    rsi=implied_rsi,
+                    signal=signal,
+                    score=score,
+                )
+            )
+
+        if candidates:
+            logger.info(
+                "Overseas ranking scan found %d candidates for %s",
+                len(candidates),
+                market.name,
+            )
+        return candidates
+
+    async def _scan_overseas_from_symbols(
+        self,
+        market: MarketInfo,
+        symbols: list[str] | None,
+    ) -> list[ScanCandidate]:
+        """Fallback overseas scan from dynamic symbol universe."""
+        assert self.overseas_broker is not None
+        if not symbols:
+            logger.info("Overseas scanner: no symbol universe for %s", market.name)
+            return []
+
+        candidates: list[ScanCandidate] = []
+        for stock_code in symbols:
+            try:
+                price_data = await self.overseas_broker.get_overseas_price(
+                    market.exchange_code, stock_code
+                )
+                output = price_data.get("output", {})
+                price = _safe_float(
+                    output.get("last")
+                    or output.get("ovrs_nmix_prpr")
+                    or output.get("stck_prpr")
+                )
+                change_rate = _safe_float(
+                    output.get("rate")
+                    or output.get("prdy_ctrt")
+                    or output.get("evlu_pfls_rt")
+                )
+                volume = _safe_float(output.get("tvol") or output.get("acml_vol"))
+
+                if price <= 0 or abs(change_rate) < 0.8:
+                    continue
+
+                score = min(abs(change_rate) / 8.0, 1.0) * 100.0
+                signal = "momentum" if change_rate >= 0 else "oversold"
+                implied_rsi = max(0.0, min(100.0, 50.0 + (change_rate * 4.0)))
+                candidates.append(
+                    ScanCandidate(
+                        stock_code=stock_code,
+                        name=stock_code,
+                        price=price,
+                        volume=volume,
+                        volume_ratio=max(1.0, abs(change_rate) / 2.0),
+                        rsi=implied_rsi,
+                        signal=signal,
+                        score=score,
+                    )
+                )
+            except ConnectionError as exc:
+                logger.warning("Failed to analyze overseas %s: %s", stock_code, exc)
+            except Exception as exc:
+                logger.error("Unexpected error analyzing overseas %s: %s", stock_code, exc)
+        return candidates
+
     def get_stock_codes(self, candidates: list[ScanCandidate]) -> list[str]:
         """Extract stock codes from candidates for watchlist update.
 
@@ -190,3 +357,13 @@ class SmartVolatilityScanner:
             List of stock codes
         """
         return [c.stock_code for c in candidates]
+
+
+def _safe_float(value: Any, default: float = 0.0) -> float:
+    """Convert arbitrary values to float safely."""
+    if value in (None, ""):
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default