訂閱機制與場景處理
加密貨幣交易推送採用連接即訂閱模型：客戶端完成 WebSocket 連接和登錄鑑權後，服務端會自動推送當前鑑權用戶的加密貨幣交易事件，無需客戶端發送額外的訂閱請求。
消息識別方式
收到一條推送消息後，按以下兩步確定處理場景：
步驟 1：讀 report_type → 確定大類（下單 / 成交 / 撤單 / 過期）
步驟 2：讀 order.is_close → 確定是否為終態，不再推送後續報告report_type | 說明 | order.is_close |
|---|---|---|
1（new_rpt.result=0） | 下單成功 | false — 訂單仍活躍 |
1（new_rpt.result≠0） | 下單失敗 | true — 終態 |
4（fill_rpt.fill_status=1） | 部分成交 | false — 仍有剩餘 |
4（fill_rpt.fill_status=2） | 完全成交 | true — 終態 |
3（cancel_rpt.result=0） | 撤單成功 | true — 終態 |
5 | 訂單過期 | true — 終態 |
事件覆蓋範圍
鑑權成功後，客戶端將自動接收以下全部報告類型，無法單獨過濾某類事件：
report_type | 說明 |
|---|---|
1 | 下單報告（含成功和失敗） |
3 | 撤單報告 |
4 | 成交報告（含部分成交和完全成交） |
5 | 訂單過期報告 |
各報告類型的消息結構和字段說明詳見 數據格式。
各場景詳解
場景一：下單成功
觸發時機：系統確認訂單已進入委託隊列。
識別方式：report_type=1，new_rpt.result=0
order 特征：
is_close = false— 訂單仍活躍，後續會收到成交或撤單事件cum_qty = "0"— 尚未有成交avg_px = "0"— 尚未有成交
處理建議：記錄訂單進入「已掛單」狀態，展示等待成交 UI。
場景二：下單失敗
觸發時機：訂單被系統拒絕（如餘額不足、價格非法、風控攔截等）。
識別方式：report_type=1，new_rpt.result≠0
order 特征：
is_close = true— 終態，該訂單已結束，不會再收到後續事件cum_qty = "0"— 無成交
new_rpt 特征：
result— 非 0 的錯誤碼err_msg— 失敗原因說明
處理建議：將訂單標記為失敗，展示 new_rpt.err_msg，結束該訂單的生命週期。
場景三：部分成交
觸發時機：訂單被部分撮合，仍有剩餘未成交數量。
識別方式：report_type=4，fill_rpt.fill_status=1
order 特征：
is_close = false— 非終態，後續還會收到成交或撤單事件cum_qty— 已更新為累計成交總量（含本次）avg_px— 已更新為新的成交均價
fill_rpt 特征：
last_qty— 本次成交數量last_px— 本次成交價格last_amount— 本次成交金額leave_qty— 剩餘未成交數量
處理建議：累加成交明細，更新訂單的已成交數量和均價，展示「部分成交」狀態。用 fill_rpt.fill_id 做冪等防止重複處理。
場景四：完全成交
觸發時機：訂單全部撮合完成。
識別方式：report_type=4，fill_rpt.fill_status=2
order 特征：
is_close = true— 終態，訂單已完結cum_qty— 等於原始order_qty（全部成交）avg_px— 最終均價
處理建議：記錄最後一筆成交明細，將訂單標記為「完全成交」並關閉，不再等待後續事件。
場景五：撤單成功
觸發時機：系統確認撤單完成（全部撤單，或部分成交後撤單）。
識別方式：report_type=3，cancel_rpt.result=0
order 特征：
is_close = true— 終態cum_qty— 撤單時的累計成交量（若之前有部分成交，此值大於 0）avg_px— 撤單時的成交均價
處理建議：將訂單標記為「已撤單」。若 order.cum_qty > "0"，說明是部分成交後撤單，需保留已成交部分的記錄。
場景六：訂單過期
觸發時機：訂單超過有效期（如 IOC 單未完全即時成交、訂單到期等）。
識別方式：report_type=5
order 特征：
is_close = true— 終態cum_qty— 過期時的累計成交量（IOC 單可能有部分成交後過期的情況）avg_px— 過期時的成交均價
處理建議：將訂單標記為「已過期」。若 order.cum_qty > "0"，說明 IOC 單在過期前已有部分成交，需保留已成交記錄。
終態判斷速查
order.is_close == true → 訂單已到達終態，不會再推送該訂單的任何後續事件
order.is_close == false → 訂單仍活躍，後續還可能收到成交或撤單事件| 場景 | order.is_close |
|---|---|
| 下單成功 | false |
| 下單失敗 | true |
| 部分成交 | false |
| 完全成交 | true |
| 撤單成功 | true |
| 訂單過期 | true |
冪等處理建議
| 字段 | 用途 |
|---|---|
report_id | 消息級別去重，防止網絡重推導致重複處理 |
fill_rpt.fill_id | 成交級別去重，防止重複記賬 |
消費方應以 report_id 或 fill_rpt.fill_id 為 key 做冪等校驗，避免重複處理。
時序示例
限價單買 0.1 BTC，部分成交後撤單
t1: report_type=1, new_rpt.result=0
→ order.cum_qty="0", order.is_close=false
→ 下單成功，訂單掛出
t2: report_type=4, fill_rpt.fill_status=1
→ order.cum_qty="0.06", order.is_close=false
→ 部分成交 0.06 BTC，fill_rpt.leave_qty="0.04"
t3: report_type=3, cancel_rpt.result=0
→ order.cum_qty="0.06", order.is_close=true
→ 撤單成功，最終成交 0.06 BTC，剩餘 0.04 BTC 已撤銷市價單完全成交
t1: report_type=1, new_rpt.result=0
→ 下單成功
t2: report_type=4, fill_rpt.fill_status=2
→ order.cum_qty=order.order_qty, order.is_close=true
→ 完全成交，訂單結束下單失敗
t1: report_type=1, new_rpt.result≠0
→ order.is_close=true, new_rpt.err_msg="<失敗原因>"
→ 下單失敗，訂單結束IOC 單部分成交後過期
t1: report_type=1, new_rpt.result=0
→ order.is_close=false
→ 下單成功
t2: report_type=4, fill_rpt.fill_status=1
→ order.cum_qty="0.03", order.is_close=false
→ 部分成交 0.03 BTC
t3: report_type=5
→ order.cum_qty="0.03", order.is_close=true
→ 剩餘數量已過期，最終成交 0.03 BTC行為說明
不補發歷史事件
連接斷開期間發生的交易事件不會在重連後補發。如需查詢歷史訂單或成交記錄，請使用以下 REST 接口：
重連後恢復
連接斷開並重新鑑權後，服務端會自動重新建立推送通道，繼續推送後續發生的事件。