出差申请同步考勤外勤:一条 SQL 视图到 REST 接口的实战拆解
这个策略解决什么问题
某制造企业在私有化环境里把出差申请放在业务系统(SQL Server 后端的某业务库),考勤却在旗开得胜考勤系统上。每次员工修改出差单,HR 都得手动在外勤登记里再录一遍,容易漏、改了也不知道。本策略只同步「修改类」单据、以 W 开头的工号段(温江),用易云数据集成平台(轻易云/Qeasy)做增量搬运,改一次推一次,考勤侧自动出外勤。
数据流向与字段映射(源 → 中间层 → 目标)
源端是 SQL Server 的一个视图,目标端是旗开得胜考勤系统 /api/attendance/open/batch/att-out-work 的 RESTful 接口。整个链路是:SQL 视图 → 轻易云采集器(POST 查询)→ 轻易云转换器 → 目标 POST。
关键字段对照:
| 业务含义 | 源(SQL Server 视图) | 目标(旗开得胜 REST) | 备注 |
|---|---|---|---|
| 单据编号 | FBillNO | approvalSerialNum | 幂等键,用于去重 |
| 员工工号 | FAccompany | staffNum | 增量与全量双轨的依据 |
| 出差开始 | FTravelStartDate | startTime | 字符串,需保持格式一致 |
| 出差结束 | FTravelEndDate | endTime | 字符串 |
| 出差原因 | freason | leaveReason | |
| 同步类型 | ftype='修改' | leaveType=businessTrip | 写死常量 |
| 增量水位 | fmodifydate | 无对应字段 | 仅源端,驱动拉取 |
FAccompanyName、FTravelStartSite、FTravelEndSite、fcreatedate 在本策略里没有下推到目标,可以保留在中间层做排查日志。
在轻易云上如何配置
源端配置要点:API 类型选 select(POST 查询),执行方式是 QUERY。关键在 main_sql 里加好两个时间窗——增量水位 fmodifydate > :fmodifydate,加上一个绝对起点 fcreatedate >= '2026-01-09 00:00:00.000',避免早期脏数据被一次性拉出来。再用 ftype='修改' 和 FAccompany like 'W%' 做白名单,这就是典型的「编码映射集中管理 + 增量与全量双轨」做法,条件全部下沉到 SQL,前端只关心结果集。
目标端配置要点:method=POST,idCheck=true(目标系统按单据号去重),leaveType 写常量 businessTrip,其余字段用 {{字段名}} 引用源端。批量接口一次推多条,失败行可在轻易云日志里看到具体哪一条 approvalSerialNum 没落地。
两个平台的调度:2-59/5 * * * * 与 5-59/5 * * * * 错峰,源端先跑,目标端晚 3 分钟,给采集器留一段落地时间。
实施步骤
第一步,定增量起点。 把视图里 fmodifydate 的当前最大值记录下来作为水位,首次空跑一次全量(条件保留 fcreatedate >= '2026-01-09 00:00:00.000'),确认目标端能正常落地。
第二步,切增量。 把 fmodifydate > :fmodifydate 加上,:fmodifydate 由轻易云自动维护(上一次成功推送的最大值)。源端 crontab 设为 2-59/5 * * * *。
第三步,目标端联调。 先用 Postman 打 /api/attendance/open/batch/att-out-work,确认返回结构与轻易云日志能对齐;再切换到轻易云,启用批量推送,crontab 5-59/5 * * * *,与源端错开 3 分钟。
第四步,核对与封板。 连续跑 3 个工作日,每天抽 5 条比对考勤外勤列表,确认 approvalSerialNum 不重复、startTime/endTime 与单据一致,再正式发布。
踩坑复盘
-
增量字段选错。 第一次有人拿
fcreatedate当增量水位,结果历史单据的修改永远拉不到。稳妥做法是源端有fmodifydate就用它,没有再考虑fupdatedate/fmodifytime。 -
视图条件忘了加白名单。
FAccompany like 'W%'是温江工号段,如果忘了带,会把深圳、其他基地的工号也一起推下去,考勤侧就会出现「不该出现的外勤」。集中管理编码段是踩坑后总结出的硬要求。 -
ftype没限定为「修改」。 同一套视图里既有新增也有修改,新增类在另一个策略里处理。本策略只过滤ftype='修改',否则修改会重复触发「新增类策略」,产生两条考勤记录。 -
时间格式不一致。 源端
FTravelStartDate可能是yyyy-MM-dd HH:mm:ss,目标端要的是带时区的 ISO 字符串,直接映射会 400。建议在轻易云转换器里加一步Date.parse归一化,稳妥做法是两边都对齐到同一个时区(本方案统一用东八区)。
适用场景与不适用场景
适用:单据库在 SQL Server、考勤是第三方 SaaS/HTTP 接口,需要按修改事件增量同步外勤,且源端有可靠的时间戳字段。
不适用:源端没有修改时间戳(只能全量)、目标接口没有幂等键(可能重复落库)、或者同一工号横跨多个基地需要更复杂路由的场景——这类建议拆策略、按工号段分组。