スマホから簡単にmicroCMSへのコンテンツ入稿してみる

microcms-content-import/
├── SKILL.md
├── references/
│   ├── api_patterns.md
│   ├── coffee_beans.md
│   └── troubleshooting.md

---
name: microcms-content-import
description: 画像やユーザーから受け取った情報をもとに、microCMSへコンテンツを入稿する。特にコーヒー豆の袋や商品写真を受け取ったとき、画像の見た目をそろえ、microCMSへアップロードし、coffee_beans などのコンテンツを作成または更新する。
---

# microCMS Content Import

画像から情報を読み取り、商品画像として使える状態に整え、mcms-cli（@mrmtsu/mcms-cli）を使ってmicroCMSに登録する。

コーヒー豆の袋写真では、「白背景」を安い背景削除作業として扱わない。このプロジェクトの既存のコーヒー画像は、カタログ写真のような商品画像である。中央配置、正方形、きれいな白または少し温かい白背景、柔らかい影、袋の識別情報が読めること、机や壁の残りがないことを基準にする。元画像が日常的なスマホ写真で、壁や机が写っている場合は、袋だけを雑に切り抜くのではなく、スタジオ撮影風の商品写真として作り直し、アップロード前に必ず目視確認する。

## CLIの前提

- 優先して使うコマンドは microcms
- 自動化しやすいように、原則として --json を付ける

認証状態の確認に使うコマンド:

```bash
microcms auth status --json
microcms config doctor --json
```

## 作業の流れ

### 1. ユーザーの意図を確認する

画像を受け取ったときは、何をしたいのかを確認する。

- 画像アップロードのみ: microCMSのメディアライブラリへアップロードしてURLを返す
- コンテンツ作成: 画像から情報を読み取り、コンテンツを作成する
- 両方: 先に画像をアップロードし、そのURLを使ってコンテンツを作成する
- コーヒー豆登録: コーヒー袋の画像を既存画像に合わせて整え、アップロードし、必要なコーヒータグを作成し、coffee_beans のコンテンツを作成する

### 2. アップロード前に商品画像を整える

コーヒー画像を既存のコーヒー豆画像に合わせる必要がある場合は、次の順で進める。

1. 可能であれば、既存の coffee_beans.photo を確認し、目標の画像スタイルを把握する
2. ユーザーの画像を確認し、単純なトリミングや白背景化で十分かを判断する
3. 日常的なスマホ写真、暗い写真、机の上、壁の前、背景に質感がある写真の場合は、袋を手で切り抜くのではなく、画像生成・編集でクリーンな商品写真として作り直す
4. アップロード前に、次の観点で目視確認する
   - 正方形構図。できれば1024x1024以上
   - 温かみのある白またはオフホワイトのシームレス背景
   - 袋が中央にあり、直立していて、正面寄り
   - 袋の下に自然で柔らかい影がある
   - 壁の質感、机の面、切り抜きの白い縁、ギザギザ、マスク抜け、汚れた背景の残りがない
   - 商品としての識別情報が保たれている。袋の色、ラベル色、ロースター名、商品名、産地などの主要な文字が不自然に変わっていない
5. 生成または編集した画像が、元画像や既存のカタログ画像より明らかに悪い場合はアップロードしない。再生成または再編集する

コーヒー袋画像の生成プロンプトは references/coffee_beans.md のパターンを使う。

### 3. 画像をmicroCMSへアップロードする

CLIでアップロードする。

```bash
microcms media upload <image_path> --json
```

重要なこと:

- 実アップロードの前に microcms media upload <image_path> --dry-run --json を実行する
- JSONレスポンスの data.url を読み取り、アップロード済みURLとして使う
- 目視確認していない途中画像はアップロードしない

複数画像がある場合は、すべてアップロードし、URLを集める。

### 4. 画像から情報を読み取る

受け取った画像を分析し、必要な情報を読み取る。

- 見えている文字、ラベル、商品情報を読む
- 商品名、産地、説明、仕様などの重要情報を特定する
- 日付、数値、その他の構造化できる情報を確認する
- コーヒー袋の場合は、ロースター名、国、地域、精製方法、焙煎度、品種、テイスティングノート、内容量を確認する
- その他の商品では、名前、ブランド、カテゴリ、特徴を確認する

### 5. 登録先APIを決める

どのmicroCMS APIにコンテンツを作成するかを確認する。

- microcms api list --json で利用可能なAPIを表示する
- ユーザーに適切なAPIを選んでもらう
- 不明な場合は内容から提案する。例: コーヒー商品なら coffee_beans

### 6. APIスキーマを取得する

必須フィールドやフィールド型を確認するため、APIスキーマを取得する。

```bash
microcms api info <endpoint_name> --json
```

確認すること:

