# API 参考

本 API 文档涵盖了 AKQuant 的核心类和方法。

快速跳转：

*   [LiveRunner broker_live 执行语义](#live-broker-semantics)

## 1. 高级入口 (High-Level API)

### `akquant.run_backtest`

最常用的回测入口函数，封装了引擎的初始化和配置过程。

```python
def run_backtest(
    data: Optional[Union[pd.DataFrame, Dict[str, pd.DataFrame], List[Bar]]] = None,
    strategy: Union[Type[Strategy], Strategy, Callable[[Any, Bar], None], None] = None,
    symbols: Union[str, List[str], Tuple[str, ...], set[str]] = "BENCHMARK",
    initial_cash: Optional[float] = None,
    commission_rate: Optional[float] = None,
    stamp_tax_rate: float = 0.0,
    transfer_fee_rate: float = 0.0,
    min_commission: float = 0.0,
    slippage: Optional[float] = None,
    volume_limit_pct: Optional[float] = None,
    timezone: Optional[str] = None,
    t_plus_one: bool = False,
    initialize: Optional[Callable[[Any], None]] = None,
    on_start: Optional[Callable[[Any], None]] = None,
    on_stop: Optional[Callable[[Any], None]] = None,
    context: Optional[Dict[str, Any]] = None,
    history_depth: Optional[int] = None,
    warmup_period: int = 0,
    lot_size: Union[int, Dict[str, int], None] = None,
    show_progress: Optional[bool] = None,
    start_time: Optional[Union[str, Any]] = None,
    end_time: Optional[Union[str, Any]] = None,
    config: Optional[BacktestConfig] = None,
    instruments_config: Optional[Union[List[InstrumentConfig], Dict[str, InstrumentConfig]]] = None,
    custom_matchers: Optional[Dict[AssetType, Any]] = None,
    risk_config: Optional[Union[Dict[str, Any], RiskConfig]] = None,
    strategies_by_slot: Optional[Dict[str, Union[Type[Strategy], Strategy, Callable[[Any, Bar], None]]]] = None,
    on_event: Optional[Callable[[BacktestStreamEvent], None]] = None,
    broker_profile: Optional[str] = None,
    fill_policy: Optional[Dict[str, Any]] = None,
    strict_strategy_params: bool = True,
    **kwargs: Any,
) -> BacktestResult
```

### `akquant.run_grid_search`

参数网格搜索入口，用于批量回测并按指标排序返回最优参数组合。

```python
def run_grid_search(
    strategy: Type[Strategy],
    param_grid: Dict[str, Sequence[Any]],
    data: Union[pd.DataFrame, Dict[str, pd.DataFrame], List[Bar]],
    sort_by: Union[str, List[str]] = "sharpe_ratio",
    ascending: Union[bool, List[bool]] = False,
    return_df: bool = True,
    result_filter: Optional[Callable[[Dict[str, Any]], bool]] = None,
    constraint: Optional[Callable[[Dict[str, Any]], bool]] = None,
    max_workers: Optional[int] = None,
    show_progress: bool = True,
    timeout: Optional[float] = None,
    max_tasks_per_child: Optional[int] = None,
    db_path: Optional[str] = None,
    forward_worker_logs: bool = False,
    **kwargs: Any,
) -> Union[pd.DataFrame, List[OptimizationResult]]
```

**关键参数补充:**

*   `forward_worker_logs`: 并行优化时是否将子进程策略日志回传到主进程。
    *   `False`：吞吐优先，日志可能在主进程不可见。
    *   `True`：启用日志聚合，便于排障。
*   `strict_strategy_params`: 通过 `**kwargs` 传递给 `run_backtest`（默认在 `run_grid_search` 内为 `True`）。
    *   严格校验 `param_grid` 与策略构造参数匹配关系；
    *   参数不匹配时快速失败，避免静默回退。

### `akquant.run_walk_forward`

滚动优化入口。按窗口执行“样本内参数优化 + 样本外验证”，并拼接样本外资金曲线。

```python
def run_walk_forward(
    strategy: Type[Strategy],
    param_grid: Mapping[str, Sequence[Any]],
    data: pd.DataFrame,
    train_period: int,
    test_period: int,
    metric: Union[str, List[str]] = "sharpe_ratio",
    ascending: Union[bool, List[bool]] = False,
    initial_cash: float = 100_000.0,
    warmup_period: int = 0,
    warmup_calc: Optional[Any] = None,
    constraint: Optional[Any] = None,
    result_filter: Optional[Any] = None,
    compounding: bool = False,
    timeout: Optional[float] = None,
    max_tasks_per_child: Optional[int] = None,
    **kwargs: Any,
) -> pd.DataFrame
```

**关键参数补充:**

*   `**kwargs` 会透传到 `run_grid_search`（样本内优化阶段）与 `run_backtest`（样本外验证阶段）。
*   因此，`forward_worker_logs` 可用于控制样本内并行优化日志回传。
*   同时，`strict_strategy_params` 会在优化与回测阶段保持严格参数校验语义（默认严格）。

### `akquant.run_warm_start`

从快照恢复并继续运行回测（支持多策略 slot 执行）。

```python
def run_warm_start(
    checkpoint_path: str,
    data: Optional[BacktestDataInput] = None,
    show_progress: bool = True,
    symbols: Union[str, List[str], Tuple[str, ...], set[str]] = "BENCHMARK",
    strategy_runtime_config: Optional[Union[StrategyRuntimeConfig, Dict[str, Any]]] = None,
    runtime_config_override: bool = True,
    strategy_id: Optional[str] = None,
    strategies_by_slot: Optional[Dict[str, Union[Type[Strategy], Strategy, Callable[[Any, Bar], None]]]] = None,
    strategy_max_order_value: Optional[Dict[str, float]] = None,
    strategy_max_order_size: Optional[Dict[str, float]] = None,
    strategy_max_position_size: Optional[Dict[str, float]] = None,
    strategy_max_daily_loss: Optional[Dict[str, float]] = None,
    strategy_max_drawdown: Optional[Dict[str, float]] = None,
    strategy_reduce_only_after_risk: Optional[Dict[str, bool]] = None,
    strategy_risk_cooldown_bars: Optional[Dict[str, int]] = None,
    strategy_priority: Optional[Dict[str, int]] = None,
    strategy_risk_budget: Optional[Dict[str, float]] = None,
    portfolio_risk_budget: Optional[float] = None,
    risk_budget_mode: Literal["order_notional", "trade_notional"] = "order_notional",
    risk_budget_reset_daily: bool = False,
    on_event: Optional[Callable[[BacktestStreamEvent], None]] = None,
    config: Optional[BacktestConfig] = None,
    **kwargs: Any,
) -> BacktestResult
```

**关键参数:**

*   `data`: 回测数据。支持单个 DataFrame，`{symbol: DataFrame}` 字典，`List[Bar]`，或实现 `DataFeedAdapter.load(request)` 的对象。
*   `strategy`: 策略类、策略实例，或 `on_bar` 函数（函数式编程风格）。
*   `initialize` / `on_start` / `on_resume` / `on_stop`: 函数式策略生命周期回调；其中 `on_resume(ctx)` 仅在 checkpoint 恢复后的热启动阶段触发，且先于 `on_start(ctx)`。
*   `on_tick` / `on_order` / `on_trade` / `on_reject` / `on_session_start` / `on_session_end` / `on_before_trading` / `on_after_trading` / `on_daily_rebalance` / `on_portfolio_update` / `on_error` / `on_expiry` / `on_pre_open` / `on_timer` / `on_train_signal`: 函数式策略事件回调；其中 `on_expiry(ctx, event)` 在引擎实际执行到期结算后触发，`on_pre_open(ctx, event)` 在每个交易日首个常规行情事件前触发，适合“盘前决策，本次 open 成交”；`on_error(ctx, error, source, payload)` 会在其他用户回调抛出异常时触发；`on_train_signal(ctx)` 仅在 ML 滚动训练窗口触发。
*   `symbols`: 标的代码或代码列表。
*   `initial_cash`: 初始资金 (默认 100,000.0)。
*   legacy 价格基准参数：已移除。
*   legacy 时序参数：已移除。
*   `fill_policy`: 统一成交语义配置。
    *   `price_basis`: `open`、`close`、`ohlc4`（OHLC 平均价）或 `hl2`（高低中价）。
    *   `bar_offset`: `0` 或 `1`，用于完整三轴语义。
    *   预留（暂未实现）: `mid_quote`、`vwap_window`、`twap_window`（当前会抛出 `NotImplementedError`）。
    *   `temporal`: `same_cycle` 或 `next_event`。
*   `legacy_execution_policy_compat`（通过 `**kwargs`）: 已移除。
*   迁移建议：legacy 执行参数已不再接受，统一使用 `fill_policy`。
*   `strict_strategy_params`: 是否严格校验策略构造参数（默认 `True`）。
    *   当传入策略不接受的参数时会立即抛错；
    *   推荐保持默认值，避免参数错配被静默忽略导致回测结果偏差。
*   `t_plus_one`: 是否启用 T+1 交易规则 (默认 False)。如果启用，将强制使用中国市场模型。
*   `slippage`: 全局滑点 (默认 0.0)。例如 0.0001 代表 1bp (0.01%) 的滑点，采用百分比模型。
*   `volume_limit_pct`: 成交量限制比例 (默认 0.25)。限制单笔成交不超过该 Bar 总成交量的百分比。
*   `warmup_period`: 策略预热期。指定需要预加载的历史数据长度（Bar 数量），用于计算指标。
*   `start_time` / `end_time`: 回测开始/结束时间。
*   `config`: `BacktestConfig` 配置对象，用于集中管理配置。
*   `instruments_config`: 标的配置。用于设置期货/期权等非股票资产的参数（如乘数、保证金）。
*   `lot_size`: 最小交易单位。如果是 `int`，应用于所有标的；如果是字典，按标的匹配。
*   `custom_matchers`: 自定义撮合器字典。
*   `risk_config`: 风控配置。支持字典 (e.g., `{"max_position_pct": 0.1}`) 或 `RiskConfig` 对象。如果同时提供了 `config.strategy_config.risk`，此参数将覆盖其中的同名字段。
*   `strategies_by_slot`: 可选多策略映射。键为 slot id，值为策略类/实例/函数式 on_bar 回调；用于启用 slot 迭代执行。
*   `strategy_fill_policy`: 可选策略级默认成交策略映射（`strategy_id -> fill_policy`）。
    下单时优先级：订单级 `fill_policy` > `strategy_fill_policy[strategy_id]` > 运行级 `fill_policy`。
*   `strategy_slippage`: 可选策略级默认滑点映射（`strategy_id -> slippage`）。
    下单时优先级：订单级 `slippage` > `strategy_slippage[strategy_id]` > 运行级 `slippage`。
*   `strategy_commission`: 可选策略级默认佣金映射（`strategy_id -> commission`）。
    下单时优先级：订单级 `commission` > `strategy_commission[strategy_id]` > 运行级佣金模型。
*   配置分层（推荐心智模型）：
    1) 订单级（`buy/sell/submit_order` 传参）；
    2) 策略映射级（`strategy_*`，按 `strategy_id/slot`）；
    3) 运行级（`run_backtest` 参数）；
    4) 市场默认（market model 内建默认规则）。
