integrate-webapi

プラグインの確認：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、先にユーザーに表示してから続行してください。

Web API の統合

Power Pages サイトを Dataverse と統合します。SPA サイトでは、フレームワーク固有のクライアント、サービス、フックのワークフローを維持します。非 SPA サイトでは、ネイティブの Forms、Lists、Liquid を優先し、要求されたクライアント側の操作に必要な場合にのみ Web API の JavaScript を追加します。

サイトタイプの振り分け

以下のワークフローを読み取ったり実行したりする前に、既存の SPA プロジェクト検索を先に実行します。

• 既存のファイル検索パターンを使って、カレントディレクトリまたは直下のサブディレクトリに powerpages.config.json があるか確認します。

• 見つかった場合は、以下の既存の SPA ワークフローを続行します。非 SPA サイトの検出は実行せず、SPA のフェーズ、プロンプト、ゲート、生成ファイル、デプロイ動作も変更しないでください。

• 既存の SPA 検索で powerpages.config.json が見つからなかった場合にのみ、次を実行します。

  node "${PLUGIN_ROOT}/scripts/lib/detect-project-context.js"
  

• siteType: "non-spa" が返された場合は、${PLUGIN_ROOT}/skills/integrate-webapi/references/non-spa-site-workflow.md に記載された7つのフェーズからなるワークフロー全体を読み、従ってください。以下の SPA ワークフローは実行しないでください。

• それ以外の場合はフェーズ1に進み、既存の未検出時の処理を維持してください。

非 SPA の経路では、ワークフローのリファレンスに定義されたリクエスト中心の呼び出しと探索的な呼び出しに対応します。SPA の呼び出し方法は、以下の既存のワークフローで定義されたとおりです。$ARGUMENTS に [CALLED-BY-PARENT-SKILL] が含まれる場合は、そのセンチネルと任意の caller=<skill-name> トークンを非 SPA ワークフローに渡してください。これにより、コミットとデプロイへの引き継ぎのみが抑止されます。非 SPA のスコープ承認やセキュリティ計画は省略されません。

---

基本原則

• 最初のテーブルは順次処理し、その後に並列処理：最初のテーブルは共有の powerPagesApi.ts クライアントを作成するため、単独で処理する必要があります。これが作成された後は、残りのテーブルはそれぞれ独立したファイル（型、サービス、フック）を作成するため、並列処理できます。
• 独立したエージェントを並列化：table-permissions-architect エージェントと webapi-settings-architect エージェントは独立しています。順次ではなく、並列で呼び出してください。
• アクセス許可にはデプロイが必要：テーブルのアクセス許可とサイト設定を構成する前に、.powerpages-site フォルダーが存在している必要があります。統合コードはこれがなくても作成できますが、アクセス許可は設定できません。
• AI 専用の読み取りモードはオプトイン：別のスキル（例：/add-ai-webapi）から呼び出され、$ARGUMENTS に [AI-READ-ONLY] センチネルが含まれる場合、読み取り専用コードを生成し、AI による要約の読み取り向けに設定とアクセス許可を強化します。契約についてはフェーズ1.6を参照してください。人間からの呼び出しでこのモードが有効になることはありません。
• TaskCreate/TaskUpdate を使用：すべてのフェーズを通じて進捗を追跡します。作業を始める前に、すべてのフェーズを含む ToDo リストを作成してください。
• サイトの整合性を維持：エージェントがモックデータに依存する UI やデータ駆動型 UI を変更する前に、${PLUGIN_ROOT}/references/site-modification-integrity.md を読みます。マニフェストがある場合は、新しく表示する状態をすべてローカライズし、コンポーネントを双方向に対応させ、拡張にも安全な状態に保ってください。

前提条件：

• /create-site で作成済みの Power Pages SPA サイト
• /setup-datamodel で設定済み、または手動で作成済みの Dataverse データモデル（テーブル／列）
• アクセス許可を設定するには、サイトが少なくとも1回デプロイ済みであり（.powerpages-site フォルダーが存在していること）、その必要があります。

最初のリクエスト： $ARGUMENTS

---

ワークフロー

1. サイトの存在を確認 — Power Pages プロジェクトを見つけ、前提条件を確認します
2. 統合ポイントを調査 — サイトのコードとデータモデルを分析し、Web API 統合が必要なテーブルを特定します
3. 統合計画を確認 — 調査結果をユーザーに提示し、統合するテーブルを確認します
4. 統合を実装 — 各テーブルに対して webapi-integration エージェントを使用します
5. 統合を検証 — 必要なファイルがすべて存在し、プロジェクトが正常にビルドされることを確認します
6. アクセス許可と設定をセットアップ — アクセス許可の情報源（図をアップロードするか、アーキテクトに分析を依頼するか）を選択し、大文字と小文字を区別して検証した列名を使用して、テーブルのアクセス許可と Web API サイト設定を構成します
7. 確認してデプロイ — ユーザーにサイトのデプロイを依頼し、確認が得られたら /deploy-site を呼び出します

---

フェーズ 1：サイトの存在を確認

目標：Power Pages プロジェクトのルートを見つけ、前提条件が満たされていることを確認します

操作：

1.1 プロジェクトを見つける

現在のディレクトリまたは直下のサブディレクトリで powerpages.config.json を探し、プロジェクトのルートを特定します。シェル固有のコマンドではなく、ファイル検索ツール（例：パターン powerpages.config.json および */powerpages.config.json を使った Glob）を使用してください。

見つからない場合：まず /create-site を使ってサイトを作成するよう、ユーザーに伝えます。

1.2 既存の設定を読み取る

powerpages.config.json を読み取り、サイト名を取得します。

1.3 フレームワークを検出する

package.json を読み取り、フレームワーク（React、Vue、Angular、または Astro）を判定します。フレームワーク検出の完全なマッピングについては ${PLUGIN_ROOT}/references/framework-conventions.md を参照してください。

