Mirror copy for gu-log SP-251. Original by Thariq (@trq212): Know your unknowns. English | 繁中
了解你的未知 · 實作後
← 所有範例

Merge 前先考我

要求一份附帶你必須通過的測驗的報告,把「我掃過 diff 了」變成驗證過的理解——artifact 不會讓你在真正理解之前感覺完成。

Prompt
我想確保在 merge 前完全理解這個變更發生的一切。給我一份關於 export-feature diff 的 HTML 報告——脈絡、直覺、做了什麼——底部附帶我必須通過的測驗。
Claude 產出的成品
Acme · Merge 準備報告

Clip 匯出:改了什麼、為什麼

一個 14 檔 diff,把伺服器端 clip 匯出加到 review threads。讀完下面三個章節,然後通過測驗。如果通不過,你還沒準備好 merge——這就是重點。

feature/clip-exportmain · 14 files · 9 commits
14
檔案變更
+612
行新增
−148
行刪除

心智模型

一張圖抵 14 個檔案:匯出請求現在的流向 vs. 之前。

在這個變更之前,「匯出 clip」意味著瀏覽器用 MediaRecorder 在客戶端拼接 frames 並上傳結果——慢、鎖住 tab、而且在 Safari 上壞掉。現在客戶端只請求匯出;一個新的 worker 從原始媒體伺服器端渲染,客戶端 poll job 直到 signed download URL 出現。

之前 · 客戶端渲染
ReviewPlayer.tsx
MediaRecorder capture(in-tab)
~40–90 秒,tab 鎖住
PUT /uploads(整個檔案)
S3 exports/ bucket
之後 · 伺服器端 job
ReviewPlayer.tsx
POST /api/exports(回傳 job id)
export-worker(新,ffmpeg)
S3 exports/ bucket
jobs table(新)
客戶端每 2 秒 poll
GET /api/exports/:id → signed URL

這帶來的三個不明顯行為

掃 diff 不會告訴你的部分。每一個都是刻意的——這是背後的原因。

01

匯出從原始上傳渲染,不是審閱者看的 proxy

什麼Worker 拉 media/originals/,從不用 720p review proxy。因此匯出的 clip 可能比審閱者畫註解時看到的更清晰
為什麼剪輯師匯出 clip 是要交給客戶的;送出壓縮的 proxy 會讓他們難堪。註解座標儲存為正規化(0–1),所以可以正確重新投射到全解析度 frame。
在哪worker/export/render.ts:41 worker/export/burn_in.ts:88
02

Export job 能撐過 worker crash——透過 visibility timeout,不是重試

什麼Job row 透過設定 locked_until = now() + 10min 來認領。如果 worker 在渲染中途死掉,不會觸發重試;lock 只是過期,下一個閒置的 worker 會從頭撿起 job。
為什麼ffmpeg 渲染在中途不是 idempotent,而 retry queue 需要我們還不想要的 dead-letter 處理。Lock 過期用一個欄位就給了 at-least-once 語意。結果:crash 的 job 會顯示「處理中」最多 10 分鐘後才恢復。
在哪db/migrations/0142_export_jobs.sql worker/export/claim.ts:19
03

下載 URL 24 小時後過期——匯出檔案本身保留 7 天

什麼GET /api/exports/:id 回傳的 signed S3 URL 有效 24 小時,但底層物件要到 7 天 lifecycle rule 觸發才會刪除。重新呼叫 endpoint 會產生新的 URL,不需要重新渲染。
為什麼短 URL 限制連結被轉發到 workspace 外(匯出可能包含未發佈的素材);較長的物件 TTL 意味著過期的 Slack 連結只需要一個 API call 就能復活,不用 90 秒重新渲染。
在哪api/exports/get.ts:57 infra/s3_lifecycle.tf:23
這依賴的現有行為

Workspace-scoped signed-URL auth。 GET /api/exports/:id 本身不做權限檢查——它重用已經守住每個 media route 的 requireWorkspaceMember middleware。如果那個 middleware 的 session 處理有變(有一張公開 ticket,BL-2214,關於 guest reviewer sessions),匯出下載也會跟著變。這個 diff 裡沒有任何東西會標記出這件事。

第 2 部分 · 證明你懂

Merge 前六個問題

不是瑣事——每一個都是你在 incident 或 review 時必須正確做出的決定。
分數:0 / 6 · 已答 0

可以 merge 了

6/6——你可以向被 page 的人解釋這個變更。下面是標準 checklist。

  • 理解已驗證(本測驗,6/6)
  • CI 在 feature/clip-export 綠燈 · 412 tests
  • Migration 0142 已審——純新增,無 backfill
  • 用上面的摘要當 commit body 做 Squash-merge
  • 部署後觀察 export-worker dashboard 30 分鐘
  • 在 merge comment 註記 BL-2214 依賴

還不行——重讀這些章節

你漏了下面的問題。缺口直接對應到報告: