策略快照、啓動門禁與長期可觀測（5-A / 5-B / 5-C）

親愛的用戶，本章介紹三項**進階**能力：策略運行前的**數據快照**、開盤前的**啓動門禁**、以及長跑時的**對賬與日誌**。若您尚未跑通基礎 live，請先閱讀 模擬實盤：配置與運行。

> 本章解決什麼問題 > 分鐘級策略若在每一步都重複拉數據，既慢又容易缺行情；開盤前若配置或數據未就緒就下單，風險大。我們把這些檢查做成可配置機制，並在日誌裏留痕，便於您覆盤。

內部代號對照（維護者/冒煙文檔會用到）

在 qteasy live 演進中，5-A / 5-B / 5-C 分別指策略快照、啓動門禁與長期可觀測三類能力。冒煙文檔與維護者筆記會使用代號；作爲用戶，您只需記住右側「用戶向名稱」即可。下表建立代號與日常說法的對應關係——閱讀本章後文時，可將「5-B」理解爲「啓動門禁」。

各列含義：**代號**爲內部階段編號；**用戶向名稱**爲文檔推薦叫法；**一句話**爲該能力在 live 鏈路中的位置。

如何使用：看到正文出現 5-A 等代號時查本表；配置鍵名稱見 模擬實盤：配置與運行 §4「策略快照」「啓動門禁」行。

代號

用戶向名稱

一句話

5-A

策略快照

策略運行前預先拉好數據，本步複用，減少重複 IO

5-B

啓動門禁

開盤/run 前檢查就緒狀態，失敗可告警或阻斷

5-C

長期可觀測

訂單與券商號映射、risk 日誌輪換、對賬與在途單診斷

5-A：策略快照（prepare_strategy_snapshot）

您可以把它理解爲：每次策略要「上考場」前，先把試卷和材料在案頭擺好；真正答題時不再臨時跑去列印室。

  • 當 live_trade_split_strategy_prepare=True 時，qteasy 會在每個 run_strategy 計劃時刻**之前**插入 prepare_strategy_snapshot 任務（提前量由 live_trade_prepare_lead_seconds 控制；0 表示同刻入隊，但排序仍保證先 prepare）。

  • prepare_strategy_snapshot 內完成原先 run_strategy 前的重活：子日頻數據刷新、準備數據緩衝、更新 live 價、注入過程數據等；完成後在內存留下「快照有效」標記（交易日 + 步序號 + 時間）。

  • 隨後 run_strategy 若發現快照仍在 live_trade_strategy_snapshot_max_age_seconds 內且步序號一致，則**不再重複**上述拉取；否則記 snapshot_missing / snapshot_stale 並**跳過本步策略**（避免用過期數據算信號）。

  • 開啓 split 時，prepare_strategy_snapshot 與 run_strategy 在**主線程同步**執行（與異步拉 live 價的任務分離），避免多線程同時碰 Operator。

與真實行爲的差異：快照在內存中，進程重啓後需重新 prepare；不是磁盤上的永久緩存。

5-B：啓動門禁（run_startup_gate）

您可以把它理解爲：發車前的**安全檢查**——策略是否就緒、必要數據表是否在、（可選）本地賬本是否與券商端一致。

  • live_trade_startup_gate_mode：

    • off — 關閉門禁

    • warn — 失敗只記日誌/trace，**仍允許**交易（建議灰度先用）

    • block — 失敗則拒絕 run_strategy 入隊（skip_reason=gate_failed）

  • Trader 在生成當日日程後會調用門禁（非交易日快速跳過）。

  • 檢查分層（失敗碼會寫入 trace failures）：

    • L1：Operator 是否就緒、賬戶是否存在

    • L2：主歷史表是否在數據源中（按 asset_type 映射日頻表等）

    • **L3**（可選）：若 Broker 返回非空遠端現金/持倉，則與本地比對；未實現遠端 API 時不硬比

手工冒煙全清單見 模擬實盤手工冒煙方案（live_grid_multi）。

5-C：賬本、日誌與恢復可觀測

在 5-A/5-B 之上，便於**長跑排障與審計**（**不含**自動改單/補償；真實 QMT 遠端查詢屬後續版本）：

  • 訂單 ↔ 券商號映射：受理成功後回寫 broker_order_id / broker_name；受理拒單則 rejected 且 broker 字段空。

  • 日誌輪換擴展：rotate_trade_logs 除 trade CSV 外也清理超期 ``*.risk.log``（規則見 產物清單與排錯）。

  • 對賬與診斷 trace：

    • pre_open / post_close 後輸出 reconcile 檢查點（checkpoint_passed / checkpoint_warn 等）

    • DEBUG 任務 diagnose_pending_orders：只讀對比本地與遠端在途單差異

給新手的結論：兩種「拒單」

在 live 訂單鏈路中，「被拒」可能發生在 RiskManager 複覈臺**（風控）或 **Broker 受理**（櫃檯）兩個站點，證據位置完全不同。:doc:`3-risk-and-order-lifecycle` 已從流程角度說明；下表從**訂單表與 broker_order_id 角度給出對照，供排錯時快速對號入座。

各列含義：路徑**爲拒單/成功類型；**本地訂單表**是否新增行；**broker_order_id 是否回寫；**審計**建議優先打開的文件或表。

如何使用：CLI 有 risk 英文拒因且無新訂單 → 第一行；訂單列表出現 rejected 且 broker 號空 → 第二行；有 broker 號 → 第三行，再查成交狀態。

示例：risk_log 含 <RISK REJECTED> 且 orders 無對應新單 → 風控拒單，勿去查券商 connect。

路徑

本地訂單表

broker_order_id

審計

風控拒單

不入庫

—

*.risk.log + <RISK REJECTED>

櫃檯受理拒單

有行，rejected

空

訂單表 + trace

受理成功

submitted 等

回寫

訂單表 + trace

diagnose_pending_orders 輸出字段（簡要）

  • local_pending_count — 本地在途單數

  • remote_pending_count — 遠端在途單數（simulator 常爲空）

  • local_pending_without_broker_order_id — 已提交但缺券商號的本地單

  • local_pending_missing_remote — 本地有券商號但遠端不存在

  • remote_pending_not_in_local — 遠端有、本地未映射

CLI 與 DEBUG（運維）

Trader Shell（--ui cli）常用命令（help 爲英文）：

  • gate / startup-gate — 手動跑啓動門禁

  • reconcile / snapshot-reconcile — 对账 JSON

  • run --task diagnose_pending_orders — 在途單診斷（需 DEBUG）

  • artifacts / ls-artifacts — 四鍵產物路徑

  • rotatelogs / rotate-logs — 手動日誌輪換

  • broker status|connect|disconnect — 券商會話（simulator 爲標誌位）

  • sync / pull-state — 預留，尚未實現真實遠端同步

下一交易日觀察建議

  • 5-A：trace 裏 strategy_run_skipped 是否過多；live 價頻率是否不低於策略步頻。

  • 5-B：先用 warn，覈對 gate_warn / gate_failed；CLI gate 複驗後再試 block。

  • 5-C：收盤 reconcile、diagnose_pending_orders；必要時 rotatelogs --days N 驗證 risk 清理。

相關文檔