システム連携プラグイン (System Integration)¶
概要¶
SystemIntegrationPlugin
は、外部システムから Vendureへ入るサーバー間連携の入口です。現時点の主な責務は、基幹システムから受信する出荷完了Webhook
(system-integration/shipment/notify) の認証、注文解決、出荷反映です。
2026-04時点では、本番環境での安全な比較検証のために、出荷Webhookへ shadow
lane を追加しています。これにより、同一入力を production と shadow
の2レーンで評価しつつ、本番副作用は production 側だけに限定できます。
受信フロー¶
X-Commerce-System-Timestamp/X-Commerce-System-Signatureを検証する。productionを正本とする処理を実行する。- 設定で有効な場合のみ、同じ payload を
shadowでも評価する。 shadowは比較記録だけを残し、本番の fulfillment / 履歴 / 通知は発生させない。- HTTP レスポンスは常に
productionの結果を返す。
shadow lane の目的¶
- production と同じ入力で、将来のロジック変更や連携先変更の影響を比較する。
- 実ユーザー向けのレスポンスや本番データを壊さずに、出荷Webhookの判定結果を観測する。
- 「channel を増やす」よりも、execution mode を明示的に渡して副作用境界を切る 方式で、責務の混線を避ける。
shadow lane の制約¶
v1 で読取するもの¶
- 注文番号からの注文解決
- fulfillment 重複判定
- 出荷適用計画（対象 line 数、carrier、tracking code）の組み立て
v1 で行わないもの¶
- fulfillment 作成
- fulfillment の
Shipped遷移 - 注文履歴メモの追加
- 上記を契機に発火する出荷完了メールや関連通知
比較で確認する項目¶
shadow capture では少なくとも以下を production と突合できるようにします。
| 項目 | 意味 |
|---|---|
orderCode |
対象注文コード |
carrierName |
配送会社名 |
trackingNumber |
追跡番号 |
duplicateDetected |
重複配送判定 |
plannedLineCount |
fulfillment 対象 line 数 |
sideEffectsApplied |
本番副作用を実行したか |
fulfillmentId / fulfillmentState |
production 側で実際に作成された fulfillment 情報 |
設定¶
出荷Webhookの shadow lane は SystemIntegrationPlugin.init()
に以下の設定で渡します。
| 設定 | 役割 | 既定値 |
|---|---|---|
shadowShipmentWebhookEnabled |
shadow 実行の ON/OFF | false |
shadowCaptureEnabled |
production/shadow 比較記録の ON/OFF | true |
Vendure Server では次の環境変数から配線します。
| 環境変数 | 説明 |
|---|---|
SHIPMENT_WEBHOOK_SHADOW_ENABLED |
出荷Webhookの shadow 実行を有効化する |
SHIPMENT_WEBHOOK_SHADOW_CAPTURE_ENABLED |
shadow 比較記録を有効化する |
運用上の注意¶
- production の主系可用性が最優先です。shadow failure は production レスポンスを失敗させません。
- 本番事故を避けるため、shadow は副作用 no-op を原則とします。状態遷移の再現が必要になった場合は、shadow DB / schema 分離を別フェーズで追加してください。
- shadow lane の ON/OFF は設定フラグで切り替え、kill switch として即時に無効化できる状態を維持してください。
受け入れ確認¶
- shadow 無効時、出荷Webhook は従来どおり fulfillment を 1 回だけ作成すること。
- shadow 有効時も、production 側の fulfillment 数や履歴件数が追加で増えないこと。
- shadow 有効時に比較記録が残ること。
- shadow failure が起きても、production 成功時の HTTP レスポンスが維持されること。