# 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`（サイズ表）**
| key | type | 許可値・形式 |
|---|---|---|
| `name` | text | 必須。表示名（CSV参照にも使う一意な名前を推奨） |
| `category` | text | `top / bottom / dress / outerwear / underwear / skirt / shoes / socks / bra / headwear`（表の列既定を決める） |
| `audience` | text | `unisex / men / women / boys / girls / baby / shoe / bra / head / none` — 採寸図の切替。`shoe`/`bra`/`head`は表の形も変える。`head`は頭囲表＋測定図のみでサイズ診断なし。`none`=図なし |
| `silhouette` | text | 平置き図の形（`top / hoodie / collar / sleeveless / cardigan / outerwear / bottom / shorts / dress / skirt / custom`）。作成時に固定・シューズ/ブラ/帽子は空。`custom`=ブランクテンプレでオーナーが図を登録。空なら店頭はカテゴリー形にフォールバック。エージェントは未設定でよい（アプリが設定） |
| `garment_type` | text | 元テンプレートのID（例: `tee-unisex`）。作成時に固定・編集画面の「品目」ラベル用。エージェントは触らない（アプリが設定） |
| `figure_image` / `garment_image` | file_reference | ブランク（`silhouette=custom`）専用の自前採寸図（体）・実寸図（服）。店頭で内蔵図の代わりに表示。エージェントは触らない（アプリが設定） |
| `measurement_type` | text | `body`（ヌード寸法）or `garment`（製品平置き寸法）。**サイズ診断のゆとり計算に影響 — 必ず正しく設定** |
| `unit_primary` | text | `cm` or `inch`（編集時の単位。**保存値は常にcm**） |
| `fit_tag` | text | `tight / regular / loose / oversize` |
| `stretch` | boolean | `"true"` / `"false"` |
| `length_tag` | text | `cropped / regular / long` |
| `tolerance_cm` | single_line_text_field | 任意の許容誤差。**cmで保存**、数値を文字列として（例 `"1.5"`）。実寸(`measurement_type=garment`)チャートのみ、店頭のサイズ表の下に個体差の注記が出る（表示単位はcm/inchトグルに追従）。エージェントは未設定のままでよい |
| `rows` | json | `[{ "size_label": "M", "size_us": "8", "size_uk": "12", "size_eu": "38", "size_jp": "11", "measurements": { "chest_cm": 88, "length_cm": 62 } }]`。measurementsキー: `chest_cm / waist_cm / hip_cm / length_cm / sleeve_cm / inseam_cm`（shoes/socks: `foot_length_cm`、bra: `underbust_cm / bust_cm`、headwear: `head_cm`）。範囲は `<key>_max` 追加（例 `"waist_cm": 78, "waist_cm_max": 84` → 78–84表示）。不要な列は省略（表に出ない） |

**`apparel_info_spec`（素材補足プロファイル）**
| key | 許可値 |
|---|---|
| `name` | 必須 |
| `transparency` | `none / slight / moderate / sheer` |
| `lining` | `none / partial / full` |
| `season` | `all / ss / aw` |
| `sustainability` | list。認証コードのみ: `gots / oeko_tex / grs / rws / ocs / bluesign / fair_trade / cradle_to_cradle / bcorp / climate_neutral` |
| `care` | json `{ "wash"?, "bleach"?, "dry"?, "iron"?, "dryclean"? }` — コードは下表。店頭では**テキストラベル表示**（アイコンなし） |

**`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つだけ）

| key | type | 内容 |
|---|---|---|
| `size_chart_ref` | metaobject_reference | サイズ表のGID（1件） |
| `spec_set_ref` | metaobject_reference | 素材補足のGID（1件） |
| `model_refs` | list.metaobject_reference | モデルのGID配列（≤4・表示順） |
| `outfit_refs` | list.metaobject_reference | コーデのGID配列（≤4・表示順） |
| `faq_items` | list.metaobject_reference | Q&AのGID配列（≤10・表示順） |
| `fit_hint_override` | text | `true_to_size / runs_small / runs_large`（空=未設定。投票が貯まると実データが優先） |

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

`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` 用）

| カテゴリ | コード |
|---|---|
| wash | `wash_30` `wash_40` `wash_60` `wash_hand` `wash_no` |
| bleach | `bleach_any` `bleach_oxygen` `bleach_no` |
| dry | `dry_tumble` `dry_no_tumble` `dry_line` `dry_flat` |
| iron | `iron_high`(200℃) `iron_med`(150℃) `iron_low`(110℃) `iron_no` |
| dryclean | `dc_p` `dc_f` `dc_w` `dc_no` |

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

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

## GraphQL例

### サイズ表テンプレートを作成
```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）
```graphql
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取得）
```graphql
{ 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を上限内に収める）。