用途:为 Frappe Tweaks 的 Sync Job 框架提供专家级指导,该框架是 DocType 之间基于队列的数据同步系统,用于创建、实现和排查同步作业。
核心概念:Sync Job Type 是定义同步配置的模板(源/目标 DocType、队列、超时、重试设置);Sync Job 是跟踪执行、状态、错误与差异的单项任务实例;Controller 是实现同步逻辑的 Python 模块,分 Bypass 与 Standard 两种模式。
快速开始:创建时进入 Sync Job Type > New,设置名称与 DocType,保存后生成控制器。入队与实现细节见 references/enqueueing.md 和 references/implementation.md。
实现模式有三条路径:单目标(Standard,一对一,实现 get_target_document() 与 update_target_doc())、多目标(Standard,一对多,实现 get_multiple_target_documents() 与 update_target_doc())、Bypass(完全控制,实现 execute())。
状态流转:Pending → Queued → Started → Finished/Failed/Skipped/Relayed/No Target;Canceled 为手动取消(可从 Pending/Queued/Failed 取消);Failed 在 retry_count 小于 max_retries 时自动重试。
常用方法:sync_job.get_context()、get_source_document()、get_trigger_document()、get_target_document();控制标志 insert_enabled/update_enabled/delete_enabled、update_without_changes_enabled、dry_run。
配置项(可逐作业覆盖):Queue(default/short/long)、Timeout 秒、Retry Delay 分钟、Max Retries、Verbose Logging(默认关闭,保留数据快照)、Context 自定义数据、Trigger Tracking 触发追踪。
Dry run 示例:enqueue_sync_job(sync_job_type="SAP Customer Sync", source_document_name="CUST-00001", dry_run=True),仅生成 diff_summary 不保存。
排查:一直 Queued 检查 RQ worker 与队列名;反复失败查看 error_message、文档是否存在与模块路径;无变更可设 update_without_changes_enabled=True;模块未找到确认控制器存在、命名与 bench migrate。
最佳实践:简单映射用 Standard,复杂操作用 Bypass;同步前校验源/目标;目标缺失时返回 target_document_type=None;用 context 传运行时参数;合理设置超时与专用队列;用 frappe.log_error() 记录关键决策;测试重试逻辑。
源码参考:tweaks/utils/sync_job.py、doctype 目录及 boilerplate/controller._py 模板。收费、价格与更多平台支持资料暂未提供。