fidc-backtest-engine/docs/rqalpha-gap-roadmap.md

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.

Parity gaps found by this pass and current closure state:

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.	Closed for daily/open/close and tick-price futures fills, including limit checks and partial quantity handling. Full order-book-depth counterparty sweeping remains out of scope unless production strategies require it.	Keep extending matching detail only when real futures tick depth data is available.
P0	Futures open-order lifecycle	SimulationBroker keeps pending orders, supports get_open_orders, cancellation, before-trading activation, tick/bar rematching, and after-trading rejection.	Closed for futures pending limit orders, cross-day rematching, cancellation by id/symbol/all, and merged open-order runtime views.	Add more order status transitions only if UI requires RQAlpha's exact intermediate event names.
P0	Combined multi-account NAV	RQAlpha portfolio aggregates account values across stock/future accounts.	Closed. DailyEquityPoint, progress events, and metrics now use aggregate stock + futures initial cash and total equity.	None.
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.	Closed for engine-side trading-parameter ingestion/resolution via futures_trading_parameters.csv or component data.	Add more exchange metadata columns only when source data exposes them.
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.	Closed. FuturesTransactionCostModel calculates by-money/by-volume open/close/close-today costs from trading parameters.	None.
P1	Futures settlement price mode	RQAlpha can settle futures by settlement or close, including previous-settlement fields.	Closed. Engine supports configurable settlement price mode and resolves settlement/prev-settlement from factor fields with close/prev_close fallback.	Add dedicated settlement columns if the storage layer later separates them from factors.
P1	Frontend risk validators for futures	RQAlpha applies cash/margin, position closable, price-limit, trading-status, and self-trade validators before order submission.	Closed for zero quantity, invalid limit price, self-trade crossing risk, paused/no executable price, price-limit, margin, and close-position rejection diagnostics.	Add exchange-specific validators only as needed.
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.	Closed. These APIs are available through DataSet and StrategyContext, using existing corporate-action, factor, market, and futures-parameter data.	Wire any missing frontend DSL aliases separately if the script layer needs them.
P2	Analyzer/report parity	RQAlpha analyser can export richer trades, positions, benchmark, monthly returns, risk, and summary artifacts.	Closed for normalized trades, positions, equity curve, benchmark series, metrics, and JSON report bundle via BacktestResult::analyzer_report(_json).	UI/service download endpoints can serialize this report directly.
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

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

Phase 2: Scheduling and execution surface

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

Phase 3: Universe and subscription model

• update_universe
• subscribe
• unsubscribe
• tick-frequency subscription guards exposed at strategy API level

Phase 4: Algo order parity

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

Phase 5: Position accounting parity

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

Phase 6: Strategy data API parity

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

Phase 7: Remaining stock data-source API parity

• is_suspended
• is_st_stock
• get_price style date-range tabular API
• active_instruments
• instruments_history

Phase 8: Order object API parity

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

Phase 9: Account / portfolio API parity

• stock-account runtime view (ctx.account() / ctx.portfolio_view())
• cash, available_cash, frozen_cash, market_value, total_value exposed to strategy runtime and DSL
• 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
• explicit deposit / withdraw API
• financing liability / repay API
• management-fee rate and callback parity
• stock account map/accessor surface (accounts, stock_account, account_by_type("STOCK"))
• standalone futures account model with contract multiplier, long/short margin, daily mark-to-market settlement, and short close cashflow
• standalone futures order execution model with open, close, close-today, close-yesterday, margin rejection, order/fill/position/account events
• wire futures account runtime view into BacktestEngine and StrategyContext (future_account, account_by_type("FUTURE"), accounts)
• wire futures order intents into the generic BacktestEngine execution loop for account-level open/close execution
• standalone futures expiration settlement closes all long/short contract positions at settlement price
• 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: P0-P2 parity items are implemented in the engine core. Remaining future work should be driven by concrete production strategy or UI requirements rather than recreating RQAlpha's full plugin/mod framework.