1.4 データモデルを確認する

利用可能なテーブルを特定するため、.datamodel-manifest.json を探します。

**/.datamodel-manifest.json

見つかった場合は読み取ります。これはテーブルを特定するための主要な情報源です。

1.5 デプロイ状況を確認する

.powerpages-site フォルダーを探します。

**/.powerpages-site

見つからない場合：アクセス許可フェーズ（フェーズ 6）の前にデプロイが必要になることをユーザーに警告します。統合コード（フェーズ 2～5）は引き続き進められます。

1.6 AI 専用読み取りモードの検出（スキル間呼び出し）

$ARGUMENTS を調べます。テキストがセンチネル [AI-READ-ONLY] で始まる場合、呼び出し元は別のスキル（通常は /add-ai-webapi）です。このスキルはすでにサイトを分析し、AI による要約読み取りに必要な Layer 1/2 の前提条件を満たすテーブルを決定しています。$ARGUMENTS から以下の構造化トークンを解析します。

トークン	必須	意味
mode=ai-read-only	はい	読み取り専用の動作を確定します。他の値の場合はエラーとして拒否します。
primary=<logical_name>	はい	要約対象のプライマリテーブルです。指定がない場合は処理を停止し、呼び出し元に契約違反を報告します。
tables=<csv>	はい	対象範囲内のすべてのテーブル（プライマリテーブルと、すべての $expand 対象）のカンマ区切りリストです。
expand-targets=<csv>	いいえ	tables のうち $expand 対象であるテーブルのサブリストです。省略時は空になります。
caller=<skill-name>	いいえ	情報提供用です。コミットメッセージと最終サマリーで使用します。

センチネルが存在する場合：

• 以降のすべてのフェーズで参照する内部フラグ AI 専用読み取りモード = true を設定します。
• Phase 3 の対話形式でのテーブル確認をスキップし、指定された tables リストをそのまま使用します（呼び出し元ですでに確認済みです）。
• Phase 4.1 の webapi-integration プロンプトでは、操作を読み取り専用（一覧表示と ID による取得）に制限します。
• Phase 6 Path B のエージェントプロンプトには、各エージェントの「AI 専用読み取りモード」セクションに記載された強化された AI 専用の動作を適用します。
• Phase 6 Path A のスクリプト呼び出しでは、テーブル権限には --read のみを使用し、Webapi/<table>/fields からプライマリキーとリレーションシップの Navigation Properties を除外します。
• Phase 3 または Phase 6.2 では AskUserQuestion プロンプトを表示しません。これらの判断は呼び出し元が行います。
• すべての Git コミットを呼び出し元に委ねます。 Phase 4.4（git add -A && git commit）と Phase 6.5（権限／設定のコミット）を完全にスキップします。呼び出し元はオーケストレーターが定めたマイルストーンで変更を1つまたは2つのコミットにまとめます。ここで予期せずコミットすると、1つの論理的な変更が3つに分割されてしまいます。呼び出し元が再現できるよう、コミット対象となるファイル一覧を出力します。
• スキル終了時のデプロイプロンプトを抑制します。 Phase 6.1（.powerpages-site がない場合の今すぐデプロイするかどうかの確認）、Phase 7.3（最終デプロイの確認）、Phase 7.4（デプロイ後の注意事項）をスキップします。オーケストレーション全体の最後に行うデプロイ判断は呼び出し元が担当します。委譲先でデプロイの確認を重ねると、1回の実行につき2～3回、ユーザーに同じ確認を求めることになります。最後にデプロイや注意事項を付けず、統合サマリー（Phase 7.2）を返します。

センチネルがない場合：これまでどおりに進めます（完全な CRUD、対話形式の全フロー、自動コミット、デプロイ確認）。これは回帰防止策です。人が直接呼び出した場合の動作は変わりません。

出力：確認済みのプロジェクトルート、フレームワーク、データモデルの利用可否、デプロイ状況、および（センチネルが存在する場合）解析済みの AI 専用読み取り契約。

---

Phase 2: 統合箇所の調査

目標：サイトのコードとデータモデルを分析し、Web API 統合が必要なすべてのテーブルを特定します。

アクション：

Task ツールで agent_type: "explore" を指定して Explore エージェントを使用し、サイトのコードとデータモデルを分析します。Explore エージェントには、以下の質問への回答を依頼してください。

2.1 テーブルの特定

Explore エージェントに、次の項目を調べて Web API との統合が必要な Dataverse テーブルをすべて特定するよう依頼します。

• .datamodel-manifest.json — テーブルとその列の一覧
• src/**/*.{ts,tsx,js,jsx,vue,astro} — テーブルデータ、モックデータ、プレースホルダーの API 呼び出しを参照するソースコードファイル
• コード内の既存の /_api/ フェッチパターン
• Dataverse テーブルスキーマに対応する TypeScript のインターフェイスまたは型
• Dataverse テーブルのデータを表示または操作するコンポーネントファイル
• API 呼び出しに置き換える必要があるモックデータファイルまたはハードコードされた配列
• API 統合に言及している TODO または FIXME コメント

Explore エージェントへのプロンプト：

「この Power Pages SPA サイトを分析し、Web API との統合が必要な Dataverse テーブルをすべて特定してください。まず .datamodel-manifest.json でデータモデルを確認し、次にソースコードを検索して、モックデータの配列、ハードコードされたデータ、/_api/ へのプレースホルダーのフェッチ呼び出し、Dataverse の列パターン（cr*_ などの発行元プレフィックス）に一致する TypeScript インターフェイス、API 統合に関する TODO/FIXME コメント、テーブルデータを表示するコンポーネントを探してください。見つかったテーブルごとに、テーブルの論理名、エンティティセット名（複数形）、参照しているソースファイル、必要な操作（読み取り／作成／更新／削除）、および src/shared/ または src/services/ に既存の API クライアントまたはサービスがあるかどうかを報告してください。また、src/shared/powerPagesApi.ts がすでに存在するかどうかも確認してください。」

