仓库主数据查询同步：从星辰到领星的稳健落地

这个策略解决什么问题

某零售企业在多套 ERP 并存的环境下，仓库主数据集中在金蝶云星辰，订单履约与库存调度又依赖领星 ERP。如果仓库档案靠人工维护，两边编码、名称、启用状态很容易漂移。我们用轻易云数据集成平台承接一条仅查询的仓库同步策略，把星辰的仓库档案按修改时间增量拉到平台层，供下游消费方按需调用，既不影响源系统写入，又能让下游拿到一份相对新鲜的主数据视图。

数据流向与字段映射

整条链路是单向拉取：源系统金蝶云星辰（接口 /jdy/v2/bd/store）→ 中间层 Qeasy 集成平台 → 目标平台（空写入，作为数据落地区）。

关键字段对照如下：

目标端 metadata 标注为「写入空操作」，意思是这一策略只负责把数据稳定地拉进平台层暂存，不直接回写源系统，由后续策略按需消费。

在轻易云上如何配置

在轻易云集成平台里，这条策略配置上需要注意几个点：

1. 源端连接器：选择金蝶云星辰 V2 的官方连接器，平台标识按实际租户配置；请求方式 GET，effect=QUERY，开启 autoFillResponse，让分页与时间区间变量自动注入。
2. 时间窗变量：modify_start_time 绑定 {{LAST_SYNC_TIME}}000、modify_end_time 绑定 {{CURRENT_TIME}}000。毫秒级时间戳一定要乘 1000，否则源系统会按秒解析，导致查询窗口错位——这是我们现场踩过最常见的坑。
3. 目标端空写入：target 选择平台自身（datahub），API 描述写「写入空操作」，effect=EXECUTE，idCheck=true。该配置不写业务数据，只让平台把拉取结果纳入自身调度台账，便于后续策略引用。
4. 编码映射集中管理：仓库编码作为下游唯一键，轻易云常见的做法是把映射表放在平台层的「编码映射」模块维护，而不是散落在每个策略里，避免后期一处改动、多处失同步。

实施步骤

我们把这条策略上线拆成三步：

• 第一步：增量起点对齐。先做一次全量回灌：把 modify_start_time 设为一个很早的时间戳（例如 0），跑一次历史补齐，让平台层仓库档案与源系统对账一致；之后再切到按修改时间增量。
• 第二步：调度频率设定。源素材里 crontab 写作 59 2 * * *，也就是每天凌晨 2:59 跑一次。仓库主数据变更频率不高，日级增量足以覆盖大多数零售/制造场景；如果客户在促销期临时新增仓库，建议临时调高频率，事后再回落。
• 第三步：分阶段上线。先在测试租户空跑一周，观察空跑日志中拉取到的仓库数量、修改时间分布是否与源系统账表相符；确认无误后再切到生产租户。轻易云客户常见的稳妥做法是「表头表体分阶段」——本策略只跑仓库档案这种表头型主数据，下游消费策略按需触发，避免一次性把库存表体也带进来造成抖动。

踩坑复盘

1. 毫秒时间戳忘了乘 1000。星辰接口要求毫秒级，部分工程师直接传秒级时间戳，源系统当成「1970 年附近」处理，返回空集。这种问题日志里看不到明显报错，只能看到「本次拉取 0 条」。稳妥做法是在平台层的时间变量转换脚本里强制做 *1000。
2. 把仅查询策略当成回写策略用。target 的 effect 写的是 EXECUTE，但 API 是「写入空操作」；曾有同事误以为可以在 target 里塞字段做映射，结果下游策略消费不到。明确「仅查询」语义，把真正消费交给后续策略，是边界最清晰的设计。
3. 增量起点没对齐就上线。直接拿当前时间作为起点，结果历史仓库全部漏掉，下游做单时找不到仓库档案。我们现在的标准动作是：上线前先跑一次全量回灌，落库后再切换增量起点。
4. 分页参数被覆盖。page_size 用变量控制，但部分环境模板里被硬编码成 100，导致数据量大时分页拉不完。配置完务必在轻易云的「请求预览」里实际点一次，看返回条数是否符合预期。
5. 编码映射散落各处。每个消费策略都自己维护一份仓库编码映射，改一次要改 N 个地方。建议在平台层统一收口，轻易云的「编码映射集中管理」就是这个场景的标配。

适用场景与不适用场景

适用：源系统只读开放、有明确的修改时间字段、下游需要按时间增量消费主数据的场景，比如仓库档案、客商档案、物料类别等表头型基础资料。

不适用：需要把仓库数据回写到源系统、或者下游对实时性要求秒级（应改用事件驱动而非定时查询）的场景；同时也不适合作为唯一数据源——一旦源系统接口变更，这条策略会立即失效，必须配套监控告警。