consumer-goods-accruals-datakit-deploy

必須：必ず Phase 6 レポートを作成する

早期終了、ブロックされたフェーズ、エラー条件を含むすべてのフェーズを完了した後、必ず Phase 6 レポートをディスクに書き込んでください。レポートを書き込まなかった場合、シナリオへの対応がどれほど適切であっても、常にテスト失敗になります。

これは、例外なくすべての終了経路に適用されます。

• 正常終了（すべてのフェーズを実行）
• Phase 1 での停止（事前チェック失敗、営業組織が見つからない、CGCloudAddons が見つからない、Data Cloud が有効になっていない）
• Phase 3 のエラー（セットアップスクリプトがゼロ以外の終了コードを返す）
• Phase 4 の失敗検出（DataKitDeploymentLog の失敗）
• スケジュールの競合（Phase 5 のガードが作動）
• その他のブロック条件（入力の欠落、組織に接続できないなど）

レポートを ${outputDir}/report.md（タスクの generatedFileLocationDirective で指定されたパス）に書き込んでください。チャットメッセージとして表示するだけではいけません。ディスク上にファイルが存在する必要があります。シナリオに正しく対応しても、ファイルを書き込まなかった場合、評価では no_output と記録され、スコアはゼロになります。

---

Accrual Data Kit をデプロイする

TPM Liability Accruals ソリューションを Salesforce 組織にエンドツーエンドでインストールします。 scripts/ に含まれるセットアップツールチェーンを実行し、組織の準備状況を確認し、 Data Cloud 接続を検証し、CGCloudAddons 静的リソースをダウンロードして、 データキットをデプロイし、デプロイを確認した後、Data Cloud エクスポートと 発生額計算のチェーンをスケジュールします。

ヘッドレスでのデリバリーを想定しています。組織を指定すると、インストール全体を実行します。

名前空間はビルドごとに異なります。cgcloud（リリース版）、cgcloud_dev（開発／ベータ版）、または プレフィックスなし（ソースのみ）です。セットアップスクリプトは、実行時に DataCloudExportScheduler Apex クラスへのクエリを通じてプレフィックスを自動検出します。cgcloud. または cgcloud_dev. をハードコードしないでください。

参考：TPM Accrual Engine の概念

スキルのルートディレクトリからセットアップスクリプトを実行します。

node scripts/setup.js --org <alias> [options]

---

収集する入力

Phase 1 のチェックを実行する前に、必須入力をすべて収集し、検証してください。組織のエイリアスと営業組織名の両方が確認できるまで、Phase 1 を開始しないでください。いずれかが質問後も不足している場合は、直ちに停止して Phase 6 レポートを作成してください。

開始前に質問してください。推測してはいけません。

入力	デフォルト	備考
組織のエイリアス／ユーザー名	—	対象組織の sf エイリアスです。必須です。
営業組織名	—	Data Space（DataSpace_<salesOrg>）、そのプレフィックス（DS<lastChar>_）、および UI コントローラーマップのキーの名前に使用します。必須です。英数字4文字ちょうどである必要があります（例：0001、AB12）。ユーザーが提示しておらず、提示できない場合は、推測したりデフォルト値を使用したりしないでください。直ちに停止し、Phase 1 をブロックした理由を「営業組織名が提供されていない」として Phase 6 レポートを作成し、セッションを終了してください。この値なしで Phase 1 のチェックを実行してはいけません。
Data Space をスキップしますか？	いいえ	組織に Data Space がない場合のみ「はい」を指定します（一部のデモ組織など）。
ドライランですか？	いいえ	ファイルを準備し、すべてのデプロイとスケジュール設定をスキップします。最初にこのオプションを提示してください。
名前空間の上書き	自動検出	自動検出が失敗する場合にのみ指定します。末尾の __ を付けずに値を渡してください。
エクスポートの cron	0 0 2 * * ?	ユーザーが別のスケジュールを希望する場合にのみ確認してください。
発生額計算チェーンの cron	0 0 3 * * ?	ユーザーが別のスケジュールを希望する場合にのみ確認してください。

ドライランのフラグはここで一度だけ収集し、すべてのフェーズで適用してください。再度確認してはいけません。

---

Phase 1 — 事前チェック

最初の失敗で停止してください。チェックに失敗した後は続行しないでください。

