収集（キャプチャ）は簡単だが、ファイナライズはな​​ぜ難しいのか？ (Why Payment Capture Is Easy But Finalization Is Hard)

一歩、六歩

「支払いを受け取った」と言うとき、通常は 1 つのことを意味します。それは、プロバイダー ゲートウェイが PSP にリクエストを送信し、PSP が「お金を受け取りました」と通知したことです。 1 回の電話、1 回の応答、1 回の確認です。しかし、「注文が完了した」というのは、もっと大きな意味を持っています。つまり、在庫が差し引かれ、財務記録が開かれ、注文が確認され、顧客に通知され、バスケットが空になり、ロイヤルティ ポイントが処理されたということです。```text Capture: Checkout Orchestrator → Provider Gateway → PSP → “alındı”

Finalization: Stok düş + Finans kaydı + Sipariş onayı + Bildirim + Sepet temizliği (altı bağımsız adım, altısı da ayrı ayrı başarısız olabilir)

## 最初に説明した概念```text
📦 Capture
PSP'nin, önceden ayrılmış veya doğrudan istenmiş bir tutarı fiilen tahsil ettiğini bildirmesi; tek bir dış sistem gerçeğidir.

📦 Finalization
Capture'dan sonra işin gerçekten bitmesi için gereken tüm iç adımların toplamı: stok, finans, onay, bildirim, temizlik.

📦 Saga
Birden fazla adımı, her biri kendi başarısızlık ve telafi mantığıyla, uçtan uca yöneten bir iş akışı deseni.

📦 Telafi Adımı (Compensating Action)
Bir saga adımı geri alınamadığında, önceki adımların etkisini dengelemek için çalıştırılan ters işlem.

📦 Adım İşaretçisi (Step Marker)
Bir saga adımının tamamlandığını kalıcı olarak işaretleyen kayıt; yeniden çalıştığında adımın tekrarlanmasını önler.
```Capture の容易さは、Capture が単一の参加者 (PSP) と単一の応答に依存しているという事実から来ています。ファイナライズの難しさは、独立して失敗する可能性のある多数の参加者に依存しているという事実から生じます。

## Capture が簡単な理由

Capture の成功基準は、PSP が「集めました」と言ったかどうかという一文です。この情報は同期応答または Webhook とともに提供され、その署名が検証され、関連する支払いレコードが `Captured` になります。ここでは、複数のデータベースへの書き込み、複数のサービス呼び出し、相互依存する一連のステップはありません。外部システムからの「はい/いいえ」の答えがあります。```text
Provider Gateway --istek--> PSP
Provider Gateway <--"captured"-- PSP
                        ↓
                Payment.Status = Captured
                (bir yazma, bir karar)
```## ファイナライズが重要な理由

キャプチャが完了したら、作業は終わりではありません。本当に複雑な部分はこれから始まります。注文が「本当に完了した」とみなされるには、次のすべてのステップが、すべて完了するまで、任意の順序で確実に実行される必要があります。```text
Finalization Saga
  1. Stok Servisi'nde rezervasyonu kesin düşüşe çevir
  2. Finans/Ledger'da gelir kaydını aç
  3. Sipariş satırlarını “onaylandı” olarak işaretle
  4. Müşteriye bildirim gönder
  5. Sepeti/aktif intent'i temizle
  6. (Varsa) sadakat puanı veya kampanya etkisini işle
```これら 6 つのステップにはそれぞれ独自のエラー パターンがあります。在庫サービスが一時的に利用できなくなる可能性があり、財務サービスが検証エラーをスローする可能性があり、通知サービスがタイムアウトになる可能性があります。 Capture には「はい/いいえ」が 1 つだけありました。ここには 6 つの独立した「はい/いいえ」があり、そのどれもが他方を保証するものではありません。

## 部分的な終了処理: 最も危険な中間状態

最も困難なシナリオは、物語の半分が機能し、半分が機能しない場合です。たとえば、株式は減額されましたが、財務記録を開くことができませんでした。システムがクラッシュしたため、作業者は再起動時にどの手順が完了したかを知る必要があります。```text
Finalization saga çalışıyor
  ✓ Stok düşüldü
  ✓ Sipariş onaylandı
  ✗ Finans kaydı — worker crash oldu
  ? Bildirim — henüz denenmedi

Worker yeniden başlar: Hangi adımları TEKRAR çalıştırmalı, hangilerini ATLAMALI?
```ステップマーカーがなければ、この質問に答えることはできません。各ステップは、その完了ステータスを永続的に記録する必要があります。それ以外の場合、ワーカーが再起動すると、最初から全体を実行して在庫を 2 回減らすか、何もせずに注文が永遠に未完了のままになります。

## この区別が当然のこととみなされる理由

ほとんどのチームが「支払いの統合」と言うとき、それはそれを毎週の仕事として把握して計画することだけを意味します。ファイナライゼーションの物語は一般に「詳細」とみなされ、適切に設計されないまま本番環境に入ります。実際には、このシリーズの最初の 2 つのパートで示したように、キャプチャは単一の外部システムと通信しています。ファイナライズには、独自のシステムが自身のエラーに耐えられる必要があります。後者には、はるかに大きなエンジニアリング投資が必要です。

## このエピソードで最も混乱を招く対戦```text
❌ Ödeme entegrasyonu = Capture'ı çalıştırmak
✓ Ödeme entegrasyonu = Capture + finalization saga'sının tamamı

❌ Capture başarılı olduysa iş bitmiştir
✓ Capture, finalization saga'sının başlangıç tetikleyicisidir, bitişi değil

❌ Saga adımlarının sırası önemli değildir, hepsi “aynı işlem”dir
✓ Her adım bağımsız başarısız olabilir; her birinin kendi retry ve telafi mantığı gerekir

❌ Worker crash olursa saga'yı baştan çalıştırmak güvenlidir
✓ Adım işaretçisi olmadan baştan çalıştırmak, tamamlanmış adımları tekrarlayıp yan etki üretir

Finalization saga のテストのリスト

1. ファイナライゼーションのステップを書き留めます。ステップはいくつあり、どのステップが個々のサービスに行きますか?
2. 各ステップがそれ自体で冪等であるかどうかをテストします。同じステップを 2 回実行すると結果は変わりますか?
3. 物語の途中で意図的に労働者を殺します (カオス テスト)。再び始めるとき、どのステップをスキップし、どのステップを繰り返すでしょうか?
4. 各ステップには障害シナリオに対する補償や再試行の計画がありますか? それとも「このステップは必ず成功する」という前提で書かれていますか?
5. キャプチャは成功したが、ファイナライズの話がまだ始まっていない場合、これを認識するまでに何分かかりますか?

これら 5 つのテストのうち 2 つで失敗した場合、最終処理の手順は、エラー パスではなく「ハッピー パス」を想定して書かれている可能性があります。

このセクションで覚えておくべきこと

1. キャプチャは、単一の外部システム (PSP) からの「はい/いいえ」の回答です。シンプルさの由来はここにあります。
2. ファイナライゼーションは、すべてを完了するために複数の独立したステップを必要とする一連の作業です。ここが難しさの原因です。
3. 部分的なファイナライズ (一部のステップは OK で、一部のステップは OK ではない) は最も危険な中間状態であり、ステップ ポインターなしでは安全に回復できません。
4. 「支払いの統合」が回収のみを対象とする場合、プロジェクトの最もリスクの高い部分が計画から除外されます。

キャプチャはPSPがあなたに同意した瞬間です。ファイナライズとは、自分のシステムに同意することですが、通常はそれがより難しい部分です。