本番決済エンジンの設計 (Designing A Production Payment Engine)

このシリーズはプロバイダーの抽象化から始まり、Webhook の信頼性、冪等性、サガ、リース、コンセンサス、可観測性、回復パイプライン、事実上 1 回の処理に進みました。この最後の技術セクションは、その過程を総合したものです。実稼働環境で実行される決済エンジンを設計している場合、どの決定をどの順序で行う必要がありますか?

チェックリストは機能のリストではありません。各項目は、シリーズの 1 つまたは複数の部分で提唱されている原則を測定できるテストです。 「冪等性はあるのか？」ではありません。質問は、「冪等性キー API、Webhook 重複排除、DB 一意性トリオは連携しますか?」です。```text Production Payment Engine ├─ Boundaries (orchestrator ↔ gateway) ├─ State & Evidence ├─ Reliability (retry, lease, outbox) ├─ Recovery (reconciliation, runbooks) └─ Observability (payment id, step log, metrics)

## 最初に説明した概念```text
📦 Checkout Orchestrator
Ödeme niyetini yöneten, semantik sonuç gören, PSP detayı bilmeyen servis.

📦 Provider Gateway
PSP SDK'sını, webhook çevirisini ve provider'a özgü akışları sahiplenen servis.

📦 Production Readiness
Sistemin sadece happy path'te değil, arıza, yarış ve sürüklenme anlarında da doğru davranması.

📦 Architectural Checklist
Tasarım kararlarının ölçülebilir, evet/hayır testlerine dönüştürülmüş hali.
```本番決済エンジンは「チャージ API が動作している」ことを意味するものではありません。これは、「チャージが失敗し、Webhook が遅れて到着し、ワーカーがクラッシュした場合はどうなりますか?」という質問に答えるためのものです。

## 1. 制限: SDK リークなし

- [ ] Checkout オーケストレーターは PSP SDK タイプをインポートしませんか?
- [ ] Orchestrator はセマンティック `ChargeRequest` / `ChargeResult` のみを認識しますか?
- [ ] Webhook は生のプロバイダー ペイロードとして、またはセマンティック イベントとしてダウンストリームに到達しますか?
- [ ] プロバイダー ゲートウェイは、プロバイダー イベント → セマンティック イベント マッピング テーブルの唯一の所有者ですか?
- [ ] 新しい PSP を追加するには、オーケストレーター コードへの変更は 0 行も必要ありませんか?

このエピソードはシリーズのエピソード 9 ～ 10 です。それはその部分の本質です。境界が壊れると、残りのすべての層がそのリークの上に構築されます。

## 2. 状態と証拠: 状態 ≠ 証拠

- [ ] 支払いステート マシンは明確に定義されていますか (Processing、FinalizePending、Captured、Failed、Expired)?
- [ ] ターミナルステータスは元に戻せませんか?
- [ ] 支払いスナップショット (金額、通貨、バスケット) は不変ですか?
- [ ] PSP からの証拠 (Webhook、同期応答) は別の証拠テーブルに保存されていますか?
- [ ] 状態遷移は証拠または仮定に基づいていますか?

## 3. 信頼性: 再試行、リース、送信トレイ

- [ ] エラー分類は定義されていますか (BusinessDecline、Timeout、RateLimited、Infrastructor)?
- [ ] カテゴリごとに異なる再試行ポリシーが適用されますか?
- [ ] DB にバックアップされたジョブはリースの下で処理されますか?
- [ ] Webhook ハンドラーはリース + バージョン トークンを併用していますか?
- [ ] イベントは、状態が変化した送信ボックス パターンと同じトランザクション内にありますか?
- [ ] 冪等性キー API、コンシューマー重複排除、DB の一意性の 3 つが一緒になっていますか?

## 4. リカバリ: 前は自動化、後は Runbook

- [ ] 調整スイーパーは FinalizePending / Expired スキャン レコードを期限切れにしますか?
- [ ] 孤立請求シナリオは相関 ID で解決できますか?
- [ ] マルチインテント カートのカート ロックはありますか?
- [ ] Uniqueness ウォール マニュアルはレビュー キューに書き込みますか?- [ ] Runbook は証拠に基づいていますか (ステップ ログ + PSP クエリ + 監査)。
- [ ] 治癒/返金の決定は反射ではなく手順ですか?

## 5. 可観測性: 支払い ID バックボーン

- [ ] 各ログ、トレース、メトリクスには支払い ID が含まれていますか?
- [ ] ステップ イベント ログは追加専用であり、すべての意味のあるステップをカバーしていますか?
- [ ] `deferred_finalize_count` および `deferred_finalize_age_seconds` メトリクスは定義されていますか?
- [ ] ドリフトカウントが急激に増加した場合、アラートが生成されますか?
- [ ] 支払い ID を使用して、チェックアウトから端末ステータスまでの完全なパスを追跡することはできますか?

## 6. 一貫性モデル: 最終的、中程度、観察可能

- [ ] 2PC ではなく、物語 + 和解モデルが意識的に選ばれましたか?
- [ ] 物語の各ステップの補正アクションは定義されていますか?
- [ ] 最終整合性ウィンドウは測定され、製品チームと共有されていますか?
- [ ] 「常に一貫性がある」という幻想ではなく、「短期間で一貫性がある」ことが目標ですか?```text
Checklist tamamlandığında sorulacak son soru:
  'Bu sistemin en kötü gününde ne olur?'
  → Cevap runbook'ta, metriklerde ve reconciliation'da yazılı olmalı.

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

