data-import

/digital-marketing-pro:data-import

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

目的

接続されたあらゆるプラットフォームに構造化データを取り込むための汎用データインポートツールです。CSV、JSON、Google Sheets から CRM システム、メール購読者リスト、オーディエンスセグメント、競合トラッカー、キャンペーン管理ツール、カスタムデータストアにインポートできます。フィールドマッピングの自動提案、データ検証、既存レコードとの重複排除、連絡先データの同意およびコンプライアンス確認、プラットフォーム MCP 経由でのバッチ実行、必要に応じたロールバック手順を含む詳細な結果レポートまで、インポートの全工程に対応します。

実行ゲート（必須 — スキップできません）

1. ライブシステムにアクセスする前に、受信者／費用／変更内容／コンプライアンスを含むプレビュー全体を実行サマリーとして提示します。
2. ユーザーは yes（または同等の明示的な承認）を入力する必要があります。それ以外の入力（曖昧、暗示的、部分的な承認、または承認なし）は、すべて実行をキャンセルします。
3. 曖昧な入力を受けて処理を進めてはいけません。失敗した実行を自動で再試行してはいけません。再実行の前に人による確認が必要です。
4. ユーザーが yes を入力した後に限り、次のコマンドで記録します。python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"data-import","platform":"<platform>","content_summary":"<実行サマリーからの1行>","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 ファイルのファイルパス、または Google Sheets の URL — インポートする生データです。CSV の区切り文字が標準と異なる場合は指定してください。Google Sheets の場合、最初のシート全体でない場合は、シート名と範囲を指定してください。ファイルは現在の環境からアクセスできる必要があります
• インポート先プラットフォーム：データの取り込み先です。CRM（HubSpot、Salesforce）、メールプラットフォーム（Mailchimp、ActiveCampaign、SendGrid）、オーディエンスマネージャー、競合トラッカー、またはカスタムの取り込み先を指定します。対応する MCP サーバーが .mcp.json で接続および設定されている必要があります
• フィールドマッピング：ソース列を取り込み先のフィールドに対応付ける方法です。明示的なマッピング（例：「Company Name」->「company」、「Work Email」->「email」）を指定するか、列名の類似性に基づくシステムの候補を使った自動マッピングを依頼します。マッピングされていない列は確認対象としてフラグが付けられ、必須の取り込み先フィールドがマッピングされていない場合は、解決するまでインポートがブロックされます
• インポートオプション（任意）：重複排除の方法（重複を skip、既存レコードを update、または無条件に create-new。デフォルトは skip）、同意確認のレベル（strict は明示的なオプトインフィールドを必須とし、standard は配信停止フラグを確認し、none は連絡先データ以外に使用）、API 書き込みのバッチサイズ（デフォルトは 100）、実行せずに検証するドライランモード

プロセス

