生产任务单到工单:一条策略讲透 KIS 私有云与黑湖小工单的同步落地
这个策略解决什么问题(场景与价值)
在离散制造企业的车间现场,ERP 端下达的生产任务单是计划口径,而 MES 端的工单是执行口径。两边一旦对不齐,车间就会同时存在"有工单无任务、有任务无工单"的尴尬。我们在客户现场遇到的典型情况是:某制造企业的 KIS 私有云每天会批量下发几十到几百张生产任务单,这些单据需要按计划开始时间落到黑湖小工单里,作为车间领料、报工、齐套分析的入口。本策略解决的就是这条"任务单 → 工单"的链路打通,关键价值在于把计划时间、计划数量、产品编码一次性带过去,让车间不用二次录入。
数据流向与字段映射(源 → 中间层 → 目标)
整体链路是单向的 A → B,源系统为 KIS 私有云,通过 RESTful 接口拉取生产任务单列表;中间层由轻易云数据集成平台(Qeasy)承担字段映射、编码转换与时间格式化;目标系统为黑湖小工单,通过 WebAPI 写入工单主数据。
关键字段对照表:
| 业务含义 | 源端(KIS 私有云) | 目标端(黑湖小工单) | 映射说明 |
|---|---|---|---|
| 单据编号 | FBillNo | projectCode | 直接传,作为幂等键 |
| 产品编号 | FItemID | productCode | 通过物料策略查表转换为 FNumber |
| 计划数量 | Fauxqty | plannedNum | 直接传,字符串口径 |
| 计划开始时间 | FPlanCommitDate | planStartTime | DATE_FORMAT 标准化为 yyyy-MM-dd HH:mm:ss |
| 计划结束时间 | FPlanFinishDate | planEndTime | 同上,做时间格式化 |
| 增量游标 | KIS-Timestamp | — | 用 {{LAST_SYNC_TIME}} 控制增量 |
源端接口分页参数包含 CurrentPage,目标端是单条创建接口,需要按单循环写入。
在轻易云上如何配置
在轻易云(Qeasy)上,这条策略的配置核心是"源查询 + 目标执行"的组合:
- 源端:选择 KIS 私有云适配器,API 选
/manufacturingorder/list,方法 POST,分页字段 CurrentPage;增量字段绑定{{LAST_SYNC_TIME}},作为 KIS-Timestamp 的请求值。 - 目标端:选择黑湖小工单适配器,API 选
/api/dytin/external/project/create,方法 POST,逐单写入。 - 字段映射:productCode 用
_findCollection从物料同步策略的结果集中按 FItemID 反查 FNumber,这是轻易云客户常见的"编码映射集中管理"模式——物料编码统一在一个策略里维护,业务单据策略只做引用,避免双向重复维护。 - 函数处理:时间类字段统一用
_function DATE_FORMAT(..., '%Y-%m-%d %H:%i:%s')兜底,防止源端返回空值或非标格式时目标端报错。
实施步骤(分阶段调度)
生产任务单同步讲究"增量起点 + 全量兜底 + 高频调度":
- 增量起点:首次上线时,把
{{LAST_SYNC_TIME}}初始化为一个较近的历史时间点(例如上线前一天),保证不会漏单。 - 全量触发:上线首日手动触发一次全量回灌,把历史任务单补齐;之后只跑增量。
- 调度频率:源端 crontab 设为
30 7,9,11,13,15,17,19,21 * * *(每 2 小时的半点触发查询),目标端 crontab 设为3-59/15 7-22 * * *(每 15 分钟执行一次写入)。这种"查询与执行错峰"是轻易云客户常见的双轨节奏——查询拉数据,执行消化数据,互不堵塞。 - 依赖关系:本策略 depends_on 物料策略,确保产品编码先到位,工单里的 productCode 才能查到。
踩坑复盘
- 编码映射没集中管理:早期有客户把 FItemID → FNumber 的转换直接写在工单策略里,结果物料那边一旦改了编码,工单全部对不上。稳妥的做法是用
_findCollection引用物料策略的结果集,改一处生效全局。 - 时间字段空值崩溃:源端偶发返回 FPlanCommitDate 为空,目标端 datetime 字段又是必填,直接 422。建议在映射层加一个默认值(例如当前时间 + 24 小时),或者在函数里做 IFNULL 兜底。
- 幂等键没设计:projectCode 直接传 FBillNo,看似天然幂等,但如果源端单据重号或重传,目标端会重复创建工单。这里容易翻车,稳妥的做法是在目标端适配器里开启 idCheck=true,失败时走更新分支而不是再插一条。
- 表头表体一锅炖:生产任务单通常有表头 + 多条明细(BOM 子件),本策略只同步了表头维度,明细留给后续工序。如果一次性把表体也塞进同一个 projectCode,黑湖那边会按"成品 + 组件"拆成多个工单,反而乱。建议分阶段:先跑通表头,再补表体。
- 增量游标被回拨:KIS-Timestamp 用的是最后同步时间,如果服务器时钟漂移,会出现"增量区间倒退"导致漏单。运维层面要监控源端与轻易云平台的时间差,超过阈值就告警。
适用场景与不适用场景
适用:ERP 下达生产任务单、车间 MES 需要按计划开始时间生成工单、计划数量相对稳定、不需要回写报工数据的场景。 不适用:需要把工单实际完工数量、报废数量回写 ERP 的双向同步;以及源端单据结构与目标端差异巨大、需要自定义中间表做转换的复杂场景——后者建议拆成多条策略,而不是塞进一条。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/solutions/strat-kis-pce9768-9398-kis-90c1de61