AI 専用読み取りモードが有効な場合（Phase 1.6 フラグが設定されている場合）： 上記のプロンプトに次の内容を追加します。

「呼び出し元は、テーブル [sentinel からのテーブル] に対して AI-READ-ONLY モードを指定しています（primary=[primary]、expand-targets=[expand-targets]）。このリスト内のすべてのテーブルで必要な操作は 読み取りのみ です。作成／更新／削除の呼び出し箇所や、モックデータの置き換え候補は報告しないでください。各 $expand 対象について、primary のコードがその展開先で $select する列も報告してください（これらが最小フィールドの一覧になります）。」

2.2 既存の統合コードの特定

Explore エージェントには、次の項目も報告してもらいます。

• src/shared/powerPagesApi.ts（または同等の API クライアント）がすでに存在するかどうか
• src/shared/services/ または src/services/ にすでにサービスファイルがあるテーブル
• src/types/ にすでに型定義があるテーブル
• すでに作成されているフレームワーク固有のフック／コンポーザブル

これにより、すでに行われた作業を重複して実施することを避けられます。

2.3 統合マニフェストの作成

Explore エージェントの調査結果をもとに、統合が必要なテーブルの一覧を作成します。

テーブル	論理名	エンティティセット	操作	参照元ファイル	既存のサービス
製品	cr4fc_product	cr4fc_products	CRUD	ProductList.tsx、ProductCard.tsx	なし
カテゴリ	cr4fc_category	cr4fc_categories	読み取り	CategoryFilter.tsx	なし

出力：すべてのテーブル、その操作、参照元ファイル、既存サービスの状況を記載した完全な統合マニフェスト

---

フェーズ 3：統合計画の確認

目標：統合マニフェストをユーザーに提示し、統合するテーブルを確認します。

アクション：

3.1 調査結果の提示

ユーザーに次の内容を示します。

1. Web API との統合対象として特定されたテーブル
2. 各テーブルを参照しているファイルと必要な操作
3. 共有 API クライアントがすでに存在するか、新たに作成する必要があるか
4. 対象外としたテーブル（すでにサービスがあるもの）

3.2 テーブルの確認

🚦 ゲート（計画 · integrate-webapi:3.2.confirm-tables）： Web API 統合コード（クライアント、型、サービス、フック）を作成するテーブルを最終決定します。

トリガー： Explore エージェントがフェーズ 3.1 で候補となるテーブルを提示しました。 確認する理由： すべてのテーブルを自動選択すると、ユーザーが Web API で公開するつもりのないテーブルに対して、孤立した TypeScript ファイルが生成される可能性があります。 キャンセルした場合： 何も残りません。サービス、型、フックのファイルはまだ作成されていません。

AI の読み取り専用モードが有効な場合（フェーズ 1.6 のフラグが設定されている場合）： このステップ全体をスキップします。センチネルから解析した tables リストをそのまま使用します。呼び出し元がすでにユーザーに選択を確認済みです。AskUserQuestion は実行しないでください。

それ以外の場合は、AskUserQuestion を使って確認します。

質問	選択肢
Web API 統合が必要な次のテーブルが見つかりました：[テーブルのリスト]。どのテーブルを統合しますか？	すべて（推奨）、特定のテーブルを選択する、テーブルを追加する必要がある

ユーザーが特定のテーブルを選択した場合、またはテーブルを追加した場合は、それに応じて統合マニフェストを更新します。

出力：統合するテーブルのユーザー確認済みリスト（AI の読み取り専用モードでは、センチネルから提供されたリスト）

---

フェーズ 4：統合を実装する

目標：webapi-integration エージェントを使って、確認済みの各テーブルの Web API 統合コードを作成します。

アクション：

4.1 テーブルごとにエージェントを呼び出す

各テーブルについて、Task ツールを使い、${PLUGIN_ROOT}/agents/webapi-integration.md にある webapi-integration エージェントを呼び出します。

エージェントへのプロンプトテンプレート：

「[テーブルの表示名] テーブルの Power Pages Web API を統合してください。

• テーブルの論理名：[logical_name]
• エンティティセット名：[entity_set_name]
• 必要な操作：[読み取り／作成／更新／削除]
• フレームワーク：[React/Vue/Angular/Astro]
• プロジェクトのルート：[path]
• このテーブルを参照するソースファイル：[ファイルのリスト]
• データモデルマニフェストのパス：[`.datamodel-manifest.json` のパス（利用可能な場合）]

TypeScript の型、CRUD サービスレイヤー、フレームワーク固有のフック／コンポーザブルを作成してください。参照元のソースファイルにあるモックデータやプレースホルダーの API 呼び出しを、新しいサービスに置き換えてください。」

AI の読み取り専用モードが有効な場合（フェーズ 1.6 のフラグが設定されている場合）： 「必要な操作：[読み取り／作成／更新／削除]」を Operations needed: read-only に置き換え、次の内容をプロンプトに追加します。

「AI の読み取り専用統合。 作成、更新、削除の関数は出力しないでください。サービスレイヤーには、ページネーション対応の list<Table> と get<Table>ById のみを用意してください。フレームワーク固有の読み取りフックのみを作成してください（例：items、isLoading、error、refetch を備えた use<Table>()。変更用フックは含めません）。AI 要約の呼び出し元に必要な場合を除き、モックデータの置き換えは行わないでください。上流のスキルがその上に要約サービスを追加します。共有の src/shared/powerPagesApi.ts クライアントがまだ存在しない場合は、引き続き作成してください。呼び出し元は AI 統合の読み取り処理でこのクライアントを使用します。」

