data-sync-workflows

数据同步工作流

当数据在系统之间流转，且应用必须在重试、部分失败和重复运行时保持正确性，请使用此技能。

设计问题

• 每个字段的事实来源是什么？
• 同步是全量、增量、事件驱动、定时还是手动的？
• 系统之间稳定的身份键是什么？
• 哪个检查点或游标可以证明上一次成功运行停止的位置？
• 操作能否安全重试？
• 部分成功意味着什么？
• 操作人员如何查看哪些内容发生了变化、失败、被跳过或需要修复？

核心设计规则

• 在实现之前定义身份和幂等性。
• 仅在所覆盖范围的数据已持久成功后存储检查点。
• 将获取、规范化、验证、应用和证据记录步骤分开。
• 让每次写入都具备幂等性，或受到确定性冲突规则的保护。
• 规范化之后，避免将外部原始数据带入领域代码。
• 在投入生产使用之前设计回填和重放路径。
• 将删除、缺失记录和墓碑记录视为明确的产品决策。

工作流形态

load checkpoint
fetch external page or range
normalize records
validate records
deduplicate by stable identity
apply idempotent writes
record per-record evidence
advance checkpoint
emit run summary

检查点规则

• 在可用时，使用单调游标、更新时间窗口、序列 ID 或来源系统提供的令牌。
• 纳入足够的元数据，以便恢复时无需重新读取边界不明确的范围。
• 对于时间窗口同步，使用重叠窗口，并按稳定身份去重。
• 绝不要将检查点推进到尚未应用的记录之后。

故障处理

• 将故障分类为可重试、永久性、数据质量、身份验证/配置问题或需要人工决策。
• 单条记录的故障应清晰可见，不要将整个运行折叠成一个笼统错误。
• 对临时基础设施错误进行有界重试。
• 对重复出现的确定性故障停止处理，并保留修复所需的证据。

证据

每次运行都应生成摘要，其中包括：

• 运行 ID
• 来源系统
• 运行前后的检查点
• 获取、创建、更新、跳过和失败的记录数
• 重试次数
• 故障类别
• 详细诊断信息的链接或 ID

审查清单

• 身份键稳定且有文档说明。
• 同步写入具备幂等性。
• 检查点推进安全。
• 已定义回填/重放行为。
• 部分故障清晰可见且可修复。
• 测试涵盖重复输入、乱序输入、字段缺失、重试和恢复。