聚水潭对接金蝶编码对不上怎么办：客户、物料和单位映射的处理方法

@TOC

一、接口通了，单据却被基础资料挡住

聚水潭和金蝶两边都有商品档案，不代表编码可以直接互用。一边叫 SKU-A，另一边叫 WL001，程序需要明确的对照关系，不能只把商品名称复制过去。

本文依据我自己的对接项目代码和映射设计说明做法，没有新增客户实测案例。示例编码都是虚构的，配置应按客户账套确认。

二、先决定哪边维护主档

我目前的实现是从目标系统拉客户和物料，保存到本地缓存供对码使用；不自动把两边档案合并，也不默认往目标系统新建基础资料。

这样做把问题分开了：目标系统有哪些资料，是缓存更新的问题；来源编码应该对应哪个目标编码，是业务确认的问题。

不能默认每个电商买家都要在金蝶建一个客户，也不能默认所有店铺都归同一个客户。这属于财务业务口径，需要先确认。

三、名称匹配只能帮助找候选

“白色短袖”和“白色短袖”可能尺寸不同；同名客户也可能属于不同组织。名称一致不能作为自动写入的唯一依据。

上线前可以按名称辅助整理候选，但最终要由负责人确认编码对照。没有唯一对应关系就挂起，避免把数据写入错误客户或物料。

映射表至少保存这些列：

编码按字符串处理。把 00123 转成数字后再存成 123，会丢掉前导零。

四、缓存表不是对照表

项目的基础资料缓存以连接和编码为键，重复拉取时更新名称、规格、单位等字段。它解决的是“最近一次读取到什么资料”，不是“两个系统什么编码等价”。

下面是说明结构的简化 SQL，表名和字段名为示例：

CREATE TABLE material_cache (
connection_id TEXT NOT NULL,
target_code TEXT NOT NULL,
target_name TEXT,
refreshed_at INTEGER NOT NULL,
 PRIMARY KEY (connection_id, target_code)
);
CREATE TABLE material_mapping (
connection_id TEXT NOT NULL,
source_code TEXT NOT NULL,
target_code TEXT NOT NULL,
confirmed_by TEXT NOT NULL,
 PRIMARY KEY (connection_id, source_code)
);

若一个来源编码需要按组织对应不同目标编码，应把组织也纳入映射键。组合商品拆分成多行的场景，则需要额外的拆分规则，不能硬塞进一对一表里。

缓存更新失败时，不应清空此前成功获取的资料。反过来，拉不到一条档案也不代表它已被删除：可能是权限、筛选或分页范围变化。

五、缺少映射应该停在哪一步

建议在单据写入前检查所需映射。发现缺失时保存来源单据标识、缺失编码和错误阶段，进入待处理清单。

function resolveCode(mapping, sourceCode) {
 if (sourceCode == null || String(sourceCode).trim() === '') {
   throw new Error('来源编码为空');
}
 const key = String(sourceCode);
 const target = mapping.get(key);
 if (target == null || String(target).trim() === '') {
   throw new Error(`缺少编码对照：${key}`);
}
 return String(target);
}

这是独立的示例函数，不是完整接口调用代码。不要为了让任务通过，随意设置“默认物料”或“默认客户”；那会把可见的失败变成不易发现的错账。

修复映射后，再补处理对应失败单。补处理前仍要查询目标，确认此前是否已经保存，避免超时导致重复创建。

六、单位换名和单位换算是两回事

“公斤”改为目标单位编码 kg 是名称或编码转换；“箱”改为“个”可能还需要数量换算。

例如一箱十二个，仅把单位改成“个”而数量仍写一，会改变库存数量。若单价也按箱计价，还要确认价格及金额怎样对应。

验收应同时核对单位、数量、单价和金额，不要只看商品名称相同。

七、基础资料变更后，历史单怎么办

更改映射通常影响后续任务，但已写入目标的单据不会自动变正确。把 A 改映射到 B 后，需要区分三种情况：未推送任务、失败待处理任务、已经完成的目标单据。

前两种可以在确认当前报文后重新处理；第三种应走业务修正流程，并保留原来使用的映射版本。不要静默修改已审核单据。

八、上线前用这五项验收