產物清單與排錯

本章是模擬實盤的「急救手冊」：日誌在哪、先查哪個文件、常見故障按什麼順序排查。

親愛的用戶，live 運行會在磁盤上留下幾類固定「產物」。把它們當成四個專用文件夾，出問題時按圖索驥，比在海量輸出裏盲找高效得多。

0. 适用场景

您已在 live 模式運行，遇到提交失敗、拒單、狀態異常、在途單對不齊
您希望按固定順序定位問題，減少反覆重啓
您需要覈對日誌路徑、輪換策略與 broker_order_id 是否回寫

1. 核心概念：四键产物

qteasy 爲每個 live 賬戶提供 四個固定鍵名 的路徑（文件可以尚不存在，路徑仍然有效）。在 live 子系統的可觀測性設計中，這四類產物分別對應「系統怎麼跑、成交明細、異常恢復、風控審計」——排錯時請先判斷問題屬於哪一類，再打開對應文件，而不是在一個日誌裏全文搜索。

各列含義：鍵名爲 list_live_trade_artifacts / CLI artifacts 返回的 dict 鍵；是什麼爲文件類型；什麼時候該打開它爲典型觸發場景。

如何使用：按 :doc:3-risk-and-order-lifecycle 判斷拒單類型 → 風控查 risk_log，成交查 trade_log；啓動/門禁/trace 查 sys_log。

鍵名	是什麼	什麼時候該打開它
`sys_log`	系統運行日誌	任務調度、啓動門禁、trace、一般報錯
`trade_log`	交易明細 CSV	成交、費用、持倉變化明細
`break_point`	斷點恢復文件（鍵名是 `break_point`）	異常退出後想恢復 Trader 狀態
`risk_log`	風控拒單審計（`*.risk.log`）	懷疑風控拒單時優先

示例（API 與 CLI）：

import qteasy as qt
arts = qt.list_live_trade_artifacts(account_id=1, data_source=qt.QT_DATA_SOURCE)
print(arts['sys_log'], arts['trade_log'], arts['break_point'], arts['risk_log'])
# 若 CLI 提示 risk 拒单，可单独打开：
print(arts['risk_log'])

在 Trader Shell 也可輸入 artifacts（別名 ls-artifacts）獲得相同四鍵路徑。

路徑規則（簡要）：

相對路徑相對於 qteasy 根目錄；絕對路徑與 ~/... 家目錄均支持
sys_log_file_path / trade_log_file_path 可在運行中用 qt.configure(...) 修改並立即生效

2. 日志轮换

長期 live 會積累 CSV 與 risk 日誌。qteasy 按 trade_log_keep_days（默認 3 天）清理過期文件。

API：qt.rotate_trade_logs(days=None)
CLI：rotatelogs（別名 rotate-logs），可選 --days N

清理範圍（在當前交易日誌目錄下）：

trade_log_*.csv / trade_summary_*.csv / value_curve_*.csv
*.risk.log

每次新 Python 進程導入 qteasy 時會自動輪換一次；您也可在運維時手動執行上述命令。

3. 建议排错顺序（决策树）

請按順序自問，避免跳步：

Step 1 — 界面上有沒有英文拒因？

有，且像 Order rejected by risk rule [...] → 走 風控路徑（Step 3）
有 Order submission failed 等 → 走 提交/連接路徑（Step 4）
沒有明顯報錯但行爲不對 → Step 6

Step 2 — 打開 artifacts，確認四個路徑可寫、文件是否在增長

Step 3 — 風控拒單

查 risk_log 中 <RISK REJECTED> 與 rule_id
不應出現新的訂單錶行（與櫃檯拒單不同）

Step 4 — 櫃檯受理 / 連接

broker status：is_connected 是否爲真（simulator 上表示適配層可受理）
訂單表：是否有 rejected 且 broker 號爲空（櫃檯拒單）

Step 5 — 在途單不一致

DEBUG 模式下：run --task diagnose_pending_orders
或 Shell：reconcile 看 JSON

Step 6 — 配置是否如我所想

liveconfig --detail 覈對快照

Step 7 — 對照 trade_log 與訂單狀態序列，以日誌最終狀態爲準

4. 高频故障剧本

每節統一：現象 → 先查什麼 → 常見原因 → 下一步。

