feat: DB WAL 모드 적용, .env.example 정리 (#210, #213, #216)

- #210: init_db()에 WAL 저널 모드 적용 (파일 DB에만, :memory: 제외)
  - 대시보드(READ)와 거래루프(WRITE) 동시 접근 시 SQLite 락 오류 방지
  - busy_timeout=5000ms 설정
- #213: RATE_LIMIT_RPS 기본값 2.0으로 통일 (.env.example이 5.0으로 잘못 표기됨)
- #216: .env.example 중요 변수 추가 및 정리
  - KIS_BASE_URL 모의/실전 URL 주석 명시 (포트 29443 수정 포함)
  - MODE, TRADE_MODE, ENABLED_MARKETS, PAPER_OVERSEAS_CASH 추가
  - GEMINI_MODEL 업데이트 (gemini-pro → gemini-2.0-flash-exp)
  - DASHBOARD 설정 섹션 추가

테스트 2개 추가 (WAL 파일 DB 적용, 메모리 DB 미적용 검증)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -1,36 +1,82 @@
+# ============================================================
+# The Ouroboros — Environment Configuration
+# ============================================================
+# Copy this file to .env and fill in your values.
+# Lines starting with # are comments.
+
+# ============================================================
 # Korea Investment Securities API
+# ============================================================
 KIS_APP_KEY=your_app_key_here
 KIS_APP_SECRET=your_app_secret_here
 KIS_ACCOUNT_NO=12345678-01
-KIS_BASE_URL=https://openapivts.koreainvestment.com:9443
 
+# Paper trading (VTS): https://openapivts.koreainvestment.com:29443
+# Live trading:        https://openapi.koreainvestment.com:9443
+KIS_BASE_URL=https://openapivts.koreainvestment.com:29443
+
+# ============================================================
+# Trading Mode
+# ============================================================
+# paper = 모의투자 (safe for testing), live = 실전투자 (real money)
+MODE=paper
+
+# daily = batch per session, realtime = per-stock continuous scan
+TRADE_MODE=daily
+
+# Comma-separated market codes: KR, US, JP, HK, CN, VN
+ENABLED_MARKETS=KR,US
+
+# Simulated USD cash for paper (VTS) overseas trading.
+# VTS overseas balance API often returns 0; this value is used as fallback.
+# Set to 0 to disable fallback (not used in live mode).
+PAPER_OVERSEAS_CASH=50000.0
+
+# ============================================================
 # Google Gemini
+# ============================================================
 GEMINI_API_KEY=your_gemini_api_key_here
-GEMINI_MODEL=gemini-pro
+# Recommended: gemini-2.0-flash-exp or gemini-1.5-pro
+GEMINI_MODEL=gemini-2.0-flash-exp
 
+# ============================================================
 # Risk Management
+# ============================================================
 CIRCUIT_BREAKER_PCT=-3.0
 FAT_FINGER_PCT=30.0
 CONFIDENCE_THRESHOLD=80
 
+# ============================================================
 # Database
+# ============================================================
 DB_PATH=data/trade_logs.db
 
-# Rate Limiting (requests per second for KIS API)
-# Reduced to 5.0 to avoid "초당 거래건수 초과" errors (EGW00201)
-RATE_LIMIT_RPS=5.0
+# ============================================================
+# Rate Limiting
+# ============================================================
+# KIS API real limit is ~2 RPS. Keep at 2.0 for maximum safety.
+# Increasing this risks EGW00201 "초당 거래건수 초과" errors.
+RATE_LIMIT_RPS=2.0
 
-# Trading Mode (paper / live)
-MODE=paper
-
-# External Data APIs (optional — for enhanced decision-making)
+# ============================================================
+# External Data APIs (optional)
+# ============================================================
 # NEWS_API_KEY=your_news_api_key_here
 # NEWS_API_PROVIDER=alphavantage
 # MARKET_DATA_API_KEY=your_market_data_key_here
 
+# ============================================================
 # Telegram Notifications (optional)
+# ============================================================
 # Get bot token from @BotFather on Telegram
 # Get chat ID from @userinfobot or your chat
 # TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 # TELEGRAM_CHAT_ID=123456789
 # TELEGRAM_ENABLED=true
+
+# ============================================================
+# Dashboard (optional)
+# ============================================================
+# DASHBOARD_ENABLED=false
+# DASHBOARD_HOST=127.0.0.1
+# DASHBOARD_PORT=8080

src/db.py

@@ -14,6 +14,11 @@ def init_db(db_path: str) -> sqlite3.Connection:
     if db_path != ":memory:":
         Path(db_path).parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(db_path)
+    # Enable WAL mode for concurrent read/write (dashboard + trading loop).
+    # WAL does not apply to in-memory databases.
+    if db_path != ":memory:":
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS trades (

src/main.py

@@ -524,6 +524,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",
@@ -1076,6 +1084,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": {

tests/test_db.py

@@ -1,5 +1,8 @@
 """Tests for database helper functions."""
 
+import tempfile
+import os
+
 from src.db import get_open_position, init_db, log_trade
 
 
@@ -58,3 +61,37 @@ def test_get_open_position_returns_none_when_latest_is_sell() -> None:
 def test_get_open_position_returns_none_when_no_trades() -> None:
     conn = init_db(":memory:")
     assert get_open_position(conn, "AAPL", "US_NASDAQ") is None
+
+
+# ---------------------------------------------------------------------------
+# WAL mode tests (issue #210)
+# ---------------------------------------------------------------------------
+
+
+def test_wal_mode_applied_to_file_db() -> None:
+    """File-based DB must use WAL journal mode for dashboard concurrent reads."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+    try:
+        conn = init_db(db_path)
+        cursor = conn.execute("PRAGMA journal_mode")
+        mode = cursor.fetchone()[0]
+        assert mode == "wal", f"Expected WAL mode, got {mode}"
+        conn.close()
+    finally:
+        os.unlink(db_path)
+        # Clean up WAL auxiliary files if they exist
+        for ext in ("-wal", "-shm"):
+            path = db_path + ext
+            if os.path.exists(path):
+                os.unlink(path)
+
+
+def test_wal_mode_not_applied_to_memory_db() -> None:
+    """:memory: DB must not apply WAL (SQLite does not support WAL for in-memory)."""
+    conn = init_db(":memory:")
+    cursor = conn.execute("PRAGMA journal_mode")
+    mode = cursor.fetchone()[0]
+    # In-memory DBs default to 'memory' journal mode
+    assert mode != "wal", "WAL should not be set on in-memory database"
+    conn.close()

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()