2026-04 出荷Webhook shadow lane 補足仕様

位置づけ

本仕様は、基幹システムから Vendure へ通知する出荷Webhookについて、productionでの安全な比較検証を行うための追加合意事項を定義する。

対象は system-integration/shipment/notify の受信経路とし、production verification の補助レーンとして運用する。

合意事項

1. 分離単位
2. 初期段階の shadow test は channel 追加ではなく execution mode によるレーン分離とする。

3. production を正本処理、shadow を比較専用処理として扱う。

4. 適用範囲

5. v1 の対象は出荷Webhook (system-integration/shipment/notify) のみとする。

6. SMILE export、決済 callback、その他Webhookには本仕様を直ちには適用しない。

7. 入力条件

8. production と shadow は同一の受信 payload（注文番号、配送会社名、追跡番号）を用いる。

9. order 解決や重複判定など、比較価値のある読取は production 相当のデータを用いる。

10. 副作用の扱い

11. shadow 実行では以下の本番副作用を起こしてはならない。
    • fulfillment 作成
    • fulfillment の Shipped 遷移
    • 注文履歴メモ追記
    • 出荷完了メールなど、前記副作用を起点とする通知

12. shadow では「実行予定だった内容」を比較用に記録し、本番系の永続化は行わない。

13. レスポンス責務

14. HTTP レスポンスは常に production 側の結果を正本とする。

15. shadow 側の失敗は production レスポンスを失敗させる理由にしない。

16. 観測

17. shadow 実行結果は production 結果と突合できる形で記録する。
18. 少なくとも以下を比較可能にする。
    • orderCode
    • carrierName
    • trackingNumber
    • duplicateDetected
    • plannedLineCount
    • sideEffectsApplied

19. shadow failure は production の主系アラートと混線しない形で記録する。

20. 運用制御

21. shadow 実行は設定フラグで ON/OFF できること。
22. kill switch として即時に無効化できること。

受け入れ観点

1. 出荷Webhook呼び出し時に production 側は従来どおり fulfillment 作成と shipped 遷移を行えること。
2. shadow 有効時も、本番DB上の fulfillment 数や注文履歴が追加で増えないこと。
3. shadow failure が発生しても、production 成功時の HTTP レスポンスが維持されること。
4. shadow ON/OFF を設定だけで切り替えられること。
5. production / shadow の比較結果を、注文番号・追跡番号単位で観測できること。