1.1 ローカルツール

1. Salesforce CLI が存在すること： sf --version
2. Node 22： node --version

1.2 組織に接続できること

sf org display --target-org <alias> --json

status が Active であることを確認します。id（組織 ID）、instanceUrl、apiVersion を記録します。 終了コードがゼロ以外、またはステータスが非アクティブの場合は停止し、ユーザーにログインを依頼します。

1.3 Data Cloud Data Kit フレームワークの存在確認

sf data query --target-org <alias> \
  --query "SELECT Id FROM DataKitDeploymentLog LIMIT 1"

INVALID_TYPE または NOT_FOUND → 直ちに停止：この組織では Data Cloud Data Kit フレームワークが有効になっていません。このスキルを続行する前に、Data Cloud と Data Kit 機能を有効にする必要があることをユーザーに伝えてください。Phase 1 がブロックされたことと、正確なクエリエラーを記載した Phase 6 レポートを今すぐ作成してください。それ以上のクエリ、ダウンロード、デプロイは実行しないでください。 行が 0 件でも問題ありません。フレームワークは存在するため、Phase 1.4 に進んでください。

1.4 CGCloudAddons 静的リソースの存在確認

sf data query --target-org <alias> \
  --query "SELECT Id FROM StaticResource WHERE Name='CGCloudAddons'"

行が 0 件 → 直ちに停止：マネージドパッケージがインストールされていないか、このバージョンには CGCloudAddons が含まれていません。続行する前にパッケージをインストールする必要があることをユーザーに伝えてください。Phase 1 がブロックされたことと、CGCloudAddons not found を記載した Phase 6 レポートを今すぐ作成してください。この失敗後に、ダウンロード、デプロイ、スケジュールを試みないでください。

1.5 Sales 組織の検証

sf data query --target-org <alias> --json \
  --query "SELECT Id, Name FROM Sales_Organization__c WHERE Name = '<salesOrg>'"

行が 0 件 → 直ちに停止：指定された Sales 組織名はこの組織に存在しません。クエリと行が 0 件だった結果をユーザーに提示してください。デプロイまたはスケジュールには進まないでください。Phase 1 をブロックとして記録してください：Sales org '<salesOrg>' not found。

1.6 デプロイのベースライン

sf data query --target-org <alias> --json \
  --query "SELECT MAX(CreatedDate) maxCreated FROM DataKitDeploymentLog"

集計クエリは常に 1 行だけを返します。テーブルが空（初回デプロイ）の場合、maxCreated は null になります。DEPLOY_BASELINE_TIME = maxCreated ?? '' を保存してください（null は空文字列として扱います）。Phase 4 では、DEPLOY_BASELINE_TIME が空でない場合に限り WHERE CreatedDate > DEPLOY_BASELINE_TIME を使用してください。空の場合は WHERE 句を完全に省略してください。WHERE CreatedDate > null は Salesforce SOQL の INVALID_QUERY_FILTER_OPERATOR エラーとなり、クエリが中止されます。

1.7 組織側での手動の前提条件

ユーザーのプロンプトですでにこれらの前提条件が確認されている場合は、確認済みとして扱い、再度尋ねないでください。まだ確認されていない項目だけを尋ねてください。

• Data Cloud と Analytics Studio が有効であること（Setup → Data Cloud Setup）
• Connectors 機能が有効であること（Data Cloud Setup → Feature Manager）
• Processing Services Pairing で Accrual Ingestion Process に割り当てられたユーザーに、Data Cloud Architect 権限セットが付与されていること
• TPM Offcore 接続アプリに OAuth スコープ cdp_ingest_api が設定されていること
• ライセンス：AccrualsProcessingAddOn、AccrualsProcessingUserAddOn、TpmAccrualsAddOn、TpmAccrualsUserAddOn（参考情報。ユーザーが確認した内容を記録してください）

---

Phase 2 — Data Cloud 接続の確認（ベストエフォート）

クエリで cdp_ingest_api の確認を試みてください。「確認できない」は WARN として扱い、STOP にはしないでください。

sf data query --target-org <alias> \
  --query "SELECT Id, Name FROM ConnectedApplication WHERE Name LIKE '%TPM%'"

