聚水潭销售订单回传钉钉物料样品领用审批单：单号评论同步策略实战
这个策略解决什么问题
一次实际项目里，某零售企业把"物料样品领用"从线下表单搬到了钉钉 OA：申请人在钉钉提单，审批通过后自动在聚水潭生成销售订单并出库。但业务跑通后发现，申请人回到钉钉只能看到一个空洞的审批单，根本不知道订单有没有出库、物流单号是多少、找谁对接。客户最初让我们"把单号同步过去"，看似一句话，做起来却卡在两个细节：一是聚水潭侧生成的是业务单号（so_id / o_id / io_id），钉钉评论接口要的却是审批实例的内部 ID；二是同一笔订单可能被多次修改，重复回传又会刷屏。本策略就是为了在不出错的前提下，把聚水潭的关键单号稳定地回写到对应的钉钉审批单评论里。
数据流向与字段映射
数据流向为 聚水潭 → 中间层（轻易云数据集成平台/Qeasy）→ 钉钉，源端为聚水潭单笔订单查询（/open/orders/single/query），目标端为钉钉审批实例添加评论（topapi/process/instance/comment/add）。
源端关键字段：so_id（线上单号）、o_id（内部单号）、io_id（出库单号）、l_id（物流单号）、io_date（出库时间）、status、modified。
目标端关键字段映射：
| 目标字段 | 源字段/规则 | 映射类型 | 说明 |
|---|---|---|---|
| request.process_instance_id | _mongoQuery [钉钉物料样品领用方案集线器ID] findField=content.id where={"content.extend.business_id":{"$eq":"{{so_id}}"}} | COLLECTION | 按 so_id 反查审批实例 ID |
| request.text | 拼接：线上单号:{{so_id}} 内部单号:{{o_id}} 出库单号:{{io_id}} 物流单号:{{l_id}} 出库时间:{{io_date}} | TRANSFORM | 评论内容 |
| request.file | 不传 | CONSTANT | 可选附件 |
编码映射的核心是 so_id → process_instance_id。源端只有业务单号，目标端评论接口必须传审批实例的内部 ID，因此通过 _mongoQuery 从上游"钉钉物料样品领用==聚水潭销售订单"策略的集线器里，按 extend.business_id 等于 so_id 的条件取出 content.id。如果 extend 结构简单且无特殊字符，也可以改用 _findCollection。
在轻易云上如何配置
在轻易云数据集成平台（Qeasy）的策略编辑页里，我们通常按以下要点配置：
- 源端组件：选择 WebAPI / QUERY 模式，方法 POST，请求体带入
modified_begin、modified_end、page_size、page_index、status。page_size按源端上限设置（材料中给出最大 25，但实际配置需结合供应商文档），idCheck设为 true，autoFillResponse开启。 - 目标端组件：选择 EXECUTE 模式，方法 POST，接口
topapi/process/instance/comment/add，主键取钉钉返回的id。 - 编码映射：在字段映射面板，把
request.process_instance_id的映射类型设为 COLLECTION，填写上面的_mongoQuery表达式；request.text设为 TRANSFORM，写字符串拼接模板。 - 幂等控制：评论接口支持追加，不天然去重；如果业务上不接受重复评论，可以在源端过滤条件里加
status限制，只对已出库订单回传，或者用_function判断io_id为空时跳过本条。
实施步骤
- 建立上下游关联：先确认上游策略（钉钉→聚水潭）已经把
extend.business_id写入聚水潭订单作为so_id，这是本策略反查的前提。 - 配置增量起点：把源端
modified_begin设为{{LAST_SYNC_TIME|datetime}}，modified_end设为{{CURRENT_TIME|datetime}}，间隔控制在 7 天以内。 - 小范围试跑：先以一天内的修改时间为窗口跑一次，观察
_mongoQuery是否能稳定命中审批实例 ID，评论文本是否符合预期。 - 全量触发一次：上线初期手动补一次历史数据，覆盖最近一段时间的出库订单，避免历史审批单全是空白。
- 配置调度：源端 crontab
1-59/9 7-23 * * *（每 9 分钟），目标端 crontab1-59/10 7-23 * * *（每 10 分钟），两端错峰避免挤压。 - 监控与告警：在轻易云上开启日志面板，关注"反查无结果"和"评论写入失败"两类异常，前者通常是
so_id未被上游写入，后者通常是钉钉 access_token 过期。
踩坑复盘
- 典型错误：把 so_id 直接当 process_instance_id 传。钉钉评论接口根本不会报错，但评论会写到一个不存在的实例上，申请人看不到。稳妥的做法是先用
_mongoQuery在测试环境验证能查到结果，再上线。 extend.business_id类型不一致导致匹配失败。上游写入时如果so_id是字符串，而_mongoQuery条件里没加引号，会出现 MongoDB 类型不匹配。条件写成{"$eq":"{{so_id}}"}而不是{"$eq":{{so_id}}}，这种小细节最容易翻车。- 增量窗口超过 7 天被源端拒绝。聚水潭接口明确要求时间间隔不超过 7 天。一旦任务积压或调度中断，恢复后第一轮拉取就会失败。稳妥的做法是设置一个"最长回溯 6 天"的硬限制，宁可丢数据也不要超窗。
- 重复评论刷屏。评论接口支持多次追加，源端订单每次修改都会触发回传。常见应对是只对已出库订单回传，或者用
_function比较modified与上一次回传时间，未变化则跳过。 - 调度错峰没做。源端每 9 分钟、目标端每 10 分钟看似异步，但大量订单并发回写时仍可能撞车。客户现场常见做法是源端 9 分钟、目标端 10 分钟起步，再根据日志调整。
适用场景与不适用场景
适用：审批单驱动销售订单、且需要在审批端回显订单履约单号的场景；订单侧有清晰业务单号且可与审批实例 ID 反查对应。不适用：需要写入钉钉审批表单字段（而非评论）的场景、需要结构化回传多个明细行的场景，以及审批实例已被归档或删除、无法再追加评论的旧数据。