プロバイダアダプタ

プロバイダアダプタ-外部サプライヤ契約（ゲームプロバイダ、決済ゲートウェイ、KYC/AML、リスクスコアリング、通知など）を内部ドメイン言語に変換する分離統合レイヤー（腐敗防止レイヤー、ACL）。不安定なAPI、ネットワーク異常、スキーマの進化、セキュリティポリシーからドメインを保護します。

1.デカップリング：外部ペイロードがコアに当たらない。

2.信頼性：障害の管理（タイムアウト、リトライ、DLQ、サーキットブレーカ）

3.一貫性：idempotency、キーオーダー、トランザクションメッセージング。

4.操作：メトリクス、トレース、制限、転送分離および居住。

1）責任のアダプター区域

契約：外部スキーム/エンドポイントの説明；マッピング→内部コマンド/イベント。
輸送：REST/gRPC/WebSocket/SQS/Kafka/SFTP；接続プール、backpressure。
セキュリティ：mTLS、 OAuth2、 HMAC、テナント/地域ごとのキー/証明書、秘密の回転。
信頼性：タイムアウト、ジッタ付きリトレイ、サーキットブレーカ、重複排除。
Idempotency： 'Idempotency-Key'/'request_id'、 responses/statusesを格納します。
観測性：SLOメトリクス、構造ログ、トレース。
バージョン管理：複数のバージョンのスキーム/エンドポイントをサポートします。
操作：ficheflags、カナリアリリース、サンドボックス、認証。

2）該当する場合（例文）

ゲーム/RGS：開始/終了ラウンド、賭け/勝利、セッショントークン、プロバイダのステータス。
支払い/PSP：入金/出金、Webhookのステータス、チャージバック、3Dセキュア。
KYC/AML：検証、制裁/POPチェック、トランザクション監視。
リスク/詐欺：スコアリング、トリガー、推奨事項のブロック。
Comms：電子メール/SMS/push、郵送の限界、型板。

各タイプには独自のイベントステートマシンとSLAがあり、アダプタはそれを正規化する義務があります。

3）契約とマッピング（内部↔外部）

• アダプタ内にPublished Languageを入力し、プロバイダのフィールドをドラッグすることはありません。
• すべてのメッセージには'tenant_id'、 'region'、 'provider_id'、 'operation_id'、 'version_ts'が含まれます。
• マッパーを介していくつかのバージョンの外部スキームをサポートしています。

yaml mapping:
provider: "AcmeRGS"
version: "v3"
inbound:
SpinResultV3 -> Round. Resulted
BonusWinV3  -> Bonus. Wagered outbound:
StartRound  -> POST /v3/sessions/{id}/start
Stake    -> POST /v3/spins compat:
accepts: ["v2","v3"]
emits:  ["v3"]

4） Idempotenceおよび順序

Request de-dup： 'Idempotency-Key： <operation_id>' in requests；story '（op_id→final status/response）'をTTLで指定します。
Webhook de-dup：テーブル'inbox （provider、 event_id）'をPKとして指定します。
キーによる順序：'aggregate_id'（例えば'round_id'または'psp_tx_id'）による呼び出しと処理をシリアル化します。
Outbox/Inboxing：パイプラインの両端のトランザクションメッセージング。

5）信頼性： タイムアウト、後退、遮断器

タイムアウト：短いクライアント側（p95指向）、接続/読み取りのために別々。
リトレイ：再試行可能（5xx/timeout/429）、指数関数バックオフ+フルジッタ、試行限度および期限合計。
サーキットブレーカ：エラー/レイテンシーが増加すると開きます。graceful degradation（たとえば、セカンダリRGS機能を無効にし「、結果を待つ」設定）。
DLQ：豊富なメタ情報を持つ「毒」メッセージ、安全な再ドレーブ。

yaml reliability:
timeout_ms:
connect: 1000 read:  1500 retry:
max_attempts: 6 initial_backoff_ms: 200 max_backoff_ms: 8000 jitter: full retry_on: [TIMEOUT, 5xx, 429]
circuit_breaker:
failure_rate_threshold: 20%   # за окно slow_call_threshold_ms: 1500 half_open_max_calls: 10

6）レート制限、クォータ、競争力

プロバイダの制限（RPS、バースト、並行）を遵守します。
「騒々しい」クライアントが予算を使い果たさないように、テナントごとのWFQ/DRR（公平性）を実装します。
'Retry-After'/'X-RateLimit-'ヘッダーを尊重します。
プロダクトの内部キュー+backpressure。

7）安全性とコンプライアンス

輸送：mTLS、 TLS 1。2+、現在の暗号スイート、可能であればピン留め証明書。
認証：OAuth2 client-credentials/MTLS、 HMAC （signed body hashes+timestamp）、 APIキー。
PII最小化：必須フィールドのみ；ログとDLQでのマスキング/編集。
秘密：KMS/HashiCorp Vault、自動回転、テナント/地域ごとの分離。
コンプライアンス：PSP用PCI DSS、 PANの代わりにトークンストレージ、GDPR/ローカルデータ法。

8）複数のテナントおよび複数の地域

テナント/リージョンごとのキー/エンドポイントの設定。
データレジデンシー：呼び出しは「ホーム」領域から行われます。cross-region-集計のみ。
分離：テナントごとの独自の接続プールと制限。