4.2 最初のテーブルを処理してから、残りを並列化する

最初のテーブルは単独で処理する必要があります。他のすべてのテーブルが依存する共有の powerPagesApi.ts クライアントを作成するためです。最初のテーブルの処理が完了し、共有クライアントが作成されたら、次の手順に進みます。

• 共有 API クライアントが src/shared/powerPagesApi.ts に作成されたことを確認します。
• その後、複数の Task 呼び出しを使って残りのすべてのテーブルを並列に呼び出します。各テーブルは独立したファイル（src/types/ にある独自の型、src/shared/services/ にあるサービス、フック／コンポーザブル）を作成するため、競合は発生しません。

テーブルが 1 つだけの場合、このステップは順次処理するだけです。

4.3 各統合を確認する

各エージェントの処理完了後（または、すべての並列エージェントの処理完了後）、出力を確認します。

• 期待されるファイル（型、サービス、フック／コンポーザブル）が作成されていることを確認します。
• 最初のテーブルの処理後に共有 API クライアントが存在することを確認します。
• エージェントから報告された問題を記録します。

4.4 Git Commit

AI のみの読み取りモードが有効な場合（Phase 1.6 のフラグが設定されている場合）はスキップします。呼び出し元がコミットをまとめて実行します。 このフェーズでステージングされるファイルの一覧を出力し、次に進みます。

それ以外の場合は、すべての統合が完了した後に、ステージングしてコミットします。

git add -A
git commit -m "Add Web API integration for [table names]"

出力：確認済みのすべてのテーブルの統合コードが作成され、検証され、（通常モードでは）コミットされていること

---

Phase 5: 統合の検証

目標：想定されるすべての統合ファイルが存在し、インポートが正しく、プロジェクトが正常にビルドできることを検証します

アクション：

5.1 ファイル一覧の検証

統合したテーブルごとに、以下のファイルが存在することを確認します。

• 型定義（src/types/ 内。例：src/types/product.ts）
• サービスファイル（src/shared/services/ または src/services/ 内。例：productService.ts）
• フレームワーク固有のフック／コンポーザブル（例：React の場合は src/shared/hooks/useProducts.ts、Vue の場合は src/composables/useProducts.ts）

さらに、以下も確認します。

• src/shared/powerPagesApi.ts に共有 API クライアントが存在する
• 各サービスファイルが /_api/ エンドポイントを参照している
• 各サービスファイルが共有 API クライアントからインポートしている

5.2 ビルドの検証

インポートエラー、型エラー、依存関係の不足を検出するため、プロジェクトをビルドします。

npm run build

ビルドに失敗した場合は、次に進む前に問題を修正します。よくある問題は次のとおりです。

• 生成されたファイル間のインポート不足
• サービスと型定義間の型の不一致
• フレームワーク固有のコンパイルエラー

5.3 検証結果の提示

検証結果をまとめた表を提示します。

テーブル	型	サービス	フック／コンポーザブル	API 参照
Products	src/types/product.ts	src/shared/services/productService.ts	src/shared/hooks/useProducts.ts	/_api/cr4fc_products
...	...	...	...	...

ビルド状態：成功／失敗（詳細を記載）

出力：すべての統合ファイルが検証され、プロジェクトが正常にビルドされていること

---

Phase 6: アクセス許可と設定のセットアップ

目標：table-permissions-architect エージェントと webapi-settings-architect エージェントを使用して、統合したすべてのテーブルのテーブルアクセス許可と Web API サイト設定を構成します

アクション：

6.1 デプロイの前提条件を確認

両方のエージェントで .powerpages-site フォルダーが必要です。

AI のみの読み取りモードが有効な場合（Phase 1.6 のフラグが設定されている場合）：呼び出し元はすでに .powerpages-site の存在を確認しています。ガードとして再確認し、本当に存在しない場合は処理を停止して、契約違反を呼び出し元に報告します（呼び出し元がユーザーに伝えます）。 以下のデプロイ確認は行わないでください。デプロイを判断するのは呼び出し元です。

それ以外の場合、.powerpages-site が存在しないときは、次のようにします。

🚦 ゲート（plan · integrate-webapi:6.1.deploy-first）： .powerpages-site が見つかりません。両方のアーキテクトエージェントで必要です。先にデプロイするか、アクセス許可のセットアップをスキップして、設定なしで完了してください。

トリガー： Phase 6.1 で .powerpages-site フォルダーが見つかりませんでした。 確認する理由： 自動的にスキップすると統合が機能しません（Web API 呼び出しを支えるアクセス許可がないため）。自動的にデプロイすると、誤った環境が選択されます。 キャンセルした場合に残るもの： 何もありません。Phase 4 で作成したサービス／型／フックは、いずれもディスク上に残ります。

AskUserQuestion を使用します。

質問	選択肢
.powerpages-site フォルダーが見つかりませんでした。アクセス許可とサイト設定を構成する前に、サイトを一度デプロイする必要があります。今すぐデプロイしますか？	はい、今すぐデプロイする（推奨）、今回はアクセス許可をスキップする — 後で設定します

「はい、今すぐデプロイする」の場合：先に /deploy-site を実行してから、このフェーズに戻ります。

「スキップ」の場合：アクセス許可とサイト設定をまだ構成する必要があることを注記して、Phase 7 に進みます。

6.2 権限の定義元を選択する

🚦 ゲート（計画 · integrate-webapi:6.2.permissions-source）： 既存の権限図をアップロードする（パス A）か、アーキテクトエージェントに導き出させる（パス B）かを決定します。この選択によって、フェーズ 6 の残りの進行先が決まります。

トリガー： デプロイの前提条件が満たされた後、フェーズ 6.2 に入ったとき。 確認する理由： パス A では、古い、または誤った図に基づくテーブル権限が生成されます。パス B では、Dataverse への問い合わせに数分かかる場合があります。 キャンセル時に残るもの： 何もありません — 権限 YAML はまだ書き込まれていません。

