データ連携・取り込み

Commerce の連携は、ソース非依存のイベント取り込みと、CMS → Shopify の双方向同期で構成されます。すべてのイベントは生ペイロードごとログに残るため、再実行（リプレイ） できます。

イベント取り込み

バックエンドのアダプタ（署名検証・封筒を組み立て）
  → direct:commerce-ingest
     ├─ logEvent（生ペイロードを記録、status=received）
     ├─ トピック別: 専用ルート（order-paid など）
     └─ その他: normalizeEvent → /content/commerce/entities/{source}/{collection}/{id}.json
  → markEvent（processed / error）

• 全トピック取り込み: 許可リスト無しで全 Webhook を受け取り、専用ワークフローが無いものはエンティティへ正規化
• マルチバックエンド: アダプタが同じ封筒（event_source / event_topic / event_id / received_at、本文=生ペイロード）を direct:commerce-ingest に送れば、コア以降は変更不要
• 設定: /etc/commerce/config/ingest.yml

リプレイ（再実行）

• 自動: commerce-replay タイマー（既定 5 分）が error を replay.maxAttempts まで再実行（backoffMinutes）。processed は retentionDays で整理
• 手動: POST …/endpoints/events.groovy に単一（{source, eventId}）または条件（{status, topic, source, sinceDays}）。{matched, replayed} を返す
• 仕組み: 封筒を replay=true 付きで再投入。Webhook の冪等ガードは回避しつつ、進行中ワークフローの重複は防止

参照: GET …/endpoints/events.groovy?status=error&limit=100。UI は Commerce Operations → Events。

双方向同期（CMS → Shopify）

GET  …/endpoints/sync.groovy   # 機能/状態
POST …/endpoints/sync.groovy   # 実行

{ "action": "inventory", "inventoryItemId": 123, "locationId": 456, "quantity": 10 }
{ "action": "price", "productId": 1, "variantId": 2, "price": "19.99", "dryRun": true }

• adminApi.enabled（shopify.yml）で制御。無効時は 409 で Shopify を呼びません
• dryRun: true で、実際の呼び出しなしに対象と値を検証・エコー
• すべての試行（dry run・失敗を含む）を /content/commerce/sync/{yyyy}/{MM}/sync_{ts}.json に監査記録
• 実装は commerce.ShopifyWrite（commerce.ShopifyAdmin 上）。突合（Reconciliation）の自動修復も同じ書き込み基盤を使います

UI は Commerce Operations → Sync（Dry run トグル、最近の送信一覧）。

Commerce の i18n

Commerce のメッセージは /etc/i18n/commerce.<locale>.json と各アプリの <appId>.<locale>.json に置かれ、ロケールごとにマージされます。キーは app.<appId>.*（共通は common.*）。書式は ICU。en と ja を必ず同期し、断片を連結せず 1 文 1 キーで記述します。

通貨・ロケールは、ユーザーの実効設定（Preferences → 地域と言語）に従い、store.json の currency をフォールバックに使います。プラットフォーム全体の i18n は「多言語とロケール」を参照してください。