Stripe webhook の信頼性土台(inbox 方式・冪等・取りこぼし突合)を決める

背景

#17 は Stripe webhook(invoice-paid)の実装 issue だが、その土台となる信頼性の設計方針が未確定。Stripe のイベントは仕様上、重複・順序不定・遅延・配信失敗が必ず起きる。

なぜ今決めるか

冪等・取りこぼし耐性を後から付けると、二重計上や記録欠損が既に台帳に生じた後になり、どの入金が欠けたかを判定する根拠が残らない。webhook を入金記録の唯一の入力にすると、配信保証が無いぶん恒久的な穴が生じる。この土台を #17 実装前に決める必要がある。

論点・選択肢

• inbox 方式: 受信イベントを Stripe event id の一意制約付きでまず永続化し、その上で状態更新を同一トランザクション内で行う。処理済みフラグと状態更新を束ねて exactly-once に近づける。
• 順序不定への耐性: イベント種別ではなく対象オブジェクトの現在状態を Stripe で確認して収束させるか、created で新旧を判定するか。
• 「入金の真実は webhook イベントであり、同期レスポンスやブラウザのリダイレクト完了ではない」を原則として固定する(会員化・台帳確定の書き込みは webhook のみを起点にする)。
• 取りこぼし対策: 配信は保証されない前提で、Stripe を入金イベントの上流の真実として突合し、欠損を埋める定期リコンサイル/バックフィル経路を土台として設計する(実行基盤は非同期処理基盤の決定に依存)。

受け入れ条件

• イベント受信テーブルの存在・トランザクション境界・購読イベント型・突合方針が決まり、#17 の実装前提として文書化されている。

関連

#17(webhook 実装)の土台(親)。お金の記録アーキテクチャ、非同期・定期処理基盤の決定に依存/接続する。

Start by reading issue #17 and the connected decisions about the payment ledger and asynchronous or scheduled processing. Define the inbox table, transaction boundary, subscribed event types, ordering policy, and reconciliation approach. Done means these reliability decisions are documented as implementation prerequisites for #17.