导入数据 - 帆倍 - 帮助文档

1. 功能简介

1.1 功能定位

数据导入主要服务于数据迁移和批量初始化。

管理员可以将外部 CRM、Excel 台账或旧系统中的客户、联系人、商机、记录等数据，按照帆倍表单字段定义批量导入。

数据导入采用仅新增模式：

导入仅创建新记录，不会更新已有记录。
同一批数据中，通过校验的行可以正常新增；失败行不会阻断其他有效行。
失败行可以下载错误报告，修正后作为新文件重新导入。

1.2 使用前提

企业创建者、系统管理员，或帆倍普通管理员可使用「导入数据」功能，其他普通成员看不到相关入口
仅支持在PC端操作，移动端不支持导入
导入前，管理员应当已完成「表单字段」配置，比如新增字段或调整已有选项类字段的名称
建议先使用 10～50 行样例数据验证配置，确认无误后再进行大批量导入。

1.3 操作入口

1）管理员登录帆倍，选中具体表单，单击右上角「导入」按钮，即可进行导入操作。

1.4 文件与任务限制

项目	限制
文件格式	.xlsx、.xls
文件大小	不超过 2 MB
数据行数	不超过 20,000 个非空数据行
数据列数	不超过 100 列
工作表	一个工作簿可以包含多个工作表，但一次导入任务只处理其中一个工作表

2. 操作步骤

2.1 完整操作流程

第一步：准备数据

先进入【应用后台-表单设置】完成目标表单和字段建设，比如新增字段或调整已有选项类字段的名称
建议下载当前对象的标准模板，再按照模板整理数据。
建议先使用 10～50 行样例数据验证配置，确认无误后再进行大批量导入。

第二步：上传文件

进入目标对象列表，单击右上角的导入。
将文件拖入上传区域，或单击点击添加选择文件。
系统检查文件格式、大小、工作表、行列数和单元格内容。
如果工作簿中包含多个工作表，在字段映射页面选择本次需要导入的工作表。
空白数据行会被跳过，不计入实际导入记录。

第三步：配置字段映射关系

在字段映射页面，将 Excel 列与 FineSales 表单字段一一对应。

系统只会在 Excel 表头与字段名称或字段 key 完全一致时自动建议映射，不进行模糊匹配。
每个 Excel 列最多映射一个目标字段，每个目标字段也只能被映射一次。
不需要导入的列选择不导入。
所有必填字段必须完成映射。
完成映射不代表每一行都有值，开始导入后仍会逐行检查必填内容。

第四步：开始导入

单击开始导入。系统会准备数据、逐行校验并写入记录，同时显示任务进度。

任务结束后可能出现以下结果：

全部成功：所有有效数据均已新增。
部分成功：有效行已新增，失败行进入错误报告。
全部数据行失败：文件可以读取，但所有数据行均未通过校验。
技术性失败：导入服务、任务状态、文件生命周期或写入环节发生异常。

第五步：重新处理失败行

下载错误报告。报告只包含失败行，第一列为错误原因，其余列保留原始数据。
根据错误原因逐行修改数据，修改后重新上传、导入。

2.2 数据校验

校验阶段	主要校验内容	不通过时的结果
文件与工作表	文件真实格式、大小、行列数、工作表、单元格长度以及公式计算结果	文件无法进入映射页，或任务整体失败
表头与映射	表头存在；映射列和目标字段不能重复；所有必填字段完成映射	“开始导入”不可用，或提示字段映射无效
必填字段	每条数据的必填字段均有有效值	对应行进入错误报告
字段类型与约束	文本长度/正则、数字范围与小数位、布尔值、日期时间格式等	对应行提示字段值格式无效
选项字段	导入值与选项 code 或显示名称完全一致，且只能匹配一个选项	对应行提示选项不存在或选项不唯一
成员与部门	按成员姓名/用户名、部门名称/编号精确查找，结果必须唯一	对应行提示不存在或重名
关联记录	按关联对象的展示字段精确匹配，并受当前对象和数据权限约束	对应行提示关联记录不存在或不唯一

常用字段的输入规范

文本：导入前会去除首尾空格，并按照表单配置检查长度、格式或正则约束。
数字：只填写数字，可包含正负号和小数点；不要附带千分位、货币符号、单位或百分号。
布尔值：支持 true / false、是 / 否、1 / 0。
日期：支持 YYYY-MM-DD、YYYY/MM/DD、YYYY.MM.DD、YYYY年M月D日等常见形式。
日期时间：除了日期，还必须包含具体时间。
选项：填写选项 code 或界面显示名称，必须完全一致，不支持模糊匹配。
多值字段：多个文本、成员、部门或关联值使用英文逗号 , 分隔。
成员：姓名唯一时可以直接填写姓名；存在重名时，建议使用姓名#用户名#，例如张三#zhangsan#。
部门：部门名称唯一时可以直接填写名称；存在重名时，建议使用部门名称#部门编号#，例如华东销售部#10023#。部门编号必须是系统中的有效整数编号。
关联记录：填写关联对象展示字段的值，通常为名称；该值需要能够唯一匹配一条当前用户有权访问的记录。

