cyqnt-trd 0.1.2__py3-none-any.whl → 0.1.7__py3-none-any.whl

cyqnt_trd/get_data/get_kline_with_factor.py

@@ -0,0 +1,808 @@
+"""
+K 线 + 因子获取（单点 / 以某点为 end 向前取 n 点）
+
+参考：model-training/trading_report_signal_ranking_v1/get_klines_data_with_factor_dire.py
+公用方法 get_klines_with_factors(klines_data)：输入原始 klines_data，输出带因子的 klines 列表。
+对外接口：
+- get_kline_with_factor_at_time：输出当前时间点的单条带因子数据
+- get_kline_with_factor_n_points：输出当前所有时间点的带因子数据
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+
+# ---------------------------------------------------------------------------
+# 时间转换（与 get_futures_data 一致）
+# ---------------------------------------------------------------------------
+
+def _convert_to_timestamp_ms(time_input: Union[datetime, str, int, None]) -> Optional[int]:
+    if time_input is None:
+        return None
+    if isinstance(time_input, datetime):
+        return int(time_input.timestamp() * 1000)
+    if isinstance(time_input, str):
+        for fmt in ["%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d", "%Y/%m/%d %H:%M:%S", "%Y/%m/%d"]:
+            try:
+                dt = datetime.strptime(time_input, fmt)
+                return int(dt.timestamp() * 1000)
+            except ValueError:
+                continue
+        raise ValueError(f"无法解析时间字符串: {time_input}")
+    if isinstance(time_input, int):
+        return time_input if time_input > 1e10 else time_input * 1000
+    raise TypeError(f"不支持的时间类型: {type(time_input)}")
+
+
+def _get_interval_duration_ms(interval: str) -> int:
+    mapping = {
+        "1m": 60 * 1000,
+        "3m": 3 * 60 * 1000,
+        "5m": 5 * 60 * 1000,
+        "15m": 15 * 60 * 1000,
+        "30m": 30 * 60 * 1000,
+        "1h": 60 * 60 * 1000,
+        "2h": 2 * 60 * 60 * 1000,
+        "4h": 4 * 60 * 60 * 1000,
+        "6h": 6 * 60 * 60 * 1000,
+        "8h": 8 * 60 * 60 * 1000,
+        "12h": 12 * 60 * 60 * 1000,
+        "1d": 24 * 60 * 60 * 1000,
+        "3d": 3 * 24 * 60 * 60 * 1000,
+        "1w": 7 * 24 * 60 * 60 * 1000,
+        "1M": 30 * 24 * 60 * 60 * 1000,
+    }
+    return mapping.get(interval, 60 * 1000)
+
+
+# ---------------------------------------------------------------------------
+# 因子计算（与 get_klines_data_with_factor_dire 一致）
+# ---------------------------------------------------------------------------
+
+def calculate_normalized_alpha_factor(
+    data_slice: pd.DataFrame,
+    factor_func: Callable,
+    factor_name: str,
+    min_required: int = 30,
+    lookback_periods: int = 30,
+    factor_cache: Optional[Dict[tuple, float]] = None,
+    current_point_idx: Optional[int] = None,
+    **factor_kwargs: Any,
+) -> Optional[Dict[str, Any]]:
+    try:
+        if len(data_slice) < min_required + 2:
+            return None
+        available_periods = len(data_slice) - min_required - 1
+        if available_periods < 2:
+            return None
+        actual_lookback = min(lookback_periods, max(2, available_periods))
+        factor_values: List[float] = []
+        cache_key_base = factor_name if current_point_idx is not None else None
+
+        for i in range(actual_lookback + 1):
+            end_idx = len(data_slice) - i
+            point_idx = current_point_idx - i if current_point_idx is not None else None
+            if factor_cache is not None and point_idx is not None and cache_key_base:
+                cache_key = (point_idx, cache_key_base)
+                if cache_key in factor_cache:
+                    factor_values.append(factor_cache[cache_key])
+                    continue
+            start_idx = max(0, end_idx - min_required - 1)
+            if end_idx <= start_idx:
+                factor_values.append(0.0)
+                continue
+            period_slice = data_slice.iloc[start_idx:end_idx]
+            try:
+                factor_value = factor_func(period_slice, **factor_kwargs)
+                if factor_value is not None:
+                    value = float(factor_value)
+                    factor_values.append(value)
+                    if factor_cache is not None and point_idx is not None and cache_key_base:
+                        factor_cache[(point_idx, cache_key_base)] = value
+                else:
+                    factor_values.append(0.0)
+            except Exception:
+                factor_values.append(0.0)
+
+        if len(factor_values) < 2:
+            return None
+        factor_array = np.array(factor_values)
+        factor_mean = factor_array.mean()
+        factor_std = factor_array.std()
+        if factor_std == 0 or np.isnan(factor_std):
+            normalized_factors = np.zeros_like(factor_array)
+        else:
+            normalized_factors = (factor_array - factor_mean) / factor_std
+        current_normalized = float(normalized_factors[0])
+        prev_normalized = float(normalized_factors[1]) if len(normalized_factors) > 1 else 0.0
+        signal = "看多" if current_normalized > 0 else ("看空" if current_normalized < 0 else "中性")
+        return {
+            "value": current_normalized,
+            "signal": signal,
+            "raw_value": float(factor_values[0]) if factor_values else 0.0,
+            "prev_normalized": prev_normalized,
+        }
+    except Exception as e:
+        logging.warning("Error calculating normalized %s factor: %s", factor_name, e)
+        return None
+
+
+def _get_factor_configs() -> List[tuple]:
+    from cyqnt_trd.trading_signal.factor.ma_factor import ma_factor
+    from cyqnt_trd.trading_signal.factor.rsi_factor import rsi_factor
+    from cyqnt_trd.trading_signal.selected_alpha import (
+        alpha1_factor,
+        alpha3_factor,
+        alpha7_factor,
+        alpha9_factor,
+        alpha11_factor,
+        alpha15_factor,
+        alpha17_factor,
+        alpha21_factor,
+        alpha23_factor,
+        alpha25_factor,
+        alpha29_factor,
+        alpha33_factor,
+        alpha34_factor,
+    )
+    return [
+        ("ma_factor_5", ma_factor, 6, {"period": 5}, False),
+        ("rsi_factor_14", rsi_factor, 16, {"period": 14}, False),
+        ("alpha1", alpha1_factor, 30, {"lookback_days": 5, "stddev_period": 20, "power": 2.0}, True),
+        ("alpha3", alpha3_factor, 30, {}, True),
+        ("alpha7", alpha7_factor, 30, {}, True),
+        ("alpha9", alpha9_factor, 30, {}, True),
+        ("alpha11", alpha11_factor, 30, {}, True),
+        ("alpha15", alpha15_factor, 30, {}, True),
+        ("alpha17", alpha17_factor, 30, {}, True),
+        ("alpha21", alpha21_factor, 30, {}, True),
+        ("alpha23", alpha23_factor, 30, {}, True),
+        ("alpha25", alpha25_factor, 30, {}, True),
+        ("alpha29", alpha29_factor, 30, {}, True),
+        ("alpha33", alpha33_factor, 30, {}, True),
+        ("alpha34", alpha34_factor, 30, {}, True),
+    ]
+
+
+HISTORY_WINDOW = 100
+# 接口单次请求 K 线数量上限，超过则分多次请求
+MAX_KLINES_PER_REQUEST = 1500
+
+
+def _compute_point_factors(
+    data_df: pd.DataFrame,
+    idx: int,
+    factor_configs: List[tuple],
+    factor_cache: Dict[tuple, float],
+    lookback_periods: int = 30,
+) -> Optional[Dict[str, Any]]:
+    time_point_data = data_df.iloc[: idx + 1]
+    kline_point = data_df.iloc[idx]
+    open_time = int(kline_point["open_time"])
+    close_time = int(kline_point["close_time"])
+    open_time_str = kline_point.get(
+        "open_time_str", pd.to_datetime(open_time, unit="ms").strftime("%Y-%m-%d %H:%M:%S")
+    )
+    close_time_str = kline_point.get(
+        "close_time_str", pd.to_datetime(close_time, unit="ms").strftime("%Y-%m-%d %H:%M:%S")
+    )
+    point_factors: Dict[str, Any] = {}
+
+    for factor_name, factor_func, min_req, kwargs, is_alpha in factor_configs:
+        if len(time_point_data) < min_req:
+            continue
+        try:
+            if is_alpha:
+                result = calculate_normalized_alpha_factor(
+                    time_point_data,
+                    factor_func,
+                    factor_name,
+                    min_required=min_req,
+                    lookback_periods=lookback_periods,
+                    factor_cache=factor_cache,
+                    current_point_idx=idx,
+                    **kwargs,
+                )
+                if result:
+                    point_factors[factor_name] = {
+                        "value": result.get("value", 0.0),
+                        "raw_value": result.get("raw_value", 0.0),
+                        "signal": result.get("signal", "中性"),
+                        "prev_normalized": result.get("prev_normalized", 0.0),
+                    }
+            else:
+                cache_key = (idx, factor_name)
+                if cache_key in factor_cache:
+                    factor_value = factor_cache[cache_key]
+                else:
+                    factor_value = factor_func(time_point_data, **kwargs)
+                    if factor_value is not None:
+                        factor_cache[cache_key] = float(factor_value)
+                if factor_value is not None:
+                    signal = "看多" if factor_value > 0 else ("看空" if factor_value < 0 else "中性")
+                    point_factors[factor_name] = {
+                        "value": float(factor_value),
+                        "raw_value": float(factor_value),
+                        "signal": signal,
+                    }
+        except Exception as e:
+            logging.debug("Failed %s at idx %s: %s", factor_name, idx, e)
+
+    # 仅在有足够历史时输出，不进行任何 0 填充
+    if idx < HISTORY_WINDOW:
+        return None
+    start_history_idx = idx - HISTORY_WINDOW
+    end_history_idx = idx
+    hist = data_df.iloc[start_history_idx:end_history_idx]
+    open_price_list = hist["open_price"].astype(float).tolist()
+    high_price_list = hist["high_price"].astype(float).tolist()
+    low_price_list = hist["low_price"].astype(float).tolist()
+    close_price_list = hist["close_price"].astype(float).tolist()
+    volume_list = hist["volume"].astype(float).tolist()
+
+    return {
+        "time_index": idx,
+        "open_time": open_time,
+        "open_time_str": open_time_str,
+        "close_time": close_time,
+        "close_time_str": close_time_str,
+        "open_price": float(kline_point["open_price"]),
+        "high_price": float(kline_point["high_price"]),
+        "low_price": float(kline_point["low_price"]),
+        "close_price": float(kline_point["close_price"]),
+        "volume": float(kline_point["volume"]),
+        "factors": point_factors,
+        "open_price_list": open_price_list,
+        "high_price_list": high_price_list,
+        "low_price_list": low_price_list,
+        "close_price_list": close_price_list,
+        "volume_list": volume_list,
+    }
+
+
+def _klines_to_df(klines_data: List[Any]) -> pd.DataFrame:
+    formatted: List[Dict[str, Any]] = []
+    for kline in klines_data:
+        if isinstance(kline, list):
+            open_time = int(kline[0]) if isinstance(kline[0], str) else kline[0]
+            close_time = int(kline[6]) if isinstance(kline[6], str) else kline[6]
+            formatted.append({
+                "datetime": pd.to_datetime(open_time, unit="ms"),
+                "open_time": open_time,
+                "open_time_str": pd.to_datetime(open_time, unit="ms").strftime("%Y-%m-%d %H:%M:%S"),
+                "open_price": float(kline[1]),
+                "high_price": float(kline[2]),
+                "low_price": float(kline[3]),
+                "close_price": float(kline[4]),
+                "volume": float(kline[5]),
+                "close_time": close_time,
+                "close_time_str": pd.to_datetime(close_time, unit="ms").strftime("%Y-%m-%d %H:%M:%S"),
+            })
+        elif isinstance(kline, dict):
+            row = dict(kline)
+            if "datetime" not in row and "open_time" in row:
+                row["datetime"] = pd.to_datetime(row["open_time"], unit="ms")
+            formatted.append(row)
+    df = pd.DataFrame(formatted)
+    return df.sort_values("datetime").reset_index(drop=True)
+
+
+def _get_fetch_fn(type: str):
+    """按 type 返回拉取 K 线的函数（futures / spot）。"""
+    if type == "futures":
+        from cyqnt_trd.get_data.get_futures_data import get_and_save_futures_klines
+        return get_and_save_futures_klines
+    from cyqnt_trd.get_data.get_trending_data import get_and_save_klines_direct
+    return get_and_save_klines_direct
+
+
+def _fetch_klines_df(
+    token: str,
+    type: str,
+    interval: str,
+    start_time: Optional[Union[datetime, str, int]] = None,
+    end_time: Optional[Union[datetime, str, int]] = None,
+    limit: Optional[int] = None,
+) -> Optional[pd.DataFrame]:
+    get_fn = _get_fetch_fn(type)
+    kwargs: Dict[str, Any] = {"symbol": token, "interval": interval, "save_csv": False, "save_json": False}
+    if limit is not None:
+        kwargs["limit"] = limit
+    if start_time is not None:
+        kwargs["start_time"] = start_time
+    if end_time is not None:
+        kwargs["end_time"] = end_time
+    raw = get_fn(**kwargs)
+    if not raw:
+        return None
+    return _klines_to_df(raw)
+
+
+def _fetch_klines_by_range_paginated(
+    token: str,
+    type: str,
+    interval: str,
+    start_ms: int,
+    end_ms: int,
+    max_per_request: int = MAX_KLINES_PER_REQUEST,
+) -> Optional[pd.DataFrame]:
+    """
+    按时间范围拉取 K 线；若条数超过 max_per_request，则按时间分段多次请求后合并。
+    返回合并去重并按 open_time 排序的 DataFrame。
+    """
+    interval_ms = _get_interval_duration_ms(interval)
+    num_bars_approx = max(0, (end_ms - start_ms) // interval_ms)
+    if num_bars_approx == 0:
+        return _fetch_klines_df(token, type, interval, start_time=start_ms, end_time=end_ms)
+
+    get_fn = _get_fetch_fn(type)
+    if num_bars_approx <= max_per_request:
+        # 小范围时仅用 end_time + limit 单次请求，避免底层 start+end 触发的多轮分页导致卡住
+        request_limit = min(num_bars_approx + 20, max_per_request)
+        raw = get_fn(
+            symbol=token,
+            interval=interval,
+            end_time=end_ms,
+            limit=request_limit,
+            save_csv=False,
+            save_json=False,
+        )
+        if not raw:
+            return None
+        df = _klines_to_df(raw)
+        # 只保留 [start_ms, end_ms] 内的 K 线
+        if "open_time" in df.columns:
+            df = df[df["open_time"] >= start_ms].sort_values("open_time").reset_index(drop=True)
+        return df
+
+    all_raw: List[Any] = []
+    current_start = start_ms
+    request_count = 0
+    max_chunk_requests = 1000  # 防止异常时无限循环
+    while current_start < end_ms and request_count < max_chunk_requests:
+        request_count += 1
+        chunk_end_ms = min(current_start + max_per_request * interval_ms, end_ms)
+        batch = get_fn(
+            symbol=token,
+            interval=interval,
+            start_time=current_start,
+            end_time=chunk_end_ms,
+            save_csv=False,
+            save_json=False,
+        )
+        if not batch:
+            break
+        all_raw.extend(batch)
+        logging.info(
+            "K线分页第 %s 次请求: %s ~ %s, 本批 %s 条, 累计 %s 条",
+            request_count,
+            pd.to_datetime(current_start, unit="ms").strftime("%Y-%m-%d %H:%M"),
+            pd.to_datetime(chunk_end_ms, unit="ms").strftime("%Y-%m-%d %H:%M"),
+            len(batch),
+            len(all_raw),
+        )
+        if len(batch) < max_per_request:
+            break
+        current_start = chunk_end_ms
+    if not all_raw:
+        return None
+    df = _klines_to_df(all_raw)
+    # 分页边界可能重复，按 open_time 去重
+    if "open_time" in df.columns:
+        df = df.drop_duplicates(subset=["open_time"], keep="first").sort_values("open_time").reset_index(drop=True)
+    return df
+
+
+def _compute_kline_data_with_factors(
+    data_df: pd.DataFrame,
+    factor_configs: List[tuple],
+    lookback_periods: int = 30,
+) -> List[Dict[str, Any]]:
+    min_required = max(c[2] for c in factor_configs)
+    # 仅对“前面至少有 HISTORY_WINDOW 根真实 K 线”的点算因子，不填充 0
+    start_idx = max(min_required + 2, HISTORY_WINDOW)
+    factor_cache: Dict[tuple, float] = {}
+    out: List[Dict[str, Any]] = []
+    for idx in range(start_idx, len(data_df)):
+        try:
+            point = _compute_point_factors(
+                data_df, idx, factor_configs, factor_cache, lookback_periods
+            )
+            if point is not None:
+                out.append(point)
+        except Exception as e:
+            logging.debug("Skip point idx %s (no padding): %s", idx, e)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# 公用方法：输入 klines_data，输出带因子的 klines 列表
+# ---------------------------------------------------------------------------
+
+def get_klines_with_factors(
+    klines_data: List[Any],
+    factor_configs: Optional[List[tuple]] = None,
+    lookback_periods: int = 30,
+) -> List[Dict[str, Any]]:
+    """
+    公用方法：输入原始 klines_data（list of kline dict/list），输出带因子的 klines 列表。
+
+    Args:
+        klines_data: 原始 K 线数据，与 get_and_save_klines_direct / get_and_save_futures_klines 返回格式一致
+        factor_configs: 因子配置，默认 None 使用内置配置
+        lookback_periods: 因子回看周期
+
+    Returns:
+        带因子的 K 线列表，每项为 dict（含 open_time, factors, open_price_list 等）
+    """
+    data_df = _klines_to_df(klines_data)
+    if data_df.empty:
+        return []
+    configs = factor_configs or _get_factor_configs()
+    return _compute_kline_data_with_factors(data_df, configs, lookback_periods)
+
+
+def get_klines_with_factors_at_time(
+    klines_data: List[Any],
+    factor_configs: Optional[List[tuple]] = None,
+    lookback_periods: int = 30,
+) -> List[Dict[str, Any]]:
+    """
+    输入 klines_data，输出带因子的 klines 数据点，仅包含最新一根（最后一个时间点）。
+
+    Args:
+        klines_data: 原始 K 线数据
+        factor_configs: 因子配置，默认 None 使用内置配置
+        lookback_periods: 因子回看周期
+
+    Returns:
+        长度为 0 或 1 的列表；有足够历史时为 [最新一根带因子的 K 线 dict]，否则为 []。
+    """
+    all_points = get_klines_with_factors(klines_data, factor_configs, lookback_periods)
+    if not all_points:
+        return []
+    return [all_points[-1]]
+
+
+def get_klines_with_factors_n_points(
+    klines_data: List[Any],
+    factor_configs: Optional[List[tuple]] = None,
+    lookback_periods: int = 30,
+) -> List[Dict[str, Any]]:
+    """
+    输入 klines_data，输出带因子的 klines 数据，包含所有可计算因子的时间点及对应数据点。
+
+    Args:
+        klines_data: 原始 K 线数据
+        factor_configs: 因子配置，默认 None 使用内置配置
+        lookback_periods: 因子回看周期
+
+    Returns:
+        带因子的 K 线列表，每项为 dict（含 open_time, factors, open_price_list 等），与 klines_data 中可算因子的点一一对应。
+    """
+    return get_klines_with_factors(klines_data, factor_configs, lookback_periods)
+
+
+# ---------------------------------------------------------------------------
+# 对外接口
+# ---------------------------------------------------------------------------
+
+def _success_at_time(
+    token: str,
+    type: str,
+    interval: str,
+    at_ms: int,
+    kline_data: List[Dict[str, Any]],
+    data_rows: Optional[int] = None,
+    reason: Optional[str] = None,
+) -> Dict[str, Any]:
+    metadata = {"token": token, "type": type, "interval": interval, "at_time": at_ms}
+    if data_rows is not None:
+        metadata["data_rows"] = data_rows
+    if reason is not None:
+        metadata["reason"] = reason
+    elif data_rows is not None:
+        metadata["at_time_str"] = pd.to_datetime(at_ms, unit="ms").strftime("%Y-%m-%d %H:%M:%S")
+    return {"status": "success", "kline_data": kline_data, "metadata": metadata}
+
+
+def get_kline_with_factor_at_time(
+    token: str,
+    type: str = "futures",
+    interval: str = "30m",
+    at_time: Union[datetime, str, int] = None,
+    limit: int = 200,
+) -> Dict[str, Any]:
+    """
+    针对某个时间点：先拉取 klines_data，再经 get_klines_with_factors 计算因子，
+    返回该时间点的单根 K 线及其因子。
+
+    Args:
+        token: 交易对，如 BTCUSDT
+        type: futures | spot
+        interval: K 线周期，如 1m, 30m, 1h
+        at_time: 目标时间点（datetime/字符串/毫秒或秒时间戳）
+        limit: 拉取 K 线数量，默认 200
+
+    Returns:
+        {"status": "success"|"error", "kline_data": [单点], "metadata": {...}}
+    """
+    at_ms = _convert_to_timestamp_ms(at_time) if at_time is not None else None
+    if at_ms is None:
+        return {"status": "error", "error": "at_time is required", "kline_data": [], "metadata": {}}
+
+    get_fn = _get_fetch_fn(type)
+    klines_data = get_fn(
+        symbol=token,
+        interval=interval,
+        limit=min(limit, MAX_KLINES_PER_REQUEST),
+        end_time=at_ms + _get_interval_duration_ms(interval),
+        save_csv=False,
+        save_json=False,
+    )
+    if not klines_data:
+        return {
+            "status": "error",
+            "error": f"No kline data for token {token}",
+            "kline_data": [],
+            "metadata": {"token": token, "type": type, "interval": interval, "at_time": at_ms},
+        }
+
+    data_df = _klines_to_df(klines_data).sort_values("datetime").reset_index(drop=True)
+    mask = data_df["open_time"] <= at_ms
+    if not mask.any():
+        return _success_at_time(token, type, interval, at_ms, [], data_rows=len(data_df))
+    row_idx = int(data_df.index[mask][-1])
+    min_idx = max(max(c[2] for c in _get_factor_configs()) + 2, HISTORY_WINDOW)
+    if row_idx < min_idx:
+        return _success_at_time(
+            token, type, interval, at_ms, [],
+            reason="Insufficient history (need at least %s bars before point)" % HISTORY_WINDOW,
+        )
+
+    kline_data_with_factors = get_klines_with_factors(klines_data)
+    target_open_time = int(data_df.iloc[row_idx]["open_time"])
+    point_data = next((p for p in kline_data_with_factors if int(p["open_time"]) == target_open_time), None)
+    return _success_at_time(token, type, interval, at_ms, [point_data] if point_data else [], data_rows=len(data_df))
+
+
+def get_kline_with_factor_n_points(
+    token: str,
+    type: str = "futures",
+    interval: str = "30m",
+    n: int = 500,
+    end_time: Optional[Union[datetime, str, int]] = None,
+) -> Dict[str, Any]:
+    """
+    以某时间为 end_time 向前取 n 个点：先拉取 klines_data，再经 get_klines_with_factors 计算因子，
+    返回当前所有时间点的带因子数据。
+
+    Args:
+        token: 交易对
+        type: futures | spot
+        interval: K 线周期
+        n: 向前取的 K 线根数
+        end_time: 结束时间，默认 None 表示当前时间
+
+    Returns:
+        {"status": "success"|"error", "kline_data": [...], "metadata": {...}}
+    """
+    end_ms = int(datetime.now().timestamp() * 1000) if end_time is None else _convert_to_timestamp_ms(end_time)
+    if end_ms is None:
+        return {"status": "error", "error": "Invalid end_time", "kline_data": [], "metadata": {}}
+
+    interval_ms = _get_interval_duration_ms(interval)
+    start_ms = end_ms - (n + HISTORY_WINDOW) * interval_ms
+    data_df = _fetch_klines_by_range_paginated(
+        token=token, type=type, interval=interval,
+        start_ms=start_ms, end_ms=end_ms + interval_ms,
+    )
+    if data_df is None or data_df.empty:
+        return {
+            "status": "error",
+            "error": f"No kline data for token {token}",
+            "kline_data": [],
+            "metadata": {"token": token, "type": type, "interval": interval, "n": n},
+        }
+
+    klines_data = data_df.to_dict("records")
+    kline_data_with_factors = get_klines_with_factors(klines_data)
+    kline_data_with_factors = [p for p in kline_data_with_factors if int(p["open_time"]) <= end_ms][-n:]
+    return {
+        "status": "success",
+        "kline_data": kline_data_with_factors,
+        "metadata": {
+            "token": token, "type": type, "interval": interval, "n": n,
+            "end_time": end_ms,
+            "end_time_str": pd.to_datetime(end_ms, unit="ms").strftime("%Y-%m-%d %H:%M:%S"),
+            "start_time": start_ms,
+            "start_time_str": pd.to_datetime(start_ms, unit="ms").strftime("%Y-%m-%d %H:%M:%S"),
+            "total_kline_points": len(kline_data_with_factors),
+            "total_data_points": len(data_df),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# 测试脚本
+# ---------------------------------------------------------------------------
+
+
+def _value_equals(va: Any, vb: Any, rtol: float, atol: float) -> bool:
+    """递归比较两值是否在数值容差内一致（支持 dict/list/数值/其它）。"""
+    if isinstance(va, dict) and isinstance(vb, dict):
+        if set(va.keys()) != set(vb.keys()):
+            return False
+        return all(_value_equals(va[k], vb[k], rtol, atol) for k in va)
+    if isinstance(va, (list, tuple)) and isinstance(vb, (list, tuple)):
+        if len(va) != len(vb):
+            return False
+        return all(_value_equals(x, y, rtol, atol) for x, y in zip(va, vb))
+    if isinstance(va, (int, float)) and isinstance(vb, (int, float)):
+        try:
+            return bool(np.isclose(float(va), float(vb), rtol=rtol, atol=atol, equal_nan=True))
+        except (TypeError, ValueError):
+            return va == vb
+    return va == vb
+
+
+def _point_dict_equals(a: Dict[str, Any], b: Dict[str, Any], rtol: float = 1e-5, atol: float = 1e-8) -> bool:
+    """比较两条 K 线+因子记录是否一致（数值字段用容差比较，含嵌套 factors）。排除 time_index（两处 data_df 不同）。"""
+    keys_a, keys_b = set(a.keys()), set(b.keys())
+    if keys_a != keys_b:
+        return False
+    skip_keys = {"time_index"}  # 两处 data_df 行号不同，不参与比较
+    if int(a.get("open_time", 0)) != int(b.get("open_time", 0)):
+        return False
+    for k in a:
+        if k in skip_keys:
+            continue
+        if not _value_equals(a[k], b[k], rtol, atol):
+            return False
+    return True
+
+
+def _test_at_time_equals_n_points_last():
+    """
+    准则：同一份 klines_data 下，get_klines_with_factors_at_time 返回的最新一根
+    应与 get_klines_with_factors_n_points 返回的最后一根完全相同。
+    """
+    print("=" * 60)
+    print("测试: get_klines_with_factors_at_time 末条 == get_klines_with_factors_n_points 末条")
+    print("=" * 60)
+    token, type_, interval = "BTCUSDT", "futures", "1h"
+    at_time_str = "2026-01-30 8:00:00"
+    at_ms = _convert_to_timestamp_ms(at_time_str)
+
+    get_fn = _get_fetch_fn(type_)
+    klines_data = get_fn(
+        symbol=token,
+        interval=interval,
+        limit=min(200, MAX_KLINES_PER_REQUEST),
+        end_time=at_ms + _get_interval_duration_ms(interval),
+        save_csv=False,
+        save_json=False,
+    )
+    if not klines_data:
+        print("FAIL: 无法获取 klines_data")
+        return
+
+    at_list = get_klines_with_factors_at_time(klines_data)
+    n_list = get_klines_with_factors_n_points(klines_data)
+    if not at_list:
+        print("FAIL: get_klines_with_factors_at_time 返回空（可能历史不足）")
+        return
+    if not n_list:
+        print("FAIL: get_klines_with_factors_n_points 返回空")
+        return
+
+    at_point = at_list[0]
+    n_last = n_list[-1]
+    if int(at_point["open_time"]) != int(n_last["open_time"]):
+        print(
+            "FAIL: open_time 不一致 at_time=%s n_points_last=%s"
+            % (at_point["open_time"], n_last["open_time"])
+        )
+        return
+    if not _point_dict_equals(at_point, n_last):
+        print("FAIL: 两条记录内容不一致（数值容差内）")
+        print("at_time 首条 open_time:", at_point.get("open_time"))
+        print("n_points 末条 open_time:", n_last.get("open_time"))
+        return
+    print("PASS: get_klines_with_factors_at_time 单条 与 get_klines_with_factors_n_points 末条 完全相同")
+    print()
+
+
+def _test_get_kline_with_factor_at_time():
+    """测试 get_klines_with_factors_at_time：先获取 klines_data，再调用得到仅最新一根带因子数据."""
+    print("=" * 60)
+    print("测试: get_klines_with_factors_at_time（输入 klines_data，输出仅最新一根带因子）")
+    print("=" * 60)
+    token, type_, interval = "BTCUSDT", "futures", "1h"
+    at_time = "2026-01-30 8:00:00"
+    at_ms = _convert_to_timestamp_ms(at_time)
+
+    get_fn = _get_fetch_fn(type_)
+    klines_data = get_fn(
+        symbol=token,
+        interval=interval,
+        limit=min(200, MAX_KLINES_PER_REQUEST),
+        end_time=at_ms + _get_interval_duration_ms(interval),
+        save_csv=False,
+        save_json=False,
+    )
+    if not klines_data:
+        print("error: No kline data")
+        return
+
+    kline_data = get_klines_with_factors_at_time(klines_data)
+    print("at_time:", at_time)
+    print("status: success")
+    print("kline_data 条数:", len(kline_data), "(预期 0 或 1)")
+    if kline_data:
+        print("首条 keys:", list(kline_data[0].keys())[:10], "...")
+    print("metadata:", {"token": token, "type": type_, "interval": interval, "at_time": at_ms, "data_rows": len(klines_data)})
+    print()
+
+
+def _test_get_kline_with_factor_n_points():
+    """测试 get_klines_with_factors_n_points：先获取 klines_data，再调用得到所有带因子数据点."""
+    import os
+
+    print("=" * 60)
+    print("测试: get_klines_with_factors_n_points（输入 klines_data，输出所有带因子数据点）")
+    print("=" * 60)
+    token, type_, interval = "BTCUSDT", "futures", "1h"
+    n, end_time = 3000, "2026-01-30 8:00:00"
+    end_ms = _convert_to_timestamp_ms(end_time)
+    interval_ms = _get_interval_duration_ms(interval)
+    start_ms = end_ms - (n + HISTORY_WINDOW) * interval_ms
+
+    data_df = _fetch_klines_by_range_paginated(
+        token=token, type=type_, interval=interval,
+        start_ms=start_ms, end_ms=end_ms + interval_ms,
+    )
+    if data_df is None or data_df.empty:
+        print("error: No kline data")
+        return
+
+    klines_data = data_df.to_dict("records")
+    kline_data_with_factors = get_klines_with_factors_n_points(klines_data)
+    # 可选：只保留 open_time <= end_ms 的最后 n 条，便于与 n_points 语义对比
+    displayed = [p for p in kline_data_with_factors if int(p["open_time"]) <= end_ms][-n:]
+
+    print("n:", n, "end_time:", end_time)
+    print("status: success")
+    print("kline_data_with_factors 总条数:", len(kline_data_with_factors))
+    print("displayed (open_time<=end_ms 最后 n 条):", len(displayed))
+    if displayed:
+        first, last = displayed[0], displayed[-1]
+        print("首条 open_time:", first.get("open_time"), "末条 open_time:", last.get("open_time"))
+    print("metadata:", {"token": token, "type": type_, "interval": interval, "n": n, "end_time": end_ms})
+
+    save_dir = "/Users/user/Desktop/repo/crypto_trading/cyqnt_trd/tmp"
+    os.makedirs(save_dir, exist_ok=True)
+    save_path = os.path.join(save_dir, "get_kline_with_factor_n_points_result.parquet")
+    try:
+        pd.DataFrame(displayed).to_parquet(save_path, engine="pyarrow", index=False)
+        print(f"结果已保存: {save_path}")
+    except Exception as e:
+        print(f"保存 parquet 时出错: {e}")
+    print()
+
+
+if __name__ == "__main__":
+    _test_get_kline_with_factor_at_time()
+    _test_get_kline_with_factor_n_points()
+    _test_at_time_equals_n_points_last()
+    print("全部测试脚本执行完毕.")