main.py

"""
퀀트 트레이더 시스템 - 메인 실행 파일

사용법:
    # 백테스팅 (과거 데이터로 전략 검증)
    python main.py --mode backtest --strategy scoring --symbol 005930

    # 백테스트 리포트 저장 경로 지정
    python main.py --mode backtest --strategy scoring --symbol 005930 --output-dir reports

    # 페이퍼 트레이딩 (모의 매매, 워치리스트 1회 순회 후 종료)
    python main.py --mode paper --strategy scoring

    # 모의 24시간 스케줄 루프 (systemd 상시 구동용, config trading.mode=paper 권장)
    python main.py --mode schedule --strategy scoring

    # 실전 (ENABLE_LIVE_TRADING=true + --confirm-live 필요)
    python main.py --mode live --strategy scoring --confirm-live

    # 특정 기간 백테스팅
    python main.py --mode backtest --strategy scoring --symbol 005930 --start 2023-01-01 --end 2025-12-31

    # momentum_top 동일비중 멀티종목 (워치리스트 정의와 동일, KS11 대비)
    python main.py --mode backtest_momentum_top --start 2019-01-01 --end 2026-03-23 --rebalance-days 20

    # 긴급 전체 청산 (live 설정에서는 ENABLE_LIVE_TRADING=true + --confirm-live 필요)
    python main.py --mode liquidate --confirm-live

    # 바스켓 리밸런싱 (목표 비중 대비 드리프트 체크 → 주문)
    python main.py --mode rebalance --basket kr_blue_chip
    python main.py --mode rebalance --basket kr_blue_chip --dry-run
"""

import os
import sys
import argparse
from pathlib import Path

# 프로젝트 루트를 경로에 추가
sys.path.insert(0, str(Path(__file__).parent))

from config.config_loader import Config
from database.models import init_database
from monitoring.logger import setup_logger
from loguru import logger
from core.watchlist_manager import WatchlistManager


def run_portfolio_backtest(args):
    """멀티종목 포트폴리오 백테스팅 모드 실행"""
    from backtest.portfolio_backtester import PortfolioBacktester

    logger.info("=" * 50)
    logger.info("포트폴리오 백테스팅 모드 시작")
    logger.info("=" * 50)

    symbols_str = getattr(args, "symbols", "") or ""
    if not symbols_str:
        logger.error(
            "--symbols 옵션으로 종목 코드를 지정하세요. "
            "예: --symbols 005930,000660,035720,051910,006400"
        )
        return

    symbols = [s.strip() for s in symbols_str.split(",") if s.strip()]
    if len(symbols) < 2:
        logger.error("포트폴리오 백테스트는 최소 2개 종목이 필요합니다.")
        return

    logger.info("종목: {} ({}개)", symbols, len(symbols))

    pbt = PortfolioBacktester()
    result = pbt.run(
        symbols=symbols,
        strategy_name=args.strategy,
        start_date=args.start,
        end_date=args.end,
    )

    if not result:
        logger.error("포트폴리오 백테스트 결과가 비어 있습니다.")
        return

    pbt.print_report(result)


def run_backtest(args):
    """백테스팅 모드 실행"""
    from core.data_collector import DataCollector
    from backtest.backtester import Backtester
    from backtest.report_generator import ReportGenerator

    logger.info("=" * 50)
    logger.info("📊 백테스팅 모드 시작")
    logger.info("=" * 50)

    config = Config.get()
    universe = (config.risk_params or {}).get("backtest_universe") or {}
    u_mode = (universe.get("mode") or "current").strip().lower()
    if u_mode == "current":
        import sys
        logger.warning(
            "backtest_universe.mode=current — 현재 상장 종목 기준. "
            "생존자 편향으로 수익률이 과대평가될 수 있습니다. "
            "mode: historical 또는 kospi200 권장 (설계서 §8.2.1)."
        )
        print(
            "\n" + "=" * 60 + "\n"
            "  ⚠️  [경고] 생존자 편향 (Survivorship Bias)\n"
            + "=" * 60 + "\n"
            "  backtest_universe.mode = current (기본)\n"
            "  → 현재 상장 종목만 사용하므로 상장폐지 종목이 제외됩니다.\n"
            "  → 백테스트 수익률이 실전보다 과대평가될 수 있습니다.\n"
            "  → config/risk_params.yaml에서 mode: historical 로 변경 권장.\n"
            + "=" * 60 + "\n",
            file=sys.stderr,
        )

    collector = DataCollector()
    symbol = args.symbol or "005930"

    logger.info("종목 {} 데이터 수집 중...", symbol)
    df = collector.fetch_stock(symbol, args.start, args.end)

    if df.empty:
        logger.error(
            "데이터를 수집할 수 없습니다. 백테스트를 위해 다음 중 하나를 설정하세요:\n"
            "  1) pip install FinanceDataReader   # 한국 주식 권장\n"
            "  2) pip install yfinance            # 한국 종목 005930.KS 지원\n"
            "  3) KIS API 환경변수 설정 시 일봉 조회로 자동 대체\n"
            "지표: pandas-ta는 Python 3.11~3.12 범위에서 사용하는 것을 권장하며, "
            "패키지 정책도 >=3.11,<3.13 기준입니다."
        )
        return

    logger.info("수집 완료: {}건 ({} ~ {})", len(df), df.index[0], df.index[-1])

    # 백테스팅 실행: strict-lookahead 기본 True. 해제 시에만 아래 명시적 경고 출력
    if not args.strict_lookahead:
        import sys
        border = "=" * 60
        msg = (
            f"\n{border}\n"
            "  ⚠️  [경고] Look-Ahead Bias 방지가 해제되었습니다 (--allow-lookahead)\n"
            f"{border}\n"
            "  • 미래 데이터가 신호 생성에 섞여 들어갈 수 있습니다.\n"
            "  • 백테스트 수익률이 실제보다 훨씬 좋게 나올 수 있습니다.\n"
            "  • 이 결과를 믿고 실전 투입 시 큰 손실이 날 수 있습니다.\n"
            "  • 실전 투입 판단 근거로 사용하지 마세요.\n"
            "  • 기본 동작은 strict-lookahead=True(권장)입니다.\n"
            f"{border}\n"
        )
        logger.warning("Look-Ahead Bias 방지 해제됨 (--allow-lookahead). 실전 판단 근거로 사용 금지.")
        print(msg, file=sys.stderr)
    backtester = Backtester()
    result = backtester.run(
        df,
        strategy_name=args.strategy,
        strict_lookahead=args.strict_lookahead,
        notify_overtrading=True,
    )

    if not result:
        logger.error("백테스트 결과가 비어 있습니다.")
        return

    # 결과 출력
    backtester.print_report(result)

    report_generator = ReportGenerator(output_dir=args.output_dir)
    report_paths = report_generator.generate_all(result)
    if report_paths:
        logger.info(
            "백테스트 리포트 저장 완료 | txt={} | html={}",
            report_paths.get("text_path", ""),
            report_paths.get("html_path", ""),
        )


def run_backtest_momentum_top(args):
    """momentum_top 정의(12개월 수익률 상위 N) 동일비중 멀티종목 백테스트. KS11 등 벤치와 지표 비교."""
    from backtest.momentum_top_portfolio import (
        print_momentum_top_portfolio_report,
        run_momentum_top_portfolio_backtest,
    )

    logger.info("=" * 50)
    logger.info("📊 momentum_top 포트폴리오 백테스트")
    logger.info("=" * 50)

    start = args.start or "2019-01-01"
    end = args.end or "2026-03-23"
    bench = getattr(args, "benchmark_symbol", None) or "KS11"
    ic = getattr(args, "initial_capital", None)
    reb = max(1, int(getattr(args, "rebalance_days", 20)))

    result = run_momentum_top_portfolio_backtest(
        start_date=start,
        end_date=end,
        rebalance_every=reb,
        initial_capital=ic,
        benchmark_symbol=bench,
        top_n_override=getattr(args, "top_n", None),
        use_market_filter=getattr(args, "market_filter", False),
        cash_buffer=float(getattr(args, "cash_buffer", 0.0) or 0.0),
        portfolio_stop=float(getattr(args, "portfolio_stop", 0.0) or 0.0),
        stop_cooldown=int(getattr(args, "stop_cooldown", 0) or 0),
    )
    if not result:
        logger.error("momentum_top 포트폴리오 백테스트 실패")
        return
    print_momentum_top_portfolio_report(result, config=Config.get())


def _run_auto_correlation(df, config, threshold=0.7):
    """상관 분석 실행 후 자동 비활성화 대상 가중치 키 반환."""
    from core.indicator_correlation import (
        run_indicator_correlation_check,
        suggest_disable_weights,
    )

    result = run_indicator_correlation_check(
        df,
        threshold=threshold,
        config=config,
        save_report=False,
    )
    disable = suggest_disable_weights(result.get("high_correlation_pairs", []))
    if result.get("high_correlation_pairs"):
        logger.info(
            "[auto-correlation] 고상관 쌍 {}개 발견: {}",
            len(result["high_correlation_pairs"]),
            [(p[0], p[1], f"r={p[2]:.2f}") for p in result["high_correlation_pairs"]],
        )
    if disable:
        logger.info("[auto-correlation] 자동 비활성화: {}", disable)
    else:
        logger.info("[auto-correlation] 고상관 쌍 없음. 모든 지표 유지.")
    return disable


def run_param_optimize(args):
    """전략 파라미터 자동 최적화 (Grid Search / Bayesian / 가중치 포함).

    --include-weights: 스코어링 전략일 때 가중치도 탐색 (대칭 Grid, OOS 샤프 게이트 포함).
    --auto-correlation: 최적화 전 상관 분석 자동 실행, 고상관 지표 비활성화 후 최적화.
    권장 파이프라인: check_correlation → optimize --include-weights → validate --walk-forward.
    """
    from datetime import datetime, timedelta

    from core.data_collector import DataCollector
    from backtest.param_optimizer import grid_search, bayesian_optimize, grid_search_scoring_weights

    logger.info("=" * 50)
    logger.info("전략 파라미터 최적화 ({}), 전략: {}", getattr(args, "optimizer", "grid"), args.strategy)
    logger.info("=" * 50)

    config = Config.get()
    collector = DataCollector()
    symbol = args.symbol or "005930"
    end_date = args.end
    start_date = args.start
    if not end_date:
        end_date = datetime.now().strftime("%Y-%m-%d")
    if not start_date:
        vy = getattr(args, "validation_years", 5)
        start_date = (datetime.now() - timedelta(days=365 * vy)).strftime("%Y-%m-%d")
        logger.info(
            "최적화 --start 미지정 → check_correlation·validate와 동일하게 최근 {}년 구간 사용",
            vy,
        )
    df = collector.fetch_stock(symbol, start_date, end_date)
    if df.empty or len(df) < 252:
        logger.error("데이터가 없거나 1년 미만입니다. --start, --end 및 데이터 소스를 확인하세요.")
        return

    optimizer = getattr(args, "optimizer", "grid")
    metric = getattr(args, "optimize_metric", "sharpe_ratio")
    train_ratio = getattr(args, "train_ratio", 0.7)
    include_weights = getattr(args, "include_weights", False)

    # 스코어링 전략 + --include-weights → 가중치 포함 Grid Search
    if args.strategy == "scoring" and include_weights:
        disabled = [s.strip() for s in (getattr(args, "disable_weights", "") or "").split(",") if s.strip()]

        auto_corr = getattr(args, "auto_correlation", False)
        if auto_corr:
            corr_threshold = getattr(args, "correlation_threshold", 0.7)
            auto_disabled = _run_auto_correlation(df, config, threshold=corr_threshold)
            merged = sorted(set(disabled) | set(auto_disabled))
            if merged != sorted(disabled):
                logger.info(
                    "[auto-correlation] 비활성화 병합: {} → {}",
                    disabled or "(없음)", merged,
                )
            disabled = merged

        result = grid_search_scoring_weights(
            df,
            metric=metric,
            train_ratio=train_ratio,
            strict_lookahead=True,
            disabled_weights=disabled or None,
        )
        if result is None:
            logger.warning(
                "가중치 최적화 결과 없음: OOS 구간 부족(30거래일 미만)이거나 OOS 샤프가 게이트(기본 1.0) 미달입니다. "
                "로그·stdout 메시지를 확인하세요. 기간을 늘리려면 --validation-years 또는 --start/--end 를 지정할 수 있습니다."
            )
            return
        if result.get("message"):
            logger.warning(result["message"])
            return

        logger.info("=" * 60)
        logger.info("[가중치 최적화 결과]")
        logger.info("평가 조합 수: {}", result["total_evaluated"])
        logger.info("최적 가중치 (대칭): {}", result["best_weight_combo"])
        logger.info("최적 임계값: buy={}, sell={}", *result["best_threshold"])
        logger.info("학습 구간 {} ({}): {:.2f}", metric, result["train_period"], result["best_score"])
        if result.get("disabled_weights"):
            logger.info("비활성화 지표(0 고정): {}", result["disabled_weights"])

        if result.get("oos_metrics"):
            oos = result["oos_metrics"]
            logger.info(
                "OOS 구간 {} ({}): sharpe={}, return={:.1f}%",
                metric, result.get("oos_period", ""),
                oos.get("sharpe_ratio"), oos.get("total_return", 0),
            )
            logger.info(
                "OOS 샤프 게이트 통과 (≥ {:.1f}). 채택 스니펫은 위 stdout에 출력되었습니다.",
                result["oos_sharpe_gate"],
            )
        if result.get("all_results"):
            logger.info("상위 5개 조합:")
            for r in result["all_results"][:5]:
                logger.info("  {} | threshold={} | {}={:.2f}", r["weight_combo"], r["threshold"], metric, r["score"])

        logger.info("=" * 60)
        validate_cmd = (
            f"python main.py --mode validate --walk-forward --strategy scoring "
            f"--symbol {symbol} --validation-years 5"
        )
        logger.info("다음 단계 (워크포워드 검증):\n  {}", validate_cmd)
        if result["oos_passed"]:
            logger.info(
                "YAML 스니펫을 strategies.yaml에 반영한 뒤 위 명령을 실행하세요.\n"
                "워크포워드에서도 안정적이면 --mode paper 로 모의투자를 시작합니다."
            )
        return

    # 기존: 임계값만 탐색
    if optimizer == "bayesian":
        result = bayesian_optimize(
            df,
            strategy_name=args.strategy,
            metric=metric,
            train_ratio=train_ratio,
            strict_lookahead=True,
            n_calls=getattr(args, "optimize_calls", 30),
        )
    else:
        result = grid_search(
            df,
            strategy_name=args.strategy,
            search_space=None,
            metric=metric,
            train_ratio=train_ratio,
            strict_lookahead=True,
        )

    if result.get("message"):
        logger.warning(result["message"])
        return

    logger.info("최적 파라미터: {}", result["best_params"])
    logger.info("학습 구간 {} ({}): {:.2f}", result["metric"], result["train_period"], result["best_score"])
    if result.get("oos_metrics"):
        logger.info(
            "OOS 구간 {} ({}): {} (오버피팅 확인용)",
            result["metric"], result.get("oos_period", ""), result["oos_metrics"].get(result["metric"]),
        )
    if result.get("all_results"):
        logger.info("상위 5개: {}", [r["params"] for r in result["all_results"][:5]])


def run_check_indicator_correlation(args):
    """스코어링 지표 독립성 검증: 지표 간 상관계수 계산, 0.7 이상 쌍에 대해 제거/가중치 축소 권고."""
    from datetime import datetime, timedelta

    from core.data_collector import DataCollector
    from core.indicator_correlation import run_indicator_correlation_check, render_correlation_report

    symbol = args.symbol or "005930"
    years = getattr(args, "validation_years", 5)
    end_date = args.end
    start_date = args.start
    if not end_date:
        end_date = datetime.now().strftime("%Y-%m-%d")
    if not start_date:
        start_date = (datetime.now() - timedelta(days=365 * years)).strftime("%Y-%m-%d")

    collector = DataCollector()
    df = collector.fetch_stock(symbol, start_date, end_date)
    if df.empty or len(df) < 120:
        logger.error("지표 상관 검증용 데이터 부족: {} ({}~{}, {}일)", symbol, start_date, end_date, len(df))
        return

    threshold = args.correlation_threshold
    result = run_indicator_correlation_check(
        df,
        threshold=threshold,
        symbol=symbol,
        config=Config.get(),
        output_dir=getattr(args, "output_dir", "reports"),
        save_report=True,
        start=start_date,
        end=end_date,
    )
    report_text = render_correlation_report(result, symbol=symbol, start=start_date, end=end_date)
    print(report_text)
    logger.info("지표 독립성 검증 리포트 저장: {}", result.get("report_path"))

    disable_weights = result.get("disable_weights", [])
    if disable_weights:
        logger.info(
            "고상관 지표 자동 비활성화 대상: {}. "
            "optimize --include-weights --disable-weights {} 로 전달하거나 "
            "--auto-correlation 플래그를 사용하세요.",
            disable_weights, ",".join(disable_weights),
        )


def run_check_ensemble_correlation(args):
    """앙상블 구성 전략(technical, momentum_factor, volatility_condition) 신호 간 상관계수 검증.
    BUY=1, SELL=-1, HOLD=0 로 수치화한 일별 시리즈 상관계수. |r| >= 0.6 이면 conservative 모드 또는 전략 재구성 권고."""
    from datetime import datetime, timedelta
    from pathlib import Path

    from core.data_collector import DataCollector
    from core.ensemble_correlation import run_ensemble_signal_correlation_check, render_ensemble_correlation_report

    symbol = args.symbol or "005930"
    years = getattr(args, "validation_years", 5)
    end_date = args.end
    start_date = args.start
    if not end_date:
        end_date = datetime.now().strftime("%Y-%m-%d")
    if not start_date:
        start_date = (datetime.now() - timedelta(days=365 * years)).strftime("%Y-%m-%d")

    collector = DataCollector()
    df = collector.fetch_stock(symbol, start_date, end_date)
    if df.empty or len(df) < 60:
        logger.error("앙상블 신호 상관 검증용 데이터 부족: {} ({}~{}, {}일)", symbol, start_date, end_date, len(df))
        return

    threshold = getattr(args, "ensemble_correlation_threshold", 0.6)
    result = run_ensemble_signal_correlation_check(df, threshold=threshold)
    report_text = render_ensemble_correlation_report(result)

    out_dir = Path(getattr(args, "output_dir", "reports"))
    out_dir.mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    report_path = out_dir / f"ensemble_correlation_{symbol}_{timestamp}.txt"
    report_path.write_text(report_text, encoding="utf-8")

    print(report_text)
    logger.info("앙상블 신호 독립성 검증 리포트 저장: {}", report_path)


def run_strategy_validation(args):
    """전략 검증 모드 실행. --walk-forward 시 슬라이딩 윈도우 워크포워드 검증."""
    from backtest.strategy_validator import StrategyValidator
    from core.notifier import Notifier

    config = Config.get()
    universe = (config.risk_params or {}).get("backtest_universe") or {}
    u_mode = (universe.get("mode") or "current").strip().lower()
    if u_mode == "current":
        logger.warning(
            "backtest_universe.mode=current — 벤치마크·유니버스가 현재 종목 기준. "
            "생존자 편향 위험. mode: historical 또는 kospi200 권장 (§8.2.1)."
        )
    else:
        logger.info("backtest_universe.mode={} — 생존자 편향 완화 적용", u_mode)

    validator = StrategyValidator(config=config, output_dir=args.output_dir)
    discord = Notifier(config)

    if getattr(args, "walk_forward", False):
        result = validator.run_walk_forward(
            symbol=args.symbol or "005930",
            strategy_name=args.strategy,
            start_date=args.start,
            end_date=args.end,
            benchmark_symbol=args.benchmark_symbol,
            validation_years=args.validation_years,
            train_days=504,
            test_days=252,
            step_days=252,
            min_sharpe=args.min_sharpe,
            max_mdd=args.max_mdd,
        )
        print(validator._render_walk_forward_report(result))
        logger.info("워크포워드 검증 리포트 저장 완료: {}", result["report_path"])
        warnings = result.get("warnings", [])
    else:
        result = validator.run(
            symbol=args.symbol or "005930",
            strategy_name=args.strategy,
            start_date=args.start,
            end_date=args.end,
            benchmark_symbol=args.benchmark_symbol,
            validation_years=args.validation_years,
            split_ratio=args.split_ratio,
            min_sharpe=args.min_sharpe,
            max_mdd=args.max_mdd,
            use_benchmark_top50=not getattr(args, "no_benchmark_top50", False),
        )
        validator.print_report(result)
        logger.info("전략 검증 리포트 저장 완료: {}", result["report_path"])
        warnings = result.get("validation", {}).get("warnings", [])

    if warnings:
        warn_text = "\n".join([f"⚠️ {w}" for w in warnings])
        discord.send_message(
            f"📊 전략 검증 경고 ({args.strategy} | {args.symbol or '005930'})\n{warn_text}"
        )

    # 앙상블 전략일 때 독립성 검증 자동 실행
    if args.strategy == "ensemble":
        _run_ensemble_independence_check_in_validate(args, config, discord)


def _run_ensemble_independence_check_in_validate(args, config, notifier):
    """validate 모드에서 앙상블 전략의 신호 독립성을 자동 검증한다."""
    from datetime import datetime, timedelta
    from core.data_collector import DataCollector
    from core.ensemble_correlation import (
        run_ensemble_signal_correlation_check,
        render_ensemble_correlation_report,
    )

    symbol = args.symbol or "005930"
    end_date = args.end or datetime.now().strftime("%Y-%m-%d")
    start_date = args.start or (datetime.now() - timedelta(days=365 * 3)).strftime("%Y-%m-%d")

    collector = DataCollector(config)
    df = collector.fetch_stock(symbol, start_date, end_date)
    if df.empty or len(df) < 60:
        logger.warning("앙상블 독립성 검증 스킵: 데이터 부족 ({}일)", len(df) if df is not None else 0)
        return

    threshold = getattr(args, "ensemble_correlation_threshold", 0.6)
    result = run_ensemble_signal_correlation_check(df, threshold=threshold, config=config)
    report = render_ensemble_correlation_report(result)

    logger.info("\n{}", report)

    if result.get("should_force_conservative"):
        warn_msg = (
            f"앙상블 독립성 검증 경고 ({symbol}): "
            f"고상관 쌍 {result['n_high']}개 감지 (|r|>={threshold}). "
            "majority_vote 모드에서 다수결 의미 퇴색 위험. "
            "conservative 전환 또는 전략 재구성 권장."
        )
        notifier.send_message(warn_msg)
    else:
        logger.info("앙상블 독립성 검증 통과: 모든 전략 쌍 |r| < {:.1f}", threshold)


# ──────────────────────────────────────────────────────────────
# 바스켓 리밸런싱 모드
# ──────────────────────────────────────────────────────────────
def _rebalance_live_strategy_id(basket_name: str) -> str:
    """live rebalance의 gate/account/order tag를 묶는 승인 단위."""
    from core.basket_rebalancer import rebalance_live_strategy_id

    return rebalance_live_strategy_id(basket_name)


def run_deploy_check(args) -> int:
    """바스켓 배포 점검 — 계획·예상비용·회전율·활성화 절차를 한눈에.

    수익성 결론(분산 보유 buy&hold)을 실제로 굴리기 전, 운영자가 한 명령으로
    바스켓 상태를 확인하고 다음 활성화 절차를 받는다. 가격은 최근 거래일 종가를
    주입해 "오늘" 시세가 없어도 동작한다. 반환: 0=점검가능, 1=확인 필요.
    """
    import json
    from datetime import datetime, timedelta
    from core.basket_rebalancer import BasketRebalancer
    from core.basket_deploy import summarize_basket_deployment
    from core.data_collector import DataCollector

    config = Config.get()
    basket_name = getattr(args, "basket", None) or "kr_diversified_hold"
    as_of = getattr(args, "as_of", None)

    baskets_cfg = BasketRebalancer._load_baskets_config()
    if basket_name not in baskets_cfg:
        logger.error("바스켓 '{}' 없음. 가능: {}", basket_name, ", ".join(baskets_cfg.keys()))
        return 1
    basket_cfg = baskets_cfg[basket_name]
    holdings = basket_cfg.get("holdings", {})

    # 최근 거래일 종가 주입(오늘 시세 없어도 동작)
    dc = DataCollector()
    end = as_of or datetime.now().strftime("%Y-%m-%d")
    start = (datetime.strptime(end, "%Y-%m-%d") - timedelta(days=20)).strftime("%Y-%m-%d")
    prices = {}
    for sym in holdings:
        try:
            df = dc.fetch_stock(sym, start_date=start, end_date=end)
            if df is not None and not df.empty:
                prices[sym] = float(df["close"].iloc[-1])
        except Exception as exc:
            logger.debug("가격 조회 실패 {}: {}", sym, exc)

    rb = BasketRebalancer(basket_name=basket_name, config=config)
    orders = rb.plan_rebalance(prices=prices) if prices else []
    summary = summarize_basket_deployment(
        basket_name, basket_cfg, orders, prices,
        portfolio_value=float(getattr(args, "initial_capital", None) or 10_000_000),
    )

    if getattr(args, "json", False):
        print(json.dumps(summary, ensure_ascii=False, indent=2))
        return 0 if summary["ready_to_validate"] else 1

    icon = "✅" if summary["ready_to_validate"] else "⚠️"
    print(f"\n{'=' * 60}")
    print(f"  {icon}  바스켓 배포 점검: {summary['display_name']} ({basket_name})")
    print(f"{'=' * 60}")
    print(f"  활성화: {'예' if summary['enabled'] else '아니오 (enabled=false)'} | "
          f"종목 {summary['holdings_count']}개 | 비중합 정상: {summary['weights_sum_ok']}")
    print(f"  리밸런싱: {summary['rebalance_trigger']} (드리프트 {summary['drift_threshold_pct']}%p, "
          f"회전상한 {summary['max_turnover_ratio_pct']}%)")
    c = summary["costs"]
    print(f"\n  계획 주문: {c['order_count']}건 | 총 거래액 {c['total_trade_amount']:,.0f}원")
    print(f"  예상 비용: 수수료 {c['est_commission']:,.0f} + 세금 {c['est_tax']:,.0f} = "
          f"{c['est_total_cost']:,.0f}원 ({c['cost_bps_of_trade']}bp)")
    if summary["turnover_pct_of_portfolio"] is not None:
        print(f"  포트폴리오 대비 회전율: {summary['turnover_pct_of_portfolio']}%")
    for p in summary["plan"][:10]:
        print(f"    {p['action']:4} {p['symbol']} {p['quantity']}주 @ {p['price']:,.0f} = {p['amount']:,.0f}원")
    print("\n  다음 절차:")
    for i, s in enumerate(summary["next_steps"], 1):
        print(f"    {i}. {s}")
    print()
    return 0 if summary["ready_to_validate"] else 1


def run_rebalance(args):
    """바스켓 포트폴리오 리밸런싱 모드."""
    from datetime import datetime
    from zoneinfo import ZoneInfo
    from core.basket_rebalancer import BasketRebalancer
    from core.notifier import Notifier
    from core.cycle_observability import (
        detect_snapshot_gaps_for_account,
        format_gap_alert,
        record_cycle_event,
    )

    config = Config.get()
    notifier = Notifier(config)
    basket_name = getattr(args, "basket", None)
    dry_run = getattr(args, "dry_run", False)
    force_rebalance = getattr(args, "force_rebalance", False)
    mode = str(config.trading.get("mode", "paper")).lower()
    live_rebalance_confirmed = False

    if basket_name:
        basket_names = [basket_name]
    else:
        basket_names = BasketRebalancer.get_enabled_baskets()
        if not basket_names:
            logger.warning("enabled=true인 바스켓이 없습니다. --basket으로 지정하거나 baskets.yaml에서 enabled를 true로 설정하세요.")
            return

    # 여러 바스켓이 같은 계좌(자본 풀)를 공유하면 각자 목표 비중을 독립 배분해
    # 과배분(예: 80%+80%)되고, paper에서는 NAV 시계열(트랙레코드)이 섞인다 — fail-closed.
    from core.basket_rebalancer import check_basket_account_isolation
    isolation_issues = check_basket_account_isolation(basket_names, config, mode)
    if isolation_issues:
        for issue in isolation_issues:
            logger.error("🚫 바스켓 계좌 격리 실패: {}", issue)
        notifier.send_message(
            "바스켓 리밸런싱 중단 — 계좌 격리 실패:\n" + "\n".join(isolation_issues)
        )
        return

    if mode == "live" and not dry_run:
        _require_live_operator_confirmation(
            args,
            action_label="실전 바스켓 리밸런싱",
            example=(
                "python main.py --mode rebalance "
                f"--basket {basket_name or '<enabled-basket>'} --confirm-live"
            ),
        )
        for name in basket_names:
            strategy_name = _rebalance_live_strategy_id(name)
            gate_issues = _check_live_readiness_gate(config, strategy_name)
            if gate_issues:
                logger.error("=" * 50)
                logger.error(
                    "🚫 실전 바스켓 리밸런싱 검증 실패 ({}) — 아래 항목 확인 후 재시도하세요:",
                    strategy_name,
                )
                for issue in gate_issues:
                    logger.error("  - {}", issue)
                logger.error("리밸런싱 주문도 live gate를 우회할 수 없습니다.")
                logger.error("=" * 50)
                sys.exit(1)
        live_rebalance_confirmed = True

    logger.info("=" * 50)
    logger.info("🔄 바스켓 리밸런싱 시작 (바스켓: {}, dry_run: {})", basket_names, dry_run)
    logger.info("=" * 50)

    # 사이클 하트비트: 결측이 나도 '언제 멈췄는지' 추적 가능하게 시작을 남긴다(6/26 교훈).
    if not dry_run:
        record_cycle_event(
            "CYCLE_START", f"리밸런싱 사이클 시작: {basket_names}", mode=mode,
        )
    cycle_snapshots_saved = 0

    for name in basket_names:
        try:
            live_strategy_name = _rebalance_live_strategy_id(name)
            # 계정·귀속 키는 paper/live 공통(basket_rebalance:<name>) — 트랙레코드를
            # 바스켓별로 격리·귀속한다(기본 계정 ''는 전 계정 합산 뷰라 오염 위험).
            rebalancer = BasketRebalancer(
                basket_name=name,
                config=config,
                account_key=live_strategy_name,
                execution_strategy=live_strategy_name,
            )

            if mode == "live" and not dry_run:
                sync_result = rebalancer.portfolio_mgr.sync_with_broker()
                if not sync_result.get("ok"):
                    msg = sync_result.get("message", "sync failed")
                    logger.error(
                        "바스켓 '{}' live 리밸런싱 전 포지션 동기화 실패: {}", name, msg,
                    )
                    # sys.exit는 SystemExit(BaseException)라 아래 except Exception에 안 걸려
                    # CYCLE_END가 안 남는다 — 중도 사망 breadcrumb을 여기서 명시로 남긴다.
                    record_cycle_event(
                        "CYCLE_ERROR",
                        f"바스켓 '{name}' live 동기화 실패로 사이클 중단: {msg}",
                        severity="error", strategy=live_strategy_name, mode=mode,
                    )
                    sys.exit(1)

            report = rebalancer.get_status_report()
            logger.info("\n{}", report)

            # 1일 1매매 패스 원칙 강제: 같은 날 두 번째 실행(중복 스케줄·수동 재실행)이
            # 회전 상한(1회 15%)을 사실상 2배로 만드는 것을 차단한다 — 6/10 진입 뭉침
            # (하루 4회 실행 → 61% 집중 매입, 타이밍 비용 -1%p)의 재발 방지를 코드로.
            # 실측: 7/3·7/7 일일 태스크가 사이클을 2회 연속 실행함. 결측 복구 재시도
            # 크론은 목적이 스냅샷이라 이 가드로 오히려 더 안전해진다(매매 없이 복구).
            # 판정 실패 시 기존 동작 유지(가드는 방어선이지 게이트가 아님).
            # 우회: --force-rebalance (운영자 명시 결정).
            already_traded_today = False
            if not dry_run and not force_rebalance:
                try:
                    from database.repositories import get_trade_history
                    today0 = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
                    already_traded_today = bool(get_trade_history(
                        mode=mode, start_date=today0, account_key=live_strategy_name,
                    ))
                except Exception as guard_exc:
                    logger.debug("바스켓 '{}' 당일 체결 판정 실패(가드 생략): {}", name, guard_exc)

            executed = False
            if already_traded_today:
                logger.info(
                    "바스켓 '{}' 오늘 이미 체결 있음 — 1일 1매매 패스 원칙으로 매매 건너뜀 "
                    "(스냅샷·리포트는 진행, 우회: --force-rebalance)", name,
                )
                record_cycle_event(
                    "REBALANCE_SKIPPED_DAILY_LIMIT",
                    f"바스켓 '{name}' 당일 재실행 — 매매 생략(1일 1매매 패스)",
                    strategy=live_strategy_name, mode=mode,
                )
            else:
                should, reason = rebalancer.should_rebalance()
                if not should and not dry_run:
                    logger.info("바스켓 '{}' 리밸런싱 불필요: {}", name, reason)
                else:
                    orders = rebalancer.plan_rebalance()
                    if not orders:
                        logger.info("바스켓 '{}' 리밸런싱 주문 없음", name)
                    else:
                        result = rebalancer.execute(
                            orders,
                            dry_run=dry_run,
                            live_confirmed=live_rebalance_confirmed,
                        )
                        executed = True
                        summary = (
                            f"바스켓 '{name}' 리밸런싱 {'(DRY RUN) ' if dry_run else ''}"
                            f"완료: 실행 {result['executed']}건, 스킵 {result['skipped']}건, "
                            f"실패 {result['failed']}건"
                        )
                        logger.info(summary)
                        notifier.send_message(summary)
                        # 예외성 실패(status=error)는 가드 거부(보호 동작, 통상 요약)와
                        # 달리 원장 불일치 가능성이 있는 인프라 실패 — 즉시 critical로
                        # 승격한다. 7/7 포지션 유실이 통상 요약에 묻혀 3일 지난 교훈.
                        error_details = [
                            d for d in result.get("details", [])
                            if d.get("status") == "error"
                        ]
                        if error_details and not dry_run:
                            err_msg = (
                                f"🚨 바스켓 '{name}' 주문 실행 예외 {len(error_details)}건 "
                                f"— 원장 정합성 확인 필요: "
                                + "; ".join(
                                    str(d.get("reason", ""))[:80]
                                    for d in error_details[:3]
                                )
                            )
                            record_cycle_event(
                                "ORDER_ERROR", err_msg, severity="critical",
                                strategy=live_strategy_name, mode=mode,
                            )
                            notifier.send_message(err_msg, critical=True)

            # 트랙레코드: 거래 여부와 무관하게 바스켓 계정의 일일 NAV 스냅샷을 남긴다.
            # 보유 종목 가격이 전부 확보된 경우에만 저장(가짜 NAV 방지), 멱등 upsert.
            if not dry_run:
                snapshot_saved = rebalancer.save_daily_nav_snapshot()
                # 사이클 관측·경보: 스냅샷 저장/스킵을 기록하고, 최근 영업일 결측을
                # 당일 경보로 노출한다(6/26류 조용한 누락 재발 방지). best-effort.
                try:
                    if snapshot_saved:
                        cycle_snapshots_saved += 1
                        record_cycle_event(
                            "SNAPSHOT_SAVED", f"바스켓 '{name}' NAV 스냅샷 저장",
                            strategy=live_strategy_name, mode=mode,
                        )
                    else:
                        record_cycle_event(
                            "SNAPSHOT_SKIPPED",
                            f"바스켓 '{name}' NAV 스냅샷 스킵 — 가격 미확보 등",
                            severity="warning", strategy=live_strategy_name, mode=mode,
                        )
                    # 스냅샷 귀속(_nav_attribution_date)이 KST 기준이므로 결측 판정의
                    # '오늘'도 KST로 맞춘다 — 호스트 TZ가 KST가 아니면(클라우드/CI) 당일
                    # 결측 경보가 엉뚱한 날을 보거나 안 울리는 것을 방지(적대적 리뷰 medium).
                    now = datetime.now(ZoneInfo("Asia/Seoul")).replace(tzinfo=None)
                    gaps = detect_snapshot_gaps_for_account(
                        config, live_strategy_name, now,
                    )
                    if gaps:
                        alert = format_gap_alert(name, gaps, today=now)
                        today_missing = now.date() in gaps
                        # 오늘 결측은 즉시 조치(critical), 과거 결측 재알림은 경고 수준
                        # — 복구 불가한 과거 결측을 매일 critical로 울리는 피로 방지.
                        record_cycle_event(
                            "SNAPSHOT_GAP", alert,
                            severity="critical" if today_missing else "warning",
                            strategy=live_strategy_name, mode=mode,
                        )
                        notifier.send_message(alert, critical=today_missing)
                except Exception as e:
                    logger.debug("바스켓 '{}' 스냅샷 관측/경보 생략: {}", name, e)
                # 일일 디스코드 리포트: 상시 스케줄러의 장마감 리포트는 일일 CLI 운영
                # 에서는 돌지 않아 운영자가 받는 푸시가 0건이었다 — 사이클마다 바스켓
                # NAV 요약 카드를 보낸다. 실패해도 사이클에는 영향 없음(채널은 보조).
                try:
                    # 시장가 기준으로 평가해야 한다 — current_prices 없이 호출하면 paper
                    # 포지션이 avg_price로 평가돼 누적수익 −0.0%·MDD 0.0%가 60일 내내
                    # 표시된다(자기검토 2라운드 HIGH). 스냅샷 단계가 채운 가격 캐시 재사용.
                    _snap_cache = getattr(rebalancer, "_market_snapshot", None) or {}
                    _prices = {s: v["price"] for s, v in _snap_cache.items()}
                    summary_data = rebalancer.portfolio_mgr.get_portfolio_summary(
                        current_prices=_prices or None,
                    )
                    # 일간 수익률: 직전 스냅샷 대비 (summary에는 누적치만 있다).
                    # 적립식 계정은 입금을 분모에 더해 중화한다 — 입금일에 +33% 같은
                    # 가짜 일간 수익 방지(docs/POCKET_TRACK_PLAN.md §4).
                    daily_ret = 0.0
                    try:
                        from database.repositories import (
                            get_portfolio_snapshots,
                            get_cash_flow_total_between,
                        )
                        from core.portfolio_manager import twr_period_return
                        snaps = get_portfolio_snapshots(
                            days=7, account_key=live_strategy_name,
                        )
                        if snaps is not None and len(snaps) >= 2:
                            sdf = snaps.sort_values("date")
                            prev = float(sdf["total_value"].iloc[-2])
                            last = float(sdf["total_value"].iloc[-1])
                            # 유입 경계는 자정 귀속(date)이 아니라 실제 측정 시각
                            # (created_at) — 직전 스냅샷 '이전'의 같은 날 입금을
                            # 이중 중화하지 않게(적대적 리뷰 medium).
                            if "created_at" in sdf.columns and sdf["created_at"].iloc[-2] is not None:
                                prev_boundary = sdf["created_at"].iloc[-2]
                            else:
                                prev_boundary = sdf["date"].iloc[-2]
                            if prev > 0:
                                flow = 0.0
                                try:
                                    flow = get_cash_flow_total_between(
                                        live_strategy_name, prev_boundary, datetime.now(),
                                    )
                                except Exception:
                                    pass
                                daily_ret = twr_period_return(prev, last, flow) * 100
                    except Exception:
                        pass
                    report_card = {
                        "total_value": summary_data.get("total_value", 0),
                        "cash": summary_data.get("cash", 0),
                        "daily_return": daily_ret,
                        "cumulative_return": summary_data.get("total_return", 0),
                        "mdd": summary_data.get("mdd", 0),
                        "position_count": summary_data.get("position_count", 0),
                        "total_trades": (result.get("executed", 0) if executed else 0),
                        "strategy_diagnosis": f"바스켓 {name} · paper 트랙레코드 일일 사이클",
                    }
                    # 적립식 계정이면 누적 원금(초기+입금)을 함께 표기 — 평가액과 원금을
                    # 분리해야 '내가 넣은 돈 대비 얼마'가 한눈에 보인다.
                    if float(summary_data.get("deposits_total", 0) or 0) > 0:
                        report_card["principal"] = summary_data.get("principal", 0)
                    # 리포트 v2 부가 필드(시장/설계/일정 대비) — 실패해도 기본 카드는 발송.
                    try:
                        from core.basket_evaluation import (
                            build_daily_report_extras,
                            collect_basket_paper_evaluation,
                        )
                        deployment = rebalancer.diagnose_deployment(_prices or None)
                        eval_result, _ = collect_basket_paper_evaluation(basket_name=name)
                        report_card.update(
                            build_daily_report_extras(
                                eval_result=eval_result, deployment=deployment,
                                # 카드의 '누적 수익률'과 같은 소스(오늘 시가 기준)로 격차 계산
                                # — 스냅샷 결측일에 📊 수치가 어긋나지 않게.
                                nav_return_pct=summary_data.get("total_return"),
                            )
                        )
                    except Exception as e:
                        logger.debug("바스켓 '{}' 리포트 v2 부가필드 생략: {}", name, e)
                    notifier.send_daily_report(report_card)
                except Exception as e:
                    logger.debug("바스켓 '{}' 일일 리포트 발송 실패(무시): {}", name, e)

        except Exception as e:
            logger.error("바스켓 '{}' 리밸런싱 실패: {}", name, e)
            notifier.send_message(f"바스켓 '{name}' 리밸런싱 오류: {e}")
            if not dry_run:
                # 사이클이 이 바스켓에서 죽었음을 남긴다 — 결측 원인 추적의 핵심.
                record_cycle_event(
                    "CYCLE_ERROR", f"바스켓 '{name}' 리밸런싱 실패: {e}",
                    severity="error", strategy=_rebalance_live_strategy_id(name), mode=mode,
                )

    if not dry_run:
        # 사이클 정상 종료 기록: START는 있는데 END가 없으면 중도 사망으로 판별된다.
        record_cycle_event(
            "CYCLE_END",
            f"리밸런싱 사이클 종료: 스냅샷 {cycle_snapshots_saved}/{len(basket_names)} 저장",
            mode=mode,
        )

    # DB 일일 백업: 트랙레코드(거래·포지션·NAV 시계열)가 단일 SQLite 파일이라
    # 손상 시 60영업일 증거가 통째로 소실된다. 기존엔 상시 스케줄러 장마감에서만
    # 백업했는데, 일일 rebalance CLI 운영에서는 그 경로가 돌지 않으므로 여기서도
    # 호출한다. database.backup_path 미설정이면 no-op, 날짜별 파일이라 멱등.
    if not dry_run:
        try:
            from database.backup import run_daily_backup
            run_daily_backup(config)
        except Exception as e:
            logger.warning("리밸런싱 후 DB 백업 실패: {}", e)