*   T+1 范围说明：当前 `t_plus_one` 仍是运行级/市场级开关，不支持按 `strategy_id` 分层配置。
*   `analyzer_plugins`: 可选 Analyzer 插件列表。插件接收 `on_start/on_bar/on_trade/on_finish` 生命周期回调，结果汇总到 `result.analyzer_outputs`。
*   `on_event`: 可选事件回调。不传时内部使用 no-op 回调并保持阻塞返回语义；传入时可实时消费事件。
*   `broker_profile`: 可选 broker 参数模板，用于快速注入费率/滑点/最小手数等默认值。内置模板：`cn_stock_miniqmt`、`cn_stock_t1_low_fee`、`cn_stock_sim_high_slippage`。

**fill_policy 推荐示例（主路径）：**

```python
# 下一根 K 线收盘价成交
result = aq.run_backtest(
    data=data,
    strategy=MyStrategy,
    symbols="000001",
    fill_policy={"price_basis": "close", "bar_offset": 1, "temporal": "same_cycle"},
)

# 当前收盘价 + next_event 时序
result = aq.run_backtest(
    data=data,
    strategy=MyStrategy,
    symbols="000001",
    fill_policy={"price_basis": "close", "bar_offset": 0, "temporal": "next_event"},
)
```

**执行语义速查（三轴主路径）：**

| 场景 | `fill_policy` |
| :--- | :--- |
| next-open 风格成交 | `{"price_basis":"open","bar_offset":1,"temporal":"same_cycle"}` |
| current-close 风格成交 | `{"price_basis":"close","bar_offset":0,"temporal":"same_cycle"}` |
| 下一根收盘价成交 | `{"price_basis":"close","bar_offset":1,"temporal":"same_cycle"}` |
| 下一根 OHLC 均价成交 | `{"price_basis":"ohlc4","bar_offset":1,"temporal":"same_cycle"}` |
| 下一根 HL2 成交 | `{"price_basis":"hl2","bar_offset":1,"temporal":"same_cycle"}` |

