如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

調查事故並測試修正

根據事故資料重現問題,提出針對該問題的修正,並整理可供審查的交接文件。

難度 Intermediate
任務時間跨度 Long-running

將已移除敏感資訊的事故資料與可正常運作的測試環境交給 Codex 雲端,讓它檢視證據、重現證據所指向的程式碼缺陷,並提供針對該缺陷的修正、迴歸測試證據,以及部署與回復至先前版本的交接說明。

最適合的對象

  • 在事故已獲控制後進行調查的小型工程團隊。
  • 已有去除敏感資訊的證據,且備有安全輸入資料可供重現問題的應用程式缺陷。
  • 在運作正常的隔離測試環境中審查特定問題修正方案的團隊。

目錄

    ← 所有應用案例

    調查事故並測試修正

    根據事故資料重現問題,提出針對該問題的修正,並整理可供審查的交接文件。

    將已移除敏感資訊的事故資料與可正常運作的測試環境交給 Codex 雲端,讓它檢視證據、重現證據所指向的程式碼缺陷,並提供針對該缺陷的修正、迴歸測試證據,以及部署與回復至先前版本的交接說明。

    Intermediate
    Long-running
    準備雲端環境

    將已移除敏感資訊的事故資料與可正常運作的測試環境交給 Codex 雲端,讓它檢視證據、重現證據所指向的程式碼缺陷,並提供針對該缺陷的修正、迴歸測試證據,以及部署與回復至先前版本的交接說明。

    Intermediate
    Long-running

    相關連結

    最適合的對象

    • 在事故已獲控制後進行調查的小型工程團隊。
    • 已有去除敏感資訊的證據,且備有安全輸入資料可供重現問題的應用程式缺陷。
    • 在運作正常的隔離測試環境中審查特定問題修正方案的團隊。

    入門提示詞

    使用 [path to sanitized incident packet] 調查 [repository/service] 中的事故 [incident ID]。請在這項任務選用的已發布雲端環境中作業。 事故資料列出了事故發生的時段、受影響版本的 SHA、預期行為與實際觀察到的行為、相關日誌與追蹤記錄的節錄,以及可安全用於重現問題的輸入資料。請先閱讀 AGENTS.md 和程式碼庫的設定與測試說明。確認目前簽出的程式碼與受影響的版本一致。如有差異,請先說明差異,再下結論。 整理簡短的事故時間軸,並標明所引用的事故資料與原始碼的檔案名稱及行號。分別列出觀察結果、假設與尚缺的證據。在隔離測試環境中檢驗證據最充分的假設。如果無法重現故障,或缺乏決定性證據,請提交調查結果並說明下一個診斷步驟。在這種情況下,請勿宣稱已確認根本原因,也不要根據猜測修改程式碼。 如果證據顯示程式碼有缺陷,請新增迴歸測試,先在原始程式碼上執行,證明測試會因該缺陷而失敗。只做必要的最小修正,重新執行同一項測試,再執行程式碼庫中涵蓋範圍較廣的相關測試,以及可用的 lint 和型別檢查。記錄執行的指令、結束代碼,以及無法執行的檢查項目。 準備分支的變更差異、Pull Request 說明草稿、test-evidence.md,以及部署與回復至先前版本的交接說明。列出證據支持的原因、仍待釐清的事項,以及修正後有哪些行為改變。每項驗證準則各用一列記錄證據,列出程式碼修訂版本與環境版本、修正前後各自的指令、結束代碼與日誌,以及實際結果。將狀態標示為通過、失敗、受阻或未執行,並註明限制。Pull Request 說明請保留為本機草稿,供審查使用。 針對這個 webhook 重複投遞的範例,請指出資料庫交易提交前與提交後各自的故障點,使用彼此獨立的資料庫連線證明同一事件重複投遞時會發生競爭,並說明對交易隔離、接收記錄的保留,以及部署期間新舊版本並行運作所做的假設。 在這個 webhook 重複投遞的範例中,請等舊版消費者處理完手上的事件,再找出沒有對應接收記錄的舊版訂單,之後才能提議恢復投遞先前保留的事件。依照現有的佇列或隔離程序,暫停處理受影響事件鍵所對應的事件。新增一項測試,預先建立缺少對應接收記錄的訂單及等待重試的對應事件,證明暫停處理期間既不會建立第二筆訂單,也不會回傳成功確認。核對訂單與事件時,只能依據可信且不可變的事件識別資訊、標準形式的事件酬載,以及訂單已提交的證據。證據不足或彼此矛盾的事件應繼續隔離,交由負責人審查。請勿自行編造指紋、刪除接收記錄,或重播尚未釐清的舊版事件。 除非我另行指定已核准的來源,否則只可使用提供的事故資料與程式碼庫。如需查詢監控資料,只可存取已提供且明確核准的唯讀監控來源。程式碼與任務產出只能寫入這個程式碼庫,資料庫也只能使用其隔離測試資料庫。請勿直接連線至正式環境的應用程式主機或資料庫主機,也不得修改正式環境系統。請勿重播正式環境事件、修改線上資料或監控、撰寫或發布對外更新訊息,也不得合併程式碼或部署。
    使用 [path to sanitized incident packet] 調查 [repository/service] 中的事故 [incident ID]。請在這項任務選用的已發布雲端環境中作業。 事故資料列出了事故發生的時段、受影響版本的 SHA、預期行為與實際觀察到的行為、相關日誌與追蹤記錄的節錄,以及可安全用於重現問題的輸入資料。請先閱讀 AGENTS.md 和程式碼庫的設定與測試說明。確認目前簽出的程式碼與受影響的版本一致。如有差異,請先說明差異,再下結論。 整理簡短的事故時間軸,並標明所引用的事故資料與原始碼的檔案名稱及行號。分別列出觀察結果、假設與尚缺的證據。在隔離測試環境中檢驗證據最充分的假設。如果無法重現故障,或缺乏決定性證據,請提交調查結果並說明下一個診斷步驟。在這種情況下,請勿宣稱已確認根本原因,也不要根據猜測修改程式碼。 如果證據顯示程式碼有缺陷,請新增迴歸測試,先在原始程式碼上執行,證明測試會因該缺陷而失敗。只做必要的最小修正,重新執行同一項測試,再執行程式碼庫中涵蓋範圍較廣的相關測試,以及可用的 lint 和型別檢查。記錄執行的指令、結束代碼,以及無法執行的檢查項目。 準備分支的變更差異、Pull Request 說明草稿、test-evidence.md,以及部署與回復至先前版本的交接說明。列出證據支持的原因、仍待釐清的事項,以及修正後有哪些行為改變。每項驗證準則各用一列記錄證據,列出程式碼修訂版本與環境版本、修正前後各自的指令、結束代碼與日誌,以及實際結果。將狀態標示為通過、失敗、受阻或未執行,並註明限制。Pull Request 說明請保留為本機草稿,供審查使用。 針對這個 webhook 重複投遞的範例,請指出資料庫交易提交前與提交後各自的故障點,使用彼此獨立的資料庫連線證明同一事件重複投遞時會發生競爭,並說明對交易隔離、接收記錄的保留,以及部署期間新舊版本並行運作所做的假設。 在這個 webhook 重複投遞的範例中,請等舊版消費者處理完手上的事件,再找出沒有對應接收記錄的舊版訂單,之後才能提議恢復投遞先前保留的事件。依照現有的佇列或隔離程序,暫停處理受影響事件鍵所對應的事件。新增一項測試,預先建立缺少對應接收記錄的訂單及等待重試的對應事件,證明暫停處理期間既不會建立第二筆訂單,也不會回傳成功確認。核對訂單與事件時,只能依據可信且不可變的事件識別資訊、標準形式的事件酬載,以及訂單已提交的證據。證據不足或彼此矛盾的事件應繼續隔離,交由負責人審查。請勿自行編造指紋、刪除接收記錄,或重播尚未釐清的舊版事件。 除非我另行指定已核准的來源,否則只可使用提供的事故資料與程式碼庫。如需查詢監控資料,只可存取已提供且明確核准的唯讀監控來源。程式碼與任務產出只能寫入這個程式碼庫,資料庫也只能使用其隔離測試資料庫。請勿直接連線至正式環境的應用程式主機或資料庫主機,也不得修改正式環境系統。請勿重播正式環境事件、修改線上資料或監控、撰寫或發布對外更新訊息,也不得合併程式碼或部署。

    讓 Codex 在備妥的雲端環境中調查一起範圍明確的事故。目標是讓工程師取得可供審查的成果:有證據支持的原因說明、修正前會失敗的迴歸測試、針對缺陷的修補,以及實際執行測試所得的證據。

    這套流程適合在事故已受控、接下來需要釐清並修正應用程式缺陷時使用。如果現有證據不足以確定原因,清楚記錄調查過程並指出下一個診斷步驟,也是一項有用的成果。

    準備環境與事故資料包

    1. 在網頁版或桌面應用程式中,選擇工作位置 > 雲端,再選取已發布的環境。

    2. 如需建立環境,請選取建立環境,選擇 GitHub 程式碼庫,並請 Codex 準備執行環境、相依套件及隔離的測試服務。

    3. 檢閱設定報告,處理未通過的檢查,並在開始新任務前選取發布。

    如果相依套件或服務設定有變更,請編輯可重複使用的環境,測試後選取重新發布,再於新任務中驗證更新後的環境。

    重新整理程式碼庫不會重新執行安裝或啟動指令,現有任務也會保留各自的狀態。

    請分別設定需要連線的網路目的地和測試憑證。允許連線至某個目的地並不會授予該服務的存取權。

    確認新任務中簽出的受影響程式碼、相依套件、檢查項目與用完即可刪除的測試資料庫都能正常運作。記錄起始提交與測試基準。

    請讓任務能取得初步調查所需的全部資料。將已移除敏感資訊的資料包放入程式碼庫,或讓任務能讀取其中的檔案。開始前,應由工程師彙整並核對以下資料:

    輸入資料 應包含的內容
    事故摘要 事故 ID、UTC 時段、預期與實際觀察到的行為、已知影響及目前狀態。請區分已確認的數量與估計值。
    發布版本資訊 已部署的提交 SHA、部署時間、不含機密的相關設定值,以及最後一個已知正常的版本(如有)。
    可相互比對的證據 日誌與追蹤記錄摘錄,包含時間戳記、事件 ID、請求 ID、追蹤 ID 及檔案參照。移除敏感資訊時,請確保相同識別碼在各處仍能相互對應。
    安全重現方式 測試用的請求本文、相關測試配置,以及如何在不呼叫線上服務的情況下執行疑似出錯的程式路徑。
    程式碼庫指引 相關路徑、資料庫引擎、測試指令、允許的變更,以及負責審查結果的工程師。

    請勿在資料包中放入存取權杖、客戶的酬載內容或個人資料。

    監控整合為選用項目。如果使用監控整合,請只授予相關專案與時段的唯讀存取權。以檔案為基礎的流程無須整合監控。程式碼庫的指引應要求將測試憑證與正式環境設定分開管理。

    執行起始提示詞

    使用本頁的起始提示詞,將預留位置替換為你的事故 ID、程式碼庫與資料包路徑。第一份結果應說明證據與受影響程式碼之間的關聯、可以重現哪些行為,以及還缺少哪些資訊。

    只有在證據支持程式碼存在缺陷時,才請 Codex 繼續實作修正。否則,請先檢閱調查結果並補齊缺少的資料。看似合理的解釋、近期的程式碼變更,或在另一個發布版本上通過的測試,都不足以確定原因。

    範例:重試 webhook 時建立了重複訂單

    使用可執行的事故範例練習調查。範例包含備妥的事故資料包、有可重現缺陷的處理常式、修正後的處理常式,以及 PostgreSQL 測試。

    服務收到 order.created webhook 後,會寫入訂單,並記錄該事件已處理。事故發生時,一次重試似乎建立了第二筆訂單。團隊已讓服務恢復穩定,現在需要一份可供審查的修補。

    範例使用 TypeScript、Node.js 測試執行器與 PostgreSQL。這套用完即可移除的測試配置包含 event_receipts 資料表,其識別欄位不可為空值,且 (provider, account_id, event_id) 上設有不可延後檢查的唯一鍵。

    這份結構描述允許在訂單建立前先寫入收件紀錄,以取得事件處理權。紀錄中也保留了正規化酬載的指紋,可用來偵測同一事件鍵是否被用於不同的酬載。

    如果應用程式要求在取得處理權時就提供訂單外鍵,或缺少可供判斷衝突的證據,請先停下來,另行決定結構描述或設計應如何處理。

    請在證據中記錄確切的執行環境、鎖定的相依套件版本、PostgreSQL 版本、交易隔離層級與收件紀錄的結構描述。可下載的測試配置固定使用 Node.js 24.19.0、PostgreSQL 17.6 與 pg 8.23.1。

    使用隨附的 Compose 設定時,請準備一個 Docker 常駐程式能正常運作的環境,並在發布環境前確認 docker info 能順利執行。範例資料庫僅接受公開的測試憑證,且只繫結至本機回送介面。調整測試以配合自己的應用程式時,請使用該應用程式的資料庫引擎及相關設定。

    本範例假設 PostgreSQL 使用 READ COMMITTED 隔離層級、供應商的事件 ID 保持不變,且收件紀錄的保留期間涵蓋供應商可能重試或重播事件的時段。

    修正後的處理常式會在同一筆資料庫交易中寫入收件紀錄與訂單。測試配置會建立用完即可移除的資料庫和 delivery_holds 資料表,用來模擬既有佇列的隔離程序。該資料表僅供測試使用,並非建議應用程式執行的資料庫遷移。

    這項應用程式修正不會新增佇列、資料庫服務、結構描述遷移或監控整合。如果上述假設不成立,請先停下來,重新界定修正範圍。

    執行範例

    解壓縮 ZIP 檔案,進入解壓縮後的目錄,然後使用 Docker 與 Compose 執行以下指令:

    docker compose -p codex-incident-rehearsal up -d --wait postgres
    docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts baseline
    docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts regression
    docker compose -p codex-incident-rehearsal run --rm runner
    docker compose -p codex-incident-rehearsal down --volumes

    基準測試指令必須以結束碼 1 結束:重試後的斷言預期訂單和收件紀錄各一筆,實際卻觀察到兩筆訂單和一筆收件紀錄。迴歸測試指令會對修正後的處理常式執行相同斷言,且必須以結束碼 0 結束。

    最後一個測試指令會執行所有測試情境,包括獨立連線、資料庫鎖定競爭,以及隔離舊版留下的孤立訂單。

    如果安裝的版本提供 docker-compose,請用它取代 docker compose。請依序執行這些指令。測試套件只會重設其標記的測試結構描述。

    檢視交易處理常式

    這段程式碼摘自下載檔中的 main.ts。請在解壓縮 ZIP 後執行完整檔案,其中包含測試與測試配置的設定程序。

    取得事件處理權與寫入訂單的交易
    import type { Client } from "pg";
    
    type IncidentEvent = {
      provider: string;
      accountId: string;
      eventId: string;
      payload: { type: string; orderId: string; amountCents: number };
    };
    
    async function fixed(
      client: Client,
      input: IncidentEvent,
      hook = async (_boundary: string) => {}
    ) {
      await assertNotHeld(client, input);
      await hook("beforeClaim");
      await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");
      let committed = false;
      try {
        const claimed = await client.query(
          `INSERT INTO event_receipts(provider, account_id, event_id, payload_fingerprint)
           VALUES ($1,$2,$3,$4)
           ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING event_id`,
          [...key(input), fingerprint(input)]
        );
        trace("receipt-claim-result", client, input, {
          inserted: claimed.rowCount === 1,
        });
        if (claimed.rowCount === 1) {
          await hook("afterClaim");
          await writeOrder(client, input);
          await hook("afterOrder");
        } else {
          // A new READ COMMITTED statement sees the winner after its commit.
          await checkReceipt(client, input);
        }
        await client.query("COMMIT");
        committed = true;
        trace("transaction-committed", client, input);
        await hook("afterCommit");
        trace("acknowledged", client, input, acknowledgment);
        return acknowledgment;
      } catch (error) {
        if (!committed) {
          await client.query("ROLLBACK");
          trace("transaction-rolled-back-no-ack", client, input);
        } else {
          trace("committed-response-lost-no-ack", client, input);
        }
        throw error;
      }
    }

    1. 提供精簡的事故資料包

    可依照下列檔案安排資料包內容:

    incidents/INC-DEMO-014/incident.md
    incidents/INC-DEMO-014/logs.ndjson
    incidents/INC-DEMO-014/release.json
    incidents/INC-DEMO-014/order-created.sanitized.json

    在這個情境中,release.json 記載範例發布版本的提交 SHA 為 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413,部署時間為 2026-09-22T11:58:00Z。事故時段為同一天的 12:03:00Z–12:05:00Z。資料包指出,兩筆內部訂單對應到供應商的同一個事件。準備自己的資料包時,請列出已確認的受影響數量,並標明哪些數字是估計值。

    移除敏感資訊後的日誌包含下列可相互比對的觀察結果:

    UTC 時間 關聯資訊 觀察結果
    12:03:04.110 事件 evt_demo_042、帳戶 acct_demo_01、請求 req_demo_a、追蹤 trace_demo_a 首次投遞進入 webhook 處理常式。
    12:03:04.145 同一事件,第一次投遞的追蹤記錄 訂單 ord_demo_101 已提交。
    12:03:04.150 同一個工作程序 工作程序結束時,日誌中尚無收件紀錄寫入成功的訊息,也沒有回應紀錄。單憑這段摘錄無法證明收件紀錄不存在。
    12:03:14.203 同一供應商、帳戶與事件,請求 req_demo_b、追蹤 trace_demo_b 重試進入處理常式。處理常式在日誌中記下未找到相符的收件紀錄。
    12:03:14.241 同一事件,第二次投遞的追蹤記錄 訂單 ord_demo_102 已提交,並已寫入收件紀錄。

    同一事件的各次投遞應沿用相同的事件 ID,但每次投遞都應有各自的請求 ID 和追蹤 ID。如果只用每個請求專屬的識別碼,就看不出重試與原始事件的關係。

    2. 追查證據並驗證假設

    事故報告推測重試風暴造成了重複訂單。Codex 應將此說法視為假設。只觀察到兩次投遞,無法證明發生了重試風暴,而且重試本來就是 webhook 處理常式必須能應付的正常情況。

    檢視範例中受影響版本的原始碼,可以看出處理順序:先查詢收件紀錄,接著提交訂單,最後在另一筆交易中寫入收件紀錄。兩次提交之間的空檔更能解釋重複訂單的成因。如果工作程序在這段空檔失敗,可能留下一筆沒有收件紀錄的訂單,之後重試時就可能再建立一筆訂單。同時投遞的兩個請求也可能在任何一方寫入收件紀錄前,各自通過獨立執行的檢查。

    請 Codex 追查實際的處理常式與交易邊界,並引用相關程式碼行。它應確認資料包記載的發布版本與受測程式碼相符,或說明測試不同的提交版本會如何限制能得出的結論。

    3. 先重現問題,再變更處理常式

    使用範例 webhook 與隔離的 PostgreSQL 資料庫新增迴歸測試。在原始處理常式中,緊接在寫入訂單之後、寫入收件紀錄之前,加入僅供測試使用的故障注入掛鉤。

    依據實際的交易邊界,確認原始訂單在該處已提交。針對相同的供應商、帳戶與事件重試,並以斷言檢查是否恰好有一筆訂單和一筆相符的收件紀錄。範例中帶有缺陷的實作應會產生兩筆訂單,導致測試失敗。

    修正後,在執行訂單寫入陳述式之後、共用交易提交之前觸發對應的掛鉤。這次失敗的嘗試必須留下零筆訂單與零筆收件紀錄。

    再次重試,並以斷言確認兩者各有一筆。各版本都應使用相同的業務行為斷言,並記錄每個版本中掛鉤的位置。

    先在原始實作上執行新測試。針對本範例預先埋入的缺陷,預期的失敗結果是出現兩筆訂單,而非一筆。請儲存指令、起始提交、結束碼與斷言輸出。如果未出現預期的失敗,請先調查結果不符的原因,再編輯處理常式。

    注入例外狀況可以測試應用程式的交易行為。請在紀錄中註明,這項測試無法重現所有可能的主機、網路或資料庫故障。

    4. 採取證據支持的最小修正

    針對這個特定缺陷,請使用同一條資料庫連線,在同一筆交易中插入收件紀錄以取得事件處理權,並寫入訂單。搭配既有的唯一鍵使用 INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ...。

    只有成功插入收件紀錄的那次投遞可以寫入訂單,且必須等交易提交後才能回覆成功。交易失敗時,兩次寫入都會回滾。請勿在捕捉違反唯一性約束的錯誤後,繼續使用已中止的交易。

    另一個競爭處理權的投遞可能需要等待第一筆交易。如果第一筆交易提交,第二次嘗試就不會插入收件紀錄。此時應在 READ COMMITTED 隔離層級下重新執行 SELECT,依事件身分與酬載的處理規則核對已儲存的資料,然後傳回既有的重複投遞確認回應,不再寫入訂單。

    如果第一筆交易回滾,另一個投遞就能取得處理權並處理事件。如果略過插入後找不到收件紀錄、事件身分有衝突,或資料庫發生暫時性錯誤,都必須依文件所述的重試或錯誤處理流程辦理,不得逕行回覆成功。

    在更嚴格的隔離層級下,若發生序列化失敗,必須依程式碼庫的規則重試整筆交易,並遵守重試上限。請參閱 PostgreSQL 的 INSERT 衝突處理行為與交易隔離說明。

    無論是記憶體中的集合,還是分開執行的「先檢查,再插入」,都無法防止工作程序並行執行或重新啟動時發生重複處理。事件鍵的適用範圍應符合供應商對事件身分的定義。如果兩次投遞理應代表同一事件,但其身分或酬載資訊互相衝突,請明確回報不一致之處,不要默默當成有效的重複投遞處理。

    本範例的業務資料變更全部發生在同一個資料庫中。如果實際的處理常式也會寄送電子郵件、向信用卡請款或呼叫其他服務,單靠這筆交易無法確保這些外部操作具備冪等性。在擴大修正範圍前,請先確認哪些操作位於交易之外,以及系統既有的投遞或冪等機制。

    5. 驗證修正後的行為

    請 Codex 提供原始版本的失敗結果與修正後的結果。在明確標示的交易邊界使用測試專用掛鉤,並從另一條連線檢查已提交的狀態。範例通過了十一項本機 PostgreSQL 測試。下載檔中的 test-evidence.md 記錄了這些結果,以及在雲端執行和部署時仍需完成的檢查。請在已發布的環境中執行測試套件,並實際測試提交期間連線中斷的情況,再採信該復原流程。

    檢查項目/故障點 必須符合的行為
    首次投遞與提交後的重複投遞 首次投遞建立一筆訂單和一筆收件紀錄。再次投遞同一事件時,應傳回約定的確認回應,且筆數維持不變。請記錄確切的回應狀態與本文。
    取得事件處理權之前 失敗時不會建立訂單或收件紀錄,也不會回覆成功。重試後,訂單和收件紀錄各建立一筆。
    取得處理權之後、寫入訂單之前 失敗時會回滾收件紀錄,且不存在訂單。重試時可以正常取得處理權並處理事件。
    寫入訂單之後、提交之前 失敗時會回滾兩筆資料。這是在修正後的程式碼中,對應原本「訂單已提交但缺少收件紀錄」缺陷的測試點。重試後兩者應各有一筆。
    提交之後、回覆確認之前 模擬回應遺失。兩筆資料仍維持已提交狀態。重試時會傳回重複投遞的確認回應,不會再建立訂單。
    提交結果不明 將提交前後發生連線中斷的情境與一般例外狀況分開模擬。沒有依據時不得回覆成功。無論第一筆交易已提交或已回滾,使用同一個事件鍵重試都必須安全。如果未測試這種傳輸中斷情境,請標記為未執行。
    同時重複投遞:第一筆交易提交 讓兩個工作程序使用各自獨立的連線競爭同一事件鍵。先暫停取得處理權的一方,並在放行前啟動另一方。確認另一方確實在等待取得該鍵,再放行先取得處理權的一方。兩者都應依預期的確認回應流程完成,且資料庫中恰好只有一筆訂單和一筆收件紀錄。
    同時重複投遞:第一筆交易回滾 重複上述受控的並行情境,但讓已取得處理權的一方在提交前失敗。交易回滾後,另一方應能取得處理權,建立一筆訂單和一筆收件紀錄。請檢查雙方的回應與最終狀態。
    事件身分與酬載衝突 不同事件應各自獨立處理。不同帳戶或供應商下,即使事件 ID 相同,也應各自獨立處理。如果同一範圍內的事件 ID 相同,但正規化後的酬載互相衝突,請依約定的衝突處理流程辦理。不得建立第二筆訂單,也不得將內容不同的操作默默確認為已處理。
    舊版訂單缺少收件紀錄,且有待處理的重試 預先建立一筆已提交但沒有收件紀錄的舊版訂單。在恢復重試前,找出並暫停處理該事件鍵。遭暫停的重試不會收到成功回應,也不會建立任何資料列。依可信證據完成核對後,可以傳回重複投遞的確認回應,此時應有一筆既有訂單與一筆收件紀錄。如果證據缺失或互相衝突,該鍵必須維持暫停狀態。
    服務的其他檢查 執行相關整合測試、lint 與型別檢查。分別列出新出現的失敗、原本就存在的失敗,以及無法執行的檢查。

    請使用同步屏障或閂鎖協調並行執行,並設定等待時間上限。不要靠固定延遲或僅啟動兩個 Promise 來控制時序。在測試清理階段放行受阻的工作程序,並使用用完即可移除的測試配置。單靠例外狀況測試,無法確認程序突然終止、傳輸中斷或正式環境中發生並行投遞時,處理常式會如何運作。

    範例會在版本固定的執行器內使用 node --experimental-strip-types main.ts baseline、node --experimental-strip-types main.ts regression 與 node --experimental-strip-types main.ts。其結構化輸出會記錄交易邊界、已提交的資料列數量、確認回應的狀態與本文,以及觀察到造成阻塞的資料庫後端程序 ID。

    調整這套流程時,請使用程式碼庫實際定義的指令,並報告實際執行結果。如果略過某項檢查或缺少必要的相依套件,應在交接資料中註明,並說明這會如何影響對結果的信心。

    檢閱交接資料

    共用的證據紀錄

    請依事故處理流程的證據格式,逐項記錄每個驗收條件。以下欄位是範本,請依實際觀察到的輸出填寫,不能直接當成通過結果。如果基準版本中還沒有新增的測試,請區分「尚無此測試」與既有檢查執行失敗。

    Criterion / test: [specific behavior and test location]
    Environment: [published setup reference; runtime, database and dependency versions]
    Before: [revision + test-only diff ID; command; exit code; observed assertion; log path]
    After: [final revision or base + diff ID; command; exit code; observed assertion; log path]
    Status: [pass / fail / blocked / not run]
    Limits / reviewer action: [untested behavior, blocker, or decision required]

    每次失敗與通過的測試都應對應到實際受測的程式碼狀態,包括在原始版本上僅為測試而加入的變更。交接時一併保留日誌、測試用回應資料與最終差異檔。最終版本若有變更,必須更新證據。未執行或受阻的檢查不能算作通過。

    請 Codex 將程式碼差異檔與以下審查資料留在程式碼庫中:

    • incident-investigation.md:時間軸、證據出處、檢驗過的假設、有證據支持的原因,以及仍不確定之處。
    • test-evidence.md:基準提交、失敗的迴歸測試輸出、修正提交或差異檔、已通過的針對性檢查、其他範圍較廣的檢查,以及驗證限制。
    • pr-draft.md:簡要說明缺陷、修正後的行為、測試證據及剩餘風險。
    • deployment-handoff.md:已驗證的結構描述、隔離層級與收件紀錄保留期限等假設,部署負責人姓名、部署前檢查、重複訂單與確認回應/錯誤指標,以及下述部署與回復條件。

    接受修補前,請確認原始程式碼無法通過新測試、修正後能通過,而且程式碼差異確實處理了測試所證實的缺陷。在 webhook 範例中,請檢查事件鍵的適用範圍、交易邊界、並行測試的涵蓋範圍,以及交易以外的任何影響。請另外檢閱既有的重複訂單。防止新增重複訂單無法修復歷史紀錄。

    規劃部署與回復

    程式碼修補只能保護執行新版處理常式的工作程序。舊版工作程序仍可能在取得事件處理權前寫入訂單,因此新舊版本並存的金絲雀部署無法證明缺陷已消除。

    部署負責人必須選擇已測試的新舊版本並存策略,或依照既有操作手冊,暫停接收事件,等待舊版工作程序完成處理中的工作,更新所有消費者,再恢復處理保留的投遞,確保沒有資料遺失。

    選擇後一種做法前,請確認供應商與佇列的重試及保留行為。不可假設暫停一定不會造成遺失。

    恢復處理保留的投遞之前,請找出已提交但沒有相符收件紀錄的舊版訂單。暫停舊版消費者並等待其完成處理中的工作,可以防止舊版再寫入資料,卻無法修復已存在的訂單。請使用既有佇列或隔離程序,暫停處理每個受影響的事件鍵。如果舊版紀錄不足以確認完整的事件身分,請繼續暫停受影響的投遞,或暫停受影響時段內的投遞,交由負責人審查。此時不可宣告掃描完成。

    只有在可信且不可變更的供應商、帳戶與事件識別資訊、正規化酬載的證據,以及已提交的業務紀錄足以共同確認先前實際執行了哪些操作時,才可核對並補齊該事件鍵的紀錄。

    依照已核准的核對程序,補寫相符的收件紀錄,不要再次執行業務資料變更。完成後,再解除該事件鍵的暫停狀態。

    如果證據缺失、酬載互相衝突,或存在多筆業務紀錄,請讓受影響的事件鍵維持隔離,交由負責人審查。重建原始事件的指紋時,不可用重試時的酬載取代原始事件的可信證據。

    恢復處理前,請逐一確認每個受影響的事件鍵:只有已完成核對,或所有消費者都仍強制暫停處理該鍵,才算通過這項檢查。

    請在預備環境中預先建立一筆舊版訂單,並安排一次待處理的重試。確認暫停處理能防止建立另一筆訂單,且不會回覆成功。依可信證據完成核對後,重試可以收到重複投遞的確認回應,而既有訂單數量應維持一筆。也請演練無法完成核對的情境:事件鍵必須維持暫停狀態,不得憑空建立收件紀錄。請在部署交接資料中保留這項恢復條件,並一併列出暫停接收與等待處理完畢、消費者版本、保留行為及回復檢查。

    部署前,請確認既有的唯一性約束存在且有效,所有消費者都採用一致的收件紀錄鍵與酬載處理規則,清理收件紀錄不會讓仍可能重播的事件再次被處理,而且外部操作仍不在本次修補範圍內。

    在預備環境中演練選定的部署順序,以及工作程序失敗後的重試。記錄負責人設定的觀察時段,並列出重複訂單、webhook 錯誤、確認回應延遲、鎖定等待與待重試事件積壓量各自的停止部署門檻。請勿自行臆定正式環境的門檻。

    回復舊版處理常式可能再次造成重複訂單。回復交接資料必須明列控制影響的步驟(例如已核准的暫停接收並等待處理完畢程序)、可安全使用的版本,以及有權決定何時恢復處理的負責人。請保留收件紀錄,不要為了讓重試繼續而刪除紀錄。歷史上的重複訂單須另行提出補救措施並接受審查。

    工程師負責部署決策與正式環境中的任何補救措施。隔離測試通過可作為審查證據,無法證明正式環境運作正常。請建立 pull request,執行平常的 CI 與審查流程,並在檢閱草稿後,依團隊既有的管控程序部署。

    在同一個任務中繼續

    使用範圍明確的後續提示詞,釐清疑點或補強交接資料:

    請針對兩種情境審查這份修補:兩次投遞並行處理,以及工作程序失敗後重試。說明測試已證實哪些行為,以及哪些行為尚未測試。將變更範圍限定於這個處理常式及其迴歸測試,並在交接資料中補上仍存在的風險。

    如果第一次執行時無法重現事故:

    請停止實作。列出證據已排除的假設,指出其餘假設中最有根據的一項,並說明要將它與其他可能原因區分開來,最少還需要補充哪些已移除敏感資訊的資料,或進行什麼最小規模的隔離實驗。請將根本原因保留為「尚未確認」。

    相關應用案例