def run_paper_trading(args):
    """페이퍼 트레이딩 모드 실행"""
    from datetime import datetime
    from core.data_collector import DataCollector
    from core.order_executor import OrderExecutor
    from core.portfolio_manager import PortfolioManager
    from core.notifier import Notifier
    from database.repositories import get_position, get_all_positions
    from strategies import is_strategy_allowed

    config = Config.get()
    config_mode = str(config.trading.get("mode", "paper")).lower()
    if config_mode == "live":
        logger.warning(
            "settings.trading.mode=live 이지만 --mode paper 실행이므로 이번 실행은 paper로 고정합니다."
        )
        config.trading["mode"] = "paper"
        if hasattr(config, "_settings") and isinstance(config._settings, dict):
            config._settings.setdefault("trading", {})["mode"] = "paper"

    strategy_name = getattr(args, "strategy", None) or config.active_strategy
    allowed, reason = is_strategy_allowed(strategy_name, "paper")
    if not allowed:
        logger.error("🚫 전략 실행 차단: {}", reason)
        sys.exit(1)

    logger.info("=" * 50)
    logger.info("📄 페이퍼 트레이딩 모드 시작 (전략: {}, 상태: experimental 이상)", strategy_name)
    logger.info("=" * 50)

    collector = DataCollector()
    account_key = args.strategy or ""
    portfolio = PortfolioManager(config, account_key=account_key)
    discord = Notifier(config)
    executor = OrderExecutor(config, account_key=account_key)

    raw_watchlist = config.watchlist  # settings.yaml의 watchlist.symbols (설정 원본)
    if not raw_watchlist:
        logger.error(
            "🚫 watchlist가 비어 있습니다. config/settings.yaml의 watchlist.symbols를 설정하세요. "
            "기본 종목(005930) 폴백을 사용하지 않습니다."
        )
        sys.exit(1)
    watchlist = WatchlistManager(config).resolve()

    logger.info("관심 종목: {} (계좌/전략: {})", watchlist, account_key or "default")

    # 최대 보유 기간 초과 포지션 강제 정리 (물리는 상황 방지)
    max_holding_days = (config.risk_params.get("position_limits", {}) or {}).get("max_holding_days", 0)
    if max_holding_days > 0:
        today = datetime.now().date()
        for pos in get_all_positions(account_key=account_key if account_key else None):
            bought_at = getattr(pos, "bought_at", None)
            if not bought_at:
                continue
            bought_date = bought_at.date() if hasattr(bought_at, "date") else bought_at
            holding_days = (today - bought_date).days
            if holding_days >= max_holding_days:
                try:
                    df = collector.fetch_stock(pos.symbol)
                    price = float(df["close"].iloc[-1]) if not df.empty and "close" in df.columns else pos.avg_price
                    result = executor.execute_sell(
                        pos.symbol, price,
                        reason=f"최대 보유 기간({max_holding_days}일) 도달 강제 정리 (보유 {holding_days}일)",
                        strategy=args.strategy,
                    )
                    if result.get("success"):
                        discord.send_trade_alert(result)
                except Exception as e:
                    logger.warning("종목 {} 최대 보유 기간 정리 실패: {}", pos.symbol, e)

    # 전략 선택
    strategy = _get_strategy(args.strategy)

    for symbol in watchlist:
        logger.info("\n--- 종목 {} 분석 시작 ---", symbol)

        try:
            # 최근 데이터 수집
            df = collector.fetch_stock(symbol)

            if df.empty or len(df) < 30:
                logger.warning("종목 {} 데이터 부족 — 스킵", symbol)
                continue

            # 신호 생성 (평균회귀 시 symbol 전달 → 펀더멘털 필터 사용)
            _sig_time = datetime.now()
            signal_info = strategy.generate_signal(df, symbol=symbol)
            signal_info["_signal_at"] = _sig_time

            logger.info(
                "종목 {} | 신호: {} | 점수: {} | 상세: {}",
                symbol, signal_info["signal"], signal_info["score"], signal_info["details"],
            )

            # 모든 비-HOLD 신호를 OperationEvent에 기록
            if signal_info["signal"] != "HOLD":
                discord.send_signal_alert(symbol, signal_info)
                try:
                    from monitoring.paper_monitor import log_event
                    log_event("SIGNAL", f"{signal_info['signal']} {symbol} score={signal_info.get('score', 0)}",
                              symbol=symbol, strategy=strategy_name, mode="paper")
                except Exception:
                    pass

            if signal_info["signal"] == "BUY" and not get_position(symbol, account_key=account_key):
                from core.market_regime import check_market_regime
                regime_result = check_market_regime(config, collector)
                if not regime_result["allow_buys"]:
                    logger.info("시장 국면 [bearish] — 200일선+단기모멘텀 하락 → {} 매수 스킵", symbol)
                    continue
                regime_scale = regime_result["position_scale"]
                capital_summary = portfolio.get_portfolio_summary()
                adjusted_capital = capital_summary["total_value"] * regime_scale
                adjusted_cash = capital_summary["cash"] * regime_scale
                if regime_scale < 1.0:
                    logger.info("시장 국면 [caution] — {} 포지션 사이징 {:.0f}%로 축소", symbol, regime_scale * 100)
                avg_vol = float(df["volume"].rolling(20, min_periods=1).mean().iloc[-1]) if "volume" in df.columns and not df["volume"].empty else None
                order_result = executor.execute_buy(
                    symbol=symbol,
                    price=signal_info["close"],
                    capital=adjusted_capital,
                    available_cash=adjusted_cash,
                    current_invested=capital_summary["current_value"],
                    atr=signal_info.get("atr"),
                    signal_score=signal_info["score"],
                    reason="paper auto-entry",
                    strategy=args.strategy,
                    avg_daily_volume=avg_vol,
                    signal_at=signal_info.get("_signal_at"),
                )
                if order_result.get("success"):
                    discord.send_trade_alert(order_result)
            elif signal_info["signal"] == "SELL" and get_position(symbol, account_key=account_key):
                avg_vol = float(df["volume"].rolling(20, min_periods=1).mean().iloc[-1]) if "volume" in df.columns and not df["volume"].empty else None
                order_result = executor.execute_sell(
                    symbol=symbol,
                    price=signal_info["close"],
                    signal_score=signal_info["score"],
                    reason="paper signal exit",
                    strategy=args.strategy,
                    avg_daily_volume=avg_vol,
                )
                if order_result.get("success"):
                    discord.send_trade_alert(order_result)

        except Exception as e:
            logger.error("종목 {} 분석 실패: {}", symbol, e)
            continue

    # 포트폴리오 요약
    summary = portfolio.get_portfolio_summary()
    logger.info("\n📊 포트폴리오 현황:")
    logger.info("  총 평가금: {:,.0f}원", summary["total_value"])
    logger.info("  수익률: {:.2f}%", summary["total_return"])
    logger.info("  보유 종목: {}개", summary["position_count"])


