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

レビューチェックリスト

• 識別キーが安定しており、文書化されています。
• 同期時の書き込みが冪等です。
• チェックポイントの更新が安全です。
• バックフィル／リプレイの動作が定義されています。
• 部分的な失敗を確認でき、修復できます。
• テストで、重複入力、順不同の入力、フィールドの欠落、再試行、再開をカバーしています。