WLD DeepCoin 단계별 구조 재편 및 설정·문서 통합

로고스/루트 레거시를 제거하고 deepcoin 패키지·scripts 01~05 CLI·docs/reference로
데이터·GT·분석·매칭·운영 단계를 정리했다. config와 .env 기반 설정, trade_anaysis.html 동기화 포함.

Co-authored-by: Cursor <cursoragent@cursor.com>

deepcoin/ops/monitor.py

@@ -0,0 +1,527 @@
+import pandas as pd
+from deepcoin.api.bithumb import HTS
+from dateutil.relativedelta import relativedelta
+from datetime import datetime
+import sqlite3
+import time
+
+try:
+    import telegram
+except ImportError:
+    telegram = None  # type: ignore
+import requests
+import json
+import asyncio
+from multiprocessing import Pool
+import numpy as np
+import os
+
+from config import *
+
+class Monitor(HTS):
+    """WLD 코인 데이터·지표·시장 상태 출력."""
+
+    last_signal = None
+    cooldown_file = None
+
+    def __init__(self, cooldown_file: str | None = None) -> None:
+        HTS.__init__(self)
+        # 최근 매수 신호 저장용(파일은 [신규] 포맷으로 저장)
+        self.last_signal: dict[str, str] = {}
+        if cooldown_file is not None:
+            self.cooldown_file = cooldown_file
+            self.buy_cooldown = self._load_buy_cooldown()
+        else:
+            self.cooldown_file = None
+            self.buy_cooldown = {}
+
+    # ------------- Persistence -------------
+    def _load_buy_cooldown(self) -> dict:
+        """load trade record file into nested dict {symbol:{'buy':{'datetime':dt,'signal':s},'sell':{...}}}"""
+        if not os.path.exists(self.cooldown_file):
+            return {}
+
+        try:
+            with open(self.cooldown_file, 'r', encoding='utf-8') as f:
+                raw = json.load(f)
+        except Exception as e:
+            print(f"Error loading cooldown data: {e}")
+            return {}
+
+        record: dict[str, dict] = {}
+        for symbol, value in raw.items():
+            # 신규 포맷: value has 'buy'/'sell'
+            if isinstance(value, dict) and ('buy' in value or 'sell' in value):
+                record[symbol] = {}
+                for side in ['buy', 'sell']:
+                    side_val = value.get(side)
+                    if isinstance(side_val, dict):
+                        dt_iso = side_val.get('datetime')
+                        sig = side_val.get('signal', '')
+                        if dt_iso:
+                            try:
+                                dt_obj = datetime.fromisoformat(dt_iso)
+                            except Exception:
+                                dt_obj = None
+                        else:
+                            dt_obj = None
+                        record[symbol][side] = {'datetime': dt_obj, 'signal': sig}
+            else:
+                # 구 포맷 처리 (매수만 기록)
+                try:
+                    dt_obj = None
+                    sig = ''
+                    if isinstance(value, str):
+                        dt_obj = datetime.fromisoformat(value)
+                    elif isinstance(value, dict):
+                        dt_iso = value.get('datetime')
+                        sig = value.get('signal', '')
+                        if dt_iso:
+                            dt_obj = datetime.fromisoformat(dt_iso)
+                    record.setdefault(symbol, {})['buy'] = {'datetime': dt_obj, 'signal': sig}
+                except Exception:
+                    continue
+
+        # last_signal 채우기 (buy 기준)
+        for sym, sides in record.items():
+            if 'buy' in sides and sides['buy'].get('signal'):
+                self.last_signal[sym] = sides['buy']['signal']
+        return record
+
+    def _save_buy_cooldown(self) -> None:
+        """save nested trade record structure"""
+        try:
+            data: dict[str, dict] = {}
+            for symbol, sides in self.buy_cooldown.items():
+                data[symbol] = {}
+                for side in ['buy', 'sell']:
+                    info = sides.get(side)
+                    if not info:
+                        continue
+                    dt_obj = info.get('datetime')
+                    sig = info.get('signal', '')
+                    data[symbol][side] = {
+                        'datetime': dt_obj.isoformat() if isinstance(dt_obj, datetime) else '',
+                        'signal': sig,
+                    }
+            with open(self.cooldown_file, 'w', encoding='utf-8') as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+        except Exception as e:
+            print(f"Error saving cooldown data: {e}")
+
+    # ------------- Telegram -------------
+    def _send_coin_msg(self, text: str) -> None:
+        if telegram is None:
+            print(f"[telegram skip] {text}")
+            return
+        coin_client = telegram.Bot(token=COIN_TELEGRAM_BOT_TOKEN)
+        asyncio.run(coin_client.send_message(chat_id=COIN_TELEGRAM_CHAT_ID, text=text))
+
+    def sendMsg(self, msg):
+        try:
+            pool = Pool(12)
+            pool.map(self._send_coin_msg, [msg])
+        except Exception as e:
+            print(f"Error sending Telegram message: {str(e)}")
+        return
+
+    def send_coin_telegram_message(self, message_list: list[str], header: str) -> None:
+        payload = header + "\n"
+        for i, message in enumerate(message_list):
+            payload += message
+            if i + 1 % MONITOR_TELEGRAM_BATCH_SIZE == 0:
+                pool = Pool(MONITOR_POOL_WORKERS)
+                pool.map(self._send_coin_msg, [payload])
+                payload = ''
+        if len(message_list) % MONITOR_TELEGRAM_BATCH_SIZE != 0:
+            pool = Pool(MONITOR_POOL_WORKERS)
+            pool.map(self._send_coin_msg, [payload])
+
+    # ------------- Indicators -------------
+    def normalize_data(self, data: pd.DataFrame) -> pd.DataFrame:
+        columns_to_normalize = ['Open', 'High', 'Low', 'Close', 'Volume']
+        normalized_data = data.copy()
+        for column in columns_to_normalize:
+            min_val = data[column].rolling(window=MONITOR_NORM_WINDOW).min()
+            max_val = data[column].rolling(window=MONITOR_NORM_WINDOW).max()
+            denominator = max_val - min_val
+            normalized_data[f'{column}_Norm'] = np.where(
+                denominator != 0,
+                (data[column] - min_val) / denominator,
+                0.5,
+            )
+        return normalized_data
+
+    def inverse_data(self, data: pd.DataFrame) -> pd.DataFrame:
+        """원본 data 가격 시계를 상하 대칭(글로벌 min/max 기준)으로 반전하여 하락↔상승 트렌드를 뒤집는다."""
+        price_cols = ['Open', 'High', 'Low', 'Close']
+        inv = data.copy()
+        global_min = data[price_cols].min().min()
+        global_max = data[price_cols].max().max()
+        # 축 기준은 global_mid = (max+min), so transformed = max+min - price
+        for col in price_cols:
+            inv[col] = global_max + global_min - data[col]
+        # Volume은 그대로 유지
+        inv['Volume'] = data['Volume']
+        # 지표 다시 계산
+        inv = self.normalize_data(inv)
+
+        for w in MONITOR_MA_WINDOWS:
+            inv[f"MA{w}"] = inv["Close"].rolling(window=w).mean()
+            inv[f"Deviation{w}"] = (inv["Close"] / inv[f"MA{w}"]) * 100
+        if len(MONITOR_MA_WINDOWS) >= 2:
+            w_fast, w_slow = MONITOR_MA_WINDOWS[0], MONITOR_MA_WINDOWS[1]
+            inv["golden_cross"] = (inv[f"MA{w_fast}"] > inv[f"MA{w_slow}"]) & (
+                inv[f"MA{w_fast}"].shift(1) <= inv[f"MA{w_slow}"].shift(1)
+            )
+        inv["MA"] = inv["Close"].rolling(window=BB_PERIOD).mean()
+        inv["STD"] = inv["Close"].rolling(window=BB_PERIOD).std()
+        inv["Upper"] = inv["MA"] + (BB_STD * inv["STD"])
+        inv["Lower"] = inv["MA"] - (BB_STD * inv["STD"])
+        return inv
+
+    def calculate_technical_indicators(self, data: pd.DataFrame) -> pd.DataFrame:
+        data = self.normalize_data(data)
+
+        for w in MONITOR_MA_WINDOWS:
+            data[f"MA{w}"] = data["Close"].rolling(window=w).mean()
+            data[f"Deviation{w}"] = (data["Close"] / data[f"MA{w}"]) * 100
+        if len(MONITOR_MA_WINDOWS) >= 2:
+            w_fast, w_slow = MONITOR_MA_WINDOWS[0], MONITOR_MA_WINDOWS[1]
+            data["golden_cross"] = (data[f"MA{w_fast}"] > data[f"MA{w_slow}"]) & (
+                data[f"MA{w_fast}"].shift(1) <= data[f"MA{w_slow}"].shift(1)
+            )
+        data["MA"] = data["Close"].rolling(window=BB_PERIOD).mean()
+        data["STD"] = data["Close"].rolling(window=BB_PERIOD).std()
+        data["Upper"] = data["MA"] + (BB_STD * data["STD"])
+        data["Lower"] = data["MA"] - (BB_STD * data["STD"])
+
+        from deepcoin.common.indicators import add_macd, add_stochastic
+
+        data = add_macd(data)
+        data = add_stochastic(data)
+        return data
+
+    def process_wld_market_status(self, symbol: str) -> None:
+        """
+        WLD: 전 봉 BB·일목 위치·추세만 출력 (자동 매매 없음).
+        """
+        from deepcoin.common.candle_features import describe_latest_position
+        from deepcoin.common.indicators import get_trend
+        from deepcoin.data.mtf_bb import load_frames_from_db
+
+        try:
+            frames = load_frames_from_db(self, symbol)
+            if not frames:
+                print(f"Data for {symbol}: 로드된 봉 없음.")
+                return
+
+            df_1d = frames.get(TREND_INTERVAL_1D)
+            df_1h = frames.get(TREND_INTERVAL_1H)
+            if df_1d is None or df_1d.empty:
+                df_1d = frames.get(ENTRY_INTERVAL)
+            if df_1h is None or df_1h.empty:
+                df_1h = frames.get(ENTRY_INTERVAL)
+
+            trend = get_trend(df_1d, df_1h)
+            print(f"{symbol} 추세(참고): {trend}")
+            print("--- 봉별 BB·일목 위치 ---")
+            for iv in sorted(frames.keys()):
+                pos = describe_latest_position(frames[iv], iv)
+                macd_s = ""
+                if pos.get("macd_hist") is not None:
+                    macd_s = f" | MACD {pos.get('macd_state', '-')} h={pos['macd_hist']}"
+                stoch_s = ""
+                if pos.get("stoch_k") is not None:
+                    stoch_s = (
+                        f" | Stoch K={pos['stoch_k']} D={pos.get('stoch_d')} "
+                        f"{pos.get('stoch_zone', '')}"
+                    )
+                disp_s = ""
+                if pos.get("disparity"):
+                    parts = [f"{p}={v:.1f}" for p, v in sorted(pos["disparity"].items())]
+                    disp_s = " | D.I. " + " ".join(parts)
+                print(
+                    f"  {pos['label']:>6} | BB {pos['bb_zone']} {pos['bb_state']:>16} | "
+                    f"일목 {pos['ichi_position']} TK={pos['ichi_tk']}"
+                    f"{macd_s}{stoch_s}{disp_s}"
+                )
+        except Exception as e:
+            print(f"Error processing {symbol}: {str(e)}")
+
+    def process_symbol(
+        self,
+        symbol: str,
+        interval: int | None = None,
+        balances: dict | None = None,
+        use_inverse: bool = False,
+    ) -> None:
+        """하위 호환: 시장 상태 출력으로 위임."""
+        self.process_wld_market_status(symbol)
+
+    def load_balances_dict(self) -> dict:
+        """getBalances() 결과를 currency 키 dict로 변환."""
+        tmps = self.getBalances()
+        balances = {}
+        for tmp in tmps:
+            balances[tmp["currency"]] = {
+                "balance": float(tmp["balance"]),
+                "avg_buy_price": float(tmp["avg_buy_price"]),
+            }
+        return balances
+
+    # ------------- Formatting -------------
+    def format_message(
+        self, symbol: str, symbol_name: str, close: float, signal: str, buy_amount: float
+    ) -> str:
+        message = f"[매수] {symbol_name} ({symbol}) [{signal}]: "
+
+        if int(close) >= 100:
+            message += f"₩{close}"
+            message += f" (₩{buy_amount})"
+        elif int(close) >= 10:
+            message += f"₩{close:.2f}"
+            message += f" (₩{buy_amount:.2f})"
+        elif int(close) >= 1:
+            message += f"₩{close:.3f}"
+            message += f" (₩{buy_amount:.3f})"
+        else:
+            message += f"₩{close:.4f}"
+            message += f" (₩{buy_amount:.4f})"
+
+        if signal != '':
+            message += f"[{signal}]"
+        return message
+
+    # ------------- Data fetch -------------
+    def get_coin_data(
+        self,
+        symbol: str,
+        interval: int = MONITOR_DEFAULT_INTERVAL,
+        to: str | None = None,
+        retries: int = MONITOR_API_RETRIES,
+    ) -> pd.DataFrame | None:
+        base = BITHUMB_API_URL.rstrip("/")
+        count = BITHUMB_API_CANDLE_COUNT
+        for attempt in range(retries):
+            try:
+                if to is None:
+                    if interval >= DAILY_INTERVAL_MIN:
+                        url = f"{base}/v1/candles/days?market=KRW-{symbol}&count={count}"
+                    else:
+                        url = (
+                            f"{base}/v1/candles/minutes/{interval}"
+                            f"?market=KRW-{symbol}&count={count}"
+                        )
+                else:
+                    if interval >= DAILY_INTERVAL_MIN:
+                        url = (
+                            f"{base}/v1/candles/days?market=KRW-{symbol}"
+                            f"&count={count}&to={to}"
+                        )
+                    else:
+                        url = (
+                            f"{base}/v1/candles/minutes/{interval}"
+                            f"?market=KRW-{symbol}&count={count}&to={to}"
+                        )
+                headers = {"accept": "application/json"}
+                response = requests.get(url, headers=headers)
+                json_data = json.loads(response.text)
+                df_temp = pd.DataFrame(json_data)
+                df_temp = df_temp.sort_index(ascending=False)
+                if 'candle_date_time_kst' not in df_temp:
+                    return None
+                data = pd.DataFrame()
+                data['datetime'] = pd.to_datetime(df_temp['candle_date_time_kst'], format='%Y-%m-%dT%H:%M:%S')
+                data['Open'] = df_temp['opening_price']
+                data['Close'] = df_temp['trade_price']
+                data['High'] = df_temp['high_price']
+                data['Low'] = df_temp['low_price']
+                data['Volume'] = df_temp['candle_acc_trade_volume']
+                data = data.set_index('datetime')
+                data = data.astype(float)
+                data["datetime"] = data.index
+                if not data.empty:
+                    return data
+                print(f"No data received for {symbol}, attempt {attempt + 1}")
+                time.sleep(MONITOR_SLEEP_AFTER_REQUEST_SEC)
+            except Exception as e:
+                print(f"Attempt {attempt + 1} failed for {symbol}: {str(e)}")
+                if attempt < retries - 1:
+                    time.sleep(MONITOR_SLEEP_RATE_LIMIT_SEC)
+                continue
+        return None
+
+    def get_coin_more_data(
+        self,
+        symbol: str,
+        interval: int,
+        bong_count: int = MONITOR_API_BONG_COUNT,
+        verbose: bool = False,
+    ) -> pd.DataFrame:
+        """
+        빗썸 API를 반복 호출해 bong_count개까지 과거 봉을 수집합니다.
+
+        Args:
+            verbose: True면 수집 진행 상황을 출력합니다.
+        """
+        to = datetime.now()
+        data: pd.DataFrame | None = None
+        step = 0
+        while data is None or len(data) < bong_count:
+            step += 1
+            if data is None:
+                chunk = self.get_coin_data(symbol, interval, to.strftime("%Y-%m-%d %H:%M:%S"))
+                data = chunk
+            else:
+                previous_count = len(data)
+                df = self.get_coin_data(symbol, interval, to.strftime("%Y-%m-%d %H:%M:%S"))
+                if df is not None and not df.empty:
+                    data = pd.concat([data, df], ignore_index=True)
+                if df is None or df.empty or previous_count == len(data):
+                    if verbose:
+                        print(f"    API 추가 데이터 없음 (수집 {len(data)}봉)")
+                    break
+            if verbose and (step == 1 or step % 5 == 0 or len(data) >= bong_count):
+                label = "일봉" if interval >= 1440 else f"{interval}분"
+                print(f"    [{label}] 요청 {step}회 — 누적 {len(data)}/{bong_count}봉")
+            time.sleep(MONITOR_SLEEP_BETWEEN_CHUNKS_SEC)
+            to = to - relativedelta(minutes=interval * MONITOR_API_CHUNK_BARS)
+        if data is None or data.empty:
+            return pd.DataFrame()
+        data = data.set_index("datetime")
+        data = data.sort_index()
+        data = data.drop_duplicates(keep="first")
+        data["datetime"] = data.index
+        return data
+
+    @staticmethod
+    def db_row_limit_for_interval(interval: int, lookback_days: int) -> int:
+        """
+        lookback_days 구간 + 지표 워밍업을 담을 SQLite LIMIT(봉 개수)을 계산합니다.
+
+        Args:
+            interval: 봉 간격(분). 1440이면 일봉.
+            lookback_days: 과거 조회 일수.
+
+        Returns:
+            LIMIT에 넣을 최대 행 수.
+        """
+        if interval >= DAILY_INTERVAL_MIN:
+            return max(
+                lookback_days + DB_ROW_DAILY_PADDING_DAYS,
+                DB_ROW_MIN_DAILY_BARS,
+            )
+        bars_per_day = max((24 * 60) // max(interval, 1), 1)
+        return bars_per_day * lookback_days + DB_ROW_WARMUP_BARS
+
+    def get_coin_saved_data(
+        self,
+        symbol: str,
+        interval: int,
+        data: pd.DataFrame,
+        db_path: str = DB_PATH,
+        max_rows: int = DB_READ_LIMIT_DEFAULT,
+    ) -> pd.DataFrame:
+        """
+        coins.db에서 저장된 봉을 읽고, API로 받은 최신 봉을 DB에 반영합니다.
+
+        scripts/01_download.py로 미리 적재해 두면 장기 MA 계산에 유리합니다.
+        """
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+        table_name = f"{symbol}_{interval}"
+        cursor.execute(
+            f"CREATE TABLE IF NOT EXISTS {table_name} "
+            "(CODE text, NAME text, ymdhms datetime, ymd text, hms text, "
+            "Close REAL, Open REAL, High REAL, Low REAL, Volume REAL)"
+        )
+        cursor.execute(
+            f"CREATE INDEX IF NOT EXISTS {table_name}_idx ON {table_name}(CODE, ymdhms)"
+        )
+
+        for i in range(1, len(data)):
+            ymdhms = data["datetime"].iloc[-i].strftime("%Y-%m-%d %H:%M:%S")
+            cursor.execute(
+                f"SELECT 1 FROM {table_name} WHERE CODE = ? AND ymdhms = ?",
+                (symbol, ymdhms),
+            )
+            if not cursor.fetchone():
+                cursor.execute(
+                    f"INSERT INTO {table_name} "
+                    "(CODE, NAME, ymdhms, ymd, hms, Close, Open, High, Low, Volume) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        symbol,
+                        KR_COINS[symbol],
+                        ymdhms,
+                        data["datetime"].iloc[-i].strftime("%Y%m%d"),
+                        data["datetime"].iloc[-i].strftime("%H%M%S"),
+                        data["Close"].iloc[-i],
+                        data["Open"].iloc[-i],
+                        data["High"].iloc[-i],
+                        data["Low"].iloc[-i],
+                        data["Volume"].iloc[-i],
+                    ),
+                )
+            else:
+                break
+
+        cursor.execute(
+            f"SELECT Open, Close, High, Low, Volume, ymdhms AS datetime "
+            f"FROM (SELECT Open, Close, High, Low, Volume, ymdhms "
+            f"FROM {table_name} ORDER BY ymdhms DESC LIMIT {int(max_rows)}) "
+            f"ORDER BY datetime"
+        )
+        result = cursor.fetchall()
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        if not result:
+            return pd.DataFrame(
+                columns=["Open", "Close", "High", "Low", "Volume", "datetime"]
+            )
+
+        df = pd.DataFrame(
+            result, columns=["Open", "Close", "High", "Low", "Volume", "datetime"]
+        )
+        df = df.set_index("datetime")
+        df = df.sort_index()
+        df["datetime"] = df.index
+        return df
+
+    def get_coin_some_data(
+        self, symbol: str, interval: int, db_max_rows: int | None = None
+    ) -> pd.DataFrame:
+        """
+        WLD 시세: API 최신 봉 + coins.db 과거 봉 + 1분봉 최신 1개를 합칩니다.
+
+        DB가 비어 있으면 API·1분봉만 사용합니다. 과거 적재는 scripts/01_download.py 실행.
+        """
+        data = self.get_coin_data(symbol, interval)
+        if data is None or data.empty:
+            return pd.DataFrame()
+
+        data_1 = self.get_coin_data(symbol, interval=1)
+        if data_1 is not None and not data_1.empty:
+            data_1 = data_1.copy()
+            data_1.at[data_1.index[-1], "Volume"] = data_1["Volume"].iloc[-1] * 60
+
+        row_limit = DB_READ_LIMIT_DEFAULT if db_max_rows is None else int(db_max_rows)
+        saved_data = self.get_coin_saved_data(
+            symbol, interval, data, max_rows=row_limit
+        )
+        parts = [data]
+        if saved_data is not None and not saved_data.empty:
+            parts.append(saved_data)
+        if data_1 is not None and not data_1.empty:
+            parts.append(data_1.iloc[[-1]])
+
+        merged = pd.concat(parts, ignore_index=True)
+        merged["datetime"] = pd.to_datetime(merged["datetime"], format="%Y-%m-%d %H:%M:%S")
+        merged = merged.set_index("datetime")
+        merged = merged.sort_index()
+        merged = merged.drop_duplicates(keep="first")
+        merged["datetime"] = merged.index
+        return merged

