销售订单写入飞书多维表格：基于轻易云的单策略集成实战

这个策略解决什么问题

销售订单是企业供应链的源头单据，业务团队往往希望在不登录 ERP 的前提下，于协作工具里实时看到订单明细。飞书多维表格（Bitable）天然适合做轻量级业务台账，但 ERP 与飞书天然不互通。轻易云数据集成平台（Qeasy）把金蝶云星空的销售订单按扁平化结构抽取后，写入到指定的多维表格，形成「一张表=一张业务看板」。该策略特别适合需要把订单数据脱敏后供销售、运营、客服查阅的场景。

数据流向与字段映射（源 → 中间层 → 目标）

数据流向：金蝶云星空 → 轻易云集成平台 → 飞书多维表格。源端通过 executeBillQuery 查询 SAL_SaleOrder，返回扁平化结果（一行=主表+一条明细）；中间层由 Qeasy 承载映射与转换；目标端调用 Bitable 的 /open-apis/bitable/v1/apps/:app_token/tables/:table_id/records 写入单条记录。

主表与明细在同一行落地，无需在集成层做分组聚合。每条记录的 FSaleOrderEntry_FEntryID 作为行级主键，用于去重与更新判定。

在轻易云上如何配置

源端选金蝶云星空，API 选 executeBillQuery，表单 ID 写 SAL_SaleOrder，主键 FBillNo，行键 FSaleOrderEntry_FEntryID。目标端选飞书，API 选 Bitable 记录写入路径，类型 RESTful，效果 EXECUTE。

编码映射建议集中管理：客户、销售组织、销售部门、物料、单据类型这些基础资料字段，源端用什么编码，目标端就用什么编码，不在中间层做翻译——这是轻易云客户常见的「编码透传、集中维护」模式。若 Bitable 需要展示客户名称、物料规格，再通过 _findCollection 联查主数据方案补一列「显示名」，原编码列保留，方便后续对账。

日期字段统一使用 {{FDate|datetime}}、{{FDeliveryDate|datetime}} 之类的格式转换，避免 Bitable 把它当成纯文本。状态与是否赠品用 CASE...END 或 _function 条件分支映射为可读文案。

实施步骤

第一阶段，确定增量起点。源端过滤条件写 FCreateDate>='{{LAST_SYNC_TIME|datetime}}'，初始值设为项目上线前一天，把历史数据先做一次性全量补齐。

第二阶段，触发全量。建议先在测试环境跑一次不带过滤条件的全量回灌，确认 Bitable 容量与字段类型匹配，特别是数字、日期、文本三类不要串列。全量通过后再切回增量过滤。

第三阶段，调度频率。源端定时 0 */3 * * *（每 3 小时整点），目标端定时 10 */3 * * *（每 3 小时过 10 分），两端错峰避免写入时被源端抽取阻塞。日常运维只看 Qeasy 的运行日志与失败重试即可。

如果后期出现业务部门要求「实时性更高」，可以单独把这条策略的频率调到 30 分钟一次，但务必先评估源端 API 限流。

踩坑复盘

1. 扁平化结构误读：executeBillQuery 返回的是「主表+一行明细」的合并结构，并不是嵌套数组。有人按主表-明细两层去循环，结果出现「分录重复 3 倍」的典型错误。稳妥做法是直接逐行映射，不做聚合。
2. 行级主键漏配：只用 FBillNo 当主键，当同一订单多行明细时会出现覆盖更新丢失。FSaleOrderEntry_FEntryID 必须作为行级唯一标识同步到 Bitable。
3. 编码与名称混用：把客户编码直接换成客户名称后，无法追溯源端编码，一旦主数据变更，Bitable 无法对账。建议编码与显示名分两列，编码列做透传。
4. 日期类型不匹配：源端长整型时间戳不经过 |datetime 转换直接写入，Bitable 会存为文本字符串，无法做筛选。
5. Bitable 字段命名带空格：源端字段名规范，但 Bitable 配列时随手写了「单据 编号」，映射表达式里也要原样保留空格，否则会静默失败。建议提前在 Bitable 端把列名规范化。

适用场景与不适用场景

适用：销售团队需要轻量台账看板、订单数据需要脱敏后跨部门共享、不希望业务人员直接登录 ERP 的场景。不适用：需要严格事务回写 ERP、订单状态双向同步、或者 Bitable 不支持的高精度数值核算场景——后者建议走标准的业务系统集成而非多维表格。