AI のみの読み取りモードが有効な場合（フェーズ 1.6 のフラグが設定されている場合）： 権限の定義元に関する質問を完全に省略し、**パス B（アーキテクトに判断を任せる）**をデフォルトとして選択して、6.3 節に直接進みます。フェーズ 1.6 の取り決めに従い、ここでは AskUserQuestion を発行しません。この判断は呼び出し元（/add-ai-webapi）が担い、6.3 節の AI のみのアーキテクトプロンプトには、すでに読み取り専用の方針が組み込まれています。パス A（既存の権限図のアップロード）は、人が対話的に行うパスであり、委任された実行には適用されません。

それ以外の場合は、AskUserQuestion ツールを使って、権限をどのように定義するかユーザーに尋ねます。

質問：「サイトの Web API の権限と設定をどのように定義しますか？」

選択肢	説明
既存の権限図をアップロードする	既存の権限構造を示す画像（PNG/JPG）または Mermaid 図を提供します
アーキテクトに判断を任せる	テーブル権限アーキテクトと Web API 設定アーキテクトが、サイトのコード、データモデル、Dataverse 環境を分析し、権限と設定を自動的に提案します

適切なパスに進みます。

パス A：既存のアクセス許可図をアップロードする

🚦 ゲート（計画 · integrate-webapi:6.2.permissions-approval）： アップロードされた図から解析したアクセス許可計画について、Web ロール／テーブルアクセス許可／サイト設定の YAML を書き込む前に最終承認を得ます。以下のパス A の手順のステップ 6 で実行されます。

トリガー： パス A — 図の解析と Mermaid フローチャートの描画が完了したとき。 確認する理由： スコープや CRUD フラグを誤ると、.powerpages-site/table-permissions/ にコミットされます。修正可能ですが、Git の履歴が煩雑になります。 キャンセル時に残るもの： 何もありません — YAML ファイルはまだ書き込まれていません。

ユーザーが既存の図をアップロードすることを選択した場合：

1. ユーザーにアクセス許可図の提供を依頼します。対応形式：

   • 画像ファイル（PNG、JPG）— Read ツールで画像を表示し、Web ロール、テーブルアクセス許可、CRUD フラグ、スコープ、サイト設定を抽出します
   • Mermaid 構文 — ユーザーは Mermaid フローチャートのテキストをチャットに直接貼り付けられます
   • テキストによる説明 — Web ロール、テーブルアクセス許可、スコープ、サイト設定の構造化リスト

2. 図を構造化形式に解析します：

   • Web ロール：名前を照合し、.powerpages-site/web-roles/ にある既存のロールと一致させて UUID を取得します
   • テーブルアクセス許可：アクセス許可名、テーブルの論理名、Web ロール UUID（複数可）、スコープ、CRUD フラグ（read/create/write/delete/append/appendto）、親アクセス許可とリレーションシップ名（スコープが Parent の場合）
   • サイト設定：Webapi/<table>/enabled および Webapi/<table>/fields — 重要：集計 OData クエリで使用する列を含め、必要な列の LogicalName をすべて明示的に指定する必要があります

3. Dataverse に対して列名を検証します — ユーザー提供の図を使用する場合も、各テーブルの列の LogicalName を Dataverse に問い合わせ、Webapi/<table>/fields の値に含まれる各列名が Dataverse の LogicalName と完全に一致する（大文字と小文字を区別する）ことを確認します。ファイルを作成する前に、不一致を修正します。

4. .powerpages-site/ の既存の設定と照合し、新しいアクセス許可とサイト設定、および既存のものを特定します。

5. ユーザーが画像またはテキストを提供した場合、解析データから Mermaid フローチャートを生成し、視覚的に確認できるようにします。

6. AskUserQuestion を使って、解析したアクセス許可計画をユーザーに提示し、承認を求めます：

   質問	選択肢
   このアクセス許可計画で問題ありませんか？	承認してファイルを作成（推奨）、変更を依頼、キャンセル

7. 解析データを使って、セクション 6.4：アクセス許可と設定ファイルの作成に直接進みます。

パス B：アーキテクトに判断を任せる

アーキテクトに判断を任せることをユーザーが選択した場合は、セクション 6.3：テーブルアクセス許可エージェントの呼び出しに進みます。

6.3 テーブルアクセス許可エージェントと Web API 設定エージェントを呼び出す（並列実行）

これら 2 つのエージェントは独立しているため、2 つの Task 呼び出しを同時に使って並列実行します：

テーブル権限エージェント

Task ツールを使用して、${PLUGIN_ROOT}/agents/table-permissions-architect.md にある table-permissions-architect エージェントを呼び出します。

プロンプト（デフォルト — 完全な CRUD）：

「この Power Pages SPA サイトを分析し、テーブル権限を提案してください。以下のテーブルは Web API に統合されています：[Phase 4 で統合されたテーブルの一覧]。既存の Web ロールとテーブル権限を確認してください。統合されたすべてのテーブルを対象とする、完全なテーブル権限プランを提案してください。私がプランを承認した後、決定論的なスクリプトを使用して Web ロールとテーブル権限の YAML ファイルを作成してください。」

プロンプト（AI 専用の読み取りモードが有効な場合）： デフォルトのプロンプトに追加します。

「AI 専用の読み取り統合です。 呼び出し元は /add-ai-webapi であり、これらのテーブルは /_api/summarization/data/v1.0/ によって要約されます。このエンドポイントは意味的に読み取りであり、Dataverse を変更することはありません。そのため、次のようにしてください。

