sf-datacloud-prepare: Data Cloud Prepare フェーズ

このスキルは、ユーザーが取り込みとレイク準備作業が必要な場合に使用します：データストリーム、Data Lake Objects (DLO)、トランスフォーム、Document AI、非構造化取り込み、またはコネクタ設定からライブストリームへのハンドオフ。

このスキルがタスクを所有する場合

以下の作業に関連する場合は sf-datacloud-prepare を使用してください：

• sf data360 data-stream *
• sf data360 dlo *
• sf data360 transform *
• sf data360 docai *
• データが Data Cloud にどのように入るべきかの選択
• ソース更新後の取り込みの再実行またはスキャン
• コネクタ設定完了後の Ingestion API バックアップストリームの準備

ユーザーが以下の場合は他のスキルに委譲してください：

• ソース接続の作成/テスト中 → sf-datacloud-connect
• DMO へのマッピングまたは IR/データグラフの設計 → sf-datacloud-harmonize
• 取り込まれたデータのクエリ実行 → sf-datacloud-retrieve

---

最初に収集すべき必須コンテキスト

以下の情報を質問するか推測してください：

• ターゲット組織のエイリアス
• ソース接続名
• ソースオブジェクト/データセット/ドキュメントソース
• 目的のストリームタイプ
• DLO命名規則の期待値
• ユーザーがストリームを作成、更新、実行、または削除するかどうか
• ソースが CRM、データベースコネクタ、非構造化ファイルソース、または Ingestion API フィードかどうか

---

コア動作ルール

• Data Cloud コマンドを実行する前に、外部プラグインのランタイムを確認してください。
• 取り込みアセットを変更する前に、共有準備分類器を実行してください：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json
• 新しい取り込みアセットを作成する前に、既存のストリームと DLO の検査を優先してください。
• 通常の使用時には 2>/dev/null でリンクプラグインの警告ノイズを抑制してください。
• DLO 命名とフィールド命名を CRM ネイティブではなく Data Cloud 固有のものとして扱ってください。
• ストリームを作成する前に、各データセットを Profile、Engagement、または Other として扱うべきかを確認してください。
• 非構造化ソースで作業する場合、ストリームレベルのリフレッシュと接続レベルの再実行を区別してください。
• 初期ストリームまたは非構造化アセット作成がプラットフォームゲートされている場合は、UI 設定を意図的に使用してください。
• 取り込みアセットが明らかに正常な場合にのみ Harmonize にハンドオフしてください。

---

推奨ワークフロー

1. 準備作業の準備状況を分類する

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json

2. 既存の取り込みアセットを検査する

sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dlo list -o <org> 2>/dev/null

3. 作成前にストリームカテゴリを確認する

提案を行う際は、以下のルールを使用してください：

カテゴリ	使用対象	典型的な要件
Profile	人物/エンティティレコード	主キー
Engagement	時間ベースのイベントまたはインタラクション	主キー + イベント時間フィールド
Other	参照/構成/サポートデータセット	主キー

ソースが曖昧な場合は、データセットを Profile、Engagement、または Other として扱うべきかをユーザーに明確に質問してください。

4. ストリームを意図的に作成または検査する

sf data360 data-stream get -o <org> --name <stream> 2>/dev/null
sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null
sf data360 data-stream create -o <org> -f stream.json 2>/dev/null
sf data360 data-stream run -o <org> --name <stream> 2>/dev/null

5. DLO の形状を確認する

sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null

6. 正しいリフレッシュメカニズムを選択する

ユーザーのゴールに一致する最小のリフレッシュスコープを使用してください：

sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null

• data-stream run はストリームレベルのリフレッシュまたは再スキャンに最も近い方法です。
• connection run-existing は接続レベルで実行され、一部のコネクタワークフローで役立つ場合がありますが、非構造化ソースでのストリームリフレッシュの信頼性の高い代替手段ではありません。
• SharePoint スタイルのドキュメントコネクタの場合、ゴールが新しく追加または変更されたファイルの再スキャンである場合は、data-stream run を優先してください。

7. 非構造化ソースを意図的に処理する

SharePoint スタイルのドキュメント取り込みの場合、最小限の非構造化 DLO ペイロードは次のようになります：

{
  "name": "my_udlo",
  "label": "My UDLO",
  "category": "Directory_Table",
  "dataSource": {
    "sourceType": "SF_DRIVE",
    "directoryAndFilesDetails": [
      {
        "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>",
        "fileName": "*"
      }
    ],
    "sourceConfig": {
      "reservedPrefix": "$dcf_content$"
    }
  }
}

ユーザーがより豊富なエンドツーエンドパイプラインを必要とする場合は、UI を使用してください。UI パスは、ベアの CLI DLO 作成フローが自動的にプロビジョニングしない可能性のある追加のドキュメントメタデータフィールドと下流アセットをシードできます。

8. 送信データワークフロー用にローカル Ingestion API 例を使用する

外部システムが Data Cloud にレコードをプッシュする場合：

1. sf-datacloud-connect でコネクタを作成します
2. sf data360 connection schema-upsert でスキーマをアップロードします
3. 必要に応じて UI でストリームを作成します
4. examples/ingestion-api/ のローカル例でレコードを送信します

cd examples/ingestion-api
cp .env.example .env
python3 send-data.py

主要な詳細：

• 認証はステージフロー：JWT → Salesforce トークン → Data Cloud トークン
• 取り込みエンドポイントは Salesforce インスタンス URL ではなくテナント URL を使用します
• 202 はペイロードが処理のために受け入れられたことを意味し、レコードがすぐにクエリ可能であることを意味しません
• 検証エラーは通常 Problem Records DLO ファミリーに表示されます

9. その後のみ調和フェーズに進む

ストリームと DLO が正常になったら、sf-datacloud-harmonize にハンドオフしてください。

---

高リスク落とし穴

• CRM バックアップストリームの動作は完全にカスタムコネクタフレームワーク取り込みと同じではありません。
• sf data360 data-stream run と sf data360 connection run-existing は交換可能ではありません。非構造化リスキャンではストリームレベルのリフレッシュを優先してください。
• SFDC ストリームはプラットフォーム管理スケジュールで同期されます。data-stream run は CRM コネクタリフレッシュの一般的なコントロールパスではありません。
• 一部の外部データベースコネクタは API を使用して作成できますが、ストリーム作成には UI フローまたは組織固有のブラウザオートメーションが必要な場合があります。すべてのコネクタタイプに対して純粋な CLI ストリーム作成パスを約束しないでください。
• 初期 SharePoint スタイルの非構造化設定は、最小限の CLI DLO 作成フロー内より UI の方が豊富である可能性があります。
• ストリーム削除は、削除モードが別途指定されていない限り、関連する DLO も削除できます。
• DLO フィールド命名は CRM フィールド命名と異なり、__c → _c 変換が含まれます。
• DLO レコード数をリスト出力で十分であると仮定する代わりに Data Cloud SQL でクエリしてください。
• CdpDataStreams は、ストリームモジュールが現在の組織/ユーザー向けにゲートされていることを意味します。盲目的に再試行する代わりに、プロビジョニング/権限確認をガイドしてください。

---

出力形式

Prepare task: <stream / dlo / transform / docai>
Source: <connection + object>
Target org: <alias>
Artifacts: <stream names / dlo names / json definitions>
Verification: <passed / partial / blocked>
Next step: <harmonize or retrieve>

---

参考資料

• README.md
• examples/ingestion-api/README.md
• ../sf-datacloud/assets/definitions/data-stream.template.json
• ../sf-datacloud/references/plugin-setup.md
• ../sf-datacloud/references/feature-readiness.md