def _compute_config_hash() -> str:
    """strategies.yaml + risk_params.yaml의 SHA256 해시. 설정 변경 감지용 (레거시 호환)."""
    from config.config_loader import compute_yaml_hash
    return compute_yaml_hash()


def _check_live_readiness_gate(config, strategy_name: str) -> list[str]:
    """
    라이브 전 필수 검증 게이트 (Hard Gate).
    하나라도 실패하면 live 진입 불가. 실패 항목 리스트를 반환 (빈 리스트 = 통과).

    필수 조건:
    1) 현재 commit/config와 일치하는 canonical promotion bundle
    2) live_candidate 승격 결과
    3) 60영업일 execution-backed paper evidence package
    4) 벤치마크 대비 양의 초과수익
    5) 데이터 소스 health check

    레거시 호환: "승인 파일 없음", "승인 파일 파싱 오류" 문자열은 기존 감사 테스트가 확인한다.
    """
    from core.live_readiness import check_live_readiness_gate

    return check_live_readiness_gate(config, strategy_name)


def run_live_trading(args):
    """
    실전 매매 모드 실행.
    4중 확인: 전략 코드 등록 → 환경변수 → --confirm-live → canonical live gate.
    """
    from strategies import get_strategy_names, is_strategy_allowed

    config = Config.get()
    strategy_name = getattr(args, "strategy", None) or config.active_strategy
    if strategy_name not in get_strategy_names():
        logger.error("🚫 Live 전략 실행 차단: 등록되지 않은 전략 '{}'", strategy_name)
        sys.exit(1)

    _require_live_operator_confirmation(
        args,
        action_label="실전 모드 진입",
        example=f"python main.py --mode live --strategy {strategy_name} --confirm-live",
    )

    allowed, reason = is_strategy_allowed(strategy_name, "live")
    if not allowed:
        logger.error(
            "🚫 Live 전략 실행 차단: 전략 상태 레지스트리가 live를 허용하지 않습니다: {}",
            reason,
        )
        sys.exit(1)

    # ── 라이브 전 필수 검증 게이트 (우회 불가) ──
    gate_issues = _check_live_readiness_gate(config, strategy_name)
    if gate_issues:
        logger.error("=" * 50)
        logger.error("🚫 실전 전환 검증 실패 — 아래 항목 확인 후 재시도하세요:")
        for issue in gate_issues:
            logger.error("  - {}", issue)
        logger.error("이 게이트는 우회할 수 없습니다. 모든 조건을 충족한 뒤 재시도하세요.")
        logger.error("=" * 50)
        sys.exit(1)
    logger.info("✅ 라이브 전 검증 게이트 통과")

    logger.info("=" * 50)
    logger.info("🔴 실전 매매 모드 시작 (이중 확인 완료)")
    logger.info("=" * 50)

    old_mode = config.trading.get("mode", "paper")
    config._settings.setdefault("trading", {})["mode"] = "live"
    # 모드 플립 직후 auto_entry의 ENV '켜기' 오버라이드를 YAML 값으로 강제 복귀 —
    # 로드 시점(YAML mode=paper)에는 _resolve_auto_entry의 live-ignore 분기가
    # 발동하지 않아, paper 실험용 QUANT_AUTO_ENTRY=true 잔존 시 signal-only 설정의
    # live가 자동매수하게 되는 구멍을 막는다.
    config.enforce_live_auto_entry_policy()

    try:
        # 토큰 사전 발급 (필수 환경변수 미설정 시 명확히 종료)
        from api.kis_api import KISApi
        kis = KISApi()
        if not kis.authenticate():
            logger.error(
                "KIS API 인증 실패. 실전 모드를 사용하려면 "
                "KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NO 환경변수를 설정하세요."
            )
            sys.exit(1)
        logger.info("KIS API 토큰 사전 발급 완료")
        if not kis.verify_connection():
            logger.error(
                "KIS 잔고 조회 실패 — 실환경 연결 검증 실패. "
                "계좌/권한을 확인한 뒤 재시도하세요. 실전 스케줄러를 시작하지 않습니다."
            )
            sys.exit(1)

        # 블랙스완 상태 확인 (로그만)
        from core.blackswan_detector import BlackSwanDetector
        bs = BlackSwanDetector(config)
        if bs.is_on_cooldown():
            logger.warning("블랙스완 쿨다운 중 — 신규 매수만 차단되며, 손절/익절은 정상 동작합니다.")

        # 장 시작 전 KIS 잔고와 DB 포지션 동기화
        from core.portfolio_manager import PortfolioManager
        portfolio = PortfolioManager(config, account_key=strategy_name)
        sync_result = portfolio.sync_with_broker()
        if not sync_result["ok"]:
            logger.error(
                "포지션 동기화 불일치 — 실전 스케줄러를 시작하지 않습니다: {}",
                sync_result["message"],
            )
            sys.exit(1)

        # 실전 스케줄러 실행 (OrderExecutor는 config에서 mode=live 읽음)
        from core.scheduler import Scheduler
        scheduler = Scheduler(
            strategy_name=strategy_name,
            config=config,
            live_gate_validated=True,
        )
        scheduler.run()
    finally:
        config._settings["trading"]["mode"] = old_mode
        logger.info("실전 모드 설정 복원됨")


def _require_live_operator_confirmation(args, *, action_label: str, example: str) -> None:
    """실주문 가능 경로는 환경변수와 CLI 플래그를 둘 다 요구한다."""
    if os.environ.get("ENABLE_LIVE_TRADING", "").lower() != "true":
        logger.error(
            "{} 거부: 환경변수 ENABLE_LIVE_TRADING=true 가 필요합니다. "
            "실수로 실주문이 나가지 않도록 설정 후 다시 실행하세요.",
            action_label,
        )
        sys.exit(1)

    if not getattr(args, "confirm_live", False):
        logger.error(
            "{} 거부: --confirm-live 플래그가 필요합니다. 예: {}",
            action_label,
            example,
        )
        sys.exit(1)


def run_scheduler_loop(args):
    """
    모의 매매용 무한 스케줄러 (장전/장중/장마감 루프).
    systemd 상시 구동 시 `--mode paper` 한 사이클 종료와 달리 프로세스를 유지한다.
    config.trading.mode 가 live 이면 거부 (--mode live --confirm-live 사용).
    """
    from strategies import is_strategy_allowed
    config = Config.get()
    strategy_name = getattr(args, "strategy", None) or config.active_strategy
    allowed, reason = is_strategy_allowed(strategy_name, "schedule")
    if not allowed:
        logger.error("🚫 스케줄러 전략 실행 차단: {}", reason)
        sys.exit(1)
    if str(config.trading.get("mode", "paper")).lower() == "live":
        logger.error(
            "config.trading.mode 가 live 입니다. 실전 루프는 "
            "ENABLE_LIVE_TRADING=true 및 --mode live --confirm-live 를 사용하세요. "
            "schedule 모드는 모의(paper) 전용입니다."
        )
        sys.exit(1)

    from core.runtime_lock import scheduler_lock
    from core.scheduler import Scheduler

    root = Path(__file__).resolve().parent
    lock_file = root / "data" / ".scheduler.lock"

    with scheduler_lock(lock_file) as acquired:
        if not acquired:
            sys.exit(1)
        logger.info("=" * 50)
        logger.info(
            "🗓️ 스케줄러 모드 시작 (무한 루프, trading.mode={})",
            config.trading.get("mode", "paper"),
        )
        logger.info("=" * 50)
        scheduler = Scheduler(strategy_name=args.strategy, config=config)
        scheduler.run()


def run_compare_paper_backtest(args):
    """모의투자 결과 vs 백테스트 결과 자동 비교 + 실전 전환 준비 평가."""
    from datetime import datetime, timedelta
    from backtest.paper_compare import run_compare, check_live_readiness
    from core.notifier import Notifier

    config = Config.get()

    start_s = args.start
    end_s = args.end
    if not start_s or not end_s:
        end_d = datetime.now()
        start_d = end_d - timedelta(days=30)
        start_s = start_d.strftime("%Y-%m-%d")
        end_s = end_d.strftime("%Y-%m-%d")
        logger.info("비교 기간 미지정 — 최근 30일 사용: {} ~ {}", start_s, end_s)
    try:
        start_date = datetime.strptime(start_s, "%Y-%m-%d")
        end_date = datetime.strptime(end_s, "%Y-%m-%d")
    except ValueError:
        logger.error("날짜 형식은 YYYY-MM-DD 여야 합니다. 예: --start 2025-01-01 --end 2025-03-18")
        return
    if start_date >= end_date:
        logger.error("시작일이 종료일보다 이전이어야 합니다.")
        return

    logger.info("=" * 50)
    logger.info("📊 모의투자 vs 백테스트 비교 ({} ~ {})", start_s, end_s)
    logger.info("=" * 50)

    compare_symbol = getattr(args, "compare_symbol", None)
    result = run_compare(
        start_date=start_date,
        end_date=end_date,
        strategy_name=args.strategy,
        symbol=compare_symbol,
    )
    if result.get("paper_metrics"):
        pm = result["paper_metrics"]
        logger.info(
            "모의투자: 수익률 {:.2f}% | 승률 {:.1f}% | 매도 {}건",
            pm["total_return_pct"], pm["win_rate"], pm["total_trades"],
        )
    if result.get("backtest_metrics"):
        bm = result["backtest_metrics"]
        logger.info(
            "백테스트: 수익률 {:.2f}% | 승률 {:.1f}% | 매도 {}건 (종목: {})",
            bm["total_return"], bm["win_rate"], bm["total_trades"], result.get("symbol", ""),
        )
    if result.get("return_diff_pct") is not None:
        logger.info(
            "차이: 수익률 {:.2f}%p, 승률 {:.2f}%p | divergence={}",
            result["return_diff_pct"], result["win_rate_diff_pct"], result["divergence"],
        )
    logger.info("결과: {}", result["message"])

    # 실전 전환 준비 평가
    logger.info("-" * 50)
    logger.info("🔄 실전 전환 준비 평가")
    readiness = check_live_readiness(
        start_date=start_date,
        end_date=end_date,
        strategy_name=args.strategy,
        symbol=compare_symbol or result.get("symbol"),
        config=config,
    )
    cr = readiness["criteria"]
    logger.info(
        "기준: 방향성 ≥{}%, 수익률차 ≤{}%, 거래일 ≥{}일, 매도 ≥{}건",
        cr["min_direction_agreement_pct"], cr["max_return_diff_pct"],
        cr["min_trading_days"], cr["min_trades"],
    )
    if readiness.get("direction_agreement_pct") is not None:
        logger.info(
            "결과: 방향성 {:.1f}% | 수익률차 {:.1f}% | 거래일 {}일 | 매도 {}건",
            readiness["direction_agreement_pct"], readiness.get("return_diff_pct", 0),
            readiness["trading_days"], readiness["total_trades"],
        )
    status = "✅ 준비 완료" if readiness["ready"] else "⏳ 미달"
    logger.info("{}: {}", status, readiness["message"])

    discord = Notifier(config)
    risk = config.risk_params
    readiness_cfg = risk.get("paper_backtest_compare", {}).get("live_readiness", {})
    if readiness["ready"] and readiness_cfg.get("notify_on_ready", True):
        discord.send_embed(
            "✅ 실전 전환 준비 완료",
            readiness["message"],
            color=0x2ECC71,
            fields=[
                {"name": "방향성 일치율", "value": f"{readiness['direction_agreement_pct']:.1f}%", "inline": True},
                {"name": "수익률 차이", "value": f"{readiness.get('return_diff_pct', 0):.1f}%", "inline": True},
                {"name": "거래일수", "value": f"{readiness['trading_days']}일", "inline": True},
            ],
        )