• read: true のみを設定してください。デフォルトの慣例で含める場合でも、create、write、delete は提案しないでください。
• コレクション値の $expand 対象（primary=[primary]、expand-targets=[expand-targets]）には、read: true を設定した Parent スコープ を使用し、関係のたどりを許可するため、親テーブルの権限に appendTo: true を追加してください。
• 適切な Web ロールがない場合は、そのことを呼び出し元に報告してください。/add-ai-webapi は事前に /create-webroles を呼び出します。ここではロールの作成を待って処理を止めないでください。」

エージェントは次の処理を行います。

1. サイトを分析し、プランを提案します（Mermaid 図を含む）
2. プランモードでプランを提示し、ユーザーの承認を求めます
3. 承認後、必要な Web ロールを create-web-role.js を使用して作成します
4. すべてのテーブル権限ファイルを create-table-permission.js を使用して作成します
5. 作成したファイルの概要を返します

Web API 設定エージェント

Task ツールを使用して、${PLUGIN_ROOT}/agents/webapi-settings-architect.md にある webapi-settings-architect エージェントを呼び出します。

プロンプト（デフォルト — 完全な CRUD）：

「この Power Pages SPA サイトを分析し、Web API のサイト設定を提案してください。以下のテーブルは Web API に統合されています：[Phase 4 で統合されたテーブルの一覧]。既存のサイト設定を確認し、Dataverse に問い合わせて列の正確な LogicalNames を取得してください。大文字と小文字を区別して検証した列名を使って、サイト設定を提案してください。私がプランを承認した後、決定論的なスクリプトを使用してサイト設定の YAML ファイルを作成してください。」

プロンプト（AI 専用の読み取りモードが有効な場合）： デフォルトのプロンプトに追加します。

「AI 専用の読み取り統合です。 これらのテーブルは /_api/summarization/data/v1.0/ によって要約されます。fields リストのルールは、デフォルトの CRUD 方針よりも厳格です。

• Webapi/<table>/fields には、そのテーブルに対するすべてのサイト呼び出しで必要な列を正確に含める必要があります。primary の $select / $expand から始めてください。そのテーブルが集計クエリにも使用されている場合は、グループ化キー、集計入力、フィルター列、並べ替え列を追加してください。
• 主キー列は含めないでください。summarization エンドポイントはレコード ID を URL パスで受け取ります。Microsoft の提供する case プリセットでは、incidentid を含めず、Webapi/incident/fields = description,title が設定されています。
• ルックアップ列には、OData の読み取り形式である _<col>_value のみを含めてください。@odata.bind の前に AI 以外のコードが使用する場合に限り、関係の Navigation Property を追加してください。
• Dataverse に問い合わせて正確な LogicalNames（大文字と小文字を区別）を取得してください。大文字と小文字の不一致があると 403 が発生します。」

エージェントは次の処理を行います。

1. サイトを分析し、Dataverse に問い合わせて列の正確な LogicalNames を取得します
2. 列名を相互検証します（大文字と小文字を区別）
3. プランモードでプランを提示し、ユーザーの承認を求めます
4. 承認後、create-site-setting.js を使用してすべてのサイト設定ファイルを作成します
5. 作成したファイルの概要を返します

6.4 に進む前に、両方のエージェントが完了するまで待ちます。

6.4 権限ファイルと設定ファイルを作成する（パス A のみ）

このセクションは、パス A（ユーザーが提供した権限図）にのみ適用されます。 パス B の場合、アーキテクトエージェントがセクション 6.3 でファイルを直接作成します。

ユーザーの図を解析したら、以下の決定論的なスクリプトを使用して YAML ファイルを作成します。YAML ファイルを手動で作成しないでください — UUID の生成、フィールドの順序、書式設定、ファイル名の決定を自動的に処理するこれらのスクリプトを必ず使用してください。

6.4.1 Web ロールを作成する（必要な場合）

プランで既存のものに加えて新しい Web ロールが必要な場合は、テーブル権限の作成に UUID が必要となるため、先に作成します。

node "${PLUGIN_ROOT}/skills/create-webroles/scripts/create-web-role.js" --projectRoot "<PROJECT_ROOT>" --name "<Role Name>" [--anonymous] [--authenticated]

JSON 出力（{ "id": "<uuid>", "filePath": "<path>" }）を記録します — テーブル権限の作成時に、id を --webRoleIds の値として使用します。

6.4.2 テーブル権限を作成する

プラン内の各テーブル権限について実行します。親権限を子権限より先に処理してください — 子権限には、JSON 出力に含まれる親の UUID が必要です。

AI 専用読み取りモードが有効な場合（Phase 1.6 フラグが設定されている場合）： デフォルトのフラグ設定は --read のみです。対象範囲内のどの権限にも、--create、--write、--delete を渡さないでください — AI による要約の読み取りでデータが変更されることはありません。Parent スコープの子権限では、引き続き --parentPermissionId と --parentRelationshipName を渡してください。親権限には --appendto を追加して、AI エンドポイントがリレーションシップをたどれるようにします。

Global／Contact／Account／Self スコープの場合：

node "${PLUGIN_ROOT}/scripts/create-table-permission.js" --projectRoot "<PROJECT_ROOT>" --permissionName "<Permission Name>" --tableName "<table_logical_name>" --webRoleIds "<uuid1,uuid2>" --scope "Global" [--read] [--create] [--write] [--delete] [--append] [--appendto]
node "${PLUGIN_ROOT}/scripts/create-table-permission.js" --projectRoot "<PROJECT_ROOT>" --permissionName "<Permission Name>" --tableName "<table_logical_name>" --webRoleIds "<uuid1,uuid2>" --scope "Contact" --contactRelationshipName "<lookup_to_contact>" [--read] [--create] [--write] [--delete] [--append] [--appendto]
node "${PLUGIN_ROOT}/scripts/create-table-permission.js" --projectRoot "<PROJECT_ROOT>" --permissionName "<Permission Name>" --tableName "<table_logical_name>" --webRoleIds "<uuid1,uuid2>" --scope "Account" --accountRelationshipName "<lookup_to_account>" [--read] [--create] [--write] [--delete] [--append] [--appendto]
node "${PLUGIN_ROOT}/scripts/create-table-permission.js" --projectRoot "<PROJECT_ROOT>" --permissionName "<Permission Name>" --tableName "<table_logical_name>" --webRoleIds "<uuid1,uuid2>" --scope "Self" [--read] [--create] [--write] [--delete] [--append] [--appendto]