说明：
* 对 `open/ohlc4/hl2` 这三种 `price_basis`，`bar_offset` 固定为 `1`（不支持 `0`）。
* 对 `close + bar_offset=1`（下一根收盘价）场景，核心时间位移语义由 `bar_offset` 决定；`temporal` 建议固定写 `same_cycle` 以减少歧义。
* `temporal` 的差异主要体现在 `close + bar_offset=0`（当前收盘价）场景。

**DataFeedAdapter 用法（多时间框）:**

```python
import akquant as aq

base = aq.CSVFeedAdapter(path_template="/data/{symbol}.csv")

feed_15m = base.resample(freq="15min", emit_partial=False)
feed_replay = base.replay(
    freq="1h",
    align="session",            # session | day | global
    day_mode="trading",         # 仅 align='day' 时生效: trading | calendar
    emit_partial=False,
    session_windows=[("09:30", "11:30"), ("13:00", "15:00")],  # 仅 align='session'
)

result = aq.run_backtest(
    data=feed_replay,
    strategy=MyStrategy,
    symbols="000001",
    show_progress=False,
)
```

*   `align="session"`: 按交易日分区，可叠加 `session_windows`。
*   `align="day"`: 按日分区，不接收 `session_windows`；`day_mode` 支持 `trading/calendar`。
*   `align="global"`: 按全局时间轴聚合，不按交易日切段。
*   参数建议：统一使用 `symbols`。`run_backtest`/`run_warm_start` 已不再接受 `symbol` 参数。

**兼容与迁移说明:**

*   推荐逐步将实时 UI / 日志 / 告警接入迁移到 `run_backtest(..., on_event=...)`。
*   流式场景统一使用 `run_backtest(..., on_event=...)`。
*   legacy 执行语义兼容开关已移除。
*   legacy 执行参数与 `legacy_execution_policy_compat` 不再接受。
*   公开执行配置全量统一使用 `fill_policy`。
*   在 PyCharm 中若未开启终端仿真，原生进度条可能不可见；可开启 `Emulate terminal in output console` 或改用 `on_event` 的 `progress` 事件输出文本进度。
*   阶段 5 后不再提供运行时参数级回滚开关；如需回滚请使用版本级回滚策略。

**阶段 5 迁移 FAQ:**

*   `run_backtest` 是否改名？不改名，调用方式保持不变。
*   `run_backtest` 是否仍可不传 `on_event`？可以，不传时仍返回同样的结果对象语义。
*   PyCharm 看不到进度条怎么办？先确认 `show_progress=True`，并在 Run 配置中开启 `Emulate terminal in output console`；若仍不可见，使用 `on_event` 消费 `progress` 事件打印文本进度。
*   线上出现问题如何回退？使用版本级回滚，不再支持 `_engine_mode` 参数级回切。
*   还可以继续用 `symbol` 吗？不可以。请统一迁移到 `symbols`。

### 流式参数与事件 (`run_backtest`)

**关键参数:**

*   `on_event`: 流式事件回调函数（可选），参数为 `BacktestStreamEvent`；不传时内部使用 no-op 回调。
*   `stream_progress_interval`: `progress` 事件采样间隔（正整数）。
*   `stream_equity_interval`: `equity` 事件采样间隔（正整数）。
*   `stream_batch_size`: 事件批量刷新阈值（正整数）。
*   `stream_max_buffer`: 缓冲区上限（正整数）。
*   `stream_error_mode`: 回调异常处理策略。
    *   `"continue"`: 回调报错后继续回测，并在结束事件中回传统计信息。
    *   `"fail_fast"`: 回调首次报错后立即终止，并抛出异常。
*   `stream_mode`: 流式模式。
    *   `"observability"`: 观测模式，允许采样与非关键事件背压丢弃。
    *   `"audit"`: 审计模式，禁用采样并采用阻塞背压（不丢弃非关键事件）。
*   `strategy_id`（通过 `**kwargs` 透传）: 为交易相关事件与结果打上策略归属，默认 `_default`。

**事件结构 (`BacktestStreamEvent`):**

*   `run_id`: 本次流式回测 ID。
*   `seq`: 事件序号（单调递增）。
*   `ts`: 事件时间戳（纳秒）。
*   `event_type`: 事件类型。
*   `symbol`: 关联标的（部分事件为空）。
*   `level`: 事件级别（如 `info`、`warn`、`error`）。
*   `payload`: 事件内容字典（字符串键值）。

**常见 `event_type`:**

*   生命周期: `started`, `finished`
*   采样更新: `progress`, `equity`
*   交易相关: `order`, `trade`, `risk`, `expiry`
*   运行异常: `error`
*   行情流: `tick`

**交易事件 payload 常用字段 (`order`/`trade`/`risk`/`expiry`):**

*   `owner_strategy_id`: 策略归属 ID（默认 `_default`）。
*   `order_id`: 订单 ID（`order`/`trade`/`risk`）。
*   `symbol`: 标的代码（`order`/`risk`）。
*   `status`: 订单状态（`order`）。
*   `filled_qty`: 订单已成交量（`order`）。
*   `trade_id`: 成交 ID（`trade`）。
*   `price`: 成交价格（`trade`）。
*   `quantity`: 成交数量（`trade`）。
*   `reason`: 风控拒绝原因（`risk`）。
*   `expiry_date`: 到期日（`expiry`，`YYYYMMDD`）。
*   `quantity_before`: 到期前持仓数量（`expiry`）。
*   `quantity_closed`: 本次因到期关闭的数量（`expiry`）。
*   `cash_flow`: 到期结算现金流（`expiry`）。
*   `settlement_type`: 到期结算模式（`expiry`，如 `cash`、`settlement_price`、`force_close`）。
*   `settlement_price`: 实际采用的结算价（`expiry`，存在时提供）。

**`finished.payload` 常用字段:**

*   `status`: `completed` 或 `failed`
*   `processed_events`: 已处理事件数
*   `total_trades`: 总成交笔数
*   `callback_error_count`: 回调报错次数
*   `dropped_event_count`: 背压丢弃事件总数
*   `dropped_event_count_by_type`: 按事件类型聚合的丢弃计数（`event=count` 逗号拼接）
*   `stream_mode`: 当前流式模式（`observability` 或 `audit`）
*   `sampling_enabled`: 是否启用采样（`true`/`false`）
*   `backpressure_policy`: 背压策略（`drop_non_critical` 或 `block`）
*   `last_callback_error`: 最近一次回调报错信息（存在时提供）
*   `reason`: 失败原因（存在时提供）

### `akquant.BacktestConfig`

用于集中配置回测参数的数据类。

```python
@dataclass
class BacktestConfig:
    strategy_config: StrategyConfig
    start_time: Optional[str] = None
    end_time: Optional[str] = None
    instruments: Optional[List[str]] = None
    instruments_config: Optional[Union[List[InstrumentConfig], Dict[str, InstrumentConfig]]] = None
    benchmark: Optional[str] = None
    timezone: str = "Asia/Shanghai"
    show_progress: bool = True
    history_depth: int = 0

    # Analysis & Bootstrap
    bootstrap_samples: int = 1000
    bootstrap_sample_size: Optional[int] = None
    analysis_config: Optional[Dict[str, Any]] = None

```