def run_emergency_liquidate(args):
    """긴급 전 종목 매도 (CLI: --mode liquidate). 블랙스완 감지 외에도 수동 개입이 필요할 때 즉시 전 종목 매도."""
    logger.info("=" * 50)
    logger.info("🚨 긴급 전 종목 매도 모드")
    logger.info("=" * 50)

    config = Config.get()
    mode = str(config.trading.get("mode", "paper")).lower()
    if mode == "live":
        _require_live_operator_confirmation(
            args,
            action_label="실전 긴급 청산",
            example="python main.py --mode liquidate --confirm-live",
        )
        _sync_live_positions_before_liquidation(config)

    from database.repositories import get_all_positions
    from core.order_executor import OrderExecutor

    positions = get_all_positions()  # 긴급 청산은 모든 계좌 포지션 대상
    summary = {
        "attempted": len(positions),
        "succeeded": 0,
        "failed": 0,
        "details": [],
    }
    if not positions:
        logger.info("보유 포지션이 없습니다.")
        _notify_emergency_liquidation_summary(config, mode, summary)
        return summary

    # 청산 시에는 계좌(전략)별로 executor 사용 (live 시 해당 계좌로 매도)
    account_executors = {}

    for pos in positions:
        try:
            ak = getattr(pos, "account_key", None) or ""
            if ak not in account_executors:
                account_executors[ak] = OrderExecutor(config, account_key=ak)
            executor = account_executors[ak]
            price = pos.avg_price
            if mode == "live":
                from api.kis_api import KISApi
                account_no = config.get_account_no(ak)
                kis = KISApi(account_no=account_no)
                price_info = kis.get_current_price(pos.symbol)
                try:
                    price = float((price_info or {}).get("price") or 0)
                except (TypeError, ValueError):
                    price = 0.0
                if price <= 0:
                    reason = "실전 긴급 청산 현재가 조회 실패"
                    summary["failed"] += 1
                    summary["details"].append({
                        "symbol": pos.symbol,
                        "account_key": ak,
                        "status": "failed",
                        "reason": reason,
                    })
                    logger.error(
                        "{}: {} — 평균단가 fallback 매도를 실행하지 않습니다.",
                        reason,
                        pos.symbol,
                    )
                    continue
            result = executor.execute_sell(
                pos.symbol,
                price,
                quantity=None,
                reason="긴급 전량 청산 (--mode liquidate)",
                strategy="emergency_liquidate",
            )
            if result.get("success"):
                summary["succeeded"] += 1
                summary["details"].append({
                    "symbol": pos.symbol,
                    "account_key": ak,
                    "status": "success",
                    "price": price,
                })
                logger.info("청산 완료: {} @ {:,.0f}원", pos.symbol, price)
            else:
                reason = result.get("reason", "")
                summary["failed"] += 1
                summary["details"].append({
                    "symbol": pos.symbol,
                    "account_key": ak,
                    "status": "failed",
                    "reason": reason,
                })
                logger.error("청산 실패 {}: {}", pos.symbol, reason)
        except Exception as e:
            symbol = getattr(pos, "symbol", "")
            summary["failed"] += 1
            summary["details"].append({
                "symbol": symbol,
                "account_key": getattr(pos, "account_key", "") or "",
                "status": "exception",
                "reason": str(e),
            })
            logger.exception("종목 {} 청산 중 오류: {}", symbol, e)

    logger.info(
        "긴급 청산 처리 완료 (대상 {}건, 성공 {}건, 실패 {}건)",
        summary["attempted"],
        summary["succeeded"],
        summary["failed"],
    )
    _notify_emergency_liquidation_summary(config, mode, summary)
    return summary


def _notify_emergency_liquidation_summary(config, mode: str, summary: dict) -> None:
    """긴급 청산 실행 결과를 통합 알림으로 전파한다."""
    attempted = int(summary.get("attempted") or 0)
    succeeded = int(summary.get("succeeded") or 0)
    failed = int(summary.get("failed") or 0)
    status = "실패 포함" if failed else "완료"
    lines = [
        f"긴급 청산 {status}",
        f"- mode: {mode}",
        f"- 대상: {attempted}건",
        f"- 성공: {succeeded}건",
        f"- 실패: {failed}건",
    ]
    failed_details = [
        d for d in (summary.get("details") or [])
        if d.get("status") in {"failed", "exception"}
    ][:5]
    for detail in failed_details:
        lines.append(
            "- 실패 상세: "
            f"{detail.get('symbol', '')} "
            f"({detail.get('reason', '')})"
        )
    try:
        from core.notifier import Notifier
        Notifier(config).send_message(
            "\n".join(lines),
            critical=(mode == "live" or attempted > 0 or failed > 0),
        )
    except Exception as exc:
        logger.error("긴급 청산 결과 알림 발송 실패: {}", exc)


def _live_liquidation_account_keys(config) -> list[str]:
    """긴급 청산 전 KIS 잔고 동기화가 필요한 계좌 키 목록."""
    kis = getattr(config, "kis_api", {}) or {}
    accounts = kis.get("accounts", {}) if isinstance(kis, dict) else {}
    keys: list[str] = []
    seen_accounts: set[str] = set()

    def add_key(account_key: str) -> None:
        account_key = str(account_key or "")
        get_account_no = getattr(config, "get_account_no", None)
        account_no = ""
        if callable(get_account_no):
            try:
                account_no = str(get_account_no(account_key) or "")
            except Exception:
                account_no = ""
        dedupe_key = account_no or account_key
        if dedupe_key in seen_accounts:
            return
        seen_accounts.add(dedupe_key)
        keys.append(account_key)

    add_key("")
    if isinstance(accounts, dict):
        for account_key in accounts:
            add_key(str(account_key))
    return keys


def _sync_live_positions_before_liquidation(config) -> list[dict]:
    """live 긴급 청산 전 KIS-only 포지션을 DB에 반영한다."""
    from core.portfolio_manager import PortfolioManager

    results: list[dict] = []
    failures: list[str] = []
    for account_key in _live_liquidation_account_keys(config):
        try:
            result = (
                PortfolioManager(config, account_key=account_key).sync_with_broker(auto_correct=True)
                or {}
            )
        except Exception as exc:
            logger.exception("긴급 청산 전 KIS↔DB 동기화 실패(account_key={}): {}", account_key, exc)
            failures.append(f"{account_key or '<default>'}: {exc}")
            continue

        corrected = result.get("corrected") or []
        mismatches = result.get("mismatches") or []
        ok = bool(result.get("ok"))
        results.append({
            "account_key": account_key,
            "ok": ok,
            "mismatches": mismatches,
            "corrected": corrected,
            "message": result.get("message", ""),
        })
        if ok:
            logger.info("긴급 청산 전 잔고 동기화 확인: account_key={}", account_key or "<default>")
        elif corrected and (not mismatches or len(corrected) >= len(mismatches)):
            logger.warning(
                "긴급 청산 전 잔고 동기화 보정 완료: account_key={} corrected={} message={}",
                account_key or "<default>",
                len(corrected),
                result.get("message", ""),
            )
        else:
            failures.append(
                f"{account_key or '<default>'}: {result.get('message', 'sync failed')}"
                f" (mismatches={len(mismatches)}, corrected={len(corrected)})"
            )

    if failures:
        logger.error(
            "긴급 청산 전 KIS↔DB 잔고 동기화가 완료되지 않아 live 청산을 시작하지 않습니다: {}",
            "; ".join(failures),
        )
        sys.exit(1)

    return results


def run_dashboard(args):
    """실시간 웹 대시보드 서버 실행 (포트폴리오·포지션·스냅샷 추이 표시)."""
    from monitoring.web_dashboard import run_web_dashboard

    logger.info("=" * 50)
    logger.info("📊 웹 대시보드 모드")
    logger.info("=" * 50)

    port = getattr(args, "dashboard_port", None)
    host = getattr(args, "dashboard_host", None)
    run_web_dashboard(host=host, port=port)


def _get_strategy(name: str):
    """전략 인스턴스 반환 (레지스트리 기반)"""
    from strategies import create_strategy
    return create_strategy(name)


def run_health_check() -> int:
    """운영 통합 헬스 점검 — 전 전략 runtime state + current_blockers를 한 번에 요약.

    tools/paper_runtime_status.py --health 와 동일한 로직. main.py 진입점에서도
    바로 쓸 수 있게 노출한다. 반환 코드: 0=OK, 1=ATTENTION, 2=BLOCKED.
    """
    import json
    from pathlib import Path
    from database.models import init_database
    from core.paper_runtime import get_paper_runtime_state
    from core.strategy_universe import get_paper_strategy_names
    from core.operator_health import build_operator_health

    init_database()
    strategies = sorted(get_paper_strategy_names() or [])
    states = []
    for strategy in strategies:
        try:
            states.append(get_paper_runtime_state(strategy))
        except Exception as exc:
            logger.warning("{} 상태 조회 실패: {}", strategy, exc)

    blockers = None
    blockers_path = Path(__file__).resolve().parent / "reports" / "current_blockers.json"
    if blockers_path.exists():
        try:
            blockers = json.loads(blockers_path.read_text(encoding="utf-8"))
        except Exception:
            blockers = None

    # 바스켓 paper 운영(트랙레코드) 상태 — 일일 사이클이 조용히 멈추면 여기서 드러난다.
    basket_operation = None
    try:
        from datetime import date
        from core.basket_rebalancer import BasketRebalancer
        from database.models import get_session, PortfolioSnapshot
        from database.repositories import get_all_positions

        from core.basket_rebalancer import rebalance_live_strategy_id

        config = Config.get()
        enabled_baskets = BasketRebalancer.get_enabled_baskets()
        baskets_cfg = BasketRebalancer._load_baskets_config()

        def _design_fraction(cfg: dict) -> float:
            """BasketRebalancer._stock_fraction과 동일 규칙(인스턴스 없이 계산)."""
            from core.basket_deploy import effective_stock_fraction
            return effective_stock_fraction(cfg, config.risk_params)

        # 바스켓별 전용 계정 키(basket_rebalance:<name>) 기준으로 조회한다.
        # 복수 바스켓이면 '가장 오래된 최신 스냅샷'을 기준으로(가장 뒤처진 사이클 감시).
        last_dates = []
        position_count = 0
        # 집계 배치율 미달 감시: 최신 스냅샷으로 실제 주식비중을 계산(네트워크 불필요),
        # 설계 대비 가장 크게 미달인 바스켓을 대표로 넘긴다(가장 뒤처진 배치 감시).
        worst_shortfall = None
        worst_dep_ratio = None
        worst_design = None
        worst_tolerance = 0.05
        session = get_session()
        try:
            for name in enabled_baskets:
                key = rebalance_live_strategy_id(name)
                snap = (
                    session.query(PortfolioSnapshot)
                    .filter(PortfolioSnapshot.account_key == key)
                    .order_by(PortfolioSnapshot.date.desc())
                    .first()
                )
                last_dates.append(snap.date if snap else None)
                positions_b = get_all_positions(account_key=key) or []
                position_count += len(positions_b)
                # 배치율은 부가 신호 — 계산 실패(예: baskets.yaml에 float 불가한
                # target_stock_weight 오타)가 핵심 신호인 결측/staleness 감지를
                # 통째로 삼키지 않도록 자체 try로 격리한다.
                # 허용 오차 = max(바스켓 설정값, 구조 하한 1주가/총액) — 적립 직후
                # '부족분 < 1주'로 매수가 보류되는 동안의 불가피한 미달(예: 잔고
                # 40만·ETF 12.8만 → 32%p)이 정상인데 매일 울리는 것을 방지. 잔고가
                # 크면 구조 하한이 저절로 조여져 설정값이 다시 지배한다.
                # '허용 초과분'이 가장 큰 바스켓을 고른다 — 원시 미달폭 최대로
                # 고르면 관찰용 트랙(허용 완화)이 진짜 감시 대상을 가린다.
                try:
                    if snap and snap.total_value and snap.total_value > 0:
                        from core.operator_health import structural_deployment_tolerance

                        cfg_b = baskets_cfg.get(name) or {}
                        dep_ratio = max(0.0, (snap.total_value - (snap.cash or 0)) / snap.total_value)
                        design = _design_fraction(cfg_b)
                        floor_tol = float(
                            (cfg_b.get("monitoring") or {}).get("deployment_tolerance", 0.05)
                        )
                        # 보유 슬롯별 1주 가격의 합 — 슬롯마다 '부족분 < 1주' 절사가
                        # 동시에 존재할 수 있으므로 최고가 1주만 재면 다중 슬롯 바스켓이
                        # 정상 적립 중에 거짓 ATTENTION을 울린다. 빈 슬롯은 실패이므로 제외.
                        truncation_unit = sum(
                            float(p.avg_price or 0) for p in positions_b
                        )
                        tol_b = structural_deployment_tolerance(
                            truncation_unit, float(snap.total_value), floor_tol,
                        )
                        violation = (design - dep_ratio) - tol_b
                        if worst_shortfall is None or violation > worst_shortfall:
                            worst_shortfall = violation
                            worst_dep_ratio = dep_ratio
                            worst_design = design
                            worst_tolerance = tol_b
                except Exception as dep_exc:
                    logger.debug("바스켓 '{}' 배치율 계산 생략: {}", name, dep_exc)
        finally:
            session.close()
        oldest_last = (
            None if (not last_dates or any(d is None for d in last_dates))
            else min(last_dates)
        )
        basket_operation = {
            "enabled_baskets": enabled_baskets,
            "last_snapshot_date": oldest_last,
            "position_count": position_count,
            "today": date.today(),
            "deployment_ratio": worst_dep_ratio,
            "design_fraction": worst_design,
            "deployment_tolerance": worst_tolerance,
        }
    except Exception as exc:
        logger.warning("바스켓 운영 상태 조회 실패: {}", exc)

    health = build_operator_health(states, blockers, basket_operation=basket_operation)
    icon = {"OK": "✅", "ATTENTION": "⚠️", "BLOCKED": "⛔"}.get(health["verdict"], "❓")
    logger.info("{} 운영 헬스: {} — {}", icon, health["verdict"], health["headline"])
    b = health["blockers"]
    logger.info(
        "go_live={} | hard_blockers={} | artifact_stale={}",
        b["go_live"], b["hard_blocker_count"], b["freshness_stale"],
    )
    for s in health["strategies"]:
        extra = f" ({', '.join(s['notes'])})" if s["notes"] else ""
        logger.info("  - {}: {}{}", s["strategy"], s["state"], extra)
    bk = health.get("basket")
    if bk is not None:
        logger.info(
            "  - basket[{}]: 스냅샷 {} | 포지션 {}개{}",
            ",".join(bk["enabled_baskets"]) or "없음",
            bk["last_snapshot_date"] or "없음",
            bk["position_count"],
            f" ({', '.join(bk['notes'])})" if bk["notes"] else "",
        )
    for item in health["attention_items"]:
        logger.info("  확인: {}", item)

    return {"OK": 0, "ATTENTION": 1, "BLOCKED": 2}.get(health["verdict"], 1)


