カタログ・PIM

商品は Shopify からミラーされ、CMS 側でオーバーレイ（PIM） を重ねて拡張します。多言語の説明、カスタム属性、メタフィールドを CMS が権威として持ち、必要に応じて Shopify へ書き戻します。

商品ミラー

/content/commerce/products/product_{id}.json に格納され、主なプロパティは次のとおりです。

プロパティ	由来
`commerce:product_id` / `commerce:title` / `commerce:handle`	Shopify
`commerce:status`	取り込みステータス（`received` / `threshold_pending` / `review_pending` / `monitored` / `error` / `deleted`）
`commerce:source_status`	Shopify の `active` / `archived` / `draft`
`commerce:vendor` / `commerce:product_type` / `commerce:tags`	Shopify（ルール照合に使用）
`metafields`	Shopify メタフィールドのミラー（Admin API 有効時）
`pim` / `pim:updated_at`	CMS の PIM オーバーレイ

PIM オーバーレイ

pim プロパティに、CMS 主導の拡張情報を保持します。

{
  "attributes": { "material": "cotton" },
  "localized": {
    "ja": { "title": "...", "description_html": "..." },
    "en": { "title": "...", "description_html": "..." }
  },
  "metafields": [ { "namespace": "custom", "key": "care", "type": "single_line_text_field", "value": "..." } ],
  "updatedAt": "...", "updatedBy": "operator@example.com"
}

商品ノードと同じ場所に保存されるため、バージョン履歴と ACL の対象になります
既定はディープマージ（merge:true）。merge:false で置換

統合ビューと検索

commerce.Pim.view が「Shopify ベース＋メタフィールドミラー＋PIM オーバーレイ」を統合します。検索は JCR の jcr:contains で商品 JSON 全体（タイトル・説明・タグ・カスタム属性）を対象にします。

エンドポイント

GET  …/endpoints/pim.groovy?q=keyword[&limit=50]   # 全文検索
GET  …/endpoints/pim.groovy?productId=123           # 統合ビュー
GET  …/endpoints/pim.groovy?productId=123&raw=true  # オーバーレイのみ
POST …/endpoints/pim.groovy {productId, pim:{...}, merge:true}  # 書き込み

Shopify へのメタフィールド送信

POST …/endpoints/sync.groovy {action:"metafields", productId:123}

pim.metafields を読み、Admin の metafieldsSet で適用します（shopify.yml の adminApi.enabled が必要、監査証跡を記録）。

操作

Webtop の Commerce PIM アプリで、商品を検索し、ローカライズ内容・カスタム属性・メタフィールドを編集します。Shopify ベースは読み取り専用で参照でき、保存は未管理キーを保ちつつ反映します。Admin API 有効時はツールバーからメタフィールドを Shopify へ送信できます。