支払い回収パイプラインとランブック (Payment Recovery Pipeline And Runbooks)

前のセクションでは、支払い ID、ステップ イベント ログ、および遅延ファイナライズ メトリクスとの相関が操作にどのようにフィードされるかを見てきました。このセクションでは、その可視性に基づいて構築された回復パイプラインについて説明します。支払いが滞った場合、システムは最初に独自に何ができるのか、そしていつ人間が介入するのか?

優れた回復パイプラインの原則はシンプルです: 最初に自動化。調整ワーカー、スタックウォッチャー、再試行ワーカー - これらは人間の介入を必要とせずにほとんどのドリフトを解消します。人間の運用手順書が機能するのは、自動化が独自性や証拠があいまいという壁にぶつかった場合のみです。```text Ödeme takıldı → otomatik: reconciliation scan → otomatik: retry with backoff → otomatik: PSP status query → insan: uniqueness wall / ambiguous evidence

## 最初に説明した概念```text
📦 Recovery Pipeline
Takılan veya tutarsız ödemeleri otomatik olarak teşhis edip düzeltmeye çalışan ardışık işlem hattı.

📦 Uniqueness Wall
Veritabanı benzersizlik kısıtının, güvenli replay veya heal girişimini engellediği durum.

📦 Evidence-Driven Runbook
Her adımın hangi kanıta (step log, PSP sorgusu, audit) dayandığını tanımlayan operasyon kılavuzu.

📦 Manual Review Queue
Otomasyonun çözemediği kayıtların biriktiği, görünür bekleme alanı.
```Runbook は「何をすべきか」という質問に答えます。証拠主導のランブックは、「証拠がなければ何ができないのか?」という質問に答えます。

## 自動化前: 回復パイプライン層

回復パイプラインは単一のワーカーではなく、相互に補完するレイヤーです。各レイヤーは、前のレイヤーでは解決できなかったことに対処します。どちらも次の仕事をしようとすべきではありません。```text
Katman 1: Retry worker
  → transient hataları backoff ile tekrar dener

Katman 2: Stuck watcher
  → lease süresi dolmuş, Processing'de kalan kayıtları sıfırlar

Katman 3: Reconciliation sweeper
  → aged FinalizePending / Expired kayıtları PSP ile karşılaştırır

Katman 4: Manual review queue
  → otomasyonun çözemediği kayıtlar
```レベル 1 ～ 3 は完全に自動であり、1 日のほとんどはこれで十分です。レイヤ 4 はパイプラインの障害ではなく、その境界が可視化されていることです。

## 独自性の壁: 自動化が止まる場所

リコンシリエーションワーカーは PSP から「成功」を確認し、ローカル レコード `Captured` を作成しようとしますが、データベースには同じ冪等キーを持つ行 `Captured` がすでに存在します。挿入または更新が失敗します。自動化が停止します。```text
Reconciliation: payment #5521 → PSP says Captured
  → local UPDATE attempt
  → UNIQUE constraint violation on idempotency_key
  → otomasyon durur
  → manual review queue'ya yaz
```これはバグではなく、保護メカニズムです。一意性の壁は二重ファイナライズを防ぎますが、自動化が「問題は解決した」と言うのを防ぎます。ここで、証拠に基づいたランブックが役に立ちます。

## 証拠に基づいた運用手順書: 反射的ではなく手順

人間の介入が必要な場合、Runbook は次の順序に従います。```text
1. Step event log'u oku (payment id ile)
2. PSP status query yap (provider gateway üzerinden)
3. Local kayıtları karşılaştır (payment, order, idempotency)
4. Kanıt tablosunu doldur
5. Karar: heal / refund / no-action
6. Audit kaydı yaz
```ランブックのすべての意思決定ポイントには証明が必要です。 「PSP は Captured but local Expired と言っています」 → 回復候補。 「PSP が見つかりません。ローカル処理中」 → 払い戻し、待機、またはエスカレーションの対象ではありません。 「キャプチャされた 2 つの行、異なる冪等キー」 → 二重に請求され、一方は返金されます。

## 手動レビューキュー: 表示される待機時間

自動化によって解決できないレコードは、静かに消えてはいけません。手動レビューキューは、これらの記録が蓄積され、古くなり、優先順位が付けられる目に見える領域です。

|エリア |目的 |
| --- | --- |
|支払いID |相関関係 |
|スタックした理由 |独自性の壁 / 曖昧な証拠 / PSP不明 |
|証拠概要 |ステップログ+PSPクエリまとめ |
|同上 |彼はどれくらい待っています |
|優先順位 |金額、顧客からの苦情、SLA |

キュー内の各レコードは Runbook ステップと一致する必要があります。オペレーターはキューから「何をすべきか」という質問を読み取ることができる必要があります。

## Runbook の例: 一意性の壁の後```text
Durum: reconciliation Captured yazamadı — idempotency_key conflict

Kanıt toplama:
  □ Step log: FinalizeAttempted iki kez mi?
  □ Mevcut Captured satırı hangi webhook'tan geldi?
  □ PSP query: kaç charge var bu correlation id ile?

Karar ağacı:
  → Tek PSP charge, local çift satır → eski satırı audit ile kapat
  → İki PSP charge → birini refund et (runbook: duplicate charge)
  → PSP charge yok → local Captured yanlış → escalate

混同されやすい区別```text

❌ Manual review queue = otomasyon başarısız oldu ✓ Manual review queue = otomasyonun sınırı görünür ve güvenli

❌ Runbook = deneyimli mühendisin sezgisi ✓ Runbook = kanıt tabanlı, tekrarlanabilir prosedür

❌ Uniqueness wall kaldırılmalı ✓ Uniqueness wall korunmalı; runbook duvarın ötesini yönetir

|ステータス |自動化 |人間のランブック |
| --- | --- | --- |
|一時的なタイムアウト |ワーカーを再試行 |必要ありません |
|期限切れのファイナライズ保留中 |和解 |必要ありません |
|べき等性の競合 |彼は立ち止まってキューに書き込みます。証拠を集めて決定する |
|あいまいな PSP の応答 |彼は立ち止まってキューに書き込みます。エスカレーションするか待つ |

## 回復パイプラインのチェックリスト

1. 再試行レイヤー、スタックウォッチャーレイヤー、および調整レイヤーは個別に、順番に動作しますか?
2. 一意性制約違反は手動レビュー キューに自動的に書き込まれますか?
3. ランブックの各ステップでは、どのような証拠が必要かを明確に定義していますか?
4. 手動レビュー キュー内のレコードは経過時間と優先度によって並べ替えられていますか?
5. 人間の介入後の監査記録とステップイベントログエントリは必須ですか?
6. オートメーションによって解決されたレートはメトリクス的に追跡されていますか (automation_resolution_rate)?

## この記事で覚えておくべきこと

1. 回復パイプラインは自動化第一原則に基づいて階層化されています。人間は最後の手段です。
2. 独自性の壁が自動化を阻止します。この保護はバグではありません。
3. 運用手順書は証拠に基づいている必要があります。反射的な動作は危険です。
4. 手動レビューキューにより、未解決のレコードが静かに消えるのを防ぎます。

> 優れた回復パイプラインは人間の介入をゼロにしようとするものではありません。人間の介入を適切な瞬間、適切な証拠、適切な手順に限定します。

次のセクションでは、メッセージング層について説明します。1 回だけというのは嘘です。多層防御で一度の作業で効果的に結果を得るにはどうすればよいでしょうか?