搬家不丢数据：vibe 项目的用户数据导入与迁移实战

为什么导入做不好，用户第一天就走

一个用户愿意从旧工具搬到你的产品，说明他已经动了心；但如果搬家的过程让他丢数据、错字段、反复手工补录，他会在第一天就得出一个结论：这个产品不值得信任。数据导入不是一个边缘功能，它是用户对产品信任的第一次大考。很多 vibe 项目把导入做成“上传一个文件，成功了就好”，结果用户上传后发现分类全乱了、日期全错了、重复了几百条，却没有任何地方告诉他错在哪里、该怎么修。用户不会再给第二次机会，他会默默回到旧工具。

更深一层的原因是：导入面对的数据从来不是干净的。用户的旧数据里有空行、有合并单元格、有同一个人写的三种不同名字、有两种日期格式混在一起、有中途改过的分类名。导入功能如果假设数据是干净的，等于把清洗工作全部推给用户。而用户之所以要换工具，恰恰是不想再做这些手工活。所以导入设计的真正目标是：让用户上传一份不完美的文件，也能得到一份可核对、可修复、可回滚的结果。

先划清边界：本篇讲的是用户把自己的业务数据从旧工具、表格文件带进你的产品；数据库表结构变更是另一篇已发指南的话题，测试用的假数据生成也是另一篇的话题。本篇不讲怎么改表结构、不讲怎么造假数据，只讲用户真实数据的搬运全过程。

先盘点：四类导入源，四种脾气

第一类是表格文件，通常是 CSV 或 Excel，这是最常见的导入源。它的脾气是格式自由：表头可能叫“客户名称”，也可能叫“Name”或“姓名”；日期可能写成 2026/10/1，也可能写成 10-01-2026；数字里可能混着货币符号和千分位逗号。表格导入必须做表头映射和格式清洗，不能假设用户会按你的模板填。

第二类是旧工具的导出文件，比如从 Notion、Trello、Airtable 导出的压缩包或 JSON。它的脾气是结构嵌套：一个任务下面挂着评论、附件、子任务，导出时层级可能被压平，也可能丢字段。处理这类来源时，先把“能保住什么、会丢什么”列出来，诚实地告诉用户，而不是悄悄丢掉一部分数据。

第三类是第三方 API 直连，比如用户授权后从旧服务直接拉数据。它的脾气是分页和限速：数据量一大就容易超时，接口一变字段就可能对不上。API 导入必须做成分批、可断点续跑的任务，不能做成一次性的同步请求。

第四类是手工粘贴，比如用户从网页表格里复制一段直接粘贴进来。它的脾气是格式最不可控，但对小批量用户最友好。粘贴导入适合“先让用户搬十条试试”的场景，可以作为正式导入前的小规模验证通道。四类来源可以先从表格文件做起，因为它覆盖了最多的用户，再逐步扩展到 API 直连。

六条设计原则

第一，导入前先预览，绝不直接写库。用户上传文件后，系统应该先解析出前若干行，展示一张映射预览表：左边是文件里的列，右边是系统里的字段，哪些对上了、哪些没对上、哪些行会被跳过，一目了然。用户确认映射无误后再点“开始导入”，这一步能拦住八成以上的错误。

第二，导入是可核对的。导入完成后，不要只给一句“导入成功”，要给一份结果报告：总共读到多少行、成功多少行、跳过多少行、失败多少行；失败的行要列出原行号、原内容和失败原因；成功的数据要能一键查看。用户需要凭这份报告判断：我的数据是不是都进来了。

第三，导入是可回滚的。每一次导入都应该生成一个批次编号，记录本次导入新增和修改了哪些记录。用户发现导入错了，可以按批次一键撤销，恢复到导入前的状态。没有批次概念的导入，等于让用户在没有后悔药的情况下做手术。

第四，重复导入不能产生重复数据。用户很可能因为第一次结果不满意而再导一次，或者网络中断后重试。导入必须用业务键去重：比如客户用邮箱或手机号做键，任务用旧系统的唯一编号做键。重复导入同一份文件，第二次的结果应该是“零新增、若干跳过”，而不是数据翻倍。

第五，错误要按行说人话。不要给用户看“Validation failed on row 42”这类报错，要写成“第 42 行：日期‘2026-13-40’无法识别，请改成 2026-01-15 这样的格式”。错误报告里最好附上原始行的内容，让用户不用翻回原文件就能定位问题。