yaml tenants:
T1:
region: eu-central provider_keys:
acme_rgs: { client_id: "...", cert_ref: "vault://..." }
psp_foo: { hmac_key_ref: "kms://..." }
endpoints:
acme_rgs: "https://eu. api. acme-rgs. com"
psp_foo: "https://eu. api. psp-foo. com"
T2:
region: sa-east
...

9）観測可能性： メトリック、ログ、トレース

• クラス別の成功/エラー（2xx/4xx/5xx/timeout/429）。
• p50/p95/p99レイテンシをメソッドで指定します。
• 速度限界の作動、開始/最後のブレーカ、DLQ率、redrive成功。
• 構造ログ：'tenant_id'、 'provider_id'、 'operation_id'、 'endpoint'、 'status'、 'attempt'、' backoff_ms'。
• トレース：シングル'trace_id'、スパン「serialize→send→receive→map→publish」、タグ'schema_version'、 'region'。

10）バージョン管理とphicheflags

外部契約のサポートv 1/v2並行して；移住-カナリア/テナントによる。
新しいプロバイダ機能はフラグの後ろにあります。リリースなしで切り替えること。
進化の契約：スキーム（JSON Schema/Proto）の付加的第一、厳密な検証。

11） Playbook（ランブック）

1.Squall 429/limits：グローバルなスロットリングをオンにし、'Retry-After'を尊重し、テナント間のウィンドウを再配布します。
2.タイムアウトの増加：同時性を減らし、タイムアウトを慎重に増やし、ブレーカを開け、機能の劣化を可能にします。
3.スキーマの不一致：redriveをフリーズし、互換性のあるマッパー、backfill/reprocessを有効にします。
4.Webhookフラップ：プル/調整モードに切り替え、受信トレイのデッドアップを適用します。
5.プロバイダでのインシデント：sandbox/backup DCに切り替える（もしあれば）、「遅延」操作を有効にします。

12）テスト

契約テスト：固定プロバイダの修正に対する生産者/消費者。
カオステスト：遅延、低下、順序外れ、重複、部分的な応答、切断。
性能：破裂のスパイクの圧力；測定p95/p99、ブレーカ挙動。
Idempotency：同じ'operation_id'を繰り返すと、追加のエフェクトは作成されません。
Sandbox E2E： happy-path/chargeback/conversy/cancellation/recalcスクリプト。

13）展開パターン

別々のサービスアダプタ：+分離、独立したリリース、−追加のネットワーク。
Sidecar/plugin：+コールの局所性；バージョンを管理するの−より困難です。
ライブラリ：埋め込みが簡単です。高いカップリングとモトリーのバージョンを−します。

推奨事項：明確なAPIとそのリリースサイクルを備えたサービスアダプタ。

14）アダプターAPIの例（擬似）

http
POST /adapters/psp/authorize
Headers:
X-Tenant: T1
Idempotency-Key: op-uuid
Body:
{ "amount":"10. 00","currency":"EUR","method":"card","card_token":"tok_..." }

→ 202 Accepted
{
"operation_id":"op-uuid",
"status":"PENDING",
"as_of":"2025-10-31T12:00:00Z"
}

• 'provider_event_id'→'inbox' （'（provider,event_id）'のPK）→mapping→domainイベント'PaymentAuthorized'のWebhook。

15）典型的なエラー

「raw」外付け回路をドメイン→タイトな接続性と高価な移行にプルします。
idempotencyとinbox/outbox→duplicateエフェクトとファントム状態の欠如。
ジッタ/リミットのないレトライ→嵐とレート制限の禁止。
公平性のない唯一のグローバルプール→1つのテナントは皆を「置く」。
PIIリビジョン→識別子のないログは、インシデントおよびコンプライアンスリスクを調査することはできません。
カナリア/フラグはありません→リリースは一度に全員を壊します。
'Retry-After'とプロバイダのメンテナンススケジュールを無視します。

16）売り上げ前のチェックリスト

• 外部スキーマ→内部言語のマッピング；バージョンと下位互換性。
• リクエスト/webhook （'operation_id'、 'inbox'）のID。
• タイムアウト、フルジッタ、サーキットブレーカ、DLQおよび安全なredriveとのリトレイ。
• テナントあたりのレート制限の公平性；'Retry-After'の尊重。
• mTLS/OAuth/HMAC、シークレットローテーション、PII最小化、アクセス監査。
• 地域の分離とデータの居住；テナント/リージョンごとに構成されます。
• p95/p99メトリクス、クラスエラー、breaker/429/DLQ-rate；トレースしています。
• サンドボックスと契約テスト；キャナリーロールアウトとフィッシュフラッグ。
• インシデントプレイブックとオンコールトレーニング。
• ドキュメント：SLA、制限、スキーマ、進化プロセス。

結論

プロバイダアダプタは、ドメインと外部の世界の間のシールドと翻訳者です。idempotency、 error control、 observabilityを備えた強力なACLは、統合を予測可能にし、プロバイダの変更コストを削減し、チェーン障害から保護します。"独立した管理可能なコンポーネントとしての設計アダプタ-そしてあなたの"外の世界"は、内部アーキテクチャを壊すのをやめます。