# RQAlpha Gap Roadmap

This document tracks the remaining RQAlpha backtest capabilities that are not
yet fully aligned in `fidc-backtest-engine`, and the implementation order we
are following.

## Scope

This roadmap focuses on closing RQAlpha parity gaps in the production backtest
engine. The China A-share stock path is mostly aligned now; the remaining gaps
are concentrated in multi-account aggregation, futures matching/data/cost
integration, and advanced RQData-style helper APIs.

## Re-Audit Findings (2026-04-24)

The re-audit compared `fidc-backtest-engine` with the local RQAlpha source under
`/Users/boris/WorkSpace/rqalpha`, especially:

- `rqalpha/mod/rqalpha_mod_sys_simulation/matcher.py`
- `rqalpha/mod/rqalpha_mod_sys_simulation/simulation_broker.py`
- `rqalpha/mod/rqalpha_mod_sys_transaction_cost/deciders.py`
- `rqalpha/mod/rqalpha_mod_sys_accounts/position_model.py`
- `rqalpha/mod/rqalpha_mod_sys_risk/validators/*.py`
- `rqalpha/apis/api_base.py`
- `rqalpha/apis/api_rqdatac.py`

Confirmed aligned areas:

- Stock explicit order APIs, target order APIs, lot sizing, algo order styles,
  pending limit orders, cancellation, open order views, and final order lookup.
- Stock account and portfolio runtime fields including cash, frozen cash, total
  value, transaction cost, trading/position PnL, management fees, financing
  liability, deposit/withdraw, and position aliases.
- Scheduler, dynamic universe, subscription guard, `history_bars`,
  `current_snapshot`, `get_price`, instruments, trading-date APIs, suspension
  and ST helpers.
- Stock matching modes, slippage models, price/volume/liquidity limits, open
  auction handling, and partial fill handling in the stock broker path.
- Standalone futures account, long/short position model, open/close,
  close-today/close-yesterday, daily mark-to-market settlement, expiration
  settlement, and runtime account views.

Remaining parity gaps found by this pass:

| Priority | Gap | RQAlpha capability | Current engine state | Next implementation |
| --- | --- | --- | --- | --- |
| P0 | Futures intraday matching | Bar/tick matchers support futures orders through the same broker lifecycle, matching type, slippage, price limit, liquidity limit, volume limit, partial fill, and market-close rejection semantics. | Futures orders execute immediately from `FuturesOrderIntent` with explicit price and cost; they do not flow through the stock broker's pending/open-order matcher. | Add a futures broker/matcher path or generalize `BrokerSimulator` so futures intents can be market/limit/algo orders matched by bar/tick/open auction data. |
| P0 | Futures open-order lifecycle | `SimulationBroker` keeps pending orders, supports `get_open_orders`, cancellation, before-trading activation, tick/bar rematching, and after-trading rejection. | Stock orders have open-order lifecycle; futures orders only emit immediate process/order/fill events. | Add futures pending limit orders, cancellation by id/symbol/all, open-order views, final order lookup, and market-close rejection. |
| P0 | Combined multi-account NAV | RQAlpha portfolio aggregates account values across stock/future accounts. | `StrategyContext.accounts()` exposes both account views, but `DailyEquityPoint`, progress events, metrics, and holdings summary are still stock-portfolio based. | Add aggregate portfolio valuation that includes stock total equity plus futures account total value/margin/PnL, then compute metrics and progress from aggregate NAV. |
| P1 | Futures trading parameter data source | RQAlpha loads contract multiplier, margin ratios, commission type, open/close/close-today commission ratios, settlement/prev-settlement, tick size, listed/de-listed dates, and dominant contracts from data proxy. | `FuturesContractSpec` and `transaction_cost` are passed manually in order intents; there is no data-source-backed trading-parameter resolver. | Add futures instrument/trading-parameter tables and resolver APIs, then let order creation derive spec, margin, tick size, settlement price, and costs automatically. |
| P1 | Futures transaction cost decider | RQAlpha supports by-money/by-volume futures commission with separate open, close, and close-today rates and a commission multiplier. | Current futures execution accepts precomputed transaction cost and stores it; it does not calculate costs from contract metadata. | Implement `FuturesTransactionCostModel` backed by trading parameters and route all futures executions through it. |
| P1 | Futures settlement price mode | RQAlpha can settle futures by `settlement` or `close`, including previous-settlement fields. | Current daily settlement accepts an injected settlement price map and expiration schedule; it does not automatically read settlement/prev_settlement series. | Extend data model with `settlement` and `prev_settlement` fields and support a configurable settlement price mode. |
| P1 | Frontend risk validators for futures | RQAlpha applies cash/margin, position closable, price-limit, trading-status, and self-trade validators before order submission. | Stock path has comparable guardrails; futures margin/position checks exist inside account execution, but submission-time validators and self-trade checks are incomplete. | Add futures-aware validator layer before order acceptance and share diagnostics with order events. |
| P2 | RQData helper APIs | RQAlpha exposes `get_dividend`, `get_split`, `get_yield_curve`, `get_factor`, `get_margin_stocks`, `get_securities_margin`, `get_dominant_future`, and dominant futures price APIs. | Core stock backtest APIs are implemented; these advanced helper APIs are not exposed by `StrategyContext`/DSL. | Add read-only data proxy methods first, then expose stable DSL/strategy functions where data is available. |
| P2 | Analyzer/report parity | RQAlpha analyser can export richer trades, positions, benchmark, monthly returns, risk, and summary artifacts. | Engine returns metrics, equity curve, orders/fills/events/holdings, but not a full RQAlpha-style analyser artifact set. | Add normalized report builders on top of `BacktestResult` without changing execution semantics. |
| P3 | Mod/config/plugin architecture | RQAlpha has pluggable mods, event bus extension points, and many config toggles. | Engine has explicit Rust config and event/process records, not a full mod framework. | Only implement toggles required by production strategies; avoid recreating the whole RQAlpha mod system unless needed. |

