数据聚合写入操作指南

场景与价值

在订单、库存或费用明细等业务数据集成场景中，源系统常返回包含多层数组的单据数据。若直接传输，多条明细可能因接口报文结构、分组边界或目标单据行数限制而无法按预期写入。为此，需要先将多维数组转换为二维明细，再按照业务维度进行分组合并。

轻易云系统集成平台支持在可视化配置中完成上述处理。用户可定义表头分组、表体分组、聚合字段及目标表体名称，从而将多条明细整理为少量目标单据。该方式适合减少明细传输规模、合并相同维度数据，并处理目标单据行数限制等场景。

集成架构与数据流

整体处理流程分为三个阶段。

第一阶段是数据拍扁。源系统返回的多维单据可能同时包含表头、多个明细数组或更深层结构。平台在源平台配置多维数据拍扁规则，将嵌套数组展开为统一的二维明细结构，并为后续分组建立数据基础。

第二阶段是分组合并。用户需要识别能够代表业务单据边界的表头字段，并指定需要继续归并的表体字段。表头分组字段确定单据的归并范围，表体分组字段决定哪些明细行可以合并到同一组中。

第三阶段是目标写入。聚合完成后，平台将结果写入目标平台。目标字段的引用方式需要适应新的数据结构：表头字段直接映射，合并后的表体则通过配置指定的数组键进行引用。

实施要点

分组合并配置的核心对象包括以下参数：

• headerGroup：设置表头分组字段。平台按这些字段识别单据归并范围。
• bodyGroup：设置表体分组字段，用于判断明细行是否进入同一聚合组。
• bodyName：指定合并后表体数据在聚合结果中的数组键名。
• targetBodyName：指定目标单据中的明细体名称。
• bodyMaxLine：限制单个目标明细体的行数。聚合结果超过限制时，平台会按目标表体进行拆分。
• calculate：配置参与聚合计算的字段及表达式。支持 $sum、$avg、$min、$max、$push、$addToSet、$first 和 $last 等表达式。

其中，$sum 用于求和，$avg 用于计算平均值，$min 与 $max 分别取最小值和最大值，$push 将字段值加入数组但不主动去重，$addToSet 会排除重复值，$first 与 $last 则根据资源文档顺序取首条或末条数据。具体选择取决于业务字段含义，不能仅以数据类型判断。

完成配置后，应使用包含相同分组维度、不同明细值以及超过目标行数限制的样本进行验证。重点检查分组边界、累计结果、表体数组键和拆分后的字段映射，避免因维度定义不完整造成不同业务数据被合并。

最佳实践

首先，分组字段应优先选择能够稳定标识业务单据或分类维度的字段，并确认源数据中不存在格式不一致、空值或精度差异。其次，金额、数量等字段在执行 $sum 前应统一单位、精度和舍入规则；平均值和首末值计算还要明确排序依据。

再次，数组聚合字段应谨慎使用 $push 与 $addToSet：需要保留全部值时使用 $push，需要生成去重集合时使用 $addToSet。最后，应在目标字段映射中正确引用 bodyName 指定的数组键，并依据 bodyMaxLine 设计必要的拆分逻辑。

上线前建议通过边界样本验证最大行数处理、空表体处理和重复数据去重规则。若业务上要求一个表头只对应一个目标单据，应确保表头分组条件足以唯一定义该单据；若允许拆单，则需同时明确拆分后表头字段的复制与继承规则。