查询星辰单位信息：聚水潭到金蝶云星辰的计量单位增量同步实战
这个策略解决什么问题
在聚水潭与金蝶云星辰的供应链集成中，计量单位（个、箱、件、千克等）是商品、价格、库存与采购单据的公共底座。我们遇到一个真实诉求：某零售企业上线初期，目标系统的单位档案为空，商品、客户、库存等下游策略都跑不通。「查询星辰单位信息」这一策略的任务只有一个——把目标系统里已有的计量单位档案，按增量时间窗拉回到集成中间层，供后续的「商品同步」「客户同步」做编码与名称映射。
它本身不写入目标系统，只承担「先把两边约定对齐」的职责，是基础资料同步链路里的第一步。
数据流向与字段映射
整体流向为：源系统（金蝶云星辰 V2）→ 集成中间层（轻易云）→ 目标平台（轻易云侧的空操作落地点，用于缓存单位档案供后续策略引用）。
源接口为 WebAPI（GET），调用金蝶云星辰 V2 的计量单位查询接口，分页 + 时间窗增量抓取。下面是关键字段对照：
| 字段名 | 中文含义 | 类型 | 取值 / 说明 |
|---|---|---|---|
| search | 模糊搜索 | string | 可空，用于按名称/编码过滤 |
| pagesize | 每页条数 | string | 固定 100，控制单次返回 |
| page | 当前页 | string | 从 1 起递增，配合分页 |
| modify_start_time | 修改时间-开始 | string | {{LAST_SYNC_TIME}}000，上次同步时间 |
| modify_end_time | 修改时间-结束 | string | {{CURRENT_TIME}}000，本次同步时间 |
| enable | 启用状态 | string | 控制是否只取启用项 |
| number | 编码 | string | 单位的唯一业务编码 |
| id | 系统内 ID | string | 平台主键 |
中间层在轻易云里做两件事：一是把 number 与 id 缓存成一张轻量映射表；二是在后续「商品同步」策略里被引用，把聚水潭的单位值换算成星辰可识别的 number。
在轻易云上如何配置
我们在轻易云数据集成平台（Qeasy）里给这条策略建一个独立任务，源平台选金蝶云星辰 V2，目标平台选轻易云本身的「写入空操作」占位。配置要点如下：
- 源端接口：API 选
/jdy/v2/bd/measure_unit，方法 GET，效果 QUERY。开启autoFillResponse，让平台自动解析返回结构。 - 请求参数：
pagesize写死 100；page由轻易云分页器自动维护；时间窗用{{LAST_SYNC_TIME}}与{{CURRENT_TIME}}两个内置变量拼出闭区间。 - 目标端：API 选「写入空操作」，方法 POST。这是一种常见的「中间层缓存」做法——不写回源，也不直接落目标，而是把数据先沉淀到轻易云侧，供依赖它的下游策略查询。
- 主键设置：
number作为业务主键，id作为系统主键；idCheck关闭，避免因源端返回空 ID 导致整批失败。 - 响应映射：在轻易云的字段映射面板里，把
number、name、id等字段一一对应到中间表结构，命名保持与目标系统字典一致，方便后续策略直接引用。
实施步骤
我们把上线分成三个阶段，遵循「编码映射集中管理」的工程惯例：
阶段一：全量触发，作为基线。 首次运行时，把 modify_start_time 设为足够早的时间（比如 1970-01-01），modify_end_time 设为当前时间，拉一次全量，生成星辰单位的初始映射表。这一步一般手动触发，跑完后核对两侧单位数是否对得上。
阶段二：切到增量，按调度频率运行。 全量成功后，策略切到正常调度：*/10 7-21 * * *，也就是每天 7 点到 21 点，每 10 分钟一次。把营业时间窗口拉满，既不会漏单，也避开了凌晨的批量结算高峰。LAST_SYNC_TIME 由轻易云自动维护，每次成功执行后落盘。
阶段三：监控与对账。 在轻易云的运行记录里观察「是否有数据」「分页是否走完」「HTTP 状态码」三项。健康情况下，每次 10 分钟窗里返回 0～N 条单位变更，pagesize 100 一般一页就够；如果连续多次返回满页，需要警惕源端是不是在做大批改。
踩坑复盘
-
时间窗写成开区间，漏边界数据。 典型错误是只传
modify_start_time，不传modify_end_time，结果每次只拿到一个时间点的快照。这里稳妥的做法是两端都传，且用毫秒级字符串（末尾补000），与金蝶云星辰 V2 的接口约定保持一致。 -
模糊搜索与时间窗同时使用，导致漏数。
search字段一旦带值，部分接口实现会忽略时间条件。我们的经验是：增量阶段不传search，靠时间窗驱动；只有在排查历史数据时再用search走临时查询。 -
忽略分页边界，最后一页被吃掉。 pagesize=100 时，如果实际返回恰好 100 条，轻易云的分页器会继续翻页直到返回少于 100。这里容易翻车，建议在轻易云里把「翻页直到空页」的策略打开，避免空跑。
-
单位被禁用了还往中间层塞。
enable参数别忘了带。源端禁用某个单位后，下游策略如果还按老映射去写商品，就会报「单位不存在」。我们在轻易云的转换器里加了过滤，停用的单位不进中间表。 -
调度窗口太密，触发源端限流。 一开始我们按
*/5跑，结果上午 10 点源端返回 429。改成*/10且限定 7-21 点后稳定下来。增量同步不是越快越好，要给源端留余量。
适用场景与不适用场景
适用：单位档案变动不频繁、需要为商品/客户等下游策略提供编码映射基线、源端接口支持按修改时间增量拉取的场景。
不适用：单位需要在两侧双向维护、源端不暴露修改时间字段、单位数量极大（百万级）需要走专用主数据平台的场景。