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, tick-price futures fills, and true multi-level order-book sweeping when optional order_book_depth data exists. L1-only data still uses the existing L1 matcher and is not inflated into fake depth.	Extend depth fields only if production vendors expose more levels or exchange-specific fields.
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, active-contract, trading-phase, tick-aligned limit price, price-limit, self-trade crossing risk, paused/no executable price, margin, and close-position rejection diagnostics. These submission validators are controlled by FuturesValidationConfig so service-level callers can relax individual checks for compatibility tests or vendor-specific rules.	Add more exchange metadata columns only when source data exposes them.
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; platform expressions also expose focused helpers such as dividend_cash, factor_value, yield_curve, is_margin_stock, dominant_future, and dominant_future_price.	Add more DSL aliases only when users need specific names.
P2	Analyzer/report parity	RQAlpha analyser can export richer trades, positions, benchmark, monthly returns, risk, and summary artifacts.	Closed for normalized trades, positions, monthly returns, risk summary, 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.	Closed for a lightweight engine-native model: BacktestProcessMod, BacktestProcessModLoader, enabled-name installation, and event-bus lifecycle hooks. It intentionally avoids RQAlpha's Python global mod loader.	Add concrete production mods/toggles as requirements appear.

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
• configurable futures active-contract, trading-phase, price-tick, and price-limit submission validators
• optional true multi-level futures order-book depth data and sweep matching

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
• platform DSL helper aliases for advanced RQData-style APIs

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

Phase 12: Lightweight mod / extension parity

• event-bus process listeners
• installable BacktestProcessMod extension hook
• BacktestProcessModLoader with enabled-name installation
• Python RQAlpha-style global mod loader, intentionally out of scope unless we need Python plugin compatibility

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.
15. Add lightweight process-mod extension hooks; only add concrete mods when production needs them.

Current Step

Active implementation target: P0-P2 parity items are implemented in the engine core, and P3 now has a lightweight event-driven extension loader. Remaining future work should be driven by concrete production strategy or UI requirements, especially optional vendor-specific depth fields, additional exchange metadata columns, or exact UI-required RQAlpha intermediate event names.