crm-sync

/digital-marketing-pro:crm-sync

スクリプトの場所。 ホストが ${CLAUDE_PLUGIN_ROOT} を設定していない場合、スクリプトはこのプラグインの scripts/ フォルダー内にあり、skills/ と同じ階層にあります。Python 3.10 以降で実行してください。python を使用し、見つからない場合は python3 を使用します（macOS、多くの Linux システム）。

目的

ブランドに接続された CRM プラットフォームとの間でマーケティングデータを同期します。自動フィールドマッピング、重複排除、コンプライアンスチェックを行いながら、連絡先の作成、取引の更新、キャンペーンとの関連付けを処理します。Salesforce、HubSpot、Zoho、Pipedrive に対応し、双方向同期機能により、手作業でのデータ入力やインポート／エクスポートを行わずに、マーケティングチームと営業チームが単一の信頼できる情報源に基づいて業務を進められます。単発の一括同期と定期的な自動転送の両方を想定して設計されており、エンタープライズグレードのデータガバナンスに必要な完全な監査証跡とロールバック機能を備えています。

重複排除、コンプライアンス検証、監査ログ記録が必要な場合は、手動の CSV インポートではなく、このコマンドを使用してください。スコアリングを伴うリード専用のインポートには、代わりに /digital-marketing-pro:lead-import を使用してください。

実行ゲート（必須 — 省略不可）

1. 稼働中のシステムに触れる前に、受信者／費用／変更／コンプライアンスを含む完全なプレビューを 実行サマリー として提示します。
2. ユーザーが yes（または同等の明示的な承認）を入力する必要があります。それ以外の入力（曖昧、暗黙的、部分的、または承認なし）は、すべて実行をキャンセルします。
3. 曖昧な入力で処理を進めてはいけません。失敗した実行を自動で再試行してはいけません。再実行の前に、人による確認が必要です。
4. ユーザーが yes を入力した後に限り、次のコマンドを記録します。python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"crm-sync","platform":"<platform>","content_summary":"<one line from the Execution Summary>","risk_level":"<tier>"}' を実行し、続けて python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action approve --id {approval_id} を実行します。どちらかのコマンドでエラーが発生した場合は、停止してエラーを報告してください。別のツールで回避してはいけません。この記録は、このアクションで承認手順が実行されたことを証明しますが、誰が yes を入力したかは証明できません。
5. 実行します。connector_executor.py を通じて送信する書き込みには --approval-id が必要で、一致する未使用かつ有効期限内の記録がある場合にのみ実行されます（/digital-marketing-pro:execute-action を参照）。接続された MCP サーバーのツールを通じた書き込みは、このコードチェックの対象外です。入力された yes と、ホストの許可プロンプトに依存します。その後、python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action mark-executed --id {approval_id} --data '{"execution_result":"success"}' を実行します（または failure を指定します）。

必須入力項目

ユーザーは次の情報を指定する必要があります（または入力を促されます）。

• 同期タイプ：同期する対象 — コンタクト、取引、キャンペーン、または単一の操作で複数のオブジェクトタイプを組み合わせたもの
• データソース：データの取得元 — CSV ファイルのパス、JSON 配列、手動入力、または別の接続済み MCP（例：Google Sheets、メールプラットフォーム、広告プラットフォーム）からのデータ
• 対象 CRM プラットフォーム：Salesforce、HubSpot、Zoho、または Pipedrive — 該当する場合は具体的なオブジェクトタイプ（例：Salesforce のリードとコンタクト、HubSpot のコンタクトと会社）
• 同期方向：一方向のプッシュ（マーケティングから CRM）、一方向のプル（CRM からマーケティング）、または競合解決の優先設定（データソースを優先、CRM を優先、または最終更新日時が新しい方を優先）を指定した双方向のマージ
• フィールドマッピングの上書き（任意）：デフォルトのフィールドマッピングが CRM のスキーマに合わない場合のカスタムマッピング — 例：「company_name」を Salesforce の「Account Name」に、「phone_mobile」を「MobilePhone」にマッピング
• 重複排除戦略：メールアドレス、電話番号、CRM ID、または複合キーで照合 — 既存レコードを更新するか、重複をスキップするか、両方のデータソースのフィールドをマージするか
• 同意とコンプライアンス要件：同期前に GDPR の同意フィールド、オプトイン状態、またはデータ処理の法的根拠を検証する必要があるか — 該当する市場の規制
• レコードフィルター（任意）：同期するレコードを絞り込む条件 — 日付範囲、セグメントへの所属、ソースキャンペーン、ライフサイクルのステータス、またはカスタムフィールドの値
• バッチサイズの設定（任意）：API のバッチあたりのレコード数 — ロールバックの安全性を高めるには小さく、大量同期の速度を優先するには大きく設定
• 通知設定：新しいコンタクトや取引がパイプラインに同期されたとき、営業担当者に通知するか — 通知する場合はチャネル（CRM 通知、メール、Slack）
• 関連付けの設定：同期したコンタクトを CRM 内の既存のアカウント、取引、またはキャンペーンに関連付けるか — 照合に使用するキー（ドメイン、アカウント名、取引 ID）
• タグまたはリストの割り当て（任意）：同期したレコードに適用するタグ、リスト、またはキャンペーンへの登録 — 後続のセグメンテーションとレポートのアトリビューション用
• エラー処理の設定：個々のレコードの処理に失敗した場合の対応 — スキップして続行する（失敗を記録して後で対応）、同期全体を停止する（完了済みのレコードをロールバック）、または失敗したレコードを隔離して手動で確認する
• 同期スケジュール（任意）：1 回限りの同期にするか、繰り返し実行する同期テンプレートとして保存するか — 繰り返し実行する場合は頻度（1 時間ごと、毎日、毎週）と、前回の実行以降に変更されたレコードのみを同期する（増分）か、一致するすべてのレコードを同期する（全件）かを指定