Parent スコープの場合（親権限の UUID とリレーションシップ名が必要です）：

node "${PLUGIN_ROOT}/scripts/create-table-permission.js" --projectRoot "<PROJECT_ROOT>" --permissionName "<Permission Name>" --tableName "<table_logical_name>" --webRoleIds "<uuid1>" --scope "Parent" --parentPermissionId "<parent-uuid>" --parentRelationshipName "<relationship_name>" [--read] [--create] [--write] [--delete] [--append] [--appendto]

各実行の出力は { "id": "<uuid>", "filePath": "<path>" } です。子権限の --parentPermissionId には id を使用します。

6.4.3 サイト設定を作成する

プラン内の各サイト設定について実行します。

有効化設定（ブール値）：

node "${PLUGIN_ROOT}/scripts/create-site-setting.js" --projectRoot "<PROJECT_ROOT>" --name "Webapi/<table>/enabled" --value "true" --description "Enable Web API access for <table> table" --type "boolean"

Fields 設定（文字列 — 図で検証済みの列名を使用）：

node "${PLUGIN_ROOT}/scripts/create-site-setting.js" --projectRoot "<PROJECT_ROOT>" --name "Webapi/<table>/fields" --value "<comma-separated-validated-columns>" --description "Allowed fields for <table> Web API access"

Inner error 設定（ブール値、デバッグ用の任意設定）：

node "${PLUGIN_ROOT}/scripts/create-site-setting.js" --projectRoot "<PROJECT_ROOT>" --name "Webapi/error/innererror" --value "true" --description "Enable detailed error messages for debugging" --type "boolean"

重要：各 Fields 設定の --value は、${PLUGIN_ROOT}/references/webapi-field-allowlist.md に必ず従ってください。通常の列には正確な LogicalNames を使用し、ルックアップの読み取りには _<LogicalName>_value を、ルックアップの書き込みには @odata.bind の前に使用する正確な Navigation Property を使用します。ワイルドカードによるフィールドアクセスは、2026 年 9 月 14 日以降サポートされません。

集計クエリ：$apply で参照されるすべてのグループ化キー、集計入力、フィルター列、並べ替え列を、明示的な Fields リストに含めます。

ルックアップ列：読み取りには _<LogicalName>_value を含めます。POST／PATCH で [email protected] を使用してリレーションシップを設定する場合は、その正確な大文字小文字を含む Navigation Property も Fields の値に含めます。

AI 専用読み取りモード（Phase 1.6 フラグが設定されている場合）：Fields の値に関するルールがさらに厳しくなります。

• テーブルに対する各サイト呼び出しに必要な正確な列を含めます。プライマリの $select／$expand から始め、そのテーブルが集計クエリでも使用される場合は、グループ化キー、集計入力、フィルター列、並べ替え列を追加します。
• プライマリキーは含めないでください。要約エンドポイントは URL パスにレコード ID を含めます。Microsoft 提供のケースプリセットでは、Webapi/incident/fields = description,title が設定されており、incidentid は含まれていません。
• ルックアップ列には、読み取り用の _<col>_value 形式のみを含めます。AI モードでは @odata.bind による書き込みを行わないため、リレーションシップの Navigation Property は省略します。
• File／Image 列と集計クエリの列は明示し、サイトが実際に使用する列のみを追加します。

6.5 Git コミット

AI 専用読み取りモードが有効な場合（Phase 1.6 フラグが設定されている場合）はスキップします — 呼び出し元がコミットをまとめて実行します。 このフェーズでステージングされるファイルの一覧を出力してから、次に進みます。

それ以外の場合は、権限ファイルと設定ファイルをステージングしてコミットします。

git add -A
git commit -m "Add table permissions and Web API site settings for [table names]"

出力：作成・検証済みのテーブル権限とサイト設定（通常モードではコミット済み）

6.6 最終サイト整合性ゲート

すべての統合ソースの変更、権限／設定の作業、ビルド検証が完了したら、次を実行します。

node "${PLUGIN_ROOT}/scripts/validate-site-integrity.js" --projectRoot "<PROJECT_ROOT>"

完了を報告したり、デプロイを依頼したりする前に、ブロッキングエラーをすべて修正してください。両方向のレビュー結果を確認し、内容を拡充して報告してください。その後にソースを変更した場合は、このゲートを再実行してください。

---

フェーズ 7：レビューとデプロイ

目標：実施したすべての作業の概要を提示し、デプロイを案内します

アクション：

7.1 スキルの使用状況を記録

参照：${PLUGIN_ROOT}/references/skill-tracking-reference.md

参照先の手順に従って、このスキルの使用状況を記録してください。--skillName "IntegrateWebApi" を使用します。

7.2 概要を提示

実施したすべての作業の概要を提示します。

手順	状態	詳細
API クライアント	作成済み／既存	src/shared/powerPagesApi.ts
型	作成済み	src/types/product.ts、src/types/category.ts
サービス	作成済み	src/shared/services/productService.ts など
フック	作成済み	src/shared/hooks/useProducts.ts など
コンポーネントの更新	X ファイル	モックデータを API 呼び出しに置き換え
テーブル権限	作成済み	X 個の権限ファイル
サイト設定	作成済み	X 個の設定ファイル

7.3 デプロイを確認

