fix: GEMINI_MODEL 기본값 'gemini-pro' → 'gemini-2.0-flash' (issue #217)

'gemini-pro'는 deprecated 모델로 API 오류 발생 가능.
.env.example은 이미 gemini-2.0-flash-exp로 설정되어 있음.

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

CLAUDE.md

@@ -170,7 +170,7 @@ Markets auto-detected based on timezone and enabled in `ENABLED_MARKETS` env var
 - `src/core/risk_manager.py` is **READ-ONLY** — changes require human approval
 - Circuit breaker at -3.0% P&L — may only be made **stricter**
 - Fat-finger protection: max 30% of cash per order — always enforced
-- Confidence < 80 → force HOLD — cannot be weakened
+- Confidence 임계값 (market_outlook별, 낮출 수 없음): BEARISH ≥ 90, NEUTRAL/기본 ≥ 80, BULLISH ≥ 75
 - All code changes → corresponding tests → coverage ≥ 80%
 
 ## Contributing

src/config.py

@@ -17,7 +17,7 @@ class Settings(BaseSettings):
 
     # Google Gemini
     GEMINI_API_KEY: str
-    GEMINI_MODEL: str = "gemini-pro"
+    GEMINI_MODEL: str = "gemini-2.0-flash"
 
     # External Data APIs (optional — for data-driven decisions)
     NEWS_API_KEY: str | None = None

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 (
@@ -28,12 +33,13 @@ def init_db(db_path: str) -> sqlite3.Connection:
             pnl REAL DEFAULT 0.0,
             market TEXT DEFAULT 'KR',
             exchange_code TEXT DEFAULT 'KRX',
-            decision_id TEXT
+            decision_id TEXT,
+            mode TEXT DEFAULT 'paper'
         )
         """
     )
 
-    # Migration: Add market and exchange_code columns if they don't exist
+    # Migration: Add columns if they don't exist (backward-compatible schema upgrades)
     cursor = conn.execute("PRAGMA table_info(trades)")
     columns = {row[1] for row in cursor.fetchall()}
 
@@ -45,6 +51,8 @@ def init_db(db_path: str) -> sqlite3.Connection:
         conn.execute("ALTER TABLE trades ADD COLUMN selection_context TEXT")
     if "decision_id" not in columns:
         conn.execute("ALTER TABLE trades ADD COLUMN decision_id TEXT")
+    if "mode" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN mode TEXT DEFAULT 'paper'")
 
     # Context tree tables for multi-layered memory management
     conn.execute(
@@ -167,6 +175,7 @@ def log_trade(
     exchange_code: str = "KRX",
     selection_context: dict[str, any] | None = None,
     decision_id: str | None = None,
+    mode: str = "paper",
 ) -> None:
     """Insert a trade record into the database.
 
@@ -182,6 +191,8 @@ def log_trade(
         market: Market code
         exchange_code: Exchange code
         selection_context: Scanner selection data (RSI, volume_ratio, signal, score)
+        decision_id: Unique decision identifier for audit linking
+        mode: Trading mode ('paper' or 'live') for data separation
     """
     # Serialize selection context to JSON
     context_json = json.dumps(selection_context) if selection_context else None
@@ -190,9 +201,10 @@ def log_trade(
         """
         INSERT INTO trades (
             timestamp, stock_code, action, confidence, rationale,
-            quantity, price, pnl, market, exchange_code, selection_context, decision_id
+            quantity, price, pnl, market, exchange_code, selection_context, decision_id,
+            mode
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             datetime.now(UTC).isoformat(),
@@ -207,6 +219,7 @@ def log_trade(
             exchange_code,
             context_json,
             decision_id,
+            mode,
         ),
     )
     conn.commit()

src/main.py

@@ -828,6 +828,7 @@ async def trading_cycle(
         exchange_code=market.exchange_code,
         selection_context=selection_context,
         decision_id=decision_id,
+        mode=settings.MODE if settings else "paper",
     )
 
     # 7. Latency monitoring
@@ -1325,6 +1326,7 @@ async def run_daily_session(
                 market=market.code,
                 exchange_code=market.exchange_code,
                 decision_id=decision_id,
+                mode=settings.MODE,
             )
 
     logger.info("Daily trading session completed")

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,135 @@ 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()
+
+
+# ---------------------------------------------------------------------------
+# mode column tests (issue #212)
+# ---------------------------------------------------------------------------
+
+
+def test_log_trade_stores_mode_paper() -> None:
+    """log_trade must persist mode='paper' in the trades table."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=85,
+        rationale="test",
+        mode="paper",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "paper"
+
+
+def test_log_trade_stores_mode_live() -> None:
+    """log_trade must persist mode='live' in the trades table."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=85,
+        rationale="test",
+        mode="live",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "live"
+
+
+def test_log_trade_default_mode_is_paper() -> None:
+    """log_trade without explicit mode must default to 'paper'."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="HOLD",
+        confidence=50,
+        rationale="test",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "paper"
+
+
+def test_mode_column_exists_in_schema() -> None:
+    """trades table must have a mode column after init_db."""
+    conn = init_db(":memory:")
+    cursor = conn.execute("PRAGMA table_info(trades)")
+    columns = {row[1] for row in cursor.fetchall()}
+    assert "mode" in columns
+
+
+def test_mode_migration_adds_column_to_existing_db() -> None:
+    """init_db must add mode column to existing DBs that lack it (migration)."""
+    import sqlite3
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+    try:
+        # Create DB without mode column (simulate old schema)
+        old_conn = sqlite3.connect(db_path)
+        old_conn.execute(
+            """CREATE TABLE trades (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                timestamp TEXT NOT NULL,
+                stock_code TEXT NOT NULL,
+                action TEXT NOT NULL,
+                confidence INTEGER NOT NULL,
+                rationale TEXT,
+                quantity INTEGER,
+                price REAL,
+                pnl REAL DEFAULT 0.0,
+                market TEXT DEFAULT 'KR',
+                exchange_code TEXT DEFAULT 'KRX',
+                decision_id TEXT
+            )"""
+        )
+        old_conn.commit()
+        old_conn.close()
+
+        # Run init_db — should add mode column via migration
+        conn = init_db(db_path)
+        cursor = conn.execute("PRAGMA table_info(trades)")
+        columns = {row[1] for row in cursor.fetchall()}
+        assert "mode" in columns
+        conn.close()
+    finally:
+        os.unlink(db_path)