### `akquant.StrategyConfig`

策略层面的配置，包含资金、费率和风控。

```python
@dataclass
class StrategyConfig:
    initial_cash: float = 100000.0

    # 费率
    commission_rate: float = 0.0
    stamp_tax_rate: float = 0.0
    transfer_fee_rate: float = 0.0
    min_commission: float = 0.0

    # 执行
    enable_fractional_shares: bool = False
    round_fill_price: bool = True       # 是否对成交价进行最小变动价位取整
    slippage: float = 0.0               # 全局滑点 (e.g. 0.0002 for 2 bps)
    volume_limit_pct: float = 0.25      # 成交量限制 (e.g. 0.25 for 25% of bar volume)
    exit_on_last_bar: bool = True       # 是否在回测结束时自动平仓

    # 持仓限制
    max_long_positions: Optional[int] = None
    max_short_positions: Optional[int] = None

    # 风控
    risk: Optional[RiskConfig] = None

    # 多策略拓扑与策略级风控
    strategy_id: Optional[str] = None
    strategies_by_slot: Optional[Dict[str, Any]] = None
    strategy_max_order_value: Optional[Dict[str, float]] = None
    strategy_max_order_size: Optional[Dict[str, float]] = None
    strategy_max_position_size: Optional[Dict[str, float]] = None
    strategy_max_daily_loss: Optional[Dict[str, float]] = None
    strategy_max_drawdown: Optional[Dict[str, float]] = None
    strategy_reduce_only_after_risk: Optional[Dict[str, bool]] = None
    strategy_risk_cooldown_bars: Optional[Dict[str, int]] = None
    strategy_priority: Optional[Dict[str, int]] = None
    strategy_risk_budget: Optional[Dict[str, float]] = None
    portfolio_risk_budget: Optional[float] = None
```

### `akquant.InstrumentConfig`

用于配置单个标的属性的数据类。

```python
@dataclass
class InstrumentConfig:
    symbol: str
    asset_type: Union[
        Literal["STOCK", "FUTURES", "FUND", "OPTION"],
        InstrumentAssetTypeEnum
    ] = InstrumentAssetTypeEnum.STOCK
    multiplier: float = 1.0    # 合约乘数
    margin_ratio: float = 1.0  # 保证金率 (0.1 表示 10% 保证金)
    tick_size: float = 0.01    # 最小变动价位
    lot_size: int = 1          # 最小交易单位

    # 费率与执行 (资产专用)
    commission_rate: Optional[float] = None
    min_commission: Optional[float] = None
    stamp_tax_rate: Optional[float] = None
    transfer_fee_rate: Optional[float] = None
    slippage: Optional[float] = None

    # 期权相关
    option_type: Optional[
        Union[Literal["CALL", "PUT"], InstrumentOptionTypeEnum]
    ] = None
    strike_price: Optional[float] = None
    expiry_date: Optional[Union[int, date, datetime]] = None
    underlying_symbol: Optional[str] = None
    settlement_type: Optional[
        Union[
            Literal["cash", "settlement_price", "force_close"],
            InstrumentSettlementTypeEnum
        ]
    ] = None
    settlement_price: Optional[float] = None
```

常用枚举（均可在 `akquant` 顶层直接访问）：

- `InstrumentAssetTypeEnum`: `STOCK` / `FUTURES` / `FUND` / `OPTION`
- `InstrumentOptionTypeEnum`: `CALL` / `PUT`
- `InstrumentSettlementTypeEnum`: `CASH` / `SETTLEMENT_PRICE` / `FORCE_CLOSE`

示例：

```python
conf = akquant.InstrumentConfig(
    symbol="IF2506",
    asset_type=akquant.InstrumentAssetTypeEnum.FUTURES,
    settlement_type=akquant.InstrumentSettlementTypeEnum.CASH,
)
```

### `akquant.InstrumentSnapshot`

策略侧可访问的标的静态属性快照对象（由引擎注入，通常通过 `Strategy.get_instrument*` 读取）。

```python
@dataclass(frozen=True)
class InstrumentSnapshot:
    symbol: str
    asset_type: Literal["STOCK", "FUTURES", "FUND", "OPTION"]
    multiplier: float
    margin_ratio: float
    tick_size: float
    lot_size: float
    option_type: Optional[Literal["CALL", "PUT"]] = None
    strike_price: Optional[float] = None
    expiry_date: Optional[int] = None  # YYYYMMDD
    underlying_symbol: Optional[str] = None
    settlement_type: Optional[Literal["CASH", "SETTLEMENT_PRICE", "FORCE_CLOSE"]] = None
    settlement_price: Optional[float] = None
    static_attrs: Dict[str, Union[str, int, float, bool]] = field(default_factory=dict)
```

要点：

*   `expiry_date` 使用 `int(YYYYMMDD)` 语义。
*   快照在 `on_start` 即可访问。
*   建议在策略中通过 `get_instrument` / `get_instrument_config` / `get_instrument_field` 访问。

### 配置系统详解 (Configuration System)

AKQuant 提供了灵活的配置系统，允许用户通过多种方式设置回测参数。

#### 1. 配置层级 (Hierarchy)

配置对象采用树状结构组织，`BacktestConfig` 是顶层入口：

```text
BacktestConfig (回测场景)
├── StrategyConfig (策略与账户)
│   ├── initial_cash (初始资金)
│   ├── commission_rate (默认佣金)
│   ├── slippage (默认滑点)
│   └── RiskConfig (风控规则)
│       ├── safety_margin (安全垫)
│       └── max_position_pct (持仓限制)
└── InstrumentConfig (资产属性)
    ├── multiplier (合约乘数)
    └── commission_rate (资产专用佣金，覆盖 StrategyConfig)
```

中国期货扩展配置位于 `BacktestConfig.china_futures`，用于管理前缀级规则：

- `instrument_templates_by_symbol_prefix`: 品种模板（乘数/保证金/tick/手数/费率）
- `fee_by_symbol_prefix`: 品种费率覆盖
- `validation_by_symbol_prefix`: 品种撮合校验开关覆盖
- `enforce_sessions`: 是否严格按交易时段控制成交
- `session_profile`: 中国期货会话模板（`CN_FUTURES_DAY`=`CN_FUTURES_COMMODITY_DAY` / `CN_FUTURES_CFFEX_STOCK_INDEX_DAY` / `CN_FUTURES_CFFEX_BOND_DAY` / `CN_FUTURES_NIGHT_23` / `CN_FUTURES_NIGHT_01` / `CN_FUTURES_NIGHT_0230`）

配置对象采用“构造即校验”：

- `symbol_prefix` 为空会直接报错
- 模板数值范围非法（如 `multiplier <= 0`）会直接报错
- 同一列表内前缀重复会报错并标注冲突项索引

#### 2. 参数优先级 (Priority)

`run_backtest` 函数的参数解析遵循以下优先级（由高到低）：

1.  **显式参数 (Explicit Arguments)**:
    *   直接传递给 `run_backtest` 的参数优先级最高。
    *   例如：`run_backtest(start_time="2022-01-01")` 会覆盖 `config.start_time`。
2.  **配置对象 (Config Objects)**:
    *   如果显式参数为 `None`，则从 `config` (`BacktestConfig`) 中读取。
    *   多策略字段可集中配置在 `config.strategy_config`（如 `strategy_id`、
        `strategies_by_slot`、`strategy_max_*`、`strategy_priority`、
        `strategy_risk_budget`、`portfolio_risk_budget`）。
3.  **默认值 (Defaults)**:
    *   如果上述两者都未提供，则使用系统默认值。

中国期货扩展（`BacktestConfig.china_futures`）推荐使用以下优先级口径：

| 配置项 | 高优先级 | 中优先级 | 默认值 |
|---|---|---|---|
| 合约参数（乘数/保证金/tick/手数） | `InstrumentConfig` 显式字段 | `instrument_templates_by_symbol_prefix` | `run_backtest` 默认参数 |
| 品种费率 | `fee_by_symbol_prefix` | 模板 `commission_rate` | `StrategyConfig.commission_rate` |
| 品种校验开关 | `validation_by_symbol_prefix` | 模板 `enforce_tick_size / enforce_lot_size` | 全局 `ChinaFuturesConfig.enforce_*` |
| 交易时段 | `china_futures.sessions` 显式配置 | `session_profile` 模板 | ChinaMarket 默认会话 |
| 市场路由 | `use_china_futures_market=False` 或混合资产回落 | `use_china_futures_market=True` 且纯期货 | `use_simple_market` |

口径说明：

*   同级规则冲突时，以显式规则覆盖模板规则。
*   撮合校验路径按更具体前缀优先（更长匹配优先）。

中国期权扩展配置位于 `BacktestConfig.china_options`，用于管理中国期权费率：

- `fee_per_contract`: 全局每张合约手续费
- `fee_by_symbol_prefix`: 按品种前缀覆盖每张合约手续费
- `use_china_market`: 是否切换到 ChinaMarket
- `sessions`: 可选时段覆盖（不与期货会话配置冲突时生效）

中国期权扩展推荐使用以下优先级口径：

| 配置项 | 高优先级 | 中优先级 | 默认值 |
|---|---|---|---|
| 期权费率（按张） | `fee_by_symbol_prefix` | `fee_per_contract` | `set_option_fee_rules` 默认配置 |
| 市场路由 | `use_china_market=True` | 混合资产时自动 ChinaMarket | `use_simple_market` |

期货 vs 期权配置能力对照：

| 能力维度 | 中国期货（`china_futures`） | 中国期权（`china_options`） |
|---|---|---|
| 路由开关 | `use_china_futures_market` | `use_china_market` |
| 全局费率 | `StrategyConfig.commission_rate` 或模板费率 | `fee_per_contract` |
| 前缀费率覆盖 | `fee_by_symbol_prefix` | `fee_by_symbol_prefix` |
| 合约参数模板 | 支持（乘数/保证金/tick/手数） | 不支持 |
| 撮合校验开关 | 支持（tick/手数，含前缀覆盖） | 不支持 |
| 会话覆盖 | 支持（`sessions`） | 支持（`sessions`） |
| 前缀匹配策略 | 更长前缀优先 | 更长前缀优先 |

股票配置推荐使用以下优先级口径：

| 配置项 | 高优先级 | 中优先级 | 默认值 |
|---|---|---|---|
| 股票费率（佣金/印花税/过户费/最低佣金） | `InstrumentConfig` 单标的费率字段 | `StrategyConfig` 全局费率字段 | `run_backtest` 内置默认值 |
| 交易单位（`lot_size`） | `InstrumentConfig.lot_size`（显式设置） | `run_backtest(lot_size=...)` 全局设置 | `1` |
| 市场制度（T+1） | `run_backtest(t_plus_one=...)` 显式参数 | `Engine.set_t_plus_one(...)` 引擎设置 | `False` |
| 市场模型 | `use_china_market()` | `use_simple_market()` | 引擎默认市场配置 |

股票侧说明：

*   当前股票没有按代码前缀的模板层（不像期货的 `china_futures` 前缀模板）。
*   生产场景建议优先用 `InstrumentConfig` 精确配置重点股票，再用 `StrategyConfig` 作为全局兜底。

#### 3. 风控配置合并 (Risk Config Merging)

`risk_config` 参数的处理逻辑比较特殊，旨在支持“基准配置 + 快速覆盖”的模式：

*   **基准**: 首先加载 `config.strategy_config.risk`（如果存在）。
*   **覆盖**: 如果提供了 `risk_config` 参数（字典或对象），它将覆盖基准配置中的同名字段。
    *   这允许你在不修改 Config 对象的情况下，通过 `run_backtest(..., risk_config={"max_position_pct": 0.5})` 快速调整风控参数进行测试。

#### 4. 策略运行时配置注入 (Strategy Runtime Config Injection)

`run_backtest` 与 `run_warm_start` 支持 `strategy_runtime_config` 参数：

*   支持 `StrategyRuntimeConfig` 对象或 `dict`。
*   用于在不修改策略类代码的前提下注入运行时行为开关。
*   示例：`run_backtest(..., strategy_runtime_config={"error_mode": "continue"})`。
*   校验行为：未知字段或非法值会快速失败，并给出字段级错误信息。
*   冲突处理：`runtime_config_override=True` 时应用外部配置；`False` 时保留策略侧配置。
*   上述冲突规则在 `run_backtest` 与 `run_warm_start` 中保持一致。
*   对同一策略实例、同一冲突内容，告警日志会自动去重。
*   优先级规则：显式传入的 `strategy_runtime_config` 参数高于转发配置映射中的同名配置。
*   故障速查入口：参考 [Runtime Config 指南](../advanced/runtime_config.md)。

```python
from akquant import StrategyRuntimeConfig, run_backtest

result = run_backtest(
    data=data,
    strategy=MyStrategy,
    strategy_runtime_config=StrategyRuntimeConfig(
        error_mode="continue",
        portfolio_update_eps=1.0,
    ),
)
```

#### 5. 最佳实践 (Best Practices)