def run_weekly_report() -> int:
    """주간 요약 리포트 — 판단 주기(주 1회) 다이제스트를 Discord로 발송.

    일일 숫자는 노이즈가 커서 매일 판단하기엔 부적합하다(P1-7). 주간 성과·귀속 분해
    (실행/구성 격차)·진행률·주간 이벤트를 한 장으로 모아 오너가 주 1회 이것만 봐도
    운영 판단이 되게 한다. 금요일 스케줄 작업에 추가해 쓴다. 반환: 0 정상.
    """
    from datetime import datetime, timedelta
    from zoneinfo import ZoneInfo
    from core.notifier import Notifier
    from core.basket_evaluation import collect_basket_paper_evaluation
    from core.weekly_report import build_weekly_summary
    from core.cycle_observability import detect_snapshot_gaps_for_account
    from core.basket_rebalancer import BasketRebalancer, rebalance_live_strategy_id
    from database.models import get_session, PortfolioSnapshot, OperationEvent, init_database

    init_database()
    config = Config.get()
    notifier = Notifier(config)
    now_kst = datetime.now(ZoneInfo("Asia/Seoul")).replace(tzinfo=None)

    def _d(v):
        return v.date() if hasattr(v, "date") and callable(getattr(v, "date")) else v

    names = BasketRebalancer.get_enabled_baskets()
    if not names:
        logger.warning("enabled 바스켓 없음 — 주간 리포트 생략")
        return 0

    for name in names:
        try:
            eval_result, basket_name = collect_basket_paper_evaluation(
                basket_name=name, include_attribution=True,
            )
            key = rebalance_live_strategy_id(name)
            session = get_session()
            try:
                snaps = (
                    session.query(PortfolioSnapshot)
                    .filter(PortfolioSnapshot.account_key == key)
                    .order_by(PortfolioSnapshot.date.asc())
                    .all()
                )
                since = now_kst - timedelta(days=7)
                cycle_errors = (
                    session.query(OperationEvent)
                    .filter(OperationEvent.strategy == key)
                    .filter(OperationEvent.event_type == "CYCLE_ERROR")
                    .filter(OperationEvent.created_at >= since)
                    .count()
                )
            finally:
                session.close()

            # 주간 NAV 변화: 마지막 스냅샷 vs '약 1주 전' 스냅샷.
            # 기준 스냅샷이 7일 전 근방(±3일 밴드) 안에 있을 때만 '주간'으로 표기한다 —
            # 스냅샷 공백으로 기준이 2~4주 전이면 다주간 수익을 주간으로 오표기하게 되므로
            # 그 경우 주간 항을 생략한다(누적은 유지). (적대적 리뷰 low)
            # 적립식 계정은 구간 입금을 분모에 더해 중화한다 — 입금 주에 '주간 +10%'
            # 같은 가짜 수익 방지(적대적 리뷰 medium).
            week_change = None
            if len(snaps) >= 2:
                last_val = float(snaps[-1].total_value)
                last_date = _d(snaps[-1].date)
                band = [
                    s for s in snaps
                    if last_date - timedelta(days=10) <= _d(s.date) <= last_date - timedelta(days=4)
                ]
                if band:
                    ref = band[-1]
                    ref_val = float(ref.total_value)
                    if ref_val > 0:
                        from core.portfolio_manager import twr_period_return
                        from database.repositories import get_cash_flow_total_between
                        flow = 0.0
                        try:
                            ref_boundary = ref.created_at or ref.date
                            last_boundary = snaps[-1].created_at or now_kst
                            flow = get_cash_flow_total_between(key, ref_boundary, last_boundary)
                        except Exception:
                            pass
                        week_change = twr_period_return(ref_val, last_val, flow) * 100

            # 결측은 '고유 일수'로 집계(SNAPSHOT_GAP 이벤트는 미복구 결측을 매 사이클
            # 재경보해 부풀려짐 → 최근 7일 실제 빠진 영업일 수를 직접 센다).
            try:
                missing_days = len(detect_snapshot_gaps_for_account(
                    config, key, now_kst, lookback_calendar_days=7,
                ))
            except Exception:
                missing_days = 0

            summary = build_weekly_summary(
                basket_name=basket_name, eval_result=eval_result,
                week_nav_change_pct=week_change,
                missing_days=missing_days, cycle_errors=cycle_errors,
            )
            logger.info("\n{}", summary["text"])
            try:
                notifier.send_embed(summary["title"], "", fields=summary["fields"])
            except Exception as e:
                logger.debug("주간 리포트 발송 실패(무시): {}", e)
        except Exception as exc:
            logger.warning("바스켓 '{}' 주간 리포트 생성 실패: {}", name, exc)

    return 0


def _build_cli_guide(args) -> str:
    """인자 없이 실행하거나 --mode guide 일 때 보여줄 사용 가이드.

    --strategy / --symbol 값을 예시 명령에 반영해 바로 복사해 쓸 수 있게 한다.
    시스템(로거·DB)을 초기화하지 않고 stdout으로만 출력한다.
    """
    strategy = getattr(args, "strategy", "scoring") or "scoring"
    symbol = getattr(args, "symbol", "005930") or "005930"
    lines = [
        "=" * 60,
        "  📖 QUANT TRADER 실행 가이드",
        "=" * 60,
        "",
        "  인자 없이 실행하면 이 가이드가 표시됩니다(매매·백테스트 미실행).",
        "  실제 동작은 아래처럼 --mode 를 명시하세요.",
        "",
        "  [분석·검증]",
        f"  python main.py --mode backtest --strategy {strategy} --symbol {symbol}",
        "      과거 데이터로 단일 종목 전략 백테스트 (strict-lookahead 기본).",
        f"  python main.py --mode validate --strategy {strategy} --validation-years 5",
        "      3~5년·in/out-of-sample·벤치마크 대비 전략 유효성 검증.",
        f"  python main.py --mode portfolio_backtest --strategy {strategy} --symbols 005930,000660,035720",
        "      멀티 종목 포트폴리오 백테스트.",
        "  python main.py --mode backtest_momentum_top --top-n 5 --market-filter",
        "      모멘텀 상위 동일비중 포트폴리오 백테스트.",
        f"  python main.py --mode optimize --strategy {strategy} --include-weights",
        "      파라미터 최적화 (OOS 게이트, 오버피팅 주의).",
        f"  python main.py --mode compare --strategy {strategy} --start 2025-01-01 --end 2025-03-18",
        "      모의투자 vs 백테스트 비교 + 실전 전환 준비 평가.",
        "",
        "  [모의·운영]",
        f"  python main.py --mode paper --strategy {strategy}",
        "      워치리스트 1회 순회 모의매매 (DB 기록만, 실주문 없음).",
        f"  python main.py --mode schedule --strategy {strategy}",
        "      모의 스케줄 무한 루프 (서버 상시 구동).",
        "  python main.py --mode rebalance --basket <이름> --dry-run",
        "      바스켓 목표 비중 리밸런싱 계획 출력.",
        "  python main.py --mode dashboard",
        "      실시간 웹 대시보드 (기본 http://127.0.0.1:8080).",
        "  python main.py --mode health",
        "      전 전략 운영 헬스·blocker 점검 (배치율 미달·스냅샷 끊김 포함).",
        "  python main.py --mode deploy_check --basket <이름>",
        "      바스켓 배포 점검 (계획 주문·예상 비용·활성화 절차).",
        "  python main.py --mode weekly_report",
        "      주간 요약 디스코드 발송 (성과·귀속 분해·진행률·주간 이벤트).",
        "",
        "  [실전 — 신중히]",
        f"  python main.py --mode live --strategy {strategy} --confirm-live",
        "      실전 매매 (ENABLE_LIVE_TRADING=true + hard gate 필요).",
        "  python main.py --mode liquidate --confirm-live",
        "      긴급 전 종목 매도.",
        "",
        "  [유지보수]",
        "  python main.py --update-holidays      휴장일 파일 자동 갱신",
        "  python main.py --mode guide            이 가이드 다시 보기",
        "  python main.py --help                  전체 옵션 도움말",
        "",
        "=" * 60,
    ]
    return "\n".join(lines)


