星辰-查询商品信息:基于轻易云的商品主数据抽取策略实战

这个策略解决什么问题(场景与价值)

在做聚水潭与金蝶云星辰的供应链集成时,商品主数据是所有后续单据(销售订单、采购入库、库存)流转的基础。一次实际项目中,我们遇到的问题是:星辰侧的商品档案频繁被门店运营人员改规格、改名称、改辅助属性,而下游分销、电商与财务核算都依赖这套编码体系。如果只靠人工维护,3 个月后两边数字就对不上,SKU 数量差异能拉到上百个。

这条「星辰-查询商品信息」策略的核心价值,是把星辰作为商品主数据的权威源,按时间窗口把变更增量拉到轻易云数据集成平台(Qeasy)做集中中转,再由后续策略分发到聚水潭与各业务系统。它解决的是「谁先动、谁为准、谁兜底」的问题。

数据流向与字段映射

数据流向很清晰:金蝶云星辰 → 轻易云数据集成平台(Qeasy),单向上行。

典型字段对照:number ↔ 商品编码;name ↔ 商品名称;category ↔ 分类;unit ↔ 基本计量单位;price ↔ 参考售价;modify_time ↔ 最后修改时间。

在轻易云上如何配置

在轻易云数据集成平台(Qeasy)里,我们把这套配置分为三块:

1. 源端接入:平台选择 Kingdee.YXC,请求方式 GET,作用 QUERY。modify_start_time 填 {{LAST_SYNC_TIME}}000,modify_end_time 填 {{CURRENT_TIME}}000。这里的占位符是轻易云的运行时变量,每次调度自动替换为上一次同步时间和当前时间。
2. 分页与明细:page_size 设为 20,idCheck 关闭,buildModel 关闭,autoFillResponse 开启。当返回分页数据后,otherRequest.detailAPI 指向 /jdy/v2/bd/material_detail,用主键回查明细,把规格、辅助单位、图片等信息补齐。
3. 目标端落库:平台选择 datahub(轻易云),接口标为「写入空操作」,作用 EXECUTE,POST 方式,number=0、id=0,idCheck=true。这一段看起来奇怪,但它是轻易云常见的编码映射集中管理模式:先占位,真正落到目标系统的动作交给后续分发策略(比如「轻易云→星辰-物料」回写)统一处理,避免同一份主数据在多个节点重复写入。

我们给轻易云客户讲解时,经常强调一个原则:这条策略只负责「准」,不负责「全」,后续由依赖它的策略来保证落库完整性。

实施步骤

我们建议分三阶段推进,也是轻易云客户常见的「增量与全量双轨」做法:

• 第一步:增量起点校准。上线前,在星辰侧先做一次人工全量导出,确认商品总数。再配置轻易云策略,跑一次空窗拉取(开始/结束时间都填历史较早时刻),把存量全部初始化进轻易云主数据池。这一步不能省略,否则增量起点会是「部署当天」,之前的商品全部漏掉。
• 第二步:全量触发与对账。启用调度 */10 7-22 * * *(源端每 10 分钟一次),目标端 */11 7-22 * * *,源与目标错开 1 分钟,避免瞬时资源争抢。跑 24 小时,把全量数据彻底刷齐,然后做一次跨系统对账报表,确认编码、名称、分类一致。
• 第三步:稳态增量。对账完成后,策略进入稳态——只拉 modify_time 在窗口内的增量变更。一旦业务方反馈「某个商品没同步过来」,第一时间看 LAST_SYNC_TIME 是否回退了,再看星辰侧 modify_time 是否被人工回写覆盖。

踩坑复盘

1. 时间窗起点搞错单位。星辰接口要求毫秒级时间戳,但很多工程师习惯传秒级,导致要么全量重复拉取、要么窗口被吃掉 1000 倍。这里稳妥的做法是统一在轻易云占位符里加 000 后缀。
2. page_size 太大触发限流。星辰侧默认上限并不公开,我们踩过把 page_size 调到 200 后被限流的坑。20 是保守值,轻易云客户里也普遍采用这个值。
3. modify_time 被回写覆盖。运营人员批量改价时,有时会把修改时间戳改回历史值,导致增量漏拉。建议在轻易云里加一道主数据版本号兜底:比对拉到的内容与轻易云侧已有内容,真的不一致才更新。
4. 明细接口没跑。主数据只取列表,规格、辅助属性全部丢失,下游分销系统无法用。detailAPI 一定要配置,并且按主键去重,避免同一商品多次回查。
5. 表头表体分阶段做错。商品同步应该先做表头(主信息),再做表体(规格、辅助属性、多单位),不要混在一个策略里。轻易云里常见的应对模式就是分两条策略串行,第二条依赖第一条的 id,通过 depends_on 字段配置。

适用场景与不适用场景

适用:星辰作为商品主数据权威源,下游需要按增量消费;SKU 体量在十万级以内;有 7-22 点的高频变更窗口。不适用:星辰只是分销末端,真正的商品主数据在 ERP 或 PIM;需要实时(秒级)同步库存;跨法人、跨账套的多组织同步。