跳到內容

事件紀錄

事件紀錄是一條只追加的紀錄,跟贊助帳本分開。帳本回答「這筆訂單有沒有入帳」。事件紀錄回答「疊層與外掛有沒有看到這件事」。

s4n.donation.test 會寫進事件紀錄,讓 OBS 能顯示測試贊助。它不會建立 Donation 列,也不會變成已付款。

表名是 EventLog。遷移檔是 20261118140000_event_log。

欄位 作用
sequence BIGSERIAL。單調遞增,刪除之後也不會重用。客戶端把它當成「我看到哪裡」
eventId 事件自己的 id。同一則可能送達超過一次,客戶端用它排除重複
type 例如 s4n.donation.succeeded、s4n.chat.message
payload JSON。不得含金鑰、權杖、密文或主金鑰
createdAt 寫入時間。保留期限用這個欄位
donationId 只有 s4n.donation.* 會填。同一筆贊助、同一種事件只留一列。它不是帳本的外鍵

聊天與其他事件的 donationId 是空的。PostgreSQL 的唯一索引把空值當成彼此不同,所以聊天可以一直追加。

送達是至少一次。API 重啟、OBS 斷線、或兩個程序同時處理同一則通知時,客戶端可能再看到同一則。疊層與工作台用事件 id 記住最近看過的 id,第二次不顯示。

斷線後的客戶端帶上最後看到的 sequence(查詢參數 since)再連線。伺服器把序號更大的事件依序補上,數量有上限。預設是 200 則符合這個疊層的事件。超過上限時,這次連線只補最舊的那一段,回應裡的 replayTruncated 會是 true;其餘的仍留在紀錄裡,工作台的「事件紀錄」可以查看,直到保留期限。

第一次打開疊層、瀏覽器裡還沒有序號時,不會把歷史全部播一遍,只從當下的最新序號繼續。這樣新加的 OBS 來源不會突然播出一整週的贊助。

贊助提醒會把補上的贊助排成佇列,一則播完再播下一則,避免一次只剩最後一則。聊天疊層則略過已經在畫面上的訊息 id。

寫入成功後,同一個交易會 NOTIFY s4n_event_log。通知裡只有序號,因為 NOTIFY 的負載上限約 8000 位元組,聊天內容可能更大。每個 API 程序用一條專用連線 LISTEN,收到之後再把那一列讀出來。

若通知在重連的空檔漏掉,每個程序每秒會再依序號把缺口讀一次。所以 v1 不需要 Redis 或 NATS。介面在 apps/api/src/realtime/event-store.ts 的 EventStore。之後若要換成 Redis 或 NATS,實作同一組方法即可,呼叫端不用改。

程序內的訂閱者只收到啟動之後的新事件。重啟不會把舊贊助再混進聊天一次。已經連過的 OBS 則靠自己的序號把錯過的事件補上。

清理是這張表唯一的刪除。序號不會回收。

變數 預設 意思
S4N_EVENT_RETENTION_DAYS 7 聊天以外的事件留幾天
S4N_EVENT_CHAT_RETENTION_HOURS 24 s4n.chat.message、delete、clear 留幾小時
S4N_EVENT_CLEANUP_INTERVAL_MINUTES 15 多久清一次
S4N_EVENT_REPLAY_LIMIT 200 一次重連最多補幾則

聊天可以比贊助短。兩組都是正整數。工作台的事件紀錄會顯示目前的天數與小時。

付款成功若在帳本寫入之後、事件寫入之前被中斷,API 會回 503,讓綠界或歐付寶再通知一次。同一筆贊助的入帳事件只會有一列,所以重送不會讓疊層再響一次。

已經在跑的站:

  1. 備份 PostgreSQL。
  2. 拉下這個版本。
  3. 執行 pnpm db:migrate。正式環境或 Compose 是 pnpm db:deploy(prisma migrate deploy)。Compose 的 API 容器啟動時會自己跑。
  4. 重啟每一個 API 程序。升級前只活在記憶體裡的事件不會補回來,這是唯一一次。
  5. 不需要新的資料庫、Redis 或別的服務。連線字串仍是 DATABASE_URL。
  6. OBS 來源保持原網址即可。第一次連上只接最新序號;之後斷線再連,才依序號補送。

登入限流仍在單一程序的記憶體裡,多個 API 不會共用那個計數。Twitch 徽章快取也還在程序裡:它含有短暫的應用程式權杖,重啟後徽章先顯示文字,下一次整理(預設一小時)再補圖。事件紀錄不放這個權杖。

登入後的工作台有「事件紀錄」。它列出序號、時間、類型與一行摘要,並用工作階段連到 /ws/dashboard。摘要不含金鑰。測試贊助出現在這裡,帳本頁不會出現。