Initial commit from Trae: Gradio Dashboard + Market Collector (Clean)

.gitignore

@@ -0,0 +1,34 @@
+# Data and Logs
+data/
+cache/
+系统日志/
+.deps/
+应用/
+策略仓库/
+4 号做市策略/
+
+# Data files
+*.h5
+*.parquet
+*.csv
+*.db
+*.sqlite
+*.pkl
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+env/
+venv/
+.env
+
+# IDEs
+.vscode/
+.idea/
+.trae/
+
+# Logs
+*.log

README.md

@@ -0,0 +1,35 @@
+# 量化交易统一系统 (Quant Unified)
+
+本仓库整合了所有量化交易相关的组件，包括管理应用、策略仓库、后端服务和基础库。
+
+## 目录结构 (中文化重构版)
+
+- **应用 (应用/)**: 各种管理与展示应用
+  - **qronos/**: 量化交易管理平台（Web 前端 + Python 后端）
+    - 提供策略管理、回测分析、实盘监控的网页界面。
+    - 启动方式: 
+      - 后端: `cd 应用/qronos && source .venv/bin/activate && python -X utf8 main.py`
+      - 前端: `cd 应用/qronos && npm run dev`
+
+- **策略仓库 (策略仓库/)**: 各种交易策略实现
+  - **二号网格策略/**: 网格交易策略实现，包含回测与实盘。
+    - 运行回测: `cd 策略仓库/二号网格策略 && python -X utf8 backtest.py`
+  - **一号择时策略/**: 包含选币和择时逻辑。
+  - **三号对冲策略/**: 双向对冲策略。
+
+- **服务 (服务/)**: 核心实盘与回测服务
+  - **firm/**: 实盘交易核心服务，提供底层交易、行情和评估功能。
+
+- **基础库 (基础库/)**: 项目通用的基础组件
+  - **common_core/**: 包含风控、配置加载、工具函数等核心模块。
+
+- **测试用例 (测试用例/)**: 单元测试与集成测试脚本。
+
+- **系统日志 (系统日志/)**: 统一存储各组件运行产生的日志。
+
+## 开发指南
+
+1. **环境准备**: 建议使用 Python 3.14+ 环境。
+2. **导入机制**: 项目使用了 `sitecustomize.py` 钩子，允许直接从顶级目录导入，例如 `import common_core` 或 `from 策略仓库.二号网格策略 import ...`。
+3. **编码规范**: 强制使用 UTF-8 编码。函数名、变量名推荐使用中文命名（符合“编程导师”教学规范）。
+4. **单体仓库**: 本仓库采用 Monorepo 结构，请直接在根目录打开 IDE 进行开发。

app.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""
+Quant_Unified 监控面板 (Gradio 版)
+这是一个运行在 Hugging Face Spaces 上的监控应用，它会：
+1. 在后台启动数据采集服务。
+2. 实时从 Supabase 获取并显示各个服务的运行状态。
+"""
+
+import gradio as gr
+import os
+import subprocess
+import time
+import pandas as pd
+from supabase import create_client
+from datetime import datetime
+import threading
+
+# ==========================================
+# 1. 配置与初始化
+# ==========================================
+SUPABASE_URL = os.getenv("SUPABASE_URL")
+SUPABASE_KEY = os.getenv("SUPABASE_SERVICE_ROLE_KEY") or os.getenv("SUPABASE_ANON_KEY")
+
+# 初始化 Supabase 客户端
+supabase = None
+if SUPABASE_URL and SUPABASE_KEY:
+    supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
+
+def 启动后台采集():
+    """在独立进程中启动采集脚本"""
+    print("🚀 正在启动后台采集服务...")
+    script_path = os.path.join("服务", "数据采集", "启动采集.py")
+    # 设置环境变量，确保子进程能找到项目根目录
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.getcwd()
+    # 使用 sys.executable 确保使用相同的 Python 解释器
+    import sys
+    process = subprocess.Popen(
+        [sys.executable, script_path],
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+        universal_newlines=True
+    )
+    # 实时打印日志到终端（HF 容器日志可见）
+    for line in process.stdout:
+        print(f"[Collector] {line.strip()}")
+
+# 启动后台线程
+thread = threading.Thread(target=启动后台采集, daemon=True)
+thread.start()
+
+# ==========================================
+# 2. UI 逻辑
+# ==========================================
+def 获取监控数据():
+    """从 Supabase 获取 service_status 表的所有数据"""
+    if not supabase:
+        return pd.DataFrame([{"错误": "未配置 SUPABASE_URL 或 KEY"}])
+    
+    try:
+        response = supabase.table("service_status").select("*").execute()
+        data = response.data
+        if not data:
+            return pd.DataFrame([{"信息": "目前没有服务在运行"}])
+        
+        # 转换为 DataFrame 方便展示
+        df = pd.DataFrame(data)
+        # 简单处理下时间格式
+        if "updated_at" in df.columns:
+            df["更新时间"] = pd.to_datetime(df["updated_at"]).dt.strftime('%Y-%m-%d %H:%M:%S')
+            df = df.drop(columns=["updated_at"])
+        
+        # 重命名列名，让高中生也能看懂
+        rename_map = {
+            "service_name": "服务名称",
+            "status": "状态",
+            "cpu_percent": "CPU使用率(%)",
+            "memory_percent": "内存使用率(%)",
+            "details": "详细信息"
+        }
+        df = df.rename(columns=rename_map)
+        return df
+    except Exception as e:
+        return pd.DataFrame([{"错误": f"获取数据失败: {str(e)}"}])
+
+# ==========================================
+# 3. 构建 Gradio 界面
+# ==========================================
+with gr.Blocks(title="Quant_Unified 监控中心", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🚀 Quant_Unified 量化系统监控中心")
+    gr.Markdown("实时展示部署在云端的采集服务状态。数据通过 Supabase 同步。")
+    
+    with gr.Row():
+        status_table = gr.DataFrame(label="服务状态列表", value=获取监控数据, every=5) # 每5秒刷新一次
+        
+    with gr.Row():
+        refresh_btn = gr.Button("手动刷新")
+        refresh_btn.click(获取监控数据, outputs=status_table)
+
+    gr.Markdown("---")
+    gr.Markdown("💡 **提示**：如果状态显示为 'ok'，说明后台采集正在正常工作。")
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

config.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""
+Quant_Unified 全局配置
+用于统一管理跨服务的常量参数
+"""
+
+import os
+
+# ==========================================
+# 1. 行情采集配置
+# ==========================================
+
+# 深度图档位 (支持 5, 10, 20, 50, 100)
+# 注意: 修改此值会影响采集器订阅的数据流以及数据存储的结构
+# 警告: 档位越高，数据量越大，带宽消耗越高
+DEPTH_LEVEL = 20
+
+# ==========================================
+# 2. 路径配置
+# ==========================================
+# 可以在这里统一定义数据根目录等

memory/user_global.md

@@ -0,0 +1,62 @@
+---
+trigger: always_on
+alwaysApply: true
+---
+
+# 核心角色与最高指令 (Core Identity & Prime Directives)
+
+## 1. 身份定位：双重人格
+你拥有双重身份，必须同时满足以下要求：
+*   **顶级全栈架构师 (The Architect)**：你只写业界最先进 (SOTA)、最优雅、性能最强及其“干净”的代码。代码风格对标 Apple/Google 首席工程师。
+*   **金牌编程导师 (The Mentor)**：你的用户是一名**只会中文的高中生**。
+    *   **教学义务**：你必须用“人话”和类比解释一切。
+    *   **术语禁忌**：遇到专业术语（如 Docker, IPC, AOT, Hydration 等）或英文缩写，**必须**立即展开解释其含义和作用，严禁直接堆砌名词。
+
+## 2. 核心原则
+*   **拒绝降级**：即使面对高中生，你也必须交付 **SOTA (业界顶尖)** 的技术方案。不要因为用户是初学者就提供简化版或过时的垃圾代码（MVP）。如果技术太难，你的任务是把它**解释清楚**，而不是把它**做烂**。
+*   **拒绝假数据**：**永远不允许**使用模拟数据 (Mock Data)。必须连接真实接口、数据库或文件系统。
+*   **显式运行**：**严禁静默运行**。任何脚本或程序的启动，必须在终端（Terminal）中有实时的日志输出。用户必须看到程序在“动”。
+
+---
+
+# 代码规范与工程标准 (Coding Standards)
+
+## 1. 中文化编程 (教学辅助)
+为了降低高中生的认知负荷，在**不导致语法错误**且**不影响运行**的前提下，强制执行：
+*   **中文命名**：函数名、变量名、类名**尽可能使用中文**。
+    *   *Good*: `def 计算移动平均线(价格列表):`
+    *   *Bad*: `def calc_ma(price_list):`
+*   **中文注释**：每个代码文件开头必须包含**中文文件头**，用通俗语言解释“这个文件是干嘛的”。代码内部逻辑必须通过中文注释解释“为什么这么写”。
+
+## 2. 前端标准 (React & UI)
+*   **React 编译器优先**：代码必须兼容并开启 **React Compiler**。避免使用过时的 `useMemo`/`useCallback` 手动优化（除非编译器无法处理），让代码更干净。
+*   **Apple 级审美**：默认扮演 Apple 顶级 UI 工程师。界面必须具有极致的审美、流畅的动画（Framer Motion）和高级的交互感。
+*   **TypeScript**：零容忍报错。自动修复所有红线，类型定义必须精准。
+*   **错误自愈**：编写前端自动化测试或脚本时，自动调用 `playwright` MCP 修复报错。
+
+## 3. Python 标准
+*   **执行环境**：默认使用 `python -X utf8` 运行，确保中文处理无乱码。
+*   **异常处理**：绝不“吞掉”错误。必须使用卫语句 (Guard Clauses) 提前拦截异常。
+
+---
+
+# 自动化工作流 (Automated Workflow)
+
+## 1. 环境与执行 (每次行动前检查)
+1.  **虚拟环境**：项目若无 venv，**优先**自动创建并激活。
+2.  **文件占用**：删除或写入文件前，检查句柄占用 (Handle check)。
+3.  **Git 自动化**：自主判断代码节点。认为有必要时（如完成一个功能模块），**自动执行 Git 提交**，无需频繁请示。
+
+## 2. 记忆与凭证
+*   **长期记忆**：自动使用 `memory` MCP 存储项目关键信息。
+*   **凭证管理**：记住关键密码（如 PostgreSQL 密码 `587376`），需要时自动填充，不要重复问用户。
+
+---
+
+# 沟通协议 (Communication Protocol)
+
+*   **思考与输出**：你可以用英文思考（Thinking Process），但**最终回复必须完全使用中文**。
+*   **解释风格**：
+    *   *场景*：解释 `Redis`。
+    *   *错误*：“Redis 是一个基于内存的 Key-Value 存储系统。”
+    *   *正确*：“Redis 就像是电脑的‘内存条’，也就是个**快取区**。我们要存东西时，先放这里，因为读写速度极快，比存到硬盘（数据库）里快几千倍。适合用来存那些大家频繁要看的数据。”

requirements.txt

@@ -0,0 +1,111 @@
+aiodns==3.6.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.13.2
+aiosignal==1.4.0
+aiosqlite==0.21.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.12.0
+attrs==25.4.0
+beautifulsoup4==4.14.3
+bleach==6.3.0
+ccxt==4.5.26
+certifi==2025.11.12
+cffi==2.0.0
+charset-normalizer==3.4.4
+click==8.3.1
+colorama==0.4.6
+contourpy==1.3.3
+cryptography==46.0.3
+cssselect==1.3.0
+cssutils==2.11.1
+cycler==0.12.1
+dataframe_image==0.2.7
+defusedxml==0.7.1
+ecdsa==0.19.1
+fastapi==0.124.2
+fastjsonschema==2.21.2
+fonttools==4.61.0
+frozenlist==1.8.0
+greenlet==3.3.0
+h11==0.16.0
+h5py==3.15.1
+hdf5plugin==6.0.0
+idna==3.11
+Jinja2==3.1.6
+jsonschema==4.25.1
+jsonschema-specifications==2025.9.1
+jupyter_client==8.7.0
+jupyter_core==5.9.1
+jupyterlab_pygments==0.3.0
+kiwisolver==1.4.9
+llvmlite==0.46.0
+lxml==6.0.2
+MarkupSafe==3.0.3
+matplotlib==3.10.7
+mistune==3.1.4
+more-itertools==10.8.0
+multidict==6.7.0
+narwhals==2.13.0
+nbclient==0.10.2
+nbconvert==7.16.6
+nbformat==5.10.4
+numba==0.63.1
+numpy==2.3.5
+packaging==25.0
+pandas==2.3.3
+pandocfilters==1.5.1
+pillow==12.0.0
+platformdirs==4.5.1
+playwright==1.57.0
+plotly==6.5.0
+propcache==0.4.1
+pyasn1==0.6.1
+pycares==4.11.0
+pycparser==2.23
+pycryptodome==3.23.0
+pydantic==2.12.5
+pydantic_core==2.41.5
+pyee==13.0.0
+Pygments==2.19.2
+pyotp==2.9.0
+pyparsing==3.2.5
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.1
+python-jose==3.5.0
+python-multipart==0.0.20
+python-socks==2.8.0
+pytz==2025.2
+pyzmq==27.1.0
+referencing==0.37.0
+requests==2.32.5
+rpds-py==0.30.0
+rsa==4.9.1
+scipy==1.16.3
+seaborn==0.13.2
+setuptools==80.9.0
+six==1.17.0
+soupsieve==2.8
+SQLAlchemy==2.0.45
+starlette==0.50.0
+tinycss2==1.4.0
+tornado==6.5.2
+tqdm==4.67.1
+traitlets==5.14.3
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+tzdata==2025.2
+urllib3==2.6.1
+uvicorn==0.38.0
+webencodings==0.5.1
+websockets
+supabase
+pyarrow
+gradio
+psutil
+python-dotenv
+websockets==15.0.1
+yarl==1.22.0
+supabase
+psutil
+pyarrow

sitecustomize.py

@@ -0,0 +1,27 @@
+"""
+Python 环境初始化钩子
+
+此文件会被 Python 的 site 模块自动加载（只要它在 sys.path 中）。
+它的主要作用是动态配置 sys.path，将项目的 libs, services, strategies, apps 等目录
+加入到模块搜索路径中。
+
+这样做的目的是：
+1. 允许项目内的代码直接通过 import 导入这些目录下的模块（如 import common_core）。
+2. 避免在每个脚本中手动编写 sys.path.append(...)。
+3. 简化开发环境配置，无需强制设置 PYTHONPATH 环境变量。
+"""
+import os
+import sys
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+_EXTRA = [
+    os.path.join(_ROOT, '基础库'),
+    os.path.join(_ROOT, '服务'),
+    os.path.join(_ROOT, '策略仓库'),
+    os.path.join(_ROOT, '4 号做市策略'),
+    os.path.join(_ROOT, '应用'),
+    os.path.join(_ROOT, '应用', 'qronos'),
+]
+for p in _EXTRA:
+    if os.path.isdir(p) and p not in sys.path:
+        sys.path.append(p)

基础库/common_core/__init__.py

@@ -0,0 +1,3 @@
+"""
+Quant Unified Common Core
+"""

基础库/common_core/backtest/__init__.py

@@ -0,0 +1,4 @@
+"""
+Quant Unified 量化交易系统
+__init__.py
+"""

基础库/common_core/backtest/equity.py

@@ -0,0 +1,360 @@
+"""
+Quant Unified 量化交易系统
+[核心资产计算模块]
+功能：负责根据策略信号、行情数据、费率等，计算资金曲线、持仓价值和爆仓风险。
+"""
+import time
+
+import numba as nb
+import numpy as np
+import pandas as pd
+
+from core.evaluate import strategy_evaluate
+from core.figure import draw_equity_curve_plotly
+from core.model.backtest_config import BacktestConfig
+from core.rebalance import RebAlways
+from core.simulator import Simulator
+from core.utils.functions import load_min_qty
+from core.utils.path_kit import get_file_path
+from update_min_qty import min_qty_path
+
+pd.set_option('display.max_rows', 1000)
+pd.set_option('expand_frame_repr', False)  # 当列太多时不换行
+
+
+def calc_equity(conf: BacktestConfig,
+                pivot_dict_spot: dict,
+                pivot_dict_swap: dict,
+                df_spot_ratio: pd.DataFrame,
+                df_swap_ratio: pd.DataFrame,
+                show_plot: bool = True):
+    """
+    计算回测结果的函数
+    :param conf: 回测配置
+    :param pivot_dict_spot: 现货行情数据
+    :param pivot_dict_swap: 永续合约行情数据
+    :param df_spot_ratio: 现货目标资金占比
+    :param df_swap_ratio: 永续合约目标资金占比
+    :param show_plot: 是否显示回测图
+    :return: 没有返回值
+    """
+    # ====================================================================================================
+    # 1. 数据预检和准备数据
+    # 数据预检，对齐所有数据的长度（防御性编程）
+    # ====================================================================================================
+    if len(df_spot_ratio) != len(df_swap_ratio) or np.any(df_swap_ratio.index != df_spot_ratio.index):
+        raise RuntimeError(f'数据长度不一致，现货数据长度：{len(df_spot_ratio)}, 永续合约数据长度：{len(df_swap_ratio)}')
+
+    # 开始时间列
+    candle_begin_times = df_spot_ratio.index.to_series().reset_index(drop=True)
+
+    # 获取现货和永续合约的币种，并且排序
+    spot_symbols = sorted(df_spot_ratio.columns)
+    swap_symbols = sorted(df_swap_ratio.columns)
+
+    # 裁切现货数据，保证open，close，vwap1m，对应的df中，现货币种、时间长度一致
+    pivot_dict_spot = align_pivot_dimensions(pivot_dict_spot, spot_symbols, candle_begin_times)
+
+    # 裁切合约数据，保证open，close，vwap1m，funding_fee对应的df中，合约币种、时间长度一致
+    pivot_dict_swap = align_pivot_dimensions(pivot_dict_swap, swap_symbols, candle_begin_times)
+
+    # 读入最小下单量数据
+    spot_lot_sizes = read_lot_sizes(min_qty_path / '最小下单量_spot.csv', spot_symbols)
+    swap_lot_sizes = read_lot_sizes(min_qty_path / '最小下单量_swap.csv', swap_symbols)
+
+    pos_calc = RebAlways(spot_lot_sizes.to_numpy(), swap_lot_sizes.to_numpy())
+
+    # ====================================================================================================
+    # 2. 开始模拟交易
+    # 开始策马奔腾啦 🐎
+    # ====================================================================================================
+    s_time = time.perf_counter()
+    equities, turnovers, fees, funding_fees, margin_rates, long_pos_values, short_pos_values = start_simulation(
+        init_capital=conf.initial_usdt,  # 初始资金，单位：USDT
+        leverage=conf.leverage,  # 杠杆
+        spot_lot_sizes=spot_lot_sizes.to_numpy(),  # 现货最小下单量
+        swap_lot_sizes=swap_lot_sizes.to_numpy(),  # 永续合约最小下单量
+        spot_c_rate=conf.spot_c_rate,  # 现货杠杆率
+        swap_c_rate=conf.swap_c_rate,  # 永续合约杠杆率
+        spot_min_order_limit=float(conf.spot_min_order_limit),  # 现货最小下单金额
+        swap_min_order_limit=float(conf.swap_min_order_limit),  # 永续合约最小下单金额
+        min_margin_rate=conf.margin_rate,  # 最低保证金比例
+        # 选股结果计算聚合得到的每个周期目标资金占比
+        spot_ratio=df_spot_ratio[spot_symbols].to_numpy(),  # 现货目标资金占比
+        swap_ratio=df_swap_ratio[swap_symbols].to_numpy(),  # 永续合约目标资金占比
+        # 现货行情数据
+        spot_open_p=pivot_dict_spot['open'].to_numpy(),  # 现货开盘价
+        spot_close_p=pivot_dict_spot['close'].to_numpy(),  # 现货收盘价
+        spot_vwap1m_p=pivot_dict_spot['vwap1m'].to_numpy(),  # 现货开盘一分钟均价
+        # 永续合约行情数据
+        swap_open_p=pivot_dict_swap['open'].to_numpy(),  # 永续合约开盘价
+        swap_close_p=pivot_dict_swap['close'].to_numpy(),  # 永续合约收盘价
+        swap_vwap1m_p=pivot_dict_swap['vwap1m'].to_numpy(),  # 永续合约开盘一分钟均价
+        funding_rates=pivot_dict_swap['funding_rate'].to_numpy(),  # 永续合约资金费率
+        pos_calc=pos_calc,  # 仓位计算
+    )
+    print(f'✅ 完成模拟交易，花费时间: {time.perf_counter() - s_time:.3f}秒')
+    print()
+
+    # ====================================================================================================
+    # 3. 回测结果汇总，并输出相关文件
+    # ====================================================================================================
+    print('🌀 开始生成回测统计结果...')
+    account_df = pd.DataFrame({
+        'candle_begin_time': candle_begin_times,
+        'equity': equities,
+        'turnover': turnovers,
+        'fee': fees,
+        'funding_fee': funding_fees,
+        'marginRatio': margin_rates,
+        'long_pos_value': long_pos_values,
+        'short_pos_value': short_pos_values
+    })
+
+    account_df['净值'] = account_df['equity'] / conf.initial_usdt
+    account_df['涨跌幅'] = account_df['净值'].pct_change()
+    account_df.loc[account_df['marginRatio'] < conf.margin_rate, '是否爆仓'] = 1
+    account_df['是否爆仓'].fillna(method='ffill', inplace=True)
+    account_df['是否爆仓'].fillna(value=0, inplace=True)
+
+    account_df.to_csv(conf.get_result_folder() / '资金曲线.csv', encoding='utf-8-sig')
+
+    # 策略评价
+    rtn, year_return, month_return, quarter_return = strategy_evaluate(account_df, net_col='净值', pct_col='涨跌幅')
+    conf.set_report(rtn.T)
+    rtn.to_csv(conf.get_result_folder() / '策略评价.csv', encoding='utf-8-sig')
+    year_return.to_csv(conf.get_result_folder() / '年度账户收益.csv', encoding='utf-8-sig')
+    quarter_return.to_csv(conf.get_result_folder() / '季度账户收益.csv', encoding='utf-8-sig')
+    month_return.to_csv(conf.get_result_folder() / '月度账户收益.csv', encoding='utf-8-sig')
+
+    if show_plot:
+        # 绘制资金曲线
+        all_swap = pd.read_pickle(get_file_path('data', 'candle_data_dict.pkl'))
+        btc_df = all_swap['BTC-USDT']
+        account_df = pd.merge(left=account_df, right=btc_df[['candle_begin_time', 'close']], on=['candle_begin_time'],
+                              how='left')
+        account_df['close'].fillna(method='ffill', inplace=True)
+        account_df['BTC涨跌幅'] = account_df['close'].pct_change()
+        account_df['BTC涨跌幅'].fillna(value=0, inplace=True)
+        account_df['BTC资金曲线'] = (account_df['BTC涨跌幅'] + 1).cumprod()
+        del account_df['close'], account_df['BTC涨跌幅']
+
+        print(f"🎯 策略评价================\n{rtn}")
+        print(f"🗓️ 分年收益率================\n{year_return}")
+
+        print(f'💰 总手续费: {account_df["fee"].sum():,.2f}USDT')
+        print()
+
+        print('🌀 开始绘制资金曲线...')
+        eth_df = all_swap['ETH-USDT']
+        account_df = pd.merge(left=account_df, right=eth_df[['candle_begin_time', 'close']], on=['candle_begin_time'],
+                              how='left')
+        account_df['close'].fillna(method='ffill', inplace=True)
+        account_df['ETH涨跌幅'] = account_df['close'].pct_change()
+        account_df['ETH涨跌幅'].fillna(value=0, inplace=True)
+        account_df['ETH资金曲线'] = (account_df['ETH涨跌幅'] + 1).cumprod()
+        del account_df['close'], account_df['ETH涨跌幅']
+
+        account_df['long_pos_ratio'] = account_df['long_pos_value'] / account_df['equity']
+        account_df['short_pos_ratio'] = account_df['short_pos_value'] / account_df['equity']
+        account_df['empty_ratio'] = (conf.leverage - account_df['long_pos_ratio'] - account_df['short_pos_ratio']).clip(
+            lower=0)
+        # 计算累计值，主要用于后面画图使用
+        account_df['long_cum'] = account_df['long_pos_ratio']
+        account_df['short_cum'] = account_df['long_pos_ratio'] + account_df['short_pos_ratio']
+        account_df['empty_cum'] = conf.leverage  # 空仓占比始终为 1（顶部）
+        # 选币数量
+        df_swap_ratio = df_swap_ratio * conf.leverage
+        df_spot_ratio = df_spot_ratio * conf.leverage
+
+        symbol_long_num = df_spot_ratio[df_spot_ratio > 0].count(axis=1) + df_swap_ratio[df_swap_ratio > 0].count(
+            axis=1)
+        account_df['symbol_long_num'] = symbol_long_num.values
+        symbol_short_num = df_spot_ratio[df_spot_ratio < 0].count(axis=1) + df_swap_ratio[df_swap_ratio < 0].count(
+            axis=1)
+        account_df['symbol_short_num'] = symbol_short_num.values
+
+        # 生成画图数据字典，可以画出所有offset资金曲线以及各个offset资金曲线
+        data_dict = {'多空资金曲线': '净值', 'BTC资金曲线': 'BTC资金曲线', 'ETH资金曲线': 'ETH资金曲线'}
+        right_axis = {'多空最大回撤': '净值dd2here'}
+
+        # 如果画多头、空头资金曲线，同时也会画上回撤曲线
+        pic_title = f"CumNetVal:{rtn.at['累积净值', 0]}, Annual:{rtn.at['年化收益', 0]}, MaxDrawdown:{rtn.at['最大回撤', 0]}"
+        pic_desc = conf.get_fullname()
+        # 调用画图函数
+        draw_equity_curve_plotly(account_df, data_dict=data_dict, date_col='candle_begin_time', right_axis=right_axis,
+                                 title=pic_title, desc=pic_desc, path=conf.get_result_folder() / '资金曲线.html',
+                                 show_subplots=True)
+
+
+def read_lot_sizes(path, symbols):
+    """
+    读取每个币种的最小下单量
+    :param path: 文件路径
+    :param symbols:  币种列表
+    :return:
+    """
+    default_min_qty, min_qty_dict = load_min_qty(path)
+    lot_sizes = 0.1 ** pd.Series(min_qty_dict)
+    lot_sizes = lot_sizes.reindex(symbols, fill_value=0.1 ** default_min_qty)
+    return lot_sizes
+
+
+def align_pivot_dimensions(market_pivot_dict, symbols, candle_begin_times):
+    """
+    对不同维度的数据进行对齐
+    :param market_pivot_dict: 原始数据，是一个dict哦
+    :param symbols: 币种（列）
+    :param candle_begin_times: 时间（行）
+    :return:
+    """
+    return {k: df.loc[candle_begin_times, symbols] for k, df in market_pivot_dict.items()}
+
+
+@nb.njit
+def calc_lots(equity, close_prices, ratios, lot_sizes):
+    """
+    计算每个币种的目标手数
+    :param equity: 总权益
+    :param close_prices: 收盘价
+    :param ratios: 每个币种的资金比例
+    :param lot_sizes: 每个币种的最小下单量
+    :return: 每个币种的目标手数
+    """
+    pos_equity = equity * ratios
+    mask = np.abs(pos_equity) > 0.01
+    target_lots = np.zeros(len(close_prices), dtype=np.int64)
+    target_lots[mask] = (pos_equity[mask] / close_prices[mask] / lot_sizes[mask]).astype(np.int64)
+    return target_lots
+
+
+@nb.jit(nopython=True, boundscheck=True)
+def start_simulation(init_capital, leverage, spot_lot_sizes, swap_lot_sizes, spot_c_rate, swap_c_rate,
+                     spot_min_order_limit, swap_min_order_limit, min_margin_rate, spot_ratio, swap_ratio,
+                     spot_open_p, spot_close_p, spot_vwap1m_p, swap_open_p, swap_close_p, swap_vwap1m_p,
+                     funding_rates, pos_calc):
+    """
+    模拟交易
+    :param init_capital: 初始资金
+    :param leverage: 杠杆
+    :param spot_lot_sizes: spot 现货的最小下单量
+    :param swap_lot_sizes: swap 合约的最小下单量
+    :param spot_c_rate: spot 现货的手续费率
+    :param swap_c_rate: swap 合约的手续费率
+    :param spot_min_order_limit: spot 现货最小下单金额
+    :param swap_min_order_limit: swap 合约最小下单金额
+    :param min_margin_rate: 维持保证金率
+    :param spot_ratio: spot 的仓位透视表 (numpy 矩阵)
+    :param swap_ratio: swap 的仓位透视表 (numpy 矩阵)
+    :param spot_open_p: spot 的开仓价格透视表 (numpy 矩阵)
+    :param spot_close_p: spot 的平仓价格透视表 (numpy 矩阵)
+    :param spot_vwap1m_p: spot 的 vwap1m 价格透视表 (numpy 矩阵)
+    :param swap_open_p: swap 的开仓价格透视表 (numpy 矩阵)
+    :param swap_close_p: swap 的平仓价格透视表 (numpy 矩阵)
+    :param swap_vwap1m_p: swap 的 vwap1m 价格透视表 (numpy 矩阵)
+    :param funding_rates: swap 的 funding rate 透视表 (numpy 矩阵)
+    :param pos_calc: 仓位计算
+    :return:
+    """
+    # ====================================================================================================
+    # 1. 初始化回测空间
+    # 设置几个固定长度的数组变量，并且重置为0，到时候每一个周期的数据，都按照index的顺序，依次填充进去
+    # ====================================================================================================
+    n_bars = spot_ratio.shape[0]
+    n_syms_spot = spot_ratio.shape[1]
+    n_syms_swap = swap_ratio.shape[1]
+
+    start_lots_spot = np.zeros(n_syms_spot, dtype=np.int64)
+    start_lots_swap = np.zeros(n_syms_swap, dtype=np.int64)
+    # 现货不设置资金费
+    funding_rates_spot = np.zeros(n_syms_spot, dtype=np.float64)
+
+    turnovers = np.zeros(n_bars, dtype=np.float64)
+    fees = np.zeros(n_bars, dtype=np.float64)
+    equities = np.zeros(n_bars, dtype=np.float64)  # equity after execution
+    funding_fees = np.zeros(n_bars, dtype=np.float64)
+    margin_rates = np.zeros(n_bars, dtype=np.float64)
+    long_pos_values = np.zeros(n_bars, dtype=np.float64)
+    short_pos_values = np.zeros(n_bars, dtype=np.float64)
+
+    # ====================================================================================================
+    # 2. 初始化模拟对象
+    # ====================================================================================================
+    sim_spot = Simulator(init_capital, spot_lot_sizes, spot_c_rate, 0.0, start_lots_spot, spot_min_order_limit)
+    sim_swap = Simulator(0, swap_lot_sizes, swap_c_rate, 0.0, start_lots_swap, swap_min_order_limit)
+
+    # ====================================================================================================
+    # 3. 开始回测
+    # 每次循环包含以下四个步骤：
+    # 1. 模拟开盘on_open
+    # 2. 模拟执行on_execution
+    # 3. 模拟平仓on_close
+    # 4. 设置目标仓位set_target_lots
+    # 如下依次执行
+    # t1: on_open -> on_execution -> on_close -> set_target_lots
+    # t2: on_open -> on_execution -> on_close -> set_target_lots
+    # t3: on_open -> on_execution -> on_close -> set_target_lots
+    # ...
+    # tN: on_open -> on_execution -> on_close -> set_target_lots
+    # 并且在每一个t时刻，都会记录账户的截面数据，包括equity，funding_fee，margin_rate，等等
+    # ====================================================================================================
+    #
+    for i in range(n_bars):
+        """1. 模拟开盘on_open"""
+        # 根据开盘价格，计算账户权益，当前持仓的名义价值，以及资金费
+        equity_spot, _, pos_value_spot = sim_spot.on_open(spot_open_p[i], funding_rates_spot, spot_open_p[i])
+        equity_swap, funding_fee, pos_value_swap = sim_swap.on_open(swap_open_p[i], funding_rates[i], swap_open_p[i])
+
+        # 当前持仓的名义价值
+        position_val = np.sum(np.abs(pos_value_spot)) + np.sum(np.abs(pos_value_swap))
+        if position_val < 1e-8:
+            # 没有持仓
+            margin_rate = 10000.0
+        else:
+            margin_rate = (equity_spot + equity_swap) / float(position_val)
+
+        # 当前保证金率小于维持保证金率，爆仓 💀
+        if margin_rate < min_margin_rate:
+            margin_rates[i] = margin_rate
+            break
+
+        """2. 模拟开仓on_execution"""
+        # 根据开仓价格，计算账户权益，换手，手续费
+        equity_spot, turnover_spot, fee_spot = sim_spot.on_execution(spot_vwap1m_p[i])
+        equity_swap, turnover_swap, fee_swap = sim_swap.on_execution(swap_vwap1m_p[i])
+
+        """3. 模拟K线结束on_close"""
+        # 根据收盘价格，计算账户权益
+        equity_spot_close, pos_value_spot_close = sim_spot.on_close(spot_close_p[i])
+        equity_swap_close, pos_value_swap_close = sim_swap.on_close(swap_close_p[i])
+
+        long_pos_value = (np.sum(pos_value_spot_close[pos_value_spot_close > 0]) +
+                          np.sum(pos_value_swap_close[pos_value_swap_close > 0]))
+
+        short_pos_value = -(np.sum(pos_value_spot_close[pos_value_spot_close < 0]) +
+                            np.sum(pos_value_swap_close[pos_value_swap_close < 0]))
+
+        # 把中间结果更新到之前初始化的空间
+        funding_fees[i] = funding_fee
+        equities[i] = equity_spot + equity_swap
+        turnovers[i] = turnover_spot + turnover_swap
+        fees[i] = fee_spot + fee_swap
+        margin_rates[i] = margin_rate
+        long_pos_values[i] = long_pos_value
+        short_pos_values[i] = short_pos_value
+
+        # 考虑杠杆
+        equity_leveraged = (equity_spot_close + equity_swap_close) * leverage
+
+        """4. 计算目标持仓"""
+        # target_lots_spot = calc_lots(equity_leveraged, spot_close_p[i], spot_ratio[i], spot_lot_sizes)
+        # target_lots_swap = calc_lots(equity_leveraged, swap_close_p[i], swap_ratio[i], swap_lot_sizes)
+
+        target_lots_spot, target_lots_swap = pos_calc.calc_lots(equity_leveraged,
+                                                                spot_close_p[i], sim_spot.lots, spot_ratio[i],
+                                                                swap_close_p[i], sim_swap.lots, swap_ratio[i])
+        # 更新目标持仓
+        sim_spot.set_target_lots(target_lots_spot)
+        sim_swap.set_target_lots(target_lots_swap)
+
+    return equities, turnovers, fees, funding_fees, margin_rates, long_pos_values, short_pos_values

基础库/common_core/backtest/evaluate.py

@@ -0,0 +1,97 @@
+"""
+Quant Unified 量化交易系统
+[策略绩效评估模块]
+功能：计算年化收益、最大回撤、夏普比率、胜率等关键指标，并生成分月/分年收益表。
+"""
+import itertools
+
+import numpy as np
+import pandas as pd
+
+
+# 计算策略评价指标
+def strategy_evaluate(equity, net_col='多空资金曲线', pct_col='本周期多空涨跌幅'):
+    """
+    回测评价函数
+    :param equity: 资金曲线数据
+    :param net_col: 资金曲线列名
+    :param pct_col: 周期涨跌幅列名
+    :return:
+    """
+    # ===新建一个dataframe保存回测指标
+    results = pd.DataFrame()
+
+    # 将数字转为百分数
+    def num_to_pct(value):
+        return '%.2f%%' % (value * 100)
+
+    # ===计算累积净值
+    results.loc[0, '累积净值'] = round(equity[net_col].iloc[-1], 2)
+
+    # ===计算年化收益
+    annual_return = (equity[net_col].iloc[-1]) ** (
+            '1 days 00:00:00' / (equity['candle_begin_time'].iloc[-1] - equity['candle_begin_time'].iloc[0]) * 365) - 1
+    results.loc[0, '年化收益'] = num_to_pct(annual_return)
+
+    # ===计算最大回撤，最大回撤的含义：《如何通过3行代码计算最大回撤》https://mp.weixin.qq.com/s/Dwt4lkKR_PEnWRprLlvPVw
+    # 计算当日之前的资金曲线的最高点
+    equity[f'{net_col.split("资金曲线")[0]}max2here'] = equity[net_col].expanding().max()
+    # 计算到历史最高值到当日的跌幅，drowdwon
+    equity[f'{net_col.split("资金曲线")[0]}dd2here'] = equity[net_col] / equity[f'{net_col.split("资金曲线")[0]}max2here'] - 1
+    # 计算最大回撤，以及最大回撤结束时间
+    end_date, max_draw_down = tuple(equity.sort_values(by=[f'{net_col.split("资金曲线")[0]}dd2here']).iloc[0][['candle_begin_time', f'{net_col.split("资金曲线")[0]}dd2here']])
+    # 计算最大回撤开始时间
+    start_date = equity[equity['candle_begin_time'] <= end_date].sort_values(by=net_col, ascending=False).iloc[0]['candle_begin_time']
+    results.loc[0, '最大回撤'] = num_to_pct(max_draw_down)
+    results.loc[0, '最大回撤开始时间'] = str(start_date)
+    results.loc[0, '最大回撤结束时间'] = str(end_date)
+    # ===年化收益/回撤比：我个人比较关注的一个指标
+    results.loc[0, '年化收益/回撤比'] = round(annual_return / abs(max_draw_down), 2)
+    # ===统计每个周期
+    results.loc[0, '盈利周期数'] = len(equity.loc[equity[pct_col] > 0])  # 盈利笔数
+    results.loc[0, '亏损周期数'] = len(equity.loc[equity[pct_col] <= 0])  # 亏损笔数
+    results.loc[0, '胜率'] = num_to_pct(results.loc[0, '盈利周期数'] / len(equity))  # 胜率
+    results.loc[0, '每周期平均收益'] = num_to_pct(equity[pct_col].mean())  # 每笔交易平均盈亏
+    results.loc[0, '盈亏收益比'] = round(equity.loc[equity[pct_col] > 0][pct_col].mean() / equity.loc[equity[pct_col] <= 0][pct_col].mean() * (-1), 2)  # 盈亏比
+    if 1 in equity['是否爆仓'].to_list():
+        results.loc[0, '盈亏收益比'] = 0
+    results.loc[0, '单周期最大盈利'] = num_to_pct(equity[pct_col].max())  # 单笔最大盈利
+    results.loc[0, '单周期大亏损'] = num_to_pct(equity[pct_col].min())  # 单笔最大亏损
+
+    # ===连续盈利亏损
+    results.loc[0, '最大连续盈利周期数'] = max(
+        [len(list(v)) for k, v in itertools.groupby(np.where(equity[pct_col] > 0, 1, np.nan))])  # 最大连续盈利次数
+    results.loc[0, '最大连续亏损周期数'] = max(
+        [len(list(v)) for k, v in itertools.groupby(np.where(equity[pct_col] <= 0, 1, np.nan))])  # 最大连续亏损次数
+
+    # ===其他评价指标
+    results.loc[0, '收益率标准差'] = num_to_pct(equity[pct_col].std())
+
+    # ===每年、每月收益率
+    temp = equity.copy()
+    temp.set_index('candle_begin_time', inplace=True)
+    year_return = temp[[pct_col]].resample(rule='YE').apply(lambda x: (1 + x).prod() - 1)
+    month_return = temp[[pct_col]].resample(rule='ME').apply(lambda x: (1 + x).prod() - 1)
+    quarter_return = temp[[pct_col]].resample(rule='QE').apply(lambda x: (1 + x).prod() - 1)
+
+    def num2pct(x):
+        if str(x) != 'nan':
+            return str(round(x * 100, 2)) + '%'
+        else:
+            return x
+
+    year_return['涨跌幅'] = year_return[pct_col].apply(num2pct)
+    month_return['涨跌幅'] = month_return[pct_col].apply(num2pct)
+    quarter_return['涨跌幅'] = quarter_return[pct_col].apply(num2pct)
+
+    # # 对每月收益进行处理，做成二维表
+    # month_return.reset_index(inplace=True)
+    # month_return['year'] = month_return['candle_begin_time'].dt.year
+    # month_return['month'] = month_return['candle_begin_time'].dt.month
+    # month_return.set_index(['year', 'month'], inplace=True)
+    # del month_return['candle_begin_time']
+    # month_return_all = month_return[pct_col].unstack()
+    # month_return_all.loc['mean'] = month_return_all.mean(axis=0)
+    # month_return_all = month_return_all.apply(lambda x: x.apply(num2pct))
+
+    return results.T, year_return, month_return, quarter_return

基础库/common_core/backtest/figure.py

@@ -0,0 +1,230 @@
+"""
+Quant Unified 量化交易系统
+figure.py
+"""
+
+import pandas as pd
+import plotly.graph_objects as go
+import seaborn as sns
+from matplotlib import pyplot as plt
+from plotly import subplots
+from plotly.offline import plot
+from plotly.subplots import make_subplots
+from pathlib import Path
+
+
+def draw_equity_curve_plotly(df, data_dict, date_col=None, right_axis=None, pic_size=None, chg=False,
+                             title=None, path=Path('data') / 'pic.html', show=True, desc=None,
+                             show_subplots=False, markers=None, right_axis_lines=None):
+    """
+    绘制策略曲线
+    :param df: 包含净值数据的df
+    :param data_dict: 要展示的数据字典格式：｛图片上显示的名字:df中的列名｝
+    :param date_col: 时间列的名字，如果为None将用索引作为时间列
+    :param right_axis: 右轴数据 (区域图/面积图) ｛图片上显示的名字:df中的列名｝
+    :param pic_size: 图片的尺寸
+    :param chg: datadict中的数据是否为涨跌幅，True表示涨跌幅，False表示净值
+    :param title: 标题
+    :param path: 图片路径
+    :param show: 是否打开图片
+    :param right_axis_lines: 右轴数据 (线图) ｛图片上显示的名字:df中的列名｝
+    :return:
+    """
+    if pic_size is None:
+        pic_size = [1500, 800]
+
+    draw_df = df.copy()
+
+    # 设置时间序列
+    if date_col:
+        time_data = draw_df[date_col]
+    else:
+        time_data = draw_df.index
+
+    # 绘制左轴数据
+    fig = make_subplots(
+        rows=3 if show_subplots else 1, cols=1,
+        shared_xaxes=True,  # 共享 x 轴，主，子图共同变化
+        vertical_spacing=0.02,  # 减少主图和子图之间的间距
+        row_heights=[0.8, 0.1, 0.1] if show_subplots else [1.0],  # 主图高度占 70%，子图各占 10%
+        specs=[[{"secondary_y": True}], [{"secondary_y": False}], [{"secondary_y": False}]] if show_subplots else [[{"secondary_y": True}]]
+    )
+    for key in data_dict:
+        if chg:
+            draw_df[data_dict[key]] = (draw_df[data_dict[key]] + 1).fillna(1).cumprod()
+        fig.add_trace(go.Scatter(x=time_data, y=draw_df[data_dict[key]], name=key, ), row=1, col=1)
+
+    # 绘制右轴数据 (面积图 - 通常用于回撤)
+    if right_axis:
+        key = list(right_axis.keys())[0]
+        fig.add_trace(go.Scatter(x=time_data, y=draw_df[right_axis[key]], name=key + '(右轴)',
+                                 #  marker=dict(color='rgba(220, 220, 220, 0.8)'),
+                                 marker_color='orange',
+                                 opacity=0.1, line=dict(width=0),
+                                 fill='tozeroy',
+                                 yaxis='y2'))  # 标明设置一个不同于trace1的一个坐标轴
+        for key in list(right_axis.keys())[1:]:
+            fig.add_trace(go.Scatter(x=time_data, y=draw_df[right_axis[key]], name=key + '(右轴)',
+                                     #  marker=dict(color='rgba(220, 220, 220, 0.8)'),
+                                     opacity=0.1, line=dict(width=0),
+                                     fill='tozeroy',
+                                     yaxis='y2'))  # 标明设置一个不同于trace1的一个坐标轴
+
+    # 绘制右轴数据 (线图 - 通常用于价格)
+    if right_axis_lines:
+        for key in right_axis_lines:
+            fig.add_trace(go.Scatter(x=time_data, y=draw_df[right_axis_lines[key]], name=key + '(右轴)',
+                                     mode='lines',
+                                     line=dict(width=1.5, color='rgba(46, 204, 113, 0.9)'),
+                                     opacity=0.9,
+                                     yaxis='y2'))
+
+    if markers:
+        for m in markers:
+            fig.add_trace(go.Scatter(
+                x=[m['time']],
+                y=[m['price']],
+                mode='markers+text',
+                name=m.get('text', 'Marker'),
+                text=[m.get('text', '')],
+                textposition="top center",
+                marker=dict(
+                    symbol=m.get('symbol', 'x'),
+                    size=m.get('size', 15),
+                    color=m.get('color', 'red'),
+                    line=dict(width=2, color='white')
+                ),
+                yaxis='y2' if m.get('on_right_axis', False) else 'y1'
+            ), row=1, col=1, secondary_y=m.get('on_right_axis', False))
+
+    if show_subplots:
+        # 子图：按照 matplotlib stackplot 风格实现堆叠图
+        # 最下面是多头仓位占比
+        fig.add_trace(go.Scatter(
+            x=time_data,
+            y=draw_df['long_cum'],
+            mode='lines',
+            line=dict(width=0),
+            fill='tozeroy',
+            fillcolor='rgba(30, 177, 0, 0.6)',
+            name='多头仓位占比',
+            hovertemplate="多头仓位占比: %{customdata:.4f}<extra></extra>",
+            customdata=draw_df['long_pos_ratio']  # 使用原始比例值
+        ), row=2, col=1)
+
+        # 中间是空头仓位占比
+        fig.add_trace(go.Scatter(
+            x=time_data,
+            y=draw_df['short_cum'],
+            mode='lines',
+            line=dict(width=0),
+            fill='tonexty',
+            fillcolor='rgba(255, 99, 77, 0.6)',
+            name='空头仓位占比',
+            hovertemplate="空头仓位占比: %{customdata:.4f}<extra></extra>",
+            customdata=draw_df['short_pos_ratio']  # 使用原始比例值
+        ), row=2, col=1)
+
+        # 最上面是空仓占比
+        fig.add_trace(go.Scatter(
+            x=time_data,
+            y=draw_df['empty_cum'],
+            mode='lines',
+            line=dict(width=0),
+            fill='tonexty',
+            fillcolor='rgba(0, 46, 77, 0.6)',
+            name='空仓占比',
+            hovertemplate="空仓占比: %{customdata:.4f}<extra></extra>",
+            customdata=draw_df['empty_ratio']  # 使用原始比例值
+        ), row=2, col=1)
+
+        # 子图：右轴绘制 long_short_ratio 曲线
+        fig.add_trace(go.Scatter(
+            x=time_data,
+            y=draw_df['symbol_long_num'],
+            name='多头选币数量',
+            mode='lines',
+            line=dict(color='rgba(30, 177, 0, 0.6)', width=2)
+        ), row=3, col=1)
+
+        fig.add_trace(go.Scatter(
+            x=time_data,
+            y=draw_df['symbol_short_num'],
+            name='空头选币数量',
+            mode='lines',
+            line=dict(color='rgba(255, 99, 77, 0.6)', width=2)
+        ), row=3, col=1)
+
+        # 更新子图标题
+        fig.update_yaxes(title_text="仓位占比", row=2, col=1)
+        fig.update_yaxes(title_text="选币数量", row=3, col=1)
+
+    fig.update_layout(template="none", width=pic_size[0], height=pic_size[1], title_text=title,
+                      hovermode="x unified", hoverlabel=dict(bgcolor='rgba(255,255,255,0.5)', ),
+                      font=dict(family="PingFang SC, Hiragino Sans GB, Songti SC, Arial, sans-serif", size=12),
+                      annotations=[
+                          dict(
+                              text=desc,
+                              xref='paper',
+                              yref='paper',
+                              x=0.5,
+                              y=1.05,
+                              showarrow=False,
+                              font=dict(size=12, color='black'),
+                              align='center',
+                              bgcolor='rgba(255,255,255,0.8)',
+                          )
+                      ]
+                      )
+    fig.update_layout(
+        updatemenus=[
+            dict(
+                buttons=[
+                    dict(label="线性 y轴",
+                         method="relayout",
+                         args=[{"yaxis.type": "linear"}]),
+                    dict(label="对数 y轴",
+                         method="relayout",
+                         args=[{"yaxis.type": "log"}]),
+                ])],
+    )
+    plot(figure_or_data=fig, filename=str(path.resolve()), auto_open=False)
+
+    fig.update_yaxes(
+        showspikes=True, spikemode='across', spikesnap='cursor', spikedash='solid', spikethickness=1,  # 峰线
+    )
+    fig.update_xaxes(
+        showspikes=True, spikemode='across+marker', spikesnap='cursor', spikedash='solid', spikethickness=1,  # 峰线
+    )
+
+    # 打开图片的html文件，需要判断系统的类型
+    if show:
+        fig.show()
+
+
+def plotly_plot(draw_df: pd.DataFrame, save_dir: str, name: str):
+    rows = len(draw_df.columns)
+    s = (1 / (rows - 1)) * 0.5
+    fig = subplots.make_subplots(rows=rows, cols=1, shared_xaxes=True, shared_yaxes=True, vertical_spacing=s)
+
+    for i, col_name in enumerate(draw_df.columns):
+        trace = go.Bar(x=draw_df.index, y=draw_df[col_name], name=f"{col_name}")
+        fig.add_trace(trace, i + 1, 1)
+        # 更新每个子图的x轴属性
+        fig.update_xaxes(showticklabels=True, row=i + 1, col=1)  # 旋转x轴标签以避免重叠
+
+    # 更新每个子图的y轴标题
+    for i, col_name in enumerate(draw_df.columns):
+        fig.update_xaxes(title_text=col_name, row=i + 1, col=1)
+
+    fig.update_layout(height=200 * rows, showlegend=True, title_text=name)
+    fig.write_html(str((Path(save_dir) / f"{name}.html").resolve()))
+    fig.show()
+
+
+def mat_heatmap(draw_df: pd.DataFrame, name: str):
+    sns.set()  # 设置一下展示的主题和样式
+    plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS', 'DejaVu Sans', 'Font 119']
+    plt.title(name)  # 设置标题
+    sns.heatmap(draw_df, annot=True, xticklabels=draw_df.columns, yticklabels=draw_df.index, fmt='.2f')  # 画图
+    plt.show()

基础库/common_core/backtest/metrics.py

@@ -0,0 +1,478 @@
+# -*- coding: utf-8 -*-
+"""
+Quant Unified 量化交易系统
+[统一回测指标模块]
+
+功能：
+    为所有策略提供统一的回测绩效指标计算，避免重复开发。
+    一次计算，处处复用 —— 所有策略（1-8号）都调用这个模块。
+
+支持的指标：
+    - 年化收益率 (CAGR)
+    - 对数收益率 (Log Return)
+    - 最大回撤 (Max Drawdown)
+    - 最大回撤恢复时间 (Recovery Time)
+    - 卡玛比率 (Calmar Ratio)
+    - 夏普比率 (Sharpe Ratio)
+    - 索提诺比率 (Sortino Ratio)
+    - 胜率 (Win Rate)
+    - 盈亏比 (Profit Factor)
+    - 交易次数 (Trade Count)
+
+使用方法：
+    ```python
+    from 基础库.common_core.backtest.metrics import 回测指标计算器
+
+    # 方式1: 传入权益曲线数组
+    计算器 = 回测指标计算器(权益曲线=equity_values, 初始资金=10000)
+    计算器.打印报告()
+    指标字典 = 计算器.获取指标()
+
+    # 方式2: 传入 DataFrame (需包含 equity 列)
+    计算器 = 回测指标计算器.从DataFrame创建(df, 权益列名='equity')
+    计算器.打印报告()
+    ```
+"""
+
+import numpy as np
+import pandas as pd
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Union, List
+from datetime import timedelta
+
+
+@dataclass
+class 回测指标结果:
+    """回测指标结果数据类"""
+    # 基础信息
+    初始资金: float = 0.0
+    最终资金: float = 0.0
+    总收益: float = 0.0
+    总收益率: float = 0.0
+    
+    # 收益指标
+    年化收益率: float = 0.0           # CAGR
+    对数收益率: float = 0.0           # Log Return
+    
+    # 风险指标
+    最大回撤: float = 0.0             # Max Drawdown (负数)
+    最大回撤百分比: str = ""          # 格式化显示
+    最大回撤开始时间: Optional[str] = None
+    最大回撤结束时间: Optional[str] = None
+    最大回撤恢复时间: Optional[str] = None  # 恢复到前高的时间
+    最大回撤恢复天数: int = 0
+    
+    # 风险调整收益
+    卡玛比率: float = 0.0             # Calmar Ratio = 年化收益 / |最大回撤|
+    夏普比率: float = 0.0             # Sharpe Ratio
+    索提诺比率: float = 0.0           # Sortino Ratio
+    年化波动率: float = 0.0           # Annualized Volatility
+    
+    # 交易统计
+    总周期数: int = 0
+    盈利周期数: int = 0
+    亏损周期数: int = 0
+    胜率: float = 0.0
+    盈亏比: float = 0.0              # Profit Factor
+    最大连续盈利周期: int = 0
+    最大连续亏损周期: int = 0
+    
+    # 其他
+    交易次数: int = 0
+    回测天数: int = 0
+    
+    def 转为字典(self) -> Dict[str, Any]:
+        """转换为字典格式"""
+        return {
+            "初始资金": self.初始资金,
+            "最终资金": self.最终资金,
+            "总收益": self.总收益,
+            "总收益率": f"{self.总收益率:.2%}",
+            "年化收益率": f"{self.年化收益率:.2%}",
+            "对数收益率": f"{self.对数收益率:.4f}",
+            "最大回撤": f"{self.最大回撤:.2%}",
+            "最大回撤恢复天数": self.最大回撤恢复天数,
+            "卡玛比率": f"{self.卡玛比率:.2f}",
+            "夏普比率": f"{self.夏普比率:.2f}",
+            "索提诺比率": f"{self.索提诺比率:.2f}",
+            "年化波动率": f"{self.年化波动率:.2%}",
+            "胜率": f"{self.胜率:.2%}",
+            "盈亏比": f"{self.盈亏比:.2f}",
+            "交易次数": self.交易次数,
+            "回测天数": self.回测天数,
+        }
+
+
+class 回测指标计算器:
+    """
+    统一回测指标计算器
+    
+    这个类就像一个"成绩单生成器"：
+    你把考试成绩(权益曲线)交给它，它会自动帮你算出：
+    - 平均分是多少 (年化收益)
+    - 最差的一次考了多少 (最大回撤)
+    - 成绩稳不稳定 (夏普比率)
+    等等一系列指标。
+    """
+    
+    def __init__(
+        self,
+        权益曲线: Union[np.ndarray, List[float], pd.Series],
+        初始资金: float = 10000.0,
+        时间戳: Optional[Union[np.ndarray, List, pd.DatetimeIndex]] = None,
+        持仓序列: Optional[Union[np.ndarray, List[float], pd.Series]] = None,
+        无风险利率: float = 0.0,  # 年化无风险利率，加密货币通常设为 0
+        周期每年数量: int = 525600,  # 分钟级数据: 365.25 * 24 * 60
+    ):
+        """
+        初始化回测指标计算器
+        
+        参数:
+            权益曲线: 账户总资产序列 (如 [10000, 10100, 10050, ...])
+            初始资金: 初始本金
+            时间戳: 可选，每个数据点对应的时间戳
+            持仓序列: 可选，持仓状态序列 (如 [0, 1, 1, -1, 0, ...])，用于计算交易次数
+            无风险利率: 年化无风险收益率，默认 0 (加密货币市场)
+            周期每年数量: 每年有多少���周期，用于年化
+                - 分钟级: 525600 (365.25 * 24 * 60)
+                - 小时级: 8766 (365.25 * 24)
+                - 日级: 365
+        """
+        # 转换为 numpy 数组
+        self.权益 = np.array(权益曲线, dtype=np.float64)
+        self.初始资金 = float(初始资金)
+        self.无风险利率 = 无风险利率
+        self.周期每年数量 = 周期每年数量
+        
+        # 时间戳处理
+        if 时间戳 is not None:
+            self.时间戳 = pd.to_datetime(时间戳)
+        else:
+            self.时间戳 = None
+            
+        # 持仓序列
+        if 持仓序列 is not None:
+            self.持仓 = np.array(持仓序列, dtype=np.float64)
+        else:
+            self.持仓 = None
+            
+        # 预计算
+        self._计算收益率序列()
+        
+    def _计算收益率序列(self):
+        """计算周期收益率序列"""
+        # 简单收益率: (P_t - P_{t-1}) / P_{t-1}
+        self.收益率 = np.diff(self.权益) / self.权益[:-1]
+        # 处理 NaN 和 Inf
+        self.收益率 = np.nan_to_num(self.收益率, nan=0.0, posinf=0.0, neginf=0.0)
+        
+        # 对数收益率: ln(P_t / P_{t-1})
+        with np.errstate(divide='ignore', invalid='ignore'):
+            self.对数收益率序列 = np.log(self.权益[1:] / self.权益[:-1])
+            self.对数收益率序列 = np.nan_to_num(self.对数收益率序列, nan=0.0, posinf=0.0, neginf=0.0)
+    
+    @classmethod
+    def 从DataFrame创建(
+        cls,
+        df: pd.DataFrame,
+        权益列名: str = 'equity',
+        时间列名: str = 'candle_begin_time',
+        持仓列名: Optional[str] = None,
+        初始资金: Optional[float] = None,
+        **kwargs
+    ) -> '回测指标计算器':
+        """
+        从 DataFrame 创建计算器
+        
+        参数:
+            df: 包含回测数据的 DataFrame
+            权益列名: 权益/净值列的名称
+            时间列名: 时间戳列的名称
+            持仓列名: 可选，持仓列的名称
+            初始资金: 可选，如不提供则使用权益曲线第一个值
+        """
+        权益 = df[权益列名].values
+        
+        时间戳 = None
+        if 时间列名 in df.columns:
+            时间戳 = df[时间列名].values
+        elif isinstance(df.index, pd.DatetimeIndex):
+            时间戳 = df.index
+            
+        持仓 = None
+        if 持仓列名 and 持仓列名 in df.columns:
+            持仓 = df[持仓列名].values
+            
+        if 初始资金 is None:
+            初始资金 = 权益[0]
+            
+        return cls(
+            权益曲线=权益,
+            初始资金=初始资金,
+            时间戳=时间戳,
+            持仓序列=持仓,
+            **kwargs
+        )
+    
+    def 计算全部指标(self) -> 回测指标结果:
+        """计算所有回测指标，返回结构化结果"""
+        结果 = 回测指标结果()
+        
+        # 1. 基础信息
+        结果.初始资金 = self.初始资金
+        结果.最终资金 = self.权益[-1]
+        结果.总收益 = 结果.最终资金 - 结果.初始资金
+        结果.总收益率 = 结果.总收益 / 结果.初始资金
+        结果.总周期数 = len(self.权益)
+        
+        # 2. 回测天数
+        if self.时间戳 is not None and len(self.时间戳) > 1:
+            结果.回测天数 = (self.时间戳[-1] - self.时间戳[0]).days
+        else:
+            结果.回测天数 = len(self.权益) // (24 * 60)  # 假设分钟级数据
+        
+        # 3. 年化收益率 (CAGR)
+        # CAGR = (最终净值 / 初始净值) ^ (1 / 年数) - 1
+        年数 = max(结果.回测天数 / 365.25, 0.001)  # 防止除零
+        净值终点 = 结果.最终资金 / 结果.初始资金
+        if 净值终点 > 0:
+            结果.年化收益率 = (净值终点 ** (1 / 年数)) - 1
+        else:
+            结果.年化收益率 = -1.0
+        
+        # 4. 对数收益率 (总体)
+        # Log Return = ln(最终净值 / 初始净值)
+        if 净值终点 > 0:
+            结果.对数收益率 = np.log(净值终点)
+        else:
+            结果.对数收益率 = float('-inf')
+        
+        # 5. 最大回撤
+        回撤结果 = self._计算最大回撤()
+        结果.最大回撤 = 回撤结果['最大回撤']
+        结果.最大回撤百分比 = f"{回撤结果['最大回撤']:.2%}"
+        结果.最大回撤开始时间 = 回撤结果.get('开始时间')
+        结果.最大回撤结束时间 = 回撤结果.get('结束时间')
+        结果.最大回撤恢复时间 = 回撤结果.get('恢复时间')
+        结果.最大回撤恢复天数 = 回撤结果.get('恢复天数', 0)
+        
+        # 6. 卡玛比率 (Calmar Ratio)
+        # Calmar = 年化收益率 / |最大回撤|
+        if abs(结果.最大回撤) > 1e-9:
+            结果.卡玛比率 = 结果.年化收益率 / abs(结果.最大回撤)
+        else:
+            结果.卡玛比率 = float('inf') if 结果.年化收益率 > 0 else 0.0
+        
+        # 7. 波动率和夏普比率
+        if len(self.收益率) > 1:
+            # 年化波动率 = 周期标准差 * sqrt(周期每年数量)
+            结果.年化波动率 = np.std(self.收益率) * np.sqrt(self.周期每年数量)
+            
+            # 夏普比率 = (年化收益 - 无风险利率) / 年化波动率
+            if 结果.年化波动率 > 1e-9:
+                结果.夏普比率 = (结果.年化收益率 - self.无风险利率) / 结果.年化波动率
+            else:
+                结果.夏普比率 = 0.0
+                
+            # 索提诺比率 = (年化收益 - 无风险利率) / 下行波动率
+            下行收益 = self.收益率[self.收益率 < 0]
+            if len(下行收益) > 0:
+                下行波动率 = np.std(下行收益) * np.sqrt(self.周期每年数量)
+                if 下行波动率 > 1e-9:
+                    结果.索提诺比率 = (结果.年化收益率 - self.无风险利率) / 下行波动率
+        
+        # 8. 胜率和盈亏比
+        盈利周期 = self.收益率[self.收益率 > 0]
+        亏损周期 = self.收益率[self.收益率 < 0]
+        
+        结果.盈利周期数 = len(盈利周期)
+        结果.亏损周期数 = len(亏损周期)
+        
+        if len(self.收益率) > 0:
+            结果.胜率 = 结果.盈利周期数 / len(self.收益率)
+        
+        if len(亏损周期) > 0 and np.sum(np.abs(亏损周期)) > 1e-9:
+            结果.盈亏比 = np.sum(盈利周期) / np.abs(np.sum(亏损周期))
+        
+        # 9. 连续盈亏
+        结果.最大连续盈利周期 = self._计算最大连续(self.收益率 > 0)
+        结果.最大连续亏损周期 = self._计算最大连续(self.收益率 < 0)
+        
+        # 10. 交易次数 (如果有持仓序列)
+        if self.持仓 is not None:
+            # 持仓变化就是交易
+            结果.交易次数 = int(np.sum(np.abs(np.diff(self.持仓)) > 0))
+        
+        return 结果
+    
+    def _计算最大回撤(self) -> Dict[str, Any]:
+        """
+        计算最大回撤及相关信息
+        
+        最大回撤 = (峰值 - 谷值) / 峰值
+        就像股票从最高点跌到最低点的幅度
+        """
+        if len(self.权益) < 2:
+            return {'最大回撤': 0.0}
+        
+        # 计算滚动最高点 (累计最大值)
+        累计最高 = np.maximum.accumulate(self.权益)
+        
+        # 计算回撤 (当前值相对于历史最高的跌幅)
+        # 回撤 = (当前值 - 最高值) / 最高值  (负数或零)
+        回撤序列 = (self.权益 - 累计最高) / 累计最高
+        
+        # 最大回撤位置 (最低点)
+        最大回撤索引 = np.argmin(回撤序列)
+        最大回撤值 = 回撤序列[最大回撤索引]
+        
+        # 最大回撤开始位置 (在最低点之前的最高点)
+        峰值索引 = np.argmax(self.权益[:最大回撤索引 + 1])
+        
+        结果 = {
+            '最大回撤': 最大回撤值,
+            '回撤开始索引': 峰值索引,
+            '回撤结束索引': 最大回撤索引,
+        }
+        
+        # 如果有时间戳，添加时间信息
+        if self.时间戳 is not None:
+            结果['开始时间'] = str(self.时间戳[峰值索引])
+            结果['结束时间'] = str(self.时间戳[最大回撤索引])
+            
+            # 计算恢复时间 (从最低点恢复到前高)
+            峰值 = self.权益[峰值索引]
+            恢复索引 = None
+            for i in range(最大回撤索引 + 1, len(self.权益)):
+                if self.权益[i] >= 峰值:
+                    恢复索引 = i
+                    break
+            
+            if 恢复索引 is not None:
+                结果['恢复时间'] = str(self.时间戳[恢复索引])
+                结果['恢复天数'] = (self.时间戳[恢复索引] - self.时间戳[最大回撤索引]).days
+            else:
+                结果['恢复天数'] = -1  # 未恢复
+                结果['恢复时间'] = "未恢复"
+        
+        return 结果
+    
+    def _计算最大连续(self, 条件数组: np.ndarray) -> int:
+        """计算最大连续满足条件的周期数"""
+        if len(条件数组) == 0:
+            return 0
+        
+        最大连续 = 0
+        当前连续 = 0
+        
+        for 满足条件 in 条件数组:
+            if 满足条件:
+                当前连续 += 1
+                最大连续 = max(最大连续, 当前连续)
+            else:
+                当前连续 = 0
+        
+        return 最大连续
+    
+    def 获取指标(self) -> Dict[str, Any]:
+        """获取指标字典"""
+        return self.计算全部指标().转为字典()
+    
+    def 打印报告(self, 策略名称: str = "策略"):
+        """
+        打印格式化的回测报告
+        
+        输出一个漂亮的表格，展示所有关键指标
+        """
+        结果 = self.计算全部指标()
+        
+        # 构建分隔线
+        宽度 = 50
+        分隔线 = "═" * 宽度
+        细分隔线 = "─" * 宽度
+        
+        print()
+        print(f"╔{分隔线}╗")
+        print(f"║{'📊 ' + 策略名称 + ' 回测报告':^{宽度-2}}║")
+        print(f"╠{分隔线}╣")
+        
+        # 基础信息
+        print(f"║ {'💰 初始资金':<15}: {结果.初始资金:>18,.2f} USDT  ║")
+        print(f"║ {'💎 最终资金':<15}: {结果.最终资金:>18,.2f} USDT  ║")
+        print(f"║ {'📈 总收益率':<15}: {结果.总收益率:>18.2%}       ║")
+        print(f"╠{细分隔线}╣")
+        
+        # 收益指标
+        print(f"║ {'📅 年化收益率':<14}: {结果.年化收益率:>18.2%}       ║")
+        print(f"║ {'📐 对数收益率':<14}: {结果.对数收益率:>18.4f}       ║")
+        print(f"╠{细分隔线}╣")
+        
+        # 风险指标
+        print(f"║ {'🌊 最大回撤':<15}: {结果.最大回撤:>18.2%}       ║")
+        if 结果.最大回撤恢复天数 > 0:
+            print(f"║ {'⏱️ 回撤恢复天数':<13}: {结果.最大回撤恢复天数:>18} 天    ║")
+        elif 结果.最大回撤恢复天数 == -1:
+            print(f"║ {'⏱️ 回撤恢复天数':<13}: {'未恢复':>21}    ║")
+        print(f"╠{细分隔线}╣")
+        
+        # 风险调整收益
+        print(f"║ {'⚖️ 卡玛比率':<14}: {结果.卡玛比率:>18.2f}       ║")
+        print(f"║ {'📊 夏普比率':<15}: {结果.夏普比率:>18.2f}       ║")
+        print(f"║ {'📉 索提诺比率':<14}: {结果.索提诺比率:>18.2f}       ║")
+        print(f"║ {'📈 年化波动率':<14}: {结果.年化波动率:>18.2%}       ║")
+        print(f"╠{细分隔线}╣")
+        
+        # 交易统计
+        print(f"║ {'🎯 胜率':<16}: {结果.胜率:>18.2%}       ║")
+        print(f"║ {'💹 盈亏比':<15}: {结果.盈亏比:>18.2f}       ║")
+        if 结果.交易次数 > 0:
+            print(f"║ {'🔄 交易次数':<15}: {结果.交易次数:>18}       ║")
+        print(f"║ {'📆 回测天数':<15}: {结果.回测天数:>18} 天    ║")
+        
+        print(f"╚{分隔线}╝")
+        print()
+        
+        return 结果
+
+
+# ============== 便捷函数 ==============
+
+def 快速计算指标(
+    权益曲线: Union[np.ndarray, List[float]],
+    初始资金: float = 10000.0,
+    打印: bool = True,
+    策略名称: str = "策略"
+) -> Dict[str, Any]:
+    """
+    快速计算回测指标的便捷函数
+    
+    使用方法:
+        from 基础库.common_core.backtest.metrics import 快速计算指标
+        
+        指标 = 快速计算指标(equity_list, 初始资金=10000)
+    """
+    计算器 = 回测指标计算器(权益曲线=权益曲线, 初始资金=初始资金)
+    if 打印:
+        计算器.打印报告(策略名称=策略名称)
+    return 计算器.获取指标()
+
+
+# ============== 测试代码 ==============
+
+if __name__ == "__main__":
+    # 生成模拟权益曲线 (用于测试)
+    np.random.seed(42)
+    天数 = 365
+    每天周期数 = 1440  # 分钟级
+    总周期 = 天数 * 每天周期数
+    
+    # 模拟一个有波动的权益曲线
+    收益率 = np.random.normal(0.00001, 0.0005, 总周期)  # 微小正漂移 + 波动
+    权益 = 10000 * np.cumprod(1 + 收益率)
+    
+    # 插入一个大回撤
+    权益[int(总周期*0.3):int(总周期*0.4)] *= 0.7
+    
+    # 测试计算器
+    计算器 = 回测指标计算器(权益曲线=权益, 初始资金=10000, 周期每年数量=每天周期数*365)
+    计算器.打印报告(策略名称="测试策略")

基础库/common_core/backtest/rebalance.py

@@ -0,0 +1,70 @@
+"""
+Quant Unified 量化交易系统
+rebalance.py
+"""
+
+import numpy as np
+import numba as nb
+from numba.experimental import jitclass
+
+
+@jitclass
+class RebAlways:
+    spot_lot_sizes: nb.float64[:]  # 每手币数，表示一手加密货币中包含的币数
+    swap_lot_sizes: nb.float64[:]
+
+    def __init__(self, spot_lot_sizes, swap_lot_sizes):
+        n_syms_spot = len(spot_lot_sizes)
+        n_syms_swap = len(swap_lot_sizes)
+
+        self.spot_lot_sizes = np.zeros(n_syms_spot, dtype=np.float64)
+        self.spot_lot_sizes[:] = spot_lot_sizes
+
+        self.swap_lot_sizes = np.zeros(n_syms_swap, dtype=np.float64)
+        self.swap_lot_sizes[:] = swap_lot_sizes
+
+    def _calc(self, equity, prices, ratios, lot_sizes):
+        # 初始化目标持仓手数
+        target_lots = np.zeros(len(lot_sizes), dtype=np.int64)
+
+        # 每个币分配的资金(带方向)
+        symbol_equity = equity * ratios
+
+        # 分配资金大于 0.01U 则认为是有效持仓
+        mask = np.abs(symbol_equity) > 0.01
+
+        # 为有效持仓分配仓位
+        target_lots[mask] = (symbol_equity[mask] / prices[mask] / lot_sizes[mask]).astype(np.int64)
+
+        return target_lots
+
+    def calc_lots(self, equity, spot_prices, spot_lots, spot_ratios, swap_prices, swap_lots, swap_ratios):
+        """
+        计算每个币种的目标手数
+        :param equity: 总权益
+        :param spot_prices: 现货最新价格
+        :param spot_lots: 现货当前持仓手数
+        :param spot_ratios: 现货币种的资金比例
+        :param swap_prices: 合约最新价格
+        :param swap_lots: 合约当前持仓手数
+        :param swap_ratios: 合约币种的资金比例
+        :return: tuple[现货目标手数, 合约目标手数]
+        """
+        is_spot_only = False
+
+        # 合约总权重小于极小值，认为是纯现货模式
+        if np.sum(np.abs(swap_ratios)) < 1e-6:
+            is_spot_only = True
+            equity *= 0.99  # 纯现货留 1% 的资金作为缓冲            
+
+        # 现货目标持仓手数
+        spot_target_lots = self._calc(equity, spot_prices, spot_ratios, self.spot_lot_sizes)
+
+        if is_spot_only:
+            swap_target_lots = np.zeros(len(self.swap_lot_sizes), dtype=np.int64)
+            return spot_target_lots, swap_target_lots
+
+        # 合约目标持仓手数
+        swap_target_lots = self._calc(equity, swap_prices, swap_ratios, self.swap_lot_sizes)
+
+        return spot_target_lots, swap_target_lots

基础库/common_core/backtest/signal.py

@@ -0,0 +1,98 @@
+"""
+Quant Unified 量化交易系统
+signal.py
+
+概率信号 -> 仓位（带迟滞 / hysteresis）
+"""
+
+from __future__ import annotations
+
+import numba as nb
+import numpy as np
+
+
+@nb.njit(cache=True)
+def positions_from_probs_hysteresis(
+    p_up: np.ndarray,
+    p_down: np.ndarray,
+    p_enter: float = 0.55,
+    p_exit: float = 0.55,
+    diff_enter: float = 0.0,
+    diff_exit: float = 0.0,
+    init_pos: int = 0,
+) -> np.ndarray:
+    """
+    将 (p_up, p_down) 转换成 {-1,0,1} 仓位序列，并加入迟滞以降低来回翻仓。
+
+    规则（默认）：
+    - 空仓：p_up>=p_enter 且 (p_up-p_down)>=diff_enter -> 做多；
+            p_down>=p_enter 且 (p_down-p_up)>=diff_enter -> 做空；
+    - 多仓：p_down>=p_exit 且 (p_down-p_up)>=diff_exit -> 反手做空；
+    - 空仓：p_up>=p_exit 且 (p_up-p_down)>=diff_exit -> 反手做多；
+    - 其他情况保持原仓位。
+    """
+    n = len(p_up)
+    pos = np.empty(n, dtype=np.int8)
+    cur = np.int8(init_pos)
+
+    for i in range(n):
+        up = p_up[i]
+        down = p_down[i]
+
+        if np.isnan(up) or np.isnan(down):
+            pos[i] = cur
+            continue
+
+        if cur == 0:
+            if up >= p_enter and (up - down) >= diff_enter:
+                cur = np.int8(1)
+            elif down >= p_enter and (down - up) >= diff_enter:
+                cur = np.int8(-1)
+        elif cur == 1:
+            if down >= p_exit and (down - up) >= diff_exit:
+                cur = np.int8(-1)
+        else:  # cur == -1
+            if up >= p_exit and (up - down) >= diff_exit:
+                cur = np.int8(1)
+
+        pos[i] = cur
+
+    return pos
+
+
+def positions_from_probs_hysteresis_py(
+    p_up: np.ndarray,
+    p_down: np.ndarray,
+    p_enter: float = 0.55,
+    p_exit: float = 0.55,
+    diff_enter: float = 0.0,
+    diff_exit: float = 0.0,
+    init_pos: int = 0,
+) -> np.ndarray:
+    """
+    Python 版本（便于调试），输出与 numba 版一致。
+    """
+    p_up = np.asarray(p_up, dtype=float)
+    p_down = np.asarray(p_down, dtype=float)
+    out = np.empty(len(p_up), dtype=np.int8)
+    cur = np.int8(init_pos)
+
+    for i, (up, down) in enumerate(zip(p_up, p_down)):
+        if np.isnan(up) or np.isnan(down):
+            out[i] = cur
+            continue
+        if cur == 0:
+            if up >= p_enter and (up - down) >= diff_enter:
+                cur = np.int8(1)
+            elif down >= p_enter and (down - up) >= diff_enter:
+                cur = np.int8(-1)
+        elif cur == 1:
+            if down >= p_exit and (down - up) >= diff_exit:
+                cur = np.int8(-1)
+        else:
+            if up >= p_exit and (up - down) >= diff_exit:
+                cur = np.int8(1)
+        out[i] = cur
+
+    return out
+

基础库/common_core/backtest/simulator.py

@@ -0,0 +1,204 @@
+"""
+Quant Unified 量化交易系统
+[高性能回测仿真器]
+功能：基于 Numba 加速，模拟交易所撮合逻辑，处理开平仓、资金费结算，提供极速的回测执行。
+"""
+import numba as nb
+import numpy as np
+from numba.experimental import jitclass
+
+"""
+# 新语法小讲堂
+通过操作对象的值而不是更换reference，来保证所有引用的位置都能同步更新。
+
+`self.target_lots[:] = target_lots`
+这个写法涉及 Python 中的切片（slice）操作和对象的属性赋值。
+
+`target_lots: nb.int64[:]  # 目标持仓手数`，self.target_lots 是一个列表，`[:]` 是切片操作符，表示对整个列表进行切片。
+
+### 详细解释：
+
+1. **`self.target_lots[:] = target_lots`**:
+   - `self.target_lots` 是对象的一个属性，通常是一个列表（或者其它支持切片操作的可变序列）。
+   - `[:]` 是切片操作符，表示对整个列表进行切片。具体来说，`[:]` 是对列表的所有元素进行选择，这种写法可以用于复制列表或对整个列表内容进行替换。
+
+2. **具体操作**：
+   - `self.target_lots[:] = target_lots` 不是直接将 `target_lots` 赋值给 `self.target_lots`，而是将 `target_lots` 中的所有元素替换 `self.target_lots` 中的所有元素。
+   - 这种做法的一个好处是不会改变 `self.target_lots` 对象的引用，而是修改它的内容。这在有其他对象引用 `self.target_lots` 时非常有用，确保所有引用者看到的列表内容都被更新，而不会因为重新赋值而改变列表的引用。
+
+### 举个例子：
+
+```python
+a = [1, 2, 3]
+b = a
+a[:] = [4, 5, 6]  # 只改变列表内容，不改变引用
+
+print(a)  # 输出: [4, 5, 6]
+print(b)  # 输出: [4, 5, 6]，因为 a 和 b 引用的是同一个列表，修改 a 的内容也影响了 b
+```
+
+如果直接用 `a = [4, 5, 6]` 替换 `[:]` 操作，那么 `b` 就不会受到影响，因为 `a` 重新指向了一个新的列表对象。
+"""
+
+
+@jitclass
+class Simulator:
+    equity: float  # 账户权益, 单位 USDT
+    fee_rate: float  # 手续费率（单边）
+    slippage_rate: float  # 滑点率（单边，按成交额计）
+    min_order_limit: float  # 最小下单金额
+
+    lot_sizes: nb.float64[:]  # 每手币数，表示一手加密货币中包含的币数
+    lots: nb.int64[:]  # 当前持仓手数
+    target_lots: nb.int64[:]  # 目标持仓手数
+
+    last_prices: nb.float64[:]  # 最新价格
+    has_last_prices: bool  # 是否有最新价
+
+    def __init__(self, init_capital, lot_sizes, fee_rate, slippage_rate, init_lots, min_order_limit):
+        """
+        初始化
+        :param init_capital: 初始资金 
+        :param lot_sizes: 每个币种的最小下单量
+        :param fee_rate: 手续费率（单边）
+        :param slippage_rate: 滑点率（单边，按成交额计）
+        :param init_lots: 初始持仓
+        :param min_order_limit: 最小下单金额
+        """
+        self.equity = init_capital  # 账户权益
+        self.fee_rate = fee_rate  # 手续费
+        self.slippage_rate = slippage_rate  # 滑点
+        self.min_order_limit = min_order_limit  # 最小下单金额
+
+        n = len(lot_sizes)
+
+        # 合约面值
+        self.lot_sizes = np.zeros(n, dtype=np.float64)
+        self.lot_sizes[:] = lot_sizes
+
+        # 前收盘价
+        self.last_prices = np.zeros(n, dtype=np.float64)
+        self.has_last_prices = False
+
+        # 当前持仓手数
+        self.lots = np.zeros(n, dtype=np.int64)
+        self.lots[:] = init_lots
+
+        # 目标持仓手数
+        self.target_lots = np.zeros(n, dtype=np.int64)
+        self.target_lots[:] = init_lots
+
+    def set_target_lots(self, target_lots):
+        self.target_lots[:] = target_lots
+
+    def fill_last_prices(self, prices):
+        mask = np.logical_not(np.isnan(prices))
+        self.last_prices[mask] = prices[mask]
+        self.has_last_prices = True
+
+    def settle_equity(self, prices):
+        """
+        结算当前账户权益
+        :param prices: 当前价格
+        :return:
+        """
+        mask = np.logical_and(self.lots != 0, np.logical_not(np.isnan(prices)))
+        # 计算公式：
+        # 1. 净值涨跌 = (最新价格 - 前最新价（前收盘价）) * 持币数量。
+        # 2. 其中，持币数量 = min_qty * 持仓手数。
+        # 3. 所有币种对应的净值涨跌累加起来
+        equity_delta = np.sum((prices[mask] - self.last_prices[mask]) * self.lot_sizes[mask] * self.lots[mask])
+
+        # 反映到净值上
+        self.equity += equity_delta
+
+    def on_open(self, open_prices, funding_rates, mark_prices):
+        """
+        模拟: K 线开盘 -> K 线收盘时刻
+        :param open_prices: 开盘价
+        :param funding_rates: 资金费
+        :param mark_prices: 计算资金费的标记价格（目前就用开盘价来）
+        :return:
+        """
+        if not self.has_last_prices:
+            self.fill_last_prices(open_prices)
+
+        # 根据开盘价和前最新价（前收盘价），结算当前账户权益
+        self.settle_equity(open_prices)
+
+        # 根据标记价格和资金费率，结算资金费盈亏
+        mask = np.logical_and(self.lots != 0, np.logical_not(np.isnan(mark_prices)))
+        pos_val = notional_value = self.lot_sizes[mask] * self.lots[mask] * mark_prices[mask]
+        funding_fee = np.sum(notional_value * funding_rates[mask])
+        self.equity -= funding_fee
+
+        # 最新价为开盘价
+        self.fill_last_prices(open_prices)
+
+        # 返回扣除资金费后开盘账户权益、资金费和带方向的仓位名义价值
+        return self.equity, funding_fee, pos_val
+
+    def on_execution(self, exec_prices):
+        """
+        模拟: K 线开盘时刻 -> 调仓时刻
+        :param exec_prices:  执行价格
+        :return:            调仓后的账户权益、调仓后的仓位名义价值
+        """
+        if not self.has_last_prices:
+            self.fill_last_prices(exec_prices)
+
+        # 根据调仓价和前最新价（开盘价），结算当前账户权益
+        self.settle_equity(exec_prices)
+
+        # 计算需要买入或卖出的合约数量
+        delta = self.target_lots - self.lots
+        mask = np.logical_and(delta != 0, np.logical_not(np.isnan(exec_prices)))
+
+        # 计算成交额
+        turnover = np.zeros(len(self.lot_sizes), dtype=np.float64)
+        turnover[mask] = np.abs(delta[mask]) * self.lot_sizes[mask] * exec_prices[mask]
+
+        # 成交额小于 min_order_limit 则无法调仓
+        mask = np.logical_and(mask, turnover >= self.min_order_limit)
+
+        # 本期调仓总成交额
+        turnover_total = turnover[mask].sum()
+
+        if np.isnan(turnover_total):
+            raise RuntimeError('Turnover is nan')
+
+        # 根据总成交额计算并扣除手续费 + 滑点（均按单边成交额计）
+        cost = turnover_total * (self.fee_rate + self.slippage_rate)
+        self.equity -= cost
+
+        # 更新已成功调仓的 symbol 持仓
+        self.lots[mask] = self.target_lots[mask]
+
+        # 最新价为调仓价
+        self.fill_last_prices(exec_prices)
+
+        # 返回扣除交易成本后的调仓后账户权益，成交额，和交易成本
+        return self.equity, turnover_total, cost
+
+    def on_close(self, close_prices):
+        """
+        模拟: K 线收盘 -> K 线收盘时刻
+        :param close_prices: 收盘价
+        :return:           收盘后的账户权益
+        """
+        if not self.has_last_prices:
+            self.fill_last_prices(close_prices)
+
+        # 模拟: 调仓时刻 -> K 线收盘时刻
+
+        # 根据收盘价和前最新价（调仓价），结算当前账户权益
+        self.settle_equity(close_prices)
+
+        # 最新价为收盘价
+        self.fill_last_prices(close_prices)
+
+        mask = np.logical_and(self.lots != 0, np.logical_not(np.isnan(close_prices)))
+        pos_val = self.lot_sizes[mask] * self.lots[mask] * close_prices[mask]
+
+        # 返回收盘账户权益
+        return self.equity, pos_val

基础库/common_core/backtest/version.py

@@ -0,0 +1,7 @@
+"""
+Quant Unified 量化交易系统
+version.py
+"""
+sys_name = 'select-strategy'
+sys_version = '1.0.2'
+build_version = 'v1.0.2.20241122'

基础库/common_core/backtest/进度条.py

@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+"""
+Quant Unified 量化交易系统
+[回测进度条模块]
+
+功能：
+    提供统一的进度条显示，让用户知道回测进行到哪了、还要等多久。
+    底层使用 tqdm 库，但封装成中文接口方便使用。
+
+使用方法：
+    ```python
+    from 基础库.common_core.backtest.进度条 import 回测进度条
+
+    # 方式1: 作为上下文管理器
+    with 回测进度条(总数=len(prices), 描述="回测中") as 进度:
+        for i in range(len(prices)):
+            # 你的回测逻辑...
+            进度.更新(1)
+
+    # 方式2: 手动控制
+    进度 = 回测进度条(总数=1000, 描述="处理数据")
+    for i in range(1000):
+        # 处理逻辑...
+        进度.更新(1)
+    进度.关闭()
+    ```
+
+显示效果：
+    回测中: 45%|████████████░░░░░░░░░░░░| 450000/1000000 [01:23<01:42, 5432.10 it/s]
+"""
+
+from tqdm import tqdm
+from typing import Optional
+
+
+class 回测进度条:
+    """
+    回测进度条封装类
+    
+    这个类就像一个"加载条"：
+    当你在下载文件或安装软件时，会看到一个进度条告诉你：
+    - 完成了多少 (45%)
+    - 已经用了多久 (01:23)
+    - 还需要多久 (01:42)
+    - 速度多快 (5432 条/秒)
+    
+    这里我们把它用在回测上，让你知道回测还要跑多久。
+    """
+    
+    def __init__(
+        self,
+        总数: int,
+        描述: str = "回测进行中",
+        单位: str = " bar",
+        刷新间隔: float = 0.1,
+        最小更新间隔: float = 0.5,
+        禁用: bool = False,
+        留存: bool = True
+    ):
+        """
+        初始化进度条
+        
+        参数：
+            总数: 总共需要处理的数量 (比如 K线条数)
+            描述: 进度条前面显示的文字描述
+            单位: 显示的单位 (如 "条", "bar", "根K线")
+            刷新间隔: 进度条刷新频率 (秒)
+            最小更新间隔: 最小更新间隔 (秒)，防止刷新太频繁拖慢速度
+            禁用: 是否禁用进度条 (静默模式)
+            留存: 完成后是否保留进度条显示
+        """
+        self.总数 = 总数
+        self.禁用 = 禁用
+        
+        # 配置 tqdm 进度条
+        self._进度条 = tqdm(
+            total=总数,
+            desc=描述,
+            unit=单位,
+            mininterval=刷新间隔,
+            miniters=max(1, 总数 // 1000),  # 至少每 0.1% 更新一次
+            disable=禁用,
+            leave=留存,
+            ncols=100,  # 进度条宽度
+            bar_format='{desc}: {percentage:3.0f}%|{bar:25}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]'
+        )
+        
+        self._当前 = 0
+    
+    def 更新(self, 步数: int = 1):
+        """
+        更新进度
+        
+        参数：
+            步数: 本次完成的数量 (默认为1)
+        """
+        self._进度条.update(步数)
+        self._当前 += 步数
+    
+    def 设置描述(self, 描述: str):
+        """动态更新进度条描述文字"""
+        self._进度条.set_description(描述)
+    
+    def 设置后缀(self, **kwargs):
+        """
+        设置进度条后缀信息
+        
+        示例：
+            进度.设置后缀(收益率="12.5%", 回撤="-3.2%")
+        """
+        self._进度条.set_postfix(**kwargs)
+    
+    def 关闭(self):
+        """关闭进度条"""
+        self._进度条.close()
+    
+    def __enter__(self):
+        """进入上下文管理器"""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """退出上下文管理器，自动关闭进度条"""
+        self.关闭()
+        return False  # 不吞掉异常
+    
+    @property
+    def 已完成数量(self) -> int:
+        """获取已完成的数量"""
+        return self._当前
+    
+    @property
+    def 完成百分比(self) -> float:
+        """获取完成百分比 (0-100)"""
+        if self.总数 == 0:
+            return 100.0
+        return (self._当前 / self.总数) * 100
+
+
+def 创建进度条(总数: int, 描述: str = "处理中", 禁用: bool = False) -> 回测进度条:
+    """
+    快速创建进度条的便捷函数
+    
+    使用方法：
+        进度 = 创建进度条(1000000, "回测ETH策略")
+        for i in range(1000000):
+            # 处理逻辑
+            进度.更新(1)
+        进度.关闭()
+    """
+    return 回测进度条(总数=总数, 描述=描述, 禁用=禁用)
+
+
+# ============== 向量化回测专用 ==============
+
+class 分块进度条:
+    """
+    分块进度条 - 适用于向量化回测
+    
+    向量化回测不是一条一条处理，而是一大块一大块处理。
+    这个进度条专门为这种情况设计。
+    
+    使用方法：
+        进度 = 分块进度条(总步骤=5, 描述="向量化回测")
+        
+        进度.完成步骤("加载数��")
+        # ... 加载数据 ...
+        
+        进度.完成步骤("计算指标")
+        # ... 计算指标 ...
+        
+        进度.完成步骤("生成信号")
+        # ... 生成信号 ...
+        
+        进度.结束()
+    """
+    
+    def __init__(self, 总步骤: int = 5, 描述: str = "回测中"):
+        self.总步骤 = 总步骤
+        self.当前步骤 = 0
+        self.描述 = 描述
+        
+        self._进度条 = tqdm(
+            total=总步骤,
+            desc=描述,
+            unit="步",
+            bar_format='{desc}: {n}/{total} |{bar:20}| {postfix}',
+            leave=True
+        )
+    
+    def 完成步骤(self, 步骤名称: str):
+        """标记一个步骤完成"""
+        self.当前步骤 += 1
+        self._进度条.set_postfix_str(f"✅ {步骤名称}")
+        self._进度条.update(1)
+    
+    def 结束(self):
+        """结束进度条"""
+        self._进度条.set_postfix_str("🎉 完成!")
+        self._进度条.close()
+
+
+# ============== 测试代码 ==============
+
+if __name__ == "__main__":
+    import time
+    
+    print("测试1: 基础进度条")
+    with 回测进度条(总数=100, 描述="处理K线") as 进度:
+        for i in range(100):
+            time.sleep(0.02)  # 模拟处理
+            进度.更新(1)
+            if i % 20 == 0:
+                进度.设置后缀(收益="12.5%")
+    
+    print("\n测试2: 分块进度条 (向量化)")
+    进度 = 分块进度条(总步骤=4, 描述="向量化回测")
+    
+    time.sleep(0.3)
+    进度.完成步骤("加载数据")
+    
+    time.sleep(0.3)
+    进度.完成步骤("计算指标")
+    
+    time.sleep(0.3)
+    进度.完成步骤("生成信号")
+    
+    time.sleep(0.3)
+    进度.完成步骤("计算收益")
+    
+    进度.结束()
+    
+    print("\n✅ 进度条模块测试通过!")

基础库/common_core/config/loader.py

@@ -0,0 +1,74 @@
+"""
+Configuration Loading Utilities
+"""
+import importlib.util
+import os
+from pathlib import Path
+from typing import Type, TypeVar, Optional, Any, Dict
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def load_config_from_module(
+    module_path: str, 
+    model: Type[T], 
+    variable_name: str = "config"
+) -> T:
+    """
+    Load configuration from a python module file and validate it against a Pydantic model.
+    
+    :param module_path: Path to the python file (e.g., 'config.py')
+    :param model: Pydantic model class to validate against
+    :param variable_name: The variable name in the module to load (default: 'config')
+    :return: Instance of the Pydantic model
+    """
+    path = Path(module_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    spec = importlib.util.spec_from_file_location("dynamic_config", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load spec from {path}")
+        
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    
+    config_data = getattr(module, variable_name, None)
+    if config_data is None:
+        # Try to find a variable that matches the variable_name case-insensitive
+        # or if variable_name is a dict of exports expected
+        raise AttributeError(f"Variable '{variable_name}' not found in {module_path}")
+        
+    return model.model_validate(config_data)
+
+
+def load_dict_from_module(module_path: str, variable_names: list[str]) -> Dict[str, Any]:
+    """
+    Load specific variables from a python module file.
+    
+    :param module_path: Path to the python file
+    :param variable_names: List of variable names to retrieve
+    :return: Dictionary of variable names to values
+    """
+    path = Path(module_path).resolve()
+    if not path.exists():
+        # Fallback: try relative to CWD
+        path = Path.cwd() / module_path
+        if not path.exists():
+             raise FileNotFoundError(f"Config file not found: {module_path}")
+
+    spec = importlib.util.spec_from_file_location("dynamic_config", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load spec from {path}")
+        
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    
+    result = {}
+    for name in variable_names:
+        if hasattr(module, name):
+            result[name] = getattr(module, name)
+            
+    return result

基础库/common_core/config/models.py

@@ -0,0 +1,60 @@
+"""
+配置模型定义
+用于定义和验证系统各部分的配置结构，利用 Pydantic 提供类型检查和自动验证功能。
+"""
+from typing import Optional, List, Dict, Union, Set
+from pydantic import BaseModel, Field, AnyHttpUrl
+
+
+class ExchangeConfig(BaseModel):
+    """交易所基础配置"""
+    exchange_name: str = Field(default="binance", description="交易所名称")
+    apiKey: str = Field(default="", description="API 密钥")
+    secret: str = Field(default="", description="API 私钥")
+    is_pure_long: bool = Field(default=False, description="是否为纯多头模式")
+    password: Optional[str] = None
+    uid: Optional[str] = None
+
+
+class FactorConfig(BaseModel):
+    """因子配置"""
+    name: str
+    param: Union[int, float, str, dict, list]
+
+
+class StrategyConfig(BaseModel):
+    """策略配置"""
+    strategy_name: str
+    symbol_type: str = Field(default="swap", description="交易对类型：spot(现货) 或 swap(合约)")
+    hold_period: str = Field(default="1h", description="持仓周期")
+    # 在此添加其他通用策略字段
+    # 这是一个基础模型，具体策略可以继承扩展此模型
+
+
+class AccountConfig(BaseModel):
+    """账户配置"""
+    name: str = Field(default="default_account", description="账户名称")
+    apiKey: Optional[str] = None
+    secret: Optional[str] = None
+    strategy: Dict = Field(default_factory=dict, description="策略配置字典")
+    strategy_short: Optional[Dict] = Field(default=None, description="做空策略配置字典")
+    
+    # 风控设置
+    black_list: List[str] = Field(default_factory=list, description="黑名单币种")
+    white_list: List[str] = Field(default_factory=list, description="白名单币种")
+    leverage: int = Field(default=1, description="杠杆倍数")
+    
+    # 数据获取设置
+    get_kline_num: int = Field(default=999, description="获取K线数量")
+    min_kline_num: int = Field(default=168, description="最小K线数量要求")
+    
+    # 通知设置
+    wechat_webhook_url: Optional[str] = Field(default=None, description="企业微信 Webhook URL")
+    
+    # 下单限制
+    order_spot_money_limit: float = Field(default=10.0, description="现货最小下单金额")
+    order_swap_money_limit: float = Field(default=5.0, description="合约最小下单金额")
+    
+    # 高级设置
+    use_offset: bool = Field(default=False, description="是否使用 Offset")
+    is_pure_long: bool = Field(default=False, description="是否为纯多头模式")

基础库/common_core/exchange/__init__.py

@@ -0,0 +1,2 @@
+"""
+"""

基础库/common_core/exchange/base_client.py

@@ -0,0 +1,723 @@
+"""
+Quant Unified 量化交易系统
+[交易所客户端基类]
+功能：定义通用的连接管理、签名鉴权、错误处理逻辑，规范化所有交易所接口，作为 StandardClient 和 AsyncClient 的父类。
+"""
+# ==================================================================================================
+# !!! 前置非常重要说明
+# !!! 前置非常重要说明
+# !!! 前置非常重要说明
+# ---------------------------------------------------------------------------------------------------
+# ** 方法名前缀规范 **
+# 1. load_* 从硬盘获取数据
+# 2. fetch_* 从接口获取数据
+# 3. get_* 从对象获取数据，可能从硬盘，也可能从接口
+# ====================================================================================================
+
+import math
+import time
+import traceback
+
+import ccxt
+import numpy as np
+import pandas as pd
+
+from common_core.utils.commons import apply_precision
+from common_core.utils.commons import retry_wrapper
+from common_core.utils.dingding import send_wechat_work_msg, send_msg_for_order
+
+
+# 现货接口
+# sapi
+
+# 合约接口
+# dapi：普通账户，包含币本位交易
+# fapi，普通账户，包含U本位交易
+
+# 统一账户
+# papi, um的接口：U本位合约
+# papi, cm的接口：币本位合约
+# papi, margin：现货API，全仓杠杆现货
+
+class BinanceClient:
+    diff_timestamp = 0
+    constants = dict()
+
+    market_info = {}  # 缓存市场信息，并且自动更新，全局共享
+
+    def __init__(self, **config):
+        self.api_key: str = config.get('apiKey', '')
+        self.secret: str = config.get('secret', '')
+        
+        # 默认配置
+        default_exchange_config = {
+            'timeout': 30000,
+            'rateLimit': 30,
+            'enableRateLimit': False,
+            'options': {'adjustForTimeDifference': True, 'recvWindow': 10000},
+        }
+
+        self.order_money_limit: dict = {
+            'spot': config.get('spot_order_money_limit', 10),
+            'swap': config.get('swap_order_money_limit', 5),
+        }
+
+        self.exchange = ccxt.binance(config.get('exchange_config', default_exchange_config))
+        self.wechat_webhook_url: str = config.get('wechat_webhook_url', '')
+        
+        # 常用配置
+        self.utc_offset = config.get('utc_offset', 8)
+        self.stable_symbol = config.get('stable_symbol', ['USDC', 'USDP', 'TUSD', 'BUSD', 'FDUSD', 'DAI'])
+
+        self.swap_account = None
+
+        self.coin_margin: dict = config.get('coin_margin', {})  # 用做保证金的币种
+
+    # ====================================================================================================
+    # ** 市场信息 **
+    # ====================================================================================================
+    def _fetch_swap_exchange_info_list(self) -> list:
+        exchange_info = retry_wrapper(self.exchange.fapipublic_get_exchangeinfo, func_name='获取BN合约币种规则数据')
+        return exchange_info['symbols']
+
+    def _fetch_spot_exchange_info_list(self) -> list:
+        exchange_info = retry_wrapper(self.exchange.public_get_exchangeinfo, func_name='获取BN现货币种规则数据')
+        return exchange_info['symbols']
+
+    # region 市场信息数据获取
+    def fetch_market_info(self, symbol_type='swap', quote_symbol='USDT'):
+        """
+        加载市场数据
+        :param symbol_type: 币种信息。swap为合约，spot为现货
+        :param quote_symbol: 报价币种
+        :return:
+            symbol_list     交易对列表
+            price_precision 币种价格精     例： 2 代表 0.01
+                {'BTCUSD_PERP': 1, 'BTCUSD_231229': 1, 'BTCUSD_240329': 1, 'BTCUSD_240628': 1, ...}
+            min_notional    最小下单金额    例： 5.0 代表 最小下单金额是5U
+                {'BTCUSDT': 5.0, 'ETHUSDT': 5.0, 'BCHUSDT': 5.0, 'XRPUSDT': 5.0...}
+        """
+        print(f'🔄更新{symbol_type}市场数据...')
+        # ===获取所有币种信息
+        if symbol_type == 'swap':  # 合约
+            exchange_info_list = self._fetch_swap_exchange_info_list()
+        else:  # 现货
+            exchange_info_list = self._fetch_spot_exchange_info_list()
+
+        # ===获取币种列表
+        symbol_list = []  # 如果是合约，只包含永续合约。如果是现货，包含所有数据
+        full_symbol_list = []  # 包含所有币种信息
+
+        # ===获取各个交易对的精度、下单量等信息
+        min_qty = {}  # 最小下单精度，例如bnb，一次最少买入0.001个
+        price_precision = {}  # 币种价格精，例如bnb，价格是158.887，不能是158.8869
+        min_notional = {}  # 最小下单金额，例如bnb，一次下单至少买入金额是5usdt
+        # 遍历获得想要的数据
+        for info in exchange_info_list:
+            symbol = info['symbol']  # 交易对信息
+
+            # 过滤掉非报价币对 ， 非交易币对
+            if info['quoteAsset'] != quote_symbol or info['status'] != 'TRADING':
+                continue
+
+            full_symbol_list.append(symbol)  # 添加到全量信息中
+
+            if (symbol_type == 'swap' and info['contractType'] != 'PERPETUAL') or info['baseAsset'] in self.stable_symbol:
+                pass  # 获取合约的时候，非永续的symbol会被排除
+            else:
+                symbol_list.append(symbol)
+
+            for _filter in info['filters']:  # 遍历获得想要的数据
+                if _filter['filterType'] == 'PRICE_FILTER':  # 获取价格精度
+                    price_precision[symbol] = int(math.log(float(_filter['tickSize']), 0.1))
+                elif _filter['filterType'] == 'LOT_SIZE':  # 获取最小下单量
+                    min_qty[symbol] = int(math.log(float(_filter['minQty']), 0.1))
+                elif _filter['filterType'] == 'MIN_NOTIONAL' and symbol_type == 'swap':  # 合约的最小下单金额
+                    min_notional[symbol] = float(_filter['notional'])
+                elif _filter['filterType'] == 'NOTIONAL' and symbol_type == 'spot':  # 现货的最小下单金额
+                    min_notional[symbol] = float(_filter['minNotional'])
+
+        self.market_info[symbol_type] = {
+            'symbol_list': symbol_list,  # 如果是合约，只包含永续合约。如果是现货，包含所有数据
+            'full_symbol_list': full_symbol_list,  # 包含所有币种信息
+            'min_qty': min_qty,
+            'price_precision': price_precision,
+            'min_notional': min_notional,
+            'last_update': int(time.time())
+        }
+        return self.market_info[symbol_type]
+
+    def get_market_info(self, symbol_type, expire_seconds: int = 3600 * 12, require_update: bool = False,
+                        quote_symbol='USDT') -> dict:
+        if require_update:  # 如果强制刷新的话，就当我们系统没有更新过
+            last_update = 0
+        else:
+            last_update = self.market_info.get(symbol_type, {}).get('last_update', 0)
+        if last_update + expire_seconds < int(time.time()):
+            self.fetch_market_info(symbol_type, quote_symbol)
+
+        return self.market_info[symbol_type]
+
+    # endregion
+
+    # ====================================================================================================
+    # ** 行情数据获取 **
+    # ====================================================================================================
+    # region 行情数据获取
+    """K线数据获取"""
+
+    def get_candle_df(self, symbol, run_time, limit=1500, interval='1h', symbol_type='swap') -> pd.DataFrame:
+        # ===获取K线数据
+        _limit = limit
+        # 定义请求的参数：现货最大1000，合约最大499。
+        if limit > 1000:  # 如果参数大于1000
+            if symbol_type == 'spot':  # 如果是现货，最大设置1000
+                _limit = 1000
+            else:  # 如果不是现货，那就设置499
+                _limit = 499
+        # limit = 1000 if limit > 1000 and symbol_type == 'spot' else limit  # 现货最多获取1000根K
+        # 计算获取k线的开始时间
+        start_time_dt = run_time - pd.to_timedelta(interval) * limit
+
+        df_list = []  # 定义获取的k线数据
+        data_len = 0  # 记录数据长度
+        params = {
+            'symbol': symbol,  # 获取币种
+            'interval': interval,  # 获取k线周期
+            'limit': _limit,  # 获取多少根
+            'startTime': int(time.mktime(start_time_dt.timetuple())) * 1000  # 获取币种开始时间
+        }
+        while True:
+            # 获取指定币种的k线数据
+            try:
+                if symbol_type == 'swap':
+                    kline = retry_wrapper(
+                        self.exchange.fapipublic_get_klines, params=params, func_name='获取币种K线',
+                        if_exit=False
+                    )
+                else:
+                    kline = retry_wrapper(
+                        self.exchange.public_get_klines, params=params, func_name='获取币种K线',
+                        if_exit=False
+                    )
+            except Exception as e:
+                print(e)
+                print(traceback.format_exc())
+                # 如果获取k线重试出错，直接返回，当前币种不参与交易
+                return pd.DataFrame()
+
+            # ===整理数据
+            # 将数据转换为DataFrame
+            df = pd.DataFrame(kline, dtype='float')
+            if df.empty:
+                break
+            # 对字段进行重命名，字段对应数据可以查询文档（https://binance-docs.github.io/apidocs/futures/cn/#k）
+            columns = {0: 'candle_begin_time', 1: 'open', 2: 'high', 3: 'low', 4: 'close', 5: 'volume', 6: 'close_time',
+                       7: 'quote_volume',
+                       8: 'trade_num', 9: 'taker_buy_base_asset_volume', 10: 'taker_buy_quote_asset_volume',
+                       11: 'ignore'}
+            df.rename(columns=columns, inplace=True)
+            df['candle_begin_time'] = pd.to_datetime(df['candle_begin_time'], unit='ms')
+            df.sort_values(by=['candle_begin_time'], inplace=True)  # 排序
+
+            # 数据追加
+            df_list.append(df)
+            data_len = data_len + df.shape[0] - 1
+
+            # 判断请求的数据是否足够
+            if data_len >= limit:
+                break
+
+            if params['startTime'] == int(df.iloc[-1]['candle_begin_time'].timestamp()) * 1000:
+                break
+
+            # 更新一下k线数据
+            params['startTime'] = int(df.iloc[-1]['candle_begin_time'].timestamp()) * 1000
+            # 下载太多的k线的时候，中间sleep一下
+            time.sleep(0.1)
+
+        if not df_list:
+            return pd.DataFrame()
+
+        all_df = pd.concat(df_list, ignore_index=True)
+        all_df['symbol'] = symbol  # 添加symbol列
+        all_df['symbol_type'] = symbol_type  # 添加类型字段
+        all_df.sort_values(by=['candle_begin_time'], inplace=True)  # 排序
+        all_df.drop_duplicates(subset=['candle_begin_time'], keep='last', inplace=True)  # 去重
+
+        # 删除runtime那根未走完的k线数据（交易所有时候会返回这条数据）
+        all_df = all_df[all_df['candle_begin_time'] + pd.Timedelta(hours=self.utc_offset) < run_time]
+        all_df.reset_index(drop=True, inplace=True)
+
+        return all_df
+
+    """最新报价数据获取"""
+
+    def fetch_ticker_price(self, symbol: str = None, symbol_type: str = 'swap') -> dict:
+        params = {'symbol': symbol} if symbol else {}
+        match symbol_type:
+            case 'spot':
+                api_func = self.exchange.public_get_ticker_price
+                func_name = f'获取{symbol}现货的ticker数据' if symbol else '获取所有现货币种的ticker数据'
+            case 'swap':
+                api_func = self.exchange.fapipublic_get_ticker_price
+                func_name = f'获取{symbol}合约的ticker数据' if symbol else '获取所有合约币种的ticker数据'
+            case _:
+                raise ValueError(f'未知的symbol_type：{symbol_type}')
+
+        tickers = retry_wrapper(api_func, params=params, func_name=func_name)
+        return tickers
+
+    def fetch_spot_ticker_price(self, spot_symbol: str = None) -> dict:
+        return self.fetch_ticker_price(spot_symbol, symbol_type='spot')
+
+    def fetch_swap_ticker_price(self, swap_symbol: str = None) -> dict:
+        return self.fetch_ticker_price(swap_symbol, symbol_type='swap')
+
+    def get_spot_ticker_price_series(self) -> pd.Series:
+        ticker_price_df = pd.DataFrame(self.fetch_ticker_price(symbol_type='spot'))
+        ticker_price_df['price'] = pd.to_numeric(ticker_price_df['price'], errors='coerce')
+        return ticker_price_df.set_index(['symbol'])['price']
+
+    def get_swap_ticker_price_series(self) -> pd.Series:
+        ticker_price_df = pd.DataFrame(self.fetch_ticker_price(symbol_type='swap'))
+        ticker_price_df['price'] = pd.to_numeric(ticker_price_df['price'], errors='coerce')
+        return ticker_price_df.set_index(['symbol'])['price']
+
+    """盘口数据获取"""
+
+    def fetch_book_ticker(self, symbol, symbol_type='swap') -> dict:
+        if symbol_type == 'swap':
+            # 获取合约的盘口数据
+            swap_book_ticker_data = retry_wrapper(
+                self.exchange.fapiPublicGetTickerBookTicker, params={'symbol': symbol}, func_name='获取合约盘口数据')
+            return swap_book_ticker_data
+        else:
+            # 获取现货的盘口数据
+            spot_book_ticker_data = retry_wrapper(
+                self.exchange.publicGetTickerBookTicker, params={'symbol': symbol}, func_name='获取现货盘口数据'
+            )
+            return spot_book_ticker_data
+
+    def fetch_spot_book_ticker(self, spot_symbol) -> dict:
+        return self.fetch_book_ticker(spot_symbol, symbol_type='spot')
+
+    def fetch_swap_book_ticker(self, swap_symbol) -> dict:
+        return self.fetch_book_ticker(swap_symbol, symbol_type='swap')
+
+    # endregion
+
+    # ====================================================================================================
+    # ** 资金费数据 **
+    # ====================================================================================================
+    def get_premium_index_df(self) -> pd.DataFrame:
+        """
+        获取币安的最新资金费数据
+        """
+        last_funding_df = retry_wrapper(self.exchange.fapipublic_get_premiumindex, func_name='获取最新的资金费数据')
+        last_funding_df = pd.DataFrame(last_funding_df)
+
+        last_funding_df['nextFundingTime'] = pd.to_numeric(last_funding_df['nextFundingTime'], errors='coerce')
+        last_funding_df['time'] = pd.to_numeric(last_funding_df['time'], errors='coerce')
+
+        last_funding_df['nextFundingTime'] = pd.to_datetime(last_funding_df['nextFundingTime'], unit='ms')
+        last_funding_df['time'] = pd.to_datetime(last_funding_df['time'], unit='ms')
+        last_funding_df = last_funding_df[['symbol', 'nextFundingTime', 'lastFundingRate']]  # 保留部分字段
+        last_funding_df.rename(columns={'nextFundingTime': 'fundingTime', 'lastFundingRate': 'fundingRate'},
+                               inplace=True)
+
+        return last_funding_df
+
+    def get_funding_rate_df(self, symbol, limit=1000) -> pd.DataFrame:
+        """
+        获取币安的历史资金费数据
+        :param symbol: 币种名称
+        :param limit: 请求获取多少条数据，最大1000
+        """
+        param = {'symbol': symbol, 'limit': limit}
+        # 获取历史数据
+        try:
+            funding_df = retry_wrapper(
+                self.exchange.fapipublic_get_fundingrate, params=param,
+                func_name='获取合约历史资金费数据'
+            )
+        except Exception as e:
+            print(e)
+            return pd.DataFrame()
+        funding_df = pd.DataFrame(funding_df)
+        if funding_df.empty:
+            return funding_df
+
+        funding_df['fundingTime'] = pd.to_datetime(funding_df['fundingTime'].astype(float) // 1000 * 1000,
+                                                   unit='ms')  # 时间戳内容含有一些纳秒数据需要处理
+        funding_df.sort_values('fundingTime', inplace=True)
+
+        return funding_df
+
+    # ====================================================================================================
+    # ** 账户设置 **
+    # ====================================================================================================
+    def fetch_transfer_history(self):
+        raise NotImplementedError
+
+    def set_single_side_position(self):
+        raise NotImplementedError
+
+    def set_multi_assets_margin(self):
+        """
+        检查是否开启了联合保证金模式
+        """
+        # 查询保证金模式
+        pass
+
+    def reset_max_leverage(self, max_leverage=5, coin_list=()):
+        """
+        重置一下页面最大杠杆
+        :param max_leverage:    设置页面最大杠杆
+        :param coin_list:       对指定币种进行调整页面杠杆
+        """
+        """
+        重置一下页面最大杠杆
+        :param exchange:        交易所对象，用于获取数据
+        :param max_leverage:    设置页面最大杠杆
+        :param coin_list:       对指定币种进行调整页面杠杆
+        """
+        # 获取账户持仓风险（这里有杠杆数据）
+        account_info = self.get_swap_account()
+        if account_info is None:
+            print(f'ℹ️获取账户持仓风险数据为空')
+            exit(1)
+
+        position_risk = pd.DataFrame(account_info['positions'])  # 将数据转成DataFrame
+        if len(coin_list) > 0:
+            position_risk = position_risk[position_risk['symbol'].isin(coin_list)]  # 只对选币池中的币种进行调整页面杠杆
+        position_risk.set_index('symbol', inplace=True)  # 将symbol设为index
+
+        # 遍历每一个可以持仓的币种，修改页面最大杠杆
+        for symbol, row in position_risk.iterrows():
+            if int(row['leverage']) != max_leverage:
+                reset_leverage_func = getattr(self.exchange, self.constants.get('reset_page_leverage_api'))
+                # 设置杠杆
+                retry_wrapper(
+                    reset_leverage_func,
+                    params={'symbol': symbol, 'leverage': max_leverage, 'timestamp': ''},
+                    func_name='设置杠杆'
+                )
+
+    # ====================================================================================================
+    # ** 交易函数 **
+    # ====================================================================================================
+    def cancel_all_spot_orders(self):
+        # 现货撤单
+        get_spot_open_orders_func = getattr(self.exchange, self.constants.get('get_spot_open_orders_api'))
+        orders = retry_wrapper(
+            get_spot_open_orders_func,
+            params={'timestamp': ''}, func_name='查询现货所有挂单'
+        )
+        symbols = [_['symbol'] for _ in orders]
+        symbols = list(set(symbols))
+        cancel_spot_open_orders_func = getattr(self.exchange, self.constants.get('cancel_spot_open_orders_api'))
+        for _ in symbols:
+            retry_wrapper(
+                cancel_spot_open_orders_func,
+                params={'symbol': _, 'timestamp': ''}, func_name='取消现货挂单'
+            )
+
+    def cancel_all_swap_orders(self):
+        # 合约撤单
+        get_swap_open_orders_func = getattr(self.exchange, self.constants.get('get_swap_open_orders_api'))
+        orders = retry_wrapper(
+            get_swap_open_orders_func,
+            params={'timestamp': ''}, func_name='查询U本位合约所有挂单'
+        )
+        symbols = [_['symbol'] for _ in orders]
+        symbols = list(set(symbols))
+        cancel_swap_open_orders_func = getattr(self.exchange, self.constants.get('cancel_swap_open_orders_api'))
+        for _ in symbols:
+            retry_wrapper(
+                cancel_swap_open_orders_func,
+                params={'symbol': _, 'timestamp': ''}, func_name='取消U本位合约挂单'
+            )
+
+    def prepare_order_params_list(
+            self, orders_df: pd.DataFrame, symbol_type: str, symbol_ticker_price: pd.Series,
+            slip_rate: float = 0.015) -> list:
+        """
+        根据策略产生的订单数据，构建每个币种的下单参数
+        :param orders_df: 策略产生的订单信息
+        :param symbol_type: 下单类型。spot/swap
+        :param symbol_ticker_price: 每个币种最新价格
+        :param slip_rate: 滑点
+        :return: order_params_list 每个币种的下单参数
+        """
+        orders_df.sort_values('实际下单资金', ascending=True, inplace=True)
+        orders_df.set_index('symbol', inplace=True)  # 重新设置index
+
+        market_info = self.get_market_info(symbol_type)
+        min_qty = market_info['min_qty']
+        price_precision = market_info['price_precision']
+        min_notional = market_info['min_notional']
+
+        # 遍历symbol_order，构建每个币种的下单参数
+        order_params_list = []
+        for symbol, row in orders_df.iterrows():
+            # ===若当前币种没有最小下单精度、或最小价格精度，报错
+            if (symbol not in min_qty) or (symbol not in price_precision):
+                # 报错
+                print(f'❌当前币种{symbol}没有最小下单精度、或最小价格精度，币种信息异常')
+                continue
+
+            # ===计算下单量、方向、价格
+            quantity = row['实际下单量']
+            # 按照最小下单量对合约进行四舍五入，对现货就低不就高处理
+            # 注意点：合约有reduceOnly参数可以超过你持有的持仓量，现货不行，只能卖的时候留一点点残渣
+            quantity = round(quantity, min_qty[symbol]) if symbol_type == 'swap' else apply_precision(quantity,
+                                                                                                      min_qty[symbol])
+            # 计算下单方向、价格，并增加一定的滑点
+            if quantity > 0:
+                side = 'BUY'
+                price = symbol_ticker_price[symbol] * (1 + slip_rate)
+            elif quantity < 0:
+                side = 'SELL'
+                price = symbol_ticker_price[symbol] * (1 - slip_rate)
+            else:
+                print('⚠️下单量为0，不进行下单')
+                continue
+            # 下单量取绝对值
+            quantity = abs(quantity)
+            # 通过最小价格精度对下单价格进行四舍五入
+            price = round(price, price_precision[symbol])
+
+            # ===判断是否是清仓交易
+            reduce_only = True if row['交易模式'] == '清仓' and symbol_type == 'swap' else False
+
+            # ===判断交易金额是否小于最小下单金额（一般是5元），小于的跳过
+            if quantity * price < min_notional.get(symbol, self.order_money_limit[symbol_type]):
+                if not reduce_only:  # 清仓状态不跳过
+                    print(f'⚠️{symbol}交易金额是小于最小下单金额（一般合约是5元，现货是10元），跳过该笔交易')
+                    print(f'ℹ️下单量：{quantity},价格：{price}')
+                    continue
+
+            # ===构建下单参数
+            price = f'{price:.{price_precision[symbol]}f}'  # 根据精度将价格转成str
+            quantity = np.format_float_positional(quantity).rstrip('.')  # 解决科学计数法的问题
+            order_params = {
+                'symbol': symbol,
+                'side': side,
+                'type': 'LIMIT',
+                'price': price,
+                'quantity': quantity,
+                'newClientOrderId': str(int(time.time())),
+                'timeInForce': 'GTC',
+                'reduceOnly': str(bool(reduce_only)),
+                'timestamp': ''
+            }
+            # 如果是合约下单，添加进行下单列表中，放便后续批量下单
+            order_params_list.append(order_params)
+        return order_params_list
+
+    def place_spot_orders_bulk(self, orders_df, slip_rate=0.015):
+        symbol_last_price = self.get_spot_ticker_price_series()
+        order_params_list = self.prepare_order_params_list(orders_df, 'spot', symbol_last_price, slip_rate)
+
+        for order_param in order_params_list:
+            del order_param['reduceOnly']  # 现货没有这个参数，进行移除
+            self.place_spot_order(**order_param)
+
+    def place_swap_orders_bulk(self, orders_df, slip_rate=0.015):
+        symbol_last_price = self.get_swap_ticker_price_series()
+        order_params_list = self.prepare_order_params_list(orders_df, 'swap', symbol_last_price, slip_rate)
+
+        for order_params in order_params_list:
+            self.place_swap_order(**order_params)
+
+    def place_spot_order(self, symbol, side, quantity, price=None, **kwargs) -> dict:
+        print(f'`{symbol}`现货下单 {side} {quantity}', '.')
+
+        # 确定下单参数
+        params = {
+            'symbol': symbol,
+            'side': side,
+            'type': 'MARKET',
+            'quantity': str(quantity),
+            **kwargs
+        }
+
+        if price is not None:
+            params['price'] = str(price)
+            params['timeInForce'] = 'GTC'
+            params['type'] = 'LIMIT'
+
+        try:
+            print(f'ℹ️现货下单参数：{params}')
+            # 下单
+            order_res = retry_wrapper(
+                self.exchange.private_post_order,
+                params=params,
+                func_name='现货下单'
+            )
+            print(f'✅现货下单完成，现货下单信息结果：{order_res}')
+        except Exception as e:
+            print(f'❌现货下单出错：{e}')
+            send_wechat_work_msg(
+                f'现货 {symbol} 下单 {float(quantity) * float(price)}U 出错，请查看程序日志',
+                self.wechat_webhook_url
+            )
+            return {}
+            # 发送下单结果到钉钉
+        send_msg_for_order([params], [order_res], self.wechat_webhook_url)
+        return order_res
+
+    def place_swap_order(self, symbol, side, quantity, price=None, **kwargs) -> dict:
+        print(f'`{symbol}`U本位合约下单 {side} {quantity}', '.')
+
+        # 确定下单参数
+        params = {
+            'symbol': symbol,
+            'side': side,
+            'type': 'MARKET',
+            'quantity': str(quantity),
+            **kwargs
+        }
+
+        if price is not None:
+            params['price'] = str(price)
+            params['timeInForce'] = 'GTC'
+            params['type'] = 'LIMIT'
+
+        try:
+            print(f'ℹ️U本位合约下单参数：{params}')
+            # 下单
+            order_res = retry_wrapper(
+                self.exchange.fapiprivate_post_order,
+                params=params,
+                func_name='U本位合约下单'
+            )
+            print(f'✅U本位合约下单完成，U本位合约下单信息结果：{order_res}')
+        except Exception as e:
+            print(f'❌U本位合约下单出错：{e}')
+            send_wechat_work_msg(
+                f'U本位合约 {symbol} 下单 {float(quantity) * float(price)}U 出错，请查看程序日志',
+                self.wechat_webhook_url
+            )
+            return {}
+        send_msg_for_order([params], [order_res], self.wechat_webhook_url)
+        return order_res
+
+    def get_spot_position_df(self) -> pd.DataFrame:
+        """
+        获取账户净值
+
+
+        :return:
+            swap_equity=1000  (表示账户里资金总价值为 1000U )
+
+        """
+        # 获取U本位合约账户净值(不包含未实现盈亏)
+        position_df = retry_wrapper(self.exchange.private_get_account, params={'timestamp': ''},
+                                    func_name='获取现货账户净值')  # 获取账户净值
+        position_df = pd.DataFrame(position_df['balances'])
+
+        position_df['free'] = pd.to_numeric(position_df['free'])
+        position_df['locked'] = pd.to_numeric(position_df['locked'])
+
+        position_df['free'] += position_df['locked']
+        position_df = position_df[position_df['free'] != 0]
+
+        position_df.rename(columns={'asset': 'symbol', 'free': '当前持仓量'}, inplace=True)
+
+        # 保留指定字段
+        position_df = position_df[['symbol', '当前持仓量']]
+        position_df['仓位价值'] = None  # 设置默认值
+
+        return position_df
+
+    # =====获取持仓
+    # 获取币安账户的实际持仓
+    def get_swap_position_df(self) -> pd.DataFrame:
+        """
+        获取币安账户的实际持仓
+
+        :return:
+
+                  当前持仓量   均价  持仓盈亏
+        symbol
+        RUNEUSDT       -82.0  1.208 -0.328000
+        FTMUSDT        523.0  0.189  1.208156
+
+        """
+        # 获取原始数据
+        get_swap_position_func = getattr(self.exchange, self.constants.get('get_swap_position_api'))
+        position_df = retry_wrapper(get_swap_position_func, params={'timestamp': ''}, func_name='获取账户持仓风险')
+        if position_df is None or len(position_df) == 0:
+            return pd.DataFrame(columns=['symbol', '当前持仓量', '均价', '持仓盈亏', '当前标记价格', '仓位价值'])
+
+        position_df = pd.DataFrame(position_df)  # 将原始数据转化为dataframe
+
+        # 整理数据
+        columns = {'positionAmt': '当前持仓量', 'entryPrice': '均价', 'unRealizedProfit': '持仓盈亏',
+                   'markPrice': '当前标记价格'}
+        position_df.rename(columns=columns, inplace=True)
+        for col in columns.values():  # 转成数字
+            position_df[col] = pd.to_numeric(position_df[col])
+
+        position_df = position_df[position_df['当前持仓量'] != 0]  # 只保留有仓位的币种
+        position_df.set_index('symbol', inplace=True)  # 将symbol设置为index
+        position_df['仓位价值'] = position_df['当前持仓量'] * position_df['当前标记价格']
+
+        # 保留指定字段
+        position_df = position_df[['当前持仓量', '均价', '持仓盈亏', '当前标记价格', '仓位价值']]
+
+        return position_df
+
+    def update_swap_account(self) -> dict:
+        self.swap_account = retry_wrapper(
+            self.exchange.fapiprivatev2_get_account, params={'timestamp': ''},
+            func_name='获取U本位合约账户信息'
+        )
+        return self.swap_account
+
+    def get_swap_account(self, require_update: bool = False) -> dict:
+        if self.swap_account is None or require_update:
+            self.update_swap_account()
+        return self.swap_account
+
+    def get_account_overview(self):
+        raise NotImplementedError
+
+    def fetch_spot_trades(self, symbol, end_time) -> pd.DataFrame:
+        # =设置获取订单时的参数
+        params = {
+            'symbol': symbol,  # 设置获取订单的币种
+            'endTime': int(time.mktime(end_time.timetuple())) * 1000,  # 设置获取订单的截止时间
+            'limit': 1000,  # 最大获取1000条订单信息
+            'timestamp': ''
+        }
+
+        # =调用API获取订单信息
+        get_spot_my_trades_func = getattr(self.exchange, self.constants.get('get_spot_my_trades_api'))
+        trades = retry_wrapper(get_spot_my_trades_func, params=params, func_name='获取币种历史订单信息',
+                               if_exit=False)  # 获取账户净值
+        # 如果获取订单数据失败，进行容错处理，返回空df
+        if trades is None:
+            return pd.DataFrame()
+
+        trades = pd.DataFrame(trades)  # 转成df格式
+        # =如果获取到的该币种的订单数据是空的，则跳过，继续获取另外一个币种
+        if trades.empty:
+            return pd.DataFrame()
+
+        # 转换数据格式
+        for col in ('isBuyer', 'price', 'qty', 'quoteQty', 'commission'):
+            trades[col] = pd.to_numeric(trades[col], errors='coerce')
+
+        # =如果isBuyer为1则为买入，否则为卖出
+        trades['方向'] = np.where(trades['isBuyer'] == 1, 1, -1)
+        # =整理下有用的数据
+        trades = trades[['time', 'symbol', 'price', 'qty', 'quoteQty', 'commission', 'commissionAsset', '方向']]
+
+        return trades
+
+    @classmethod
+    def get_dummy_client(cls) -> 'BinanceClient':
+        return cls()

基础库/common_core/exchange/binance_async.py

@@ -0,0 +1,172 @@
+"""
+Quant Unified 量化交易系统
+[币安异步交易客户端]
+功能：基于 AsyncIO 实现高并发行情获取与交易指令发送，大幅提升数据下载和实盘响应速度。
+"""
+import asyncio
+import math
+import time
+import traceback
+import ccxt.async_support as ccxt  # 异步 CCXT
+import pandas as pd
+import numpy as np
+
+from common_core.exchange.base_client import BinanceClient
+from common_core.utils.async_commons import async_retry_wrapper
+
+class AsyncBinanceClient(BinanceClient):
+    def __init__(self, **config):
+        super().__init__(**config)
+        # 使用异步版本覆盖 self.exchange
+        default_exchange_config = {
+            'timeout': 30000,
+            'rateLimit': 30,
+            'enableRateLimit': False,
+            'options': {'adjustForTimeDifference': True, 'recvWindow': 10000},
+        }
+        self.exchange = ccxt.binance(config.get('exchange_config', default_exchange_config))
+    
+    async def close(self):
+        await self.exchange.close()
+
+    async def _fetch_swap_exchange_info_list(self) -> list:
+        exchange_info = await async_retry_wrapper(self.exchange.fapipublic_get_exchangeinfo, func_name='获取BN合约币种规则数据')
+        return exchange_info['symbols']
+
+    async def _fetch_spot_exchange_info_list(self) -> list:
+        exchange_info = await async_retry_wrapper(self.exchange.public_get_exchangeinfo, func_name='获取BN现货币种规则数据')
+        return exchange_info['symbols']
+
+    async def fetch_market_info(self, symbol_type='swap', quote_symbol='USDT'):
+        print(f'🔄(Async) 更新{symbol_type}市场数据...')
+        if symbol_type == 'swap':
+            exchange_info_list = await self._fetch_swap_exchange_info_list()
+        else:
+            exchange_info_list = await self._fetch_spot_exchange_info_list()
+        
+        # 复用基类逻辑？
+        # 逻辑是处理列表。我们可以复制或提取它。
+        # 为了速度，我将在这里复制处理逻辑。
+        
+        symbol_list = []
+        full_symbol_list = []
+        min_qty = {}
+        price_precision = {}
+        min_notional = {}
+
+        for info in exchange_info_list:
+            symbol = info['symbol']
+            if info['quoteAsset'] != quote_symbol or info['status'] != 'TRADING':
+                continue
+            full_symbol_list.append(symbol)
+
+            if (symbol_type == 'swap' and info['contractType'] != 'PERPETUAL') or info['baseAsset'] in self.stable_symbol:
+                pass
+            else:
+                symbol_list.append(symbol)
+
+            for _filter in info['filters']:
+                if _filter['filterType'] == 'PRICE_FILTER':
+                    price_precision[symbol] = int(math.log(float(_filter['tickSize']), 0.1))
+                elif _filter['filterType'] == 'LOT_SIZE':
+                    min_qty[symbol] = int(math.log(float(_filter['minQty']), 0.1))
+                elif _filter['filterType'] == 'MIN_NOTIONAL' and symbol_type == 'swap':
+                    min_notional[symbol] = float(_filter['notional'])
+                elif _filter['filterType'] == 'NOTIONAL' and symbol_type == 'spot':
+                    min_notional[symbol] = float(_filter['minNotional'])
+
+        self.market_info[symbol_type] = {
+            'symbol_list': symbol_list,
+            'full_symbol_list': full_symbol_list,
+            'min_qty': min_qty,
+            'price_precision': price_precision,
+            'min_notional': min_notional,
+            'last_update': int(time.time())
+        }
+        return self.market_info[symbol_type]
+
+    async def get_market_info(self, symbol_type, expire_seconds: int = 3600 * 12, require_update: bool = False, quote_symbol='USDT'):
+        if require_update:
+            last_update = 0
+        else:
+            last_update = self.market_info.get(symbol_type, {}).get('last_update', 0)
+        
+        if last_update + expire_seconds < int(time.time()):
+            await self.fetch_market_info(symbol_type, quote_symbol)
+        
+        return self.market_info[symbol_type]
+
+    async def get_candle_df(self, symbol, run_time, limit=1500, interval='1h', symbol_type='swap') -> pd.DataFrame:
+        _limit = limit
+        if limit > 1000:
+            if symbol_type == 'spot':
+                _limit = 1000
+            else:
+                _limit = 499
+        
+        start_time_dt = run_time - pd.to_timedelta(interval) * limit
+        df_list = []
+        data_len = 0
+        params = {
+            'symbol': symbol,
+            'interval': interval,
+            'limit': _limit,
+            'startTime': int(time.mktime(start_time_dt.timetuple())) * 1000
+        }
+
+        while True:
+            try:
+                if symbol_type == 'swap':
+                    kline = await async_retry_wrapper(
+                        self.exchange.fapipublic_get_klines, params=params, func_name=f'获取{symbol}K线', if_exit=False
+                    )
+                else:
+                    kline = await async_retry_wrapper(
+                        self.exchange.public_get_klines, params=params, func_name=f'获取{symbol}K线', if_exit=False
+                    )
+            except Exception as e:
+                print(f"Error fetching {symbol}: {e}")
+                return pd.DataFrame()
+
+            if not kline:
+                break
+            
+            df = pd.DataFrame(kline, dtype='float')
+            if df.empty:
+                break
+
+            columns = {0: 'candle_begin_time', 1: 'open', 2: 'high', 3: 'low', 4: 'close', 5: 'volume', 6: 'close_time',
+                       7: 'quote_volume', 8: 'trade_num', 9: 'taker_buy_base_asset_volume', 10: 'taker_buy_quote_asset_volume',
+                       11: 'ignore'}
+            df.rename(columns=columns, inplace=True)
+            df['candle_begin_time'] = pd.to_datetime(df['candle_begin_time'], unit='ms')
+            
+            # 优化：稍后进行排序和去重
+            
+            df_list.append(df)
+            data_len += df.shape[0]
+
+            if data_len >= limit:
+                break
+            
+            last_time = int(df.iloc[-1]['candle_begin_time'].timestamp()) * 1000
+            if params['startTime'] == last_time:
+                break
+            
+            params['startTime'] = last_time
+            # 异步 sleep 通常在这里不需要，因为我们要尽可能快，但为了安全起见：
+            # await asyncio.sleep(0.01) 
+
+        if not df_list:
+            return pd.DataFrame()
+
+        all_df = pd.concat(df_list, ignore_index=True)
+        all_df['symbol'] = symbol
+        all_df['symbol_type'] = symbol_type
+        all_df.sort_values(by=['candle_begin_time'], inplace=True)
+        all_df.drop_duplicates(subset=['candle_begin_time'], keep='last', inplace=True)
+
+        all_df = all_df[all_df['candle_begin_time'] + pd.Timedelta(hours=self.utc_offset) < run_time]
+        all_df.reset_index(drop=True, inplace=True)
+
+        return all_df

基础库/common_core/exchange/standard_client.py

@@ -0,0 +1,284 @@
+"""
+Quant Unified 量化交易系统
+[币安标准同步客户端]
+功能：提供传统的同步接口调用方式，用于兼容旧代码或低频操作场景，支持现货和合约的下单、撤单、查询等操作。
+"""
+
+import time
+from datetime import datetime
+
+import pandas as pd
+
+from common_core.exchange.base_client import BinanceClient
+from common_core.utils.commons import retry_wrapper
+
+
+class StandardClient(BinanceClient):
+    constants = dict(
+        spot_account_type='SPOT',
+        reset_page_leverage_api='fapiprivate_post_leverage',
+        get_swap_position_api='fapiprivatev2_get_positionrisk',
+        get_spot_open_orders_api='private_get_openorders',
+        cancel_spot_open_orders_api='private_delete_openorders',
+        get_swap_open_orders_api='fapiprivate_get_openorders',
+        cancel_swap_open_orders_api='fapiprivate_delete_allopenorders',
+        get_spot_my_trades_api='private_get_mytrades',
+    )
+
+    def __init__(self, **config):
+        super().__init__(**config)
+        self.is_pure_long: bool = config.get('is_pure_long', False)
+
+    def _set_position_side(self, dual_side_position=False):
+        """
+        检查是否是单向持仓模式
+        """
+        params = {'dualSidePosition': 'true' if dual_side_position else 'false', 'timestamp': ''}
+        retry_wrapper(self.exchange.fapiprivate_post_positionside_dual, params=params,
+                      func_name='fapiprivate_post_positionside_dual', if_exit=False)
+        print(f'ℹ️修改持仓模式为单向持仓')
+
+    def set_single_side_position(self):
+
+        # 查询持仓模式
+        res = retry_wrapper(
+            self.exchange.fapiprivate_get_positionside_dual, params={'timestamp': ''}, func_name='设置单向持仓',
+            if_exit=False
+        )
+
+        is_duel_side_position = bool(res['dualSidePosition'])
+
+        # 判断是否是单向持仓模式
+        if is_duel_side_position:  # 若当前持仓模式不是单向持仓模式，则调用接口修改持仓模式为单向持仓模式
+            self._set_position_side(dual_side_position=False)
+
+    def set_multi_assets_margin(self):
+        """
+        检查是否开启了联合保证金模式
+        """
+        # 查询保证金模式
+        res = retry_wrapper(self.exchange.fapiprivate_get_multiassetsmargin, params={'timestamp': ''},
+                            func_name='fapiprivate_get_multiassetsmargin', if_exit=False)
+        # 判断是否开启了联合保证金模式
+        if not bool(res['multiAssetsMargin']):  # 若联合保证金模式没有开启，则调用接口开启一下联合保证金模式
+            params = {'multiAssetsMargin': 'true', 'timestamp': ''}
+            retry_wrapper(self.exchange.fapiprivate_post_multiassetsmargin, params=params,
+                          func_name='fapiprivate_post_multiassetsmargin', if_exit=False)
+            print('✅开启联合保证金模式')
+
+    def get_account_overview(self):
+        spot_ticker_data = self.fetch_spot_ticker_price()
+        spot_ticker = {_['symbol']: float(_['price']) for _ in spot_ticker_data}
+
+        swap_account = self.get_swap_account()
+        equity = pd.DataFrame(swap_account['assets'])
+        swap_usdt_balance = float(equity[equity['asset'] == 'USDT']['walletBalance'])  # 获取usdt资产
+        # 计算联合保证金
+        if self.coin_margin:
+            for _symbol, _coin_balance in self.coin_margin.items():
+                if _symbol.replace('USDT', '') in equity['asset'].to_list():
+                    swap_usdt_balance += _coin_balance
+                else:
+                    print(f'⚠️合约账户未找到 {_symbol} 的资产，无法计算 {_symbol} 的保证金')
+
+        swap_position_df = self.get_swap_position_df()
+        spot_position_df = self.get_spot_position_df()
+        print('✅获取账户资产数据完成\n')
+
+        print(f'ℹ️准备处理资产数据...')
+        # 获取当前账号现货U的数量
+        if 'USDT' in spot_position_df['symbol'].to_list():
+            spot_usdt_balance = spot_position_df.loc[spot_position_df['symbol'] == 'USDT', '当前持仓量'].iloc[0]
+            # 去除掉USDT现货
+            spot_position_df = spot_position_df[spot_position_df['symbol'] != 'USDT']
+        else:
+            spot_usdt_balance = 0
+        # 追加USDT后缀，方便计算usdt价值
+        spot_position_df.loc[spot_position_df['symbol'] != 'USDT', 'symbol'] = spot_position_df['symbol'] + 'USDT'
+        spot_position_df['仓位价值'] = spot_position_df.apply(
+            lambda row: row['当前持仓量'] * spot_ticker.get(row["symbol"], 0), axis=1)
+
+        # 过滤掉不含报价的币
+        spot_position_df = spot_position_df[spot_position_df['仓位价值'] != 0]
+        # 仓位价值 小于 5U，无法下单的碎币，单独记录
+        dust_spot_df = spot_position_df[spot_position_df['仓位价值'] < 5]
+        # 过滤掉仓位价值 小于 5U
+        spot_position_df = spot_position_df[spot_position_df['仓位价值'] > 5]
+        # 过滤掉BNB，用于抵扣手续费，不参与现货交易
+        spot_position_df = spot_position_df[spot_position_df['symbol'] != 'BNBUSDT']
+
+        # 现货净值
+        spot_equity = spot_position_df['仓位价值'].sum() + spot_usdt_balance
+
+        # 持仓盈亏
+        account_pnl = swap_position_df['持仓盈亏'].sum()
+
+        # =====处理现货持仓列表信息
+        # 构建币种的balance信息
+        # 币种 : 价值
+        spot_assets_pos_dict = spot_position_df[['symbol', '仓位价值']].to_dict(orient='records')
+        spot_assets_pos_dict = {_['symbol']: _['仓位价值'] for _ in spot_assets_pos_dict}
+
+        # 币种 : 数量
+        spot_asset_amount_dict = spot_position_df[['symbol', '当前持仓量']].to_dict(orient='records')
+        spot_asset_amount_dict = {_['symbol']: _['当前持仓量'] for _ in spot_asset_amount_dict}
+
+        # =====处理合约持仓列表信息
+        # 币种 : 价值
+        swap_position_df.reset_index(inplace=True)
+        swap_assets_pos_dict = swap_position_df[['symbol', '仓位价值']].to_dict(orient='records')
+        swap_assets_pos_dict = {_['symbol']: _['仓位价值'] for _ in swap_assets_pos_dict}
+
+        # 币种 : 数量
+        swap_asset_amount_dict = swap_position_df[['symbol', '当前持仓量']].to_dict(orient='records')
+        swap_asset_amount_dict = {_['symbol']: _['当前持仓量'] for _ in swap_asset_amount_dict}
+
+        # 币种 : pnl
+        swap_asset_pnl_dict = swap_position_df[['symbol', '持仓盈亏']].to_dict(orient='records')
+        swap_asset_pnl_dict = {_['symbol']: _['持仓盈亏'] for _ in swap_asset_pnl_dict}
+
+        # 处理完成之后在设置index
+        swap_position_df.set_index('symbol', inplace=True)
+
+        # 账户总净值 = 现货总价值 + 合约usdt + 持仓盈亏
+        account_equity = (spot_equity + swap_usdt_balance + account_pnl)
+
+        print('✅处理资产数据完成\n')
+
+        return {
+            'usdt_balance': spot_usdt_balance + swap_usdt_balance,
+            'negative_balance': 0,
+            'account_pnl': account_pnl,
+            'account_equity': account_equity,
+            'spot_assets': {
+                'assets_pos_value': spot_assets_pos_dict,
+                'assets_amount': spot_asset_amount_dict,
+                'usdt': spot_usdt_balance,
+                'equity': spot_equity,
+                'dust_spot_df': dust_spot_df,
+                'spot_position_df': spot_position_df
+            },
+            'swap_assets': {
+                'assets_pos_value': swap_assets_pos_dict,
+                'assets_amount': swap_asset_amount_dict,
+                'assets_pnl': swap_asset_pnl_dict,
+                'usdt': swap_usdt_balance,
+                'equity': swap_usdt_balance + account_pnl,
+                'swap_position_df': swap_position_df
+            }
+        }
+
+    def fetch_transfer_history(self, start_time=datetime.now()):
+        """
+        获取划转记录
+
+        MAIN_UMFUTURE 现货钱包转向U本位合约钱包
+        MAIN_MARGIN 现货钱包转向杠杆全仓钱包
+
+        UMFUTURE_MAIN U本位合约钱包转向现货钱包
+        UMFUTURE_MARGIN U本位合约钱包转向杠杆全仓钱包
+
+        CMFUTURE_MAIN 币本位合约钱包转向现货钱包
+
+        MARGIN_MAIN 杠杆全仓钱包转向现货钱包
+        MARGIN_UMFUTURE 杠杆全仓钱包转向U本位合约钱包
+
+        MAIN_FUNDING 现货钱包转向资金钱包
+        FUNDING_MAIN 资金钱包转向现货钱包
+
+        FUNDING_UMFUTURE 资金钱包转向U本位合约钱包
+        UMFUTURE_FUNDING U本位合约钱包转向资金钱包
+
+        MAIN_OPTION 现货钱包转向期权钱包
+        OPTION_MAIN 期权钱包转向现货钱包
+
+        UMFUTURE_OPTION U本位合约钱包转向期权钱包
+        OPTION_UMFUTURE 期权钱包转向U本位合约钱包
+
+        MAIN_PORTFOLIO_MARGIN 现货钱包转向统一账户钱包
+        PORTFOLIO_MARGIN_MAIN 统一账户钱包转向现货钱包
+
+        MAIN_ISOLATED_MARGIN 现货钱包转向逐仓账户钱包
+        ISOLATED_MARGIN_MAIN 逐仓钱包转向现货账户钱包
+        """
+        start_time = start_time - pd.Timedelta(days=10)
+        add_type = ['CMFUTURE_MAIN', 'MARGIN_MAIN', 'MARGIN_UMFUTURE', 'FUNDING_MAIN', 'FUNDING_UMFUTURE',
+                    'OPTION_MAIN', 'OPTION_UMFUTURE', 'PORTFOLIO_MARGIN_MAIN', 'ISOLATED_MARGIN_MAIN']
+        reduce_type = ['MAIN_MARGIN', 'UMFUTURE_MARGIN', 'MAIN_FUNDING', 'UMFUTURE_FUNDING', 'MAIN_OPTION',
+                       'UMFUTURE_OPTION', 'MAIN_PORTFOLIO_MARGIN', 'MAIN_ISOLATED_MARGIN']
+
+        result = []
+        for _ in add_type + reduce_type:
+            params = {
+                'fromSymbol': 'USDT',
+                'startTime': int(start_time.timestamp() * 1000),
+                'type': _,
+                'timestamp': int(round(time.time() * 1000)),
+                'size': 100,
+            }
+            if _ == 'MAIN_ISOLATED_MARGIN':
+                params['toSymbol'] = 'USDT'
+                del params['fromSymbol']
+            # 获取划转信息(取上一小时到当前时间的划转记录)
+            try:
+                account_info = self.exchange.sapi_get_asset_transfer(params)
+            except BaseException as e:
+                print(e)
+                print(f'当前账户查询类型【{_}】失败，不影响后续操作，请忽略')
+                continue
+            if account_info and int(account_info['total']) > 0:
+                res = pd.DataFrame(account_info['rows'])
+                res['timestamp'] = pd.to_datetime(res['timestamp'], unit='ms')
+                res.loc[res['type'].isin(add_type), 'flag'] = 1
+                res.loc[res['type'].isin(reduce_type), 'flag'] = -1
+                res = res[res['status'] == 'CONFIRMED']
+                result.append(res)
+
+        # 获取主账号与子账号之间划转记录
+        result2 = []
+        for transfer_type in [1, 2]:  # 1: 划入。从主账号划转进来  2: 划出。从子账号划转出去
+            params = {
+                'asset': 'USDT',
+                'type': transfer_type,
+                'startTime': int(start_time.timestamp() * 1000),
+            }
+            try:
+                account_info = self.exchange.sapi_get_sub_account_transfer_subuserhistory(params)
+            except BaseException as e:
+                print(e)
+                print(f'当前账户查询类型【{transfer_type}】失败，不影响后续操作，请忽略')
+                continue
+            if account_info and len(account_info):
+                res = pd.DataFrame(account_info)
+                res['time'] = pd.to_datetime(res['time'], unit='ms')
+                res.rename(columns={'qty': 'amount', 'time': 'timestamp'}, inplace=True)
+                res.loc[res['toAccountType'] == 'SPOT', 'flag'] = 1 if transfer_type == 1 else -1
+                res.loc[res['toAccountType'] == 'USDT_FUTURE', 'flag'] = 1 if transfer_type == 1 else -1
+                res = res[res['status'] == 'SUCCESS']
+                res = res[res['toAccountType'].isin(['SPOT', 'USDT_FUTURE'])]
+                result2.append(res)
+
+        # 将账号之间的划转与单账号内部换转数据合并
+        result.extend(result2)
+        if not len(result):
+            return pd.DataFrame()
+
+        all_df = pd.concat(result, ignore_index=True)
+        all_df.drop_duplicates(subset=['timestamp', 'tranId', 'flag'], inplace=True)
+        all_df = all_df[all_df['asset'] == 'USDT']
+        all_df.sort_values('timestamp', inplace=True)
+
+        all_df['amount'] = all_df['amount'].astype(float) * all_df['flag']
+        all_df.rename(columns={'amount': '账户总净值'}, inplace=True)
+        all_df['type'] = 'transfer'
+        all_df = all_df[['timestamp', '账户总净值', 'type']]
+        all_df['timestamp'] = all_df['timestamp'] + pd.Timedelta(hours=self.utc_offset)
+        all_df.reset_index(inplace=True, drop=True)
+
+        all_df['time'] = all_df['timestamp']
+        result_df = all_df.resample(rule='1H', on='timestamp').agg(
+            {'time': 'last', '账户总净值': 'sum', 'type': 'last'})
+        result_df = result_df[result_df['type'].notna()]
+        result_df.reset_index(inplace=True, drop=True)
+
+        return result_df

基础库/common_core/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quant-unified-common-core"
+version = "0.1.0"
+description = "Quant Unified 通用核心库：交易所客户端、回测、风控与工具集"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Quant Unified Team" }]
+license = { text = "Proprietary" }
+dependencies = [
+    "ccxt>=4.3.0",
+    "pandas>=2.2.0",
+    "numpy>=1.26.0",
+    "aiohttp>=3.9.0",
+    "numba>=0.59.0",
+    "plotly>=5.18.0",
+    "scipy>=1.10.0",
+]
+
+[tool.setuptools]
+packages = { find = { where = ["."] } }
+

基础库/common_core/quant_unified_common_core.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: quant-unified-common-core
+Version: 0.1.0
+Summary: Quant Unified 通用核心库：交易所客户端、回测、风控与工具集
+Author: Quant Unified Team
+License: Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: ccxt>=4.3.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: numba>=0.59.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: scipy>=1.10.0

基础库/common_core/quant_unified_common_core.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+pyproject.toml
+backtest/__init__.py
+backtest/equity.py
+backtest/evaluate.py
+backtest/figure.py
+backtest/rebalance.py
+backtest/simulator.py
+backtest/version.py
+exchange/__init__.py
+exchange/base_client.py
+exchange/binance_async.py
+exchange/standard_client.py
+quant_unified_common_core.egg-info/PKG-INFO
+quant_unified_common_core.egg-info/SOURCES.txt
+quant_unified_common_core.egg-info/dependency_links.txt
+quant_unified_common_core.egg-info/requires.txt
+quant_unified_common_core.egg-info/top_level.txt
+risk_ctrl/liquidation.py
+risk_ctrl/test_liquidation.py
+utils/__init__.py
+utils/async_commons.py
+utils/commons.py
+utils/dingding.py
+utils/factor_hub.py
+utils/functions.py
+utils/path_kit.py

基础库/common_core/quant_unified_common_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

基础库/common_core/quant_unified_common_core.egg-info/requires.txt

@@ -0,0 +1,7 @@
+ccxt>=4.3.0
+pandas>=2.2.0
+numpy>=1.26.0
+aiohttp>=3.9.0
+numba>=0.59.0
+plotly>=5.18.0
+scipy>=1.10.0

基础库/common_core/quant_unified_common_core.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+backtest
+exchange
+risk_ctrl
+utils

基础库/common_core/risk_ctrl/liquidation.py

@@ -0,0 +1,45 @@
+"""
+Quant Unified 量化交易系统
+[爆仓检查模块]
+功能：提供通用的保证金率计算与爆仓检测逻辑，支持单币种和多币种组合模式。
+"""
+import numpy as np
+
+class LiquidationChecker:
+    """
+    通用爆仓检查器
+    """
+    def __init__(self, min_margin_rate=0.005):
+        """
+        初始化
+        :param min_margin_rate: 维持保证金率 (默认 0.5%)
+        """
+        self.min_margin_rate = min_margin_rate
+
+    def check_margin_rate(self, equity, position_value):
+        """
+        检查保证金率
+        :param equity: 当前账户权益 (USDT)
+        :param position_value: 当前持仓名义价值 (USDT, 绝对值之和)
+        :return: (is_liquidated, margin_rate)
+                 is_liquidated: 是否爆仓 (True/False)
+                 margin_rate: 当前保证金率
+        """
+        if position_value < 1e-8:
+            # 无持仓，无限安全
+            return False, 999.0
+            
+        margin_rate = equity / float(position_value)
+        
+        is_liquidated = margin_rate < self.min_margin_rate
+        
+        return is_liquidated, margin_rate
+
+    @staticmethod
+    def calculate_margin_rate(equity, position_value):
+        """
+        静态方法：纯计算保证金率
+        """
+        if position_value < 1e-8:
+            return 999.0
+        return equity / float(position_value)

基础库/common_core/risk_ctrl/test_liquidation.py

@@ -0,0 +1,34 @@
+
+import unittest
+from common_core.risk_ctrl.liquidation import LiquidationChecker
+
+class TestLiquidationChecker(unittest.TestCase):
+    def setUp(self):
+        self.checker = LiquidationChecker(min_margin_rate=0.005)
+
+    def test_safe_state(self):
+        # 权益 10000, 持仓 10000 -> 保证金率 100% -> 安全
+        is_liq, rate = self.checker.check_margin_rate(10000, 10000)
+        self.assertFalse(is_liq)
+        self.assertEqual(rate, 1.0)
+
+    def test_warning_state(self):
+        # 权益 100, 持仓 10000 -> 保证金率 1% -> 安全但危险
+        is_liq, rate = self.checker.check_margin_rate(100, 10000)
+        self.assertFalse(is_liq)
+        self.assertEqual(rate, 0.01)
+
+    def test_liquidation_state(self):
+        # 权益 40, 持仓 10000 -> 保证金率 0.4% < 0.5% -> 爆仓
+        is_liq, rate = self.checker.check_margin_rate(40, 10000)
+        self.assertTrue(is_liq)
+        self.assertEqual(rate, 0.004)
+
+    def test_zero_position(self):
+        # 无持仓
+        is_liq, rate = self.checker.check_margin_rate(10000, 0)
+        self.assertFalse(is_liq)
+        self.assertEqual(rate, 999.0)
+
+if __name__ == '__main__':
+    unittest.main()

基础库/common_core/tests/test_orderbook_replay.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import unittest
+from Quant_Unified.基础库.common_core.utils.orderbook_replay import OrderBook
+
+class TestOrderBookReplay(unittest.TestCase):
+    def setUp(self):
+        self.ob = OrderBook("BTCUSDT")
+
+    def test_apply_delta_basic(self):
+        # 增加买单
+        self.ob.apply_delta("buy", 6000000, 1000)
+        self.ob.apply_delta("buy", 6000100, 2000)
+        
+        # 增加卖单
+        self.ob.apply_delta("sell", 6000200, 1500)
+        self.ob.apply_delta("sell", 6000300, 2500)
+        
+        snap = self.ob.get_snapshot(depth=5)
+        
+        # 验证排序: Bids 应该降序
+        self.assertEqual(snap['bids'][0][0], 6000100)
+        self.assertEqual(snap['bids'][1][0], 6000000)
+        
+        # 验证排序: Asks 应该升序
+        self.assertEqual(snap['asks'][0][0], 6000200)
+        self.assertEqual(snap['asks'][1][0], 6000300)
+
+    def test_update_and_delete(self):
+        self.ob.apply_delta("buy", 6000000, 1000)
+        # 更新
+        self.ob.apply_delta("buy", 6000000, 5000)
+        self.assertEqual(self.ob.bids[6000000], 5000)
+        
+        # 删除
+        self.ob.apply_delta("buy", 6000000, 0)
+        self.assertNotIn(6000000, self.ob.bids)
+
+    def test_flat_snapshot(self):
+        self.ob.apply_delta("bid", 100, 10)
+        self.ob.apply_delta("ask", 110, 20)
+        
+        flat = self.ob.get_flat_snapshot(depth=2)
+        self.assertEqual(flat['bid1_p'], 100)
+        self.assertEqual(flat['bid1_q'], 10)
+        self.assertEqual(flat['ask1_p'], 110)
+        self.assertEqual(flat['ask1_q'], 20)
+        # 深度不够的应该补 0
+        self.assertEqual(flat['bid2_p'], 0)
+
+if __name__ == '__main__':
+    unittest.main()

基础库/common_core/utils/__init__.py

@@ -0,0 +1,2 @@
+"""
+"""

基础库/common_core/utils/async_commons.py

@@ -0,0 +1,30 @@
+"""
+Quant Unified 量化交易系统
+[异步工具函数库]
+功能：提供 async/await 语境下的辅助工具，重点包含异步重试装饰器，确保高并发任务的健壮性。
+"""
+import asyncio
+import traceback
+from functools import wraps
+
+async def async_retry_wrapper(func, params={}, func_name='', if_exit=True):
+    """
+    Async retry wrapper
+    """
+    max_retries = 3
+    for i in range(max_retries):
+        try:
+            if params:
+                return await func(params)
+            else:
+                return await func()
+        except Exception as e:
+            print(f'❌{func_name} 出错: {e}')
+            if i < max_retries - 1:
+                print(f'⏳正在重试 ({i+1}/{max_retries})...')
+                await asyncio.sleep(1)
+            else:
+                print(traceback.format_exc())
+                if if_exit:
+                    raise e
+    return None

基础库/common_core/utils/commons.py

@@ -0,0 +1,181 @@
+"""
+Quant Unified 量化交易系统
+[通用工具函数库]
+功能：包含重试装饰器、时间计算、精度处理等常用辅助功能，是系统稳定运行的基础组件。
+"""
+
+import time
+import traceback
+from datetime import datetime, timedelta
+
+import pandas as pd
+
+
+# ===重试机制
+def retry_wrapper(func, params=None, func_name='', retry_times=5, sleep_seconds=5, if_exit=True):
+    """
+    需要在出错时不断重试的函数，例如和交易所交互，可以使用本函数调用。
+    :param func:            需要重试的函数名
+    :param params:          参数
+    :param func_name:       方法名称
+    :param retry_times:     重试次数
+    :param sleep_seconds:   报错后的sleep时间
+    :param if_exit:         报错是否退出程序
+    :return:
+    """
+    if params is None:
+        params = {}
+    for _ in range(retry_times):
+        try:
+            if 'timestamp' in params:
+                from core.binance.base_client import BinanceClient
+                params['timestamp'] = int(time.time() * 1000) - BinanceClient.diff_timestamp
+            result = func(params=params)
+            return result
+        except Exception as e:
+            print(f'❌{func_name} 报错，程序暂停{sleep_seconds}(秒)')
+            print(e)
+            print(params)
+            msg = str(e).strip()
+            # 出现1021错误码之后，刷新与交易所的时差
+            if 'binance Account has insufficient balance for requested action' in msg:
+                print(f'⚠️{func_name} 现货下单资金不足')
+                raise ValueError(func_name, '现货下单资金不足')
+            elif '-2022' in msg:
+                print(f'⚠️{func_name} ReduceOnly订单被拒绝, 合约仓位已经平完')
+                raise ValueError(func_name, 'ReduceOnly订单被拒绝, 合约仓位已经平完')
+            elif '-4118' in msg:
+                print(f'⚠️{func_name} 统一账户 ReduceOnly订单被拒绝, 合约仓位已经平完')
+                raise ValueError(func_name, '统一账户 ReduceOnly订单被拒绝, 合约仓位已经平完')
+            elif '-2019' in msg:
+                print(f'⚠️{func_name} 合约下单资金不足')
+                raise ValueError(func_name, '合约下单资金不足')
+            elif '-2015' in msg and 'Invalid API-key' in msg:
+                # {"code":-2015,"msg":"Invalid API-key, IP, or permissions for action, request ip: xxx.xxx.xxx.xxx"}
+                print(f'❌{func_name} API配置错误，可能写错或未配置权限')
+                break
+            elif '-1121' in msg and 'Invalid symbol' in msg:
+                # {"code":-2015,"msg":"Invalid API-key, IP, or permissions for action, request ip: xxx.xxx.xxx.xxx"}
+                print(f'❌{func_name} 没有交易对')
+                break
+            elif '-5013' in msg and 'Asset transfer failed' in msg:
+                print(f'❌{func_name} 余额不足，无法资金划转')
+                break
+            else:
+                print(f'❌{e}，报错内容如下')
+                print(traceback.format_exc())
+            time.sleep(sleep_seconds)
+    else:
+        if if_exit:
+            raise ValueError(func_name, '报错重试次数超过上限，程序退出。')
+
+
+# ===下次运行时间
+def next_run_time(time_interval, ahead_seconds=5):
+    """
+    根据time_interval，计算下次运行的时间。
+    PS：目前只支持分钟和小时。
+    :param time_interval: 运行的周期，15m，1h
+    :param ahead_seconds: 预留的目标时间和当前时间之间计算的间隙
+    :return: 下次运行的时间
+
+    案例：
+    15m  当前时间为：12:50:51  返回时间为：13:00:00
+    15m  当前时间为：12:39:51  返回时间为：12:45:00
+
+    10m  当前时间为：12:38:51  返回时间为：12:40:00
+    10m  当前时间为：12:11:01  返回时间为：12:20:00
+
+    5m  当前时间为：12:33:51  返回时间为：12:35:00
+    5m  当前时间为：12:34:51  返回时间为：12:40:00
+
+    30m  当前时间为：21日的23:33:51  返回时间为：22日的00:00:00
+    30m  当前时间为：14:37:51  返回时间为：14:56:00
+
+    1h  当前时间为：14:37:51  返回时间为：15:00:00
+    """
+    # 检测 time_interval 是否配置正确，并将 时间单位 转换成 可以解析的时间单位
+    if time_interval.endswith('m') or time_interval.endswith('h'):
+        pass
+    elif time_interval.endswith('T'):  # 分钟兼容使用T配置，例如  15T 30T
+        time_interval = time_interval.replace('T', 'm')
+    elif time_interval.endswith('H'):  # 小时兼容使用H配置， 例如  1H  2H
+        time_interval = time_interval.replace('H', 'h')
+    else:
+        print('⚠️time_interval格式不符合规范。程序exit')
+        exit()
+
+    # 将 time_interval 转换成 时间类型
+    ti = pd.to_timedelta(time_interval)
+    # 获取当前时间
+    now_time = datetime.now()
+    # 计算��日时间的 00：00：00
+    this_midnight = now_time.replace(hour=0, minute=0, second=0, microsecond=0)
+    # 每次计算时间最小时间单位1分钟
+    min_step = timedelta(minutes=1)
+    # 目标时间：设置成默认时间，并将 秒，毫秒 置零
+    target_time = now_time.replace(second=0, microsecond=0)
+
+    while True:
+        # 增加一个最小时间单位
+        target_time = target_time + min_step
+        # 获取目标时间已经从当日 00:00:00 走了多少时间
+        delta = target_time - this_midnight
+        # delta 时间可以整除 time_interval，表明时间是 time_interval 的倍数，是一个 整时整分的时间
+        # 目标时间 与 当前时间的 间隙超过 ahead_seconds，说明 目标时间 比当前时间大，是最靠近的一个周期时间
+        if int(delta.total_seconds()) % int(ti.total_seconds()) == 0 and int(
+                (target_time - now_time).total_seconds()) >= ahead_seconds:
+            break
+
+    return target_time
+
+
+# ===依据时间间隔, 自动计算并休眠到指定时间
+def sleep_until_run_time(time_interval, ahead_time=1, if_sleep=True, cheat_seconds=0):
+    """
+    根据next_run_time()函数计算出下次程序运行的时候，然后sleep至该时间
+    :param time_interval: 时间周期配置，用于计算下个周期的时间
+    :param if_sleep: 是否进行sleep
+    :param ahead_time: 最小时间误差
+    :param cheat_seconds: 相对于下个周期时间，提前或延后多长时间， 100： 提前100秒； -50：延后50秒
+    :return:
+    """
+    # 计算下次运行时间
+    run_time = next_run_time(time_interval, ahead_time)
+    # 计算延迟之后的目标时间
+    target_time = run_time
+    # 配置 cheat_seconds ，对目标时间进行 提前 或者 延后
+    if cheat_seconds != 0:
+        target_time = run_time - timedelta(seconds=cheat_seconds)
+    print(f'⏳程序等待下次运行，下次时间：{target_time}')
+
+    # sleep
+    if if_sleep:
+        # 计算获得的 run_time 小于 now, sleep就会一直sleep
+        _now = datetime.now()
+        if target_time > _now:  # 计算的下个周期时间超过当前时间，直接追加一个时间周期
+            time.sleep(max(0, (target_time - _now).seconds))
+        while True:  # 在靠近目标时间时
+            if datetime.now() > target_time:
+                time.sleep(1)
+                break
+
+    return run_time
+
+
+# ===根据精度对数字进行就低不就高处理
+def apply_precision(number: int | float, decimals: int) -> float:
+    """
+    根据精度对数字进行就低不就高处理
+    :param number:      数字
+    :param decimals:    精度
+    :return:
+        (360.731, 0)结果是360，
+        (123.65, 1)结果是123.6
+    """
+    multiplier = 10 ** decimals
+    return int(number * multiplier) / multiplier
+
+
+def bool_str(true_or_false):
+    return '🔵[OK]' if true_or_false else '🟡[NO]'

基础库/common_core/utils/dingding.py

@@ -0,0 +1,107 @@
+"""
+Quant Unified 量化交易系统
+[消息推送工具]
+功能：集成钉钉/企业微信 Webhook，用于发送实盘交易信号、报错报警和状态监控，让您随时掌握系统动态。
+"""
+
+import base64
+import hashlib
+import os.path
+import requests
+import json
+import traceback
+from datetime import datetime
+from config import proxy
+
+
+# 企业微信通知
+def send_wechat_work_msg(content, url):
+    if not url:
+        print('未配置wechat_webhook_url，不发送信息')
+        return
+    try:
+        data = {
+            "msgtype": "text",
+            "text": {
+                "content": content + '\n' + datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            }
+        }
+        r = requests.post(url, data=json.dumps(data), timeout=10, proxies=proxy)
+        print(f'调用企业微信接口返回： {r.text}')
+        print('成功发送企业微信')
+    except Exception as e:
+        print(f"发送企业微信失败:{e}")
+        print(traceback.format_exc())
+
+
+# 上传图片，解析bytes
+class MyEncoder(json.JSONEncoder):
+
+    def default(self, obj):
+        """
+        只要检查到了是bytes类型的数据就把它转为str类型
+        :param obj:
+        :return:
+        """
+        if isinstance(obj, bytes):
+            return str(obj, encoding='utf-8')
+        return json.JSONEncoder.default(self, obj)
+
+
+# 企业微信发送图片
+def send_wechat_work_img(file_path, url):
+    if not os.path.exists(file_path):
+        print('找不到图片')
+        return
+    if not url:
+        print('未配置wechat_webhook_url，不发送信息')
+        return
+    try:
+        with open(file_path, 'rb') as f:
+            image_content = f.read()
+        image_base64 = base64.b64encode(image_content).decode('utf-8')
+        md5 = hashlib.md5()
+        md5.update(image_content)
+        image_md5 = md5.hexdigest()
+        data = {
+            'msgtype': 'image',
+            'image': {
+                'base64': image_base64,
+                'md5': image_md5
+            }
+        }
+        # 服务器上传bytes图片的时候，json.dumps解析会出错，需要自己手动去转一下
+        r = requests.post(url, data=json.dumps(data, cls=MyEncoder, indent=4), timeout=10, proxies=proxy)
+        print(f'调用企业微信接口返回： {r.text}')
+        print('成功发送企业微信')
+    except Exception as e:
+        print(f"发送企业微信失败:{e}")
+        print(traceback.format_exc())
+    finally:
+        if os.path.exists(file_path):
+            os.remove(file_path)
+
+
+def send_msg_for_order(order_param, order_res, url):
+    """
+    发送下单信息，只有出问题才会推送，正常下单不在推送信息
+    """
+    if not url:
+        print('未配置wechat_webhook_url，不发送信息')
+        return
+    msg = ''
+    try:
+        for _ in range(len(order_param)):
+            if 'msg' in order_res[_].keys():
+                msg += f'币种:{order_param[_]["symbol"]}\n'
+                msg += f'方向:{"做多" if order_param[_]["side"] == "BUY" else "做空"}\n'
+                msg += f'价格:{order_param[_]["price"]}\n'
+                msg += f'数量:{order_param[_]["quantity"]}\n'
+                msg += f'下单结果:{order_res[_]["msg"]}'
+                msg += '\n' * 2
+    except BaseException as e:
+        print('send_msg_for_order ERROR', e)
+        print(traceback.format_exc())
+
+    if msg:
+        send_wechat_work_msg(msg, url)

基础库/common_core/utils/factor_hub.py

@@ -0,0 +1,58 @@
+"""
+选币框架
+"""
+import importlib
+
+import pandas as pd
+
+
+class DummyFactor:
+    """
+    ！！！！抽象因子对象，仅用于代码提示！！！！
+    """
+
+    def signal(self, *args) -> pd.DataFrame:
+        raise NotImplementedError
+
+    def signal_multi_params(self, df, param_list: list | set | tuple) -> dict:
+        raise NotImplementedError
+
+
+class FactorHub:
+    _factor_cache = {}
+
+    # noinspection PyTypeChecker
+    @staticmethod
+    def get_by_name(factor_name) -> DummyFactor:
+        if factor_name in FactorHub._factor_cache:
+            return FactorHub._factor_cache[factor_name]
+
+        try:
+            # 构造模块名
+            module_name = f"factors.{factor_name}"
+
+            # 动态导入模块
+            factor_module = importlib.import_module(module_name)
+
+            # 创建一个包含模块变量和函数的字典
+            factor_content = {
+                name: getattr(factor_module, name) for name in dir(factor_module)
+                if not name.startswith("__")
+            }
+
+            # 创建一个包含这些变量和函数的对象
+            factor_instance = type(factor_name, (), factor_content)
+
+            # 缓存策略对象
+            FactorHub._factor_cache[factor_name] = factor_instance
+
+            return factor_instance
+        except ModuleNotFoundError:
+            raise ValueError(f"Factor {factor_name} not found.")
+        except AttributeError:
+            raise ValueError(f"Error accessing factor content in module {factor_name}.")
+
+
+# 使用示例
+if __name__ == "__main__":
+    factor = FactorHub.get_by_name("PctChange")

基础库/common_core/utils/functions.py

@@ -0,0 +1,71 @@
+"""
+选币框架
+"""
+import warnings
+from pathlib import Path
+from typing import Dict
+
+import numpy as np
+import pandas as pd
+
+from config import stable_symbol
+
+warnings.filterwarnings('ignore')
+
+
+# =====策略相关函数
+def del_insufficient_data(symbol_candle_data) -> Dict[str, pd.DataFrame]:
+    """
+    删除数据长度不足的币种信息
+
+    :param symbol_candle_data:
+    :return
+    """
+    # ===删除成交量为0的线数据、k线数不足的币种
+    symbol_list = list(symbol_candle_data.keys())
+    for symbol in symbol_list:
+        # 删除空的数据
+        if symbol_candle_data[symbol] is None or symbol_candle_data[symbol].empty:
+            del symbol_candle_data[symbol]
+            continue
+        # 删除该币种成交量=0的k线
+        # symbol_candle_data[symbol] = symbol_candle_data[symbol][symbol_candle_data[symbol]['volume'] > 0]
+
+    return symbol_candle_data
+
+
+def ignore_error(anything):
+    return anything
+
+
+def load_min_qty(file_path: Path) -> (int, Dict[str, int]):
+    # 读取min_qty文件并转为dict格式
+    min_qty_df = pd.read_csv(file_path, encoding='utf-8-sig')
+    min_qty_df['最小下单量'] = -np.log10(min_qty_df['最小下单量']).round().astype(int)
+    default_min_qty = min_qty_df['最小下单量'].max()
+    min_qty_df.set_index('币种', inplace=True)
+    min_qty_dict = min_qty_df['最小下单量'].to_dict()
+
+    return default_min_qty, min_qty_dict
+
+
+def is_trade_symbol(symbol, black_list=()) -> bool:
+    """
+    过滤掉不能用于交易的币种，比如稳定币、非USDT交易对，以及一些杠杆币
+    :param symbol: 交易对
+    :param black_list: 黑名单
+    :return: 是否可以进入交易，True可以参与选币，False不参与
+    """
+    # 如果symbol为空
+    # 或者是.开头的隐藏文件
+    # 或者不是USDT结尾的币种
+    # 或者在黑名单里
+    if not symbol or symbol.startswith('.') or not symbol.endswith('USDT') or symbol in black_list:
+        return False
+
+    # 筛选杠杆币
+    base_symbol = symbol.upper().replace('-USDT', 'USDT')[:-4]
+    if base_symbol.endswith(('UP', 'DOWN', 'BEAR', 'BULL')) and base_symbol != 'JUP' or base_symbol in stable_symbol:
+        return False
+    else:
+        return True

基础库/common_core/utils/orderbook_replay.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+L2 订单簿重放引擎
+功能：根据增量更新（Delta）维护内存中的盘口状态，并支持快照提取。
+支持价格和数量的整数存储以提高性能。
+"""
+
+from sortedcontainers import SortedDict
+import logging
+
+logger = logging.getLogger(__name__)
+
+class OrderBook:
+    def __init__(self, symbol: str):
+        self.symbol = symbol
+        # bids 降序排列 (最高价在最前)
+        self.bids = SortedDict(lambda x: -x)
+        # asks 升序排列 (最低价在最前)
+        self.asks = SortedDict()
+        self.last_update_id = 0
+        self.timestamp = None
+
+    def apply_delta(self, side: str, price_int: int, amount_int: int):
+        """
+        应用单条增量更新
+        :param side: 'buy' 或 'sell' (Tardis 格式) 或 'bid'/'ask'
+        :param price_int: 整数价格
+        :param amount_int: 整数数量 (为 0 表示删除该档位)
+        """
+        target_dict = self.bids if side in ['buy', 'bid'] else self.asks
+        
+        if amount_int <= 0:
+            target_dict.pop(price_int, None)
+        else:
+            target_dict[price_int] = amount_int
+
+    def reset(self):
+        """重置盘口"""
+        self.bids.clear()
+        self.asks.clear()
+
+    def get_snapshot(self, depth: int = 50) -> dict:
+        """
+        获取当前盘口的快照
+        :param depth: 档位深度
+        :return: 包含 bids 和 asks 列表的字典
+        """
+        bid_keys = list(self.bids.keys())[:depth]
+        bid_list = [(p, self.bids[p]) for p in bid_keys]
+            
+        ask_keys = list(self.asks.keys())[:depth]
+        ask_list = [(p, self.asks[p]) for p in ask_keys]
+            
+        return {
+            "symbol": self.symbol,
+            "bids": bid_list,
+            "asks": ask_list
+        }
+
+    def get_flat_snapshot(self, depth: int = 50) -> dict:
+        """
+        获取打平的快照格式，方便直接喂给模型 (例如 bid1_p, bid1_q ...)
+        """
+        result = {}
+        
+        bid_keys = list(self.bids.keys())
+        # 处理 Bids
+        for i in range(depth):
+            if i < len(bid_keys):
+                price = bid_keys[i]
+                amount = self.bids[price]
+                result[f"bid{i+1}_p"] = price
+                result[f"bid{i+1}_q"] = amount
+            else:
+                result[f"bid{i+1}_p"] = 0
+                result[f"bid{i+1}_q"] = 0
+                
+        ask_keys = list(self.asks.keys())
+        # 处理 Asks
+        for i in range(depth):
+            if i < len(ask_keys):
+                price = ask_keys[i]
+                amount = self.asks[price]
+                result[f"ask{i+1}_p"] = price
+                result[f"ask{i+1}_q"] = amount
+            else:
+                result[f"ask{i+1}_p"] = 0
+                result[f"ask{i+1}_q"] = 0
+                
+        return result

基础库/common_core/utils/path_kit.py

@@ -0,0 +1,72 @@
+"""
+Quant Unified 量化交易系统
+[路径管理工具]
+功能：自动识别操作系统，统一管理数据、配置、日志等文件夹路径，解决硬编码路径带来的跨平台问题。
+"""
+
+import os
+from pathlib import Path
+
+# 通过当前文件的位置，获取项目根目录
+PROJECT_ROOT = os.path.abspath(os.path.join(__file__, os.path.pardir, os.path.pardir, os.path.pardir, os.path.pardir))
+
+
+# ====================================================================================================
+# ** 功能函数 **
+# - get_folder_by_root: 获取基于某一个地址的绝对路径
+# - get_folder_path: 获取相对于项目根目录的，文件夹的绝对路径
+# - get_file_path: 获取相对于项目根目录的，文件的绝对路径
+# ====================================================================================================
+def get_folder_by_root(root, *paths, auto_create=True) -> str:
+    """
+    获取基于某一个地址的绝对路径
+    :param root: 相对的地址，默认为运行脚本同目录
+    :param paths: 路径
+    :param auto_create: 是否自动创建需要的文件夹们
+    :return: 绝对路径
+    """
+    _full_path = os.path.join(root, *paths)
+    if auto_create and (not os.path.exists(_full_path)):  # 判断文件夹是否存在
+        try:
+            os.makedirs(_full_path)  # 不存在则创建
+        except FileExistsError:
+            pass  # 并行过程中，可能造成冲突
+    return str(_full_path)
+
+
+def get_folder_path(*paths, auto_create=True, as_path_type=False) -> str | Path:
+    """
+    获取相对于项目根目录的，文件夹的绝对路径
+    :param paths: 文件夹路径
+    :param auto_create: 是否自动创建
+    :param as_path_type: 是否返回Path对象
+    :return: 文件夹绝对路径
+    """
+    _p = get_folder_by_root(PROJECT_ROOT, *paths, auto_create=auto_create)
+    if as_path_type:
+        return Path(_p)
+    return _p
+
+
+def get_file_path(*paths, auto_create=True, as_path_type=False) -> str | Path:
+    """
+    获取相对于项目根目录的，文件的绝对路径
+    :param paths: 文件路径
+    :param auto_create: 是否自动创建
+    :param as_path_type: 是否返回Path对象
+    :return: 文件绝对路径
+    """
+    parent = get_folder_path(*paths[:-1], auto_create=auto_create, as_path_type=True)
+    _p = parent / paths[-1]
+    if as_path_type:
+        return _p
+    return str(_p)
+
+
+if __name__ == '__main__':
+    """
+    DEMO
+    """
+    print(get_file_path('data', 'xxx.pkl'))
+    print(get_folder_path('系统日志'))
+    print(get_folder_by_root('data', 'center', 'yyds', auto_create=False))

基础库/通用选币回测框架/因子库/9_SharpeMomentum.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""
+多头动量因子9 | 夏普动量因子
+author: D Luck
+"""
+
+import pandas as pd
+import numpy as np
+
+def signal(*args):
+    df, n, factor_name = args
+
+    ret = df['close'].pct_change()
+    mean_ = ret.rolling(n, min_periods=1).mean()
+    std_ = ret.rolling(n, min_periods=1).std()
+
+    df[factor_name] = mean_ / (std_ + 1e-12)
+    return df
+
+
+def signal_multi_params(df, param_list) -> dict:
+    ret_dic = {}
+    ret = df['close'].pct_change()
+
+    for param in param_list:
+        n = int(param)
+
+        mean_ = ret.rolling(n).mean()
+        std_ = ret.rolling(n).std()
+
+        ret_dic[str(param)] = mean_ / (std_ + 1e-12)
+
+    return ret_dic

基础库/通用选币回测框架/因子库/ADX.py

@@ -0,0 +1,49 @@
+import numpy as np
+import pandas as pd
+
+
+def signal(*args):
+    df = args[0].copy()  # 避免修改原数据
+    N = args[1]
+    factor_name = args[2]
+
+    # 1. 计算 True Range (TR)
+    prev_close = df['close'].shift(1)
+    tr1 = df['high'] - df['low']
+    tr2 = (df['high'] - prev_close).abs()
+    tr3 = (df['low'] - prev_close).abs()
+    df['tr'] = pd.concat([tr1, tr2, tr3], axis=1).max(axis=1)
+
+    # 2. 计算 +DM 和 -DM
+    up_move = df['high'].diff()
+    down_move = (-df['low'].diff())
+
+    df['plus_dm'] = up_move.where((up_move > down_move) & (up_move > 0), 0)
+    df['minus_dm'] = down_move.where((down_move > up_move) & (down_move > 0), 0)
+
+    # 3. Wilders 平滑函数（关键！）
+    def wilders_smooth(series, n):
+        return series.ewm(alpha=1 / n, adjust=False).mean()
+
+    df['tr_smooth'] = wilders_smooth(df['tr'], N)
+    df['plus_dm_smooth'] = wilders_smooth(df['plus_dm'], N)
+    df['minus_dm_smooth'] = wilders_smooth(df['minus_dm'], N)
+
+    # 4. 计算 +DI 和 -DI
+    df['plus_di'] = (df['plus_dm_smooth'] / df['tr_smooth']) * 100
+    df['minus_di'] = (df['minus_dm_smooth'] / df['tr_smooth']) * 100
+
+    # 5. 计算 DX
+    di_sum = df['plus_di'] + df['minus_di']
+    di_diff = (df['plus_di'] - df['minus_di']).abs()
+
+    # 防止除零
+    df['dx'] = np.where(di_sum > 0, (di_diff / di_sum) * 100, 0)
+
+    # 6. ADX = DX 的 Wilders 平滑
+    df['adx'] = wilders_smooth(df['dx'], N)
+
+    # 7. 输出到指定列名
+    df[factor_name] = df['adx']
+
+    return df

基础库/通用选币回测框架/因子库/AO.py

@@ -0,0 +1,53 @@
+"""
+AO 因子（Awesome Oscillator，动量震荡）— 量纲归一版本
+
+定义
+- 使用中位价 `mid=(high+low)/2` 的短/长均线差作为动量源
+- 先对均线差做比例归一：`(SMA_s - SMA_l) / SMA_l`
+- 再对结果以 `ATR(l)` 做风险归一，得到跨币种可比的无量纲指标
+
+用途
+- 作为前置过滤（方向确认）：AO > 0 表示短期动量强于长期动量
+- 也可作为选币因子，但推荐保留主因子（如 VWapBias）主导排名
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def _parse_param(param):
+    """解析参数，支持 (s,l)、"s,l" 两种写法；默认 (5,34)"""
+    if isinstance(param, (tuple, list)) and len(param) >= 2:
+        return int(param[0]), int(param[1])
+    if isinstance(param, str) and "," in param:
+        a, b = param.split(",")
+        return int(a), int(b)
+    return 5, 34
+
+
+def _atr(df, n):
+    """计算 ATR(n)：真实波动范围的均值，用于风险归一"""
+    prev_close = df["close"].shift(1).fillna(df["open"])  # 前收盘价（首根用开盘补齐）
+    # 真实波动 TR = max(高-低, |高-前收|, |低-前收|)
+    tr = np.maximum(
+        df["high"] - df["low"],
+        np.maximum(np.abs(df["high"] - prev_close), np.abs(df["low"] - prev_close)),
+    )
+    return pd.Series(tr).rolling(n, min_periods=1).mean()  # 滚动均值作为 ATR
+
+
+def signal(*args):
+    """计算单参数 AO 因子并写入列名 `factor_name`"""
+    df = args[0]  # K线数据
+    param = args[1]  # 参数（支持 "s,l"）
+    factor_name = args[2]  # 因子列名
+    s, l = _parse_param(param)  # 解析短/长窗口
+    eps = 1e-12  # 防除零微量
+    mid = (df["high"] + df["low"]) / 2.0  # 中位价
+    sma_s = mid.rolling(s, min_periods=1).mean()  # 短均线
+    sma_l = mid.rolling(l, min_periods=1).mean()  # 长均线
+    atr_l = _atr(df, l)  # 长窗 ATR
+    # 比例/ATR 归一：跨币种可比、抗量纲
+    ao = ((sma_s - sma_l) / (sma_l + eps)) / (atr_l + eps)
+    df[factor_name] = ao.replace([np.inf, -np.inf], 0).fillna(0)  # 安全处理
+    return df

基础库/通用选币回测框架/因子库/ATR.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""
+ATR 波动率因子（时间序列）
+基于真实波幅的均值衡量价格波动率
+author: 邢不行框架适配
+"""
+def signal(*args):
+    df = args[0]
+    n = args[1]            # ATR计算窗口
+    factor_name = args[2]
+
+    # 1) 计算 True Range (TR)
+    df['pre_close'] = df['close'].shift(1)  # 前一周期收盘价
+    df['tr1'] = df['high'] - df['low']
+    df['tr2'] = (df['high'] - df['pre_close']).abs()
+    df['tr3'] = (df['low'] - df['pre_close']).abs()
+    df['TR'] = df[['tr1', 'tr2', 'tr3']].max(axis=1)  # 三者取最大:contentReference[oaicite:1]{index=1}
+
+    # 2) 计算 ATR：TR 的 n 期滚动均值作为波动率指标
+    df[factor_name] = df['TR'].rolling(window=n, min_periods=1).mean()
+
+    # 3) 清理临时字段
+    del df['pre_close'], df['tr1'], df['tr2'], df['tr3'], df['TR']
+
+    return df

基础库/通用选币回测框架/因子库/ActiveBuyRatio.py

@@ -0,0 +1,23 @@
+
+def signal(*args):
+    df = args[0]
+    n = args[1]
+    factor_name = args[2]
+
+    # 计算主动买入占比因子
+    # taker_buy_base_asset_volume: 主动买入的基础资产数量
+    # volume: 总交易量（基础资产）
+    # 主动买入占比 = 主动买入量 / 总交易量
+    df['active_buy_ratio'] = df['taker_buy_base_asset_volume'] / (df['volume'] + 1e-9)
+
+    # 对占比进行滚动窗口处理（可选）
+    # 计算n周期内的平均主动买入占比
+    df[factor_name] = df['active_buy_ratio'].rolling(
+        window=n,
+        min_periods=1
+    ).mean()
+
+    # 清理临时列
+    df.drop('active_buy_ratio', axis=1, inplace=True, errors='ignore')
+
+    return df

基础库/通用选币回测框架/因子库/AdxMinus.py

@@ -0,0 +1,122 @@
+"""邢不行™️选币框架
+Python数字货币量化投资课程
+
+版权所有 ©️ 邢不行
+微信: xbx8662
+
+未经授权，不得复制、修改、或使用本代码的全部或部分内容。仅限个人学习用途，禁止商业用途。
+
+Author: 邢不行
+--------------------------------------------------------------------------------
+
+# ** 因子文件功能说明 **
+1. 因子库中的每个 Python 文件需实现 `signal` 函数，用于计算因子值。
+2. 除 `signal` 外，可根据需求添加辅助函数，不影响因子计算逻辑。
+
+# ** signal 函数参数与返回值说明 **
+1. `signal` 函数的第一个参数为 `candle_df`，用于接收单个币种的 K 线数据。
+2. `signal` 函数的第二个参数用于因子计算的主要参数，具体用法见函数实现。
+3. `signal` 函数可以接收其他可选参数，按实际因子计算逻辑使用。
+4. `signal` 函数的返回值应为包含因子数据的 K 线数据。
+
+# ** candle_df 示例 **
+    candle_begin_time         symbol      open      high       low     close       volume  quote_volume  trade_num  taker_buy_base_asset_volume  taker_buy_quote_asset_volume  funding_fee   first_candle_time  是否交易
+0          2023-11-22  1000BONK-USDT  0.004780  0.004825  0.004076  0.004531  12700997933  5.636783e+07     320715                   6184933232                  2.746734e+07     0.001012 2023-11-22 14:00:00         1
+1          2023-11-23  1000BONK-USDT  0.004531  0.004858  0.003930  0.004267  18971334686  8.158966e+07     573386                   8898242083                  3.831782e+07     0.001634 2023-11-22 14:00:00         1
+2          2023-11-24  1000BONK-USDT  0.004267  0.004335  0.003835  0.004140  17168511399  6.992947e+07     475254                   7940993618                  3.239266e+07     0.005917 2023-11-22 14:00:00         1
+
+# ** signal 参数示例 **
+- 如果策略配置中 `factor_list` 包含 ('AdxMinus', True, 14, 1)，则 `param` 为 14，`args[0]` 为 'AdxMinus_14'。
+- 如果策略配置中 `filter_list` 包含 ('AdxMinus', 14, 'pct:<0.8')，则 `param` 为 14，`args[0]` 为 'AdxMinus_14'。
+"""
+
+
+"""ADX- (DI-) 下跌趋势强度指标，用于衡量下跌动能的强度"""
+import pandas as pd
+import numpy as np
+
+
+def signal(candle_df, param, *args):
+    """
+    计算ADX- (DI-) 下跌趋势强度指标
+    DI-反映价格下跌动能的强度，数值越高表示下跌趋势越强
+    
+    计算原理：
+    1. 计算真实波幅TR
+    2. 计算下跌方向移动DM-
+    3. 对TR和DM-进行平滑处理
+    4. DI- = (平滑DM- / 平滑TR) * 100
+    
+    :param candle_df: 单个币种的K线数据
+    :param param: 计算周期参数，通常为14
+    :param args: 其他可选参数，args[0]为因子名称
+    :return: 包含因子数据的 K 线数据
+    """
+    factor_name = args[0]  # 从额外参数中获取因子名称
+    n = param  # 计算周期
+    
+    # 步骤1: 计算真实波幅TR (True Range)
+    # TR衡量价格的真实波动幅度，考虑跳空因素
+    tr1 = candle_df['high'] - candle_df['low']  # 当日最高价-最低价
+    tr2 = abs(candle_df['high'] - candle_df['close'].shift(1))  # 当日最高价-前日收盘价的绝对值
+    tr3 = abs(candle_df['low'] - candle_df['close'].shift(1))   # 当日最低价-前日收盘价的绝对值
+    tr = pd.concat([tr1, tr2, tr3], axis=1).max(axis=1)
+    
+    # 步骤2: 计算下跌方向移动DM- (Directional Movement Minus)
+    # DM-衡量价格向下突破的动能
+    high_diff = candle_df['high'] - candle_df['high'].shift(1)  # 最高价变化
+    low_diff = candle_df['low'].shift(1) - candle_df['low']     # 最低价变化（前日-当日，正值表示下跌）
+    
+    # 只有当下跌幅度大于上涨幅度且确实下跌时，才记录为负向动能
+    dm_minus = np.where((low_diff > high_diff) & (low_diff > 0), low_diff, 0)
+    
+    # 步骤3: 使用Wilder's平滑方法计算平滑TR和DM-
+    # Wilder's平滑：类似指数移动平均，但平滑系数为1/n
+    tr_smooth = tr.ewm(alpha=1/n, adjust=False).mean()
+    dm_minus_smooth = pd.Series(dm_minus).ewm(alpha=1/n, adjust=False).mean()
+    
+    # 步骤4: 计算DI- (Directional Indicator Minus)
+    # DI-表示下跌趋势的相对强度，范围0-100
+    di_minus = (dm_minus_smooth / tr_smooth) * 100
+    
+    # 将计算结果赋值给因子列
+    candle_df[factor_name] = di_minus
+    
+    return candle_df
+
+
+# 使用说明：
+# 1. DI-数值含义：
+#    - DI- > 25: 下跌趋势较强
+#    - DI- > 40: 强下跌趋势
+#    - DI- < 20: 下跌动能较弱
+#
+# 2. 交易信号参考：
+#    - DI-持续上升：下跌趋势加强，可考虑做空或避险
+#    - DI-开始下降：下跌动能减弱，可能见底反弹
+#    - DI-与DI+交叉：趋势可能转换
+#
+# 3. 风险管理应用：
+#    - DI-快速上升：及时止损，避免深度套牢
+#    - DI-高位钝化：下跌动能衰竭，关注反弹机会
+#    - DI-与价格背离：可能出现趋���反转信号
+#
+# 4. 最佳实践：
+#    - 结合ADX使用：ADX>25时DI-信号更可靠
+#    - 结合成交量：放量下跌时DI-信号更强
+#    - 关注支撑位：在重要支撑位DI-减弱可能是买入机会
+#
+# 5. 在config.py中的配置示例：
+#    factor_list = [
+#        ('AdxMinus', True, 14, 1),   # 14周期DI-
+#        ('AdxMinus', True, 21, 1),   # 21周期DI-（更平滑）
+#    ]
+#    
+#    filter_list = [
+#        ('AdxMinus', 14, 'pct:<0.3'),  # 过滤掉DI-排名前30%的币种（避开强下跌趋势）
+#    ]
+#
+# 6. 与其他指标组合：
+#    - DI- + RSI: DI-高位+RSI超卖可能是反弹信号
+#    - DI- + 布林带: DI-上升+价格触及下轨可能是超跌
+#    - DI- + MACD: DI-与MACD背离可能预示趋势转换

基础库/通用选币回测框架/因子库/AdxPlus.py

@@ -0,0 +1,112 @@
+"""邢不行™️选币框架
+Python数字货币量化投资课程
+
+版权所有 ©️ 邢不行
+微信: xbx8662
+
+未经授权，不得复制、修改、或使用本代码的全部或部分内容。仅限个人学习用途，禁止商业用途。
+
+Author: 邢不行
+--------------------------------------------------------------------------------
+
+# ** 因子文件功能说明 **
+1. 因子库中的每个 Python 文件需实现 `signal` 函数，用于计算因子值。
+2. 除 `signal` 外，可根据需求添加辅助函数，不影响因子计算逻辑。
+
+# ** signal 函数参数与返回值说明 **
+1. `signal` 函数的第一个参数为 `candle_df`，用于接收单个币种的 K 线数据。
+2. `signal` 函数的第二个参数用于因子计算的主要参数，具体用法见函数实现。
+3. `signal` 函数可以接收其他可选参数，按实际因子计算逻辑使用。
+4. `signal` 函数的返回值应为包含因子数据的 K 线数据。
+
+# ** candle_df 示例 **
+    candle_begin_time         symbol      open      high       low     close       volume  quote_volume  trade_num  taker_buy_base_asset_volume  taker_buy_quote_asset_volume  funding_fee   first_candle_time  是否交易
+0          2023-11-22  1000BONK-USDT  0.004780  0.004825  0.004076  0.004531  12700997933  5.636783e+07     320715                   6184933232                  2.746734e+07     0.001012 2023-11-22 14:00:00         1
+1          2023-11-23  1000BONK-USDT  0.004531  0.004858  0.003930  0.004267  18971334686  8.158966e+07     573386                   8898242083                  3.831782e+07     0.001634 2023-11-22 14:00:00         1
+2          2023-11-24  1000BONK-USDT  0.004267  0.004335  0.003835  0.004140  17168511399  6.992947e+07     475254                   7940993618                  3.239266e+07     0.005917 2023-11-22 14:00:00         1
+
+# ** signal 参数示例 **
+- 如果策略配置中 `factor_list` 包含 ('AdxPlus', True, 14, 1)，则 `param` 为 14，`args[0]` 为 'AdxPlus_14'。
+- 如果策略配置中 `filter_list` 包含 ('AdxPlus', 14, 'pct:<0.8')，则 `param` 为 14，`args[0]` 为 'AdxPlus_14'。
+"""
+
+
+"""ADX+ (DI+) 上涨趋势强度指标，用于衡量上涨动能的强度"""
+import pandas as pd
+import numpy as np
+
+
+def signal(candle_df, param, *args):
+    """
+    计算ADX+ (DI+) 上涨趋势强度指标
+    DI+反映价格上涨动能的强度，数值越高表示上涨趋势越强
+    
+    计算原理：
+    1. 计算真实波幅TR
+    2. 计算上涨方向移动DM+
+    3. 对TR和DM+进行平滑处理
+    4. DI+ = (平滑DM+ / 平滑TR) * 100
+    
+    :param candle_df: 单个币种的K线数据
+    :param param: 计算周期参数，通常为14
+    :param args: 其他可选参数，args[0]为因子名称
+    :return: 包含因子数据的 K 线数据
+    """
+    factor_name = args[0]  # 从额外参数中获取因子名称
+    n = param  # 计算周期
+    
+    # 步骤1: 计算真实波幅TR (True Range)
+    # TR衡量价格的真实波动幅度，考虑跳空因素
+    tr1 = candle_df['high'] - candle_df['low']  # 当日最高价-最低价
+    tr2 = abs(candle_df['high'] - candle_df['close'].shift(1))  # 当日最高价-前日收盘价的绝对值
+    tr3 = abs(candle_df['low'] - candle_df['close'].shift(1))   # 当日最低价-前日收盘价的绝对值
+    tr = pd.concat([tr1, tr2, tr3], axis=1).max(axis=1)
+    
+    # 步骤2: 计算上涨方向移动DM+ (Directional Movement Plus)
+    # DM+衡量价格向上突破的动能
+    high_diff = candle_df['high'] - candle_df['high'].shift(1)  # 最高价变化
+    low_diff = candle_df['low'].shift(1) - candle_df['low']     # 最低价变化（前日-当日）
+    
+    # 只有当上涨幅度大于下跌幅度且确实上涨时，才记录为正向动能
+    dm_plus = np.where((high_diff > low_diff) & (high_diff > 0), high_diff, 0)
+    
+    # 步骤3: 使用Wilder's平滑方法计算平滑TR和DM+
+    # Wilder's平滑：类似指数移动平均，但平滑系数为1/n
+    tr_smooth = tr.ewm(alpha=1/n, adjust=False).mean()
+    dm_plus_smooth = pd.Series(dm_plus).ewm(alpha=1/n, adjust=False).mean()
+    
+    # 步骤4: 计算DI+ (Directional Indicator Plus)
+    # DI+表示上涨趋势的相对强度，范围0-100
+    di_plus = (dm_plus_smooth / tr_smooth) * 100
+    
+    # 将计算结果赋值给因子列
+    candle_df[factor_name] = di_plus
+    
+    return candle_df
+
+
+# 使用说明：
+# 1. DI+数值含义：
+#    - DI+ > 25: 上涨趋势较强
+#    - DI+ > 40: 强上涨趋势
+#    - DI+ < 20: 上涨动能较弱
+#
+# 2. 交易信号参考：
+#    - DI+持续上升：上涨趋势加强，可考虑做多
+#    - DI+开始下降：上涨动能减弱，注意风险
+#    - DI+与DI-交叉：趋势可能转换
+#
+# 3. 最佳实践：
+#    - 结合ADX使用：ADX>25时DI+信号更可靠
+#    - 结合价格形态：在支撑位附近DI+上升信号更强
+#    - 避免震荡市：横盘整理时DI+信号容易失效
+#
+# 4. 在config.py中的配置示���：
+#    factor_list = [
+#        ('AdxPlus', True, 14, 1),    # 14周期DI+
+#        ('AdxPlus', True, 21, 1),    # 21周期DI+（更平滑）
+#    ]
+#    
+#    filter_list = [
+#        ('AdxPlus', 14, 'pct:>0.7'),  # 选择DI+排名前30%的币种
+#    ]

基础库/通用选币回测框架/因子库/AdxVolWaves.py

@@ -0,0 +1,108 @@
+import numpy as np
+import pandas as pd
+from .TMV import calculate_adx
+
+
+def signal(candle_df, param, *args):
+    factor_name = args[0] if args else "AdxVolWaves"
+
+    if isinstance(param, tuple):
+        bb_length = param[0] if len(param) > 0 else 20
+        bb_mult = param[1] if len(param) > 1 else 1.5
+        adx_length = param[2] if len(param) > 2 else 14
+        adx_influence = param[3] if len(param) > 3 else 0.8
+        zone_offset = param[4] if len(param) > 4 else 1.0
+        zone_expansion = param[5] if len(param) > 5 else 1.0
+        smooth_length = param[6] if len(param) > 6 else 50
+        signal_cooldown = param[7] if len(param) > 7 else 20
+    else:
+        bb_length = int(param)
+        bb_mult = 1.5
+        adx_length = 14
+        adx_influence = 0.8
+        zone_offset = 1.0
+        zone_expansion = 1.0
+        smooth_length = 50
+        signal_cooldown = 20
+
+    close = candle_df["close"]
+    high = candle_df["high"]
+    low = candle_df["low"]
+
+    adx_df = calculate_adx(candle_df, adx_length)
+    adx = adx_df["adx"]
+    di_plus = adx_df["di_plus"]
+    di_minus = adx_df["di_minus"]
+    adx_normalized = adx / 100.0
+
+    bb_basis = close.rolling(window=bb_length, min_periods=1).mean()
+    bb_dev = close.rolling(window=bb_length, min_periods=1).std()
+
+    adx_multiplier = 1.0 + adx_normalized * adx_influence
+    bb_dev_adjusted = bb_mult * bb_dev * adx_multiplier
+
+    bb_upper = bb_basis + bb_dev_adjusted
+    bb_lower = bb_basis - bb_dev_adjusted
+
+    bb_basis_safe = bb_basis.replace(0, np.nan)
+    bb_width = (bb_upper - bb_lower) / bb_basis_safe * 100.0
+    bb_width = bb_width.replace([np.inf, -np.inf], np.nan).fillna(0.0)
+
+    bb_upper_smooth = bb_upper.rolling(window=smooth_length, min_periods=1).mean()
+    bb_lower_smooth = bb_lower.rolling(window=smooth_length, min_periods=1).mean()
+    bb_range_smooth = bb_upper_smooth - bb_lower_smooth
+
+    offset_distance = bb_range_smooth * zone_offset
+
+    top_zone_bottom = bb_upper_smooth + offset_distance
+    top_zone_top = top_zone_bottom + bb_range_smooth * zone_expansion
+
+    bottom_zone_top = bb_lower_smooth - offset_distance
+    bottom_zone_bottom = bottom_zone_top - bb_range_smooth * zone_expansion
+
+    price_in_top_zone = close > top_zone_bottom
+    price_in_bottom_zone = close < bottom_zone_top
+
+    bb_width_ma = bb_width.rolling(window=50, min_periods=1).mean()
+    is_squeeze = bb_width < bb_width_ma
+
+    price_in_top_zone_prev = price_in_top_zone.shift(1).fillna(False)
+    price_in_bottom_zone_prev = price_in_bottom_zone.shift(1).fillna(False)
+
+    n = len(candle_df)
+    enter_top = np.zeros(n, dtype=bool)
+    enter_bottom = np.zeros(n, dtype=bool)
+
+    top_vals = price_in_top_zone.to_numpy()
+    bottom_vals = price_in_bottom_zone.to_numpy()
+    top_prev_vals = price_in_top_zone_prev.to_numpy()
+    bottom_prev_vals = price_in_bottom_zone_prev.to_numpy()
+
+    last_buy_bar = -10**9
+    last_sell_bar = -10**9
+
+    for i in range(n):
+        if top_vals[i] and (not top_prev_vals[i]) and (i - last_sell_bar >= signal_cooldown):
+            enter_top[i] = True
+            last_sell_bar = i
+        if bottom_vals[i] and (not bottom_prev_vals[i]) and (i - last_buy_bar >= signal_cooldown):
+            enter_bottom[i] = True
+            last_buy_bar = i
+
+    factor_main = np.where(enter_bottom, 1.0, 0.0)
+    factor_main = np.where(enter_top, -1.0, factor_main)
+
+    candle_df[factor_name] = factor_main
+    candle_df[f"{factor_name}_ADX"] = adx
+    candle_df[f"{factor_name}_DI_Plus"] = di_plus
+    candle_df[f"{factor_name}_DI_Minus"] = di_minus
+    candle_df[f"{factor_name}_BB_Upper"] = bb_upper
+    candle_df[f"{factor_name}_BB_Lower"] = bb_lower
+    candle_df[f"{factor_name}_TopZoneBottom"] = top_zone_bottom
+    candle_df[f"{factor_name}_BottomZoneTop"] = bottom_zone_top
+    candle_df[f"{factor_name}_Squeeze"] = is_squeeze.astype(int)
+    candle_df[f"{factor_name}_EnterTop"] = enter_top.astype(int)
+    candle_df[f"{factor_name}_EnterBottom"] = enter_bottom.astype(int)
+
+    return candle_df
+