Fire 策略系统文档

概述

Fire量化交易系统采用模块化的策略架构，所有策略基于 BaseStrategy 基类实现，通过 StrategyRegistry 自动注册系统进行管理。本文档涵盖策略实现、注册、生命周期管理和数据处理规范。

当前系统状态

已实现功能

StrategyRegistry 自动注册系统
- 基于装饰器的策略注册
- 自动元数据管理
- 策略分类和查询
pandas-ta 技术指标集成
- 10+ 常用技术指标
- 两层缓存优化（全局 + 实例级）
- TTL自动过期机制
策略生命周期管理
- TradingChannel 自动启动/停止 StrategyEngine
- 策略预热机制 (is_warmup 参数)
- 防御性日志和错误处理

已注册策略列表

当前共 8 个策略 已成功注册：

分类	策略ID	描述	状态
Momentum (2个)
	`MomentumBreakoutStrategy`	动量突破策略：价格突破 + 成交量确认	已实现
	`RSIMomentumStrategy`	RSI动量策略：RSI + 趋势过滤	已实现
Trend Following (3个)
	`MACDStrategy`	MACD策略	已实现
	`MACrossStrategy`	移动平均线交叉：快慢均线金叉死叉	已实现
	`TrendChannelStrategy`	趋势通道：Donchian Channel + ATR止损	已实现
Mean Reversion (1个)
	`BollingerBandsStrategy`	布林带均值回归：触及上下轨交易	已实现
Volume (1个)
	`VolumeSpikeStrategy`	成交量异动：异常成交量 + 价格变化	已实现
Volatility (1个)
	`LowVolatilityStrategy`	低波动率：寻找低波动率股票	已实现

验证命令:

cd backend && source venv/bin/activate
python -c "from core.trading.strategies.registry import StrategyRegistry; \
           import core.trading.strategies; \
           StrategyRegistry.debug_print_registry()"

开发者必读

核心设计原则

1. 数据查询架构原则

严格数据查询原则（Critical Design Principle）

单点查询：必须精确匹配

单点查询 (get_stock_data(symbol, timestamp)):
- 必须精确匹配时间戳
- 如果指定时间点无数据，返回 None
- 禁止返回”附近”或”最近”的数据
- 这确保了回测、分析等场景的数据准确性和可重复性

为什么禁止近似查询？

回测时同一个数据点被返回上千次
策略看到19小时价格不变 → 无法产生交易信号
破坏了时间序列数据的完整性

批量查询：有就有，没有就没有

时间范围查询 (get_stock_data_list(), get_stock_data_by_date()):
- 返回指定时间范围内的所有可用数据
- 数据有就有，没有就没有
- 禁止自动向前回溯填充
- 禁止返回”附近”的数据
- 调用方可以根据返回的数据量判断数据完整性

回溯查询：必须返回回溯信息

如果需要”凑齐N个数据点”的功能（例如策略预热需要固定数量的历史数据），系统提供专门的回溯查询方法：

get_stock_data_with_backfill() - 返回指定数量的数据和回溯信息
返回值包含数据列表和从起始时间向前回溯的秒数

数据查询方式：

单点查询: 精确匹配指定时间戳，无数据则返回 None
范围查询: 返回时间范围内的所有可用数据
回溯查询: 向前回溯获取指定数量的数据

详细规范: 市场数据缺失处理规范

策略架构

StrategyRegistry 自动注册系统

Fire 使用基于装饰器的策略注册系统，无需手动维护策略映射。

注册新策略

from core.trading.strategies.registry import StrategyRegistry
from core.trading.strategies.metadata import StrategyCategory
from core.trading.strategies.base_strategy import BaseStrategy

@StrategyRegistry.register(
    category=StrategyCategory.MOMENTUM,
    description="我的动量策略：自定义逻辑",
    min_history_bars=50,
    supports_realtime=True,
    supports_backtest=True,
)
class MyMomentumStrategy(BaseStrategy):
    def __init__(self, name: str, config: Dict[str, Any]):
        super().__init__(name, config)
        # 初始化参数

    def on_market_data(self, market_data: MarketData, is_warmup: bool = False):
        # 处理市场数据
        pass

    def on_trade_update(self, trade):
        # 处理交易更新
        pass

