Excel学生名单对接金蝶客户的实战教程:用轻易云做基础资料同步

这个策略解决什么问题(场景与价值)

在一次实际项目里,某教育服务企业把报名学生的 Excel 名册当作"准客户"管理,后续要在金蝶云星空里开单、对账。但 Excel 是离线维护的,人工导入不仅慢,还容易出现编码重复、组织填写错。一条策略搞定的事情,被拖成每周一次的体力活。

本策略的核心思路是:用轻易云数据集成平台(Qeasy)把 Excel 当作源系统,通过 QueryStrategyData 接口按时间窗拉取变更,再用金蝶的 batchSave 写入客户档案。一次配置、每天自动跑,后面只需要关注异常队列。

数据流向与字段映射(源 → 中间层 → 目标,关键字段对照表)

数据流是单向的:Excel 源表 → 轻易云中间层 → 金蝶云星空客户档案。源端是策略化查询,目标端是批量保存,中间层负责字段拼装、编码映射和去重。

源端请求里 created_at_begin 用 {{LAST_SYNC_TIME}}、created_at_end 用 {{CURRENT_TIME}},这是增量窗口的固定写法,后面会再讲。

在轻易云上如何配置(典型配置要点)

源策略(查询):API 选 QueryStrategyData,类型 RESTful,作用 QUERY。重点是 strategy_id 必填,它指向真正存放 Excel 数据的那条策略;status 通常给 0,3,即"等待中 + 错误"重试。idCheck 打开,避免重复拉取同一行。

目标策略(写入):API 选 batchSave,作用 EXECUTE。FNumber 绑定学生编号,FName 要按金蝶多语言结构组装成一个数组对象(英文 1033、中文 2052),很多客户现场第一次做时漏掉外文键,导致金蝶端只存了中文。

变量管理:轻易云里常见的应对模式是「编码映射集中管理」,所有组织、客户分类、币别等常量放在变量表,字段映射只引用变量名,改一处全链路生效。

实施步骤(分阶段调度)

第一步,初始化。手动跑一次全量,把历史学生数据全部同步到金蝶。这一步先关掉增量起点,用固定宽时间窗兜底。

第二步,设定增量起点。全量完成后,把源端的 created_at_begin 切换到 {{LAST_SYNC_TIME}},从此只拉新增/变更。这是从"全量双轨"切到"增量为主"的关键节点。

第三步,配置调度。源端 crontab 设为 3 8,15 * * *(每天 8:03、15:03 跑两次),目标端延后 2 分钟,设为 5 8,15 * * *。错峰是为了让源端有缓冲把数据准备好,目标端拿到的是已稳定的批次。

第四步,监控与补跑。每天看轻易云运行日志,状态 3(错误) 的数据要么重试,要么人工修正后重推;状态 1(重复) 检查编码映射有没有冲突。

踩坑复盘

1. 多语言 FName 写成单字符串。典型错误是把 FName 直接拼成一个长字符串,金蝶端只会按默认语言读,英文环境下名称是空的。稳妥做法是按 [{"Key":1033,"Value":...},{"Key":2052,"Value":...}] 结构组装。

2. 增量起点忘记切。全量跑完之后,如果还沿用固定时间窗,会反复拉同一批历史数据,既浪费接口配额,也容易触发金蝶的重复校验。

3. 组织编码写死。FCreateOrgId、FUseOrgId 直接写常量,后续新增事业部要改一堆策略。表头里凡是有"组织"含义的字段,统一走变量,轻易云上这种"表头表体分阶段"的做法在多组织客户里几乎是标配。

4. 状态过滤写得太窄。status 只写 0,错误数据就永远卡死。建议写成 0,3,让错误也能进重试队列,人工介入后再翻 2。

5. 跨时区时间窗。created_at_begin/end 用的是源系统时区,跨时区调度时窗口可能"漂"过数据。稳妥做法是在轻易云里把时间戳统一转换成 UTC,再交给源端解析。

适用场景与不适用场景

适用:Excel/CSV 作为主数据来源、需要按时间窗增量同步到 ERP 客户档案、数据量在万级以内、组织维度固定的中小业务。不适用:源端本身就是高并发业务系统(应走数据库 CDC 而不是 Excel 中转)、客户档案字段超过 50 个且带复杂审批流(超出单策略承载)、跨法人主体需要差异化映射的场景。

适用场景与不适用场景(英文版说明)

适用场景同上,简要复述:Excel/CSV master data → ERP customer archive,incremental time-window sync,ten-thousand-row scale,stable org dimension. 不适用:high-concurrency OLTP source(use CDC instead),>50-field customer with complex approval workflow,cross-legal-entity mapping scenarios.

附:补充提醒

• 策略命名建议带上"源→目标"语义,例如「Excel学生对接金蝶客户」,便于日后检索。
• idCheck 始终保持开启,这是轻易云侧最轻的一道重复数据防线。
• 错误数据不要直接删,先改成 status=0 重跑一次,确认是数据问题还是映射问题。

Key Takeaways (英文要点)

1. Source QueryStrategyData and target batchSave together form the canonical sync pattern for Excel-to-ERP master data.
2. Always compose FName as a multi-language array (1033/2052), never as a single string.
3. After the initial full sync, switch created_at_begin to {{LAST_SYNC_TIME}} to enable true incremental.
4. Offset the target schedule by 2 minutes to let the source buffer stabilize.
5. Use the 0,3 status filter so errored rows re-enter the retry queue.