Payment Webhook Doctor
從證據開始，不要直接重送。將事件重複送入有問題的處理程式可能會重複其副作用。
一次專注單一任務
| 問題 | 參考文件 |
|---|---|
| 簽章失敗、錯誤的密鑰、解析後的內文、舊版傳遞 | references/signatures.md |
| 重複計入額度、延遲履行、成功後失敗、退款順序錯亂 | references/reconciliation.md |
| 4xx/5xx/逾時、復原、遺失事件、正式環境上線 | references/incident-playbook.md |
| 需要經過驗證的通訊協定事實與版本邊界 | references/sources.md |
| 需要非 Stripe / M-Pesa 的轉接器 | references/provider-boundary.md |
工作流程
- 建立範圍：提供者、快照與瘦事件的區別、測試/正式模式、已連結帳號、端點框架與 API 版本。僅針對會改變診斷結果的缺失事實進行提問。
- 檢查處理程式碼、遷移檔案、預期訂單金額/幣別、伺服器建立的 PaymentIntent 對應，以及經過編輯的傳遞中繼資料。將簽章密鑰保留在本機環境變數中。不要要求使用者將密鑰或客戶內文貼到對話中。
- 在解析 JSON 之前，先驗證原始請求的確切位元組。對於已部署的處理程式，建議使用官方 Stripe SDK。內建無相依性的驗證器是一個小型、可檢查的診斷參考工具，並非替代 SDK。
- 先使用以下本機工具搭配合成測試夾具重現錯誤。將證據分類為「觀察到的」、「推斷的」或「未經驗證的」。有效的簽章僅能驗證傳遞的真實性，不能證明訂單應該被履行。
- 修復最小原因並新增回歸測試。將付款綁定至受信任的伺服器端訂單；比對金額、幣別、帳戶範圍及模式。將收件匣、帳本更新與副作用意圖保持在同一個資料庫交易中。
- 驗證重複事件、相同物件的不同事件、重新啟動、交付順序錯亂、失敗的事件，以及部分/全額退款。不要將事件時間戳記作為總排序機制。
- 提供調查結果、修補程式、測試證據、未解決的整合需求，以及明確的回退/復原計畫。未經使用者授權的工作流程，請勿進行部署、重送正式事件、發出退款或轉帳。
本機工具
從此技能根目錄執行：
npm test
npm run demo
使用已記錄的測試夾具時鐘檢查已儲存的測試模式夾具：
export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
--secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
--normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
--orders fixtures/orders.json < /tmp/payment-doctor-event.json
export 指令拒絕覆寫現有檔案。請使用新的輸出路徑，或自行有意識地刪除自訂的合成輸出。Python CLI 僅會寫入明確指定的本機 SQLite 資料庫。它預期接收驗證器的受信任正規化輸出；它本身不會驗證簽章。切勿將其暴露為公開的 Webhook 端點。
正常的診斷報告會排除客戶資料、原始酬載與簽章。明確的正規化匯出則會保留本機對帳所需的身分識別碼與整數金額。請保持其私密性，並排除在版本控管之外。
--fixture-now 僅適用於舊的合成測試事件；它會拒絕接收正式模式的輸入。對於一般的當前傳遞，請省略此參數。參考帳本會拒絕正式模式的事件，從不呼叫 Stripe，也從不傳送外寄信箱的資料列。
必備報告
- 結果： 發生什麼事以及是否已重現。
- 證據： 檔案/行數、經過清理的傳遞中繼資料、確切指令、觀察到的結果。
- 根因： 已確認的原因與剩餘的假設。
- 修復： 最小修補程式加上遷移/回補的影響說明。
- 回歸矩陣： 重複、重新啟動、範圍不符、金額/幣別錯誤、順序、退款案例。
- 營運交接： 仍需要的測試模式整合證據；安全重放與回退的標準。
邊界
支援範圍刻意狹窄：Stripe 快照 payment_intent.succeeded、payment_intent.payment_failed 與退款物件事件。瘦事件、訂閱授權、Checkout Session、爭議、多重擷取付款語意、應用程式費用、稅金以及 Connect 轉帳，需要專用的轉接器。無發現結果不等同於安全認證或資金已到帳的證明。在擴充功能前請先參閱參考文件。