# Backtest Framework Design (M3 Deliverable)

**版本**: v1.0  
**日期**: 2025-10-09  
**负责人**: Research / Quant Engineering  
**依赖文档**: `IMPLEMENTATION_PLAN.md`, `TESTING_PLAN.md`, `M16_INCREMENTAL_GRID_DESIGN.md`

---

## 1. 背景

M3 阶段要求支持参数回放与敏感性测试，以验证网格/剥头皮策略在不同市场环境下的表现，并作为金丝雀流程的一部分。当前仅有轻量级 replay 工具，缺乏系统化框架。

---

## 2. 功能目标

1. **Event Replay**：消费历史行情（book trades）与交易日志，复用生产策略逻辑。  
2. **Latency Injection**：基于实盘观测的延迟分布，在回测中注入下单/撤单延迟。  
3. **Fee / Funding / Slippage 模型**：准确反映成本、资金费率与滑点。  
4. **Parameter Sweep**：支持 Grid/MicroScalper 参数的网格或随机搜索。  
5. **报告与可视化**：生成 EV、Sharpe、回撤、成交桶等指标，方便对比。  
6. **可插拔**：可在 CI 或研究环境运行，允许仅回测部分模块。

---

## 3. 架构概览

```
┌──────────────────────────┐
│ BacktestRunner            │
│  - loadScenario()         │
│  - run()                  │
│  - generateReport()       │
├───────────┬──────────────┤
│ DataFeed  │ LatencyModel │
└────┬──────┴───────┬──────┘
     │              │
  MarketAdapter  ExecutionAdapter
     │              │
┌────▼─────┐   ┌────▼─────┐
│Strategy  │   │Connector │(mock)
│(Grid/MM) │   │(REST/WS) │
└──────────┘   └──────────┘
```

- `BacktestRunner`： orchestrate 数据加载、策略执行、结果收集。  
- `DataFeed`：抽象行情来源，支持 JSON、Parquet、Kafka snapshot。  
- `LatencyModel`：针对下单/撤单/成交回报注入延迟。  
- `ExecutionAdapter`：Mock Pacifica 连接器，遵循真实接口。  
- `MetricsCollector`：聚合指标并输出报告。

---

## 4. 模块设计

### 4.1 BacktestRunner

```ts
interface ScenarioConfig {
  name: string;
  start: string;  // ISO timestamp
  end: string;
  symbol: string;
  strategyConfig: GridConfig | ScalperConfig;
  latencyProfile: LatencyProfile;
  feeModel: FeeModelConfig;
  fundingModel: FundingModelConfig;
}
```

主要方法：
- `loadScenario(config: ScenarioConfig)`: 初始化 DataFeed/Adapters/Strategy。  
- `run()`: 按时间顺序驱动事件；支持加速（跳帧）与实时模式。  
- `generateReport()`: 输出 JSON + Markdown + 可选 CSV，包含指标。

### 4.2 DataFeed

接口：
```ts
interface DataFeed {
  next(): Promise<Event | null>;
  peekTime(): number | null;
  reset(): Promise<void>;
}
```

事件类型：
- `BookSnapshot`, `BookDelta`, `Trade`, `FundingUpdate`, `CustomSignal`。  
- 支持多 source：本地文件、S3、Kafka（通过 iterator 抽象）。  
- 为保证复现性，所有事件带有严格的 timestamp。

### 4.3 ExecutionAdapter (Mock)

实现 `OrderRouterDispatchFn`, `CancelFn` 等接口，模拟交易所行为：
- 接受订单 → 记录到队列 → 根据 LatencyModel + SlippageModel 生成成交或 partial fill。  
- 支持限价与 IOC，post-only 校验由策略层完成。  
- 记录真实下单时间与成交时间，用于衡量延迟影响。

### 4.4 LatencyModel

定义：
```ts
interface LatencyModel {
  orderSubmitDelay(): number;    // ms
  cancelDelay(): number;
  fillDelay(): number;
}
```

实现方式：
- **HistogramModel**：读取实盘指标（Prometheus/Humio），以 P50/P95/P99 构建分布。  
- **Config-based**：允许手动指定常量或离散分布。  
- 支持按照时间片（白天/夜间）加载不同 profile。

### 4.5 Fee & Funding Model

```ts
interface FeeModel {
  makerFeeBps: number;
  takerFeeBps: number;
  rebateBps: number;
  calc(order: Order, fill: Fill): number; // 返回费用（USD）
}

interface FundingModel {
  getFundingRate(ts: number): number;   // annualized
  settle(position: Position, ts: number): number;
}
```

- Funding 可以读取外部 CSV 或 API；若缺失则使用固定费率。  
- Slippage 模型（可选）：基于订单簿深度估算滑点。

### 4.6 MetricsCollector

输出指标（JSON/CSV/Markdown）：
- `pnl_total`, `pnl_fee`, `pnl_funding`, `pnl_slippage`  
- `ev_bps`, `sharpe`, `sortino`, `max_drawdown`  
- `fill_count`, `fill_interval_stats`, `hedge_cost_bps`  
- Bucket 报告（按小时/volatility/OBI 分类）  
- 图表：`delta_abs` vs time, EV 累计曲线。

---

## 5. 参数搜索

### 5.1 接口

```ts
interface ParameterSweep {
  run(scenarios: ScenarioConfig[], params: ParameterGrid): Promise<SweepResult>;
}
```

- `ParameterGrid`: 数组或 ranges；支持顺序/随机。  
- 结果保存 best N 配置（EV/Sharpe 排序），并输出数据表。  
- 可集成到 CLI：`pnpm backtest --scenario btc-vol-shock --grid grid.yaml --param sweep.yaml`.

---

## 6. 数据格式

- 标准输入格式：  
  - `books/{date}/{symbol}.parquet`  
  - `trades/{date}/{symbol}.parquet`  
  - 文件包含 timestamp、price、size、side。  
- Runner 接受 JSON/Parquet；对大型数据集建议使用 Parquet + Arrow stream。  
- 需提供转换脚本（如 `scripts/export-from-humio.ts`）。

---

## 7. 集成与兼容

- 生产代码抽象：策略/Router/Hedge 等必须通过接口调用，避免直接访问网络。  
- Backtest 使用同一 `config.yaml`（或子集），支持在 `ScenarioConfig` 中覆盖参数。  
- 可选：支持“实时回放”模式，用于边跑边可视化或用于 demo。

---

## 8. 测试计划

1. 单元测试：数据源迭代、latency model、fee model。  
2. 集成测试：使用小样本（1 小时）验证指标与手工计算一致。  
3. 回归：与实盘日志对比（同一时间窗口），结果误差需在 ±5%。  
4. 性能：30 天数据在 30 分钟内跑完（视硬件可调整）。  
5. CI：运行最小场景（10 分钟数据）作为 smoke test。

---

## 9. 时间规划

- Week 1：框架骨架 + DataFeed + ExecutionAdapter + LatencyModel。  
- Week 2：Fee/Funding 模型、MetricsCollector、参数搜索、测试。  
- Week 3：文档与示例脚本、与策略团队对接、金丝雀回放。  
- 持续：接入真实数据源、优化性能、增加可视化。

---

## 10. 交付物

- `packages/backtest/`（新 package）  
- CLI：`pnpm backtest --config backtest/btc_micro.yaml`  
- 示例配置：`backtest/scenarios/btc-vol-shock.yaml`  
- 指南：`docs/BACKTEST_USAGE.md`（未来撰写）  
- GitHub Action：运行 smoke backtest 并上传报告。
