From 8af5f564c392adebb73415e83e7a963308c68a73 Mon Sep 17 00:00:00 2001
From: agentson <agentson@localhost>
Date: Thu, 26 Feb 2026 00:19:55 +0900
Subject: [PATCH] =?UTF-8?q?fix:=20ranking=20API=20=ED=95=84=EC=88=98=20?=
 =?UTF-8?q?=ED=8C=8C=EB=9D=BC=EB=AF=B8=ED=84=B0=20KEYB=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80=20=EB=B0=8F=20GUBN=20=EA=B0=92=20=EC=88=98=EC=A0=95?=
 =?UTF-8?q?=20(#258)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

KIS 공식 문서(20260221) 기준 KEYB(NEXT KEY BUFF)는 Required=Y이나
누락되어 있어 항상 rt_cd=2 오류 발생, fallback 경로로만 실행됨.

- fluctuation/volume 양쪽 params에 KEYB: '' 추가
- GUBN 주석 수정: 0=하락율, 1=상승율 (문서 기준)
- GUBN 값 0→1 수정: 상승율 기준으로 변동성 급등 종목 스캔

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/broker/overseas.py        | 4 +++-
 tests/test_overseas_broker.py | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/broker/overseas.py b/src/broker/overseas.py
index 13f3903..69504a6 100644
--- a/src/broker/overseas.py
+++ b/src/broker/overseas.py
@@ -121,6 +121,7 @@ class OverseasBroker:
             tr_id = self._broker._settings.OVERSEAS_RANKING_VOLUME_TR_ID
             path = self._broker._settings.OVERSEAS_RANKING_VOLUME_PATH
             params: dict[str, str] = {
+                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                 "AUTH": "",
                 "EXCD": ranking_excd,
                 "MIXN": "0",
@@ -130,10 +131,11 @@ class OverseasBroker:
             tr_id = self._broker._settings.OVERSEAS_RANKING_FLUCT_TR_ID
             path = self._broker._settings.OVERSEAS_RANKING_FLUCT_PATH
             params = {
+                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                 "AUTH": "",
                 "EXCD": ranking_excd,
                 "NDAY": "0",
-                "GUBN": "0",  # 0=전체(상승+하락), 1=상승만 — 변동성 스캐너는 전체 필요
+                "GUBN": "1",  # 0=하락율, 1=상승율 — 변동성 스캐너는 급등 종목 우선
                 "VOL_RANG": "0",
             }
 
diff --git a/tests/test_overseas_broker.py b/tests/test_overseas_broker.py
index 3f346f6..0f47bec 100644
--- a/tests/test_overseas_broker.py
+++ b/tests/test_overseas_broker.py
@@ -122,9 +122,10 @@ class TestFetchOverseasRankings:
         params = call_args[1]["params"]
 
         assert "/uapi/overseas-stock/v1/ranking/updown-rate" in url
+        assert params["KEYB"] == ""  # Required by KIS API spec
         assert params["EXCD"] == "NAS"
         assert params["NDAY"] == "0"
-        assert params["GUBN"] == "0"  # 0=전체(상승+하락), 변동성 스캐너에 필요
+        assert params["GUBN"] == "1"  # 1=상승율 — 변동성 스캐너는 급등 종목 우선
         assert params["VOL_RANG"] == "0"
 
         overseas_broker._broker._auth_headers.assert_called_with("HHDFS76290000")
@@ -157,6 +158,7 @@ class TestFetchOverseasRankings:
         params = call_args[1]["params"]
 
         assert "/uapi/overseas-stock/v1/ranking/volume-surge" in url
+        assert params["KEYB"] == ""  # Required by KIS API spec
         assert params["EXCD"] == "NYS"
         assert params["MIXN"] == "0"
         assert params["VOL_RANG"] == "0"