策略元数据

注册时可指定以下元数据：

参数	类型	默认值	说明
`category`	`StrategyCategory`	必需	策略分类（MOMENTUM/TREND_FOLLOWING/等）
`description`	`str`	必需	策略描述（至少10个字符）
`supports_realtime`	`bool`	`True`	是否支持实时交易
`supports_backtest`	`bool`	`True`	是否支持回测
`supports_markets`	`List[MarketType]`	所有市场	支持的市场类型
`supports_granularities`	`List[TimeGranularity]`	常用粒度	支持的时间粒度
`min_history_bars`	`int`	`100`	最少历史数据条数
`memory_intensive`	`bool`	`False`	是否内存密集
`cpu_intensive`	`bool`	`False`	是否CPU密集

查询已注册策略

# 获取策略类
strategy_class = StrategyRegistry.get_strategy("MomentumBreakoutStrategy")

# 获取元数据
metadata = StrategyRegistry.get_metadata("MomentumBreakoutStrategy")

# 列出所有策略
all_strategies = StrategyRegistry.list_all_strategies()

# 按分类列出
momentum_strategies = StrategyRegistry.list_by_category(StrategyCategory.MOMENTUM)

# 验证策略存在
if StrategyRegistry.validate_strategy_exists("MyStrategy"):
    print("策略已注册")

策略参数定义系统

参数类型系统

Fire 支持完整的参数类型系统,前端会根据参数类型自动渲染合适的UI组件。

定义策略参数

所有策略参数必须在 backend/core/models/strategy_config.py 的 StrategyConfigPreset 中定义:

from core.models.strategy_config import StrategyParameter, ParameterType, StrategyConfigTemplate

# 在 STRATEGY_TEMPLATES 字典中添加策略模板
"MyStrategy": StrategyConfigTemplate(
    strategy_name="MyStrategy",
    display_name="我的策略",
    description="策略描述",
    version="1.0.0",
    author="系统",
    parameters=[
        # 整数参数 - 用于周期、数量、索引
        StrategyParameter(
            name="fast_period",
            type=ParameterType.INTEGER,  # 整数类型
            default_value=12,
            description="快线周期（K线数量）",
            min_value=5,
            max_value=50,
            category="technical",
        ),

        # 浮点数参数 - 用于比率、百分比、价格
        StrategyParameter(
            name="stop_loss",
            type=ParameterType.FLOAT,  # 浮点数类型
            default_value=0.03,
            description="止损比例（相对价格变化）",
            min_value=0.01,
            max_value=0.20,
            category="risk",
        ),

        # 布尔参数 - 用于开关
        StrategyParameter(
            name="use_ema",
            type=ParameterType.BOOLEAN,
            default_value=True,
            description="使用指数移动平均线",
            category="technical",
        ),

        # 枚举参数 - 用于选项列表
        StrategyParameter(
            name="ma_type",
            type=ParameterType.STRING,
            default_value="EMA",
            description="均线类型",
            allowed_values=["SMA", "EMA"],
            category="technical",
        ),
    ],
    # ... 其他配置
)

参数类型与UI组件映射

前端会根据参数类型自动选择UI组件:

参数类型	UI组件	步长	精度	示例
`INTEGER`	Slider / InputNumber	`step=1`	`precision=0`	周期=12 (显示为 “12”)
`FLOAT`	Slider / InputNumber	`step=0.01`	`precision=2`	止损=0.03 (显示为 “0.03”)
`BOOLEAN`	Switch	-	-	启用EMA: ON/OFF
`STRING` (with `allowed_values`)	Select	-	-	均线类型: SMA/EMA
`STRING` (without `allowed_values`)	Input	-	-	自定义文本

参数类型选择指南

