模擬實盤手工冒煙方案（live_grid_multi）

親愛的用戶，本章是一份**手工驗收清單**：在真實交易日（或您方便的時間段），用倉庫示例 examples/live_grid_multi.py 跑一遍模擬實盤，逐項打勾，確認 qteasy 行爲與文檔一致。

> 冒煙測試是什麼？ > 像新船下水前的試航——不必覆蓋所有策略，而是用**固定示例 + 固定檢查項**快速發現「能不能用、日誌能不能看懂」。本手冊側重 真實 ``qt.run`` + 人眼驗收；非交易時段也可用倉庫內無頭腳本做架構迴歸（見下文）。

策略基線：``examples/live_grid_multi.py``（5 分鐘 VS + 多標的網格）。 維護者若需對照內部路線圖，可參考倉庫 ``.cursor/plans/trader架構升級路線圖_0650f0d5.plan.md``（可選，非閱讀必需）。

與無頭腳本的關係

  • tests/notebook_trader_headless_script.py 提供分階段無頭冒煙（含 5-A/5-B、5-C 等），可在 Notebook 分 cell 調用。

  • **本手冊**側重：您親自啓動 live、看 CLI/日誌、打勾。

  • 建議節奏：**交易日**按本手冊；**休市**用無頭腳本補回歸。

一、環境與前置條件

  1. Python：推薦 /opt/anaconda3/envs/py39/bin/python。若您通過 pip 安裝 qteasy，工作目錄可以是任意包含 examples/live_grid_multi.py 的路徑（不必克隆全倉庫，但需能訪問示例腳本）。

  2. **新賬戶、無持倉**（避免舊訂單幹擾）：

    • -n/--new_account <用戶名> 創建新賬戶；或

    • 已有 account_id 且 --restart 清空記錄，並確認無持倉後再啓。

  3. 數據：分鐘策略需本地有 stock_1min 等表；首次 refill 可能較久，屬正常。

  4. 日誌：sys_log_file_path、trade_log_file_path 可寫（用 artifacts 覈對）。

二、啓動命令模板

在含示例的目錄執行（按您的賬戶調整）:

/opt/anaconda3/envs/py39/bin/python examples/live_grid_multi.py \\
    -a <ACCOUNT_ID> -n <NEW_USER_NAME_OR_OMIT> \\
    --ui cli \\
    [--debug] [--restart]

說明：

  • 冷啓動：新建 -n 或 --restart 後確認持倉爲空。

  • 勿在不明環境放大 trade_batch，以免資金壓力。

  • 5-C 相關 CLI 建議加 --debug，以便 run --task diagnose_pending_orders。

三、分階段驗收（逐項打勾）

下列階段對應內部路線圖 0～5-C / 階段 11；每項含 本階段在驗證什麼、操作與驗收。

階段 0：基線、狀態機與可觀測性

驗證什麼：Trader 能正常啓動、狀態遷移合理、日誌能還原「啓動 → 日程 → 關鍵任務」順序。

  • 操作：觀察 CLI/日誌中狀態（stopped → sleeping/running 等）與任務入隊。

  • 驗收：無未解釋死鎖；能還原一次完整啓動時間線。

階段 1：規範退出

驗證什麼：正常 stop/退出後資源釋放，斷點與日誌無異常截斷。

  • 操作：用 Shell 正常退出，勿強殺進程。

  • 驗收：無殭屍線程；日誌完整。

階段 2：任務調度與 SKIP

驗證什麼：異步拉價與策略任務邊界清晰；跳過任務時日誌含可讀的 skip_reason。

  • 操作：觀察 acquire_live_price、run_strategy 等調度。

  • 驗收：異常/跳過可解釋、可統計。

階段 3：日程與 catch-up

驗證什麼：同一配置下日程可復現；盤中啓動的「補跑」行爲與文檔一致。

  • 操作：對比同日兩次關鍵任務時刻，或盤中啓動一次。

  • 驗收：日程輸出可復現。