プロセス

1. ブランドコンテキストを読み込む: ~/.claude-marketing/brands/_active-brand.json を読み込み、アクティブなスラッグを確認してから、~/.claude-marketing/brands/{slug}/profile.json を読み込みます。ブランドのトーン、対象市場のコンプライアンスルール（skills/context-engine/compliance-rules.md）、業界コンテキストを適用します。ガイドラインも確認してください。~/.claude-marketing/brands/{slug}/guidelines/_manifest.json がある場合は、制限事項と関連するカテゴリファイルを読み込みます。~/.claude-marketing/sops/ にある代理店の SOP も確認します。ブランドが存在しない場合は、「先にブランドを設定しますか（/digital-marketing-pro:brand-setup）？」と尋ねるか、デフォルト設定で続行します。
2. 接続済み CRM の状態を確認する: python "${CLAUDE_PLUGIN_ROOT}/scripts/crm-sync.py" --brand {slug} --action get-crm-status を実行し、プラットフォーム接続、API 認証情報、レート制限の余裕、利用可能なオブジェクトを確認します。CRM が接続されていない場合は、CRM MCP 統合の設定をユーザーに案内し、プラットフォーム固有のセットアップ手順を提示します。
3. 入力データを検証する: ソースデータを解析し、必須フィールドを検証します。メール形式（RFC 5322）、電話番号の正規化（E.164）、必須フィールドの有無、データ型の一貫性、文字エンコーディングを確認します。無効なレコードには具体的なエラー理由を示し、有効なデータセットから分離します。
4. フィールドを CRM スキーマにマッピングする: skills/context-engine/crm-integration-guide.md を参照し、プラットフォームごとの標準フィールドマッピングを確認します。一致するフィールド名を自動でマッピングし、ユーザーによる上書きを適用し、マッピングされていないソースフィールドを特定して、ソースとのマッピングがない必須 CRM フィールドにフラグを付けます。続行前に、フィールドマッピングの全体表を提示して確認を求めます。
5. 重複を確認する: python "${CLAUDE_PLUGIN_ROOT}/scripts/crm-sync.py" --brand {slug} --action check-dedup --data '{"email":"[email protected]","phone":"...","name":"...","company":"..."}' を実行します。このスクリプトは、email を必須とし（phone、name、company は任意）、1 回の呼び出しにつき 1 件の連絡先辞書を受け取ります。大量の重複チェックを行う場合は、レコードごとに繰り返し実行します。完全一致、あいまい一致（名前とドメインのレーベンシュタイン距離）、新規レコードを特定します。レコードごとに推奨アクション（作成、更新、スキップ、統合）を含む重複チェック結果を提示します。
6. コンプライアンス要件を検証する: ブランドの対象市場に適用されるコンプライアンスルールに照らして、同意フィールド、オプトインの状態、データ処理の法的根拠を確認します。必要な同意がないレコードや、データ保持ポリシーに違反するレコードにフラグを付けます。GDPR 対象市場では、レコードごとに法的根拠が記録されていることを確認します。
7. CRM 用のペイロードを準備する: 検証および重複排除済みのレコードを、プラットフォーム固有の API ペイロードに変換します。正しいフィールド名、データ型、選択リストの値、関連付け参照（連絡先とアカウントの紐付けなど）、テリトリーまたはラウンドロビンルールに基づく担当者の割り当てを設定します。
8. 承認ゲートを設ける: リスクレベルを評価します。100 件未満は中、100 件以上は高とします。レコード総数、作成／更新／スキップの内訳、重複チェック結果、フィールドマッピングの概要、コンプライアンス状況、対応が必要な検証警告を示す同期プレビューを提示します。
9. 承認後、CRM MCP 経由で同期を実行する: プラットフォームの MCP を通じて、バッチリクエストでペイロードを対象 CRM に送信します。レート制限には指数バックオフで対処し、プラットフォームに到達しなかったことが確実な書き込み（接続拒否、DNS 障害、429 レート制限による拒否）のみ再試行します。タイムアウトまたは応答の消失が発生した場合は、まずプラットフォーム上で（メールまたは外部 ID を使って）レコードを検索し、不足しているものだけを再送します。各レコードの結果（ID を付与して作成、変更されたフィールドとともに更新、理由を添えてスキップ、エラーコードとともに失敗）を記録します。
10. レコード数とデータの整合性を確認する: 同期後に CRM を照会し、同期されたレコード数が予想合計と一致することを確認します。ランダムに 5 件を抽出し、フィールド値が正しく転送されたことをスポットチェックします。件数の不一致やデータの食い違いがあれば、直ちに調査できるようフラグを付けます。
11. 関連付けとタグを適用する: 同期されたレコードについて、関連付けを実行します。ドメインの一致に基づいて連絡先をアカウントに紐付け、メールアドレスを使って連絡先を商談に関連付け、キャンペーンメンバーシップを適用します。ユーザーが指定したタグとリストへの割り当てを追加し、後続のセグメンテーションに利用できるようにします。
12. ロールバックマニフェストを生成する: 作成または変更されたすべてのレコード ID と、保存済みの変更前のフィールド値を記載した、元に戻せる変更マニフェストを作成します。同期後にデータ品質の問題が発生した場合に、CRM 内で対象を絞ったロールバックを可能にします。
13. 結果を記録して通知する: 同期実行の詳細（タイムスタンプ、レコード数、フィールドマッピング、エラー、作成された関連付け、所要時間）を ~/.claude-marketing/brands/{slug}/logs/crm-sync-log.json に記録します。通知設定がある場合は、パイプラインに新しいレコードが追加されたことを関係する営業担当者に通知します。

