一物一码接口字段映射,应把每个字段的含义、来源、格式、可变条件与失败处理写清楚。产品名称相同不代表身份相同,请求发出也不代表业务已经完成。潜利建议在联调前建立字段与事件清单,用能够人工复核的任务样本逐项验证。
产品主键和展示名称分别管理
产品编码用于识别对象,名称用于阅读。两个系统使用不同编码时,应维护受控映射并保存有效范围,不宜按名称相似直接匹配。前导零、大小写和批号字符要按约定保留,避免把字符编号当成数字处理。
单位也需要明确。ERP一箱、现场一瓶、仓库一托的数量不能直接相加。箱规发生变化,应根据任务及版本计算,不能用今天的箱规解释所有历史单据。
最小字段清单怎样写?
| 字段 | 含义示例 | 校验重点 |
|---|---|---|
| businessId | 原系统业务单号 | 可追到实际任务 |
| eventId | 本次业务事件身份 | 重试沿用原编号 |
| productCode | 受控产品主键 | 映射有效且唯一 |
| eventTime | 现场实际发生时间 | 与接收时间分开 |
| version | 当前业务版本 | 防止旧状态覆盖 |
这些名称是技术示例,不是潜利或其他平台固定接口。实际开发应列出必填、允许为空、长度、字符集、枚举及责任系统。对于包装关系,还需说明绑定、拆分和更正事件如何表达。
重试为何需要保持同一身份?
网络超时可能发生在服务端已经处理后。若客户端每次重试都创建新事件,可能重复入库或重复绑定。可使用稳定事件编号识别同一请求,并检查相同编号的内容是否一致。内容冲突应进入异常处理,不能无条件当作成功。
并发修改也需要核对当前业务版本。读取箱内十件后,另一工位已经拆走两件,原请求不能继续按旧清单覆盖。应返回明确冲突,让人员重新查询和复核。
错误回执需要分几类?
区分网络不可达、权限不足、字段错误、对象不存在、状态冲突与结果未知。临时网络问题可按策略重试,业务校验失败应修复原因后再处理。回执应包含请求身份、处理状态及可查询线索,公开页面不显示内部凭据与敏感日志。
错误清单还需明确人工职责。技术人员可以检查传输格式,但不能代替仓库确认实物。补录与更正由授权岗位操作,并保存前后关系。
模拟联调:回执丢失后的重复提交
以下为模拟测试。仓库出库事件已处理,但返回中断。重试后应查到原处理结果,库存只变化一次。随后再用相同事件编号提交不同数量,系统应提示冲突,而不是静默覆盖。最后对照原单据、库存与事件记录,确认一致。
测试条件与交付材料
固定测试数据、系统版本、时区与样本数量,分别演练重复提交、字段缺失、主键未知、取消单据和断网恢复。测试结果注明预期、实际、证据与处理人,不用“接口正常”一句话概括全部场景。
可以先参考系统职责与实施总览确定业务边界,再结合生产赋码管理系统确认现场回传数据。
常见问题
原系统只有文件导出还能对接吗?
可以评估文件或中间表方式,但仍需唯一身份、导入校验和结果对账。
重发失败记录可以直接改编号吗?
不宜通过改编号绕过错误,应先判断是否同一业务事件。
时间字段全部用服务器时间可以吗?
应区分现场发生时间与接收时间,尤其关注离线补传。
需要制定字段与异常联调清单,可联系潜利科技:400-600-9896。