diff --git a/docs/rqalpha-gap-roadmap.md b/docs/rqalpha-gap-roadmap.md index f2f92e5..0254c4d 100644 --- a/docs/rqalpha-gap-roadmap.md +++ b/docs/rqalpha-gap-roadmap.md @@ -6,9 +6,54 @@ are following. ## Scope -This roadmap focuses on the China A-share stock backtest path first. Multi-asset -coverage such as futures/options is tracked separately and is not part of the -current alignment pass. +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 @@ -99,6 +144,29 @@ current alignment pass. - [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 @@ -111,12 +179,16 @@ current alignment pass. 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: continue account parity after exposing the stock -account runtime view, core Portfolio fields, deposit/withdraw, financing -liability APIs, management-fee callbacks, stock account accessors, and the -standalone futures account/order execution model plus generic engine runtime -account visibility and account-level futures order intents; next gap is adding -futures intraday matching semantics. +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.