退货通知单关联查询：从旺店通到金蝶云星空的同步策略实战

这个策略解决什么问题

在某零售企业的 ToB 业务里，退货通知单既要给仓库做预收登记，也要给财务记账。从旺店通推过来的退货单据如果不能及时回写金蝶云星空，库存与应收就会一直停在“待确认”状态。这条策略的核心，是用金蝶的 executeBillQuery 接口按源单号关联查询退货通知单，再把结果回传至轻易云数据集成平台（Qeasy）的中间层，作为后续单据转换与写入的“事实底座”。

数据流向与字段映射

数据流向清晰分三段：旺店通（源）→ 轻易云中间层 → 金蝶云星空（目标）。第一段是从旺店通拉取退货原始数据；第二段在轻易云里做清洗、字段映射与编码翻译；第三段是把整理好的查询条件提交给金蝶的 executeBillQuery，回写单据状态。

关键字段对照如下：

业务含义	源系统（旺店通）	中间层（轻易云）	目标系统（金蝶云星空）
单据唯一编号	退货单号	id	FBillNo
源单单号	原始出库单号	src_bill_no	FSRCBILLNO
内部主键	旺店通 FID	src_id	FID
退货日期	业务日期	bill_date	FDate
退货客户	客户编码	cust_code	FRetcustId.FNumber
销售组织	组织编码	sale_org_code	FSALEORGID
分录内码	明细行 ID	entry_id	FEntity_FEntryID

实战经验：客户编码这种带“.”路径的字段（例如 FRetcustId.FNumber），在轻易云里要按“路径字段”单独建映射，否则会被当成普通字符串。

在轻易云上如何配置

在轻易云数据集成平台里，这条策略属于典型的“源端查询 + 目标端无写入”形态：源端按时间窗和源单号轮询，目标端是金蝶的查询接口。配置要点如下：

源平台填写金蝶云星空的连接信息（账套、用户、安全模式），接口选 executeBillQuery，HTTP 方法 POST，效果为 QUERY。
请求体按金蝶 Filter 格式组装，关键入参 FBillNo、FSRCBILLNO、FDate、FRetcustId.FNumber、FSALEORGID 全部列在 request 数组里，is_required 根据业务可选填。
返回结构勾选 autoFillResponse 与 buildModel，让轻易云自动根据金蝶返回的 JSON 推断出字段模型，省掉手工建表的工夫。
目标平台选轻易云自己的 datahub，接口名为“写入空操作”，idCheck 打开、buildModel 关掉——这一步相当于把查询结果沉淀到中间库，不直接落金蝶。
调度使用 crontab */15 * * * *，每 15 分钟跑一次，配合增量时间戳即可。

实施步骤

在客户现场，我们一般把实施拆成四步，避免一上来就跑全量。

第一步：确定增量起点。 先在金蝶里查一次最近一笔退货通知单的 FDate，把这个时间作为增量窗口的左边界；右边界用 now()。轻易云支持把这条 SQL 当成“预查询”跑，结果存为变量，避免硬编码日期。

第二步：构建全量触发。 全量只在切换日跑一次。把时间窗放大到“近 180 天”，手工触发一次，确认轻易云中间层的记录数和金蝶 executeBillQuery 返回条数一致，再放开调度。这一步是踩坑复盘里最容易翻车的地方，下面会展开。

第三步：配置调度频率。 退货单量不大的客户，*/15 * * * * 完全够用；如果是大促节点后，单量可能瞬时翻倍，可以临时把频率切到每 5 分钟，等单量回落后再切回 15 分钟。轻易云的调度可以直接在线上调整，不需要重启策略。

第四步：上线监控与对账。 在轻易云的运行监控里，重点看“空返回率”和“重复返回率”两个指标。空返回说明查询条件太严，重复返回说明去重键没配对。常见的稳妥做法是用 FBillNo + FEntity_FEntryID 组合做去重键，单据头与表体分阶段落库。

踩坑复盘

路径字段被当成普通字符串。 FRetcustId.FNumber 这种金蝶特有的“维度点路径”，在轻易云里必须用“路径提取”转换器，否则返回的 customer 永远是 null，下游写入会失败。
增量起点没固化。 第一次跑完忘了把起始时间存进轻易云的变量表，第二天调度又从 1970 年开始拉，几小时内把 180 天数据全跑了一遍，源库被打到报警。
全量没做条数比对。 直接放开全量，没先在轻易云里做“源端条数 vs 目标端条数”校验，结果金蝶某张表做过权限过滤，返回条数对不上，事后排查花了整整一天。
idCheck 与 buildModel 同时打开。 这是金蝶 WebAPI 配置里的高频错误：idCheck 只在写入场景需要，查询场景必须关掉；buildModel 则反过来，只在第一次接入时打开一次用于推断字段，之后要关，否则每次返回都会重建模型、消耗资源。
编码映射散落在脚本里。 客户编码、组织编码、仓库编码这三类主数据，在轻易云里建议集中放到一张“编码映射表”统一维护，不要写死在每条策略的转换器里。我们做过的客户，三个月后改一次组织架构，如果映射没集中管理，要改 30 多条策略。

适用场景与不适用场景

适用：ToB 退货单据需要按源单号反查、且查询频率稳定（每 15 分钟一次以内）；金蝶侧退货通知单权限清晰、不需要做复杂聚合。 不适用：单据需要在金蝶侧做实时反写、且对延迟要求在分钟级以内；或者退货明细体量巨大、需要流式处理的场景，此时应改用分页拉取+游标的策略，而不是一次性 executeBillQuery。