Merge pull request 'feat: 실전 투자 전환 — TR_ID 분기, URL, 신뢰도 임계값, 텔레그램 알림 (#201~#205, #208, #214)' (#219) from feature/issue-201-202-203-broker-live-mode into main

Reviewed-on: #219

src/broker/kis_api.py

@@ -285,7 +285,10 @@ class KISBroker:
         await self._rate_limiter.acquire()
         session = self._get_session()
 
-        headers = await self._auth_headers("VTTC8434R")  # 모의투자 잔고조회
+        # TR_ID: 실전 TTTC8434R, 모의 VTTC8434R
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '국내주식 잔고조회' 시트
+        tr_id = "TTTC8434R" if self._settings.MODE == "live" else "VTTC8434R"
+        headers = await self._auth_headers(tr_id)
         params = {
             "CANO": self._account_no,
             "ACNT_PRDT_CD": self._product_cd,
@@ -330,7 +333,13 @@ class KISBroker:
         await self._rate_limiter.acquire()
         session = self._get_session()
 
-        tr_id = "VTTC0802U" if order_type == "BUY" else "VTTC0801U"
+        # TR_ID: 실전 BUY=TTTC0012U SELL=TTTC0011U, 모의 BUY=VTTC0012U SELL=VTTC0011U
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '주식주문(현금)' 시트
+        # ※ TTTC0802U/VTTC0802U는 미수매수(증거금40% 계좌 전용) — 현금주문에 사용 금지
+        if self._settings.MODE == "live":
+            tr_id = "TTTC0012U" if order_type == "BUY" else "TTTC0011U"
+        else:
+            tr_id = "VTTC0012U" if order_type == "BUY" else "VTTC0011U"
 
         # KRX requires limit orders to be rounded down to the tick unit.
         # ORD_DVSN: "00"=지정가, "01"=시장가

src/broker/overseas.py

@@ -175,8 +175,12 @@ class OverseasBroker:
         await self._broker._rate_limiter.acquire()
         session = self._broker._get_session()
 
-        # Virtual trading TR_ID for overseas balance inquiry
-        headers = await self._broker._auth_headers("VTTS3012R")
+        # TR_ID: 실전 TTTS3012R, 모의 VTTS3012R
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 잔고조회' 시트
+        balance_tr_id = (
+            "TTTS3012R" if self._broker._settings.MODE == "live" else "VTTS3012R"
+        )
+        headers = await self._broker._auth_headers(balance_tr_id)
         params = {
             "CANO": self._broker._account_no,
             "ACNT_PRDT_CD": self._broker._product_cd,
@@ -229,10 +233,12 @@ class OverseasBroker:
         await self._broker._rate_limiter.acquire()
         session = self._broker._get_session()
 
-        # Virtual trading TR_IDs for overseas orders
+        # TR_ID: 실전 BUY=TTTT1002U SELL=TTTT1006U, 모의 BUY=VTTT1002U SELL=VTTT1001U
         # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 주문' 시트
-        # VTTT1002U: 모의투자 미국 매수, VTTT1001U: 모의투자 미국 매도
-        tr_id = "VTTT1002U" if order_type == "BUY" else "VTTT1001U"
+        if self._broker._settings.MODE == "live":
+            tr_id = "TTTT1002U" if order_type == "BUY" else "TTTT1006U"
+        else:
+            tr_id = "VTTT1002U" if order_type == "BUY" else "VTTT1001U"
 
         body = {
             "CANO": self._broker._account_no,

src/config.py

@@ -13,7 +13,7 @@ class Settings(BaseSettings):
     KIS_APP_KEY: str
     KIS_APP_SECRET: str
     KIS_ACCOUNT_NO: str  # format: "XXXXXXXX-XX"
-    KIS_BASE_URL: str = "https://openapivts.koreainvestment.com:9443"
+    KIS_BASE_URL: str = "https://openapivts.koreainvestment.com:29443"
 
     # Google Gemini
     GEMINI_API_KEY: str

src/dashboard/static/index.html

@@ -172,6 +172,51 @@
       /* Spinner */
       .spinner { display: inline-block; width: 12px; height: 12px; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: spin 0.8s linear infinite; }
       @keyframes spin { to { transform: rotate(360deg); } }
+
+      /* Generic panel */
+      .panel {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 10px;
+        padding: 16px;
+        margin-top: 20px;
+      }
+
+      /* Playbook panel - details/summary accordion */
+      .playbook-panel details { border: 1px solid var(--border); border-radius: 4px; margin-bottom: 6px; }
+      .playbook-panel summary { padding: 8px 12px; cursor: pointer; font-weight: 600; background: var(--bg); color: var(--fg); }
+      .playbook-panel summary:hover { color: var(--accent); }
+      .playbook-panel pre { margin: 0; padding: 12px; background: var(--bg); overflow-x: auto;
+                            font-size: 11px; color: #a0c4ff; white-space: pre-wrap; }
+
+      /* Scorecard KPI card grid */
+      .scorecard-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 10px; }
+      .kpi-card { background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 12px; text-align: center; }
+      .kpi-card .kpi-label { font-size: 11px; color: var(--muted); margin-bottom: 4px; }
+      .kpi-card .kpi-value { font-size: 20px; font-weight: 700; color: var(--fg); }
+
+      /* Scenarios table */
+      .scenarios-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+      .scenarios-table th { background: var(--bg); padding: 8px; text-align: left; border-bottom: 1px solid var(--border);
+                            color: var(--muted); font-size: 11px; font-weight: 600; white-space: nowrap; }
+      .scenarios-table td { padding: 7px 8px; border-bottom: 1px solid rgba(40,69,95,0.5); }
+      .scenarios-table tr:hover td { background: rgba(255,255,255,0.02); }
+
+      /* Context table */
+      .context-table { width: 100%; border-collapse: collapse; font-size: 12px; }
+      .context-table th { background: var(--bg); padding: 8px; text-align: left; border-bottom: 1px solid var(--border);
+                          color: var(--muted); font-size: 11px; font-weight: 600; white-space: nowrap; }
+      .context-table td { padding: 6px 8px; border-bottom: 1px solid rgba(40,69,95,0.5); vertical-align: top; }
+      .context-value { max-height: 60px; overflow-y: auto; color: #a0c4ff; word-break: break-all; }
+
+      /* Common panel select controls */
+      .panel-controls { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+      .panel-controls select, .panel-controls input[type="number"] {
+        background: var(--bg); color: var(--fg); border: 1px solid var(--border);
+        border-radius: 4px; padding: 4px 8px; font-size: 13px; font-family: inherit;
+      }
+      .panel-date { color: var(--muted); font-size: 12px; }
+      .empty-msg { color: var(--muted); text-align: center; padding: 20px 0; font-size: 12px; }
     </style>
   </head>
   <body>
@@ -283,6 +328,72 @@
           </tbody>
         </table>
       </div>
+
+      <!-- playbook panel -->
+      <div class="panel playbook-panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F4CB; 프리마켓 플레이북</span>
+          <div class="panel-controls">
+            <select id="pb-market-select" onchange="fetchPlaybook()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+              <option value="US_NYSE">US_NYSE</option>
+            </select>
+            <span id="pb-date" class="panel-date"></span>
+          </div>
+        </div>
+        <div id="playbook-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- scorecard panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F4CA; 일간 스코어카드</span>
+          <div class="panel-controls">
+            <select id="sc-market-select" onchange="fetchScorecard()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+            </select>
+            <span id="sc-date" class="panel-date"></span>
+          </div>
+        </div>
+        <div id="scorecard-grid" class="scorecard-grid"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- scenarios panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F3AF; 활성 시나리오 매칭</span>
+          <div class="panel-controls">
+            <select id="scen-market-select" onchange="fetchScenarios()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+            </select>
+          </div>
+        </div>
+        <div id="scenarios-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- context layer panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F9E0; 컨텍스트 트리</span>
+          <div class="panel-controls">
+            <select id="ctx-layer-select" onchange="fetchContext()">
+              <option value="L7_REALTIME">L7_REALTIME</option>
+              <option value="L6_DAILY">L6_DAILY</option>
+              <option value="L5_WEEKLY">L5_WEEKLY</option>
+              <option value="L4_MONTHLY">L4_MONTHLY</option>
+              <option value="L3_QUARTERLY">L3_QUARTERLY</option>
+              <option value="L2_YEARLY">L2_YEARLY</option>
+              <option value="L1_LIFETIME">L1_LIFETIME</option>
+            </select>
+            <input id="ctx-limit" type="number" value="20" min="1" max="200"
+                   style="width:60px;" onchange="fetchContext()">
+          </div>
+        </div>
+        <div id="context-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
     </div>
 
     <script>
@@ -521,6 +632,117 @@
         fetchDecisions(currentMarket);
       }
 
+      function todayStr() {
+        return new Date().toISOString().slice(0, 10);
+      }
+
+      function esc(s) {
+        return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+      }
+
+      async function fetchJSON(url) {
+        const r = await fetch(url);
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        return r.json();
+      }
+
+      async function fetchPlaybook() {
+        const market = document.getElementById('pb-market-select').value;
+        const date = todayStr();
+        document.getElementById('pb-date').textContent = date;
+        const el = document.getElementById('playbook-content');
+        try {
+          const data = await fetchJSON(`/api/playbook/${date}?market=${market}`);
+          const stocks = data.stock_playbooks ?? [];
+          if (stocks.length === 0) {
+            el.innerHTML = '<p class="empty-msg">오늘 플레이북 없음</p>';
+            return;
+          }
+          el.innerHTML = stocks.map(sp =>
+            `<details><summary>${esc(sp.stock_code ?? '?')} — ${esc(sp.signal ?? '')}</summary>` +
+            `<pre>${esc(JSON.stringify(sp, null, 2))}</pre></details>`
+          ).join('');
+        } catch {
+          el.innerHTML = '<p class="empty-msg">플레이북 없음 (오늘 미생성 또는 API 오류)</p>';
+        }
+      }
+
+      async function fetchScorecard() {
+        const market = document.getElementById('sc-market-select').value;
+        const date = todayStr();
+        document.getElementById('sc-date').textContent = date;
+        const el = document.getElementById('scorecard-grid');
+        try {
+          const data = await fetchJSON(`/api/scorecard/${date}?market=${market}`);
+          const sc = data.scorecard ?? {};
+          const entries = Object.entries(sc);
+          if (entries.length === 0) {
+            el.innerHTML = '<p class="empty-msg">스코어카드 없음</p>';
+            return;
+          }
+          el.className = 'scorecard-grid';
+          el.innerHTML = entries.map(([k, v]) => `
+            <div class="kpi-card">
+              <div class="kpi-label">${esc(k)}</div>
+              <div class="kpi-value">${typeof v === 'number' ? v.toFixed(2) : esc(String(v))}</div>
+            </div>`).join('');
+        } catch {
+          el.innerHTML = '<p class="empty-msg">스코어카드 없음 (오늘 미생성 또는 API 오류)</p>';
+        }
+      }
+
+      async function fetchScenarios() {
+        const market = document.getElementById('scen-market-select').value;
+        const date = todayStr();
+        const el = document.getElementById('scenarios-content');
+        try {
+          const data = await fetchJSON(`/api/scenarios/active?market=${market}&date_str=${date}&limit=50`);
+          const matches = data.matches ?? [];
+          if (matches.length === 0) {
+            el.innerHTML = '<p class="empty-msg">활성 시나리오 없음</p>';
+            return;
+          }
+          el.innerHTML = `<table class="scenarios-table">
+            <thead><tr><th>종목</th><th>신호</th><th>신뢰도</th><th>매칭 조건</th></tr></thead>
+            <tbody>${matches.map(m => `
+              <tr>
+                <td>${esc(m.stock_code)}</td>
+                <td>${esc(m.signal ?? '-')}</td>
+                <td>${esc(m.confidence ?? '-')}</td>
+                <td><code style="font-size:11px">${esc(JSON.stringify(m.scenario_match ?? {}))}</code></td>
+              </tr>`).join('')}
+            </tbody></table>`;
+        } catch {
+          el.innerHTML = '<p class="empty-msg">데이터 없음</p>';
+        }
+      }
+
+      async function fetchContext() {
+        const layer = document.getElementById('ctx-layer-select').value;
+        const limit = Math.min(Math.max(parseInt(document.getElementById('ctx-limit').value, 10) || 20, 1), 200);
+        const el = document.getElementById('context-content');
+        try {
+          const data = await fetchJSON(`/api/context/${layer}?limit=${limit}`);
+          const entries = data.entries ?? [];
+          if (entries.length === 0) {
+            el.innerHTML = '<p class="empty-msg">컨텍스트 없음</p>';
+            return;
+          }
+          el.innerHTML = `<table class="context-table">
+            <thead><tr><th>timeframe</th><th>key</th><th>value</th><th>updated</th></tr></thead>
+            <tbody>${entries.map(e => `
+              <tr>
+                <td>${esc(e.timeframe)}</td>
+                <td>${esc(e.key)}</td>
+                <td><div class="context-value">${esc(JSON.stringify(e.value ?? e.raw_value))}</div></td>
+                <td style="font-size:11px;color:var(--muted)">${esc((e.updated_at ?? '').slice(0, 16))}</td>
+              </tr>`).join('')}
+            </tbody></table>`;
+        } catch {
+          el.innerHTML = '<p class="empty-msg">데이터 없음</p>';
+        }
+      }
+
       async function refreshAll() {
         document.getElementById('last-updated').textContent = '업데이트 중...';
         await Promise.all([
@@ -529,6 +751,10 @@
           fetchPositions(),
           fetchPnlHistory(currentDays),
           fetchDecisions(currentMarket),
+          fetchPlaybook(),
+          fetchScorecard(),
+          fetchScenarios(),
+          fetchContext(),
         ]);
         const now = new Date();
         const timeStr = now.toLocaleTimeString('ko-KR', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false });

src/main.py

@@ -340,7 +340,13 @@ async def trading_cycle(
         purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
 
         # Paper mode fallback: VTS overseas balance API often fails for many accounts.
-        if total_cash <= 0 and settings and settings.PAPER_OVERSEAS_CASH > 0:
+        # Only activate in paper mode — live mode must use real balance from KIS.
+        if (
+            total_cash <= 0
+            and settings
+            and settings.MODE == "paper"
+            and settings.PAPER_OVERSEAS_CASH > 0
+        ):
             logger.debug(
                 "Overseas cash balance is 0 for %s; using paper fallback %.2f USD",
                 market.exchange_code,
@@ -524,6 +530,14 @@ async def trading_cycle(
     # BUY 결정 전 기존 포지션 체크 (중복 매수 방지)
     if decision.action == "BUY":
         existing_position = get_open_position(db_conn, stock_code, market.code)
+        if not existing_position and not market.is_domestic:
+            # SELL 지정가 접수 후 미체결 시 DB는 종료로 기록되나 브로커는 여전히 보유 중.
+            # 이중 매수 방지를 위해 라이브 브로커 잔고를 authoritative source로 사용.
+            broker_qty = _extract_held_qty_from_balance(
+                balance_data, stock_code, is_domestic=False
+            )
+            if broker_qty > 0:
+                existing_position = {"price": 0.0, "quantity": broker_qty}
         if existing_position:
             decision = TradeDecision(
                 action="HOLD",
@@ -1033,11 +1047,12 @@ async def run_daily_session(
                 balance_info.get("frcr_buy_amt_smtl", "0") or "0"
             )
             # Paper mode fallback: VTS overseas balance API often fails for many accounts.
-            if total_cash <= 0 and settings.PAPER_OVERSEAS_CASH > 0:
-                total_cash = settings.PAPER_OVERSEAS_CASH
-
-            # VTS overseas balance API often returns 0; use paper fallback.
-            if total_cash <= 0 and settings.PAPER_OVERSEAS_CASH > 0:
+            # Only activate in paper mode — live mode must use real balance from KIS.
+            if (
+                total_cash <= 0
+                and settings.MODE == "paper"
+                and settings.PAPER_OVERSEAS_CASH > 0
+            ):
                 total_cash = settings.PAPER_OVERSEAS_CASH
 
         # Calculate daily P&L %
@@ -1076,6 +1091,33 @@ async def run_daily_session(
                 decision.confidence,
             )
 
+            # BUY 중복 방지: 브로커 잔고 기반 (미체결 SELL 리밋 주문 보호)
+            if decision.action == "BUY":
+                daily_existing = get_open_position(db_conn, stock_code, market.code)
+                if not daily_existing and not market.is_domestic:
+                    # SELL 지정가 접수 후 미체결 시 DB는 종료로 기록되나 브로커는 여전히 보유 중.
+                    # 이중 매수 방지를 위해 라이브 브로커 잔고를 authoritative source로 사용.
+                    broker_qty = _extract_held_qty_from_balance(
+                        balance_data, stock_code, is_domestic=False
+                    )
+                    if broker_qty > 0:
+                        daily_existing = {"price": 0.0, "quantity": broker_qty}
+                if daily_existing:
+                    decision = TradeDecision(
+                        action="HOLD",
+                        confidence=decision.confidence,
+                        rationale=(
+                            f"Already holding {stock_code} "
+                            f"(entry={daily_existing['price']:.4f}, "
+                            f"qty={daily_existing['quantity']})"
+                        ),
+                    )
+                    logger.info(
+                        "BUY suppressed for %s (%s): already holding open position",
+                        stock_code,
+                        market.name,
+                    )
+
             # Log decision
             context_snapshot = {
                 "L1": {
@@ -1944,6 +1986,10 @@ async def run(settings: Settings) -> None:
                     )
                 except CircuitBreakerTripped:
                     logger.critical("Circuit breaker tripped — shutting down")
+                    await telegram.notify_circuit_breaker(
+                        pnl_pct=settings.CIRCUIT_BREAKER_PCT,
+                        threshold=settings.CIRCUIT_BREAKER_PCT,
+                    )
                     shutdown.set()
                     break
                 except Exception as exc:
@@ -2261,6 +2307,8 @@ async def run(settings: Settings) -> None:
                 except TimeoutError:
                     pass  # Normal — timeout means it's time for next cycle
     finally:
+        # Notify shutdown before closing resources
+        await telegram.notify_system_shutdown("Normal shutdown")
         # Clean up resources
         await command_handler.stop_polling()
         await broker.close()

tests/test_broker.py

@@ -572,4 +572,156 @@ class TestSendOrderTickRounding:
         order_call = mock_post.call_args_list[1]
         body = order_call[1].get("json", {})
         assert body["ORD_DVSN"] == "01"
-        assert body["ORD_UNPR"] == "0"
+
+
+# ---------------------------------------------------------------------------
+# TR_ID live/paper branching (issues #201, #202, #203)
+# ---------------------------------------------------------------------------
+
+
+class TestTRIDBranchingDomestic:
+    """get_balance and send_order must use correct TR_ID for live vs paper mode."""
+
+    def _make_broker(self, settings, mode: str) -> KISBroker:
+        from src.config import Settings
+
+        s = Settings(
+            KIS_APP_KEY=settings.KIS_APP_KEY,
+            KIS_APP_SECRET=settings.KIS_APP_SECRET,
+            KIS_ACCOUNT_NO=settings.KIS_ACCOUNT_NO,
+            GEMINI_API_KEY=settings.GEMINI_API_KEY,
+            DB_PATH=":memory:",
+            ENABLED_MARKETS="KR",
+            MODE=mode,
+        )
+        b = KISBroker(s)
+        b._access_token = "tok"
+        b._token_expires_at = float("inf")
+        b._rate_limiter.acquire = AsyncMock()
+        return b
+
+    @pytest.mark.asyncio
+    async def test_get_balance_paper_uses_vttc8434r(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(
+            return_value={"output1": [], "output2": {}}
+        )
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp) as mock_get:
+            await broker.get_balance()
+
+        headers = mock_get.call_args[1].get("headers", {})
+        assert headers["tr_id"] == "VTTC8434R"
+
+    @pytest.mark.asyncio
+    async def test_get_balance_live_uses_tttc8434r(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(
+            return_value={"output1": [], "output2": {}}
+        )
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp) as mock_get:
+            await broker.get_balance()
+
+        headers = mock_get.call_args[1].get("headers", {})
+        assert headers["tr_id"] == "TTTC8434R"
+
+    @pytest.mark.asyncio
+    async def test_send_order_buy_paper_uses_vttc0012u(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
+        ) as mock_post:
+            await broker.send_order("005930", "BUY", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "VTTC0012U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_buy_live_uses_tttc0012u(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
+        ) as mock_post:
+            await broker.send_order("005930", "BUY", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "TTTC0012U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_sell_paper_uses_vttc0011u(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
+        ) as mock_post:
+            await broker.send_order("005930", "SELL", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "VTTC0011U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_sell_live_uses_tttc0011u(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
+        ) as mock_post:
+            await broker.send_order("005930", "SELL", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "TTTC0011U"

tests/test_main.py

@@ -3001,3 +3001,185 @@ async def test_buy_proceeds_when_no_open_position() -> None:
 
     # 포지션이 없으므로 해외 주문이 실행되어야 함
     overseas_broker.send_overseas_order.assert_called_once()
+
+
+class TestOverseasBrokerIntegration:
+    """Test overseas broker live-balance gating for double-buy prevention.
+
+    Issue #195: KIS VTS SELL limit orders are accepted (rt_cd=0) immediately
+    but may not fill until the market price reaches the limit. During this window,
+    the DB records the position as closed, causing the next cycle to BUY again.
+    These tests verify that live broker balance is used as the authoritative source.
+    """
+
+    @pytest.mark.asyncio
+    async def test_overseas_buy_suppressed_by_broker_balance_when_db_shows_closed(
+        self,
+    ) -> None:
+        """BUY must be suppressed when broker still holds shares even if DB says closed.
+
+        Scenario: SELL limit order was accepted (DB shows closed), but hasn't
+        filled yet — broker balance still shows 10 AAPL shares.
+        Expected: send_overseas_order is NOT called.
+        """
+        db_conn = init_db(":memory:")
+        # DB: BUY then SELL recorded → get_open_position returns None (closed)
+        log_trade(
+            conn=db_conn,
+            stock_code="AAPL",
+            action="BUY",
+            confidence=90,
+            rationale="entry",
+            quantity=10,
+            price=180.0,
+            market="US_NASDAQ",
+            exchange_code="NASD",
+        )
+        log_trade(
+            conn=db_conn,
+            stock_code="AAPL",
+            action="SELL",
+            confidence=90,
+            rationale="sell order accepted",
+            quantity=10,
+            price=182.0,
+            market="US_NASDAQ",
+            exchange_code="NASD",
+        )
+
+        overseas_broker = MagicMock()
+        overseas_broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "182.50"}}
+        )
+        # 브로커: 여전히 AAPL 10주 보유 중 (SELL 미체결)
+        overseas_broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}],
+                "output2": [
+                    {
+                        "frcr_dncl_amt_2": "50000.00",
+                        "frcr_evlu_tota": "60000.00",
+                        "frcr_buy_amt_smtl": "50000.00",
+                    }
+                ],
+            }
+        )
+        overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
+
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match("AAPL"))
+
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        telegram = MagicMock()
+        telegram.notify_trade_execution = AsyncMock()
+        telegram.notify_fat_finger = AsyncMock()
+        telegram.notify_circuit_breaker = AsyncMock()
+        telegram.notify_scenario_matched = AsyncMock()
+
+        decision_logger = MagicMock()
+        decision_logger.log_decision = MagicMock(return_value="decision-id")
+
+        await trading_cycle(
+            broker=MagicMock(),
+            overseas_broker=overseas_broker,
+            scenario_engine=engine,
+            playbook=_make_playbook(market="US"),
+            risk=MagicMock(),
+            db_conn=db_conn,
+            decision_logger=decision_logger,
+            context_store=MagicMock(
+                get_latest_timeframe=MagicMock(return_value=None),
+                set_context=MagicMock(),
+            ),
+            criticality_assessor=MagicMock(
+                assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+                get_timeout=MagicMock(return_value=5.0),
+            ),
+            telegram=telegram,
+            market=market,
+            stock_code="AAPL",
+            scan_candidates={},
+        )
+
+        # 브로커 잔고에 보유 중이므로 BUY 주문이 억제되어야 함 (이중 매수 방지)
+        overseas_broker.send_overseas_order.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_overseas_buy_proceeds_when_broker_shows_no_holding(
+        self,
+    ) -> None:
+        """BUY must proceed when both DB and broker confirm no existing holding.
+
+        Scenario: No prior trades in DB and broker balance shows no AAPL.
+        Expected: send_overseas_order IS called (normal buy flow).
+        """
+        db_conn = init_db(":memory:")
+        # DB: 레코드 없음 (신규 포지션)
+
+        overseas_broker = MagicMock()
+        overseas_broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "182.50"}}
+        )
+        # 브로커: AAPL 미보유
+        overseas_broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output1": [],
+                "output2": [
+                    {
+                        "frcr_dncl_amt_2": "50000.00",
+                        "frcr_evlu_tota": "50000.00",
+                        "frcr_buy_amt_smtl": "0.00",
+                    }
+                ],
+            }
+        )
+        overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
+
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match("AAPL"))
+
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        telegram = MagicMock()
+        telegram.notify_trade_execution = AsyncMock()
+        telegram.notify_fat_finger = AsyncMock()
+        telegram.notify_circuit_breaker = AsyncMock()
+        telegram.notify_scenario_matched = AsyncMock()
+
+        decision_logger = MagicMock()
+        decision_logger.log_decision = MagicMock(return_value="decision-id")
+
+        with patch("src.main.log_trade"):
+            await trading_cycle(
+                broker=MagicMock(),
+                overseas_broker=overseas_broker,
+                scenario_engine=engine,
+                playbook=_make_playbook(market="US"),
+                risk=MagicMock(),
+                db_conn=db_conn,
+                decision_logger=decision_logger,
+                context_store=MagicMock(
+                    get_latest_timeframe=MagicMock(return_value=None),
+                    set_context=MagicMock(),
+                ),
+                criticality_assessor=MagicMock(
+                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+                    get_timeout=MagicMock(return_value=5.0),
+                ),
+                telegram=telegram,
+                market=market,
+                stock_code="AAPL",
+                scan_candidates={},
+            )
+
+        # DB도 브로커도 보유 없음 → BUY 주문이 실행되어야 함 (회귀 테스트)
+        overseas_broker.send_overseas_order.assert_called_once()

