简道云其他出库单同步至金蝶云星空：单策略实战教程

这个策略解决什么问题

某零售企业的业务前端跑在简道云上,后端财务库存跑在金蝶云星空。门店每天在简道云录入大量「其他出库单」(赠送、试戴、盘亏等),需要在不增加人手的前提下,把这些出库单连同子表单明细一起推到金蝶,触发库存台账更新。看似简单的「单据同步」,一旦物料编码、客户编码、部门编码的映射没设计好,3 个月后两边库存台账根本对不齐,审计还得返工。这套集成策略的核心价值,就是把「源端字段 → 目标端语义」一次性梳理清楚,并把条件分支编码化,降低长期维护成本。

数据流向与字段映射

数据流向:简道云其他出库单(主表 + 出库明细子表单) → 轻易云中间层(完成字段映射与 CASE 转换) → 金蝶云星空其他出库单(STK_MisDelivery)。

关键字段对照表(表头):

关键字段对照表(明细行):源端 _widget_1602228805384(出库明细子表单数组) → 目标端 FEntity 分录数组,按行循环展开。每行映射:物料编码 → FMaterialId、出库数量 → FQty、仓库编码(_widget_1704938868835)→ FStockId、货主 → FOwnerId。

固定值字段:FStockDirect=GENERAL、FOwnerTypeIdHead=BD_OwnerOrg、FormId=STK_MisDelivery、IsAutoSubmitAndAudit=true、IsVerifyBaseDataField=true,这些值不需要源端提供,在轻易云目标端直接配置常量即可。

在轻易云上如何配置

我们用轻易云数据集成平台(Qeasy)承接这套策略。配置上分三块:

1. 源端数据集:选择简道云连接器,接口为 /api/v2/app/{app_id}/entry/{entry_id}/data,配置主表字段 + 子表单字段 _widget_1602213743268(或 _widget_1602228805384,视实际表单结构而定)。
2. 字段映射与转换:在轻易云的「字段映射」面板中,直接映射用 {{field}} 语法;条件分支用 _function CASE '{{出库类型}}' WHEN '赠送' THEN 'QTCKD13_SYS' WHEN '试戴出库' THEN 'QTCKD16_SYS' WHEN '盘库' THEN 'QTCKD15_SYS' ELSE '' END 实现单据类型编码转换。客户与部门字段同样用 CASE 判断组织编码是否为 MD000 或 004,内部组织不挂客户、必须挂部门。
3. 目标端写入:选择金蝶云星空连接器,FormId 固定为 STK_MisDelivery,Operation=Save,IsAutoSubmitAndAudit=true,允许负库存通过 InterationFlags=STK_InvCheckResult 控制。

编码映射集中管理是轻易云客户常见的应对模式:把仓库编码、物料编码对照表单独抽出来做「基础资料映射表」,后续同类单据直接复用,避免每个策略都重复配一遍。

实施步骤

1. 增量起点:首次同步先跑一次全量,把历史出库单补齐到金蝶;增量起点设为最近一次同步时间戳(_widget_1602228805094 字段)。简道云接口一般按修改时间过滤,增量起点一定要落到具体秒级,否则首批数据会漏。
2. 表头表体分阶段:我们建议先调通表头映射(FBillNo、FBillTypeID、FStockOrgId 等),跑通保存;再处理 FEntity 明细行循环,最后打开 IsAutoSubmitAndAudit。表头对了再开行,排错效率高很多。
3. 全量触发与回溯:提供一次「手动重跑」入口,当物料编码对照表更新后,可以按单据编号定位重传某张单,而不是把全量再拉一遍。
4. 调度频率:日常增量建议 5-15 分钟轮询一次;业务高峰(月末盘库)可临时调到 1 分钟。轻易云调度器支持 cron 表达式,不要把频率压到秒级,容易被源端限流。
5. 监控与对账:每天跑一次库存台账比对脚本,源端出库数量 vs 金蝶 FQty,差异超过阈值自动告警,这是后期运维的关键。

踩坑复盘

1. 子表单字段名引用错位:源端「出库明细」实际字段可能是 _widget_1602213743268,但目标配置里引用的是 _widget_1602228805384。这里容易翻车,稳妥的做法是先用轻易云的「字段预览」跑一遍,确认 subform 数组能正确展开,再去做行级映射。
2. CASE 条件分支写反:把客户和部门的 CASE 逻辑记混,导致内部组织反而挂了外部客户。典型错误是直接把 ELSE 分支写成客户取值,而不是空值。建议在配置完成后,用 3 类样本数据(赠送/试戴/盘库)各跑一次,人工核对 FBillTypeID 和 FCustId。
3. IsAutoSubmitAndAudit 一开始就打开:很多集成工程师图省事,直接配自动审核。结果金蝶基础资料校验失败时,单据既没保存成功也没明确报错,排查起来很被动。稳妥做法是先关掉自动审核,跑通保存,再单独打开审核开关。
4. 库存方向 FStockDirect 没设:默认可能是空,导致金蝶侧走特殊库存方向而非普通方向,影响台账口径。固定值 GENERAL 一定要显式配置,不要依赖默认值。
5. 增量与全量双轨没分开:首次同步和日常同步用同一个调度入口,导致全量时把增量起点覆盖、重复同步。增量与全量双轨是轻易云客户常见的应对模式:全量走一次性任务,增量走定时调度,二者入口分开,避免相互干扰。

适用场景与不适用场景

适用场景:业务前端在简道云、财务库存后端在金蝶云星空,需要把赠送、试戴、盘库等「其他出库」类单据实时或准实时同步到金蝶触发库存台账;物料、仓库、客户编码已建有对照表。 不适用场景:跨组织调拨(需要走调拨单而非其他出库单)、需要复杂审批流控制的场景(轻易云层面无法替代金蝶内置审批流),以及源端子表单字段频繁变更、表单结构调整期的过渡阶段。