cms-migration

将 CMS 迁移到 Payload

用于根据源 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，还是保留原始格式

可以提出生成 seed 脚本，或带领用户手动导入。

需要厘清的事项

在整个过程中，留意以下问题：

• ID 引用 - 它们是否是指向其他集合的关系？
• 图片/文件 URL - 使用上传字段，还是保留为外部 URL？
• 嵌套对象 - 使用分组、数组还是区块？
• 本地化 - 是否有字段需要按语言环境分别设置值？
• 访问控制 - 谁可以读取/写入此集合？
• 相关内容类型 - 是否需要为分类、标签、作者等创建单独的集合？

关键：选择字段还是关系

这是迁移中最常见的错误。 看似静态的数据，往往需要动态管理。

如果发现重复出现的字符串值（分类、标签、类型、状态）：

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

不要假设它是选择字段。 请询问：

“我看到 category 的值包括 ‘Technology’、‘News’。它应该是：

• 选项固定的选择字段（值不会改变）
• 与 Categories 集合关联的关系（用户以后可以添加/编辑/删除分类）”

对于以下内容，默认使用关系：

• 分类、标签、主题、标记
• 作者、受指派人、审核人
• 超出简单草稿/已发布状态的状态
• 可能随时间扩展的类型

仅在以下情况使用选择字段：

• 确实固定的枚举值（是/否、草稿/已发布/已归档）
• 由业务逻辑定义、而非由内容决定的选项（付款状态、优先级）
• 更改后会导致功能异常的值（具有代码依赖的角色类型）

如果创建关系，请记得将相关集合（Categories、Tags 等）添加到迁移计划中。

参考文档

• PAYLOAD-FIELD-REFERENCE.md - 完整的 Payload 字段类型架构及示例

常见问题

问题	处理方法
用户提供的数据不完整	请用户提供更多样本，尤其是边缘情况
关系不明确	请用户描述内容类型之间的关联方式
富文本存在歧义	明确询问：使用 Lexical 编辑器、Slate，还是存储原始 HTML
缺少媒体集合	在引用上传集合前，务必确认其已存在
嵌套数据过于复杂	考虑扁平化，或使用区块替代深层分组