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 文档。

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