## Remaining Gaps

### Phase 1: Strategy API parity

- [x] `order_to` / target-shares style explicit order primitive
- [x] `order_target_portfolio(_smart)` style public API surface
- [x] richer explicit order styles exposed to platform scripts

### Phase 2: Scheduling and execution surface

- [x] minute-level `time_rule` semantics like `market_open`, `market_close`,
      `physical_time`
- [x] finer `1m` / `tick` strategy execution entrypoints beyond `open_auction`
      and `on_day`
- [x] scheduled actions evaluated against explicit intraday times

### Phase 3: Universe and subscription model

- [x] `update_universe`
- [x] `subscribe`
- [x] `unsubscribe`
- [x] tick-frequency subscription guards exposed at strategy API level

### Phase 4: Algo order parity

- [x] `VWAPOrder` first-class explicit action parity (`order.vwap_value/percent`)
- [x] `TWAPOrder` first-class explicit action parity (`order.twap_value/percent`)
- [x] `order_target_portfolio_smart(..., order_prices=AlgoOrder, valuation_prices=...)`

### Phase 5: Position accounting parity

- [x] `trading_pnl`
- [x] `position_pnl`
- [x] `dividend_receivable`
- [x] richer position lifecycle fields exposed to strategy runtime
- [x] RQAlpha-style stock position aliases (`order_book_id`, `avg_price`,
      `sellable`, `closable`, `equity`, `position_prev_close`)

### Phase 6: Strategy data API parity

- [x] `history_bars` numeric helper for daily, intraday, and tick fields
- [x] `current_snapshot`
- [x] `instrument` / `instruments` / `all_instruments`
- [x] `get_trading_dates` / `get_previous_trading_date` /
      `get_next_trading_date`
- [x] phase-aware minute/tick history cursor semantics matching the active
      bar or tick callback

### Phase 7: Remaining stock data-source API parity

- [x] `is_suspended`
- [x] `is_st_stock`
- [x] `get_price` style date-range tabular API
- [x] `active_instruments`
- [x] `instruments_history`

### Phase 8: Order object API parity

- [x] open-order status and unfilled quantity exposed to strategy runtime
- [x] final order object lookup by order id
- [x] order average fill price and transaction cost aggregation

### Phase 9: Account / portfolio API parity

- [x] stock-account runtime view (`ctx.account()` / `ctx.portfolio_view()`)
- [x] `cash`, `available_cash`, `frozen_cash`, `market_value`, `total_value`
      exposed to strategy runtime and DSL
- [x] `unit_net_value`, `static_unit_net_value`, `daily_pnl`,
      `daily_returns`, `total_returns`, `transaction_cost`, `trading_pnl`,
      and `position_pnl` exposed to strategy runtime and DSL
- [x] explicit deposit / withdraw API
- [x] financing liability / repay API
- [x] management-fee rate and callback parity
- [x] stock account map/accessor surface (`accounts`, `stock_account`,
      `account_by_type("STOCK")`)
- [x] standalone futures account model with contract multiplier, long/short
      margin, daily mark-to-market settlement, and short close cashflow
- [x] standalone futures order execution model with open, close, close-today,
      close-yesterday, margin rejection, order/fill/position/account events
- [x] wire futures account runtime view into `BacktestEngine` and
      `StrategyContext` (`future_account`, `account_by_type("FUTURE")`,
      `accounts`)
- [x] wire futures order intents into the generic `BacktestEngine` execution
      loop for account-level open/close execution
- [x] standalone futures expiration settlement closes all long/short contract
      positions at settlement price
- [x] data-driven futures expiration schedule in `BacktestEngine` settlement
      phase
- [ ] futures intraday matching integration
- [ ] futures pending/open-order lifecycle and cancellation parity
- [ ] aggregate multi-account NAV/metrics/progress across stock and futures
- [ ] futures trading-parameter data source and automatic cost/margin resolver
- [ ] futures settlement/prev-settlement data integration and settlement mode
- [ ] futures-aware submission validators and self-trade checks

### Phase 10: Advanced data API parity

- [ ] `get_dividend`
- [ ] `get_split`
- [ ] `get_yield_curve`
- [ ] `get_factor`
- [ ] `get_margin_stocks`
- [ ] `get_securities_margin`
- [ ] `get_dominant_future`
- [ ] futures dominant price helpers

### Phase 11: Analyzer / report parity

- [ ] RQAlpha-style normalized trades report
- [ ] RQAlpha-style normalized positions report
- [ ] benchmark / monthly returns / risk summary artifacts
- [ ] downloadable analyser output bundle

## Execution Order

1. Close the explicit order API gap with target-shares / `order_to` parity.
2. Add public batch target-portfolio semantics.
3. Expand scheduler to intraday time rules.
4. Add dynamic universe APIs.
5. Add algo-order styles.
6. Finish position accounting parity.
7. Continue stock data-source API parity.
8. Continue order object API parity.
9. Continue account / portfolio API parity.
10. Add aggregate multi-account NAV and metrics so futures affects reported
    performance.
11. Add futures intraday matcher and pending-order lifecycle.
12. Add futures trading-parameter resolver, transaction-cost decider, and
    settlement-price integration.
13. Add advanced RQData helper APIs where source data exists.
14. Add analyser/report artifact parity.

## Current Step

Active implementation target: close the P0 gaps found by the 2026-04-24
re-audit. The next code target should be aggregate multi-account NAV/metrics,
followed by futures intraday matching and futures pending-order lifecycle.