Mitasu for Apparel — AI操作ガイド（AIエージェント向け仕様書）

バージョン 2026-07-10（アプリ実装と同期・自動テストで整合性を検証） 使い方: この文書全体を、Shopify Admin API に接続できるAIアシスタント （Claude + Shopifyコネクタ、Claude Code + Shopify MCP、カスタムエージェント等）に 貼り付けてから、商品情報の登録・割り当てを依頼してください。 English version: https://mitasu.tech/ai/apparel-agent-guide.en.md

このアプリのデータはすべてShopifyのメタフィールド／メタオブジェクトに保存されます （外部DBなし・namespace は全て apparel_info）。Admin GraphQL を使えるAIエージェントは、 アプリ管理画面を介さずにテンプレート作成と商品への割り当てを実行できます。

最重要: 2つの安全な経路

1. 【最も安全・推奨】CSV経路 — アプリの「CSV書き出し」→ AIが列を埋める → 「CSV取り込み」（Pro）。名前参照・検証・上限クランプがアプリ側で全部かかる。 列: title, handle, size_chart, spec, outfits, models, faq(参照はテンプレート名、 Q&Aは質問文で指定。複数は | 区切り。空欄の列は変更されない)。
2. 【上級】GraphQL直書き — 本書のスキーマに厳密に従うこと。テンプレート （メタオブジェクト）の作成 + 商品への参照割り当てのみ行い、それ以外のキーには 書かない。

絶対ルール（違反するとストア表示・アプリ管理画面が壊れます）

1. 採寸値は cm のみで保存（inch は保存しない。表示時にアプリが換算）。
2. 書き込みは「テンプレート作成」と「参照(ref)の割り当て」だけ。 *_override / fit_feedback / return_stats / fit_baseline / review_pending / insights_cache / installed_at / plan / plan_cancel_at には絶対に書かない （アプリ管理の集計・内部値。商品ごとの微調整はオーナーにアプリの上書きUIを案内）。
3. レガシーキーに新規入力しない: inline materials / care / model_fit / fit_details（商品・バリアントとも）/ outfit_ref（単数）/ faq（旧JSON）/ faq_custom_items / faq_order — すべて読み取りフォールバック専用。 素材構成・色・ストレッチ等は Shopify標準のカテゴリーメタフィールド（商品ページで 入力）をアプリが自動表示する（特徴タブ）。アプリ側namespaceには書かない。
4. 割り当て上限: コーデ outfit_refs ≤ 4 / モデル model_refs ≤ 4 / Q&A faq_items ≤ 10。コーデ1件内の着用商品 items ≤ 6。
5. 作成前に同名テンプレートの有無を必ず検索（重複作成しない）。 テンプレートの削除はアプリUIからのみ（直接deleteすると割り当て・上書きの 後始末が行われない）。
6. 破壊的変更（既存refの差し替え・大量更新）の前に現在値を読み、ユーザーに確認する。
7. metafieldsSet は1回 ≤ 25件。書き込み後は userErrors を必ず確認。

データモデル（現行 = Plan A: テンプレート参照 + 商品ごと上書き）

テンプレート = メタオブジェクト（5種・再利用可能）

apparel_info_size_chart（サイズ表）

apparel_info_spec（素材補足プロファイル）

apparel_info_model（モデル着用）: name(必須) / height_cm / weight_kg / size_worn / fit_tag(tight/regular/loose/oversize) / comment / image(写真URL文字列)

apparel_info_faq（Q&A 1問）: question(必須) / answer(必須)

apparel_info_outfit（コーデ）: name(必須) / items(list.product_reference・ 商品GID配列・≤6) / note / image(file_reference — Files のGID。用意が難しければ省略可)

商品メタフィールド（割り当て = 書き込み可はこの6つだけ）

バリアントメタフィールド（書き込み可）

size_chart_ref / spec_set_ref のみ（例: 「レギュラー/トール」でサイズ表を分ける）。

ストア設定（SHOP）— 原則アプリの「設定」画面で変更を案内

feature_flags（セクションON/OFF）/ section_order / section_titles / default_unit(cm|inch) / week_start(mon|sun)。読み取りは自由。

ケアコード表（apparel_info_spec.care 用）

推奨ワークフロー（商品分析 → テンプレ作成 → 割り当て）

1. 商品を読む — タイトル/説明/タイプ/タグ/標準カテゴリーから、服種・対象 （メンズ/レディース/キッズ）・素材感を分類。
2. 既存テンプレを検索 — metaobjects(type: "...", first: 250) で name 一覧。 合うものがあれば再利用（アプリ同梱の68種サイズ表テンプレをオーナーがUIで 取り込んでいる場合も多い）。
3. 足りないテンプレだけ作成 — 上記スキーマ厳守（特に measurement_type と cm）。
4. 割り当て — metafieldsSet で ref を設定（listは "[\"gid://...\"]" 形式の JSON文字列）。またはCSVを生成してオーナーに取り込みを案内（最も安全）。
5. 検証 — アプリ管理画面「商品データ」のカバレッジバッジ／「インサイト」で 割り当て状況を確認するようオーナーに案内。

GraphQL例

サイズ表テンプレートを作成

mutation {
  metaobjectCreate(metaobject: {
    type: "apparel_info_size_chart",
    fields: [
      { key: "name", value: "メンズTシャツ S-XL" },
      { key: "category", value: "top" },
      { key: "audience", value: "men" },
      { key: "measurement_type", value: "garment" },
      { key: "unit_primary", value: "cm" },
      { key: "fit_tag", value: "regular" },
      { key: "stretch", value: "false" },
      { key: "length_tag", value: "regular" },
      { key: "rows", value: "[{\"size_label\":\"S\",\"measurements\":{\"chest_cm\":86,\"length_cm\":66}},{\"size_label\":\"M\",\"measurements\":{\"chest_cm\":92,\"length_cm\":69}}]" }
    ]
  }) { metaobject { id } userErrors { field message } }
}

商品に割り当て（サイズ表 + 素材補足 + Q&A）

mutation {
  metafieldsSet(metafields: [
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "size_chart_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/456" },
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "spec_set_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/789" },
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "faq_items",
      type: "list.metaobject_reference", value: "[\"gid://shopify/Metaobject/111\",\"gid://shopify/Metaobject/222\"]" }
  ]) { metafields { key } userErrors { field message } }
}

既存テンプレート一覧（重複チェック・割り当て用GID取得）

{ metaobjects(type: "apparel_info_size_chart", first: 250) {
    nodes { id field(key: "name") { value } }
    pageInfo { hasNextPage endCursor } } }

トラブルシューティング

• UNDEFINED_OBJECT_TYPE / 定義エラー → アプリの「設定 → 再チェック」を案内 （定義は自動修復される）。
• 割り当てたのに店頭に出ない → ①その機能がProで店舗がFreeでないか（モデル/素材補足/ コーデ/投票/サイズ感バッジはPro） ②設定でセクションOFFになっていないか ③テーマにブロック未設置でないか、の順で確認。
• 上限超過分は表示されない（refを上限内に収める）。