乐悠厨房接手公司OA系统后，我遇到最头疼的事，不是流程配置，而是泛微ecology9建模表的Excel批量导入。市场部每周都要往项目台账建模表里导一份Excel，日期有的带点、有的带杠，客户名称大小写混用，甚至有的行里直接写“待定”，导进去之后统计报表全废。后来仔细研究建模表的导入转换接口，才把这类杂乱Excel变成本地合规数据。这篇文章就把我整套实践过程记录下来，从接口原理、实现步骤到高频场景和坑点，一次讲透，给正在做E9二次开发的你一个可以直接抄的作业。
1. 业务部门的Excel总是“脏数据”：建模表导入的最后一公里问题
1.1 默认导入能做什么，做不到什么
泛微EC9自带的建模表（也叫建模引擎/自定义模块）Excel导入功能，平时用来做基础数据初始化确实非常方便。你只需要在后台设计好表结构，勾选允许导入，系统就会生成一个标准的Excel导入模板，用户填写后上传，系统自动把每一行映射到建模表字段上。默认情况下，这个过程做的是“字段名对字段名”的直传，也就是Excel第A列对应建模表的company_name字段，第B列对应owner字段，数据是什么，落库就是什么。
这个设计在数据规范、格式统一的内部系统之间没有问题。可一旦面对外部Excel，各种业务人员手工填写的表格，默认导入几乎必然出问题。我遇到过的情况包括：
- 日期列有“2024/3/1”“2024-03-01”“20240301”“2024年3月1日”四种写法；
- 金额列里有千分位逗号、人民币符号，甚至有的单元格存的是文本前导空格；
- 下拉选项列里填的是中文显示值，而建模表里真正存的是英文编码；
- 需要外键关联其他表的时候，Excel里只有业务名称，没有目标表的主键ID。
这些情况，默认导入的字段映射是解决不了的，因为它只做“搬家”，不做“加工”。这也是很多E9项目上线后，业务人员抱怨“导入不好用”的真正原因——其实不是导入功能不行，而是数据在进建模表之前缺少一道处理工序。
1.2 三种最典型的需要处理的数据现场
从接触过的项目来看，建模表导入数据需要“额外处理”的场景大致可以归成三类。
第一类是格式规范化。这是最普遍的。不同来源的Excel，同一类信息的格式五花八门，而建模表的字段类型是定的：日期字段就是date，数字字段就是decimal。一旦Excel里某个单元格格式不匹配，整行导入就会报错，或者虽然导进去了，但后续列表展示、查询排序全是乱的。这类问题必须在入库前把字符串清洗成统一格式。
第二类是编码映射。业务人员填Excel时习惯填中文显示值，比如性别写“男/女”，部门写“华东大区”，产品写“精密仪器A型”。但建模表如果设计成字典字段或外键字段，真正需要写入数据库的是编码“M/F”“HD”“P-A”。要是不处理，数据是安静的，但查询统计一塌糊涂。
第三类是关联ID补全。建模表经常要引用其他表的数据，比如项目表要关联客户表，Excel里业务人员只会写客户名称，不会写也不应该让他们写客户表的内部ID。这时候就要在导入过程中拿客户名称去客户表里查，查出主键ID，再填到项目表的customer_id字段里。这个操作最容易被忽略，也最影响使用体验。
1.3 导入转换接口的价值边界
泛微的建模表导入转换接口，本质就是给导入动作留了一个“自定义加工”的钩子。你在配置里指定一个Java实现类，导入的时候，系统会在每一行数据落库之前，先把当前行数据塞进你的代码里走一遍；你把它处理完再还给系统，系统再入库。
这个接口的边界要讲清楚：它处理的是一行一行的单元格数据，做的是“数据清洗、格式转换、默认值补全、关联查询”，不是用来做跨行汇总、批量计算的。如果你有一万行数据需要求平均值再写回每一行，那应该在Excel端处理完再导，而不是指望转换接口来做。理解了这个边界，后面写代码的时候思路才会清晰。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. E9建模表导入的执行链路与转换接口插入位置
2.1 从上传Excel到落入建模表，系统其实做了四步
真正写转换接口之前，我建议先把E9建模表导入的完整过程吃透。它看着是“上传文件”一个动作，实际后台拆成四步：
第一步是文件解析。前端把Excel传到后台，系统按Sheet页、行、列把Excel解析成一个二维数据结构，也就是行集合，每一行是一个字段名到单元格值的Map。这一步它不关心你的字段类型是什么，所有单元格内容先统一以字符串形式取出。
第二步是字段映射。系统根据你在导入规则里配置的Excel列与建模表字段的对应关系，把第一步解析出来的Map重新组装成“建模表字段名 -> 单元格值”的形式。比如Excel表头是“客户名称”，建模表字段是customer_name，映射之后Map里的key就变成customer_name。
第三步是数据转换。如果你的导入规则里挂了转换类，系统在这一步会调用你的转换逻辑，把第二步得到的Map传给你，你处理后返回。这里就是转换接口的插入位置。
第四步是校验入库。系统拿到你返回的数据，按建模表字段类型做最终校验，比如日期能不能解析、必填项有没有值、外键是否存在，然后执行insert或update（取决于你导入