*   **简单脚本**: 直接使用 `run_backtest` 的扁平参数（如 `initial_cash`, `start_time`）。
*   **生产/复杂策略**: 构建完整的 `BacktestConfig` 对象，以便于版本管理和复用。
*   **页面化参数输入**: 在策略类中声明 `PARAM_MODEL`（`akquant.ParamModel`），并使用 `get_strategy_param_schema` / `validate_strategy_params` 完成前后端参数联动与校验。
*   **参数调优**: 使用 `run_grid_search` 时，通常通过修改 Config 对象或传入 override 参数来实现。

## 2. 策略开发 (Strategy)

### `akquant.Strategy`

策略基类。用户应继承此类并重写回调方法。

**回调方法:**

*   `on_start()`: 策略启动时触发。用于订阅 (`subscribe`) 和注册指标。
*   `on_bar(bar: Bar)`: K 线闭合时触发。
*   `on_tick(tick: Tick)`: Tick 到达时触发。
*   `on_order(order: Order)`: 订单状态更新时触发（如成交、取消、拒绝）。
*   `on_trade(trade: Trade)`: 订单成交时触发。
*   `on_reject(order: Order)`: 订单首次进入 `Rejected` 时触发一次。
*   `on_expiry(event: Dict[str, Any])`: 到期结算回调。仅当引擎实际执行 `expiry_date` 驱动的到期结算/移除后触发；回调时账户状态已更新。示例见：`examples/49_on_expiry_demo.py`。
*   `on_session_start(session, timestamp)`: 会话切换开始时触发。
*   `on_session_end(session, timestamp)`: 会话切换结束时触发。
*   `on_before_trading(trading_date, timestamp)`: 每个本地交易日首次进入 Normal 会话时触发一次。
*   `on_pre_open(event: Dict[str, Any])`: 每个交易日首个常规行情事件前触发一次。适合“盘前决策，本次 open 成交”；默认下单语义会自动解析为 `price_basis=open, bar_offset=1, temporal=same_cycle`。示例见：`examples/52_pre_open_demo.py`。
*   `on_daily_rebalance(trading_date, timestamp)`: 交易日调仓钩子，每个交易日最多触发一次。
*   `on_after_trading(trading_date, timestamp)`: 离开 Normal 会话时触发；若先跨日则在下一事件补发。
*   `on_portfolio_update(snapshot)`: 账户快照变化时触发。
*   `on_error(error, source, payload=None)`: 用户回调抛异常时触发，默认触发后继续抛出。
*   `on_timer(payload: str)`: 定时器触发。
*   `on_stop()`: 策略停止时触发。
*   `on_train_signal(context)`: 滚动训练信号触发 (ML 模式)。

`on_pre_open` 推荐写法：

```python
def on_pre_open(self, event: Dict[str, Any]) -> None:
    signal = self.compute_pre_open_signal()
    if signal > 0:
        self.buy("000001", quantity=100)
```

说明：若这里不显式传 `fill_policy`，框架会默认按当日 `open` 语义处理订单。

**属性与快捷访问:**

*   `self.symbol`: 当前正在处理的标的代码。
*   `self.close`, `self.open`, `self.high`, `self.low`, `self.volume`: 当前 Bar/Tick 的价格和成交量。
*   `self.position`: 当前标的持仓辅助对象 (`Position`)，包含 `size` 和 `available` 属性。
*   `self.now`: 当前回测时间 (`pd.Timestamp`)。
*   `self.runtime_config`: 运行时行为配置对象 (`StrategyRuntimeConfig`)。
*   `self.enable_precise_day_boundary_hooks`: 是否启用边界定时器精确交易日钩子（默认 `False`）。
*   `self.portfolio_update_eps`: 账户快照更新阈值，低于该变化量不触发 `on_portfolio_update`（默认 `0.0`）。
*   `self.error_mode`: 错误处理模式，`"raise"` 或 `"continue"`（默认 `"raise"`）。
*   `self.re_raise_on_error`: 用户回调异常后是否继续抛出（默认 `True`）。
*   `self.ctx`: 策略上下文 (`StrategyContext`)，提供底层 API 访问。

**交易方法:**

*   `buy(symbol, quantity, price=None, trigger_price=None, ...)`: 买入（开多/平空）。
    *   如果不指定 `price`，则为市价单。
    *   如果指定 `price`，则为限价单。
    *   如果指定 `trigger_price`，则为止损/止盈单 (Stop Market)。
*   `sell(symbol, quantity, price=None, trigger_price=None, ...)`: 卖出（平多/开空）。参数同上。
*   `submit_order(..., order_type="StopTrail", trail_offset=..., trail_reference_price=None)`: 提交跟踪止损单。`trail_offset` 必须大于 0。
*   `submit_order(..., order_type="StopTrailLimit", price=..., trail_offset=..., trail_reference_price=None)`: 提交跟踪止损限价单。`price` 与 `trail_offset` 必填。
*   `submit_order(..., broker_options={...})`: 可选 broker 扩展参数透传（回测阶段仅记录在订单对象 `order.broker_options` 上，便于联调与审计）。
*   `place_trailing_stop(symbol, quantity, trail_offset, side="Sell", trail_reference_price=None, ...) -> str`: 跟踪止损助手，触发后按市价执行。
*   `place_trailing_stop_limit(symbol, quantity, price, trail_offset, side="Sell", trail_reference_price=None, ...) -> str`: 跟踪止损限价助手，触发后按限价执行。
*   `order_target_weights(target_weights, price_map=None, liquidate_unmentioned=False, allow_leverage=False, rebalance_tolerance=0.0, ...)`: 按多标的目标权重调仓。
    *   `target_weights` 形如 `{symbol: weight}`，默认要求权重和不超过 `1.0`。
    *   `liquidate_unmentioned=True` 时，会将未出现在目标字典中的现有持仓目标设为 `0`。
    *   执行顺序为先卖后买，减少现金约束导致的调仓失败。
    *   `rebalance_tolerance` 按组合市值比例跳过小偏差，降低无效换手。
*   `cancel_order(order_id: str)`: 撤销指定订单。
*   `cancel_all_orders(symbol)`: 取消指定标的的所有挂单。如果不指定 `symbol`，则取消所有挂单。
*   `create_oco_order_group(first_order_id, second_order_id, group_id=None) -> str`: 创建 OCO 订单组。组内任一订单成交后，另一订单会被自动撤单。
*   `place_bracket_order(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...) -> str`: 创建 Bracket 订单。先提交进场单，进场成交后自动提交止损/止盈；当止损与止盈同时存在时会自动绑定 OCO。

**数据与工具:**

