PapaParse CSV 客户导入解析

CSV 客户数据导入的常见痛点

当需要将 CSV 文件中的客户信息批量导入系统时，开发者常面临几个具体问题：编码不一致导致中文表头乱码，无法判断文件是否有表头，表头名称与系统字段（如“公司”“联系人”“手机”）不匹配需要手动映射，大文件直接解析可能引发内存风险，且全量导入前缺乏预览确认环节容易误操作。

技能核心能力与工作流程

该技能基于 PapaParse 库构建，默认开启 header: true（无表头文件需手动关闭），优先采用 UTF-8 编码处理，若出现乱码会提示用户另存为 UTF-8 或尝试其他编码。核心流程分为三步：

• 第一步：选择文件并通过 parseCsvFile 解析，自动提取表头字段并展示前 50 行预览表格；
• 第二步：配置表头与业务字段的映射关系（如将 CSV 中的“公司名称”映射到系统“公司”字段）；
• 第三步：二次确认后再写入业务库，可接入 Zod/Yup 进行行级数据校验。

适用边界与注意事项

• 预览默认仅展示前 50 行，全量导入必须经过二次确认，避免误操作；
• 空文件或无有效行时，会返回明确的中文错误提示；
• 禁止静默导入上万行数据，需提前提示内存风险；
• 不能将 xlsx 二进制文件当作 CSV 硬解，应先转换为 CSV 或使用专门的 xlsx 解析库。