1. qteasy 總體架構與設計思路

1.1. 1. 引言：为什么需要从“架构”理解 qteasy

qteasy 是一套本地化、可復現的量化交易工具包。在使用教程和 API 文檔之外，若能從系統架構和設計思路理解各模塊如何分層、如何協作，可以更準確地使用接口、排查問題，並在擴展自定義策略或數據時少走彎路。本章從整體上概括 qteasy 的架構與三條設計主線，後續各章再分模塊展開。

1.2. 2. 三条设计主线（简述）

2.1 數據：從“原始表”到“類型化資訊”（DataType）

原始行情、財務等數據經拉取與清洗後，以統一表結構存入 DataSource（文件或數據庫）。qteasy 並不讓策略直接讀寫這些表，而是把“可被策略使用的資訊”抽象成 DataType（由 name、freq、asset_type 等構成，對應唯一的 dtype_id）。策略只聲明自己需要哪些 DataType 以及多長的歷史窗口（window_length），運行時由引擎按聲明從 DataSource 取出數據、整理成數據窗口並注入策略。這樣做的目的包括：回測與實盤使用同一套數據視圖、策略接口統一、從機制上避免“未來函數”（策略只能看到引擎按時間步注入的過去數據）。

2.2 策略：四大要素與統一的 realize()

一個策略在概念上包含四類要素：

  • 運行時機：何時、以何頻率運行（如每日收盤）——在 qteasy 2.0 中由策略所屬的 Group 管理，不在策略類內部寫死。

  • 所需數據：需要哪些 DataType、多長窗口（data_types、window_length 等），在策略初始化時聲明。

  • 可調參數：由 Parameter 定義，運行前通過 set_parameter 等設置，優化時由 Optimizer 在參數空間中搜索。

  • 邏輯：通過無參的 realize() 實現；在方法內通過 get_pars()、get_data(dtype_id) 獲取當前步的參數與數據，計算並返回交易信號。

同一段 realize() 在回測與實盤中複用，保證行爲一致。

2.3 運行：Operator 與 Group、按時間步驅動、統一 run(config)

Operator 既是策略的容器，也是運行的入口：它持有多個 Group，每個 Group 是一組具有相同 run_freq、run_timing（以及 signal_type、blender）的策略。group_timing_table 是一張“時間步 × Group”的表，表示每個時間步有哪些 Group 需要運行。單步流程可以概括爲：根據當前步查表得到要運行的 Group → 爲這些 Group 內的每個策略準備數據窗口並注入 → 調用各策略的 generate()（內部調用 realize()）→ 用 Group 的 blender 混合同組信號 → 得到該步的合併信號。回測、實盤、優化都基於同一套“按 group_timing_table 逐步運行 Operator”的機制；差異僅在於數據來源（歷史 vs 實時）和結果處理（模擬成交 vs 真實下單 vs 參數搜索）。

2.4 可視化：HistoryPanel 與多後端圖表

在數據與運行之上，qteasy 提供了基於 HistoryPanel 的可視化棧：

  • HistoryPanel 作爲三維數據容器（shares × hdates × htypes），既是 get_history_data 的自然返回值，也是可視化的前置數據結構；

  • HistoryPanel.plot(...) 是統一的繪圖入口，根據 htypes 與 shares 自動選擇 合適的圖表類型（K 線、成交量、MACD、折線等），並生成與後端無關的圖表規格；

  • 靜態後端（matplotlib）和交互後端（Plotly）在同一套規格之上渲染圖表， 保證靜態/交互視圖在配色、佈局和語義上的一致性；

  • 上層的 qt.candle(...) 等 API 只是“取數 → 構建 HistoryPanel → 調用 hp.plot()” 的包裝器。

這樣，可視化邏輯與數據獲取、回測引擎解耦，便於獨立演進和測試。

1.3. 3. 总体架构图（三层）

qteasy 從職責上可劃分爲三層，如下圖所示（文字版）：

