接口项目失败的典型场景：程序能跑，日志正常，但采购拿到的 BOM 还是不能下单。技术上“通了”，业务上“没用”。
原因几乎总是同一个：接口把设计端的数据原样搬了过去，而设计端的口径本来就不统一。接口是放大器，不是过滤器——上游有什么问题，下游会被完整继承，而且更难发现。
这篇文章讲工程做法：数据流怎么设计、字段映射怎么写、主数据怎么治、异常怎么处理、升级怎么适配。
一、先判断：这个需求该不该开发
三类需求值得开发：
- 高频且规则稳定：一年上千次，每次步骤一致
- 人工易错：字段多、需转换、靠人核对容易漏
- 系统间必须实时或准实时：人工中转会成为瓶颈
三类不该开发：
- 一次性任务：只做一次的数据整理，写脚本的成本高于人工
- 配置能解决：编号规则、图框字段、报表列，多数能在项目设置里完成
- 流程未定型：流程还在变，写死的代码每次都要改
一个实用判断：把需求写成一句话，问“这个动作一年发生多少次、规则会不会变”。次数少或规则不稳，先别开发。
二、接口的三种形态
| 形态 | 工作方式 | 优点 | 限制 |
|---|---|---|---|
| 中间表 | 双方约定数据库表结构，定时读写 | 解耦、易排查、对系统侵入小 | 实时性差，需要数据库权限 |
| API 直连 | 调用对方提供的接口 | 实时、规范、可控 | 依赖对方接口能力与稳定性 |
| 文件交换 | 导出约定格式文件，对方导入 | 实现简单、跨系统兼容好 | 时效差，易出现版本混乱 |
形态选择不取决于偏好，取决于三个约束：两边系统的能力、IT 的权限策略、业务对时效的要求。
制造业里最常见的是“中间表 + 定时任务”：设计端定时把变更写入中间表，ERP 定时读取。它的好处是出问题时能直接看表里的数据，排查成本低。
三、数据流设计：四个必须定清的问题
问题一：谁是主数据源
物料编码以谁为准？设计库还是 ERP？必须二选一，不允许双写。
双写的后果是：同一物料在两个系统里各有一个版本，谁也不知道哪个是对的。等到采购发现型号不一致，追溯成本极高。
通常建议以 ERP 为物料主数据的唯一源，设计库从 ERP 同步；设计端只负责“选用”，不负责“创建”。但有些企业设计端先行（新产品先出图，物料后建档），这时需要一套“临时码转正”的流程。
问题二：单向还是双向
- 单向：设计 → ERP（BOM、需求），或 ERP → 设计（物料、价格）
- 双向：两边都能改，需要冲突解决机制
双向的复杂度远高于单向，因为要处理“同一字段两边都改了”的情况。除非业务确实需要，否则优先单向。
问题三：全量还是增量
全量简单但慢，增量快但需要可靠的变更识别。
增量同步的关键是“变更标记”：设计端要能识别哪些数据是新的或改过的。如果软件本身不提供变更日志，通常需要在接口层做快照比对——这会增加复杂度，也可能漏掉“改了又改回去”的情况。
问题四：失败怎么办
接口一定会失败：网络断了、对方系统在维护、数据不合规。失败后的处理必须事先约定：
- 重试几次、间隔多久
- 重试仍失败时，进人工队列还是丢弃
- 人工处理完怎么重新入队
- 失败记录保留多久
没有失败处理方案的接口，第一次出问题就会变成“停线等 IT”。
四、字段映射：把口径写在纸上
字段映射表是接口项目的核心文档。它不是一个技术附件，而是双方对“数据是什么”的共识。
| 设计侧字段 | 目标字段 | 必填 | 转换规则 | 异常处理 |
|---|---|---|---|---|
| 部件号 | 物料编码 | 是 | 去空格、统一大写 | 空值阻断并记录 |
| 制造商 | 供应商 | 是 | 按对照表转换 | 未匹配进待处理队列 |
| 型号 | 规格型号 | 是 | 原样传递，去尾部空格 | 超长截断需告警 |
| 数量 | 需求量 | 是 | 按 BOM 层级汇总 | 小数位统一两位 |
| 单位 | 计量单位 | 是 | 按对照表转换 | 未匹配阻断 |
| 项目号 | 项目/订单号 | 否 | 原样传递 | 空值允许 |
| 位置 | 装配位置 | 否 | 按位置码映射 | 未匹配记录 |
写映射表时，四个坑最常见：
坑一：只写正常值，不写异常。 空值、重复、超长、特殊字符，这些才是工作量的主要来源。一张 30 个字段的映射表，异常规则可能占一半篇幅。
坑二：单位不统一。 设计端用“个”，ERP 用“PC”；设计端用“米”，ERP 用“M”。不统一，数量全错。
坑三：一对多没处理。 一个设计部件对应多个可选物料（替代料），映射表必须说明取哪个、按什么规则。
坑四：字段含义靠猜。 “位置”在设计端指安装位置，在 ERP 里可能指库位。名字一样，含义不同，必须在表里写清定义与示例值。
五、主数据治理：接口之前必须做的事
如果设计库里的部件属性缺失三成，接口会把这三成缺失同步到 ERP，然后采购开始打电话。返工的范围比不做接口更大。
治理的最小动作：
- 定必填字段：制造商、型号、描述、单位、物料组，缺一不可入库
- 查重：按“制造商 + 型号”做唯一性校验，合并重复条目
- 补全：能确认的补，不能确认的进待处理队列，不猜
- 抽检：随机 20 条，核对图纸—库—ERP 三方一致
这四步做完，接口的成功率会大幅提升。跳过这四步，接口项目会在联调阶段反复返工。
六、异常处理：四种场景的约定
| 场景 | 处理策略 | 是否阻断 |
|---|---|---|
| 必填字段为空 | 记录并进入待处理队列，通知责任人 | 阻断该条 |
| 物料编码重复 | 按“制造商+型号”合并，保留最新 | 阻断并告警 |
| 字段超长 | 按目标系统限制截断，保留原文到备注 | 告警不阻断 |
| 接口超时 | 指数退避重试三次，仍失败转人工 | 阻断该批 |
| 数据格式非法 | 拒绝该条，记录原始报文 | 阻断该条 |
原则是：能定位的单条问题阻断单条，不能定位的批次问题阻断批次。 最怕的是“静默跳过”——数据没同步，但没人知道。
七、升级适配：让接口活得久一点
接口的寿命通常比软件版本短。EPLAN 或 SWE 升级后，依赖的 API 可能变化，程序需要回归测试。
降低风险的四条做法：
- 只用官方公开 API，不碰内部结构与未公开接口
- 程序内置版本判断，不同版本走不同分支
- 接口层与业务层分离，升级时只改接口层
- 交付升级适配说明：依赖了哪些 API、哪些功能需要回归测试
升级前留回滚方案：先在测试环境升级，跑一遍关键链路（打开项目、导出 BOM、生成报表、打印），再动生产环境。
如果插件是几年前的第三方开发的、没有源码也没有文档，升级前先做“可维护性评估”。评估结论通常是“重写比适配便宜”，早接受比晚接受好。
八、验收：一条链路，逐列比对
接口验收不要看演示，看数据。
- 选一个真实项目，从设计端导出，到目标系统接收
- 逐行逐列比对，差异必须能逐条解释
- 检查异常场景：故意造一条空值、一条重号、一条超长，看处理是否符合约定
- 检查日志：能否定位到“哪条数据、什么原因、处理结果”
验收通过的标志是：采购拿到同步后的 BOM，不需要打电话确认就能下单。
九、三个反模式
反模式一：先写代码，后定口径。 开发过程中不断发现“这个字段是什么意思”，代码反复改。正确顺序是先把映射表定稿。
反模式二：一次做全量集成。 所有系统、所有字段一次打通，需求在过程中膨胀。正确做法是先做一条最有价值的链路，闭环后再扩展。
反模式三：接口做完就没人管。 没有监控、没有失败告警、没有责任人。接口失效两周后才发现，数据已经断档。
常见问题
Q20EPLAN 二次开发到底能做什么？哪些需求其实不需要开发？
值得开发的三类需求：
- 系统接口：与 PLM/ERP 交换物料、BOM、项目数据，人工搬运频繁且易错
- 批量处理：几十上百个项目要统一改图框、改属性、导数据，手工做不现实
- 特制输出：报表格式特殊，软件自带配置改不出来，且格式长期稳定
不建议开发的三类需求：
- 一次性任务：只做一次的数据整理，写脚本的成本高于人工
- 本可以用配置解决：编号规则、图框字段、报表列，多数能在项目设置与模板里完成，开发反而增加维护负担
- 流程尚未定型：流程还在变，先把代码写死，后面每次调整都要改程序
一个实用判断：把需求写成一句话，问“这个动作一年会发生多少次”。几十次以内，人工或半自动更划算；上千次且规则稳定，才值得开发。还有一条常被忽略：开发交付的不只是程序，还有接口文档、字段映射表、异常处理约定和升级预案。没有这些，程序半年后就是黑盒。
Q21EPLAN 和 SAP、用友这类 ERP 对接，BOM 怎么才能打通？
BOM 打不通，八成不是接口技术问题，而是三处口径不一致：
- 物料编码：设计库里的部件号与 ERP 物料号不是同一套，或同一物料两个号
- 层级定义：图纸上的 BOM 是“功能结构”，ERP 要的是“装配结构”，层级关系对不上
- 变更时点：设计变更后，什么时候同步、同步哪些字段、历史版本怎么处理，没有约定
落地顺序建议：1. 先做物料主数据治理：确定唯一编码源，是 ERP 主还是设计库主，二选一，不允许双写2. 再定字段映射表：设计侧字段、ERP 字段、是否必填、转换规则、异常值处理，逐列写清3. 然后定同步策略：全量还是增量、单向还是双向、失败重试与人工兜底4. 最后才是写接口与联调接口形态通常是中间表、API 或文件交换，选哪种取决于两边系统的能力与 IT 约束，不取决于偏好。验收要盯一件事：同一项目，从设计端导出的 BOM 与 ERP 接收后的 BOM，逐行逐列比对，差异为零。做不到这一步，接口只是“能跑”，不是“能用”。
Q22二次开发的周期和费用怎么评估？会不会做起来没底？
评估一个二次开发项目，看四个变量：
- 接口数量与方向：几个系统、单向还是双向、实时还是批量
- 字段复杂度：映射字段多少、是否有取值转换、是否存在一对多
- 异常分支：数据缺失、重复、超长、编码冲突时怎么处理，这部分常被低估，实际能占一半工作量
- 环境约束：能否拿到测试环境、是否有权限限制、联调窗口是否可控
合理的推进方式是“先单点、后扩展”：选一条最有价值的链路（例如某类项目的 BOM 导出到 ERP），做成闭环并验收，再复制到其他链路。一上来做“全系统集成”，需求会在过程中不断膨胀。关于费用，我们不在网页上给数字，原因不是回避，而是区间没有意义：同样是“EPLAN 对接 ERP”，字段 10 个和 80 个、单向和双向、有无测试环境，工作量差数倍。正确做法是先出一页需求边界说明（做什么、不做什么、验收标准），再据此评估。合同里建议明确三件事：需求变更怎么计价、源码与文档是否交付、软件升级后接口适配是否包含。
Q23二次开发会不会影响后续 EPLAN 升级？升级后插件还能用吗？
会影响，但风险可控，关键在于开发时依赖了什么：
- 依赖官方公开 API：升级后通常只需适配少量签名变化，风险最低
- 依赖内部数据结构或未公开接口：版本一变就可能失效，风险最高
- 依赖文件格式直读直写：格式微调就会出错，需要版本兼容层
降低升级风险的四条做法：
- 只用厂商公开的 API 与扩展点，不碰内部实现
- 把版本判断写进程序，不同版本走不同分支，而不是假设只有一个版本
- 接口层与业务层分离，升级时只改接口层
- 交付时附一份“升级适配说明”：依赖了哪些 API、哪些地方需要回归测试
还有一件常被忽略的事：升级前要留回滚方案。测试环境先升，跑一遍关键链路（打开项目、导出 BOM、生成报表、打印），再动生产环境。如果插件是几年前由其他方开发的、没有源码也没有文档，升级前先做一次“可维护性评估”，比升级后救火便宜。
有具体对接场景时，建议先准备三样东西：现状流程图、涉及的系统清单、一份真实的 BOM 样例。有了这三样，判断“该开发还是该配置”通常只需要一次沟通。