cms-migration

Payload への CMS 移行

移行元 CMS のデータから Payload コレクションを設計するためのインタラクティブなワークフローです。設定ファーストのアプローチを採用し、データをインポートする前に、会話を通じてデータ構造を確定します。

ワークフロー

Start
  ↓
Ask for data sample
  ↓
Analyze data shape
  ↓
Propose collection config
  ↓
User reviews ──────────────┐
  │                        │
  ├─ changes needed ───→ Adjust config ──→ (back to User reviews)
  │
  └─ looks good ───→ Config confirmed
                            ↓
                    More collections? ──────┐
                            │               │
                            ├─ yes ──→ (back to Ask for data sample)
                            │
                            └─ no ───→ All collections confirmed
                                              ↓
                                      Discuss migration approach
                                              ↓
                                            Done

フェーズ 1：データ分析

ユーザーからデータ（JSON、CSV、またはスキーマの説明）が提供された場合：

1. フィールドの型を特定する - テキスト、数値、日付、リレーションシップ、メディア、リッチテキスト
2. パターンを見つける - ID、タイムスタンプ、ネストされたオブジェクト、配列
3. リレーションシップを確認する - 外部キー、埋め込み参照、関連するコンテンツタイプ
4. 曖昧な点を明らかにする - 複数の型になり得るフィールド、目的が不明なフィールド

フェーズ 2：コレクション設定の提案

分析に基づいて Payload コレクション設定を提示します：

// Example output format
export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'content', type: 'richText' },
    { name: 'author', type: 'relationship', relationTo: 'users' },
    // ...
  ],
}

各フィールドの選択理由を説明します。グループと JSON、テキストとテキストエリア、セレクトとリレーションシップのように複数の選択肢がある場合は、決めつけずに質問します。

フェーズ 3：ユーザーと設定を調整する

必須フィールド、hasMany リレーションシップ、リッチテキストと HTML のどちらにするか、組み込みのものではなくカスタムタイムスタンプを使うかなど、不明点を確認します。ユーザーが設定を承認するまで続けます。

フェーズ 4：追加コレクション

確認のたびに、次のように尋ねます：

「他にもコレクションを作成すべきコンテンツタイプはありますか？」

はいの場合は、新しいデータサンプルを使ってフェーズ 1 に戻ります。

関連コレクションとしてよく確認するもの：

• メディア／アップロード
• ユーザー／作成者
• カテゴリー／タグ
• 設定（グローバル）

フェーズ 5：移行方法

すべてのコレクションが確認されてから、データのインポートについて話し合います：

1. 順序が重要です - 依存関係のないコレクションはどれか？それらを最初に移行します
2. リレーションシップのマッピング - 移行元の ID を Payload の ID に解決する方法
3. メディアの処理 - ダウンロードして再アップロードするか、外部 URL を使うか
4. リッチテキスト - HTML 変換が必要か、そのまま保持するか

シードスクリプトの生成、または手動インポートの手順を案内することを提案します。

確認すべきこと

プロセス全体を通して、次の点に注意します：

• ID 参照 - 他のコレクションへのリレーションシップですか？
• 画像／ファイルの URL - アップロードフィールドにするか、外部 URL のままにするか？
• ネストされたオブジェクト - グループ、配列、ブロックのどれにするか？
• ローカライズ - ロケールごとに値を設定する必要があるフィールドはありますか？
• アクセス制御 - このコレクションの読み取り／書き込みができるのは誰ですか？
• 関連するコンテンツタイプ - 独自のコレクションが必要なカテゴリー、タグ、作成者はありますか？

重要：セレクトとリレーションシップ

これは移行で最もよくある間違いです。 静的に見えるデータでも、動的に管理する必要があることがよくあります。

繰り返し登場する文字列値（カテゴリー、タグ、タイプ、ステータス）がある場合：

{ "category": "Technology" }
{ "category": "News" }
{ "category": "Technology" }

セレクトフィールドだと決めつけないでください。 次のように尋ねます：

「category には 'Technology' や 'News' のような値があります。次のどちらにしますか？

• 固定の選択肢を持つセレクトフィールド（値は変更されません）
• Categories コレクションへのリレーションシップ（ユーザーが後からカテゴリーを追加／編集／削除できます）」

次のような項目は、デフォルトでリレーションシップにします：

• カテゴリー、タグ、トピック、ラベル
• 作成者、担当者、レビュアー
• 単純な下書き／公開以外のステータス
• 時間の経過とともに増える可能性があるタイプ

セレクトを使うのは、次の場合のみです：

• 本当に固定された列挙型（はい／いいえ、下書き／公開／アーカイブ）
• コンテンツではなくビジネスロジックで定義される選択肢（支払いステータス、優先度レベル）
• 変更すると機能に支障が出る値（コード依存のあるロールタイプ）

リレーションシップを作成する場合は、関連コレクション（Categories、Tags など）を移行計画に追加することを忘れないでください。

リファレンスドキュメント

• PAYLOAD-FIELD-REFERENCE.md - Payload のフィールド型スキーマと例を網羅しています

よくある落とし穴

問題	対処方法
ユーザーから一部のデータしか提供されない	特に例外的なケースについて、追加のサンプルを求めます
リレーションシップが不明確	コンテンツタイプ同士のつながり方をユーザーに説明してもらいます
リッチテキストの仕様が曖昧	Lexical エディター、Slate、または生の HTML の保存のどれにするか確認します
メディアコレクションがない	参照する前に、アップロード用コレクションが存在することを必ず確認します
ネストされたデータが複雑すぎる	フラット化するか、深いグループの代わりにブロックを使うことを検討します