出力

以下を含む、構造化された CRM 同期レポートです。

• 同期の概要：処理したレコードの合計数と内訳 — 作成、更新、スキップ（重複）、失敗の件数と割合、および予想合計との比較
• 重複排除レポート：検出された重複レコードと、各重複ペアの照合タイプ（完全一致／あいまい一致）、使用した照合フィールド、信頼度スコア、実行した処理（更新、スキップ、または統合）
• フィールドマッピング表：使用したソースから CRM への完全なフィールドマッピング。自動マッピングされたフィールド、ユーザーによる上書き、マッピングされていないソースフィールド、および必須 CRM フィールドに適用されたデフォルト値を含みます
• コンプライアンス監査：同意の欠落、オプトインの不足、またはデータ処理の法的根拠に関する問題があるとしてフラグ付けされたレコード。各レコードの是正案と、該当する規制も記載します
• 検証エラーレポート：無効なレコードと、フィールド単位の具体的なエラー（不正なメールアドレス、必須フィールドの欠落、データ型の不一致、エンコードの問題）および修正案
• 実行ログ：すべての API 呼び出しを記録したタイムスタンプ付きログ。バッチ番号、バッチごとのレコード数、応答ステータス、再試行（プラットフォームに到達しなかったことが確実な書き込みに限る）、レート制限による一時停止、バッチごとの処理時間を含みます
• ロールバック参照情報：この同期で作成または変更されたレコード ID と以前のフィールド値。同期後に問題が見つかった場合に、対象を絞ったロールバックを実行できます
• データ整合性の検証：同期後のスポットチェック結果 — ソースと CRM の間で無作為に抽出した 5 件のレコードを比較し、マッピングされたすべてのフィールドの正確性を確認します
• 関連付けの概要：アカウントにリンクされた連絡先、キャンペーンに関連付けられた案件、および対象レコードの欠落によって失敗した関連付け。手動で解決する手順も記載します
• パフォーマンス指標：同期のスループット（1 秒あたりのレコード数）、消費した API 呼び出しの合計数、レート制限の利用率、および同規模の次回同期にかかる推定時間
• タグとリストの割り当て確認：適用したタグ、割り当てたリスト、作成したキャンペーンメンバーシップ。タグ／リストごとの件数と、割り当てに失敗したものも記載します
• 競合解決ログ（双方向同期のみ）：双方向同期で発生した、フィールド単位のすべての競合。ソース値、CRM 値、適用した解決方法（ソースを優先、CRM を優先、または最新の値を優先）、および手動確認が必要な競合を記録します
• 次回の同期に関する推奨事項：失敗したレコードの再同期、定期同期のスケジュール設定、未マッピングフィールドの整理、フィールドマッピングのデフォルト値の更新、自動双方向同期の設定など、推奨するフォローアップ対応

使用エージェント

• crm-manager — フィールドマッピング、重複排除ロジック、データ検証、CRM スキーマの解決、コンプライアンス確認、ペイロードの準備、担当者の割り当て、関連付け、および同期実行の管理
• execution-coordinator — 承認ワークフロー、リスク評価、バッチ実行のオーケストレーション、レート制限の処理、プラットフォームに到達しなかったことが確実な書き込みに限った再試行、ロールバック用マニフェストの生成、通知の配信、および実行ログの記録