单一策略实战：领星ERP售后退款订单查询接入轻易云集成平台
这个策略解决什么问题
某跨境零售企业的售后退款单原本散落在 ERP 中，财务对账时要手动导出再清洗。我们这次要做的，就是把领星 ERP 的售后退款订单按时间窗口稳定拉到轻易云数据集成平台（Qeasy）上沉淀下来，作为后续退款核销、库存回滚与财务记账的统一数据源。它本身只负责「取数」，不做写入，是典型的 QUERY_ONLY 策略。
数据流向与字段映射
数据从领星 ERP 出发，经过轻易云集成平台的中转层，再落到目标端（本策略中目标端配置为「写入空操作」，实际是占位落库）。整体链路：领星 ERP → 轻易云请求构建器 → 轻易云响应解析层 → 目标占位写入。
关键请求字段对照（源 → 中间层 → 目标）：
| 字段 | 源（领星 API） | 中间层（轻易云） | 目标（占位） |
|---|---|---|---|
| time_type | 时间查询类型（int） | 时间查询类型 | 透传 |
| start_date / end_date | 起始/结束日期（date） | 日期窗口 | 透传 |
| offset / length | 分页偏移与长度（int） | 分页游标 | 透传 |
| after_type | 售后类型筛选 | 售后类型筛选 | 透传 |
| amazon_order_id | 单据编号（number） | 单据编号 | 主键 |
| id | 平台记录主键（id） | 幂等主键 | 主键 |
幂等键采用 id + amazon_order_id 双字段，开启 idCheck，确保重跑不重复落库。
在轻易云上如何配置
策略类型选择 QUERY_ONLY，目标平台指向 datahub（即轻易云自身）。源端填写领星侧的售后列表接口 afterSaleList，POST 方法。请求体使用轻易云的「请求字段绑定」按时间窗口与分页构造；分页策略选「按 length 累加 offset」，直到返回为空翻页结束。
目标端配置为 WebAPI 占位（API 名称为「写入空操作」），method 填 POST，请求/响应均为空结构——它只承接解析后的数据落库，不回写源系统。
注意源端元数据的几个开关：autoFillResponse=true 让响应字段自动回流到字段映射区；buildModel=false 表示不预生成模型，由我们按字段一一映射；idCheck=true 启用幂等。
实施步骤
我们采用「增量起点 + 全量触发 + 调度频率」三段式推进。
第一步：增量起点。上线当天，先用一个小窗口（如最近 7 天）作为起点，避免一次性把历史全量拉过来冲垮下游。这里把 start_date 设为当周第一天，end_date 取执行时刻前一天，time_type 用「按更新时间」。
第二步：全量触发。增量稳定运行一周后，手动补一次历史全量；窗口按月切分（如 2024-01-01 → 2024-01-31），每跑完一个月再切下一段，避免单次响应体过大导致超时。
第三步：调度频率。日常调度按天执行，建议放在业务低峰期。素材里 crontab 写的是 1 1 1 1 1（五字段占位，实际按日运行即可），落地时调整为「每天凌晨 02:30 跑一次」。
踩坑复盘
- 时间窗口要明确语义。time_type=1 是按更新时间还是按退款完成时间，必须和业务对齐。曾经有客户按退款完成时间查，结果「已发起未完成」的退款一直没进来，对账时差出一截。
- 分页长度别贪大。length 设 50 是稳妥做法；调到 200 后偶发接口超时。重跑幂等能救命，所以 idCheck 一定开着。
- amazon_order_id 重复问题。同一退款单在多次状态更新时会出现多条记录，主键必须用领星自增
id，而不是平台单号，否则会被当成同一笔更新掉历史状态。 - 编码映射集中管理。轻易云里把店铺、币种、退款原因等枚举值统一维护在映射表，源字段一改映射就同步生效，避免散落在多个策略里改到漏改。
- 依赖策略顺序。本策略（sequence=B）依赖上游的「查询领星-亚马逊店铺 id」先把店铺维表跑出来，再用维表去过滤退款单，否则会出现「店铺 id 还没拿到就先拉单」的空指针。
适用场景与不适用场景
适用：需要把售后退款明细稳定沉淀到数据中台、后续做退款核销或对账报表；需要按时间窗口增量拉取并保证幂等。不适用：需要把退款单直接回写到业务系统做冲销处理（应配写入型策略）；需要近实时秒级同步（本策略按天调度，时效性是 T+1）。