A. 訂單被風控拒絕

現象：CLI 英文拒因；提交結果爲空 {}
先查：risk_log 含 <RISK REJECTED>；訂單表無新行
常見原因：超單筆上限、不在白名單、非交易時段等
下一步：調整規則或訂單參數，同場景複測；詳見 :doc:3-risk-and-order-lifecycle

B. 提交失敗（非風控）

現象：無有效提交記錄，或本地校驗報錯
先查：broker status、現金/持倉是否夠、sys_log 錯誤棧
常見原因：未 connect、字段不合法、資源不足
下一步：修復連接或字段後重試

C. 櫃檯受理拒單

現象：訂單表有行，status=rejected，broker_order_id 爲空
先查：trace、受理返回的 reason
常見原因：模擬券商規則不接受該委託（與風控無關）
下一步：對照 :doc:6-trader-snapshot-gate 拒單表，勿與風控混淆

D. 長期 partial-filled

現象：訂單一直是部分成交
先查：累計成交量 vs 委託數量
常見原因：回報尚未湊滿；或行情導致分批成交慢
下一步：結合成交回報判斷是否應變爲 filled

E. 收盤後狀態不確定

現象：收盤後不知在途單如何處理
先查：post_close 相關 trace、reconcile JSON
下一步：覈對撤單與最終狀態

F. broker_order_id / 在途單異常

當本地訂單狀態、券商委託號或在途單列表「對不上」時，現象多樣但都可歸入下表幾類。本表位於 live 5-C 可觀測範疇，與 :doc:6-trader-snapshot-gate 診斷字段一致；simulator 上遠端列常爲空，屬正常。

各列含義：現象爲您觀察到的矛盾；先查爲第一證據來源；下一步爲建議動作（只讀診斷爲主，不自動改單）。

如何使用：匹配「現象」行 → 執行「先查」→ 若仍不明，DEBUG 下 run --task diagnose_pending_orders。

現象	先查	下一步
風控拒單	`risk_log`，無新訂單行	調規則
櫃檯拒單	訂單 `rejected`，broker 空	trace / reason
已 submitted 但無 broker id	受理 ACK 與回寫	:doc:`4-broker-adapter-and-integration`
本地與遠端在途不一致	DEBUG：`run --task diagnose_pending_orders`	只讀診斷；simulator 遠端常爲空

CLI 辅助：reconcile、gate。

G. 界面與日誌不一致

現象：CLI 提示與事後查日誌感覺矛盾
先查：按時間順序對齊同一訂單 ID 的全鏈路記錄
下一步：以日誌最終狀態爲準覆盤

5. 运维建议

定期看交易日誌目錄佔用；必要時 rotatelogs --days N
關鍵運行日保存 liveconfig --detail 輸出截圖或文本
長跑或發版前對照 :doc:7-manual-smoke-live-grid-roadmap

6. 快速检查清单

賬戶正確
配置生效（liveconfig）
風控是否拒絕（risk_log）
券商是否可受理（broker status）
受理成功是否回寫 broker_order_id
四鍵路徑可讀（artifacts）

7. 常用英文提示与中文含义

Order rejected by risk rule [MAX_ORDER_QTY]: order quantity exceeds limit

含義：本地風控規則 MAX_ORDER_QTY 拒絕——數量超限。查 risk_log，不是券商拒單。

<RISK REJECTED> rule_id='MAX_ORDER_QTY' reason='...' symbol='000001.SZ' ...

含義：同上，結構化風控日誌行，便於搜索。

Order submission failed.

含義：提交鏈路失敗（非風控通過後的櫃檯拒單），查連接與 sys_log。

[NOT_IMPLEMENTED] sync_from_broker is reserved for QMT broker integration (S2.1-b).

含義：sync 命令尚未實現真實遠端同步，屬預期提示，不是運行故障。

8. 相关跳转

啓動與配置：:doc:2-configuration-and-run
生命週期：:doc:3-risk-and-order-lifecycle
快照/門禁/拒單：:doc:6-trader-snapshot-gate
手工冒煙：:doc:7-manual-smoke-live-grid-roadmap
CLI 对照：:doc:8-cli-trader-capability-matrix
Broker：:doc:4-broker-adapter-and-integration
實操教程：tutorials/8-live-trade-risk-and-broker-walkthrough.md