tests/test_overseas_broker.py

@@ -640,4 +640,176 @@ class TestPaperOverseasCash:
             GEMINI_API_KEY="g",
         )
         assert settings.PAPER_OVERSEAS_CASH == 0.0
-        del os.environ["PAPER_OVERSEAS_CASH"]
+
+
+# ---------------------------------------------------------------------------
+# TR_ID live/paper branching — overseas (issues #201, #203)
+# ---------------------------------------------------------------------------
+
+
+def _make_overseas_broker_with_mode(mode: str) -> OverseasBroker:
+    s = Settings(
+        KIS_APP_KEY="k",
+        KIS_APP_SECRET="s",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="g",
+        DB_PATH=":memory:",
+        MODE=mode,
+    )
+    kis = KISBroker(s)
+    kis._access_token = "tok"
+    kis._token_expires_at = float("inf")
+    kis._rate_limiter.acquire = AsyncMock()
+    return OverseasBroker(kis)
+
+
+class TestOverseasTRIDBranching:
+    """get_overseas_balance and send_overseas_order must use correct TR_ID."""
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_balance_paper_uses_vtts3012r(self) -> None:
+        broker = _make_overseas_broker_with_mode("paper")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output1": [], "output2": []})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.get_overseas_balance("NASD")
+        assert "VTTS3012R" in captured
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_balance_live_uses_ttts3012r(self) -> None:
+        broker = _make_overseas_broker_with_mode("live")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output1": [], "output2": []})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.get_overseas_balance("NASD")
+        assert "TTTS3012R" in captured
+
+    @pytest.mark.asyncio
+    async def test_send_overseas_order_buy_paper_uses_vttt1002u(self) -> None:
+        broker = _make_overseas_broker_with_mode("paper")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+        broker._broker._get_hash_key = AsyncMock(return_value="h")  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0", "msg1": "OK"})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.send_overseas_order("NASD", "AAPL", "BUY", 1)
+        assert "VTTT1002U" in captured
+
+    @pytest.mark.asyncio
+    async def test_send_overseas_order_buy_live_uses_tttt1002u(self) -> None:
+        broker = _make_overseas_broker_with_mode("live")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+        broker._broker._get_hash_key = AsyncMock(return_value="h")  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0", "msg1": "OK"})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.send_overseas_order("NASD", "AAPL", "BUY", 1)
+        assert "TTTT1002U" in captured
+
+    @pytest.mark.asyncio
+    async def test_send_overseas_order_sell_paper_uses_vttt1001u(self) -> None:
+        broker = _make_overseas_broker_with_mode("paper")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+        broker._broker._get_hash_key = AsyncMock(return_value="h")  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0", "msg1": "OK"})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.send_overseas_order("NASD", "AAPL", "SELL", 1)
+        assert "VTTT1001U" in captured
+
+    @pytest.mark.asyncio
+    async def test_send_overseas_order_sell_live_uses_tttt1006u(self) -> None:
+        broker = _make_overseas_broker_with_mode("live")
+        captured: list[str] = []
+
+        async def mock_auth_headers(tr_id: str) -> dict:
+            captured.append(tr_id)
+            return {"tr_id": tr_id, "authorization": "Bearer tok"}
+
+        broker._broker._auth_headers = mock_auth_headers  # type: ignore[method-assign]
+        broker._broker._get_hash_key = AsyncMock(return_value="h")  # type: ignore[method-assign]
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0", "msg1": "OK"})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=mock_resp)
+        broker._broker._get_session = MagicMock(return_value=mock_session)
+
+        await broker.send_overseas_order("NASD", "AAPL", "SELL", 1)
+        assert "TTTT1006U" in captured