def main():
    """메인 진입점"""
    parser = argparse.ArgumentParser(
        description="퀀트 트레이더 - 자동 주식 매매 시스템",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
예시:
  python main.py --mode backtest --strategy scoring --symbol 005930
  python main.py --mode backtest --strategy mean_reversion --symbol 000660 --start 2023-01-01
  python main.py --mode backtest --strategy scoring --symbol 005930
  python main.py --mode backtest --strategy scoring --symbol 005930 --allow-lookahead  # 위험: 미래 데이터 혼입 허용
  python main.py --mode validate --strategy scoring --symbol 005930 --validation-years 5
  python main.py --mode paper --strategy scoring
  python main.py --mode schedule --strategy scoring  # 모의 스케줄 무한 루프 (서버 상시 구동)
  python main.py --mode live --strategy scoring --confirm-live  # 실전 (ENABLE_LIVE_TRADING=true 필요)
  python main.py --mode liquidate --confirm-live  # 긴급 전 종목 매도 (live 설정에서는 ENABLE_LIVE_TRADING=true 필요)
  python main.py --mode compare --start 2025-01-01 --end 2025-03-18 --strategy scoring  # 모의투자 vs 백테스트 비교
  python main.py --update-holidays  # 휴장일 파일(pykrx+fallback) 자동 갱신
  python main.py --mode optimize --strategy scoring  # 임계값만 Grid Search (오버피팅 주의)
  python main.py --mode optimize --strategy scoring --include-weights  # 가중치+임계값 동시 최적화 (OOS 샤프≥1.0 게이트)
  python main.py --mode optimize --strategy scoring --include-weights --auto-correlation  # 상관분석+비활성화+최적화 원스텝
  python main.py --mode optimize --strategy scoring --include-weights --disable-weights w_rsi,w_ma  # 수동으로 RSI·MA 제외
  python main.py --mode optimize --strategy scoring --optimizer bayesian  # Bayesian 최적화 (scikit-optimize)
  python main.py --mode dashboard  # 실시간 웹 대시보드 (기본 http://127.0.0.1:8080)
        """,
    )

    parser.add_argument(
        "--optimizer", type=str, default="grid", choices=["grid", "bayesian"],
        help="[optimize 모드] grid 또는 bayesian (bayesian 시 pip install scikit-optimize)",
    )
    parser.add_argument(
        "--optimize-metric", type=str, default="sharpe_ratio",
        help="[optimize 모드] 최대화할 지표 (sharpe_ratio, total_return, calmar_ratio 등)",
    )
    parser.add_argument(
        "--train-ratio", type=float, default=0.7,
        help="[optimize 모드] 학습 구간 비율 (0~1). 나머지는 OOS 검증용",
    )
    parser.add_argument(
        "--optimize-calls", type=int, default=30,
        help="[optimize 모드, bayesian] 목적 함수 호출 횟수",
    )
    parser.add_argument(
        "--include-weights", action="store_true",
        help="[optimize 모드, scoring] 스코어링 가중치(weights)도 탐색 (대칭 Grid + OOS 샤프 게이트)",
    )
    parser.add_argument(
        "--disable-weights", type=str, default="",
        help="[optimize 모드, --include-weights] 탐색에서 0으로 고정할 가중치 키 (쉼표 구분, 예: w_rsi,w_ma)",
    )
    parser.add_argument(
        "--auto-correlation", action="store_true",
        help="[optimize 모드, --include-weights] 최적화 전 상관 분석 자동 실행, 고상관 지표 자동 비활성화 후 최적화. "
        "check_correlation + optimize를 한 번에 수행.",
    )
    parser.add_argument(
        "--update-holidays",
        action="store_true",
        help="config/holidays.yaml을 pykrx(또는 fallback)로 자동 갱신 후 종료",
    )
    parser.add_argument(
        "--mode", type=str, default="backtest",
        choices=[
            "backtest",
            "backtest_momentum_top",
            "portfolio_backtest",
            "validate",
            "paper",
            "schedule",
            "live",
            "liquidate",
            "compare",
            "optimize",
            "dashboard",
            "check_correlation",
            "check_ensemble_correlation",
            "rebalance",
            "health",
            "deploy_check",
            "weekly_report",
            "guide",
        ],
        help="실행 모드. backtest_momentum_top: 모멘텀 상위 동일비중 멀티종목. portfolio_backtest: 멀티종목 포트폴리오 백테스트. paper: 워치리스트 1회. schedule: 모의 스케줄 무한 루프(상시 서버). rebalance: 바스켓 리밸런싱. health: 운영 통합 헬스 점검(전 전략 runtime + blockers). deploy_check: 바스켓 배포 점검(계획·비용·활성화 절차). weekly_report: 주간 요약 디스코드 발송(성과·귀속 분해·진행률·이벤트).",
    )
    from strategies import get_strategy_names
    parser.add_argument(
        "--strategy", type=str, default="scoring",
        choices=get_strategy_names(),
        help="매매 전략 (기본: scoring)",
    )
    parser.add_argument(
        "--symbol", type=str, default="005930",
        help="종목 코드 (기본: 005930 삼성전자)",
    )
    parser.add_argument(
        "--start", type=str, default=None,
        help="시작일 (YYYY-MM-DD)",
    )
    parser.add_argument(
        "--end", type=str, default=None,
        help="종료일 (YYYY-MM-DD)",
    )
    parser.add_argument(
        "--allow-lookahead", action="store_true",
        help="[위험] Look-Ahead Bias 방지(strict-lookahead)를 해제합니다. 기본값은 strict-lookahead=True이며, 이 옵션 사용 시에만 해제됩니다. 수익률 과대평가·실전 손실 위험.",
    )
    parser.add_argument(
        "--confirm-live", action="store_true",
        help="실전 모드 진입 시 필수. 미지정 시 live 모드 진입 거부.",
    )
    # --force-live 제거됨 (감사 C-1 대응): hard gate는 우회 불가
    parser.add_argument(
        "--output-dir", type=str, default="reports",
        help="백테스트 리포트 저장 디렉토리 (기본: reports)",
    )
    parser.add_argument(
        "--benchmark-symbol", type=str, default="KS11",
        help="전략 검증 벤치마크 종목/지수 코드 (기본: KS11, 코스피 지수)",
    )
    parser.add_argument(
        "--validation-years", type=int, default=5,
        help="전략 검증 시 조회 연수. 최소 3년 권장, 기본 5년 (오버피팅 방지·통계적 신뢰)",
    )
    parser.add_argument(
        "--split-ratio", type=float, default=0.7,
        help="전략 검증 시 in-sample 비율 (기본: 0.7). out-of-sample과 분리해 오버피팅 검증",
    )
    parser.add_argument(
        "--min-sharpe", type=float, default=1.0,
        help="전략 검증 통과 기준: 샤프 비율 최소값 (기본: 1.0). 미달 시 실전 투입 비권장",
    )
    parser.add_argument(
        "--max-mdd", type=float, default=-20.0,
        help="전략 검증 최대 허용 MDD(%%, 음수값, 기본: -20)",
    )
    parser.add_argument(
        "--walk-forward", action="store_true",
        help="[validate 모드] 슬라이딩 윈도우 워크포워드 검증 (train 2년→test 1년, 1년 스텝 반복). 미지정 시 1회 train/test 분할",
    )
    parser.add_argument(
        "--no-benchmark-top50", action="store_true",
        help="[validate 모드] 코스피 상위 50종목 동일비중 벤치마크 비활성화 (기본: 사용)",
    )
    parser.add_argument(
        "--compare-symbol", type=str, default=None,
        help="[compare 모드] 백테스트 대상 종목. 미지정 시 기간 내 모의투자 거래 최다 종목 사용",
    )
    parser.add_argument(
        "--dashboard-port", type=int, default=None,
        help="[dashboard 모드] 웹 대시보드 포트 (기본: config dashboard.port 또는 8080)",
    )
    parser.add_argument(
        "--dashboard-host", default=None,
        help="[dashboard 모드] 웹 대시보드 바인드 주소 (기본: config dashboard.host 또는 127.0.0.1)",
    )
    parser.add_argument(
        "--correlation-threshold", type=float, default=0.7,
        help="[check_correlation 모드] 고상관 판단 기준 (기본: 0.7). 이 값 이상이면 제거/가중치 축소 권고",
    )
    parser.add_argument(
        "--ensemble-correlation-threshold", type=float, default=0.6,
        help="[check_ensemble_correlation 모드] 앙상블 신호 고상관 기준 (기본: 0.6). 이 값 이상이면 conservative 또는 전략 재구성 권고",
    )
    parser.add_argument(
        "--basket", type=str, default=None,
        help="[rebalance 모드] 리밸런싱 대상 바스켓 이름 (미지정 시 enabled=true인 모든 바스켓)",
    )
    parser.add_argument(
        "--dry-run", action="store_true",
        help="[rebalance 모드] 실제 주문 없이 계획만 출력",
    )
    parser.add_argument(
        "--force-rebalance", action="store_true",
        help="[rebalance 모드] 1일 1매매 패스 가드 우회 — 같은 날 이미 체결이 있어도 매매 재실행 (운영자 명시 결정)",
    )
    parser.add_argument(
        "--as-of", type=str, default=None,
        help="[deploy_check 모드] 가격 기준일(YYYY-MM-DD). 미지정 시 오늘",
    )
    parser.add_argument(
        "--json", action="store_true",
        help="[deploy_check 모드] 결과를 JSON으로 출력",
    )
    parser.add_argument(
        "--rebalance-days", type=int, default=20,
        help="[backtest_momentum_top] 거래일 기준 리밸런싱 간격 (기본 20)",
    )
    parser.add_argument(
        "--initial-capital", type=float, default=None,
        help="[backtest_momentum_top] 초기 자본(원). 미지정 시 risk_params.initial_capital",
    )
    parser.add_argument(
        "--top-n", type=int, default=None,
        help="[backtest_momentum_top] 모멘텀 상위 보유 종목 수(미지정 시 config watchlist.top_n)",
    )
    parser.add_argument(
        "--market-filter",
        action="store_true",
        help="[backtest_momentum_top] KS11 20거래일 수익률 국면 필터(≤-5%% 신규매수 금지, ≤-10%% 전량 현금)",
    )
    parser.add_argument(
        "--cash-buffer", type=float, default=0.0,
        help="[backtest_momentum_top] 항상 현금으로 남길 비율(0~1, 예: 0.3이면 70%%만 주식 매수). 기본 0",
    )
    parser.add_argument(
        "--portfolio-stop", type=float, default=0.0,
        help="[backtest_momentum_top] 고점 대비 NAV 하락 시 전량 매도(0~1, 예: 0.15=-15%%). 기본 0=비활성",
    )
    parser.add_argument(
        "--stop-cooldown", type=int, default=0,
        help="[backtest_momentum_top] 포트폴리오 손절 후 N거래일 뒤 재진입(0=다음 리밸런스까지 대기). 기본 0",
    )
    parser.add_argument(
        "--symbols", type=str, default="",
        help="[portfolio_backtest 모드] 종목 코드 쉼표 구분 (예: 005930,000660,035720,051910,006400)",
    )

    args = parser.parse_args()
    # Look-Ahead Bias 방지: 기본값 True. --allow-lookahead 사용 시에만 False(해제 시 명시적 경고 출력)
    args.strict_lookahead = True
    if args.allow_lookahead:
        args.strict_lookahead = False

    # 인자 없이 실행(`python main.py`)하거나 `--mode guide` → 사용 가이드만 출력 후 종료.
    # 시스템(로거·DB)을 초기화하지 않고, 매매/백테스트도 실행하지 않는다.
    if len(sys.argv) == 1 or args.mode == "guide":
        print(_build_cli_guide(args))
        return

    # 휴장일 파일만 갱신 후 종료
    if getattr(args, "update_holidays", False):
        setup_logger()
        from core.holidays_updater import update_holidays_yaml
        update_holidays_yaml()
        logger.info("휴장일 파일 갱신 완료. config/holidays.yaml 확인.")
        return

    # 시스템 초기화
    setup_logger()
    init_database()

    logger.info("🚀 퀀트 트레이더 시작 (모드: {}, 전략: {})", args.mode, args.strategy)

    try:
        if args.mode == "backtest":
            run_backtest(args)
        elif args.mode == "backtest_momentum_top":
            run_backtest_momentum_top(args)
        elif args.mode == "portfolio_backtest":
            run_portfolio_backtest(args)
        elif args.mode == "validate":
            run_strategy_validation(args)
        elif args.mode == "paper":
            run_paper_trading(args)
        elif args.mode == "schedule":
            run_scheduler_loop(args)
        elif args.mode == "live":
            run_live_trading(args)
        elif args.mode == "liquidate":
            run_emergency_liquidate(args)
        elif args.mode == "compare":
            run_compare_paper_backtest(args)
        elif args.mode == "optimize":
            run_param_optimize(args)
        elif args.mode == "dashboard":
            run_dashboard(args)
        elif args.mode == "check_correlation":
            run_check_indicator_correlation(args)
        elif args.mode == "check_ensemble_correlation":
            run_check_ensemble_correlation(args)
        elif args.mode == "rebalance":
            run_rebalance(args)
        elif args.mode == "health":
            raise SystemExit(run_health_check())
        elif args.mode == "deploy_check":
            raise SystemExit(run_deploy_check(args))
        elif args.mode == "weekly_report":
            raise SystemExit(run_weekly_report())
        else:
            logger.error("알 수 없는 모드: {}", args.mode)
    except KeyboardInterrupt:
        logger.info("사용자에 의해 중단됨")
        raise SystemExit(130)
    except Exception as e:
        logger.exception("시스템 오류 발생: {}", e)
        raise SystemExit(1)
    finally:
        logger.info("퀀트 트레이더 종료")


if __name__ == "__main__":
    main()