クエリが権限エラーになる場合は、Setup → App Manager → （TPM Offcore 接続アプリを編集）→ OAuth Policies → Selected OAuth Scopes に cdp_ingest_api が含まれていることをユーザーに確認してください。ユーザーの確認後にのみ続行してください。

---

フェーズ 3 — セットアップスクリプトの実行

スキルのルートディレクトリから、エンドツーエンドのセットアップスクリプトを実行します。ドライランモードでは、--dry-run を指定します。

node scripts/setup.js --org <alias> --sales-org <salesOrg> [--skip-dataspace] [--dry-run] [--namespace <ns>]

現在の作業ディレクトリから scripts/setup.js にアクセスできない場合は、フェーズ 6 のレポートにフェーズ 3 を not run — script path not accessible in this environment と記録し、 フェーズ 4 に直接進みます（DEPLOY_BASELINE_TIME より後の行があるかどうか、DataKitDeploymentLog をクエリします）。

スクリプトは次のステップを順番に実行します。

• ステップ 0 — 前提条件の確認（対話型プロンプト。ドライランではスキップ）
• ステップ 1 — CGCloudAddons 静的リソースのダウンロード
• ステップ 2 — データキットのメタデータ内にある __SF_ORG_ID__ プレースホルダーの置換
• ステップ 3 — TPM Accruals Data Kit のメタデータのデプロイ（sf project deploy start）
• ステップ 4 — sfdatakit__DeployDataKitComponents を使用した Liability Accruals Engine データキットのデプロイ （デプロイ済みのコンポーネントはスキップし、完了まで最大 30 分待機）
• ステップ 5 — sfdatakit__DeployDataKitComponents を使用した TPM Accruals データキットのデプロイ （同じパターンで、完了まで待機）
• ステップ 6 — データスペースの作成（手動プロンプト — 下記を参照。--skip-dataspace を指定するとスキップ）
• ステップ 7 — データスペースのプレースホルダーを置換して Accruals Reports のメタデータをデプロイ（2 パス）
• ステップ 8 — 名前空間とデータスペースを置換して TPMAccrualTacticSummary UI コンポーネントをデプロイ
• ステップ 9 — スケジュール設定の手順を表示

スクリプトは ステップ 0（前提条件の確認）と ステップ 6（データスペースの作成）で一時停止します。一時停止したら、=== Step N: から始まる stdout のブロックを取得し、そのままユーザーに伝えます。続行する前に、ユーザーがステップを完了するまで待ちます。

TPMAccrualTacticSummary UI コンポーネントを Promotion ページに追加する作業は、実行後に手動で行います。スクリプトは手順を表示するだけです。フェーズ 6 では、これを保留中として記録します。

終了コードが 0 以外の場合は停止し、stdout の末尾 50 行を提示します。スクリプトが失敗した場合、フェーズ 4 に進まないでください。

---

フェーズ 4 — デプロイの検証

ドライランモードでは、このフェーズ全体をスキップします。 レポートに pending — not run (dry-run) と記録します。

sf data query --target-org <alias> --json \
  --query "SELECT ComponentName, DeploymentStatus, DeploymentError, CreatedDate
           FROM DataKitDeploymentLog
           WHERE CreatedDate > ${DEPLOY_BASELINE_TIME}
           ORDER BY CreatedDate ASC
           LIMIT 200"

（DEPLOY_BASELINE_TIME が空の場合は WHERE 句を省略します。必ず LIMIT 200 を含めます。）

行を評価します。

• DeploymentStatus = 'Failure' の行、または空でない DeploymentError がある場合 → 停止し、失敗したすべてのコンポーネント名と、その DeploymentError の値を列挙します。フェーズ 5 に進まないでください。 フェーズ 6 のレポートにフェーズ 5 を not run — deployment failures unresolved と記録します。
• InProgress の行がある場合 → 60 秒待って再クエリします。すべての行が終端状態（Successful または Failure）になるまで、フェーズ 5 に進まないでください。30 分経過しても InProgress の行がある場合は停止し、現在の件数を提示します。
• 0 行の場合 → デプロイによってログエントリがまだ生成されていません。30 分間、60 秒ごとに再クエリします。0 行が続く場合はデプロイの問題として扱い、停止して報告します。
• すべての行が Successful の場合 → フェーズ 5 に進みます。
• ポーリング期間内に行が 0 件返された場合、または InProgress、Failure の行がある場合は、フェーズ 5 に進まないでください。

