一筆 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 延遲。

POST /v1/fundamentals/jobs 依 kind 驗證參數（年度區間、月數、股號白名單），落一列 'requested' 到 data_jobs，立刻回傳 job_id。request 執行緒完全不碰 TWSE。需要 admin key——跟 POST /v1/admin/backfill 同一道門。

fund-worker 每 JOB_POLL_SEC=5 秒撿最舊一件 'requested'，用續寫 'running' 列來認領，跑抓取，最後續寫 done|failed 帶筆數。每個 job 的現況 = LATEST ON ts PARTITION BY job_id。沒有原子 claim，所以只能跑一個實例——多開會重複執行。

snapshot（OpenAPI 最新一季全上市 + 產業對照）、backfill（MOPS 財報逐年,民國）、revenue（月營收逐月）、reports（年報 PDF → MinIO）。每種 kind 帶自己的 params JSON；worker 依 kind 分派,完成時記錄寫入筆數。

Fundamentals 頁有四張觸發卡 + 一張即時任務表，有任務在跑時每 4 秒輪詢 GET /v1/fundamentals/jobs（閒置放慢到 20 秒）。POST 走的是跟 kbars 回補按鈕同一條 admin-key BFF proxy——API key 永遠不進瀏覽器。

Yahoo 用 Morningstar 式代碼（F0GBR067HA:FO）；基富通用數字業務鍵（002008）。平台刻意兩邊都存但不對照——fundrich_id ↔ yahoo_code 的對照是消費端業務邏輯（super-funds-trade 自己維護 fund_mappings 表）。fund_* 與 fundrich_* 兩組表永遠不 join。

Yahoo 沒有公開的「全基金清單」API——但 Yahoo 自家的 sitemap（sitemap_funds{0,1}.xml.gz，每日更新）枚舉了所有基金頁：2 個 HTTP 請求換 8,881 檔代碼。每日同步只對 fund_watchlist「新增」（requested_by='sitemap'）；代碼從 sitemap 消失只記錄、絕不自動 untrack。低於 5,000 檔代表 Yahoo 端有變——寧可中止也不信殘缺清單。

Yahoo 的禮貌下限是全域 0.6s/請求（超速回 HTTP 999），所以 ~8,900 檔跑一輪要 4–6 小時——一天三輪不可能。分層解法：priority 層（手動/API track）維持一天 3 輪；sitemap 層每天 10:20 掃一輪 bulk。分層就藏在 requested_by 欄位——不動 schema，而 POST /v1/fund/track 重寫 watchlist 列就自然把 bulk 檔升級。

同一輪掃描的所有列共用同一個 ts（該輪開始時間），讀取端從不取 max(ts)——一律跟著 fundrich_scans 最新 done 列的 catalog_ts。中途掛掉或不完整的輪（抓到數 < 官網宣告 90%）不寫任何 catalog 列、標 failed：讀取端繼續供昨天的完整輪。過時的目錄勝過殘缺的目錄。

基富通第一輪正式掃描查回 catalog count = 0：int(dt.timestamp() * 1e9) 在 1e18 量級的 float 誤差可達 ~128ns，截斷後 designated ts 比 client 走精確整數路徑寫入的 TIMESTAMP 欄位低 1 微秒。現在所有「designated ts 必須與存值相等」的寫入（淨值日、交易日、掃描輪）一律走 exact_ts_nanos()——純整數運算。

每輪 detail 掃描把指數的近 20 日表 upsert 進 market_daily（DEDUP ts+symbol）。第一天有 20 日，之後每天多一日；重掃冪等、漏日自癒。商品/匯率沒有 detail 頁，改由每 30 分的 quote 掃描每個台北日落一列。消費端（jsmart 全球市場頁）的走勢圖從 20 日起步，悄悄長成 60 日。

market/registry.py 寫死 34 檔與其 StockQ 連結路徑——首頁列一律用 href 對照，絕不用顯示名稱（首頁有兩個「韓國」：KOSPI 與 MSCI 韓國）。加一檔 = registry 加一行；掃描、表、API 全自動跟上，不動 schema。

StockQ 每檔指數已算好 5–260 日均線、偏離與期間報酬；平台原樣保存（market_index_stats），不用自己還沒長齊的歷史重算。等 market_daily 累積超過 260 日後可以改為自算——刻意先不做。

兩種掃描都在 market_scans 落 running/done/failed；讀取端從最新 done quote 輪的 quote_ts 進場。StockQ 改版會觸發防呆（regex 解析下限、|漲跌%| < 30、命中 ≥90%）讓該輪 failed——昨天的資料繼續供應。