🚦 ゲート（plan · integrate-webapi:7.3.deploy）： 統合後のデプロイ確認 — 権限とサイト設定をデプロイするまで、Web API 呼び出しは機能しません。

トリガー： 統合コードと権限 YAML のコミットがすべて完了したとき。 確認する理由： 自動デプロイは、PAC CLI がその時点で参照している環境を対象にします。 キャンセルした場合： 何も起きません。統合成果物はディスク上に残り、デプロイは実行されません。

AI のみの読み取りモードが有効な場合（フェーズ 1.6 のフラグが設定されている場合）はスキップします。呼び出し元がオーケストレーション終了時のデプロイ判断を一度だけ行います。フェーズ 7.2 の概要を返して終了してください。

それ以外の場合は、AskUserQuestion を使用します。

質問	選択肢
Web API の統合と権限の準備ができました。すべてを公開するには、サイトをデプロイする必要があります。今すぐデプロイしますか？	はい、今すぐデプロイします（推奨）、いいえ、後でデプロイします

「はい、今すぐデプロイします」の場合：/deploy-site スキルを呼び出して、サイトをデプロイします。

「いいえ、後でデプロイします」の場合：了承し、次のように案内します。

「問題ありません。準備ができたら、/deploy-site を使用してサイトをデプロイしてください。新しい権限を適用してサイトをデプロイするまで、Web API 呼び出しは機能しません。」

7.4 デプロイ後の注意事項

AI のみの読み取りモードが有効な場合はスキップします。呼び出し元が、AI 固有の懸念事項（ガバナンスの階層、ランタイムのバージョン、Bing への依存関係）を含むデプロイ後の案内を独自に提示します。

それ以外の場合は、デプロイ後（またはデプロイをスキップした場合）に、次の点をユーザーに案内します。

• API をテストする：デプロイ済みのサイトを開き、ブラウザーの「ネットワーク」タブで Web API 呼び出しが機能することを確認します
• 権限を確認する：API 呼び出しが 403 を返す場合は、テーブル権限とサイト設定が正しいことを確認します。最も一般的な原因は、リクエスト内の列が Webapi/<table>/fields にないこと、またはメタデータから返された Dataverse の論理名（大文字小文字を区別）と完全に一致しないことです。OData の集計（$apply、集計、グループ化された合計）では、グループ化キー、集計入力、フィルター列、並べ替え列がすべて明示的に列挙されていることを確認します。
• 本番環境では innererror を無効にする：デバッグのために Webapi/error/innererror を有効にしていた場合は、公開前に無効にします
• Web ロール：保護された API にアクセスするには、ユーザーに適切な Web ロールを割り当てる必要があります

出力：概要を提示済み。デプロイは完了または延期（通常モード）、あるいは呼び出し元に返却（AI のみの読み取りモード）。

---

重要な注意事項

すべてのフェーズを通じて

• TaskCreate/TaskUpdate を使用して、各フェーズの進捗を追跡します
• 重要な意思決定のタイミングでユーザーに確認を求めます（以下の一覧を参照）
• 最初のテーブルは順番に、その後は並列で処理します。最初のテーブルで共有 API クライアントを作成し、その後は各テーブルで独立したファイルを作成するため、残りのテーブルは並列で処理できます
• 節目でコミットします。統合コードの完成後、および権限ファイルの完成後にコミットします
• 統合ごとに検証します。エージェントの呼び出し後に、想定したファイルが存在することを確認します

重要な意思決定のタイミング（ユーザーの回答を待つ）

1. フェーズ 2 の後：統合するテーブルを確認します
2. フェーズ 3 の後：統合計画の承認を得ます
3. フェーズ 6.1：.powerpages-site がない場合、今すぐデプロイするか、権限の設定をスキップするかを確認します
4. フェーズ 6.2：権限の情報源を選択します（図をアップロードするか、アーキテクトに分析を依頼します）
5. フェーズ 6.3：テーブル権限の計画と Web API サイト設定の計画の承認を得ます（パス B では両方のエージェントが並列で実行され、それぞれが独自の計画を提示して承認を求めます）
6. フェーズ 7.2：今すぐデプロイするか、後でデプロイするかを確認します

進捗管理

フェーズ 1 を開始する前に、TaskCreate を使用してすべてのフェーズのタスクリストを作成します。

タスクの件名	activeForm	説明
サイトの存在を確認	サイトの前提条件を確認しています	プロジェクトのルートを特定し、フレームワークを検出して、データモデルとデプロイ状況を確認します
統合ポイントを調査	コードの統合ポイントを分析しています	Explore エージェントを使用してテーブルと既存のサービスを見つけ、統合マニフェストを作成します
統合計画を確認	ユーザーと統合計画を確認しています	調査結果を提示し、統合するテーブルを確認します
統合を実装	Web API 統合を実装しています	最初のテーブルで webapi-integration エージェントを呼び出して共有クライアントを作成し、その後、残りのテーブルを並列で処理して、出力を検証し、git commit を実行します
統合を検証	統合を検証しています	想定されるすべてのファイルの存在を検証し、インポートと API 参照を確認して、プロジェクトをビルドします
権限と設定をセットアップ	権限とサイト設定を構成しています	権限の情報源（図のアップロードまたはアーキテクトによる分析）を選択し、table-permissions-architect エージェントと webapi-settings-architect エージェントを並列で呼び出して、大文字と小文字を区別して検証済みの列名を使用する YAML ファイルを作成し、git commit を実行します
レビューしてデプロイ	概要を確認してデプロイしています	概要を提示し、デプロイするかどうかを確認して、デプロイ後のガイダンスを提供します

各タスクの開始時に TaskUpdate で in_progress に設定し、完了時に completed に設定します。これにより、ユーザーが進捗を把握でき、ワークフローを確実に進められます。

---

フェーズ 1 から開始します：サイトの存在を確認