❌ Checklist = feature tamamlandı demek ✓ Checklist = mimari ilkenin ölçülebilir testi

❌ Production ready = load test geçti ✓ Production ready = arıza anında doğru davranış kanıtlandı

❌ Daha fazla PSP = daha fazla karmaşıklık ✓ İyi sınırlar varsa, yeni PSP yalnızca gateway'i etkiler

|セクション |シリーズエピソード |基本的な質問 |
| --- | --- | --- |
|ボーダー | 9-10 | Orchestrator は PSP を知っていますか? |
|状況と証拠 | 1-4、6 |それは国の証拠に基づいていますか？ |
|信頼性 | 5、7-8、11、17、20 |故障した場合はどうなりますか? |
|回復 | 12-16、19 |ドリフトを捕まえる方法は？ |
|可観測性 | 18 |滞っている支払いは表示されますか? |
|一貫性 | 3、16 | 2PCかサーガか？ |

## 実稼働準備状況の評価

1. 設計レビューでは、チェックリストの 6 つのセクションを 1 つずつ実行します。各項目について「はい」「いいえ」「一部」で答えてください。
2. 技術的負債リストに「部分的」回答を追加します。ビジネスへの影響に基づいて優先順位を付けます。
3. 最悪の日のシナリオ (PSP 5xx、Webhook の遅延、ワーカーのクラッシュ、孤立した充電) を机上演習として実行します。
4. 演習中に空白のままになっているチェックリスト項目に注意してください。これらは初期の改善目標です。
5. チェックリストを生きた文書として保管します。実稼働インシデントが発生するたびに、関連する記事を更新します。

## このシリーズで覚えておくべきこと

1. 本番の支払いエンジンは、幸せな経路ではなく、失敗時の行動によって測定されます。
2. チェックリストは、シリーズの 22 のエピソードを測定可能にまとめたものであり、機能リストではありません。
3. 境界 (オーケストレーター ↔ ゲートウェイ) が壊れた場合、他のすべてはそのリークの上に構築されます。
4. 最悪の日の質問に対する答えは、ランブック、指標、調整に書かれるべきです。

> 本番決済エンジンの設計は、「チャージ API を書く」ことではありません。それは、キャプチャと完全な制御、観察可能、回復可能との間のギャップを作ることです。

最終回では、このシリーズをキャリアの観点から取り上げます。フィンテック企業は実際に何を求めているのでしょうか?