snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/user-guide/data-migration/capabilities/error-handling.mdx

@@ -0,0 +1,76 @@
+---
+title: 错误处理与验证
+description: 在确认之前，直接在 UI 中查看并修复导入错误。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 导入前验证
+
+上传文件并完成字段映射后，Twenty 会在导入**之前**验证你的数据。 这样可以在不影响现有数据的情况下捕捉并修复错误。
+
+## 工作原理
+
+1. **上传**您的 CSV 文件
+2. **映射**您的列到 Twenty 的字段
+3. **查看**黄色高亮的潜在错误
+4. 可直接在 UI 中**修复错误**
+5. **确认**导入
+
+<VimeoEmbed videoId="1145273857" title="视频演示" />
+
+## 错误显示
+
+存在问题的行会被高亮为**黄色**。 您可以：
+
+* **直接编辑单元格**以修复错误
+* **删除该行**以完全跳过该行
+
+这种行内编辑可节省时间——无需返回电子表格、修复错误并重新上传。
+
+## 常见错误类型
+
+### 重复值
+
+**原因**：唯一字段（电子邮件、域名）已在 Twenty 中存在，或在您的文件中出现了两次。
+
+**修复**：
+
+* 在导入 UI 中编辑重复值
+* 删除其中一条重复的行
+
+关于如何实施唯一性，详见[唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)。
+
+### 格式无效
+
+**原因**：数据与期望的格式不匹配（例如，电子邮件无效、日期格式错误）。
+
+**修复**：编辑单元格，使其符合正确格式。
+
+请参见[字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping)，了解每种字段类型的期望格式。
+
+### 缺少必填字段
+
+**原因**：必填字段为空。
+
+**修复**：在必填字段中输入值，或删除该行。
+
+### 未找到关系
+
+**原因**：被引用的记录不存在（例如，公司域名尚未导入）。
+
+**修复**：
+
+* 先导入父级记录
+* 或更正引用值
+
+有关正确的导入顺序及如何关联记录，参见[导入关系](/l/zh/user-guide/data-migration/capabilities/import-relations)。
+
+## 减少错误的建议
+
+1. **下载模板** 以在导入文件前查看预期格式
+2. 先在电子表格中，**清理您的数据**
+3. **按正确顺序导入文件**以导入关系（公司 → 联系人 → 商机）
+4. **用小批量进行测试**，再进行完整导入
+5. 在上传前，**检查重复项**
+6. **将每个文件限制为1万条记录**

packages/twenty-docs/l/zh/user-guide/data-migration/capabilities/field-mapping.mdx

