星辰产品主数据查询策略：把物料同步的第一公里稳稳走通

这个策略解决什么问题

某制造企业的 ERP 用金蝶云星辰、MES 端用黑湖小工单，物料主数据要保持一致。第一公里往往是物料查询接口：星辰侧物料是后续所有单据同步（生产任务单、销售订单、库存）的基准。如果拉取环节没设计好，下游每一条链都会跟着抖。

「星辰产品仅查询」策略的核心价值，就是把物料数据稳定、可重放地从星辰侧抽取到中间层。源端只负责查、目标端执行一次空写（写空操作），目的是让轻易云数据集成平台能够挂接后续写入逻辑，并保留完整的查询结果与可观测性。这是「基础资料同步」链路里最常见的起手式。

数据流向：金蝶云星辰 V2（源，类型为 QUERY）→ 轻易云集成平台（中间层）→ 黑湖小工单（目标）。本策略当前仅完成「源 → 中间层」的拉取，目标端写入逻辑由其他策略承接。

关键请求参数对照：

源 API 为 GET /jdy/v2/bd/material，主键字段为 number（编码）与 id（内码）。目标端在轻易云侧配置为一个「写入空操作」的 WebAPI 占位，便于未来挂接真正的下游写入。

源端配置要点：接入「金蝶云星辰 V2」适配器，API 选择 /jdy/v2/bd/material，请求方式 GET。把 enable 固定为 1，避免每次拉全量禁用物料。分页参数沿用轻易云内置的 page 分页器即可，单页大小建议 100–200 条，太大容易被星辰限流。

目标端配置要点：选择「轻易云集成平台」自带的 WebAPI，写入空操作。number 与 id 都填 0，idCheck 置为 true。这里的关键不是写数据，而是把「目标端槽位」占住——后续真正写黑湖物料时，只换这个 WebAPI 的实现，上游拉取链路不用动。

中间层治理：编码映射我们习惯集中放在轻易云的「映射表」里维护，物料编码 → 黑湖物料编码、单位换算、分类映射都走同一张表。这种「编码映射集中管理」的模式，是轻易云客户里最常见的应对方式，改一处全链路生效。

我们建议分三段跑：

第一段，增量起点。在轻易云里把星辰侧最近 7 天的物料拉一遍，对照两边数据，定位编码、单位、规格字段的差异。这一步通常跑两三轮才能把异常物料清掉，是隐形成本最高的一步。

第二段，全量触发。把 create_start_time 置为 0、create_end_time 留空，跑一次完整全量；跑完后立即核对两端编码数量与抽样 50 条的字段一致性。全量往往在业务低峰期（比如凌晨）执行。

第三段，调度频率。源策略的 crontab 建议「0-59/3 7-22 * * *」，即每天 7 点到 22 点每 3 分钟一次。这条策略只读，写入压力为零，频率可以拉高；下游写入策略按业务需要降频即可。这种「增量与全量双轨」的模式，也是轻易云客户最常用的稳态。

enable 不固定。这里容易翻车的是查询参数不写死，每次返回里混进禁用记录，下游写入直接报错。稳妥做法：在轻易云源端把 enable=1 写死，需要查禁用物料时单独再开一条策略。
时间戳单位不一致。星辰接口要的是秒级时间戳，不是毫秒。典型错误是把毫秒直接传过去，结果拉不到任何数据。
分页边界。星辰单页默认不大，但遇到 10 万级物料时，如果只跑一次不重试就会丢尾页。
目标端占位策略忘了挂后续。一旦这个空写策略上线，很容易被当作「已完成」忽略掉，下游物料不同步。需要在轻易云的策略依赖里显式声明「本策略是 X 的前置」。
数据权限开关。isdataperm 默认 false 一旦在某次账号升级后变成 true，会突然只返回部分物料。建议显式传 false 并加监控告警。

适用：物料主数据从 ERP 到 MES/下游系统的首轮接入、需要稳定可重放的查询链路、后续要在此基础上挂接多条写入策略的场景。

不适用：目标系统要求强一致实时写入（应改用变更捕获或消息队列）、单据类业务数据（应走表单同步而非基础资料查询）。