一筆 tick 的完整旅程

ingestor 用連續代碼訂閱，但 callback 的 tick.code 是實際月合約（TXF202607）。code→symbol 反查表必須在掛 callback 之前整份建好：等 contracts ready → resolve → 建表 → 掛 callback → 訂閱。順序錯了，搶先抵達的 tick 會以原始月代碼入庫，永久汙染下游。

反查表同時收 R1 別名自身的 code 和所有同 delivery_month 的實際合約 code（掃同類別群組找出來）——實測兩種都會出現在 callback 裡。

反查表只在每次（重）登入時整份替換——不逐鍵改、盤中不刷新。換月後要等下一次重連才更新。對不上的 code 會以原始代碼入庫並警告一次：這是要處理的資料分裂，不是可以忽略的雜訊。

每筆 TickEvent 都帶 contract = 實際月合約，一路寫進 ticks.contract 與 bars_1m.contract（bar 取 bucket 內最後一筆 tick 的 contract——換月當下可稽核）。kbars 回補的列 contract=NULL，真實身分靠 join contract_map 補回。

一交易日一列。backfill loop 每輪用 live 的 Shioaji Contracts 記今天的對應（權威）；rollcal 子命令按結算規則回推歷史。recorded_by 欄位區分兩者。

bar finalize 後 120 秒內的遲到 tick 會重新計算：bar 修正後以 revision+1 重發（QuestDB DEDUP 冪等覆蓋；Kafka 下游留最高 revision）。超過窗口就記進 dropped_late 計數，交給 kbars 修補。

buy_volume 累計 tick_type=1（外盤）、sell_volume 累計 tick_type=2（內盤）；tick_type=0 兩邊都不算。

每根 bar 的交叉核對：用單調遞增的 total_volume 差推出的期望量 vs 實際聚合量。0 = 完整；非 0 = 漏了 tick（品質旗標，不是錯誤）。跨盤 total_volume 歸零時自動跳過。

試撮永遠不進 bar。要不要存進 ticks 表由 TICKS_STORE_SIMTRADE 決定（預設存）；API 預設濾掉，除非帶 include_simtrade=true。

crash 後從最早仍開著的 bucket 的第一個 offset 重播。last-finalized watermark 擋住已 finalize bar 的重播尾巴、不讓它重建成殘缺 bar；關機也不強制 finalize——資料庫裡的殘缺 bar 比缺一根更糟，replay 會重建。

日盤期望 300 根 open-stamp 分鐘（08:45–13:44）、夜盤 840 根（15:00–04:59）。13:45 / 05:00 的收盤集合競價 bar「可有可無」：有就算覆蓋、沒有不算缺口。coverage_pct 上限鎖 100，因為競價 bar 會讓 actual 超過 expected。

交易日 = 平日扣掉手動維護的休市表（2024H2–2026，含颱風假；可用 TAIFEX_CLOSED_DAYS env 增補）。夜盤歸開盤那天：05:01 之前的時間戳屬於前一個交易日。

每 300 秒：期望分鐘 − 實存分鐘 → 相鄰缺漏合併成段 → 段長 ≥ GAP_MIN_MINUTES=2 才立案（夜盤單一分鐘沒成交是常態，不是缺口）。掃描只看 now−3 分鐘之前完整結束的分鐘，留出 grace + flush 的緩衝。

detected → kbars 修補只寫缺漏的分鐘 → filled。如果 kbars 在那些分鐘也沒資料、但該盤別其他時間有資料，就以 note=tradeless_confirmed_by_kbars 直接結案為 filled。整個盤別全空則標 unfillable——每 6 小時重試一次，以防 vendor 只是晚到。

quant-backfill verify 逐交易日把 bars_1m 對平移後的 kbars（權威）比對、補寫缺漏，然後落一列 coverage_checks（expected / vendor / stored / repaired、status ok|mismatch）。Coverage 頁的 verified 徽章讀的就是這張表。