*   `get_history(count, symbol, field="close") -> np.ndarray`: 获取历史数据数组 (Zero-Copy)。
*   `get_history_map(count, symbols, field="close") -> Dict[str, np.ndarray]`: 批量获取多个标的历史数据。
*   `rebalance_to_topn(scores, top_n, weight_mode="equal", ...) -> List[str]`: 根据打分选取 TopN 并执行调仓，支持等权或按分数归一化。
*   `get_history_df(count, symbol) -> pd.DataFrame`: 获取历史数据 DataFrame (OHLCV)。
*   `get_position(symbol) -> float`: 获取当前持仓量。
*   `get_available_position(symbol) -> float`: 获取可用持仓量。
*   `get_positions() -> Dict[str, float]`: 获取所有标的持仓。
*   `hold_bar(symbol) -> int`: 获取当前持仓持有的 Bar 数量。
*   `get_cash() -> float`: 获取当前可用资金。
*   `get_account() -> Dict[str, float]`: 获取账户详情快照。常见字段包括 `cash`、`equity`、`market_value`、`notional_value`、`frozen_cash`、`margin`、`used_margin`、`unrealized_pnl`、`borrowed_cash`、`short_market_value`、`maintenance_ratio`、`account_mode`、`accrued_interest`、`daily_interest`。
    *   现金账户 / 现货账户下，`market_value` 通常表示持仓市值。
    *   期货保证金账户下，`equity` 表示账户权益，`used_margin` 表示已占用保证金，`notional_value` 表示期货名义敞口，`unrealized_pnl` 表示浮动盈亏；期货持仓不会像股票那样把全额名义本金直接计入 `cash` 扣减，也不会把名义敞口直接映射为 `market_value`。
    *   在策略回调内，如果你只想读取“当前账户总权益”，优先使用 `get_portfolio_value()`；其口径与 `get_account()["equity"]` 对齐。
*   `get_order(order_id) -> Order`: 获取指定订单详情。
*   `get_open_orders(symbol) -> List[Order]`: 获取当前未完成订单列表。
*   `get_trades() -> List[ClosedTrade]`: 获取所有已平仓交易记录。
*   `subscribe(instrument_id: str)`: 订阅行情。
*   `log(msg: str, level: int)`: 输出带时间戳的日志。
*   `schedule(trigger_time, payload)`: 注册单次定时任务。
*   `add_daily_timer(time_str, payload)`: 注册每日定时任务。
*   `to_local_time(timestamp) -> pd.Timestamp`: 将 UTC 时间戳转换为本地时间。
*   `format_time(timestamp, fmt) -> str`: 格式化时间戳。

**标的静态属性 API（推荐）:**

*   `get_instrument(symbol) -> InstrumentSnapshot`: 获取单个标的静态属性快照。
*   `get_instruments(symbols=None) -> Dict[str, InstrumentSnapshot]`: 获取多个标的静态属性快照字典；`symbols=None` 时返回全部。
*   `get_instrument_field(symbol, field) -> Any`: 获取单个标的字段值。
*   `get_instrument_config(symbol, fields=None) -> Union[Any, Dict[str, Any], InstrumentSnapshot]`: 兼容接口；支持整对象、单字段或多字段读取。

说明：

*   这些接口在 `on_start` 即可使用（启动阶段已注入快照）。
*   推荐优先使用这些接口读取静态属性，而不是依赖 `bar.extra`。

**机器学习支持:**

*   `set_rolling_window(train_window, step)`: 设置滚动训练窗口。
*   `get_rolling_data(length, symbol)`: 获取滚动训练数据 (X, y)。
*   `prepare_features(df, mode)`: (需重写) 特征工程与标签生成。

### `akquant.Bar`

K 线数据对象。

*   `timestamp`: Unix 时间戳 (纳秒)。
*   `open`, `high`, `low`, `close`, `volume`: OHLCV 数据。
*   `symbol`: 标的代码。
*   `extra`: 扩展数据字典 (`Dict[str, float]`)。
*   `timestamp_str`: 时间字符串。

### `akquant.Tick`

Tick 数据对象。

*   `timestamp`: Unix 时间戳 (纳秒)。
*   `price`: 最新价。
*   `volume`: 成交量。
*   `symbol`: 标的代码。

### `akquant.live.LiveRunner`（broker_live 执行语义） {: #live-broker-semantics }

实盘 broker 路由可通过 `gateway_options` 传入网关特定参数：

```python
runner = LiveRunner(
    strategy_cls=on_bar,
    instruments=instruments,
    broker="ctp",
    trading_mode="broker_live",
    gateway_options={"execution_semantics_mode": "strict"},
)
```

`gateway_options.execution_semantics_mode`：

| 取值 | 默认值 | 行为 | 推荐场景 |
| :--- | :--- | :--- | :--- |
| `strict` | 是 | `Cancelled` / `Rejected` / `Filled` 等终态由订单回报 (`OnRtnOrder`) 最终确认。错误回报会先缓存拒单原因，再在后续订单回报中补齐。 | 生产实盘 |
| `compatible` | 否 | 在部分错误/撤单路径允许本地立即推进终态，以兼容历史行为。 | 迁移过渡 |

严格模式注意事项：

*   撤单请求发送成功不等于 `Cancelled`，需等待 `OnRtnOrder(Cancelled)`。
*   收到错误回报不等于 `Rejected`，最终状态以订单回报为准。

## 3. 核心引擎 (Core)

### `akquant.Engine`

回测引擎的主入口 (通常通过 `run_backtest` 隐式使用)。

**配置方法:**

*   `set_timezone(offset: int)`: 设置时区偏移。
*   `use_simulated_execution()` / `use_realtime_execution()`: 设置执行环境。
*   `set_fill_policy(price_basis, bar_offset, temporal)`: 设置统一三轴执行策略（推荐）。
*   `get_fill_policy()`: 获取当前三轴执行策略。
*   `set_history_depth(depth)`: 设置历史数据缓存长度。

**市场与费率配置:**

*   `use_simple_market()`: 启用简单市场。
*   `use_china_market()`: 启用中国市场 (股票)。
*   `use_china_futures_market()`: 启用中国期货市场。
*   `set_stock_fee_rules(commission, stamp_tax, transfer_fee, min_commission)`: 设置股票费率。
*   `set_futures_fee_rules(commission_rate)`: 设置期货费率。
*   `set_futures_fee_rules_by_prefix(symbol_prefix, commission_rate)`: 设置期货品种前缀费率。
*   `set_futures_validation_options(enforce_tick_size, enforce_lot_size)`: 设置期货撮合前校验开关。
*   `set_futures_validation_options_by_prefix(symbol_prefix, enforce_tick_size, enforce_lot_size)`: 设置期货品种前缀校验开关。
*   `set_fund_fee_rules(...)`: 设置基金费率。
*   `set_option_fee_rules(...)`: 设置期权费率。
*   `set_slippage(type, value)`: 设置滑点 (Fixed 或 Percent)。
*   `set_volume_limit(limit)`: 设置成交量限制 (如 0.1 表示不超过 Bar 成交量的 10%)。
*   `set_market_sessions(sessions)`: 设置交易时段。