---

フェーズ 5 — スケジュール設定

ドライランモードでも、ステップ 5.1（名前空間の検出 — 読み取り専用）と 5.2（cron ジョブの確認 — 読み取り専用）は実行し、実行されるはずの置換済み Apex を表示します。ただし、sf apex run は実行しないでください。レポートにフェーズ 5 を pending — not run (dry-run) と記録します。

5.1 名前空間プレフィックスの検出

インストール済みクラスをクエリします（scripts/steps/utils.js で使用されているものと同じプローブ）。

sf data query --target-org <alias> --json \
  --query "SELECT NamespacePrefix FROM ApexClass WHERE Name='DataCloudExportScheduler'"

クエリ結果	NS_PREFIX	意味
0 行	—	スケジューラクラスがデプロイされていません → 停止：フェーズ 3 が完了していません
1 行、null	""	管理対象外ソースのデプロイ
1 行、任意の値	その値	クエリが返した名前空間を使用します
1 行超	—	曖昧です → 停止し、すべての行を表示します

ドット付きのプレフィックスを組み立てます。

NS="${NS_PREFIX:+${NS_PREFIX}.}"    # yields "cgcloud.", "cgcloud_dev.", or ""

以下のすべての Apex 識別子は ${NS}ClassName の形式で記述されています。

5.2 cron ジョブの重複を防ぐ

sf data query --target-org <alias> --json \
  --query "SELECT Id, State, CronJobDetail.Name FROM CronTrigger
           WHERE CronJobDetail.Name IN
             ('DataCloud Export Daily','TPM Accrual Process Chain')"

一致するジョブがある場合：

1. 競合する各ジョブの既存の Id と State をユーザーに示します。
2. 既存のジョブを中止して再スケジュールするか、スケジュールをスキップするか、明示的に尋ねます。
3. 黙って上書きしてはいけません。System.schedule を呼び出す前に、ユーザーの回答を待ちます。
4. ユーザーが中止して再スケジュールすることを選んだ場合：競合する各ジョブに対して System.abortJob('<id>') を実行し、その後 5.3/5.4 に進み、新しい CronTrigger の State = 'WAITING' および NextFireTime が null でないことを確認します。
5. 競合とその解決方法を Phase 6 のレポートに記録します。

cron の順序要件： Data Cloud のデータをチェーン実行時に利用できるように、エクスポートジョブ（5.3）はアクルーアルチェーンジョブ（5.4）より先に実行される必要があります。デフォルト値（exportCron = 0 0 2 * * ?、accrualCron = 0 0 3 * * ?）では 1 時間の間隔が確保されます。ユーザーがカスタム式を指定した場合は、エクスポートの cron がアクルーアルの cron より先になることを確認します。1 時間以上の間隔を推奨します。2 つの式が競合または逆転している場合はユーザーに警告し、確認を得るまでスケジュールしてはいけません。

5.3 Data Cloud Connector Export をスケジュールする

以下の Apex を一時ファイル（例：/tmp/dc-export.apex）に書き込み、実行してから、ファイルを削除します：

${NS}DataCloudExportScheduler scheduler = new ${NS}DataCloudExportScheduler(
  new List<String>{ 'promotionmeasures', 'paymenttacticmeasures', 'dailymeasurereal' }
);
System.schedule('DataCloud Export Daily', '<exportCron>', scheduler);

# Write to temp file, run, clean up
cat > /tmp/dc-export.apex << 'EOF'
<filled-in Apex from above>
EOF
sf apex run --target-org <alias> --file /tmp/dc-export.apex
rm /tmp/dc-export.apex

確認：CronTrigger WHERE CronJobDetail.Name = 'DataCloud Export Daily' → 行がちょうど 1 件あり、State = 'WAITING' で、NextFireTime が null ではないこと。

5.4 Accrual Calculation Chain をスケジュールする

以下の Apex を一時ファイル（例：/tmp/accrual-chain.apex）に書き込み、実行してから、ファイルを削除します（ルールを参照してください。ingestionMode で有効なのは 'partial' または 'full' のみです）：

