# fidc-backtest-engine

面向中国 A 股和期货策略的 Rust 回测核心。仓库目标是提供平台自有的策略 DSL、执行模型、撮合模型和结果分析能力，最终由 `fidc-backtest-service` 对外提供策略运行服务。

## 当前能力

- 日频、分钟、tick 级策略生命周期与确定性回放。
- A 股行情、估值、因子、基准、候选资格、涨跌停触达、停牌和 ST 标记。
- 平台策略 DSL 与 `StrategyContext` 数据 API，不暴露非平台脚本语法。
- `BacktestConfig` 支持起止日期、初始资金、决策滞后、执行价格字段、基准代码。
- `DailyMarketSnapshot` 支持 `open/close/last/day_open/prev_close/upper_limit/lower_limit`。
- Universe 选择器支持动态市值带、排序、Top-N、动态订阅和策略内更新。
- A 股规则钩子支持 T+1、停牌、涨停不可买、跌停不可卖、整手和最小下单量。
- Broker 支持目标权重、显式金额、目标股数、限价、VWAP/TWAP、挂单、撤单和订单查询。
- 期货账户支持多空持仓、开平仓、今昨仓、保证金、手续费、结算和到期处理。
- 报告输出支持权益曲线、成交、持仓、月度收益、风险指标、基准序列和 JSON 分析包。
- 内置 `OmniMicroCapStrategy`，覆盖动态市值带、均线过滤、止损止盈、固定频率再平衡和盘中执行近似。

## Workspace 布局

```text
.
├── Cargo.toml
├── crates
│   ├── bt-demo
│   └── fidc-core
│       └── src
│           ├── broker.rs
│           ├── calendar.rs
│           ├── cost.rs
│           ├── data.rs
│           ├── engine.rs
│           ├── futures.rs
│           ├── platform_expr_strategy.rs
│           ├── portfolio.rs
│           ├── rules.rs
│           ├── scheduler.rs
│           ├── strategy.rs
│           └── strategy_ai.rs
├── data/demo
└── docs
```

## 核心模块

- `calendar`: 交易日历、交易日滚动和调度日期工具。
- `instrument`: 证券和合约静态定义。
- `data`: 行情、因子、基准、候选资格、公司行为、盘口和期货交易参数数据模型。
- `universe`: 动态市值带和预排序候选集。
- `portfolio`: 股票账户现金、持仓、可卖数量、盈亏、分红应收和资金流水。
- `futures`: 期货账户、合约参数、保证金、手续费和多空持仓。
- `rules`: 中国市场交易规则和风控校验。
- `broker`: 股票撮合、订单簿、滑点、成交量约束、限价和显式订单执行。
- `scheduler`: 日、周、月、分钟、tick 调度规则。
- `platform_expr_strategy`: 平台 DSL 解析后的表达式策略执行模型。
- `strategy`: 策略 trait、内置策略和运行时视图。
- `strategy_ai`: 策略 AI 手册、提示词生成和数据库字段目录合并。
- `engine`: 回测主循环、事件发布、报告和指标汇总。

## 平台策略模型

策略代码不直接运行 Python 或非平台 API，而是被解析为平台自有的策略 spec。执行链路是：

1. 页面编辑平台 DSL。
2. spec 生成器解析变量、函数、选股、排序、风控、资金分配和显式订单。
3. 回测引擎按交易日和调度事件构造 `StrategyContext`。
4. 策略返回 `StrategyDecision` 或显式订单动作。
5. Broker、规则钩子和账户模型完成撮合、费用、持仓和权益更新。
6. Analyzer 输出标准化结果供服务和前端展示。

平台 DSL 支持：

- `strategy("name") { ... }` 策略入口。
- `let` 自定义参数和 `fn` 自定义函数。
- `when / unless / else` 条件块。
- `selection.market_cap_band(...)` 动态市值带。
- `filter.stock_expr(...)` 任意指标、因子和组合选股。
- `ordering.rank_by(...)` 与 `ordering.rank_expr(...)` 排序。
- `allocation.buy_scale(...)` 动态买入资金比例。
- `risk.stop_loss(...)`、`risk.take_profit(...)` 多条件止盈止损。
- `order.*`、`cancel.*`、`update_universe(...)`、`subscribe(...)` 显式交易动作。

任意数据库指标和自定义因子通过 `factor("field")`、`factor_value("field", lookback)`、`rolling_mean("field", n)`、`sma("close", n)` 等函数读取。未预计算的均线窗口可在回测中按已有历史数据实时计算。

## 内置微盘策略

`OmniMicroCapStrategy` 是平台内置的微盘轮动策略，用于 demo、性能验证和策略迁移基线：

1. 使用 `benchmark_signal_symbol` 的同日决策价格计算指数信号。
2. 按 `(index_level - base_index_level) * xs + base_cap_floor` 计算动态市值带。
3. 在预排序 eligible universe 中按市值区间截取候选。
4. 过滤停牌、ST、退市、科创板、一元股、涨停、跌停和不可买卖标记。
5. 使用个股短中长均线过滤。
6. 支持止损、止盈、定期再平衡和替补买入。
7. 默认按 10:18 附近的平台调度快照近似盘中决策，并使用 `last_price` 或配置的盘口价格执行。

## 运行方式

默认运行仓库 demo 数据：

```bash
cargo run --bin bt-demo
```

运行平台内置微盘策略：

```bash
FIDC_BT_STRATEGY=omni-microcap \
FIDC_BT_SIGNAL_SYMBOL=000001.SH \
cargo run --release --bin bt-demo
```

接入真实分区 snapshot 目录：

```bash
FIDC_BT_DATA_LAYOUT=partitioned \
FIDC_BT_DATA_DIR=/path/to/snapshots \
FIDC_BT_SIGNAL_SYMBOL=000001.SH \
cargo run --bin bt-demo
```

约定目录结构：

```text
snapshots/
├── instruments.csv
├── benchmark/YYYY/MM/*.csv
├── market/YYYY/MM/*.csv
├── factors/YYYY/MM/*.csv
└── candidates/YYYY/MM/*.csv
```

运行后默认生成：

- `output/demo/equity_curve.csv`
- `output/demo/trades.csv`
- `output/demo/holdings_summary.csv`

## 测试与构建

```bash
cargo fmt
cargo test
cargo build
```