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.

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

• 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: 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.