deepcoin/ops/monitor_coin.py

@@ -0,0 +1,34 @@
+"""
+WLD(월드코인) 실시간 모니터 — BB·일목 위치·추세 출력 (자동 매매 없음).
+"""
+
+from datetime import datetime
+import time
+
+from config import COIN_NAME, MONITOR_LOOP_SLEEP_SEC, SYMBOL
+from deepcoin.ops.monitor import Monitor
+
+
+class MonitorCoin(Monitor):
+    """WLD 시장 상태 주기 출력."""
+
+    def monitor_wld(self) -> None:
+        """전 봉 BB·일목·추세를 콘솔에 출력합니다."""
+        print(
+            "[{}] {} ({})".format(
+                datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                COIN_NAME,
+                SYMBOL,
+            )
+        )
+        self.process_wld_market_status(SYMBOL)
+
+    def run_schedule(self) -> None:
+        """MONITOR_LOOP_SLEEP_SEC 간격으로 상태를 출력합니다."""
+        while True:
+            self.monitor_wld()
+            time.sleep(MONITOR_LOOP_SLEEP_SEC)
+
+
+if __name__ == "__main__":
+    MonitorCoin(cooldown_file=None).run_schedule()

deepcoin/ops/simulation.py

@@ -0,0 +1,595 @@
+"""
+WLD 볼린저 밴드 차트.
+
+  python scripts/05_chart_bb.py
+  python scripts/05_chart_truth.py
+  python scripts/02_ground_truth.py
+"""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objs as go
+from plotly.subplots import make_subplots
+
+from config import (
+    CHART_LOOKBACK_DAYS,
+    COIN_NAME,
+    DISPARITY_OVERBOUGHT,
+    DISPARITY_OVERSOLD,
+    DISPARITY_PERIODS,
+    ENTRY_INTERVAL,
+    GROUND_TRUTH_FILE,
+    GT_INITIAL_CASH_KRW,
+    GT_MARKER_SIZE_MAX,
+    GT_MARKER_SIZE_MIN,
+    MACD_FAST,
+    MACD_SIGNAL,
+    MACD_SLOW,
+    STOCH_D_PERIOD,
+    STOCH_K_PERIOD,
+    SYMBOL,
+    TRADING_FEE_RATE,
+    TREND_INTERVAL_1D,
+    TREND_INTERVAL_1H,
+)
+from deepcoin.common.indicators import apply_bar_indicators, disparity_column, get_trend
+from deepcoin.ops.monitor import Monitor
+from deepcoin.data.mtf_bb import interval_label, load_frames_from_db
+
+from deepcoin.paths import CHART_BB_HTML, CHART_TRUTH_HTML, resolve_ground_truth_file
+
+OUTPUT_HTML = CHART_BB_HTML
+TRUTH_HTML = CHART_TRUTH_HTML
+GROUND_TRUTH_PATH = resolve_ground_truth_file()
+REPORT_DIR = CHART_BB_HTML.parent
+
+
+def interval_chart_label(interval_min: int) -> str:
+    """차트 제목용 봉 라벨."""
+    if interval_min >= 1440:
+        return "일봉"
+    return f"{interval_min}분봉"
+
+
+def _marker_sizes(trades: list[dict], action: str) -> list[float]:
+    """비중(weight, 0~1)에 비례한 삼각형 크기."""
+    pts = [t for t in trades if t.get("action") == action]
+    if not pts:
+        return []
+    lo, hi = float(GT_MARKER_SIZE_MIN), float(GT_MARKER_SIZE_MAX)
+    return [
+        lo + (hi - lo) * min(max(float(t.get("weight", 1.0)), 0.05), 1.0)
+        for t in pts
+    ]
+
+
+def _add_truth_markers(fig, trades: list[dict], row: int = 1) -> None:
+    """정답 매수·매도 마커 (삼각형 크기 = 비중)."""
+    for action, color, symbol, label in [
+        ("buy", "#16a34a", "triangle-up", "정답 매수"),
+        ("sell", "#dc2626", "triangle-down", "정답 매도"),
+    ]:
+        pts = [t for t in trades if t.get("action") == action]
+        if not pts:
+            continue
+        sizes = _marker_sizes(trades, action)
+        fig.add_trace(
+            go.Scatter(
+                x=[pd.Timestamp(t["dt"]) for t in pts],
+                y=[t["price"] for t in pts],
+                mode="markers",
+                name=label,
+                legendgroup=label,
+                marker=dict(
+                    symbol=symbol,
+                    size=sizes,
+                    sizemode="diameter",
+                    color=color,
+                    line=dict(width=1.5, color="#111"),
+                ),
+                hovertext=[
+                    f"{label}<br>{t['dt'][:16]}<br>₩{t['price']:,.0f}"
+                    f"<br>비중 {float(t.get('weight', 1))*100:.0f}%"
+                    f"<br>{t.get('memo', '')}"
+                    for t in pts
+                ],
+                hovertemplate="%{hovertext}<extra></extra>",
+            ),
+            row=row,
+            col=1,
+        )
+
+
+def build_chart_html(
+    df: pd.DataFrame,
+    trend: str,
+    interval_min: int = ENTRY_INTERVAL,
+    note: str = "",
+    truth_trades: list[dict] | None = None,
+    title_suffix: str = "BB 차트",
+    pnl_summary: dict | None = None,
+) -> str:
+    """BB·이격도·RSI·MACD·스토캐스틱·거래량 차트 HTML."""
+    df = apply_bar_indicators(df.copy())
+    iv_label = interval_chart_label(interval_min)
+    close_last = float(df["Close"].iloc[-1])
+    bb_pos = None
+    if "bb_pos" in df.columns and pd.notna(df["bb_pos"].iloc[-1]):
+        bb_pos = float(df["bb_pos"].iloc[-1])
+
+    disp_title = "이격도 " + ",".join(str(p) for p in DISPARITY_PERIODS)
+    fig = make_subplots(
+        rows=6,
+        cols=1,
+        shared_xaxes=True,
+        vertical_spacing=0.03,
+        row_heights=[0.42, 0.11, 0.11, 0.11, 0.13, 0.12],
+        subplot_titles=(
+            f"{COIN_NAME} ({SYMBOL}) {iv_label}",
+            disp_title,
+            f"Stochastic ({STOCH_K_PERIOD},{STOCH_D_PERIOD})",
+            "RSI (14)",
+            f"MACD ({MACD_FAST},{MACD_SLOW},{MACD_SIGNAL})",
+            "거래량",
+        ),
+    )
+    disp_colors = ("#0d9488", "#7c3aed", "#ca8a04")
+
+    fig.add_trace(
+        go.Candlestick(
+            x=df.index,
+            open=df["Open"],
+            high=df["High"],
+            low=df["Low"],
+            close=df["Close"],
+            name=f"{iv_label} 캔들",
+            increasing_line_color="#ef4444",
+            decreasing_line_color="#3b82f6",
+        ),
+        row=1,
+        col=1,
+    )
+    if "MA" in df.columns:
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["MA"],
+                name="BB 중심",
+                line=dict(color="#64748b", width=1, dash="dot"),
+            ),
+            row=1,
+            col=1,
+        )
+    if "Upper" in df.columns:
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["Upper"],
+                name="BB 상단",
+                line=dict(color="#94a3b8", width=1),
+            ),
+            row=1,
+            col=1,
+        )
+    if "Lower" in df.columns:
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["Lower"],
+                name="BB 하단",
+                line=dict(color="#94a3b8", width=1),
+            ),
+            row=1,
+            col=1,
+        )
+
+    if truth_trades:
+        _add_truth_markers(fig, truth_trades, row=1)
+
+    disp_row = 2
+    for i, p in enumerate(DISPARITY_PERIODS):
+        col = disparity_column(p)
+        if col not in df.columns:
+            continue
+        color = disp_colors[i % len(disp_colors)]
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df[col],
+                name=f"D.I. {p}",
+                line=dict(color=color, width=1),
+            ),
+            row=disp_row,
+            col=1,
+        )
+    if any(disparity_column(p) in df.columns for p in DISPARITY_PERIODS):
+        fig.add_hline(
+            y=100, line_dash="solid", line_color="#64748b", row=disp_row, col=1
+        )
+        fig.add_hline(
+            y=DISPARITY_OVERBOUGHT,
+            line_dash="dot",
+            line_color="#ef4444",
+            row=disp_row,
+            col=1,
+        )
+        fig.add_hline(
+            y=DISPARITY_OVERSOLD,
+            line_dash="dot",
+            line_color="#16a34a",
+            row=disp_row,
+            col=1,
+        )
+
+    stoch_row = 3
+    if "stoch_k" in df.columns:
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["stoch_k"],
+                name="Stoch %K",
+                line=dict(color="#0ea5e9", width=1),
+            ),
+            row=stoch_row,
+            col=1,
+        )
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["stoch_d"],
+                name="Stoch %D",
+                line=dict(color="#f97316", width=1),
+            ),
+            row=stoch_row,
+            col=1,
+        )
+        fig.add_hline(y=80, line_dash="dot", line_color="#9ca3af", row=stoch_row, col=1)
+        fig.add_hline(y=20, line_dash="dot", line_color="#9ca3af", row=stoch_row, col=1)
+
+    rsi_row = 4
+    if "RSI" in df.columns:
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["RSI"],
+                name="RSI",
+                line=dict(color="#7c3aed"),
+            ),
+            row=rsi_row,
+            col=1,
+        )
+        fig.add_hline(y=70, line_dash="dot", line_color="#9ca3af", row=rsi_row, col=1)
+        fig.add_hline(y=30, line_dash="dot", line_color="#9ca3af", row=rsi_row, col=1)
+
+    macd_row = 5
+    vol_row = 6
+    if "macd_hist" in df.columns:
+        colors = np.where(df["macd_hist"].astype(float) >= 0, "#ef4444", "#3b82f6")
+        fig.add_trace(
+            go.Bar(
+                x=df.index,
+                y=df["macd_hist"],
+                name="MACD Hist",
+                marker_color=colors,
+            ),
+            row=macd_row,
+            col=1,
+        )
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["macd_line"],
+                name="MACD",
+                line=dict(color="#2563eb", width=1),
+            ),
+            row=macd_row,
+            col=1,
+        )
+        fig.add_trace(
+            go.Scatter(
+                x=df.index,
+                y=df["macd_signal"],
+                name="Signal",
+                line=dict(color="#ea580c", width=1, dash="dot"),
+            ),
+            row=macd_row,
+            col=1,
+        )
+
+    fig.add_trace(
+        go.Bar(
+            x=df.index,
+            y=df["Volume"],
+            name="Volume",
+            marker_color="#cbd5e1",
+        ),
+        row=vol_row,
+        col=1,
+    )
+
+    fig.update_layout(
+        height=1180,
+        template="plotly_white",
+        xaxis_rangeslider_visible=False,
+        legend=dict(orientation="h", y=1.05, x=0),
+        margin=dict(l=60, r=30, t=90, b=40),
+    )
+    fig.update_yaxes(title_text="가격 (KRW)", row=1, col=1)
+    fig.update_yaxes(title_text="이격도", row=2, col=1)
+    fig.update_yaxes(title_text="Stoch", row=3, col=1, range=[0, 100])
+    fig.update_yaxes(title_text="RSI", row=4, col=1, range=[0, 100])
+    fig.update_yaxes(title_text="MACD", row=5, col=1)
+
+    chart_html = fig.to_html(full_html=False, include_plotlyjs="cdn")
+    note_html = f"<p class='note'>{note}</p>" if note else ""
+    bb_pos_txt = f"{bb_pos:.2f}" if bb_pos is not None else "-"
+    pnl = pnl_summary or {}
+    if truth_trades and not pnl:
+        from deepcoin.ground_truth.ground_truth import simulate_truth_portfolio
+
+        pnl = simulate_truth_portfolio(
+            truth_trades,
+            initial_cash=GT_INITIAL_CASH_KRW,
+            fee_rate=TRADING_FEE_RATE,
+            last_price=close_last,
+        )
+    trade_rows = ""
+    if truth_trades:
+        from deepcoin.ground_truth.ground_truth import simulate_truth_portfolio_steps
+
+        steps = simulate_truth_portfolio_steps(
+            truth_trades,
+            initial_cash=GT_INITIAL_CASH_KRW,
+            fee_rate=TRADING_FEE_RATE,
+        )
+        step_key = {
+            (s["dt"], s["action"], float(s["price"]), float(s["weight"])): s
+            for s in steps
+        }
+        sorted_trades = sorted(truth_trades, key=lambda x: x["dt"])
+        trade_rows += f"""
+        <tr class="initial-row">
+          <td>시작</td>
+          <td>-</td>
+          <td>-</td>
+          <td>-</td>
+          <td><b>₩{GT_INITIAL_CASH_KRW:,.0f}</b></td>
+          <td>초기 현금 (보유 0)</td>
+        </tr>"""
+        for t in sorted_trades:
+            cls = "buy" if t["action"] == "buy" else "sell"
+            mark = "매수" if t["action"] == "buy" else "매도"
+            ret = t.get("forward_return_pct")
+            ret_s = f" (+{ret}%)" if ret is not None else ""
+            w = float(t.get("weight", 1.0))
+            key = (t["dt"], t["action"], float(t["price"]), w)
+            step = step_key.get(key)
+            if step:
+                total_s = f"₩{step['total_asset_krw']:,.0f}"
+                hold_s = f" (현금 ₩{step['cash_krw']:,.0f} + 코인 {step['holding_qty']:,.2f}개)"
+            else:
+                total_s = "-"
+                hold_s = ""
+            trade_rows += f"""
+        <tr>
+          <td>{t['dt'][:16]}</td>
+          <td class="{cls}">{mark}</td>
+          <td>{w*100:.0f}%</td>
+          <td>₩{t['price']:,.0f}{ret_s}</td>
+          <td><b>{total_s}</b>{hold_s}</td>
+          <td>{t.get('memo', '')}</td>
+        </tr>"""
+    trade_table = ""
+    if truth_trades:
+        if not trade_rows:
+            trade_rows = "<tr><td colspan='6'>타점 없음</td></tr>"
+        mark_note = ""
+        if pnl.get("mark_price"):
+            mark_note = (
+                f" 상단 최종 자산은 미청산 포함 종가 ₩{pnl['mark_price']:,.0f} 평가."
+            )
+        trade_table = f"""
+  <h2>정답 타점 (ground_truth)</h2>
+  <p class="meta">삼각형 크기 = 비중. 매수: 저점 분할 / 매도: 고점 1~2회.
+  총평가 = 체결 직후 현금 + 보유×체결가.{mark_note}</p>
+  <table>
+    <thead><tr><th>시각</th><th>구분</th><th>비중</th><th>가격</th><th>총 평가금액</th><th>해석</th></tr></thead>
+    <tbody>{trade_rows}</tbody>
+  </table>"""
+
+    pnl_cards = ""
+    if truth_trades and pnl.get("initial_cash_krw") is not None:
+        pnl_cards = f"""
+    <div class="card"><span>시작</span><b>₩{pnl['initial_cash_krw']:,.0f}</b></div>
+    <div class="card"><span>최종 자산</span><b>₩{pnl['final_asset_krw']:,.0f}</b></div>
+    <div class="card"><span>수익금</span><b>₩{pnl['pnl_krw']:+,.0f}</b></div>
+    <div class="card"><span>수익률</span><b>{pnl['pnl_pct']:+.2f}%</b></div>
+    <div class="card"><span>수수료</span><b>₩{pnl['total_fees_krw']:,.0f}</b></div>"""
+        if pnl.get("holding_qty", 0) > 0:
+            pnl_cards += f"""
+    <div class="card"><span>미청산</span><b>{pnl['holding_qty']}개 (₩{pnl['holding_value_krw']:,.0f})</b></div>"""
+
+    return f"""<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8"/>
+  <title>{SYMBOL} {title_suffix}</title>
+  <style>
+    body {{ font-family: "Malgun Gothic", Arial, sans-serif; margin: 24px; background: #f8fafc; }}
+    h1 {{ font-size: 1.35rem; }}
+    .meta {{ color: #475569; font-size: 0.9rem; }}
+    .note {{ background: #f1f5f9; border: 1px solid #cbd5e1; padding: 10px; border-radius: 6px; color: #334155; }}
+    .cards {{ display: flex; flex-wrap: wrap; gap: 10px; margin: 16px 0; }}
+    .card {{ background: #fff; border: 1px solid #e2e8f0; border-radius: 8px; padding: 10px 14px; }}
+    .card span {{ font-size: 0.75rem; color: #64748b; display: block; }}
+    .card b {{ font-size: 1.05rem; }}
+    .chart-wrap {{ background:#fff; border:1px solid #e2e8f0; border-radius:8px; padding:8px; }}
+    .legend-box {{ font-size:0.85rem; color:#475569; margin-bottom:10px; }}
+    table {{ width:100%; border-collapse:collapse; background:#fff; font-size:0.85rem; }}
+    th, td {{ border:1px solid #e2e8f0; padding:8px; text-align:left; }}
+    th {{ background:#f1f5f9; }}
+    td.buy {{ color:#16a34a; font-weight:600; }}
+    td.sell {{ color:#dc2626; font-weight:600; }}
+  </style>
+</head>
+<body>
+  <h1>{COIN_NAME} ({SYMBOL}) {title_suffix}</h1>
+  <p class="meta">추세(참고): {trend} | 기간: {df.index[0]} ~ {df.index[-1]} | 봉 수: {len(df)}</p>
+  {note_html}
+  <div class="legend-box">▲ 매수 · ▼ 매도 — 삼각형이 클수록 비중이 큽니다.</div>
+    <div class="cards">
+    <div class="card"><span>종가</span><b>₩{close_last:,.2f}</b></div>
+    <div class="card"><span>BB %B</span><b>{bb_pos_txt}</b></div>
+    <div class="card"><span>정답 타점</span><b>{len(truth_trades) if truth_trades else 0}건</b></div>
+    {pnl_cards}
+  </div>
+  <div class="chart-wrap">{chart_html}</div>
+  {trade_table}
+</body>
+</html>"""
+
+
+def _frames_to_mtf(
+    frames: dict[int, pd.DataFrame],
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """전 간격 frames에서 1d/1h/3m 추출."""
+    df_3m = frames.get(ENTRY_INTERVAL)
+    if df_3m is None or df_3m.empty:
+        raise ValueError(f"{ENTRY_INTERVAL}분봉 데이터 없음")
+    df_1d = frames.get(TREND_INTERVAL_1D)
+    if df_1d is None or df_1d.empty:
+        df_1d = df_3m
+    df_1h = frames.get(TREND_INTERVAL_1H)
+    if df_1h is None or df_1h.empty:
+        df_1h = df_3m
+    return df_1d, df_1h, df_3m
+
+
+def load_chart_frames() -> dict[int, pd.DataFrame] | None:
+    """coins.db 전 간격 로드. 부족 시 None."""
+    monitor = Monitor(cooldown_file=None)
+    print(f"DB 조회: 최근 {CHART_LOOKBACK_DAYS}일 (CHART_LOOKBACK_DAYS)")
+    frames = load_frames_from_db(monitor, SYMBOL, lookback_days=CHART_LOOKBACK_DAYS)
+    if ENTRY_INTERVAL not in frames:
+        print("coins.db 데이터 부족. python scripts/01_download.py 실행 후 재시도.")
+        return None
+    return frames
+
+
+def run_ground_truth_chart(open_browser: bool = True) -> Path:
+    """
+    정답 타점을 생성·저장하고 마커가 포함된 HTML 차트를 만듭니다.
+
+    Args:
+        open_browser: True면 브라우저로 HTML을 엽니다.
+
+    Returns:
+        HTML 파일 경로.
+    """
+    from deepcoin.ground_truth.ground_truth import run_from_db
+
+    data = run_from_db()
+    frames = load_chart_frames()
+    if frames is None:
+        raise RuntimeError("차트 데이터 로드 실패")
+
+    df_1d, df_1h, df_3m = _frames_to_mtf(frames)
+    trend = get_trend(df_1d, df_1h)
+    df_chart = apply_bar_indicators(df_3m)
+    trades = data.get("trades") or []
+
+    summary = data.get("summary") or {}
+    html = build_chart_html(
+        df_chart,
+        trend,
+        note=data.get("note", ""),
+        truth_trades=trades,
+        title_suffix=f"정답 타점 ({CHART_LOOKBACK_DAYS}일)",
+        pnl_summary=summary if summary.get("pnl_krw") is not None else None,
+    )
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    TRUTH_HTML.write_text(html, encoding="utf-8")
+    print(f"HTML: {TRUTH_HTML}")
+    if open_browser:
+        webbrowser.open(TRUTH_HTML.resolve().as_uri())
+    return TRUTH_HTML
+
+
+def run_chart(open_browser: bool = True) -> Path:
+    """
+    3분봉 BB 차트 HTML을 생성합니다.
+
+    Args:
+        open_browser: True면 기본 브라우저로 HTML을 엽니다.
+
+    Returns:
+        저장된 HTML 경로.
+    """
+    frames = load_chart_frames()
+    if frames is None:
+        raise RuntimeError("차트 데이터 로드 실패")
+
+    df_1d, df_1h, df_3m = _frames_to_mtf(frames)
+    trend = get_trend(df_1d, df_1h)
+    df_chart = apply_bar_indicators(df_3m)
+    print(f"\n추세(참고): {trend}")
+    print(f"3분: {df_chart.index[0]} ~ {df_chart.index[-1]} ({len(df_chart)}봉)")
+
+    html = build_chart_html(
+        df_chart,
+        trend,
+        note="자동 매수·매도 전략은 사용하지 않습니다.",
+    )
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    OUTPUT_HTML.write_text(html, encoding="utf-8")
+    print(f"HTML: {OUTPUT_HTML}")
+    if open_browser:
+        webbrowser.open(OUTPUT_HTML.resolve().as_uri())
+    return OUTPUT_HTML
+
+
+def print_usage() -> None:
+    print(
+        """
+DeepCoin simulation.py
+
+  python simulation.py
+      WLD 3분봉 BB 차트 → docs/charts/wld_bb_chart.html
+
+  python simulation.py truth
+      정답 타점 생성 → ground_truth_trades.json
+      차트 → docs/02_ground_truth/wld_ground_truth_chart.html
+"""
+    )
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help", "help"):
+        print_usage()
+        return
+    if len(sys.argv) > 1 and sys.argv[1] in ("truth", "ground-truth", "gt"):
+        print("=" * 60)
+        print("정답 타점 생성 + 차트")
+        print("=" * 60)
+        run_ground_truth_chart()
+        print("\n완료.")
+        return
+    if len(sys.argv) > 1:
+        print(f"알 수 없는 옵션: {sys.argv[1]}\n")
+        print_usage()
+        return
+    print("=" * 60)
+    print("WLD BB 차트 (매매 전략 없음)")
+    print("=" * 60)
+    run_chart()
+    print("\n완료.")
+
+
+if __name__ == "__main__":
+    main()