参数模式	推荐类型	原因	示例
`*_period`	`INTEGER`	K线数量必须是整数	`fast_period=12`
`*_days`	`INTEGER`	天数必须是整数	`lookback_days=20`
`lookback_*`	`INTEGER`	历史窗口大小是整数	`lookback_period=50`
`*_threshold`	`FLOAT`	通常是0-1之间的比率	`breakout_threshold=0.65`
`*_ratio`	`FLOAT`	比率值通常是小数	`position_ratio=0.1`
`stop_` / `take_`	`FLOAT`	止损止盈为价格变化百分比	`stop_loss=0.03`
`*_multiplier`	`FLOAT`	乘数可以是小数	`volume_multiplier=1.5`
`max_` / `min_`	`INTEGER`	数量限制通常是整数	`max_positions=5`
`use_` / `enable_`	`BOOLEAN`	开关标志	`use_ema=True`

前端自动化处理

定义好参数类型后,前端会自动:

类型转换: useStrategyMetadata.ts 保留 integer/float 区分
步长设置: 整数 step=1, 浮点数 step=0.01
精度控制: 整数 precision=0 (无小数), 浮点数 precision=2 (2位小数)
显示格式: 整数显示 “12”, 浮点数显示 “0.03”

无需前端额外配置,只需在后端正确定义 ParameterType 即可!

完整示例

参考现有策略的参数定义:

整数参数: MACrossStrategy (快慢线周期)
浮点数参数: MomentumBreakoutStrategy (止损止盈比例)
混合参数: 大多数策略同时包含整数和浮点数参数

策略生命周期管理

生命周期阶段

┌─────────────┐
│   创建      │ → strategy = StrategyClass(name, config)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  初始化     │ → strategy.initialize(context)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  预热       │ → strategy.on_market_data(data, is_warmup=True)
│  (WARMING)  │   积累历史数据，不生成信号
│             │   追踪: warmup_progress / warmup_required
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  运行       │ → strategy.on_market_data(data, is_warmup=False)
│  (交易)     │   处理实时数据，生成信号
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  停止       │ → strategy.stop() (如果有清理逻辑)
└─────────────┘

StrategyEngine 生命周期

TradingChannel 自动管理 StrategyEngine 的生命周期：

通道启动时自动启动策略引擎
通道停止时自动停止策略引擎
确保策略引擎与交易通道状态同步

策略预热机制

策略支持自动追踪预热进度，并在完成时自动通知：

1. 声明所需历史数据量

通过实现 get_required_history_length() 方法声明策略需要的历史数据条数。

2. 初始化预热状态

在 initialize() 方法中调用 _init_warmup_state() 初始化预热状态跟踪。

3. 在数据处理中追踪预热进度

在 on_market_data 方法中：

调用 _update_warmup_progress() 更新预热进度
预热阶段只积累数据，不生成信号
预热完成后开始正常处理市场数据并生成信号

4. 预热进度日志

策略会自动记录预热进度：

预热状态初始化：需要 50 条历史数据
预热中：10/50 (20.0%)
预热中：20/50 (40.0%)
预热中：30/50 (60.0%)
预热中：40/50 (80.0%)
预热中：50/50 (100.0%)
预热完成！已接收 50 条数据，策略准备就绪

5. 预热状态属性

策略提供以下属性来追踪预热状态：

is_warmed_up: bool - 预热是否完成
warmup_progress: int - 已接收的数据条数
warmup_required: int - 需要的数据条数

策略开发指南

1. 基础策略结构

策略开发需要：

继承 BaseStrategy 基类
使用 @StrategyRegistry.register 装饰器注册策略，指定分类、描述和所需历史数据条数
在 __init__ 中配置策略参数和初始化数据结构
实现 initialize() 接收策略上下文
实现 get_required_history_length() 声明所需历史数据量
实现 on_market_data() 处理市场数据并生成信号
可选实现 on_trade_update() 处理交易回调

参考现有策略实现：backend/core/trading/strategies/

2. 使用 pandas-ta 技术指标

系统集成了 pandas-ta 库，提供10+种常用技术指标：

使用 PandasTAWrapper 调用技术指标
内置两级缓存机制（全局 + 实例级）
支持的指标：RSI、MACD、SMA、EMA、ATR、BBANDS 等

所有指标计算自动缓存，避免重复计算。

3. 共同设计模式

动态股票管理模式

策略支持动态管理多个股票的历史数据：