2.3 失败情况说明与处理

失败情况	常见原因	处理方式
字段选项不匹配	Excel 值不在当前表单选项中，或者名称与 code 均不完全一致	将值修改为已有选项名称/code；如果业务确实需要该值，先在表单设置中新增选项，再重新导入
选项值不唯一	多个选项使用了相同的显示名称	优先填写唯一的选项 code，或在表单设置中清理重复选项名称
成员重名	只填写姓名时匹配到多个成员	改用姓名#用户名# 精确定位，例如李雷#lilei#
部门重名	只填写部门名称时匹配到多个同名部门	改用部门名称#部门编号#，并确认编号为系统中的有效部门编号
成员或部门不存在	姓名、用户名、部门名称或编号在当前组织中找不到	核对拼写和组织架构；必要时先在组织管理中补齐成员或部门
关联记录不存在	被引用的主数据尚未导入，或当前用户无权访问	先导入被引用的数据，再处理依赖对象；通常先客户，再联系人/商机，最后导入记录等依赖对象
关联记录重名	展示字段匹配到多条记录	先清理重名数据，保证关联对象的展示字段能够唯一匹配，再重试失败行
缺少必填字段	必填字段未映射，或者某些数据行为空/转换失败	补齐字段映射和对应行数据；注意“已映射”不等于“每行都有值”
字段格式无效	数字带单位、日期格式不合法、布尔值无法识别、文本超长或违反字段约束	按字段规范和表单设置修正；公式列建议粘贴为值
外部 ID 或其他唯一值重复	文件内重复，或与 FineSales 已有记录冲突	先去重并核对已有数据；仅新增导入不会根据相同外部 ID 更新原记录
技术性失败	导入服务、任务状态、文件有效期或写入环节异常	重新上传文件并导入；多次失败时记录页面上的追踪 ID，交由系统管理员或技术支持排查

3. 注意事项

3.1 建议先在表单设置中重构表单

导入模板、可导入字段和校验规则都来自当前表单配置。建议先在表单设置中完成表单重构，再准备 Excel：

先确定字段类型，不要临时将日期、数值、选项或关联关系全部作为文本导入。
提前定义并清理字段选项，避免同义词、错别字和重复显示名称。
确定必填字段和唯一字段。
确认人员、部门及关联对象的数据已经准备完成。
如果导入过程中修改了字段、必填状态或选项，返回字段映射页面重新确认，必要时重新上传文件。

3.2 仅支持导入新增

数据导入不会根据名称、手机号、外部 ID 或其他字段查找并更新已有记录，也不能作为批量覆盖或数据同步工具。

出现唯一字段冲突时，应先清理待导入数据或确认系统已有记录，而不是重复导入。

3.3 外部 ID

FineSales 的预置业务表单通常包含 external_id 字段，如客户表中的外部客户 ID。

如果外部系统导出的数据带有稳定、唯一且不会复用的 ID，建议一并导入 external_id。
external_id 是唯一字段，文件内重复值会被校验；系统中已有相同值时也不能再次新增。
外部 ID 只用于唯一标识、数据对账和后续系统集成；相同外部 ID 不会触发更新。
不要把 FineSales 内部 _id、自动编号或临时行号当作外部 ID。
该字段在普通表单中可能被隐藏且不可编辑，但数据导入会将其作为特殊字段开放映射。

3.4 可导入字段范围

字段映射列表只展示当前表单中可写且类型受支持的字段。以下内容通常不会出现在映射列表中：

内部 _id、创建人、创建时间、更新人、更新时间等系统维护字段。
自动编号、AI 生成字段、敏感字段和已废弃字段。
隐藏且不可编辑的普通业务字段；external_id 是特殊例外。
当前导入功能尚不支持的字段类型。

3.5 导入执行与后续影响

导入任务使用发起导入时管理员的身份和权限执行。
创建人和创建时间由系统维护，不能通过 Excel 指定。
当前批量导入不会触发 webhook，也不会自动刷新 AI 字段；依赖这些能力时需要另行确认或手动触发后续流程。
错误报告和下载链接具有有效期，任务完成后应及时下载和归档。
导入前保留原始文件备份，不要直接覆盖唯一一份源数据。

3.6 导入前检查清单

已在表单设置中完成字段、选项配置。
文件为真实的 .xlsx 或 .xls，大小不超过 2 MB。
数据不超过 20,000 个非空行和 100 列。
第一行就是表头，或至少保证首个非空表头位于前 100 行内。
所有必填字段都有对应列，并且每条数据都有有效值。
选项值与表单完全一致，成员、部门和关联记录能够唯一匹配。
外部 ID 已去重，并确认不会与 FineSales 中已有记录冲突。
公式列已在 Excel 中保存计算结果，关键列最好粘贴为值。
已先用小批量样例验证，并保留原始数据备份。