cms-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CMS Migration to Payload

CMS内容迁移至Payload CMS

Interactive workflow to design Payload collections from source CMS data. Config-first approach: establish the data structure through conversation before any data import.

从源CMS数据设计Payload集合的交互式工作流。采用配置优先的方法：在导入任何数据之前，通过沟通确定数据结构。

Workflow

工作流

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

开始
  ↓
请求数据样本
  ↓
分析数据结构
  ↓
提出集合配置方案
  ↓
用户审核 ──────────────┐
  │                        │
  ├─ 需要修改 ───→ 调整配置 ──→ 返回用户审核
  │
  └─ 确认无误 ───→ 配置确认完成
                            ↓
                    是否还有其他集合？ ──────┐
                            │               │
                            ├─ 是 ──→ 返回请求数据样本
                            │
                            └─ 否 ───→ 所有集合确认完成
                                              ↓
                                      讨论迁移实施方案
                                              ↓
                                            完成

Phase 1: Data Analysis

第一阶段：数据分析

When user provides data (JSON, CSV, or describes their schema):

Identify field types - text, number, date, relationships, media, rich text
Spot patterns - IDs, timestamps, nested objects, arrays
Note relationships - foreign keys, embedded refs, linked content types
Flag ambiguities - fields that could be multiple types, unclear purposes

当用户提供数据（JSON、CSV格式，或描述其数据结构）时：

识别字段类型 - 文本、数字、日期、关联关系、媒体、富文本
发现模式规律 - ID、时间戳、嵌套对象、数组
记录关联关系 - 外键、嵌入式引用、关联内容类型
标记模糊点 - 可能属于多种类型的字段、用途不明确的字段

Phase 2: Propose Collection Config

第二阶段：提出集合配置方案

Present a Payload collection config based on analysis:

typescript

// 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' },
    // ...
  ],
}

Explain your reasoning for each field choice. When something could go multiple ways (group vs JSON, text vs textarea, select vs relationship), ask rather than assume.

基于分析结果提供Payload集合配置：

typescript

// 示例输出格式
export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'content', type: 'richText' },
    { name: 'author', type: 'relationship', relationTo: 'users' },
    // ...
  ],
}

解释每个字段选择的理由。当存在多种可能性时（比如用分组还是JSON、文本还是文本域、选择框还是关联关系），要询问用户而非自行假设。

Phase 3: Iterate with User

第三阶段：与用户迭代优化

Work through uncertainties: required fields, hasMany relationships, rich text vs HTML, custom timestamps vs built-in. Continue until the user confirms the config.

解决不确定的问题：必填字段、多对多关联关系、富文本还是HTML、自定义时间戳还是内置时间戳。持续优化直到用户确认配置无误。

Phase 4: Additional Collections

第四阶段：添加其他集合

After each confirmation, ask:

"Are there other content types we should create collections for?"

If yes, loop back to Phase 1 with new data sample.

Common related collections to prompt for:

Media/uploads
Users/authors
Categories/tags
Settings (global)

每次确认完成后，询问：

"是否还有其他需要创建集合的内容类型？"

如果是，回到第一阶段处理新的数据样本。

常见的需提示的关联集合：

媒体/上传文件
用户/作者
分类/标签
设置（全局）

Phase 5: Migration Approach

第五阶段：迁移实施方案

Only after ALL collections are confirmed, discuss data import:

Order matters - which collections have no dependencies? Migrate those first
Relationship mapping - how to resolve source IDs to Payload IDs
Media handling - download/re-upload vs external URLs
Rich text - HTML conversion needs or keep raw

Offer to generate a seed script or walk through manual import.

仅在所有集合确认完成后，讨论数据导入事宜：

顺序很重要 - 哪些集合没有依赖关系？优先迁移这些集合
关联关系映射 - 如何将源ID转换为Payload ID
媒体处理 - 下载重新上传还是保留外部URL
富文本处理 - 是否需要转换HTML格式还是保留原始内容

可提供生成种子脚本或指导手动导入的服务。

Things to Clarify

需要澄清的事项

Throughout the process, watch for these:

ID references - are they relationships to other collections?
Image/file URLs - upload fields or keep as external URLs?
Nested objects - group, array, or blocks?
Localization - any fields need per-locale values?
Access control - who can read/write this collection?
Related content types - categories, tags, authors that need their own collections?

在整个过程中，注意以下几点：

ID引用 - 这些是否是与其他集合的关联关系？
图片/文件URL - 是使用上传字段还是保留为外部URL？
嵌套对象 - 使用分组、数组还是区块？
本地化 - 是否有字段需要按区域设置不同的值？
访问控制 - 哪些用户可以读写该集合？
关联内容类型 - 分类、标签、作者等是否需要单独的集合？

Critical: Select vs Relationship

关键要点：选择框 vs 关联关系

This is the most common migration mistake. Data that looks static often needs to be dynamic.

When you see repeated string values (categories, tags, types, statuses):

json

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

Don't assume it's a select field. Ask:

"I see
category
has values like 'Technology', 'News'. Should this be:
A select field with fixed options (values won't change)

A relationship to a Categories collection (users can add/edit/remove categories later)"

Default to relationship for anything that looks like:

Categories, tags, topics, labels
Authors, assignees, reviewers
Statuses beyond simple draft/published
Types that might expand over time

Use select only for:

Truly fixed enums (yes/no, draft/published/archived)
Options defined by business logic, not content (payment status, priority levels)
Values that would break functionality if changed (role types with code dependencies)

If creating a relationship, remember to add the related collection (Categories, Tags, etc.) to the migration plan.

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

当看到重复的字符串值（如分类、标签、类型、状态）时：

json

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

**不要假设这是选择框字段。**请询问：

"我注意到
category
字段有'Technology'、'News'等值。它应该设置为：
带有固定选项的选择框字段（值不会更改）

与Categories集合关联的关联关系（用户后续可添加/编辑/删除分类）"

对于以下类型，默认使用关联关系：

分类、标签、主题、标签
作者、经办人、审核人
除简单草稿/已发布外的状态
可能随时间扩展的类型

仅在以下情况使用选择框：

真正固定的枚举值（是/否、草稿/已发布/归档）
由业务逻辑而非内容定义的选项（支付状态、优先级）
更改会破坏功能的值（与代码依赖关联的角色类型）

如果设置为关联关系，请记得将相关集合（如Categories、Tags等）加入迁移计划。

Reference Documentation

参考文档

PAYLOAD-FIELD-REFERENCE.md - Complete Payload field type schemas with examples

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

Common Pitfalls

常见陷阱

Issue	How to Handle
User provides partial data	Ask for more samples, especially edge cases
Unclear relationships	Ask user to describe how content types connect
Rich text ambiguity	Clarify: Lexical editor, Slate, or store raw HTML
Missing media collection	Always confirm upload collection exists before referencing
Overly complex nested data	Consider flattening or using blocks instead of deep groups

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