階段 3.5：成交入賬一致性

驗證什麼：成交後現金/持倉/訂單一致，無重複扣款。

  • 操作：至少一筆模擬成交後覈對賬本。

  • 驗收：無「半提交」矛盾。

階段 4-A：成交回報路徑

驗證什麼：成交經 poll_fills 等公開路徑消費，整日 sim 可穩定運行。

  • 操作：跑滿半個交易日或整日。

  • 驗收：無內部隊列類報錯棧。

階段 4-B：SKIP 原因分桶

驗證什麼：日誌中 skip_reason= 可人工歸類（如 gate_failed、snapshot_stale）。

  • 操作：檢索 skip_reason=。

  • 驗收：字段齊全、含義可懂。

階段 5-A：策略快照

驗證什麼：開啓 split 後，prepare 在 run 之前；快照過期時跳過有日誌。

  • 操作：先 live_trade_split_strategy_prepare=False 作基線；再 True 並設 live_trade_prepare_lead_seconds、live_trade_strategy_snapshot_max_age_seconds``（須在 ``qt.run 前 configure）。

  • 驗收：日程/日誌見 prepare；snapshot_stale 可解釋。

階段 5-B：啓動門禁

驗證什麼：warn 只告警；block 在嚴重失敗時阻斷策略入隊。

  • 操作：分檔試 warn / block；Shell 執行 gate。

  • 驗收：block 不誤殺正常交易日（先 warn 灰度）。

階段 11 / 5-C：映射、輪換、診斷、對賬

驗證什麼：券商號回寫、risk 日誌輪換、在途單診斷、收盤對賬 JSON。

  1. 訂單映射 — 成功單有 broker_order_id；櫃檯拒單 rejected 且 broker 空；風控拒單無新訂單行、risk_log 有 <RISK REJECTED>。

  2. 產物與輪換 — artifacts 四鍵可寫；rotatelogs --days 30 清理超期 *.risk.log。

  3. 在途單診斷 — DEBUG：run --task diagnose_pending_orders，字段齊全。

  4. post_close — reconcile JSON 含 is_ok、failures 等。

四、與 live_grid_multi 相關的補充

  • 多標的 VS + multi_pars：各標的網格參數首日初始化合理。

  • 子日頻 refill：冒煙日可先縮小 refill 表，僅保留 stock_1min 等最小集。

  • 驗收：無持倉起步下首日行爲與示例邏輯一致；無 NaN 價誤成交。

五、Notebook 無頭冒煙（可選）

休市時在 Notebook 中可調用 tests/notebook_trader_headless_script.py 各 stage* 函數；詳見腳本內註釋。與手工 live 可二選一或組合。

六、當日收工簡表

手工冒煙結束時，可用下表快速勾選「今天測到哪一步」。各行對應上文第三部分的階段編號；**您執行的動作摘要**請按實際填寫，**打勾標準**來自該階段驗收說明。本表範圍覆蓋路線圖 0～5-C / 階段 11，不含 Broker/QMT 接入（見 券商適配層與集成）。

各列含義：**階段**爲路線圖編號；**您執行的動作摘要**由您記錄；**打勾標準**爲通過該階段的最小條件。

如何使用：冒煙過程中完成某階段後，在「動作摘要」列寫一句（如「warn 模式下 gate 通過」），達標則在心中或副本上打勾；未達標則記入 §七記錄模板的「結論」列。

階段

動作摘要

打勾標準

0

看狀態/日誌

啓動鏈路可還原

1

規範退出

資源正常釋放

2～4-B

調度與 SKIP

skip_reason 可懂

5-A/B

快照與門禁

stale/gate 可解釋

11 / 5-C

映射/輪換/診斷/對賬

見上文四節

七、記錄模板（建議填寫）

每次冒煙後記錄：版本號、核心 live_trade_* 配置、gate 結果、拒單抽檢、reconcile 摘要、結論（通過/待查/阻塞）。便於下一交易日對照。

相關文檔