- 必須フィールド
- フィールド型。text、select、media、relation など
- select の選択肢
- relation フィールドの参照先API

### 7. 追加情報を集める

スキーマと画像から読み取った情報をもとに、足りない情報を確認する。

1. タグやカテゴリなどの関連コンテンツを確認する
   - microcms content list <endpoint> --limit 100 --json
   - 必要に応じて --q、--filters、--fields を使う
2. 足りない必須情報を特定する
3. 足りない情報はユーザーに確認する
4. 読み取った情報をAPIフィールドへ対応づける

重要: コンテンツ作成前に references/api_patterns.md を読み、正しいフィールド形式を確認する。

このプロジェクトのコーヒー豆マスタ登録では、coffee_beans を作成する前に references/coffee_beans.md を読む。

### 8. コンテンツを作成する

作成または更新の前に事前確認を行う。

```bash
microcms validate <endpoint> --file payload.json --json
```

コンテンツを作成する。

```bash
microcms content create <endpoint> --file payload.json --json
```

既存コンテンツを更新する場合:

```bash
microcms content update <endpoint> <content_id> --file payload.json --json
```

フィールド形式のガイドライン。詳細は references/api_patterns.md を参照する。

- Select fields: 文字列ではなく ["value"] のような配列形式を使う
- Media fields: {"url": "..."} のようなオブジェクトではなく、URL文字列を使う
- Relation fields: コンテンツIDを使う。単一なら文字列、複数なら配列

### 9. 確認して報告する

作成後は次を行う。

1. 作成したコンテンツを取得して確認する
   - microcms content get <endpoint> <content_id> --json
2. コマンド成功だけでなく、返ってきたフィールド値を確認する。select のpayload形式が間違っていると、コマンドは成功しても空になることがある
3. フィールド値のサマリーを表示する
4. コンテンツIDと関連URLを表示する
5. CLIレスポンスの ok: true を確認する

## ツールとリソース

### References

- references/api_patterns.md: フィールド型ごとの正しい形式
- references/troubleshooting.md: よくあるエラーと解決方法
- references/coffee_beans.md: コーヒー袋画像の標準化と coffee_beans 作成ワークフロー

## ベストプラクティス

1. APIスキーマを必ず先に確認する。コンテンツ作成前にフィールド型を理解する
2. 既存データを確認する。タグや関連コンテンツを作成する前に重複を避ける
3. 正しいフィールド形式を使う。型エラーを避けるため api_patterns.md を確認する
4. 段階的に情報を集める。画像から読めるものを抽出し、足りないものは確認する
5. 作成前に検証する。microcms validate <endpoint> --file payload.json --json を実行する
6. 自動化しやすい出力を優先する。--json を有効にして、デバッグしやすくする
7. 商品写真はアップロード前に必ず目視確認する。粗い切り抜きはアップロードしない

## よくある落とし穴

- --json を付けず、出力の解析やエラーハンドリングが不安定になる
- メディアアップロードで間違ったドメインを使う。CLIは内部でManagement APIを使う
- フィールド形式を間違える。select は配列、media はURL文字列が必要
- コンテンツ作成前にスキーマ検証をしない
- 既存の関連コンテンツ、タグ、カテゴリを確認しない
- 背景が白いだけで画像をアップロードしてしまう。マスクの破綻、机の残り、壊れた影、照明の不一致がある画像は避ける
- create/update の成功だけを信じて、取得し直してフィールドが入っているか確認しない

エラーが出た場合は references/troubleshooting.md を確認する。

# Coffee Bean Master Workflow

ユーザーがコーヒー袋の写真を提供し、その画像を既存サイトのコーヒー画像とそろえ、microCMSにアップロードし、coffee_beans のマスタコンテンツを作成したい場合に使う。

## 画像基準

既存の coffee_beans.photo のスタイルを目標にする。

- 正方形の商品画像。通常は1024x1024以上
- 白または少し温かい白のシームレス背景
- コーヒー袋が中央にあり、直立している
- 商品として識別できる程度に正面を向いている
- 柔らかいスタジオ照明と自然な接地影
- 机、壁、部屋の質感、手、道具、カップ、豆、装飾物を入れない

粗い背景削除画像はアップロードしない。悪い結果を使うくらいなら、待つ方がよい。

次のような場合は却下して再生成する。

- 切り抜きの縁がギザギザ
- 袋の内側に灰色や白の穴がある
- 机や壁の質感が残っている
- 元写真の硬い長方形の切り抜きが残っている
- ラベルが不自然にぼけている、にじんでいる
- 商品がきつく切れすぎている
- 影が物体から浮いて見える

## 推奨画像ワークフロー

1. 既存のコーヒー豆画像を確認する。まだ知らない場合は次を使う
   - microcms content list coffee_beans --fields id,name,photo --limit 20 --json