flowchart TB subgraph dataLayer [数据层] DS[DataSource] Tables[数据表] DT[DataType / dtype_id] GHD[get_history_data] HP[HistoryPanel] DS --> Tables Tables --> DT DT --> GHD GHD --> HP end subgraph strategyLayer [策略层] BS[BaseStrategy 及子类] PAR[Parameter] DTL[data_types / window_length] BS --> PAR BS --> DTL HP --> BS end subgraph runLayer [运行层] OP[Operator] GR[Group] GTT[group_timing_table] BL[blender] BT[Backtester] TR[Trader] OPR[Optimizer] OP --> GR OP --> GTT GR --> BL OP --> BT OP --> TR OP --> OPR end subgraph vizLayer [可视化层] HPPlot[HistoryPanel.plot] SpecBuilder[图表规格/布局] StaticBackend[静态后端(matplotlib)] InteractiveBackend[交互后端(Plotly)] HP --> HPPlot HPPlot --> SpecBuilder SpecBuilder --> StaticBackend SpecBuilder --> InteractiveBackend end dataLayer --> strategyLayer strategyLayer --> runLayer dataLayer --> vizLayer

  • 數據層：DataSource、數據表、DataType、以及面向外部的 get_history_data / HistoryPanel，爲策略與運行層提供“按類型、按窗口”的歷史資訊。

  • 策略層：BaseStrategy 及子類（如 RuleIterator、FactorSorter、GeneralStg）、Parameter、data_types / window_length，負責聲明需求並實現 realize()。

  • 運行層：Operator、Group、group_timing_table、blender，以及 Backtester / Trader / Optimizer，負責按時間驅動策略、彙總信號並執行回測/實盤/優化。

1.4. 4. 核心对象关系图

flowchart LR subgraph operator [Operator] G1[Group A] G2[Group B] end G1 --> S1[Strategy 1] G1 --> S2[Strategy 2] G2 --> S3[Strategy 3] S1 --> DT[DataType] S1 --> PAR[Parameter] S2 --> DT S2 --> PAR S3 --> DT S3 --> PAR OP_RUN[op.run] CFG[config] DSRC[datasource] OP_RUN --> operator CFG --> OP_RUN DSRC --> OP_RUN

  • Operator 包含多個 Group，每個 Group 包含多個 Strategy。

  • 每個 Strategy 聲明自己依賴的 DataType（及 window_length），並通過 Parameter 定義可調參數。

  • 運行入口爲 op.run(config, datasource, logger)，由 config 與 datasource 驅動。

1.5. 5. 数据与信号的大致流向

從數據源到策略再到回測/實盤/優化，整體流向可簡化爲：

sequenceDiagram participant User participant DataSource participant Operator participant Strategy participant Backtester User->>Operator: qt.run(op, mode=1/0/2, ...) Operator->>DataSource: 按策略声明请求历史/实时数据 DataSource-->>Operator: 数据窗口 loop 每个时间步 Operator->>Strategy: 注入数据窗口，调用 realize() Strategy-->>Operator: 信号 Operator->>Operator: blender 混合 end Operator-->>Backtester: 信号序列（回测时） Backtester-->>User: 资金曲线、绩效等

  • 用戶通過 qt.run(op, mode=...) 進入回測（1）、實盤（0）或優化（2）。

  • Operator 根據 config 與策略聲明向 DataSource 請求數據，再按 group_timing_table 逐步調用策略並混合信號。

  • 回測時，信號序列交給 Backtester 做模擬成交與評價；實盤時交給 Trader/Broker 執行；優化時由 Optimizer 多次回測並彙總。

1.6. 6. 本系列各章与教程、API、示例的阅读顺序建议

  • 本系列（架構與設計）：建議先讀本章（00）和 核心概念速覽，再按需閱讀 數據層、策略中的數據、Operator 與 Group、Strategy 運行與參數、回測/實盤/優化，以建立整體圖景。

  • 使用教程：側重“手把手”操作，適合在瞭解架構後按需選讀，用於完成具體任務（如下載數據、編寫策略、運行回測）。

  • 下載並管理金融歷史數據、API 參考：用於查詢數據配置、接口參數與返回值；本系列只講“結構與機制”，不替代 API 文檔。

  • 示例：提供完整可運行示例，可與教程、本系列配合使用。