每個 Kafka 事件帶兩個時間：ts（交易所時間，ISO +08:00，給人看）與 ts_ns（權威 UTC epoch 奈秒——下游一律以它為準）。

盤別窗是「當日第幾分鐘」的集合：日盤 [08:45, 13:46)、夜盤 [15:00, 05:01)——多出的那一分鐘容納可有可無的收盤競價。Python 與 SQL 的 minute-of-day 運算共用同一份定義，過濾條件不可能漂移。

高 timeframe 用 SAMPLE BY … ALIGN TO CALENDAR TIME ZONE 'Asia/Taipei' 現算；1d 再加 WITH OFFSET '05:01'，讓夜盤 05:00 的收盤 bar 落回自己的交易日——與 trading_date_of 的 05:01 切點完全一致。

Shioaji kbars 標記分鐘的結束；管線存 open-stamp，所以回補用 KBAR_TS_SHIFT_MINUTES=-1 平移。calibrate 子命令可逐帳號驗證：日盤第一根在 08:46 = END-stamp（維持 -1），在 08:45 = OPEN-stamp（改 0）。平移後明確轉型成 ns——pandas 3.x 預設 µs，會差一千倍。

每個 poll 批次：寫入 ILP buffer → flush（唯一的 durability barrier）→ 發 BarEvent（盡力而為）→ commit Kafka offset。任何一點 crash 都會重送；DEDUP 吸收重播。

每個 partition 可提交的 offset = 所有仍開著的 bar bucket 中最早的起始 offset。試撮、DLQ、遲到修正的 tick 都不把關。重啟時就從最舊未完成 bar 的開頭精準重播。

auto_flush=off + 顯式 Buffer，flush 用 clear=False、成功才手動 clear。官方 client 失敗時會先清掉 internal buffer 再丟例外——若用 auto-flush，重試等於 flush 空 buffer、假成功，資料就蒸發了。

flush 失敗時 writer 暫停消費、以 1→30 秒退避重試，靠對暫停的 partition poll(0) 保住 group membership；心跳在最後一次失敗後 5 分鐘內標 degraded。rebalance 被收走 partition 時丟掉開著的 bar 並重置 gate——由 replay 重建，避免雙倍量的 bar。

DEDUP 是整列覆蓋，而 kbars 沒有 vwap/tick_count/buy/sell——盲目覆寫會把即時聚合的加值欄位洗成 NULL。所以缺口修補與 catch-up 只寫真正缺的分鐘（only_minutes / after_ts）；全量覆蓋只留給明示的 seed/repair，並在 backfill_runs.requested_by 標注 [full-overwrite]。

驗證失敗的訊息帶著 reason + 原始 bytes 進 market.dlq.v1，offset 立即可提交——一則壞訊息永遠不會卡死 partition。DLQ 告警每分鐘最多一次。

ingestor 每小時查 api.usage() 並上報 ops topic；backfill 在剩餘額度 < USAGE_MIN_REMAINING_PCT=20% 時中止分段任務，並印出精確的續跑指令——續跑無害，因為每筆寫入都 DEDUP 冪等。

ingestor 唯一的背壓點是 20 萬筆的有界佇列。溢出就丟、把窗口記成 gap——刻意不做磁碟 spool（Zeabur 磁碟是 ephemeral），反正 kbars 修補才是權威恢復路徑。五檔沒有回補來源：丟了就永遠沒了，這是接受的取捨。

關機時先停訂閱、再以 10 秒 deadline 汲取佇列，逐筆 try/except——一筆送失敗不會拖累其他；所有損失都記進 gap 窗口。

建表、聚合器 watermark 種子、ILP 連線全部用 1→30 秒退避重試，而不是 crash loop；watermark 種子讀 max(ts) 讀兩次、間隔 500ms，容忍 crash 後 QuestDB WAL 的 read-your-write 延遲。