2. ユーザーの元画像を確認する
3. 元画像がすでにスタジオ商品写真に近い場合は、正方形にトリミングまたは余白追加し、軽く補正する
4. 元画像が日常的な写真、机の上、壁の前、低照度の場合は、画像生成・編集でクリーンな商品写真版を作る
5. 生成画像をアップロード前に見る。厳しめに確認する
6. 目視確認後にだけ、次を実行する
   - microcms media upload <path> --dry-run --json
   - microcms media upload <path> --json

## 画像生成プロンプトのパターン

具体的な袋に合わせて、このプロンプトを調整する。

```text
提供されたコーヒー袋の写真を、ミニマルなコーヒーカタログのスタイルに合う、きれいな商品画像へ編集してください。
実物としての識別情報を保ってください: [袋の色や素材] のコーヒーパウチ、[ラベルの色] の正面ラベル、[見えている商品名・産地・ロースター名] が読めること。
壁、机、背景を完全に取り除いてください。
温かい白またはオフホワイトのシームレス背景で、リアルなスタジオ商品写真として再構成してください。正方形構図、袋は中央、直立、正面寄り、袋の下に自然で柔らかい影、均一なソフトボックス照明、高品質なEC商品写真の雰囲気にしてください。
袋の比率、素材感、ラベルの色面、見えている文字の雰囲気を保ってください。
余計な小物、手、カップ、コーヒー豆、ロゴ、装飾要素を追加しないでください。
切り抜きの破綻、ギザギザ、机の残り、強すぎる影、ぼけ、文字の歪みを避けてください。
```

## 情報抽出

袋のラベルを読み取り、見えている事実を coffee_beans に対応づける。

- name: 日本語名とラベル上の元名を必要に応じて併記する。例: ケニア ンダロイニ / NDARO INI
- country: 既存サイトで日本語表記を使っている場合は国名を日本語にする
- region: 見えている地域。例: Nyeri
- variety: 見えている品種。複数ある場合はカンマ区切り
- process: microCMSのselect表示値として扱う。例: ["ウォッシュド"]
- roastLevel: ラベルやユーザー入力から明示または明らかに推測できる場合のみ入れる。例: Nordic Light / light roast なら ["浅煎り"]
- roaster: 見えているロースター名
- tags: 既存サイトのパターンに合わせ、国タグと焙煎度タグを使う
- photo: アップロード済みメディアURL文字列

見えていない、または推測できないフィールドは空にするか、ユーザーに確認する。農園名や生産者情報を勝手に作らない。

## 既存タグのパターン

このプロジェクトでは、コーヒー豆は通常次のタグを使う。

- 国タグ。例: ケニア
- 焙煎度タグ。例: 浅煎り

タグを作成する前に確認する。

```bash
microcms content list tags --filters 'domain[contains]coffee' --limit 100 --json
```

国タグがない場合は、次の形で作る。

```json
{
  "name": "ケニア",
  "domain": ["coffee"]
}
```

本作成の前に content create tags --file <payload> --dry-run --json を実行する。

## coffee_beans のpayload形式

レスポンス形式ではなく、作成・更新用のpayload形式を使う。

良いpayload:

```json
{
  "name": "ケニア ンダロイニ / NDARO INI",
  "country": "ケニア",
  "region": "Nyeri",
  "variety": "SL 28, SL 34, Batian, Ruiru 11",
  "process": ["ウォッシュド"],
  "roastLevel": ["浅煎り"],
  "roaster": "KOJIMA roastworks",
  "tags": ["countryTagId", "roastTagId"],
  "photo": "https://images.microcms-assets.io/assets/..."
}
```

write payload で避けるべきレスポンス形式:

```json
{
  "tags": [{ "id": "tagId" }],
  "photo": { "url": "https://...", "width": 1024, "height": 1024 }
}
```

## 作成手順

中途半端なコンテンツを避けるため、次の順序を使う。

1. 画像をアップロードし、画像URLを目視確認する
2. タグが存在することを確認する
3. 完全なpayloadファイルを作る
4. microcms validate coffee_beans --file payload.json --json を実行する
5. microcms content create coffee_beans --file payload.json --dry-run --json を実行する
6. microcms content create coffee_beans --file payload.json --json を実行する
7. 作成したエントリを取得する
   - microcms content get coffee_beans <id> --json
8. process、roastLevel、tags、photo など、意図したフィールドがすべて入っていることを確認する

作成が不透明な400エラーで失敗した場合は、必須フィールドだけで作成し、その後小さな単位で更新して復旧する。

1. text fields
2. select fields
3. tags
4. photo

各更新後に必ずコンテンツを取得し、値が実際に存在することを確認する。コマンドが ok: true を返しても、select値が不正な場合はフィールドが空になることがある。