使用 Dict[str, deque] 结构存储每个股票的数据
首次接收某股票数据时自动初始化
使用 deque(maxlen=N) 自动限制历史数据长度

信号生成模式

使用 _set_signal() 方法生成交易信号：

direction: “BUY”, “SELL”, 或 “HOLD”
confidence: 0.0 到 1.0 之间的置信度
metadata: 可选的附加信息

其他模块通过 get_signal(symbol) 获取策略信号。

策略对比

策略名称	类别	技术指标	信号逻辑	适用场景	风险特征	历史数据需求
MomentumBreakoutStrategy	动量	价格、成交量、标准差	突破 + 成交量确认	趋势启动	中等风险	50条
RSIMomentumStrategy	动量	RSI、EMA	RSI超买超卖 + 趋势过滤	趋势市场	中等风险	50条
MACrossStrategy	趋势	快慢均线	均线交叉（金叉死叉）	趋势确认	低风险	50条
TrendChannelStrategy	趋势	Donchian Channel、ATR	通道突破 + ATR止损	突破交易	高风险	50条
BollingerBandsStrategy	波动率	布林带（SMA + 标准差）	触及上下轨均值回归	震荡市场	中等风险	50条
LowVolatilityStrategy	波动率	ATR、标准差	低波动选股 + 成交量过滤	稳健配置	低风险	50条
VolumeSpikeStrategy	成交量	成交量、价格	异常成交量 + 价格方向	事件驱动	高风险	30条

测试策略

所有策略都有对应的单元测试，验证以下功能：

策略初始化
信号生成逻辑
预热状态管理
多股票处理
边界条件

测试文件位于 tests/unit/strategies/ 目录。

策略性能监控

所有策略跟踪以下指标：

总交易次数
胜率（盈利交易占比）
最大回撤
夏普比率
累计收益率
平均持仓时间

通过日志和Redis可以实时查看策略表现。

技术指标管理

Fire 系统提供技术指标元数据管理功能，便于用户了解和使用各种技术指标。

可用技术指标

系统当前包含 10 个 常用技术指标元数据：

指标ID	名称	类型	描述
`rsi`	相对强弱指标 (RSI)	momentum	衡量价格变动速度的动量振荡器
`macd`	MACD	trend	趋势跟踪动量指标
`bollinger_bands`	布林带	volatility	基于标准差的波动率通道
`sma`	简单移动平均线	trend	价格算术平均
`ema`	指数移动平均线	trend	加权移动平均
`atr`	真实波幅 (ATR)	volatility	衡量市场波动性
`stoch`	随机指标	momentum	超买超卖振荡器
`obv`	能量潮 (OBV)	volume	成交量趋势指标
`vwap`	成交量加权平均价	volume	机构交易参考
`adx`	平均方向指数	trend	趋势强度指标

指标元数据存储

指标元数据以 JSON 文件形式存储在：

backend/core/trading/strategies/indicators/metadata/
├── _template.md          # JSON 模板说明
├── rsi.json
├── macd.json
├── bollinger_bands.json
├── sma.json
├── ema.json
├── atr.json
├── stoch.json
├── obv.json
├── vwap.json
└── adx.json

添加新指标

在 metadata/ 目录下创建新的 JSON 文件
参考 _template.md 填写指标信息
指标会自动被 API 发现并返回

JSON 文件结构：

{
  "id": "indicator_id",
  "name": "INDICATOR",
  "display_name": "指标中文名",
  "english_name": "English Name",
  "category": "momentum|trend|volatility|volume",
  "description": "详细描述...",
  "parameters": [
    {
      "name": "length",
      "type": "int",
      "default": 14,
      "min": 2,
      "max": 100,
      "description": "参数描述"
    }
  ],
  "pandas_ta": {
    "function": "ta.indicator(...)",
    "returns": "pd.Series|pd.DataFrame",
    "example": "df.ta.indicator(length=14)"
  },
  "interpretation": {
    "signal_type": "信号解读说明"
  }
}

前端技术指标页面

访问 /strategies/analysis 可以浏览和搜索所有技术指标：

支持按名称搜索
支持按类别筛选
点击查看详细参数说明和 pandas-ta API 文档