@@ -0,0 +1,198 @@
+---
+title: 字段映射
+description: 数据导入期间字段映射的工作原理。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 字段映射的工作原理
+
+当您上传文件时，Twenty 会分析您的列，并尝试将其与现有字段匹配。
+
+### 自动映射
+
+Twenty 将根据以下内容尝试匹配列：
+
+* 列标题名称（精确或相似匹配）
+* 数据类型检测（日期、数字、电子邮件）
+* 常见字段模式
+
+<Note>**快速提示：** 从您要导入的对象中导出几行数据。 导出的文件将包含 Twenty 期望的精确列名，从而在导入时实现无缝的自动映射。</Note>
+
+### 手动映射选项
+
+对于每一列，您可以：
+
+* **映射到字段**：从下拉列表中选择匹配的 Twenty 字段
+* **不进行映射**：完全跳过该列（不会导入数据）
+
+<Note>**字段必须在导入前已存在。** 导入会创建记录，而不是创建字段。 请在导入前于 **设置 → 数据模型** 中创建自定义字段。</Note>
+
+## 字段类型兼容性
+
+数据模型中可用的所有字段类型都支持导入。
+
+您也可以导入 `id` 值，以便为新记录指定特定 ID，或更新现有记录。
+
+<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}} />
+
+## 数据格式要求
+
+<Note>**某些字段有特殊语法。** 我们建议在准备导入之前下载示例文件，以查看每种字段类型的预期语法。</Note>
+
+### 地址字段
+
+地址是一个嵌套字段，包含多个列。 其中一些可以留空。
+
+* **Address / Address 1**：街道地址第 1 行
+* **Address / Address 2**：街道地址第 2 行
+* **Address / City**：城市名称
+* **Address / State**：州或省
+* **Address / Country**：国家名称
+* **Address / Post Code**：邮政/ZIP 编码
+
+### 数组字段
+
+使用以下格式：
+
+```
+["value1","value2"]
+```
+
+### 布尔字段
+
+使用 `TRUE` 或 `FALSE`（大写），不要使用 `true` 或 `false`
+
+### 货币字段
+
+货币是一个**嵌套字段**，需要两列，且**两列都必须填写**：
+
+* **Amount / Amount**：数值（例如，`1234.56`）
+* **Amount / Currency**：货币代码（例如，`USD`、`EUR`）
+
+### 日期字段
+
+支持的格式：
+
+* `YYYY-MM-DD`（推荐）
+* `MM/DD/YYYY`
+* `DD/MM/YYYY`
+* ISO 8601 格式
+
+### 域名字段
+
+* 建议使用 `https://domain.com` 格式以避免创建重复，因为通过邮箱和日历同步创建的公司会使用该格式
+* 可以填写 `Domain Label` 和 `Domain URL`：最佳做法是在标签中填写 `domain.com`，在 url 中填写 `https://domain.com`
+* 在 Companies 对象内，域名必须唯一
+* **待导入文件中的域名必须唯一**
+
+### 电子邮件字段
+
+* 必须为有效的电子邮件格式
+* 在 People 对象内，电子邮件必须唯一
+* **待导入文件中的电子邮件必须唯一**
+* 对于附加邮箱：主邮箱请使用 **Emails / Primary Email**，附加邮箱请使用 **Emails / Additional Emails**，并采用以下格式：
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### ID 字段
+
+在导入过程中指定 `id` 是可选的。 如未提供，Twenty 将自动生成 ID。
+
+映射 `id` 列的用例：
+
+* **设置特定 ID**：为新创建的记录选择 UUID
+* **更新现有记录**：与现有记录进行匹配以更新它们，而不是创建重复项。 在这种情况下，建议不要映射其他唯一字段：仅映射一个唯一字段可确保导入更顺畅。
+
+<Note>如果您提供 `id`，其必须为 UUID 格式（例如，`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）。</Note>
+
+### JSON 字段
+
+使用有效的 JSON 格式：
+
+```
+{"key":"value","key2":"value2"}
+```
+
+### 链接字段
+
+与域名字段类似：
+
+* 同时填写标签和 URL 两列：**Links / Link URL** 和 **Links / Link Label**
+* 使用完整的 URL 格式：`https://example.com`
+* 对于次要链接，请使用 **Links / Secondary Links** 列，并采用以下格式：
+
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### 多选字段
+
+使用**API 名称**（而非显示标签），格式如下：
+
+```
+["VALUE1","VALUE2"]
+```
+
+请参见[此处](#finding-api-names-for-select-fields)了解如何查找 API 名称。
+
+<Note>新的选择项不会通过导入自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。</Note>
+
+<Warning>
+**导入会覆盖，不会追加。**
+
+如果一条记录已选择了 `VALUE2` 和 `VALUE3`，而您导入了 `["VALUE1"]`，则导入后该记录将只保留 `VALUE1`。 之前的选择会被替换，而不是合并。
+</Warning>
+
+### 数字字段
+
+* 仅限数字
+* 小数使用点号：`1234.56`
+* 不使用千位分隔符
+
+### 电话字段
+
+电话是一个包含多列的嵌套字段，且**必须填写**
+
+* **Phones / Primary Phone Number**：电话号码（例如，`4159095555`）
+* **Phones / Primary Phone Country Code**：国家代码（例如，`US`）
+* **Phones / Primary Phone Calling Code**：拨号代码（例如，`+1`）
+
+### 评分字段
+
+使用 API 名称格式：`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4`、`RATING_5`
+
+### 关系字段
+
+请参阅我们的专门文章：[在对象之间导入关联](/l/zh/user-guide/data-migration/capabilities/import-relations)
+
+### 选择字段
+
+使用选项的**API 名称**（而不是显示标签）：
+
+```
+VALUE1
+```
+
+请参见[此处](#finding-api-names-for-select-fields)了解如何查找 API 名称。
+<Note>新的选择项不会通过导入自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。</Note>
+
+### 文本字段
+
+* 无需特殊格式
+* 首尾空格会被移除
+
+## 查找 API 名称
+
+对于具有预定义选项的 Select、Multi-Select 和 Array 字段，必须使用 **API 名称**，而不是显示标签。
+
+### 如何查找 API 名称
+
+1. 进入 **设置 → 数据模型**
+2. 选择对象和字段
+3. 启用 **高级模式**（在设置页面右下角切换）
+4. 查看每个选项的 API 名称
+
+<VimeoEmbed videoId="1144910809" title="视频演示" />

packages/twenty-docs/l/zh/user-guide/data-migration/capabilities/file-formats.mdx

@@ -0,0 +1,48 @@
+---
+title: 支持的文件格式
+description: 在 Twenty 中用于数据导入的受支持文件格式。
+---
+
+## 支持的格式
+
+Twenty 支持三种导入文件格式：
+
+| 格式            | 扩展名   | 备注          |
+| ------------- | ----- | ----------- |
+| **CSV**       | .csv  | 推荐，兼容性最佳    |
+| **Excel**     | .xlsx | 现代 Excel 格式 |
+| **Excel（旧版）** | .xls  | 旧版 Excel 格式 |
+
+## 文件要求
+
+| 要求       | 值                 |
+| -------- | ----------------- |
+| **编码**   | 推荐使用 UTF-8        |
+| **记录上限** | 每个文件最多 10,000 条记录 |
+| **结构**   | 第一行必须包含列标题        |
+| **内容**   | 每个文件仅包含一种对象类型     |
+
+## CSV 最佳实践
+
+* **分隔符**：使用逗号（`,`）或分号（`;`）
+* **文本限定符**：对于包含逗号的文本，请使用双引号（`"`）
+* **行结束符**：支持 Windows（CRLF）或 Unix（LF）
+* **空值**：将单元格留空，不要使用 "NULL" 或 "N/A"
+
+## Excel 最佳实践
+
+从 Excel 导出时：
+
+* 移除公式（仅导出值）
+* 删除末尾的空行
+* 确保没有合并单元格
+* 仅使用第一个工作表
+
+## 大型数据集
+
+对于超过 10,000 条记录的数据集：
+
+* 拆分为多个文件
+* 或者使用 [API 导入](/l/zh/user-guide/data-migration/how-tos/import-data-via-api) 以导入无限数量的记录
+
+<Note>对于非常大的迁移（100,000+ 条记录），API 比 CSV 导入明显更快且更可靠。</Note>

packages/twenty-docs/l/zh/user-guide/data-migration/capabilities/import-relations.mdx

@@ -0,0 +1,148 @@
+---
+title: 导入对象之间的关系
+description: 通过 CSV 导入记录之间的关系。
+---
+
+## 概览
+
+Twenty 支持在 CSV 导入过程中导入对象之间的关系。 这使您可以在数据迁移过程中关联记录（例如，将人员关联到公司）。
+
+<Note>**当前支持导入**：两侧均指向单一对象类型的一对多关系（例如，人员 → 公司）。 指向多个对象类型的关系目前尚不支持导入/导出。</Note>
+
+## Twenty 中关系的工作方式
+
+### 一对多 / 多对一
+
+Twenty 支持一条记录关联到多条记录的标准关系：
+
+* **一个公司 → 多个人员**：一家公司可以有多名员工，但每个人只隶属于一家公司
+* **一个公司 → 多个商机**：一家公司可以有多个商机，但每个商机只属于一家公司
+
+### 可指向多种对象类型的关系
+
+某些关系可以连接到不同类型的对象。 这有两种方式：
+
+**模式 1：来自不同对象类型的多条记录，各自链接到一条记录**
+
+几个笔记或任务可以同时附加到多个对象类型：
+
+* **笔记** 可以同时关联到一个人员、一个公司和一个商机
+* **任务** 可以同时关联到一个人员、一个公司和一个商机
+
+在此场景中，笔记/任务位于“多”的一侧。 每条记录在每种对象类型上都仅链接到一条记录。
+
+<img src="/images/user-guide/fields/many-to-one-morph.png" style={{width:'100%'}} />
+
+**模式 2：一条记录接收来自不同对象类型的多条记录的链接**
+
+一个项目可以接收来自不同对象类型的多条记录的链接：
+
+* **一个项目** 可以关联到许多人员、许多公司，并附加许多笔记
+
+在此场景中，项目位于“一”的一侧。 来自不同对象的多条记录都可以链接到同一个项目。
+
+<img src="/images/user-guide/fields/one-to-many-morph.png" style={{width:'100%'}} />
+
+<Warning>
+**导入/导出限制**：指向多个对象类型的关系（如 笔记 → 人员/公司/商机）在 CSV 导入或导出中**尚不支持**。
+
+* **导入**：仅支持导入两侧均指向单一对象类型的一对多关系
+* **导出**：指向多个对象类型的关系列目前会留空
+
+此功能已在我们的路线图中。
+</Warning>
+
+### 当前不支持的内容
+
+**多对多关系** 目前尚不可用。 例如，您目前无法创建如下关系：
+
+* 多个人员关联到多个项目
+
+<Note>多对多关系计划在 2026 年下半年推出。</Note>
+
+## 在导入过程中关联记录
+
+<Note>**提醒**：仅可导入指向单一对象类型的一对多关系（例如，人员 → 公司）。 指向多个对象类型的关系（例如，笔记 → 人员/公司/商机）目前尚不支持。</Note>
+
+### 步骤 1：确定“一”和“多”两侧
+
+首先，确定关系中哪个对象位于“一”侧，哪个对象位于“多”侧。
+
+**示例**：
+
+* **公司** 位于“一”侧（一个公司有许多员工）
+* **人员** 位于“多”侧（每个人都隶属于一家公司）
+
+### 步骤 2：确保“一”侧的记录已存在
+
+在导入“多”侧之前，“一”侧的记录必须已在 Twenty 中存在。
+
+* 请先导入或创建“一”侧的记录（例如，公司）
+* 验证其唯一标识符。 可以是：
+  * `id`（Twenty 的 UUID）
+  * 一个被设置为唯一的字段（例如，公司的 `domain`，或您先前系统中的外部 ID）
+
+<Warning>若引用了不存在的记录，导入将失败。</Warning>
+
+### 步骤 3：准备您的 CSV 文件
+
+在“多”侧的 CSV 文件中添加一列，用于引用“一”侧的记录。
+
+**示例**：对于将人员关联到公司的 CSV 文件：
+
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**重要**：
+
+* 该值必须与公司记录上的唯一字段**完全匹配**
+* 对于域名，请使用**域名 URL**（例如，`https://acme.com`），而不是域名标签
+* 每个关系只映射**一个**唯一标识符：这将使导入更顺畅
+
+### 步骤 4：核实关系字段是否存在
+
+在上传文件之前，确保对象之间已存在关系字段。
+
+如果不存在：
+
+1. 进入 **设置 → 数据模型**
+2. 选择您的对象（例如，人员）
+3. 创建一个指向目标对象（例如，公司）的关系字段
+
+### 步骤 5：上传并映射关系
+
+1. 通过导入界面上传您的 CSV 文件
+2. 在字段映射步骤中，找到您的关系列（例如，`companyDomain`）
+3. 将其映射到关系字段（例如，公司）
+4. Twenty 将自动把每条记录关联到匹配的父级
+
+### 可用于关系的唯一字段
+
+| 对象               | 可用的唯一字段                 |
+| ---------------- | ----------------------- |
+| **公司**           | `id`、`domain`，任何自定义唯一字段 |
+| **人员**           | `id`、`email`，任何自定义唯一字段  |
+| **工作区成员**        | `id`、`email`（而非姓名）      |
+| **其他标准对象和自定义对象** | `id`，或任何标记为唯一的字段        |
+
+<Note>**关联到工作区成员**：当关系指向工作区成员（您的团队登录 Twenty）时，请使用其**电子邮件地址**进行引用，而不是姓名。</Note>
+
+<Note>我们建议对公司使用 `domain`，对人员使用 `email`，因为这些字段可读性强，且易于在电子表格中维护。</Note>
+
+<Note>**提醒**：软删除的记录（可在“命令菜单 → 查看已删除的记录”中查看）计入唯一性判定标准。 如果您导入的记录与某条已删除记录具有相同的唯一值，该已删除记录将被还原。 详见[唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)。</Note>
+
+## 导入顺序规则
+
+<Warning>
+**务必先导入“一”端！**
+
+1. **公司** 优先（无依赖关系）
+2. **人员** 其次（关联到公司）
+3. **商机** 第三（关联到公司/人员）
+4. **自定义对象**（按其依赖关系）
+
+在引用之前，父级记录必须已存在。
+</Warning>

packages/twenty-docs/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints.mdx

@@ -0,0 +1,72 @@
+---
+title: 唯一性约束
+description: Twenty 如何在导入过程中强制确保数据唯一性。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 概览
+
+Twenty 会在特定字段上强制唯一性，以防止重复记录并确保数据完整性。 了解这些约束对于成功导入至关重要。
+
+## 默认唯一字段
+
+| 对象        | 唯一字段           |
+| --------- | -------------- |
+| **人员**    | `id`, `email`  |
+| **公司**    | `id`, `domain` |
+| **自定义对象** | 仅 `id`（默认）     |
+
+<Note>`id` 字段是 Twenty 的内部标识符，为每条记录自动生成。 它使用 UUID 格式（例如，`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）。</Note>
+
+## 自定义唯一字段
+
+您可以在 **设置 → 数据模型** 下定义其他唯一字段：
+
+1. 进入 **设置 → 数据模型**
+2. 选择一个对象
+3. 点击某个字段
+4. 在字段设置中启用 **Unique**
+
+### 自定义唯一字段的使用场景
+
+* **外部 ID**：存储来自其他系统的 ID（Salesforce ID、HubSpot ID）
+* **业务标识符**：员工编号、客户代码
+* **替代联系方式**：LinkedIn 资料、电话号码
+
+<Note>字段名 `id` 保留给 Twenty 的内部 ID。 外部标识符请使用 `externalId` 或 `legacyId` 等其他名称。</Note>
+
+## 导入行为
+
+### 创建新记录
+
+如果唯一字段的值不存在，将创建一条新记录。
+
+### 更新现有记录
+
+如果唯一字段的值与现有记录匹配，该记录将使用新数据进行**更新**。
+<Warning>要**更新现有记录**，建议**仅匹配一个唯一字段**。</Warning>
+
+### 软删除的记录
+
+<Warning>
+**已删除的记录也会计入唯一性。**
+
+软删除的记录（可在“命令菜单 → 查看已删除的记录”中查看）会包含在唯一性检查中。 如果您导入的记录与某条已删除记录具有相同的唯一值，该已删除记录将被**还原**，并使用新数据。
+</Warning>
+
+## 导入过程中的重复检测
+
+在验证阶段：
+
+* 文件中的重复项会以黄色高亮显示
+* 开始导入前，您可以在界面中编辑或移除重复的行
+
+<VimeoEmbed videoId="1145246326" title="视频演示" />
+
+## 最佳实践
+
+1. 在导入前，**从文件中移除重复项**
+2. 在导入前，在 Twenty 中**检查是否存在现有记录**
+3. 从其他系统迁移时，**使用外部 ID**
+4. 如果您希望更新现有记录，请**包含唯一字段**

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/export-faq.mdx

@@ -0,0 +1,32 @@
+---
+title: 导出常见问题
+description: 经常询问有关导出数据的问题。
+---
+
+<AccordionGroup>
+<Accordion title="我们能否在取消之前导出所有工作区数据，包括自定义对象、自定义领域、关系、说明、任务、机会、附件、工作流、权限和审计历史？">
+取消之前可以导出工作区数据，但有一些例外：必须手动转移仪表板、工作流量和权限；不能转移审计日志。
+</Accordion>
+<Accordion title="哪些元素目前不能导出或迁移？">
+大多数元素可以导出或迁移，但有一些例外：
+* 工作流、仪表板和所有设置 (API 键、网络钩子、审计日志、用户设置等) 必须手动迁移
+* 应用程序创建的对象和字段可以通过在不同的工作区中安装所说的应用进行迁移。 他们不应手动迁移
+* 一些记录，如工作流版本和工作流运行，根本无法转移，预计会丢失
+* 某些对象，如消息和日历相关对象不应被导出，因为它们是在帐户连接并定期同步时创建的。 一旦您连接到您的帐户，他们将再次同步(只要您有权访问该帐户)。 如果是离开您公司的团队成员的帐户，那么这些消息必须导出，不然就会丢失)
+</Accordion>
+<Accordion title="是否有自收自留的移徙程序的官方云，或得到协助的移徙服务？">
+到目前为止，还没有正式的由云端对自我接纳的移徙程序。 总的想法是：
+* 首先，安装应用程序来引入应用拥有的对象和字段
+* 复制用户添加的自定义对象和字段
+* 使用 API 密钥或 AI 工具的脚本将所有数据从一个工作区迁移到另一个工作区
+* 所有不可转移对象必须手动迁移
+
+请注意以下几件事：
+* 您可以在 Pro 计划中每分钟发送最多50个请求，或者在本组织计划中每分钟发送100个请求，然后点击请求/最小限制
+* 每个API请求最多可以有 200 条记录
+* 一些字段中的数据创建者, 时间线活动和更新者将在导入过程中丢失, 并被系统覆盖
+</Accordion>
+<Accordion title="导出的文件是否以开放和有文件记录的格式提供？">
+在UI中导出的文件使用Excel格式，所有API请求都可以保存为 JSON 格式。
+</Accordion>
+</AccordionGroup>

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/export-your-data.mdx

@@ -0,0 +1,209 @@
+---
+title: 导出您的数据
+description: 从 Twenty 导出数据的完整分步指南。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 概览
+
+将您的工作区数据导出为 CSV，用于备份、报表或迁移。
+
+**使用场景：**
+
+* **定期备份** — 保留您的数据副本
+* **外部报表** — 在 Excel、Google 表格或 BI 工具中分析数据
+* **迁移** — 将数据迁移到其他系统
+* **批量更新** — 通过导出、编辑并重新导入来更新记录
+
+## 您需要了解的内容
+
+### 导出限制
+
+* **每次导出最多 20,000 条记录**
+* 仅导出**可见列**
+* 仅导出**筛选后的记录**（基于您当前视图）
+
+<Note>对于更大的导出（20,000+ 条记录），请使用筛选器分批导出，或使用 [API](/l/zh/developers/extend/api)。</Note>
+
+### 权限
+
+导出数据需要拥有 **"Export CSV"** 权限。 如果您没有此选项，请联系您的工作区管理员。
+
+## 步骤 1：导航到对象
+
+前往您要导出的对象：
+
+* **People** — 用于联系人
+* **Companies** — 用于组织
+* **Opportunities** — 用于商机
+* **自定义对象** — 您创建的任意对象
+
+## 步骤 2：配置您的视图
+
+\*\*重要：\*\*导出仅包含您当前视图中可见的内容。
+
+### 添加/移除列
+
+1. 单击 **Options → Fields**（或单击列末尾的 **+**）
+2. 勾选您要导出的字段
+3. 取消勾选不需要的字段
+
+### 筛选记录（可选）
+
+如果您只需要数据的一个子集：
+
+1. 单击 **Filter**
+2. 添加筛选条件（例如："Created date > January 1, 2024"）
+3. 仅会导出匹配的记录
+
+### 排序记录（可选）
+
+1. 单击列标题进行排序
+2. 导出将遵循您的排序顺序
+
+<Note>**创建专用的导出视图。** 保存一个专为导出配置的视图，这样每次就无需重新配置。</Note>
+
+## 步骤 3：导出数据
+
+1. 单击表格右上角的 **⋮** 图标
+2. 选择 **Export view**
+3. 选择 CSV 文件的保存位置
+4. 等待下载完成
+
+## 导出内容
+
+| 包含           | 不包含      |
+| ------------ | -------- |
+| 所有可见列        | 隐藏列      |
+| 与当前筛选条件匹配的记录 | 被过滤掉的记录  |
+| 自定义字段值       | 不在视图中的字段 |
+| 记录 ID        | 文件附件     |
+| 关系 ID        | 图片       |
+
+### 关系字段
+
+关系 ID 仅在关系的\*\*“多”端\*\*导出：
+
+* **People 导出** 包含一个 `companyId` 列（People → Company 关系）
+* **Companies 导出** 不包含 `peopleIds`（Companies 是“一”端）
+
+这意味着您可以使用 People 的导出来重新导入并保持与 Company 的链接，但您需要在导入 Companies 之后再次导入 People 以重新创建这些关系。
+
+## 针对特定目的的导出
+
+### 用于备份
+
+1. 创建一个显示**所有字段**的视图
+2. 移除所有筛选器以包含所有记录
+3. 分别导出每种对象类型
+4. 将导出文件存储在安全位置
+5. 设置重复提醒（每周/每月）
+
+### 用于外部报表
+
+1. 只包含您进行分析所需的字段
+2. 应用筛选器以聚焦相关数据
+3. 考虑按您将要分析的字段进行排序
+
+### 用于批量更新
+
+1. 导出您要更新的记录
+2. 包含唯一标识符（`email`、`domain` 或 `id`）
+3. 编辑导出的文件
+4. 重新导入以更新记录
+   参见：[如何更新现有记录](/l/zh/user-guide/data-migration/how-tos/update-existing-records-via-import)
+
+### 用于迁移
+
+如果您为迁移到其他系统而进行导出：
+
+1. **分别导出每个对象** — People、Companies、Opportunities 等。
+2. **包含 ID 字段** — 有助于维护关系
+3. **记录字段映射** — 记录 Twenty 字段如何映射到您的目标系统
+
+## 处理大型数据集（20,000+ 条记录）
+
+导出限制为 20,000 条记录。 对于更大的数据集：
+
+### 选项 1：分批导出
+
+1. 添加一个筛选器（例如 "Created date" 范围）
+2. 导出第一批
+3. 更改筛选器
+4. 导出下一批
+5. 在电子表格中合并文件
+
+**用于分批的示例筛选器：**
+
+* 按日期范围（1 月、2 月、3 月……）
+* 按所有者（团队成员 A、团队成员 B……）
+* 按状态（活跃、非活跃……）
+
+### 选项 2：使用 API
+
+API 没有记录数量限制：
+
+1. 在 **Settings → Developers** 中获取您的 API 密钥
+2. 使用 GraphQL API 查询记录
+3. 在您的应用程序中处理结果
+
+参见：[API 文档](/l/zh/developers/extend/api)
+
+## 技巧与最佳实践
+
+### 创建导出视图
+
+保存专为导出配置的视图：
+
+1. 配置列和筛选器
+2. 单击 **View options** → **Save as new view**
+3. 将其命名为 "Export - [Purpose]"
+
+### 保护您的导出文件安全
+
+导出的文件可能包含敏感数据：
+
+* 存放在安全位置
+* 不再需要时删除旧的导出文件
+* 共享导出文件时请谨慎
+
+### 导出前检查
+
+<Check>显示了正确的列</Check>
+<Check>筛选器设置正确（或为完整导出已移除）</Check>
+<Check>您具有导出权限</Check>
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="为什么我的导出缺少某些列？">
+    仅导出可见列。 在导出之前通过 **Options → Fields** 添加所需的列。
+  </Accordion>
+
+  <Accordion title="为什么我的导出没有包含所有记录？">
+    检查您的筛选器。 导出仅包含与您当前视图筛选条件匹配的记录。 移除筛选器以导出所有记录。
+  </Accordion>
+
+  <Accordion title="我可以导出超过 20,000 条记录吗？">
+    单次导出不可以。 使用筛选器分批导出，或使用 API 处理更大的数据集。
+  </Accordion>
+
+  <Accordion title="导出文件是什么格式？">
+    CSV（逗号分隔值）。 可在 Excel、Google 表格或任何电子表格应用中打开。
+  </Accordion>
+
+  <Accordion title="是否包含关系 ID？">
+    包含，但仅限于关系的“多”端。 例如，People 的导出包含 `companyId`，但 Companies 的导出不包含人员 ID。
+  </Accordion>
+
+  <Accordion title="我可以自动化导出吗？">
+    无法直接通过 UI 实现。 使用 API 构建自动化的导出工作流。
+  </Accordion>
+</AccordionGroup>
+
+## 下一步
+
+* [如何更新现有记录](/l/zh/user-guide/data-migration/how-tos/update-existing-records-via-import) — 编辑并重新导入您的导出文件
+* [如何通过 API 导入数据](/l/zh/user-guide/data-migration/how-tos/import-data-via-api) — 适用于大型数据集
+* [API 文档](/l/zh/developers/extend/api) — 构建自定义导出工作流

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/fix-import-errors.mdx

@@ -0,0 +1,430 @@
+---
+title: 修复导入错误
+description: 解决 CSV 导入错误的完整故障排除指南。
+---
+
+## 概览
+
+导入无法正常工作？ 本指南将逐步帮助你识别并修复常见的导入错误。
+
+## 导入验证的工作原理
+
+上传文件并完成列映射后，Twenty 会对你的数据进行验证：
+
+1. **开始验证** — Twenty 会逐行检查是否存在错误
+2. **错误会被高亮** — 有问题的行将以**黄色**显示
+3. **可就地修复** — 可在导入界面中直接编辑单元格
+4. **或移除行** — 完全跳过有问题的记录
+
+<Note>**在界面中修复错误。** 无需返回电子表格。 在导入过程中直接编辑单元格以节省时间。</Note>
+
+## 分步故障排查
+
+### 步骤 1：确定错误类型
+
+点击高亮的行查看具体的错误信息。 常见错误类型：
+
+| 错误消息                                                         | 含义                           |
+| ------------------------------------------------------------ | ---------------------------- |
+| 重复值以黄色高亮显示                                                   | 该值已存在于 Twenty 中，或在你的文件中出现了两次 |
+| `{field} is not a valid {type}`（将鼠标悬停在黄色单元格上）                | 数据与预期格式不匹配                   |
+| 必填字段被高亮显示                                                    | 必填字段为空                       |
+| `Can't connect to {object}. No unique record found...`（导入失败） | 被引用的记录不存在                    |
+| `Too many records. Up to 10000 allowed`（已阻止上传）               | 文件包含超过 10,000 条记录            |
+
+### 步骤 2：修复错误
+
+根据下面针对每种错误类型的具体说明进行处理。
+
+---
+
+## 错误：重复值
+
+### 您将会看到什么
+
+在开始导入之前，导入界面中包含重复值的行会被**黄色高亮**。
+
+### 含义
+
+唯一字段（电子邮件、域名）可能：
+
+* 已存在于 Twenty 中
+* 在你的文件中出现了两次
+
+### 修复方法
+
+**选项 1：编辑重复值**
+
+1. 点击包含错误的单元格
+2. 更改为唯一值
+3. 继续导入
+
+**选项 2：移除重复行**
+
+1. 点击该行旁的 X
+2. 导入时将跳过该行
+
+**选项 3：让 Twenty 更新现有记录**
+
+1. 确保你的文件包含唯一标识符（`email`、`domain` 或 `id`）
+2. 映射该唯一标识符字段
+3. Twenty 将更新现有记录，而不是创建重复项
+
+<Note>
+**你也可以更新唯一字段。**
+
+* 如果保留 `id` 但更改 `email` → 将更新该电子邮件
+* 如果保留 `email` 但更改 `id` → 将更新该 id
+
+只要至少有一个唯一标识符匹配，Twenty 就会更新该记录。
+</Note>
+
+### 如何避免此错误
+
+导入前：
+
+1. 按唯一字段对电子表格进行排序
+2. 删除重复行
+3. 检查 Twenty 中是否已存在这些记录
+
+<Warning>
+**软删除的记录也会计入唯一性。**
+
+检查 Command Menu → 查看已删除的记录。 其中的记录仍会参与唯一性校验。 将其永久删除，或还原后再更新。
+</Warning>
+
+了解更多详情：[唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)
+
+---
+
+## 错误：格式无效
+
+### 您将会看到什么
+
+该单元格的值会以黄色高亮显示。 将鼠标悬停其上以查看错误信息：
+
+```
+{field name} is not a valid {field type}
+```
+
+### 含义
+
+该数据与该字段类型的预期格式不匹配。
+
+### 修复方法 — 按字段类型
+
+#### 电子邮件
+
+**问题：** 电子邮件格式无效
+**解决方案：** 使用 `name@domain.com` 格式
+
+```
+❌ john.smith@
+❌ john smith@acme.com
+✓ john.smith@acme.com
+```
+
+#### 域
+
+**问题：** 格式不一致可能导致重复
+**解决方案：** 使用 `https://domain.com` 格式（推荐）
+
+```
+⚠️ acme.com         (valid, but not recommended)
+⚠️ www.acme.com     (valid, but not recommended)
+✅ https://acme.com  (recommended)
+```
+
+<Note>所有格式都有效，但推荐使用 `https://domain.com`，因为它与电子邮件/日历同步所用的格式一致。 使用其他格式可能会创建重复的公司。</Note>
+
+#### 日期
+
+**问题：** 无法识别的日期格式
+**解决方案：** 在整个文件中一致使用 `YYYY-MM-DD` 格式
+
+```
+✓ 2024-03-15        (YYYY-MM-DD)
+❌ 03/15/2024        (MM/DD/YYYY)
+❌ 15/03/2024        (DD/MM/YYYY)
+```
+
+#### 电话
+
+**问题：** 缺少必需的列
+**解决方案：** 包含所有电话相关列
+
+| 列                                       | 示例           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **Phones / Primary Phone Calling Code** | `+1`         |
+
+#### 布尔值
+
+**问题：** 布尔值不正确
+**解决方案：** 使用大写的 `TRUE` 或 `FALSE`
+
+```
+❌ true
+❌ yes
+❌ 1
+✓ TRUE
+✓ FALSE
+```
+
+#### 选择/多选
+
+**问题：** 值与现有选项不匹配
+**解决方案：** 使用**API 名称**，而非显示标签
+
+如何查找 API 名称：
+
+1. 进入 **设置 → 数据模型**
+2. 选择对象和字段
+3. 启用 **高级模式**（右下角切换）
+4. 使用 API 名称（例如：`OPTION_1`，而不是 "Option 1"）
+
+```
+❌ High Priority
+✓ HIGH_PRIORITY
+```
+
+#### 货币
+
+**问题：** 缺少金额或货币代码
+**解决方案：** 同时填写这两列
+
+| 列                     | 示例        |
+| --------------------- | --------- |
+| **Amount / Amount**   | `1234.56` |
+| **Amount / Currency** | `USD`     |
+
+#### 数字
+
+**问题：** 含非数字字符
+**解决方案：** 只能使用数字，小数点用英文句点
+
+```
+❌ $1,234.56
+❌ 1,234.56
+✓ 1234.56
+```
+
+完整格式参考：[字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping)
+
+---
+
+## 错误：缺少必填字段
+
+### 您将会看到什么
+
+该行将以黄色高亮，并标出缺失的必填字段单元格。
+
+### 含义
+
+此行存在必填字段为空。
+
+### 修复方法
+
+**选项 1：输入一个值**
+
+1. 点击空白单元格
+2. 输入值
+3. 继续导入
+
+**选项 2：移除该行**
+
+1. 如果没有该数据，点击 X 跳过该行
+
+### 如何避免此错误
+
+在导入之前，确定必填字段：
+
+1. 进入 **设置 → 数据模型**
+2. 选择你的对象
+3. 检查哪些字段被标记为必填
+
+---
+
+## 错误：未找到关系
+
+### 您将会看到什么
+
+该错误会在**导入开始之后**出现 — 导入将因如下消息而失败：
+
+```
+Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f
+```
+
+这意味着 Twenty 中没有具有该特定标识符的公司。
+
+<Note>与其他错误不同，此错误不会在数据审核步骤中被捕获。 导入会开始执行，但在遇到缺失的关联时失败。</Note>
+
+### 含义
+
+你正在尝试关联一条在 Twenty 中不存在的记录。
+
+### 修复方法
+
+**选项 1：先导入父级记录**
+
+1. 取消当前导入
+2. 导入父级记录（例如，公司）
+3. 然后导入子级记录（例如，人员）
+
+**选项 2：修正引用值**
+
+1. 检查文件中的引用值
+2. 确保其与现有记录完全匹配
+3. 核对格式：域名应为 `https://domain.com`
+
+**选项 3：移除该关联**
+
+1. 清空该单元格，以不带关联地进行导入
+2. 稍后手动添加该关联
+
+### 如何避免此错误
+
+1. **按正确顺序导入：**
+   * 先导入公司
+   * 其次导入人员（包含公司引用）
+   * 第三导入机会
+
+2. **核对引用值：**
+   * 导出父级记录以获取精确的标识符
+   * 使用域名格式 `https://domain.com`
+   * 检查拼写错误和大小写是否一致
+
+<Warning>
+**若引用了不存在的记录，导入将失败。**
+
+始终先导入父对象，再导入子对象。
+</Warning>
+
+了解更多详情：[导入关系](/l/zh/user-guide/data-migration/capabilities/import-relations)
+
+---
+
+## 错误：文件过大
+
+### 您将会看到什么
+
+在上传文件时会出现该错误 — 上传将被完全阻止：
+
+```
+Too many records. Up to 10000 allowed
+```
+
+在减小文件大小之前，你将无法进入数据审核步骤。
+
+### 含义
+
+你的文件包含超过 10,000 条记录。
+
+### 修复方法
+
+**选项 1：拆分为多个文件**
+
+1. 将数据分成每个不超过 10,000 条记录的文件
+2. 分别导入每个文件
+3. 保持导入顺序（先公司，后人员）
+
+**选项 2：使用 API 导入**
+对于非常大的数据集，请使用没有记录数量限制的 API。
+参见：[如何通过 API 导入数据](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)
+
+---
+
+## 错误：无法识别字段
+
+### 含义
+
+文件中的某一列无法映射，因为 Twenty 中不存在该字段。
+
+### 修复方法
+
+1. 进入 **设置 → 数据模型**
+2. 选择你要导入的对象
+3. 点击 **+ 添加字段**
+4. 创建具有适当类型的自定义字段
+5. 重新上传你的文件
+
+<Note>CSV 导入会创建记录，而不是字段。 在导入之前，所有字段都必须已存在。</Note>
+
+---
+
+## 错误：用户关联为空
+
+### 含义
+
+你正在尝试将记录分配给某个用户（所有者、被指派者），但该关联未被映射。
+
+### 常见原因
+
+1. **用户尚未接受邀请** — 该用户在 Twenty 中尚不存在
+2. **使用旧系统的用户 ID** — Twenty 无法匹配来自其他系统的 ID
+3. **电子邮件格式错误** — 该邮箱与用户的 Twenty 账户不匹配
+
+### 修复方法
+
+1. 确保所有用户都已接受邀请加入你的 Twenty 工作区
+2. 使用用户的电子邮箱地址（而不是姓名或旧系统的 ID）
+3. 使用他们用于加入 Twenty 的同一邮箱
+
+<Warning>
+**在导入之前，用户必须先接受邀请。**
+
+如果某个用户尚未接受邀请，引用该用户的记录将出现空的用户关联。
+</Warning>
+
+---
+
+## 导入前清单
+
+导入前检查以下项目以避免错误：
+
+### 文件要求
+
+<Check>文件为 CSV、XLSX 或 XLS 格式</Check>
+<Check>文件少于 10,000 条记录</Check>
+<Check>文件使用 UTF-8 编码</Check>
+
+### 数据质量
+
+<Check>无重复电子邮件（针对联系人）</Check>
+<Check>无重复域名（针对公司）</Check>
+<Check>所有日期采用一致的格式</Check>
+<Check>所有域名使用 `https://domain.com` 格式</Check>
+
+### 字段格式
+
+<Check>布尔字段使用 `TRUE` 或 `FALSE`（大写）</Check>
+<Check>选择字段使用 API 名称，而非显示标签</Check>
+<Check>电话字段包含所有必需的列</Check>
+<Check>货币字段同时包含金额和货币代码</Check>
+
+### 关系
+
+<Check>先导入父级记录，再导入子级记录</Check>
+<Check>关联列引用现有记录</Check>
+<Check>域名格式与 Twenty 的格式完全一致</Check>
+
+### 数据模型
+
+<Check>设置 → 数据模型 中已存在所有自定义字段</Check>
+<Check>在导入前先创建所有选择项</Check>
+
+---
+
+## 仍有问题？
+
+如果你已尝试以上解决方案：
+
+1. **下载示例文件** — 了解 Twenty 期望的确切格式
+2. **导出现有记录** — 将你的文件与可用数据进行对比
+3. **用小批量测试** — 先尝试 5-10 行
+4. **查看参考文章：**
+   * [字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping)
+   * [唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)
+   * [导入关系](/l/zh/user-guide/data-migration/capabilities/import-relations)
+   * [错误处理](/l/zh/user-guide/data-migration/capabilities/error-handling)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/import-companies-via-csv.mdx

@@ -0,0 +1,201 @@
+---
+title: 通过 CSV 导入公司
+description: 将公司导入 Twenty 的完整分步指南。
+---
+
+## 概览
+
+本指南将引导您将公司导入 Twenty。 **应先导入公司**，因为 People 和 Opportunities 会关联到公司。
+
+## 开始之前
+
+### 先决条件清单
+
+<Check>
+您的文件为 CSV、XLSX 或 XLS 格式
+</Check>
+
+<Check>
+文件包含少于 10,000 条记录
+</Check>
+
+<Check>
+您的文件中没有重复的域名
+</Check>
+
+<Check>
+所有自定义字段已存在于 **设置 → 数据模型**
+</Check>
+
+<Note>
+需要导入超过 10,000 家公司？ 拆分为多个文件，或使用 [API 导入](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)。
+</Note>
+
+## 步骤 1：准备您的公司数据
+
+### 必填与推荐字段
+
+| 字段         | 是否必填？ | 格式                   | 备注         |
+| ---------- | ----- | -------------------- | ---------- |
+| **Name**   | 推荐    | 文本                   | 公司显示名称     |
+| **Domain** | 推荐    | `https://domain.com` | 唯一标识符      |
+| **地址**     | 可选    | 多列                   | 详见下文       |
+| **员工**     | 可选    | 数字                   | 员工数量       |
+| **自定义字段**  | 可选    | 因情况而异                | 必须存在于数据模型中 |
+
+### 域名格式
+
+<Warning>
+**域名请使用 `https://domain.com` 格式。**
+
+这与通过电子邮件/日历同步自动创建公司时使用的格式一致，从而防止之后出现重复。
+</Warning>
+
+**域名列：**
+
+* **Domain / Domain Label**: `acme.com`
+* **Domain / Domain URL**: `https://acme.com`
+
+### 地址格式
+
+地址是一个嵌套字段，包含多个列：
+
+```
+Address / Address 1,Address / City,Address / State,Address / Country,Address / Post Code
+123 Main Street,San Francisco,CA,USA,94105
+```
+
+### 示例 CSV 结构
+
+```csv
+name,Domain / Domain URL,Domain / Domain Label,Address / City,Address / Country,employees
+Acme Corp,https://acme.com,acme.com,San Francisco,USA,250
+Widget Co,https://widgets.co,widgets.co,New York,USA,50
+```
+
+<Note>
+**专业提示：** 在导入过程中单击 **Download sample file**，以查看 Twenty 期望的确切列名。
+</Note>
+
+## 步骤 2：进入导入功能
+
+**选项 1：从 Companies 视图**
+
+1. 在左侧边栏中导航到 **Companies**
+2. 单击右上角的 **⋮** 图标
+3. 选择 **Import records**
+
+**选项 2：使用命令菜单**
+
+1. 按 `Cmd + K`（Mac）或 `Ctrl + K`（Windows）
+2. 输入 "import"
+3. 选择 **Import records**
+4. 选择 **Companies**
+
+## 步骤 3：上传您的文件
+
+1. 单击 **Select file**
+2. 选择您的 CSV、XLSX 或 XLS 文件
+3. 等待 Twenty 分析您的文件
+
+## 步骤 4：映射您的列
+
+Twenty 会自动尝试将您的列与字段匹配。 检查并调整：
+
+1. **检查自动映射** — 核实其是否正确
+2. **修正不正确的映射** — 单击下拉菜单选择正确的字段
+3. **跳过列** — 对不想导入的列选择 **Do not map**
+
+### 重要的映射规则
+
+* **Domain**：映射到 **Domain / Domain URL**（而非 Domain Label）
+* **地址**：将每个部分映射到其对应的列（City、State 等）
+* **选择型字段**：其值必须与现有选项匹配（否则您将在下一步进行映射）
+
+<img src="/images/user-guide/import-export-data/match-columns.png" style={{width:'100%'}} />
+
+## 步骤 5：映射选择字段的值
+
+如果您有选择或多选字段：
+
+1. Twenty 会将您的值与现有选项并列显示
+2. 将文件中的每个值与一个 Twenty 选项匹配
+3. 或在需要时创建新选项
+
+<Note>
+选择型选项使用 **API 名称**，而不是显示标签。 在 **Settings → Data Model** 中启用 **Advanced mode** 以查看 API 名称。
+</Note>
+
+## 步骤 6：检查并修复错误
+
+在完成导入之前，Twenty 会验证您的数据：
+
+1. 单击 **Next Steps**
+2. 有错误的行会被高亮为**黄色**
+3. **直接修复错误** — 单击单元格并编辑其值
+4. **移除有问题的行** — 单击 X 以跳过该行
+
+### 常见公司导入错误
+
+| 错误         | 原因              | 解决方案                    |
+| ---------- | --------------- | ----------------------- |
+| **域名重复**   | 域名已存在于 Twenty 中 | 从文件中删除或更新现有记录           |
+| **域名格式无效** | 格式错误            | 使用 `https://domain.com` |
+| **缺少必填字段** | 必填字段为空          | 填写该值或删除该行               |
+
+## 步骤 7：完成导入
+
+1. 查看导入摘要
+2. 单击 **Confirm** 以进行导入
+3. 等待导入完成
+4. 通过抽查几条记录进行验证
+
+## 导入公司之后
+
+现在您可以导入与公司关联的记录：
+
+1. **[导入 People](/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv)** — 使用域名将其关联到公司
+2. **导入机会** — 将其关联到公司
+3. **验证导入** — 抽查几条记录以确保数据正确
+
+## 更新现有公司
+
+若要更新公司而非创建新公司：
+
+1. 在文件中包含 `domain` 或 `id` 列
+2. Twenty 将根据此唯一标识符匹配记录
+3. 现有公司会被更新；新公司会被创建
+
+详情请参见 [如何更新现有记录](/l/zh/user-guide/data-migration/how-tos/update-existing-records-via-import)。
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="为什么两个公司不能使用相同的域名？">
+    在 Twenty 中，域名是唯一标识符。 这可防止重复公司，并确保电子邮件同步将邮件正确关联到对应的公司。
+  </Accordion>
+
+  <Accordion title="如果有公司没有域名怎么办？">
+    您可以将域名留空。 不过，我们建议在可能的情况下添加域名，以获得更好的数据质量和自动邮件关联功能。
+  </Accordion>
+
+  <Accordion title="我可以在未关联任何联系人的情况下导入公司吗？">
+    是! 您可以先导入公司，随后再导入联系人，并通过公司域名将其关联起来。
+  </Accordion>
+
+  <Accordion title="如果我导入了一个已存在的域名，会发生什么？">
+    如果您包含与现有公司匹配的唯一标识符（域名或 id），Twenty 会更新该公司，而不是创建重复项。
+  </Accordion>
+
+  <Accordion title="如何修复“重复域名”错误？">
+    您可以从文件中移除重复项，或包含公司的 `id` 以更新现有记录。
+  </Accordion>
+</AccordionGroup>
+
+## 故障排除
+
+遇到问题？ 请查看：
+
+* [如何修复导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)
+* [字段映射参考](/l/zh/user-guide/data-migration/capabilities/field-mapping)
+* [唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv.mdx

@@ -0,0 +1,242 @@
+---
+title: 通过 CSV 导入联系人
+description: 将人员/联系人导入 Twenty 的完整分步指南。
+---
+
+## 概览
+
+本指南将引导您将联系人（People）导入 Twenty。
+
+## 开始之前
+
+### 先决条件清单
+
+<Check>
+您的文件为 CSV、XLSX 或 XLS 格式
+</Check>
+
+<Check>
+文件包含少于 10,000 条记录
+</Check>
+
+<Check>
+您的文件中没有重复的电子邮件地址
+</Check>
+
+<Check>
+**先导入公司**（如果要将 People 关联到公司）
+</Check>
+
+<Check>
+所有自定义字段已存在于 **设置 → 数据模型**
+</Check>
+
+<Warning>
+**先导入公司，再导入 People**
+
+如果您想将 People 关联到公司，请先导入公司。 在引用之前，公司必须已存在。
+</Warning>
+
+## 步骤 1：准备您的联系人数据
+
+### 必填与推荐字段
+
+| 字段        | 是否必填？ | 格式                | 备注         |
+| --------- | ----- | ----------------- | ---------- |
+| **电子邮件**  | 推荐    | `name@domain.com` | 必须唯一       |
+| **名字**    | 推荐    | 文本                |            |
+| **姓氏**    | 推荐    | 文本                |            |
+| **公司**    | 可选    | 域名或 ID            | 链接到现有公司    |
+| **电话**    | 可选    | 多列                | 详见下文       |
+| **职位**    | 可选    | 文本                |            |
+| **自定义字段** | 可选    | 因情况而异             | 必须存在于数据模型中 |
+
+### 电子邮件格式
+
+* 必须为有效的电子邮件格式：`name@domain.com`
+* **必须唯一** — 您的文件或 Twenty 中不得重复
+* 对于附加电子邮件，请使用 **Emails / Additional Emails** 列：
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### 电话格式
+
+电话是一个 **嵌套字段**，需要多列：
+
+| 列                                       | 示例           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **Phones / Primary Phone Calling Code** | `+1`         |
+
+### 关联到公司
+
+添加包含公司唯一标识符的列：
+
+| 列名              | 格式     | 示例                                     |
+| --------------- | ------ | -------------------------------------- |
+| `companyDomain` | URL 格式 | `https://acme.com`                     |
+| `companyId`     | UUID   | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` |
+
+<Note>
+**使用域名 URL 格式**（`https://acme.com`），而不是标签。 这与公司在 Twenty 中的存储方式一致。
+</Note>
+
+### 示例 CSV 结构
+
+```csv
+firstName,lastName,email,jobTitle,companyDomain,Phones / Primary Phone Number,Phones / Primary Phone Country Code
+John,Smith,john@acme.com,CEO,https://acme.com,4159095555,US
+Jane,Doe,jane@widgets.co,CTO,https://widgets.co,2125551234,US
+```
+
+<Note>
+**专业提示：** 在导入过程中单击 **Download sample file**，或导出现有的一些 People，以查看 Twenty 期望的确切列名。
+</Note>
+
+## 步骤 2：进入导入功能
+
+**选项 1：从 People 视图**
+
+1. 在左侧边栏中导航到 **People**
+2. 单击右上角的 **⋮** 图标
+3. 选择 **Import records**
+
+**选项 2：使用命令菜单**
+
+1. 按 `Cmd + K`（Mac）或 `Ctrl + K`（Windows）
+2. 输入 "import"
+3. 选择 **Import records**
+4. 选择 **People**
+
+## 步骤 3：上传您的文件
+
+1. 单击 **Select file**
+2. 选择您的 CSV、XLSX 或 XLS 文件
+3. 等待 Twenty 分析您的文件
+
+## 步骤 4：映射您的列
+
+Twenty 会自动尝试将您的列与字段匹配。 检查并调整：
+
+1. **检查自动映射** — 核实其是否正确
+2. **修正不正确的映射** — 单击下拉菜单选择正确的字段
+3. **跳过列** — 对不想导入的列选择 **Do not map**
+
+### 重要的映射规则
+
+| 列类型    | 映射到                            | 备注                 |
+| ------ | ------------------------------ | ------------------ |
+| 公司引用   | **Company** 关系字段               | 仅使用域名或 ID，不要同时使用二者 |
+| 电子邮件   | **电子邮件**                       | 主要电子邮件地址           |
+| 附加电子邮件 | **Emails / Additional Emails** | 数组格式               |
+| 电话     | 分列                             | 号码、国家代码、拨号代码       |
+
+<img src="/images/user-guide/import-export-data/match-columns.png" style={{width:'100%'}} />
+
+### 映射公司关系
+
+当映射公司列时：
+
+1. 找到您的公司引用列（例如，`companyDomain`）
+2. 将其映射到 **Company** 关系字段
+3. Twenty 会将每个 Person 关联到匹配的 Company
+
+<Warning>
+**仅为关系映射一个唯一标识符。**
+
+不要同时映射 `companyId` 和 `companyDomain`。 选择其一——最好使用域名，因为它更易读。
+</Warning>
+
+## 步骤 5：映射选择字段的值
+
+如果您有选择或多选字段（如 Lead Source）：
+
+1. Twenty 会将您的值与现有选项并列显示
+2. 将文件中的每个值与一个 Twenty 选项匹配
+3. 或在需要时创建新选项
+
+<Note>
+选择型选项使用 **API 名称**，而不是显示标签。 在 **Settings → Data Model** 中启用 **Advanced mode** 以查看 API 名称。
+</Note>
+
+## 步骤 6：检查并修复错误
+
+在完成导入之前，Twenty 会验证您的数据：
+
+1. 单击 **Next Steps**
+2. 有错误的行会被高亮为**黄色**
+3. **直接修复错误** — 单击单元格并编辑其值
+4. **移除有问题的行** — 单击 X 以跳过该行
+
+### 常见联系人导入错误
+
+| 错误           | 原因                   | 解决方案                  |
+| ------------ | -------------------- | --------------------- |
+| **电子邮件重复**   | 电子邮件在 Twenty 或文件中已存在 | 删除重复项或更新现有记录          |
+| **电子邮件格式无效** | 电子邮件格式不正确            | 更正为 `name@domain.com` |
+| **未找到关系**    | 公司不存在                | 先导入公司，或修复引用           |
+| **缺少必填字段**   | 必填字段为空               | 填写该值或删除该行             |
+
+## 步骤 7：完成导入
+
+1. 查看导入摘要
+2. 单击 **确认** 以进行导入
+3. 等待导入完成
+4. 通过检查一些记录及其公司关联来验证
+
+## 导入联系人之后
+
+您的联系人现已在 Twenty 中！ 后续步骤：
+
+1. **验证公司关联** — 打开一些 People 记录，确认它们已关联到正确的公司
+2. **导入机会** — 如有需要，将其关联到 People 和 Companies
+3. **设置电子邮件同步** — 连接您的邮箱，以在联系人记录中查看电子邮件历史
+
+## 更新现有联系人
+
+若要更新联系人而非创建新联系人：
+
+1. 在文件中包含 `email` 或 `id` 列
+2. Twenty 将根据此唯一标识符匹配记录
+3. 现有联系人会被更新；新的联系人会被创建
+
+详情请参见 [如何更新现有记录](/l/zh/user-guide/data-migration/how-tos/update-existing-records-via-import)。
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="为什么两个 People 不能使用相同的电子邮件？">
+    在 Twenty 中，电子邮件是唯一标识符。 这可防止重复联系人，并确保电子邮件同步将邮件正确关联到对应的人。
+  </Accordion>
+
+  <Accordion title="如果有人员没有电子邮件怎么办？">
+    您可以将电子邮件留空。 不过，我们建议在可能的情况下添加电子邮件，以获得更好的数据质量和电子邮件同步功能。
+  </Accordion>
+
+  <Accordion title="在导入过程中如何将 People 关联到 Companies？">
+    添加包含公司域名（例如 `https://acme.com`）或 ID 的列。 在映射过程中，将此列连接到 Company 关系字段。
+  </Accordion>
+
+  <Accordion title="如果该 Company 还不存在怎么办？">
+    先导入 Companies，再导入 People。 在引用之前，该 Company 必须已存在。
+  </Accordion>
+
+  <Accordion title="我可以导入之前 CRM 中的 ID 吗？">
+    是! 在您的数据模型中创建一个标记为“唯一”的自定义字段，用于存储外部 ID。 注意：字段名 `id` 保留给 Twenty 的内部 ID。
+  </Accordion>
+
+  <Accordion title="如何修复“未找到关系”的错误？">
+    您引用的 Company 不存在。 先导入该 Company，或检查域名/ID 是否与现有 Company 完全匹配。
+  </Accordion>
+</AccordionGroup>
+
+## 故障排除
+
+遇到问题？ 请查看：
+
+* [如何修复导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)
+* [如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)
+* [字段映射参考](/l/zh/user-guide/data-migration/capabilities/field-mapping)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/import-data-via-api.mdx

@@ -0,0 +1,176 @@
+---
+title: 通过 API 导入数据
+description: 何时以及如何使用 Twenty 的 API 进行大规模数据导入。
+---
+
+## 概览
+
+Twenty 提供 **GraphQL** 和 **REST API**，用于以编程方式导入数据。 当 CSV 导入不适合您的数据量，或您需要自动化、定期的导入时，请使用 API。
+
+## 何时使用 API 导入
+
+| 场景                  | 推荐方法            |
+| ------------------- | --------------- |
+| 少于 10,000 条记录       | CSV 导入          |
+| 10,000 - 50,000 条记录 | CSV 导入（拆分为多个文件） |
+| **50,000+ 条记录**     | **API 导入**      |
+| 一次性迁移               | 两者皆可（取决于数据量）    |
+| **定期导入**            | **API 导入**      |
+| **实时同步**            | **API 导入**      |
+| **与其他系统集成**         | **API 导入**      |
+
+<Note>对于包含数十万条记录的数据集，API 比多次 CSV 导入显著更快且更可靠。</Note>
+
+## API 速率限制
+
+Twenty 实施速率限制以确保系统稳定性：
+
+| 限制             | 值             |
+| -------------- | ------------- |
+| **每分钟请求数**     | 100           |
+| **每次批量调用的记录数** | 60            |
+| **最大吞吐量**      | ~6,000 条记录/分钟 |
+
+<Warning>
+**围绕这些限制规划您的导入。**
+
+在最大吞吐量下，导入 100,000 条记录预计约需 17 分钟。 为错误处理和重试预留缓冲时间。
+</Warning>
+
+## 开始使用
+
+### 步骤 1：获取您的 API 密钥
+
+1. 前往 **设置 → 开发者**
+2. 点击 **+ 创建 API 密钥**
+3. 为您的密钥指定一个描述性名称
+4. 立即复制该 API 密钥（不会再次显示）
+5. 将其安全存储
+
+<Warning>
+**请保密您的 API 密钥。**
+
+任何获得您 API 密钥的人都可以访问并修改您的工作区数据。 切勿将其提交到代码仓库或公开分享。
+</Warning>
+
+### 步骤 2：选择您的 API
+
+Twenty 支持两种 API 类型：
+
+| 接口          | 最适合                     | 文档                               |
+| ----------- | ----------------------- | -------------------------------- |
+| **GraphQL** | 灵活查询、获取关联数据、复杂操作        | [API 文档](/l/zh/developers/extend/api) |
+| **REST**    | 简单的 CRUD 操作、熟悉的 REST 模式 | [API 文档](/l/zh/developers/extend/api) |
+
+两种 API 都支持：
+
+* 创建、读取、更新和删除记录
+* **批量操作** — 每次调用最多创建或更新 60 条记录
+
+**对于导入，请使用批量操作**，以在速率限制内最大化吞吐量。
+
+### 步骤 3：规划您的导入顺序
+
+与 CSV 导入一样，对于关联关系，**顺序很重要**：
+
+1. **公司** 优先（无依赖）
+2. **人员** 其次（可关联到公司）
+3. **商机** 第三（可关联到公司和人员）
+4. **任务/笔记**（可关联到以上任一项）
+5. **自定义对象**（按照其依赖关系）
+
+## 最佳实践
+
+### 批量处理请求
+
+* 不要逐条发送记录
+* 每次 API 调用最多分组处理 **60 条记录**
+* 这可在速率限制内最大化吞吐量
+
+### 处理速率限制
+
+* 在请求之间实施延迟（持续导入时至少 600ms）
+* 达到限制时使用指数退避
+* 监控 429（请求过多）响应
+
+### 先验证数据
+
+* 在导入前清洗并验证数据
+* 检查必填字段是否已填写
+* 验证格式是否符合 Twenty 的要求 (参见 [字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping))
+
+### 记录一切
+
+* 记录每一条导入的记录（包括 ID）
+* 记录错误及其完整上下文
+* 这有助于调试问题并验证完成情况
+
+### 先进行测试
+
+* 使用小批量进行测试（10-20 条记录）
+* 验证数据在 Twenty 中显示是否正确
+* 然后执行完整导入
+
+### 使用合并插入避免重复
+
+GraphQL API 支持**批量合并插入** — 若记录已存在则更新，不存在则创建。 这可以在重新运行导入时防止重复。
+
+## 查找对象和字段名称
+
+查看可用的对象和字段：
+
+1. 前往 **设置 → API 和 Webhooks**
+2. 浏览 **Metadata API**
+3. 查看所有标准和自定义对象及其字段
+
+文档展示了所有标准和自定义对象、它们的字段以及预期的数据类型。
+
+## 专业服务
+
+对于复杂的 API 迁移，我们的合作伙伴可以提供帮助：
+
+| 服务         | 包含内容       |
+| ---------- | ---------- |
+| **数据模型设计** | 设计最优的数据结构  |
+| **迁移脚本**   | 编写并运行导入脚本  |
+| **数据转换**   | 处理复杂的映射与清理 |
+| **验证与 QA** | 验证迁移是否完成   |
+
+**适用于：**
+
+* 迁移 100,000+ 条记录
+* 复杂的数据转换
+* 紧迫的时间安排
+* 缺乏开发人员资源的团队
+
+请通过 [contact@twenty.com](mailto:contact@twenty.com) 与我们联系，或查看我们的 [实施服务](/l/zh/user-guide/getting-started/capabilities/implementation-services)。
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="GraphQL 与 REST 有何区别？">
+    GraphQL 允许您在一次查询中准确请求所需数据，并且更适合复杂操作。 REST 使用标准的 HTTP 方法（GET、POST、PUT、DELETE），如果您使用过传统 API，可能会更熟悉。
+  </Accordion>
+
+  <Accordion title="我可以通过 API 更新现有记录吗？">
+    是! 使用 update mutation（GraphQL）或带有记录 `id` 的 PUT/PATCH 请求（REST）。
+  </Accordion>
+
+  <Accordion title="如何处理重复数据？">
+    首先使用唯一标识符（email、domain）查询现有记录。 存在则更新，不存在则创建。
+  </Accordion>
+
+  <Accordion title="我可以通过 API 删除记录吗？">
+    可以，使用 delete mutation（GraphQL）或 DELETE 请求（REST）。
+  </Accordion>
+
+  <Accordion title="是否提供 Python 或 Node.js 的 SDK？">
+    目前没有，但这两种 API 可与任何语言中的任意 HTTP 客户端配合使用。
+  </Accordion>
+</AccordionGroup>
+
+## API 文档
+
+有关完整的实现细节、代码示例和架构参考：
+
+* [API 文档](/l/zh/developers/extend/api)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv.mdx

@@ -0,0 +1,225 @@
+---
+title: 通过 CSV 导入对象之间的关系
+description: 在 CSV 导入过程中关联记录的完整分步指南。
+---
+
+## 概览
+
+本指南将引导您导入对象之间的关系——例如，将人员与公司关联，或将商机与人员关联。
+
+<Note>\*\*可导入内容：\*\*仅限指向单个对象类型的一对多关系。 指向多个对象类型的关系（例如，笔记同时关联到人员和公司）目前尚不支持导入。</Note>
+
+## 了解关系
+
+### 什么是“一对多”关系？
+
+在一对多关系中：
+
+* **一个**公司拥有**多个**人员（员工）
+* **一个**公司拥有**多个**商机
+* **一个**人拥有**多个**任务
+
+“一”侧为**父级**。 “多”侧为**子级**。
+
+### Twenty 中的常见关系
+
+| 关系      | “一”侧（父级） | “多”侧（子级） |
+| ------- | -------- | -------- |
+| 公司 → 人员 | 公司       | 人员       |
+| 公司 → 商机 | 公司       | 机会       |
+| 人员 → 任务 | 人员       | 任务       |
+| 人员 → 笔记 | 人员       | 备注       |
+
+## 步骤 1：确定“一”和“多”两侧
+
+在导入之前，确定哪个对象是父级，哪个是子级。
+
+**自问：**“是否一个[对象 A]拥有多个[对象 B]？”
+
+* 一个公司 → 多个人员 ✓（公司为父级）
+* 一个人 → 多个公司 ✗（这是错误的——一个人隶属于一个公司）
+
+## 步骤 2：先导入父级记录
+
+在引用之前，父级（“一”侧）必须已存在于 Twenty 中。
+
+**导入顺序：**
+
+1. **公司** 优先（无依赖关系）
+2. **人员** 其次（关联到公司）
+3. **商机** 第三（关联到公司和/或人员）
+4. **任务/笔记**（可关联到以上任一项）
+
+<Warning>
+**如果父级记录不存在，导入将失败。**
+
+在导入包含公司引用的人员之前，请务必确认公司已导入。
+</Warning>
+
+## 步骤 3：记录父级的唯一标识符
+
+您需要使用**唯一标识符**来引用父级记录。 可用选项：
+
+| 父级对象      | 可用的唯一标识符                          |
+| --------- | --------------------------------- |
+| **公司**    | `id`（UUID）、`domain`（推荐）或任何自定义唯一字段 |
+| **人员**    | `id`（UUID）、`email`，或任何自定义唯一字段     |
+| **工作区成员** | `id`（UUID）、`email`（而非姓名）          |
+| **自定义对象** | `id`（UUID），或任何标记为唯一的字段            |
+
+<Note>\*\*建议：\*\*公司使用 `domain`，人员使用 `email`。 这些字段可读性强，且在电子表格中易于核对。</Note>
+
+### 查找标识符
+
+如果您需要 `id`：
+
+1. 从 Twenty 导出父级记录
+2. 导出结果包含 `id` 列
+3. 在子级记录文件中使用这些 ID
+
+## 步骤 4：核实关系字段是否存在
+
+在导入之前，确保对象之间存在关系字段。
+
+**检查或创建的方法：**
+
+1. 进入 **设置 → 数据模型**
+2. 选择您的子级对象（例如，人员）
+3. 查找指向父级的关系字段（例如，公司）
+4. 如果不存在，请创建：
+   * 点击 **+ 添加字段**
+   * 选择 **关系** 类型
+   * 选择父级对象
+
+## 步骤 5：准备您的 CSV 文件
+
+在子级 CSV 中添加一列，使用父级的唯一标识符进行引用。
+
+### 示例：人员关联到公司
+
+**您的人员 CSV：**
+
+```csv
+firstName,lastName,email,jobTitle,companyDomain
+John,Smith,john@acme.com,CEO,https://acme.com
+Jane,Doe,jane@widgets.co,CTO,https://widgets.co
+Bob,Johnson,bob@techstart.io,Developer,https://techstart.io
+```
+
+`companyDomain` 列引用公司的域名。
+
+### 格式要求
+
+| 标识符  | 格式     | 示例                                     |
+| ---- | ------ | -------------------------------------- |
+| 域    | URL 格式 | `https://acme.com`                     |
+| 电子邮件 | 标准邮箱   | `john@acme.com`                        |
+| 编号   | UUID   | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` |
+
+<Warning>
+**域名格式很重要！**
+
+请使用 `https://domain.com`（而不是仅 `domain.com`）。 这与 Twenty 存储公司域名的方式一致，并可避免匹配错误。
+</Warning>
+
+### 重要规则
+
+1. **需要精确匹配** — 值必须与父级记录完全一致
+2. **仅映射一个唯一标识符** — 不要同时包含 `companyId` 和 `companyDomain`
+3. **区分大小写** — `Acme.com` ≠ `acme.com`
+
+## 步骤 6：上传并映射关系
+
+1. 前往子级对象（例如，人员）
+2. 点击 **⋮** → **导入记录**
+3. 上传您的 CSV 文件
+4. 在字段映射步骤中：
+   * 找到您的关系列（例如，`companyDomain`）
+   * 将其映射到 **Company** 关系字段
+5. 完成其余映射
+6. 检查错误并确认
+
+Twenty 将自动把每条子级记录关联到匹配的父级。
+
+## 步骤 7：验证导入结果
+
+导入后：
+
+1. 打开几条子级记录（例如，人员）
+2. 确认关系字段显示正确的父级（例如，公司）
+3. 打开一条父级记录并检查相关记录部分
+
+## 常见错误及避免方法
+
+| 错误         | 问题                                     | 解决方案                       |
+| ---------- | -------------------------------------- | -------------------------- |
+| **导入顺序错误** | 在公司之前导入人员                              | 始终先导入父级，再导入子级              |
+| **域名格式错误** | 使用 `acme.com` 而非 `https://acme.com`    | 使用带有 `https://` 的完整 URL 格式 |
+| **多个唯一字段** | 同时映射 `companyId` 和 `companyDomain`     | 仅映射一个唯一标识符                 |
+| **缺少关系字段** | 数据模型中不存在该关系字段                          | 请在导入前于 **设置 → 数据模型** 中创建   |
+| **记录不存在**  | 父级记录在 Twenty 中不存在                      | 先导入父级记录，或检查是否有拼写错误         |
+| **大小写不匹配** | 文件中为 `Acme.com`，但 Twenty 中为 `acme.com` | 确保大小写完全一致                  |
+
+## 关联到工作区成员
+
+当关联到工作区成员（您的团队）时：
+
+* 使用他们的**电子邮箱地址**，而不是姓名
+* 例如：`owner@yourcompany.com`，而不是 "John Smith"
+
+```csv
+taskName,assignedTo
+Follow up with client,john@yourcompany.com
+Review proposal,jane@yourcompany.com
+```
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="如果我的父级记录没有域名或邮箱怎么办？">
+    您有两个选项：
+    1. 使用 Twenty 的 `id`（导出父级记录以获取其 ID）
+    2. 在数据模型中创建自定义唯一字段，用于存储来自旧系统的外部 ID
+  </Accordion>
+
+  <Accordion title="我可以更新现有记录上的关系吗？">
+    是! 包含子级记录的唯一标识符（例如，人员的 `email`）以及新的关系值。 导入将更新该关系。
+  </Accordion>
+
+  <Accordion title="我可以导入多对多关系吗？">
+    目前尚不支持导入多对多关系。 计划于 2026 年上半年推出。
+  </Accordion>
+
+  <Accordion title="我可以关联到多个对象类型吗（例如，笔记同时关联到人员和公司）？">
+    指向多个对象类型的关系目前尚不支持导入/导出。 此功能已在我们的路线图中。
+  </Accordion>
+
+  <Accordion title="如果父级记录不存在会怎样？">
+    导入会为该行显示错误。 您可以：
+    * 先导入父级记录，然后重新导入
+    * 修正引用值
+    * 从导入中移除该行
+  </Accordion>
+
+  <Accordion title="为什么我的关系没有正确关联？">
+    常见原因：
+    * 格式错误（域名请使用 `https://domain.com`）
+    * 大小写不匹配（检查拼写是否完全一致）
+    * 父级不存在（请先导入父级）
+    * 映射了多个标识符（仅使用一个）
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+**请注意：软删除的记录也会计入唯一性。**
+
+如果您收到“not found”错误，但记录似乎存在，请检查命令菜单 → 查看已删除的记录。 父级可能已被软删除。
+</Warning>
+
+## 故障排除
+
+遇到问题？ 请查看：
+
+* [如何修复导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)
+* [导入关系功能](/l/zh/user-guide/data-migration/capabilities/import-relations)
+* [唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/migrating-from-other-crms.mdx

@@ -0,0 +1,289 @@
+---
+title: 从其他CRM迁移
+description: 分步指南：将您的数据从任何客户关系管理系统迁移到 Twenty。
+---
+
+## 概览
+
+本指南将引导您将数据从任何客户关系管理系统迁移到 Twenty。 该过程包括审核您的数据、准备您的 Twenty 工作区、从当前系统导出，并导入到 Twenty。
+
+<Note>视图、工作流和权限必须在迁移后手动重新创建。 为这些配置工作预留时间。</Note>
+
+## 步骤 1：审核您现有的数据
+
+迁移是一个重新开始的机会。 不要把冗余内容带过来。
+
+**应保留的内容：**
+
+* 活跃的联系人和公司
+* 进行中的机会和交易
+* 重要的备注和活动
+* 实际使用的自定义字段
+
+**应舍弃的内容：**
+
+* 过时的联系人（超过 2 年无任何活动）
+* 重复记录
+* 测试数据
+* 未使用的自定义字段
+
+## 步骤 2：映射您的数据模型
+
+在您当前的客户关系管理系统与 Twenty 之间创建一份映射文档：
+
+| 您的客户关系管理系统 | Twenty          |
+| ---------- | --------------- |
+| 账户 / 组织    | **公司**          |
+| 联系人 / 人员   | **人员**          |
+| 交易 / 机会    | **商业机会**        |
+| 活动         | **任务** 或 **注意** |
+| 自定义对象      | **自定义对象**       |
+
+**对于每个字段，文档：**
+
+* 源字段名称
+* 目标20领域
+* 任何需要的格式转换 (日期, 电话号码等)
+
+<Note>在导入过程中保持此映射文档的便捷性—您将在映射列时引用。</Note>
+
+## 第 3 步：设置您的20个工作区
+
+在导入数据之前，准备您的20个工作区：
+
+### 创建自定义对象和字段
+
+1. 转到**设置 -> 数据模型**
+2. 创建您需要的任何自定义对象
+3. 将自定义字段添加到标准和自定义对象
+4. 配置字段设置 (独特，需要选择选项等)
+
+<Warning>
+**字段必须在导入前存在。**
+
+CSV 导入创建记录，而不是字段。 在导入前在 设置 -> 数据模型中创建所有自定义字段。
+</Warning>
+
+### 邀请您的团队
+
+<Warning>
+**邀请用户BERE导入数据。**
+
+如果您的数据包含用户引用(帐户所有者、受让人等)，那么这些用户必须在20个时间内才能导入。 否则，就无法确定这些关系。
+</Warning>
+
+1. 转到 **设置 → 成员**
+2. 邀请所有团队成员
+3. **等待所有人接受**他们的邀请
+4. 验证所有用户出现在您的会员列表
+
+## 第 4 步：从您当前的 CRM 导出
+
+从您当前的 CRM 导出数据：
+
+1. 寻找一个 **导出** 函数 (通常在设置、 数据管理或管理下)
+2. 尽可能导出为 **CSV 格式**
+3. 单独导出每个对象类型 (公司、联系人、交易等)
+4. 包括你想要迁移的所有字段
+
+**导出这些对象(按此顺序作为参考)：**
+
+1. 公司/帐户 / 组织
+2. 联系人 / 人员
+3. 交易/机会
+4. 说明和活动
+5. 自定义对象
+
+## 第 5 步：清理和格式化您的数据
+
+在电子表格应用程序中打开每个导出的 CSV 并为20做准备。
+
+### 删除重复项
+
+1. 按唯一字段排序 (个人电子邮件，公司域)
+2. 删除或合并重复的行
+3. 验证不存在重复的 20 个已经存在
+
+### 正确格式字段
+
+| 字段类型        | 所需格式                       |
+| ----------- | -------------------------- |
+| **域**       | `https://domain.com`       |
+| **电子邮件**    | `name@domain.com` (必须是唯一的) |
+| **日期**      | `YYY-MM-DD`                |
+| **电话**      | 三列：数字，国家代码，呼叫代码            |
+| **Boolean** | `TRUE` 或 `FALSE` (大写)      |
+| **选择字段**    | 使用 API 名称，不显示标签            |
+
+<Warning>
+**域格式是关键。**
+
+使用 `https://domain.com` (不是 `domain.com` 或 `www.domain.com` )。 这匹配20个格式，并且在您连接电子邮件/日历同步时防止重复。
+</Warning>
+
+查看[如何准备您的 CSV 文件](/l/zh/user-guide/data-migration/how-tos/prepare-your-csv-files) 以获取所有字段类型的完整格式要求。
+
+### 添加关系列
+
+要连接记录(例如人与公司)，添加一列与母公司唯一标识符。
+
+**示例：有公司链接的人CSV**
+
+```csv
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+查看[如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) 获取链接记录的详细说明。
+
+### 更新用户引用
+
+如果您的数据包含用户指派(Owner，指派)：
+
+1. 在 **用户的电子邮件** 中添加一列(不仅仅是旧系统中的他们的 ID)
+2. 使用用户用来加入你的20个工作区的相同电子邮件地址
+
+参见 [如何准备 CSV 文件](/l/zh/user-guide/data-migration/how-tos/prepare-your-csv-files) 以获取完整的格式指南。
+
+## 步骤6：导入到 20
+
+<Warning>
+**导入订单事项！**
+
+总是按此顺序导入：
+1. **Companies** 优先(无依赖)
+2. **People** 秒(链接到公司)
+3. **Opportunities** 第三个(链接到公司/人民)
+4. **便笺和任务** (链接到记录)
+5. **自定义对象** 跟随他们的依赖关系
+
+在您可以引用之前必须存在父记录。
+</Warning>
+
+### 导入每个对象
+
+对于每个CSV文件，先后顺序：
+
+1. 在 20 中导航到对象
+2. 单击**视图-> 导入记录**
+3. 上传CSV文件
+4. 映射列到字段:
+   * 映射用户电子邮件列到适当的关系字段
+   * 映射关系列(例如`companyDomain`) 到关联字段
+5. 审核并修复界面中的任何错误
+6. 确认导入
+7. 在继续到下一个文件之前验证几个记录
+
+**详细指南：**
+
+* [如何导入公司](/l/zh/user-guide/data-migration/how-tos/import-companies-via-csv)
+* [如何导入联系人](/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv)
+* [如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)
+
+## 步骤7：大型迁移(50 000+个记录)
+
+对于大型迁移：
+
+| 音量               | 建议的办法      |
+| ---------------- | ---------- |
+| 不足1万份记录          | 单独导入 CSV   |
+| 10,000-50,000份记录 | 拆分成多个CSV文件 |
+| 50,000多条记录       | 使用 API     |
+
+**用于API导入：**
+
+* 更快、更可靠的大型数据集
+* 支持批量操作 (每次呼叫最多60个记录)
+* 查看[如何通过 API 导入数据](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)
+
+## 步骤8：迁移后设置
+
+导入数据后，完成您的工作区配置：
+
+### 重新创建视图
+
+* 使用过滤器、排序和列配置设置已保存的视图
+* 创建您需要的 kanban 或日历视图
+
+### 重新创建工作流
+
+* 在 **设置 -> Workflow** 中重建您的automatic
+* 以最关键的工作流开始
+* 在依赖之前测试每一个
+
+### 配置角色和权限
+
+* 在 **设置 → 成员 → 角色** 中设置角色
+* 分配用户到适当的角色
+
+### 连接电子邮件和日历
+
+* 每个用户在 **设置 -> 帐户** 中连接自己的帐户
+* 20个将开始同步电子邮件到联系记录
+* 查看[电子邮件和日历](/l/zh/user-guide/calendar-emails/overview)
+
+### 训练你的团队
+
+* 通过新接口一起移动
+* 记录任何特定团队的进程
+
+## 常见问题及解决方案
+
+| 问题         | 原因        | 解答                          |
+| ---------- | --------- | --------------------------- |
+| **复制错误**   | 电子邮件/域已存在 | 从文件中删除重复，或者包含唯一的标识符来更新现有记录  |
+| **找不到关系**  | 父记录不存在    | 首先导入父对象 (People之前的公司)       |
+| **缺少字段**   | 自定义字段不存在  | 在导入前在设置 -> 数据模型中创建字段        |
+| **选择字段错误** | 使用显示标签    | 使用 API 名称 (在设置中启用高级模式来查找他们) |
+| **用户关系为空** | 用户未接受邀请   | 确保所有用户在导入前接受邀请              |
+
+请参阅[如何修复导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)详细故障排除步骤。
+
+## 迁移后检查表
+
+### 数据的完整性
+
+<Check>所有记录均已导入（与源系统的数量进行比较）</Check>
+<Check>关联工作正常（人员已关联到公司）</Check>
+<Check>用户分配映射正确（Owner、Assignee）</Check>
+<Check>自定义字段已填充</Check>
+<Check>没有意外的重复项</Check>
+
+### 配置
+
+<Check>视图已重新创建</Check>
+<Check>工作流已重新创建并通过测试</Check>
+<Check>角色和权限已配置</Check>
+<Check>邮件/日历同步已连接</Check>
+
+### 团队准备情况
+
+<Check>团队在新系统</Check>
+<Check>老的 CRM 访问计划已决定 (保留以供参考吗？ 何时禁用？)</Check>
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="我可以自动迁移工作流吗？">
+    不是当前的。 工作流必须在 20 中手动重新创建。
+  </Accordion>
+
+  <Accordion title="文件附件是什么？">
+    文件附件不包含在 CSV 导出中。 您需要手动重新上传他们，通过API迁移，或联系我们的团队寻求帮助。
+  </Accordion>
+
+  <Accordion title="我能在迁移期间保持两个系统运行吗？">
+    是的，我们建议保持您旧的 CRM 运行，直到您验证迁移完成。 请注意不要在这两个地方建立新的数据。
+  </Accordion>
+
+  <Accordion title="移徙通常需要多长时间？">
+    取决于数据量和复杂性。 可在几个小时内进行小规模移徙（不到10 000项记录）。 大规模迁移可能需要几天时间，包括数据清理和测试。
+  </Accordion>
+</AccordionGroup>
+
+## 需要帮助？
+
+<Tip>
+  想在迁移过程中获得帮助吗？ [查找认证的20个合作伙伴](https://twenty.com/partners/list?categories=SOLUTIONING\&ref=docs-migrate-crm) 以移动您的数据、管道和用户端到结束。
+</Tip>

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/migrating-from-self-hosted-to-cloud.mdx

@@ -0,0 +1,173 @@
+---
+title: 从自托管迁移到云
+description: 分步指南：将您的 Twenty 自托管实例迁移到 Twenty Cloud。
+---
+
+## 概览
+
+本指南将引导您把数据从 Twenty 自托管实例迁移到 Twenty Cloud。 该过程包括设置您的云端工作区、导出数据并重新导入。
+
+<Note>视图、工作流和角色必须在迁移后手动重新创建。 为这些配置工作预留时间。</Note>
+
+## 步骤 1：创建您的云端工作区
+
+1. 访问 [app.twenty.com](https://app.twenty.com) 并创建一个新的工作区
+2. 完成初始设置向导
+3. 记录您的新工作区 URL
+
+## 步骤 2：重新创建您的数据模型
+
+在导入数据之前，重新创建您的自定义对象和字段：
+
+1. 在您的云端实例中进入 **设置 → 数据模型**
+2. 创建与自托管设置相匹配的自定义对象
+3. 向标准对象和自定义对象添加自定义字段
+4. 配置字段设置（唯一、必填等）
+
+<Note>为便于参考，请截取自托管数据模型的屏幕截图，或并排打开两个实例。</Note>
+
+## 步骤 3：邀请所有用户
+
+<Warning>
+**至关重要：在导入数据之前邀请用户。**
+
+在您导入任何引用到他们的记录（例如“账户所有者”字段）之前，用户必须先接受邀请。 如果用户尚不存在，则无法映射这些关系。
+</Warning>
+
+1. 在您的云端实例中进入 **设置 → 成员**
+2. 邀请所有在自托管环境中拥有账户的团队成员
+3. **等待所有人接受** 邀请
+4. 核实所有用户都出现在您的“成员”列表中
+
+## 步骤 4：从自托管导出数据
+
+从您的自托管实例中导出每个对象：
+
+1. 导航到每个对象（公司、人员、商机等）
+2. 将视图配置为显示您希望迁移的**所有列**
+3. 点击 **⋮** → **导出视图**
+4. 将每个 CSV 文件保存为清晰的名称（例如，`companies-export.csv`）
+
+**按以下顺序导出**（供导入时参考）：
+
+1. 公司
+2. 人员
+3. 机会
+4. 自定义对象（按其依赖关系顺序）
+5. 任务、笔记
+
+## 步骤 5：更新工作区成员引用
+
+导出的 CSV 包含来自您自托管实例的用户 ID。 这些 ID 与您的云端实例不匹配，因此需要将其替换为邮箱地址。
+
+**对于每个包含用户引用（所有者、被指派人等）的 CSV 文件：**
+
+1. 在电子表格应用中打开该 CSV
+2. 在每个用户 ID 列旁边添加一个新列（例如，在 `accountOwnerId` 旁添加 `accountOwnerEmail`）
+3. 填写每位用户的邮箱地址
+4. 您可以删除旧的 ID 列或保留它（导入时会被跳过）
+
+**示例:**
+
+之前:
+
+```csv
+name,domain,accountOwnerId
+Acme Corp,https://acme.com,old-uuid-123
+```
+
+之后:
+
+```csv
+name,domain,accountOwnerEmail
+Acme Corp,https://acme.com,john@yourcompany.com
+```
+
+<Note>请使用用户接受云端工作区邀请时所使用的相同邮箱地址。</Note>
+
+## 步骤 6：规划您的导入顺序
+
+按正确顺序导入文件以保持关系：
+
+1. **公司** 优先（无依赖关系）
+2. **人员** 其次（关联到公司）
+3. **商机** 第三（关联到公司和人员）
+4. **自定义对象**（按其依赖关系）
+5. **任务和笔记** 最后（关联到其他记录）
+
+有关维护关系的详细信息，请参见[如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)。
+
+## 步骤 7：导入到云端
+
+针对每个 CSV 文件，按顺序进行：
+
+1. 在云端实例中导航到该对象
+2. 点击 **⋮** → **导入记录**
+3. 上传 CSV 文件
+4. 将列映射到字段：
+   * 将用户邮箱列映射到相应的关系字段
+   * 按常规方式映射其他列
+5. 检查并修复任何错误
+6. 确认导入
+7. 在继续下一个文件之前，先核对几条记录
+
+## 步骤 8：重新创建配置
+
+导入数据后，请手动重新创建：
+
+### 视图
+
+* 根据筛选、排序和列配置重新创建已保存的视图
+* 设置任何看板或日历视图
+
+### 工作流
+
+* 在 **设置 → 工作流** 中重新创建自动化
+* 在依赖之前先测试每个工作流
+
+### 角色和权限
+
+* 在 **设置 → 成员 → 角色** 中设置角色
+* 将用户分配到合适的角色
+
+### 集成
+
+* 为每位用户重新连接邮件和日历同步
+* 使用新的 API 密钥重新配置任何 API 集成
+
+## 迁移后检查表
+
+<Check>所有数据均已成功导入</Check>
+<Check>对象之间的关系运行正常</Check>
+<Check>用户分配（所有者、被指派人）映射正确</Check>
+<Check>视图已重新创建</Check>
+<Check>工作流已重新创建并通过测试</Check>
+<Check>角色和权限已配置</Check>
+<Check>邮件/日历同步已重新连接</Check>
+<Check>API 集成已使用新密钥更新</Check>
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="我可以自动迁移工作流吗？">
+    目前不可以。 必须在您的云端实例中手动重新创建工作流。
+  </Accordion>
+
+  <Accordion title="文件附件和图片怎么办？">
+    CSV 导出不包含文件附件。 您需要手动重新上传任何附件、通过 API 迁移它们，或联系我方团队获取大规模迁移的协助。
+  </Accordion>
+
+  <Accordion title="迁移期间我可以同时运行两个实例吗？">
+    可以。我们建议在您确认云端迁移完成之前，保持自托管实例运行。 只要注意不要在两个环境中同时创建新数据即可。
+  </Accordion>
+
+  <Accordion title="如果某个用户尚未接受邀请怎么办？">
+    引用该用户的记录将导入失败，或其关系字段为空。 在导入数据之前，确保所有用户都已接受邀请。
+  </Accordion>
+</AccordionGroup>
+
+## 需要帮助？
+
+<Tip>
+  正在迁移大型或复杂的工作区？ [寻找经过认证的 Twenty 合作伙伴](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-migrate-cloud) 来端到端处理整个迁移。 *(或者联系我们的团队： [contact@twenty.com](mailto:contact@twenty.com)。)*
+</Tip>

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

@@ -0,0 +1,267 @@
+---
+title: 准备您的 CSV 文件
+description: 完整的分步指南，指导您将数据格式化以导入 Twenty。
+---
+
+## 概览
+
+本指南将引导您准备 CSV 文件，以成功完成导入。 请按照以下步骤操作以避免错误。
+
+## 步骤 1：检查文件要求
+
+开始之前，请确保您的文件满足以下要求：
+
+| 要求       | 详情                |
+| -------- | ----------------- |
+| **格式**   | CSV、XLSX 或 XLS    |
+| **大小限制** | 每个文件最多 10,000 条记录 |
+| **编码**   | 建议使用 UTF-8        |
+| **结构**   | 每个文件仅一种对象类型       |
+
+<Note>对于超过 10,000 条记录的数据集，请拆分为多个文件，或使用[API 导入](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)。</Note>
+
+## 步骤 2：下载示例文件
+
+**这是最重要的一步。** 示例文件展示了 Twenty 期望的准确列名和格式。
+
+1. 进入对象视图（人员、公司等）
+2. 点击 **⋮** → **导入记录**
+3. 点击 **下载示例文件**
+4. 将此文件用作模板
+
+<Note>**专业提示：** 改为导出少量现有记录。 这将为您提供数据应如何格式化的真实示例，并且在导入过程中列名会自动映射。</Note>
+
+## 步骤 3：移除重复值
+
+Twenty 会对某些字段强制唯一性。 重复项会导致导入错误。
+
+| 对象        | 唯一字段               |
+| --------- | ------------------ |
+| **人员**    | `id`, `email`      |
+| **公司**    | `id`, `domain`     |
+| **自定义对象** | `id`，以及任何您标记为唯一的字段 |
+
+**导入之前：**
+
+1. 按唯一字段（email 或 domain）对电子表格排序
+2. 删除或合并重复的行
+3. 检查 Twenty 中是否已存在重复项
+
+<Warning>**软删除的记录计入唯一性。** 位于“命令菜单 → 查看已删除的记录”中的记录会导致重复错误。 请永久删除这些记录，或将其恢复并更新。</Warning>
+
+## 步骤 4：正确格式化各字段类型
+
+不同的字段类型需要特定格式。 以下是完整参考：
+
+### 文本字段
+
+* 无需特殊格式
+* 首尾空格将自动去除
+
+### 电子邮件字段
+
+* 必须是有效的电子邮件格式：`name@domain.com`
+* 必须唯一（文件内及 Twenty 中不得重复）
+* 对于附加电子邮件，请在 **Emails / Additional Emails** 列中使用此格式：
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### 域名字段
+
+* **推荐格式**：`https://domain.com`
+* 这与邮箱/日历同步所使用的格式一致（可防止重复）
+* 填写这两列：
+  * **Domain / Domain Label**：`domain.com`
+  * **Domain / Domain URL**：`https://domain.com`
+* 在您的文件内以及在 Twenty 中必须唯一
+
+### 电话字段
+
+电话是一个**嵌套字段**，需要多列：
+
+| 列                                       | 示例           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **电话 / 主电话号码国际区号**                      | `+1`         |
+
+### 地址字段
+
+地址是一个**嵌套字段**，包含多个列（有些可以留空）：
+
+* **Address / Address 1**：街道地址第 1 行
+* **Address / Address 2**：街道地址第 2 行（可选）
+* **Address / City**：城市名称
+* **Address / State**：州或省
+* **Address / Country**：国家名称
+* **Address / Post Code**：邮政/ZIP 编码
+
+### 日期字段
+
+在整个文件中使用一致的格式：
+
+* `YYYY-MM-DD`（推荐）：`2024-03-15`
+* ISO 8601：`2024-03-15T10:30:00Z`
+
+### 数字字段
+
+* 仅数字（无文本）
+* 小数使用点号：`1234.56`
+* 不使用千位分隔符（不要写成 `1,234.56`）
+
+### 货币字段
+
+货币是一个**嵌套字段**，需要两列，且**两列都必须填写**：
+
+| 列                     | 示例        |
+| --------------------- | --------- |
+| **Amount / Amount**   | `1234.56` |
+| **Amount / Currency** | `USD`     |
+
+### 布尔字段
+
+使用大写：`TRUE` 或 `FALSE`
+
+<Warning>小写的 `true` 或 `false` 将无法使用。</Warning>
+
+### 选择字段
+
+使用选项的**API 名称**，而不是显示标签。
+
+**如何查找 API 名称：**
+
+1. 进入 **设置 → 数据模型**
+2. 选择对象和字段
+3. 启用**高级模式**（右下角切换）
+4. 复制该 API 名称（例如：`OPTION_1`，而不是 "Option 1"）
+
+<Note>新的选择项不会自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。</Note>
+
+### 多选字段
+
+以数组格式使用 API 名称：
+
+```
+["VALUE1","VALUE2"]
+```
+
+### 数组字段
+
+使用 JSON 数组格式：
+
+```
+["value1","value2"]
+```
+
+### 评分字段
+
+使用以下格式：`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4` 或 `RATING_5`
+
+### 链接/URL 字段
+
+填写两列：
+
+* **Links / Link Label**：`Twenty`
+* **Links / Link URL**：`https://twenty.com`
+
+对于次要链接，请使用 **Links / Secondary Links** 列：
+
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### JSON 字段
+
+使用有效的 JSON 格式：
+
+```
+{"key":"value","key2":"value2"}
+```
+
+### ID 字段
+
+* **可选**：如未提供，Twenty 将自动生成 ID
+* **格式**：UUID（例如：`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）
+* **使用场景**：包含 ID 以更新现有记录，而不是创建新记录
+
+## 步骤 5：添加关系列（如果要关联记录）
+
+要将记录关联到其他对象（例如，将人员关联到公司），请添加包含关联记录唯一标识符的列。
+
+**示例**：将人员关联到公司
+
+在您的人员 CSV 中添加一列：
+
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**关系的重要规则：**
+
+* 父记录必须已存在于 Twenty 中
+* 使用**域名 URL** 格式（`https://domain.com`），而不是标签
+* 仅映射一个唯一标识符（不要同时包含 `companyId` 和 `companyDomain`）
+* 对于工作区成员，请使用其**电子邮箱**（而不是姓名）
+
+<Warning>
+**导入顺序很重要！**
+
+先导入“1”端，再导入“多”端：
+1. **公司** 优先
+2. **人员** 其次（包含公司引用）
+3. **机会** 第三
+
+在引用之前，父记录必须已存在。
+</Warning>
+
+详细说明请参见[如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)。
+
+## 步骤 6：确保 Twenty 中存在这些字段
+
+导入会创建**记录**，而非**字段**。 要导入的所有字段必须已在您的数据模型中存在。
+
+**导入前：**
+
+1. 进入 **设置 → 数据模型**
+2. 选择您的对象
+3. 创建所需的任何自定义字段
+4. 记录准确的字段名称（必须与列标题匹配）
+
+## 步骤 7：最终检查清单
+
+在上传文件之前，请确认：
+
+<Check>文件为 CSV、XLSX 或 XLS 格式</Check>
+<Check>文件少于 10,000 条记录</Check>
+<Check>编码为 UTF-8</Check>
+<Check>没有重复的电子邮箱（针对人员）或域名（针对公司）</Check>
+<Check>日期在全篇使用一致的格式</Check>
+<Check>域名使用 `https://domain.com` 格式</Check>
+<Check>布尔字段使用 `TRUE` 或 `FALSE`（大写）</Check>
+<Check>选择字段使用 API 名称，而非显示标签</Check>
+<Check>所有自定义字段已存在于 设置 → 数据模型 中</Check>
+<Check>父记录先于子记录导入</Check>
+<Check>关系列引用现有记录</Check>
+
+## 常见错误及避免方法
+
+| 错误                  | 解决方案                         |
+| ------------------- | ---------------------------- |
+| 使用 `true` 而非 `TRUE` | 布尔值必须为大写                     |
+| 在选择字段中使用显示标签        | 在“设置”中查找并使用 API 名称           |
+| 在公司之前导入人员           | 始终先导入父对象                     |
+| 货币字段缺少货币代码          | 填写金额和货币两列                    |
+| 域名格式错误              | 始终使用 `https://domain.com` 格式 |
+| 为关系映射了多个唯一字段        | 仅映射一个（域名或 ID，不要同时映射）         |
+
+## 下一步
+
+您的文件已准备就绪！ 现在：
+
+* [导入公司](/l/zh/user-guide/data-migration/how-tos/import-companies-via-csv)（先导入这些）
+* [导入联系人](/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv)
+* [修复任何导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)

packages/twenty-docs/l/zh/user-guide/data-migration/how-tos/update-existing-records-via-import.mdx

@@ -0,0 +1,198 @@
+---
+title: 通过导入更新现有记录
+description: 使用 CSV 导入批量更新记录的完整分步指南。
+---
+
+## 概览
+
+需要一次更新许多记录吗？ 与其逐个编辑，不如使用 CSV 导入批量更新现有记录。
+
+**使用场景：**
+
+* 为多人更新职位名称
+* 批量更改公司信息
+* 向新的自定义字段添加数据
+* 更正多条记录中的数据错误
+
+## 工作原理
+
+当您导入的文件包含与现有记录匹配的**唯一标识符**时，Twenty 会更新该记录，而不是创建重复项。
+
+| 如果唯一标识符... | Twenty 将...          |
+| ---------- | -------------------- |
+| 与现有记录匹配    | **更新**现有记录           |
+| 与任何记录都不匹配  | **创建**新记录            |
+| 您的文件中缺少    | **创建**新记录（带自动生成的 ID） |
+
+<Warning>
+**多选字段会被覆盖，而不是合并。**
+
+如果一条记录已选择了 `Option A` 和 `Option B`，而您导入了 `["Option C"]`，则导入后该记录将只保留 `Option C`。 导入会替换之前的所有选择——不会在其基础上追加。
+
+若要保留现有值，请在导入中包含它们全部：`["Option A","Option B","Option C"]`
+</Warning>
+
+## 步骤 1：导出现有数据
+
+首先，导出您要更新的记录：
+
+1. 导航到对象（人员、公司等）
+2. **添加所需列** — 点击 **Options → Fields** 以显示您要更新的字段
+3. **如有需要，进行筛选** — 将范围缩小到仅包含您要更新的记录
+4. 点击 **⋮** → **导出视图**
+5. 保存 CSV 文件
+
+<Note>**为什么先导出？** 导出的文件具有正确的格式，包含唯一标识符，并且在导入时可自动映射。</Note>
+
+### 导出内容
+
+* 当前视图中所有可见列
+* 记录的唯一标识符（`id`、`email`、`domain`）
+* 可供您修改的当前字段值
+
+## 步骤 2：编辑 CSV 文件
+
+在电子表格应用（Excel、Google 表格等）中打开导出的文件：
+
+1. **保留唯一标识符列** — 不要删除 `id`、`email` 或 `domain`
+2. 在您要更改的列中**更新这些值**
+3. **移除不需要更新的列**（可选，但更简洁）
+4. **不要更改唯一标识符的值** — 否则 Twenty 将创建新记录
+
+### 示例：更新职位名称
+
+**导出的文件：**
+
+```csv
+id,email,firstName,lastName,jobTitle
+550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Sales Rep
+550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Sales Rep
+550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Sales Rep
+```
+
+**进行编辑后：**
+
+```csv
+id,email,firstName,lastName,jobTitle
+550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Account Executive
+550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Senior Account Executive
+550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Account Executive
+```
+
+<Warning>
+**不要更改唯一标识符的值。**
+
+如果您将 `john@acme.com` 更改为 `john.smith@acme.com`，Twenty 将创建新记录，而不是更新现有记录。
+</Warning>
+
+## 步骤 3：导入已更新的文件
+
+1. 导航到对象
+2. 点击 **⋮** → **导入记录**
+3. 上传您已编辑的 CSV 文件
+4. **确保唯一标识符已映射** — 确认 `email`、`domain` 或 `id` 映射正确
+5. 检查字段映射
+6. 检查是否存在错误
+7. 点击 **确认**
+
+Twenty 根据唯一标识符匹配记录，并使用新值进行更新。
+
+## 选择合适的唯一标识符
+
+| 对象        | 推荐     | 备选   | 备注          |
+| --------- | ------ | ---- | ----------- |
+| **人员**    | `电子邮件` | `id` | 电子邮件便于阅读    |
+| **公司**    | `域`    | `id` | 域名便于阅读      |
+| **自定义对象** | 任何唯一字段 | `id` | 使用您的自定义唯一字段 |
+
+<Note>**仅使用一个唯一标识符。** 不要同时映射 `email` 和 `id`。 这可能会引起混淆和错误。</Note>
+
+### 使用自定义唯一字段
+
+如果您有标记为唯一的自定义字段（例如来自其他系统的外部 ID）：
+
+1. 在导出和导入中包含该字段
+2. 在导入过程中进行映射
+3. Twenty 将基于该字段进行匹配
+
+## 步骤 4：验证更新结果
+
+导入后：
+
+1. 打开几条已更新的记录
+2. 确认更改已生效
+3. 检查是否未创建重复记录
+
+## 文件中未包含的字段会怎样？
+
+**未包含在导入文件中的字段将保持不变。**
+
+| 您的文件包含...                  | 结果                         |
+| -------------------------- | -------------------------- |
+| `email`，`jobTitle`         | 只有 `jobTitle` 被更新；其他字段保持不变 |
+| `email`，`jobTitle`，`phone` | `jobTitle` 和 `phone` 被更新   |
+
+这意味着您只需包含想要更改的字段（以及唯一标识符）。
+
+## 同时进行更新与创建新记录
+
+您可以在同一次导入中更新现有记录并创建新记录：
+
+```csv
+email,firstName,lastName,jobTitle
+john@acme.com,John,Smith,Senior Manager    ← Updates existing (email matches)
+newperson@acme.com,New,Person,Analyst      ← Creates new (email doesn't match)
+```
+
+## 常见错误及避免方法
+
+| 错误          | 问题                                               | 结果         | 解决方案                         |
+| ----------- | ------------------------------------------------ | ---------- | ---------------------------- |
+| **更改唯一标识符** | 将 `john@acme.com` 更改为 `john.smith@acme.com`      | 创建新记录而不是更新 | 保持唯一标识符不变                    |
+| **多个唯一字段**  | 同时映射 `email` 和 `id`                              | 可能出现匹配冲突   | 仅映射一个唯一标识符                   |
+| **没有唯一标识符** | 文件仅包含 `firstName`、`lastName`、`jobTitle`          | 所有行都会创建新记录 | 务必包含 `email`、`domain` 或 `id` |
+| **大小写不匹配**  | 文件中为 `John@acme.com`，但 Twenty 中为 `john@acme.com` | 创建新记录      | 从 Twenty 导出以获取精确值            |
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="如果某些记录尚不存在怎么办？">
+    具有唯一标识符但与现有记录不匹配的记录将被创建为新记录。 这样您就可以在同一次导入中同时进行更新和创建。
+  </Accordion>
+
+  <Accordion title="我可以清除/清空字段值吗？">
+    可以，在 CSV 中将该单元格留空即可。 导入会清除现有记录中该字段的值。
+  </Accordion>
+
+  <Accordion title="我未包含在导入中的字段会怎样？">
+    未包含在导入文件中的字段在现有记录上将保持不变。 只有您包含的字段会被更新。
+  </Accordion>
+
+  <Accordion title="我可以更新关联字段（例如公司）吗？">
+    是! 包含该关联对象的唯一标识符（例如 `companyDomain`），并将其映射到该关联字段。 该关联将被更新。
+  </Accordion>
+
+  <Accordion title="我如何知道哪些记录会被更新、哪些会被创建？">
+    在导入审核步骤中，Twenty 会根据唯一标识符的匹配情况，显示将被更新与被创建的记录数量。
+  </Accordion>
+
+  <Accordion title="我可以撤销一次批量更新吗？">
+    无法自动撤销。 我们建议在进行批量更新之前导出数据作为备份。
+  </Accordion>
+</AccordionGroup>
+
+## 最佳实践
+
+1. **先导出** — 始终从导出开始，以确保格式正确
+2. **更新前先备份** — 在进行批量更改之前导出您的数据
+3. **先用少量记录进行测试** — 在进行大规模批量处理前，先尝试更新 5-10 条记录
+4. **使用便于阅读的标识符** — `email` 和 `domain` 比 `id` 更容易核对
+5. **只包含必要的列** — 列越少，出错的可能性越低
+
+## 故障排除
+
+遇到问题？ 请查看：
+
+* [如何修复导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)
+* [唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)
+* [字段映射参考](/l/zh/user-guide/data-migration/capabilities/field-mapping)

packages/twenty-docs/l/zh/user-guide/data-migration/overview.mdx

@@ -0,0 +1,83 @@
+---
+title: 数据迁移
+description: 通过 CSV 文件或 API 导入和导出您的 CRM 数据。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 导入方法
+
+Twenty 支持两种主要的数据导入方法：
+
+| 方法         | 最佳适用      | 数量上限            |
+| ---------- | --------- | --------------- |
+| **CSV 导入** | 标准迁移，定期更新 | 每个文件 10,000 条记录 |
+| **API 导入** | 大规模迁移，自动化 | 无限制             |
+
+<Note>对于非常大的数据集（数十万条记录），请使用 API。 我们的[实施合作伙伴](/l/zh/user-guide/getting-started/capabilities/implementation-services)如有需要，可帮助运行这些脚本。</Note>
+
+## CSV 导入基础知识
+
+您可以使用 CSV、XLSX 或 XLS 文件导入任何对象的数据。 每个文件应**仅包含一种对象类型**（例如，仅包含“人员”记录）。
+
+<Note>**字段必须在导入前已存在。** 上传 CSV 会创建记录，但不会创建字段。 如果您需要自定义字段，请先在**设置 → 数据模型**中创建它们。</Note>
+
+### 步骤
+
+1. 导航到您要导入数据的对象
+2. 点击右上角的 **⋮** 图标（命令菜单），然后点击 **导入记录**
+3. 下载模板文件以确保您的数据符合预期格式
+4. 上传已按格式整理的 CSV 文件
+5. 将您的列映射到 Twenty 字段
+6. 检查错误（以黄色高亮），并在 UI 中直接编辑进行修复
+7. 确认导入
+
+### 导入对象之间的关系
+
+您可以使用 CSV 导入功能来导入对象之间的关系。 您需要使用此对象中的唯一字段来引用相关对象：`id`；对于人员和工作区成员，使用 `email`；对于公司，使用 `domain`；对于其他对象，则使用数据模型中设置为唯一的任何字段。
+
+<Note>**已删除的记录也计入唯一性。** 软删除的记录（在“命令菜单 → 查看已删除记录”下可见）会包含在唯一性检查中。 如果您导入的记录与某个已删除记录具有相同的唯一值，该已删除记录将被还原。</Note>
+
+<Warning>
+**导入顺序很重要！**
+
+在导入相关对象时，请按以下顺序上传文件：
+1. 首先导入**公司**（关系中的“一”端）
+2. **人员** 第二（通过 companyId 关联到公司）
+3. **商机** 第三（关联到公司/人员）
+4. 最后导入有关系的**自定义对象**
+
+为什么？ 在一对多关系中，“一”端必须先存在，才能被引用。 例如，在导入带有该公司 ID 的人员之前，必须先存在该公司的记录。
+</Warning>
+
+有关操作的分步指南，请参阅[这篇文章](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)。
+
+## 导出数据
+
+导出您的工作区数据，用于备份、报告或迁移。
+
+### 步骤
+
+1. 导航到您要导出的对象
+2. 在视图中配置所需的列
+3. 点击 **⋮** → **导出视图**
+4. 保存该 CSV 文件
+
+<Note>**仅导出可见列。** CSV 文件只包含当前视图中显示的列。 导出前添加或隐藏列以控制包含的数据。</Note>
+
+<Note>**导出限制**：每次导出最多 20,000 条记录。</Note>
+
+## 权限
+
+数据导入和导出需要特定权限：
+
+* **导入**：需要“导入 CSV”权限
+* **导出**：需要“导出 CSV”权限
+
+如果您没有这些权限，请联系您的工作区管理员。
+
+## 下一步
+
+* [准备您的 CSV 文件](/l/zh/user-guide/data-migration/how-tos/prepare-your-csv-files)
+* [通过 CSV 导入对象之间的关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)
+* [通过 API 导入大型数据集](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)