1. ブランドのコンテキストを読み込む：~/.claude-marketing/brands/_active-brand.json を読み込み、有効なスラッグを確認してから、~/.claude-marketing/brands/{slug}/profile.json を読み込みます。対象市場のコンプライアンスルール（skills/context-engine/compliance-rules.md）を適用します。特に、連絡先データのインポートに関する GDPR、CAN-SPAM、CCPA の要件に注意してください。~/.claude-marketing/sops/ に代理店の SOP がないか確認します。ブランドが存在しない場合は、「まずブランドを設定しますか（/digital-marketing-pro:brand-setup）？」と尋ねるか、デフォルト設定で続行します。
2. ソースデータを読み取って解析する：指定されたソースからデータを読み込みます。ヘッダーを検出して区切り文字を処理しながら CSV を解析するか、スキーマを推定しながら JSON を解析するか、Google Sheets MCP 経由で Google Sheets からデータを取得します。基本的な形式の整合性（行間の列数の一貫性、解析可能なデータ型、完全に空の行や列がないこと）を検証します。ソースの統計情報（レコード総数、検出された列、推定されたデータ型）を報告します。
3. フィールドマッピングウィザード：列名と宛先フィールド名の類似性に基づいてマッピングを自動提案します（「email」、「first_name」、「phone」、「company」など、一般的なパターンをあいまい一致で照合します）。提案するマッピングを提示し、ユーザーの確認を求めます。未マッピングのソース列（無視されるデータ）と、未マッピングの必須宛先フィールド（インポート前に解決が必要な阻害要因）にフラグを付けます。ユーザーがマッピングを調整、追加、削除できるようにします。
4. データ品質を検証する：すべてのレコードに対して検証を実行します。メール形式（RFC 5322）、電話番号形式の検出、必須フィールドが存在し値が空でないこと、データ型の適合性（日付、数値、文字列）、宛先プラットフォームごとのフィールド長制限を確認します。インポートファイル内の重複を検出します。CRM が接続されている場合は、メールアドレスまたは電話番号を照合キーとして既存レコードとの重複を確認します。メールおよび SMS のインポートでは、同意フィールドを確認し、明示的なオプトインのタイムスタンプ、配信停止フラグ、ブランドの市場規制への準拠を検証します。
5. 承認ゲートを設ける：ユーザーの確認用に、インポートの包括的な概要を提示します。ソース内のレコード総数、検証に合格したレコード数、検証に失敗したレコード数（理由別）、検出された重複レコード数（ファイル内および既存データとの重複）、連絡先インポートの同意確認状況、宛先プラットフォームと対象オブジェクトの種類、フィールドマッピングの概要、適用する重複排除方法を含めます。ユーザーが明示的に承認するまで実行をブロックします。
6. 宛先 MCP 経由でインポートを実行する：承認後、適切な MCP を通じて、レコードを宛先プラットフォームにバッチで書き込みます。CRM の連絡先は CRM MCP（HubSpot または Salesforce）、メール購読者リストはメール MCP（Mailchimp、ActiveCampaign、または SendGrid）、競合他社のベースラインデータは competitor-tracker.py、オーディエンスセグメントはオーディエンスマネージャーを使用します。レコードごとに成功、失敗、スキップのステータスを追跡します。レート制限時は待機し、書き込みがプラットフォームに到達していないことが確実な場合（接続拒否、DNS 障害、または 429 レート制限による拒否）のみ再試行します。タイムアウトまたは応答の消失後は、まずプラットフォーム上でレコードを検索し（メールアドレスまたは外部 ID で照合）、不足しているものだけを再送信します。タイムアウトを再送信の理由にしてはいけません。
7. 結果を報告する：詳細なインポート結果レポートを作成します。宛先 ID とともにインポートに成功したレコード、レコードごとの具体的なエラー理由を伴う失敗レコード、重複排除または検証によりスキップされたレコード、同意確認の概要、API 呼び出し総数、処理時間を記載します。失敗がレコード総数の 10% を超える場合は、確認が必要であることを示し、ロールバックの手順を提示します。

出力

以下を含む、構造化されたインポート結果レポートです。

• インポートの概要：処理したレコード数、正常にインポートされたレコード数、失敗したレコード数、スキップされたレコード数（重複）、スキップされたレコード数（検証エラー）を、割合の内訳および処理時間とともに記載します
• 使用したフィールドマッピング：ソース列と宛先フィールドの間に適用された最終的なマッピングを記載します。監査証跡および今後のインポートでの再利用のため、自動マッピングされたフィールドとユーザーによる上書きも含みます
• 検証レポート：検出されたデータ品質の問題（無効なメールアドレス、必須フィールドの欠落、形式の不一致、フィールド長の違反）を分類して一覧表示し、各問題の種類について該当レコード数とサンプル値を記載します
• 同意の確認状況：連絡先データをインポートする場合、オプトインが確認済みのレコード数、同意が欠落しているレコード数、配信停止フラグが設定されているレコード数、およびブランドの対象市場の規制（GDPR、CAN-SPAM、CCPA）に照らしたコンプライアンス評価を記載します
• 宛先の確認：プラットフォーム名、オブジェクトの種類、バッチ数、API 応答の概要、および取得可能な場合は正常にインポートされたレコードの宛先レコード ID を記載します
• 失敗したレコードのエラー詳細：レコードごとの失敗理由をエラーの種類別に分類します。API 検証エラー、書き込みがプラットフォームに到達していないことが確実な場合に限り許可された回数の再試行後も拒否されたレート制限（429）による拒否、権限エラー、宛先プラットフォームによるデータ形式の拒否が含まれます
• ロールバック手順：インポートを取り消す必要がある場合に備え、削除するレコード ID、使用する API エンドポイント、宛先プラットフォームでの一括削除の手順を記載します

使用するエージェント

• execution-coordinator — ソースの解析から MCP の実行までのインポートパイプラインのオーケストレーション、包括的なインポート前の概要とリスク評価を含む承認ワークフロー、書き込みがプラットフォームに到達していないことが確実な場合に限った再試行を伴うバッチ処理での MCP データ書き込みとエラー処理、レコードごとのステータス追跡を伴う実行ログ記録、失敗または問題のあるインポートに対するロールバック手順の生成を担当します
• crm-manager — プラットフォームのスキーマ認識（HubSpot のプロパティ、Salesforce のフィールド）に基づく CRM 固有のフィールドマッピング、既存の CRM レコードに対するメールアドレスと電話番号の照合キーを使用した重複排除ロジック、連絡先データの品質スコアリング、ブランドの対象市場のコンプライアンス要件に照らした同意フィールドの確認を担当します