命名约定说明：

*   期货费率接口统一使用复数命名 `set_futures_fee_rules*`。
*   旧单数命名 `set_future_fee_rules*` 已移除，不再对外暴露。

### `akquant.gateway` 自定义 Broker 注册

可通过注册表机制按名称接入自定义 broker，而无需修改内置工厂分支。

**注册表 API:**

*   `register_broker(name, builder)`: 注册 broker 构建函数。
*   `unregister_broker(name)`: 取消注册 broker。
*   `get_broker_builder(name)`: 查询 broker 构建函数。
*   `list_registered_brokers()`: 获取当前已注册 broker 列表。

**Builder 签名:**

```python
def builder(
    feed: DataFeed,
    symbols: Sequence[str],
    use_aggregator: bool,
    **kwargs: Any,
) -> GatewayBundle:
    ...
```

**示例:**

```python
from akquant import DataFeed
from akquant.gateway import create_gateway_bundle, register_broker

register_broker("demo", demo_builder)
bundle = create_gateway_bundle(
    broker="demo",
    feed=DataFeed(),
    symbols=["000001.SZ"],
)
```

## 4. 交易对象 (Trading Objects)

### `akquant.Order`

*   `id`: 订单 ID。
*   `symbol`: 标的代码。
*   `side`: `OrderSide.Buy` / `OrderSide.Sell`。
*   `order_type`: `OrderType.Market` / `OrderType.Limit` / `StopMarket` 等。
*   `status`: `OrderStatus.New` / `Filled` / `Cancelled` 等。
*   `quantity` / `filled_quantity`: 委托/成交数量。
*   `price`: 委托价格。
*   `average_filled_price`: 成交均价。
*   `trigger_price`: 触发价格。
*   `time_in_force`: 有效期 (`GTC`, `IOC`, `FOK`, `Day`)。
*   `created_at` / `updated_at`: 时间戳。
*   `tag`: 标签。
*   `reject_reason`: 拒绝原因。

### `akquant.Trade`

单次成交记录（一个订单可能对应多次成交）。

*   `id`: 成交 ID。
*   `order_id`: 对应订单 ID。
*   `symbol`: 标的代码。
*   `side`: 方向。
*   `quantity`: 成交数量。
*   `price`: 成交价格。
*   `commission`: 手续费。
*   `timestamp`: 成交时间。

### `akquant.ClosedTrade`

已平仓交易记录（开仓+平仓的完整周期）。

*   `entry_time` / `exit_time`: 开/平仓时间。
*   `entry_price` / `exit_price`: 开/平仓价格。
*   `quantity`: 数量。
*   `pnl`: 盈亏金额。
*   `return_pct`: 收益率。
*   `duration`: 持仓时间。
*   `mae` / `mfe`: 最大不利/有利变动。

## 5. 投资组合与风控 (Portfolio & Risk)

### `akquant.RiskConfig`

风控配置。

```python
@dataclass
class RiskConfig:
    active: bool = True
    safety_margin: float = 0.0001
    max_order_size: Optional[float] = None
    max_order_value: Optional[float] = None
    max_position_size: Optional[float] = None
    restricted_list: Optional[List[str]] = None
    max_position_pct: Optional[float] = None
    sector_concentration: Optional[Union[float, tuple]] = None

    # 账户级风控
    max_account_drawdown: Optional[float] = None
    max_daily_loss: Optional[float] = None
    stop_loss_threshold: Optional[float] = None
```

账户级字段说明：

*   `max_account_drawdown`: 最大回撤阈值（0~1 小数）。以历史权益峰值为基准，当前权益回撤超过阈值后，新的下单请求会被拒绝。
*   `max_daily_loss`: 单日亏损阈值（0~1 小数）。以当日首次风控检查时的权益为基准，当日亏损超过阈值后，新的下单请求会被拒绝。
*   `stop_loss_threshold`: 账户净值止损阈值（0~1 小数）。当当前权益低于“规则首次生效时权益 × 阈值”后，新的下单请求会被拒绝。

这些拒单原因会体现在 `orders_df.reject_reason` 字段中。

## 6. 结果分析 (Analysis)

### `akquant.BacktestResult`

回测结果对象。

**属性:**

*   `metrics_df`: 绩效指标表格 (Sharpe, Drawdown 等)。
*   `trades_df`: 所有平仓交易记录表格。
*   `orders_df`: 所有委托记录表格。
*   `executions_df`: 所有成交流水表格（优先使用 Rust IPC/dict 快速导出）。
*   `positions_df`: 每日持仓详情。
*   `equity_curve`: 权益曲线 (List[Tuple[timestamp, value]])。
*   `cash_curve`: 现金曲线 (List[Tuple[timestamp, value]])。
*   `margin_curve`: 保证金曲线 (List[Tuple[timestamp, value]])。
*   `equity_curve_daily`: 日频权益曲线（按日末值聚合）。
*   `cash_curve_daily`: 日频现金曲线（按日末值聚合）。
*   `margin_curve_daily`: 日频保证金曲线（按日末值聚合）。
*   `trades`: `ClosedTrade` 对象列表。
*   `executions`: `Trade` 对象列表 (所有成交流水)。
*   `snapshots`: 每日 `PositionSnapshot` 列表。

**分析方法:**

*   `exposure_df(freq="D")`: 组合暴露分解（净暴露、总暴露、杠杆）。
*   `attribution_df(by="symbol", use_net=True, top_n=None)`: 按 symbol/tag 做归因汇总。
*   `capacity_df(freq="D")`: 容量代理指标（订单数、成交率、换手）。
*   `orders_by_strategy()`: 按 `owner_strategy_id` 聚合订单统计。
*   `executions_by_strategy()`: 按 `owner_strategy_id` 聚合成交流水统计。
*   `get_event_stats()`: 返回流式事件统计摘要（如 `processed_events`、`dropped_event_count`、`callback_error_count`、`backpressure_policy`、`stream_mode`）。
*   `report(..., curve_freq="raw" | "D")`: 生成 HTML 报告时，可选原始频率或日频末值曲线。

```python
orders_by_strategy = result.orders_by_strategy()
executions_by_strategy = result.executions_by_strategy()

# 常用字段示例
# orders_by_strategy:
# - owner_strategy_id, order_count, filled_order_count,
#   ordered_quantity, filled_quantity, ordered_value, filled_value,
#   fill_rate_qty, fill_rate_value
#
# executions_by_strategy:
# - owner_strategy_id, execution_count, total_quantity,
#   total_notional, total_commission, avg_fill_price

event_stats = result.get_event_stats()
# 常见字段:
# - processed_events, dropped_event_count, callback_error_count,
#   backpressure_policy, stream_mode, reason
```