第六，大导入要异步、可追踪。超过几百行的导入不要让用户在页面上干等，要转成后台任务，给出进度条、预计剩余时间和完成通知。用户关掉页面后回来，应该还能在导入记录里找到这次任务的状态和结果报告。

七步导入流程：从上传到核对

第一步，上传与格式识别。接受 CSV、Excel 和粘贴文本三种入口，上传后先做编码识别和分隔符探测：中文文件常见的 GBK 编码、Excel 里的合并单元格、CSV 里带引号的逗号，都要在解析层处理掉，而不是报错让用户自己转格式。文件大小上限要明说，比如单次最多五万行，超了引导用户分批或走 API。

第二步，字段映射。系统根据表头自动猜测映射关系：比如“客户名称”“Name”“姓名”都指向客户姓名字段；猜不准的字段留空，让用户手动选。映射界面要支持三件事：改映射、设默认值、标记忽略列。默认值很有用，比如用户文件里没有“状态”列，可以统一设为“待处理”，而不是让所有行导入失败。

第三步，规则预检。在真正写库之前，对全部行跑一遍轻量校验：必填字段是否为空、日期格式是否可解析、数值是否在合理范围、业务键是否重复。预检结果要分三档：可直接导入的行、有警告但可导入的行、必须修复的行。用户可以先修必须修复的行，也可以选择“只导入通过的行，失败的行生成一份待修文件”。

第四步，试跑一小批。不要一上来就全量导入，先对前五十行做一次真实写库的试跑，生成试跑报告给用户看。试跑的意义是让用户在小规模上验证映射和规则是否正确，错了只影响五十行，清理成本极低。试跑通过后，用户再点“全量导入”，这一步值得多花一次点击。

第五步，全量导入与批次记录。正式导入按批次写入，每批记录批次编号、来源文件名、映射快照和操作人。写入时用事务或分段提交，保证中途失败不会留下一半新一半旧的脏数据。导入过程中显示进度：已处理行数、成功数、失败数，用户可以随时查看，也可以先去做别的事。

第六步，结果报告与错误修复。导入结束后生成一份结果报告，失败的行可以下载为一份“待修文件”，里面保留原始内容并加一列失败原因。用户修好后可以直接把这份文件再导一次，系统用业务键去重，不会产生重复数据。报告要长期保留在导入记录里，而不是只在页面上闪一下。

第七步，核对与回滚。给用户一个核对清单：总数对不对、几个关键分类的分布对不对、抽查三条记录的字段对不对。如果不对，用户可以按批次一键撤销本次导入，数据恢复到导入前。撤销操作本身也要记录，防止用户误点后无法追溯。七步走完，一次导入才算真正闭环。

字段映射表的设计要点

映射表是导入功能里最值得花心思的界面。第一，表头猜测要透明：系统猜对了就显示“已自动匹配”，猜错了用户一点就能改，不要把猜测藏起来让用户猜系统在想什么。第二，支持同义词典：把“客户名称、姓名、Name、Customer”这类常见表头预先建成同义词表，随着用户反馈不断补充，猜测准确率会越用越高。

第三，日期、数字、枚举三类字段要单独处理。日期要支持多种格式自动识别，并在预览里把解析结果展示出来，让用户一眼看出有没有解析错；数字要去掉货币符号和千分位逗号，并标明小数位数；枚举值比如任务状态，要支持映射：用户文件里的“进行中、In Progress、Doing”都可以指向系统里的同一个状态值。第四，映射关系要保存为模板：用户下次导入同类文件时可以直接复用上次的映射，不用每次重新配一遍。模板按导入源类型保存，比如“客户表模板”“订单表模板”，而不是笼统的一份全局模板。

反模式：这六种做法请避开

• 上传即写库，没有预览和确认：用户一次手滑选错文件，脏数据就已经进库了，清理成本远高于多一次确认。
• 失败只给总数，不给行级原因：用户知道“失败了 37 行”，却不知道是哪 37 行、为什么失败，只能全部重导一遍。
• 没有批次概念，无法撤销：导入错了只能手动一条条删，用户会直接放弃这个产品。
• 重复导入产生重复数据：没有业务键去重，用户重试一次数据就翻倍，信任立刻崩塌。
• 用技术报错原文当错误提示：用户看不懂“foreign key constraint”，他只想知道第几行、哪个字段、改成什么样。
• 大文件同步导入，页面卡死超时：用户不知道导入进行到哪一步，刷新一次可能导致重复写入，体验和数据都会出问题。

检查清单：上线前逐项打勾