${NS}ScheduleTPMAccrualProcessChain scheduler =
  new ${NS}ScheduleTPMAccrualProcessChain();
System.schedule('TPM Accrual Process Chain', '<accrualCron>', scheduler);

# Write to temp file, run, clean up
cat > /tmp/accrual-chain.apex << 'EOF'
<filled-in Apex from above>
EOF
sf apex run --target-org <alias> --file /tmp/accrual-chain.apex
rm /tmp/accrual-chain.apex

5.3 と同じ CronTrigger のパターンで確認します。

参考：

• DataCloudExportScheduler
• ScheduleTPMAccrualProcessChain

---

Phase 6 — レポート

早期に停止した場合も含め、実行のたびにこのレポートを作成してください。 Phase 1 で実行がブロックされた場合（入力の不足、事前チェックの失敗、Data Cloud が有効になっていない、営業組織が見つからない）は、停止条件を確認した直後にレポートを作成してください。省略してはいけません。適切に早期停止を処理しても report.md ファイルが作成されていない場合は、失敗と評価されます。ファイル出力の指示があるエージェント評価の状況では、その指示は「作業が終わったらファイルを書き込む」という意味であり、「作業の代わりにファイルを書き込む」という意味ではありません。

シェルコマンド（例：Write ツールまたは cat > <path>）を使って、レポートをディスクに書き込んでください。チャットメッセージに表示するだけでは不十分です。タスクの指示で指定されたパスにファイルとして存在している必要があります。

早期停止のレポートは簡潔にしてください。 Phase 3 の開始前に実行がブロックされた場合（入力の不足、事前チェックの失敗）、レポートには実際に発生したこと、ブロックの理由、実行しなかったこと、再試行に必要なユーザーからの情報のみを記載します。実行されなかったフェーズの定型セクションで、早期停止のレポートを水増ししてはいけません（DataKit のデプロイ詳細、スケジュールの競合解決、ライセンスに関する警告、手動作業の手順など）。これらのセクションは、該当するフェーズが実行された場合にのみ必要です。Phase 1 でブロックされた場合は、3～5 行が適切な分量です。

Deployment report — <org alias, or "not provided">
  Sales org: <salesOrg, or "not provided">
  Dry run: <yes|no>
  Namespace prefix: <detected value, or "(not detected — execution blocked)">
  Phase 1 preflight: <passed | blocked: <exact check that failed>>
  DataKit deployments: <X succeeded / Y failed / Z in progress, or "not run — Phase 1 blocked">
  Data Space: <created | skipped | not run — Phase 1 blocked>
  Data Cloud Export: <scheduled | dry-run | not run — Phase 1 blocked>
  Accrual Chain: <scheduled | dry-run | not run — Phase 1 blocked>
  Pending manual steps: <list, or "none — execution did not complete">
  License warnings: <unconfirmed licenses, or "none — not checked">

ルール

• 報告する前に、必ず実行してください。 Phase 6 のレポートを書く前に、すべてのフェーズを最後まで実行してください（または、文書化された停止条件に到達するまで実行してください）。スキルを実行する代わりにレポートを書いてはいけません。ファイル出力の指示は「作業完了後に書く」という意味であり、「作業の代わりに書く」という意味ではありません。
• 再実行とは、実際に再実行することです。 既存のデプロイを再実行または検証するよう求められた場合は、必ず node scripts/setup.js を再実行し、その前に新しい DataKitDeploymentLog のベースラインを取得してください。過去の実行が成功していても十分だと見なさず、今回の実行で新たに記録された行を使って再検証してください。
• 今回の実行における DataKitDeploymentLog の行に、DeploymentStatus = 'Failure' または空でない DeploymentError がある間は、成功したと主張してはいけません。
• CronTrigger で State = 'WAITING' かつ NextFireTime が null 以外であることを確認するまで、スケジュールが成功したと主張してはいけません。
• 最初のプリフライトチェックに失敗した時点で停止し、正確な失敗内容を報告してください。
• セットアップスクリプトの標準出力にある手動手順の指示をそのまま伝え、ユーザーの応答を待ってください。
• 出力する Apex に名前空間プレフィックスをハードコードしてはいけません。必ず ${NS} から組み立ててください。
• ingestionMode で受け付ける値は 'partial' または 'full' のみです。'initial' は例外をスローします。