• 上传后先预览映射，用户确认后才写库。
• 预检分三档：可导入、有警告、必须修复，失败行可下载待修文件。
• 试跑五十行通过后，才开放全量导入。
• 每次导入有批次编号，记录映射快照，支持按批次一键撤销。
• 业务键去重已实现，重复导入同一文件零新增。
• 错误报告按行写人话，附原始行内容和修改建议。
• 大导入走后台任务，有进度、完成通知和导入记录可查。
• 日期、数字、枚举三类字段的清洗规则已在预览里可见。
• 映射模板可保存复用，按导入源类型区分。
• 已用一份真实的脏数据实测：空行、重复键、两种日期格式、异常分类名全部覆盖。

一个记账产品的落地示例

假设用户从旧记账应用导出了一份五千行的 CSV，表头是“日期、类别、金额、备注”，日期混着 2026/1/5 和 01-05-2026 两种格式，类别里既有“餐饮”，也有用户自己写的“吃饭”“外卖”。导入流程这样走：上传后系统自动把四列映射到日期、分类、金额、备注；预检发现三行日期无法解析、十二行金额带货币符号；试跑五十行后，分类映射界面提示“吃饭、外卖是否都指向餐饮”，用户确认合并；全量导入完成后报告显示成功 4985 行、失败 3 行，失败行下载为待修文件；用户修好三行再导一次，去重后零新增；核对时发现餐饮分类占比合理，导入完成。整个过程用户没有打开过数据库、没有手动改过一行原始数据，这就是导入功能应该有的样子。

最后提醒一句：导入功能上线后，最有价值的反馈来自用户真实的脏文件。把每次导入的失败原因做聚合统计：哪类字段最容易错、哪种格式最常见、哪个映射最常被手动改，这些数字会告诉你下一步该优化哪里。导入不是一次性功能，而是一条越用越准的管道：模板越攒越多、猜测越来越准、用户搬家越来越顺，产品的口碑就是这样一点点搬出来的。

API 直连导入的断点续跑设计

表格导入做顺之后，下一步往往是 API 直连导入：用户授权后，系统直接从旧服务拉数据。API 导入和表格导入最大的不同是时间不可控：旧服务可能限速、可能分页返回上万条、可能中途返回错误。如果把 API 导入做成一次同步请求，用户页面会在几分钟后超时，而后台到底写了多少条，谁也说不清。

正确的做法是把 API 导入拆成三个阶段：拉取、转换、写入，每个阶段都记录游标。拉取阶段按页请求，每拉一页就把原始数据存下来，并记下下一页的游标；转换阶段按映射规则逐条处理，失败的行单独记录，不阻塞整批；写入阶段按批次提交，每批成功后更新进度。任何一个阶段中断，下次续跑都从上次成功的游标继续，而不是从头再来。续跑按钮要放在导入记录里显眼的位置，用户不需要重新授权、不需要重新选映射，就能接着跑完。

限速和配额也要提前谈好。拉取时遵守旧服务的限速规则，遇到限速返回就按指数退避等待，而不是立刻重试把账号封掉；写入时控制并发，避免一次写入冲垮自己的数据库。导入记录里要展示三个数字：已拉取、已转换、已写入，用户看到这三个数字在动，就知道任务还活着。API 导入的另一个细节是字段漂移：旧服务改版后字段名变了，映射模板要能标出“上次能对上的字段这次对不上了”，提醒用户重新确认，而不是悄悄把整列丢掉。

最后是授权安全：API 直连需要用户在旧服务上授权，授权凭证要加密存储、只用于导入任务、任务完成后按用户选择保留或立即吊销。不要把授权凭证的权限要得过大，只要读数据的权限就够了；导入完成后给用户一句明确的说明，告诉他凭证是保留还是已吊销、在哪里可以手动吊销。用户把旧工具的数据交给你，信任的边界必须说清楚，含糊其辞的授权说明比导入失败更伤信任。

导入后的第一周：别让新数据烂掉

导入完成不是终点，接下来的一周决定了用户会不会留下来。第一，导入后的数据要有一个“新导入”标记或筛选视图，让用户在第一周里能快速找到刚搬进来的记录，逐条检查、批量修正。第二，系统应该在导入后三天内主动提醒用户核对一次，比如在首页放一句“你上周导入了 4985 条记录，已核对 120 条”，而不是导入完就再也不提。第三，收集用户在核对时的修正行为：哪些字段被批量改过、哪些分类被合并过，这些修正就是下一版映射模板的养料。导入功能的口碑不是在导入当天建立的，而是在用户发现“搬过来的东西真的能用、错了也真的能修”的那一周里建立的。