integrate-backend

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

バックエンド統合

ユーザーのビジネス上の課題を分析し、適切なバックエンド統合の方法（Web API、AI Web API、サーバーロジック、クラウドフロー、またはそれらの組み合わせ）を提案してから、ソリューションの実装に適したスキルを呼び出します。

基本原則

• まず課題を理解する：技術の選択に飛びついてはいけません。提案する前に、ユーザーの意図、データフロー、セキュリティ要件、パフォーマンス要件を分析します。
• 機能する最もシンプルな方法を提案する：シンプルな Dataverse の CRUD には Web API、生成要約や既存データに基づく検索には AI Web API、サーバー側の処理が必要な場合にはサーバーロジック、非同期のバックグラウンド処理にはクラウドフローを使います。過剰に複雑な設計は避けてください。
• セキュリティが重要なアクションはサーバーで処理する：改ざん防止が必要なビジネスルール（状態遷移、承認ワークフロー、計算値）に書き込みが依存する場合、サーバーロジックで検証と書き込みの両方を実行する必要があります。検証だけを行い、書き込みをクライアント側の Web API 呼び出しに任せてはいけません。判断フレームワークのセキュアアクションの原則を参照してください。
• AI Web API は Web API の上に成り立つ：Data Summarization エンドポイントと Case-preset エンドポイントは、通常の Web API と同じ _api レイヤーを介して読み取るため、同じテーブル権限、列権限、Webapi/<table>/* サイト設定が適用されます。計画に同じテーブルに対する Web API 項目と AI Web API 項目の両方が含まれる場合、AI 項目は Web API 項目に依存するため、後のフェーズに配置します。Search Summary にはテーブル単位の前提条件がなく、単独で使用できます。
• 組み合わせは一般的です：実際のシナリオでは、複数の方法が必要になることがよくあります。妥当な場合は組み合わせを提案し、それぞれの要素が必要な理由を説明してください。
• 実装ではなく、適切なスキルへ振り分ける：このスキルは適切なスキルを提案して呼び出します。バックエンドファイル自体は作成しません。

初期リクエスト： $ARGUMENTS

---

ワークフロー

1. サイトの存在を確認する — Power Pages プロジェクトを見つけ、前提条件を確認します
2. ビジネス上の課題を理解する — ユーザーが必要としていることと、その理由を分析します
3. 統合方法を提案する — 理由を添えて推奨案を提示します
4. 適切なスキルへ振り分ける — 実装に適したバックエンドスキルを呼び出します

---

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

目標：Power Pages プロジェクトのルートを見つけ、前提条件を確認します

アクション：

1. 4 つのフェーズすべてを含む TODO リストを作成します（進捗管理の表を参照）

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

現在のディレクトリまたはその直下のサブディレクトリで powerpages.config.json を探します。

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

1.2 現在の状態を調べる

Explore エージェントを使って、サイトに既存のバックエンド統合があるかをすばやく確認します。

「この Power Pages SPA サイトにある既存のバックエンド統合を分析してください。

1. .powerpages-site/server-logic/ を確認し、既存のサーバーロジックエンドポイントを一覧表示する
2. .powerpages-site/cloud-flow-consumer/ を確認し、登録済みのクラウドフローを一覧表示する
3. フロントエンドコード（src/**/*.{ts,tsx,js,jsx,vue,astro}）で、/_api/（Web API）、/_api/serverlogics/（サーバーロジック）、/_api/cloudflow/（クラウドフロー）の呼び出しを検索する
4. src/services/、src/shared/ などに既存のサービスレイヤーや API ユーティリティがあるか確認する
5. .powerpages-site/web-roles/*.webrole.yml から利用可能な Web ロールを一覧表示する すでに存在するバックエンド統合を報告してください。既存のものを活用して構築します。」

1.3 Dataverse カスタム アクションを確認する

ユーザーの Dataverse 環境に、統合で活用できる既存のカスタム アクションがあるかどうかを確認します。

node "${PLUGIN_ROOT}/scripts/list-custom-actions.js" "<ENV_URL>"

スクリプトは、Custom APIs（最新）と Custom Process Actions（レガシー）について、名前、説明、バインドの種類、パラメーターを返します。カスタム アクションが見つかった場合は記録してください。フェーズ 3 の推奨事項に反映します。

出力：プロジェクトのルートを確認し、既存のバックエンド統合を特定し、Dataverse カスタム アクションを検出します。

---

フェーズ 2：ビジネス上の課題を把握する

目標：技術的な依頼だけでなく、その背景にあるビジネス上の課題を理解するために、ユーザーのリクエストを分析します。

アクション：

2.1 リクエストを分析する

ユーザーのリクエストと既存のサイトの状態から、次の点を判断します。

• ユーザーは何を実現しようとしていますか？（技術ではなく、ビジネス上の成果）
• どのようなデータが関係しますか？（Dataverse テーブル、外部システム、ユーザー入力）
• 誰が処理を開始しますか？（ユーザー操作、フォーム送信、ページ読み込み、スケジュール実行）
• ユーザーは即時の応答を必要としていますか？（リアルタイムの UI 更新か、バックグラウンド処理か）
• 外部サービスが関係しますか？（決済ゲートウェイ、メール、Graph、SharePoint、サードパーティ API）
• 資格情報やシークレットが関係しますか？（API キー、クライアント シークレット、トークン）
• ロジックをブラウザーから隠す必要がありますか？（価格設定ルール、検証アルゴリズム、ビジネスルール）
• これは単純なデータ操作ですか、それとも複雑なビジネスロジックですか？（CRUD か、複数ステップの処理か）
• 改ざん防止が必要なビジネスルールに書き込みが依存していますか？（状態遷移、承認条件、計算値）。該当する場合、サーバー側のロジックは検証だけでなく、書き込みの実行も行う必要があります。
• UI で、AI が生成した要約、根拠に基づく AI 検索、関連レコードの発見が必要ですか？（例：「このケースを要約する」、「未完了の注文を要約する」、「ケースページでナレッジベースの記事を提案する」、「AI を活用した検索」）。該当する場合は、AI Web API が適しています。次の表現が使われているか確認してください。要約する、〜の要約、Copilot、関連する／類似する／提案された <エンティティ>、AI 検索、セマンティック検索。
• 既存の Dataverse カスタム アクションで要件の一部に対応できますか？ フェーズ 1.3 でカスタム アクションが見つかった場合、ユーザーのニーズに合致するものがあるか確認してください。サーバー側のロジックは、同等のロジックを一から構築する代わりに、InvokeCustomApi を介して既存のカスタム アクションをラップできます。

2.2 あいまいな点を確認する

リクエストが複数のアプローチに当てはまり、適切な選択肢が明確でない場合は、AskUserQuestion を使って確認します。

質問	確認するタイミング
ユーザーは結果をすぐに確認する必要がありますか、それともバックグラウンドでの処理でも問題ありませんか？	同期処理にも非同期処理にもできる処理を含むリクエストの場合
外部 API やサービス（例：Stripe、SendGrid、SharePoint）が関係しますか？	リクエストで「統合」に言及されているものの、詳細が不明な場合
ブラウザーに置くべきではない機密資格情報が関係しますか？	外部サービスとの統合に言及している場合
これは一度限りの操作ですか、それとも複数ステップのワークフローですか？	単純な呼び出しにも、オーケストレーションにもできる場合

出力：ビジネス上の課題と技術要件を明確に把握します。

---

フェーズ 3：統合アプローチを推奨する

目標：明確な根拠とともに推奨事項を提示します。

アクション：

3.1 決定フレームワークを適用する

参照：${PLUGIN_ROOT}/skills/integrate-backend/references/decision-framework.md

参照先の決定マトリックス、意図のマッピング、セキュアアクションの原則を使って、適切なアプローチを判断します。次の点を検討してください。

1. Web API だけで対応できますか？ 外部呼び出し、シークレット、サーバー側ロジックがなく、書き込みを規定するビジネスルールもない単純な Dataverse CRUD であれば、Web API を推奨します。最もシンプルな選択肢です。

2. AI Web API が必要ですか？ 次のいずれかに該当する場合は、AI Web API が適しています。

   • UI で、詳細ページ上のレコードの AI 生成サマリーを表示する（例：「このケースを要約」「Copilot サマリー」）
   • UI で、リストやコレクションの AI サマリーを表示する（例：「未処理の注文を要約」「今週のケースの傾向を強調表示」）
   • 詳細ページで関連レコードを見つける（例：「このケースに関連する KB 記事を提案」「類似商品」「類似ケース」）。手作業で作成した OData のキーワード照合より、Search Summary の根拠に基づく検索の方が適しています。
   • サイトで、キーワードのみの検索に代わる、またはそれを補完する、AI の根拠に基づいた検索を行う

   AI Web API は読み取り専用のため、セキュアアクションの原則は適用されません。AI 項目が Web API 項目と同じ Dataverse テーブルを対象とする場合は、AI 項目を後のフェーズに配置してください（Web API レイヤー 1／2 の前提条件が整っている必要があります）。Search Summary 項目にはテーブルごとの前提条件がないため、単独で使用できます。

3. サーバーロジックが必要ですか？ 次のいずれかに該当する場合は、サーバーロジックが必要です。

   • 外部 API の呼び出し（HttpClient）
   • 認証情報やシークレットをサーバー上に保持する必要がある
   • ビジネスロジックをブラウザーから見えないようにする必要がある
   • 複数の Dataverse クエリを 1 つのエンドポイントにまとめる必要がある
   • 回避できないサーバー側の検証が必要である
   • ポータルで使用する Dataverse Custom API／Action をラップする。フェーズ 1.3 でカスタムアクションが見つかった場合は、ゼロからの構築を推奨する前に、要件に合うものがあるか確認してください。
   • 書き込みが、改ざん不能でなければならないビジネスルール（状態遷移、承認条件、計算値）に依存する。サーバーロジックで検証と書き込みの両方を実行する必要があります。

4. クラウドフローが必要ですか？ 次のいずれかに該当する場合は、クラウドフローが適しています。

   • 操作が非同期である。ユーザーは即時の結果を必要としない
   • バックグラウンド処理（メール送信、通知、注文処理）
   • Power Automate コネクタを使用してシステム間で実行する複数ステップのワークフロー
   • サーバーロジックのタイムアウトである 120 秒を超える長時間のプロセス
   • 開発者以外のユーザーがワークフローを変更できる必要がある

5. 組み合わせが必要ですか？ よくある組み合わせは次のとおりです。

   • Web API + AI Web API：UI で Dataverse の生レコードと同じデータの AI サマリーを表示する（最も一般的な AI パターン。ダッシュボード、ケース／注文の詳細ページなど）
   • Web API + Cloud Flow：UI では機密情報ではない Dataverse フィールドを読み書きし、一部の操作でバックグラウンドフローを起動する
   • Server Logic + Cloud Flow：リアルタイムエンドポイントで操作を検証して実行し、非同期フローで後続処理を行う（例：サーバーロジックでステータスを遷移させ、Cloud Flow で通知を送信する）
   • Web API + Server Logic：安全な直接読み書きには Web API を使用し、ビジネスルールの適用が必要な操作にはサーバーロジックを使用する（サーバーロジックで該当する操作の検証と書き込みの両方を行う）
   • Web API + AI Web API + Cloud Flow：閲覧可能なケース、Copilot サマリーと KB の検索、非同期通知を備えたサポートポータル

3.1.1 セキュリティレビュー — セキュアアクションの原則を適用する

計画を確定する前に、Web API に割り当てられたすべての項目を確認し、次の点を問いかけます。「ユーザーが先行するサーバーロジックの検証をスキップして、この Web API エンドポイントを直接呼び出した場合、ビジネスルールに違反できてしまう可能性はあるか？」

答えが**「はい」**の場合、その書き込みは Web API の項目に含めてはいけません。その書き込みを検証するサーバーロジックの項目に移してください。サーバーロジックで Server.Connector.Dataverse を使用して、書き込みを検証し、実行してください。

検証と実行をサーバーロジックで行う必要がある一般的なパターン（Web API では不可）：

パターン	サーバー側で処理する必要がある理由
ステータス／状態の遷移（Draft → Submitted → Approved）	クライアントは直接 PATCH を送信して、任意のステータスに変更できてしまいます
条件付きの書き込み（期限前のみ許可、特定のロールのみ許可など）	クライアントは期限後、または不適切なロールコンテキストから書き込みできてしまいます
計算フィールドへの書き込み（サーバーがスコア、価格、派生値を計算）	クライアントがフィールドに直接書き込む場合、任意の値を送信できてしまいます
複数テーブルにまたがるアトミックな操作（入札を落札にして、他の入札を却下し、イベントを更新する）	クライアントで一部しか実行されないと、データに不整合が生じる可能性があります
他のレコードの現在の状態に依存する書き込み	クライアント側の古いデータ表示により、無効な書き込みが発生する可能性があります

状態遷移に関する計画の正しい構成：

Phase 1: Server Logic — "transition-order" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition is allowed, writes new status
  - Returns { success, previousStatus, newStatus }

Phase 2: Web API — Order table CRUD
  - Read: list/filter orders (safe for Web API)
  - Create: new orders in Draft status (safe — initial state, no rule to enforce)
  - Update: description, notes, dates (safe — no business rules on these fields)
  - NOTE: Status changes are NOT here — they go through the server logic endpoint

計画の誤った構成（アンチパターン）：

❌ Phase 1: Server Logic — "validate-transition" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition
  - Returns { valid: true/false }   ← only validates, doesn't write

❌ Phase 2: Web API — Order table CRUD
  - Update: includes status field  ← client writes status after "validation"
  - PROBLEM: client can skip Phase 1 and write any status directly

3.2 HTML プランをレンダリングする

承認を求める前に、プランのデータを作成し、HTML プランをレンダリングします。このプランでは、以下を視覚化します。

• 主要な概念 — Web API、サーバーロジック、Cloud Flows の概要（テンプレートにハードコードされています）
• 概要 — アプローチごとの統計、アプローチのチップ、設計の根拠
• データフロー — 各ユーザー操作でデータがどのように移動するかを示す視覚的なフロー図。ステップはアプローチごとに色分けされています
• 実装順序 — フェーズごとにまとめられた項目、依存関係、複雑さのバッジ、実装コマンド
• 統合項目 — 各項目のアプローチ、理由、実装の詳細

次のキーを持つ JSON オブジェクトを用意します。

キー	説明
SITE_NAME	powerpages.config.json に記載されているサイト名
PLAN_TITLE	短いタイトル（例：「バックエンド統合プラン」）
SUMMARY	統合戦略の概要（1～3 文）
ITEMS_DATA	統合項目の配列（下記の形式を参照）
DATA_FLOWS_DATA	データフロー図の配列（下記の形式を参照）
RATIONALE_DATA	設計の根拠となる項目の配列（icon、title、desc）

ITEMS_DATA の形式：

{
  "name": "Create PayPal Order",
  "approach": "webapi|aiwebapi|serverlogic|cloudflow",
  "description": "What this item does",
  "reasoning": "Why this approach was chosen",
  "phase": 1,
  "status": "new|existing|extends",
  "complexity": "low|medium|high",
  "depends": "Name of item this depends on (if any)",
  "details": [
    { "label": "Endpoint", "value": "/_api/serverlogics/create-paypal-order" },
    { "label": "Secrets", "value": "PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET" }
  ],
  "docs": [
    { "label": "Server Logic Overview", "url": "https://learn.microsoft.com/..." }
  ]
}

フェーズの割り当てルール — 依存関係に基づいて、各項目に phase 番号を割り当てます。

1. 依存関係のない項目は、そのアプローチに適した最も早いフェーズに割り当てます
2. 他の項目に依存する項目は、その依存先より後のフェーズに割り当てます
3. 同じフェーズの項目同士には依存関係がなく、並行して実装できます
4. 推奨されるデフォルトの順序：まずサーバーロジックの基盤（状態遷移用の検証・実行エンドポイント、バッチクエリ）、次に機密性のないフィールドの Web API CRUD（読み取り、安全なデフォルト値を使った作成、ビジネスルールのないフィールドの更新）、続いて高度なサーバーロジック（複数テーブルのトランザクション）、次に AI Web API（Web API で設定したテーブルを対象とする要約や根拠に基づく検索）、最後に Cloud Flows（非同期の後続処理）
5. セキュリティ上の制約：Web API 項目で、サーバーロジック項目が適用するビジネスルールによって値が決まるフィールドを書き込んではいけません。フィールドに検証が必要な場合は、サーバーロジック項目がそのフィールドに直接書き込む必要があります。Web API 項目の対象範囲からは、そのフィールドを除外します
6. AI のレイヤー化に関する制約：Web API 項目でも対象となっている Dataverse テーブルの AI Web API 項目は、その Web API 項目より後のフェーズに割り当てる必要があります。AI Web API の Data Summarization エンドポイントでは、Web API の Layer 1/2 の前提条件（テーブルのアクセス許可、Webapi/<table>/* サイト設定）を再利用します。Search Summary 項目にはテーブルごとの前提条件がないため、どのフェーズにも割り当てられます

DATA_FLOWS_DATA の形式（各ステップの approach は webapi、aiwebapi、serverlogic、cloudflow のいずれかです）：

{
  "trigger": "User registers and pays",
  "description": "User fills the form, pays via PayPal, receives confirmation",
  "steps": [
    { "approach": "serverlogic", "name": "Validate Seats", "detail": "Check availability" },
    { "approach": "serverlogic", "name": "Create Order", "detail": "Server calls PayPal" },
    { "approach": "cloudflow", "name": "Send Email", "detail": "Async confirmation" }
  ]
}

重要：データフロー図で、サーバーロジックのステップがビジネスルールを検証する場合、次のステップを同じフィールドへの Web API 書き込みにしてはいけません。サーバーロジックのステップで検証と実行の両方を行う必要があります。例：

// ✅ Correct — server logic validates and writes status
{ "approach": "serverlogic", "name": "Submit Order", "detail": "Validates Draft→Submitted, writes new status" }

// ❌ Incorrect — split across server logic validation and Web API write
{ "approach": "serverlogic", "name": "Validate Transition", "detail": "Checks Draft→Submitted" },
{ "approach": "webapi", "name": "Update Status", "detail": "PATCH status to Submitted" }

プランを <PROJECT_ROOT>/docs/backend-plan.html に書き込みます（必要に応じて docs/ を作成します）。レンダースクリプトを使用します。

node "${PLUGIN_ROOT}/scripts/render-backend-plan.js" --output "<OUTPUT_PATH>" --data "<DATA_JSON_PATH>"

レンダースクリプトは既存ファイルの上書きを拒否します。デフォルトのパスにファイルが存在する場合は、新しい説明的なファイル名（例：backend-plan-payments.html）を選びます。

レンダリング後、ユーザーのデフォルトブラウザーで HTML プランを開きます。

open "<OUTPUT_PATH>"  # macOS
# start "<OUTPUT_PATH>"  # Windows
# xdg-open "<OUTPUT_PATH>"  # Linux

3.3 プランの概要を提示する

CLI でプラン全体を繰り返してはいけません。HTML ファイルを、詳細なプランを記載した唯一の成果物とします。

CLI では、次の簡潔な概要のみを提示します。

• 項目の合計数と、アプローチごとの項目数
• 使用するアプローチが 1 つか、複数の組み合わせか
• 実際の出力パス
• ブラウザーで開いた HTML に、データフロー図を含む詳細が記載されていることを示す注記

3.4 ユーザーに確認する

🚦 ゲート（計画 · integrate-backend:3.4.plan-approval）： 適切な子スキル（integrate-webapi / add-server-logic / add-cloud-flow）を呼び出す前に、統合計画を承認してください。計画の HTML は選択内容にかかわらずディスクに保存されます。キャンセルすると、ディスパッチのみが停止します。

トリガー： フェーズ 3.3 で HTML の計画が生成され、簡潔な CLI の概要が表示されていること。 確認する理由： 間違った子スキルがディスパッチされる可能性があります。Web API のタスクに add-server-logic を使うと数分の時間が無駄になり、Web API のタスクに add-cloud-flow を使うと孤立したフロー YAML が作成されます。 キャンセルした場合： 何も起こりません。子スキルは呼び出されず、HTML の計画は保存先のパスに残ります。

AskUserQuestion を使用します。

質問	選択肢
統合計画はこちらです。HTML の計画をブラウザーで開いています。データフロー図と各項目の理由が記載されています。この方針で問題ありませんか？	はい、続行（推奨）、方針を変更、キャンセル

「方針を変更」の場合：希望する方針とその理由を尋ね、計画を更新して、再度提示します。

「キャンセル」の場合：ワークフローを停止します。

出力：ユーザーが承認した統合方針

---

フェーズ 4：スキルに振り分ける

目標：フェーズの順序を守り、各フェーズ内では並列に実行して、承認された方針を実装するための適切なスキルを呼び出します。

アクション：

4.1 フェーズ実行計画を作成する

計画に記載された phase 番号ごとに、承認された項目をまとめます。各フェーズは独立した項目のまとまりです。フェーズ内の項目は互いに依存関係がなく、並列に実装できます。

方針	呼び出すスキル	渡す内容
Web API	/integrate-webapi	ユーザーのリクエスト + このフェーズのテーブル + 既存のパターン
AI Web API	/add-ai-webapi	ユーザーのリクエスト + このフェーズの対象ページ／テーブル + 使用する 2 つの API（Search Summary または Data Summarization）のどちらか + トリガー設定（リストの要約をマウント時に自動実行するか、手動ボタンにするか）。対象のテーブルで Web API の前提条件を以前のフェーズですでに設定している場合は、そのことを伝えて、AI スキルが Layer 1/2 への委任をスキップできるようにします。
サーバーロジック	/add-server-logic	ユーザーのリクエスト + このフェーズのエンドポイント + 必要な SDK 機能 + 特定したシークレット + フェーズ 1.3 の一致する Dataverse カスタムアクション
クラウドフロー	/add-cloud-flow	ユーザーのリクエスト + このフェーズの非同期処理

4.2 フェーズごとに実行する

フェーズは順番に処理してください（フェーズ 1、次にフェーズ 2、という順です）。次のフェーズに進む前に、そのフェーズの項目をすべて完了してください。後続のフェーズは前のフェーズに依存しています。

各フェーズ内では、並列性を最大限に高めてください。

• フェーズ内のアプローチが 1 つの場合：そのフェーズのすべての項目をまとめてスキルを 1 回呼び出します。スキルには次のように伝えてください：「この N 個の項目は互いに独立しているため、可能な限り並列で実装してください。」
• 同じフェーズ内に複数のアプローチがある場合：各スキルを、それぞれの項目について呼び出します。同じフェーズ内の項目には相互依存関係がないため、フェーズ内でスキルを呼び出す順序は問いません。2 つ目のスキルを呼び出す際は、最初のスキルからのコンテキストを渡し、同じフロントエンドのパターン（命名規則やファイル構成など）に従えるようにします。

例 — 4 つのフェーズがある計画：

フェーズ	項目	スキル	並列処理
1	Validate Transition（serverlogic）、Dashboard Metrics（serverlogic）	/add-server-logic	両方の項目をまとめて渡し、スキルが並列で構築します
2	Supplier Updates（webapi）、Bid CRUD（webapi）、PR Creation（webapi）	/integrate-webapi	3 つすべての項目をまとめて渡し、スキルが並列で構築します
3	Award Bid（serverlogic）	/add-server-logic	1 つの項目を順次処理します
4	Approval Notification（cloudflow）、Expiry Alerts（cloudflow）	/add-cloud-flow	両方の項目をまとめて渡し、スキルが並列で構築します

各スキルを呼び出す際は、次の内容を含めてください。

1. 実装する項目 — このフェーズで計画に記載されている具体的な項目名を列挙します
2. 並列処理の指示 — 「これらの項目は同じフェーズにあり、相互に依存していません。可能な限り並列で実装してください。」
3. 前のフェーズからのコンテキスト — スキルがそれを基に構築できるよう、これまでに作成したもの（ファイル、パターン、サービス）を示します

4.3 概要

すべてのフェーズが完了したら、作成したものの概要を簡潔に提示してください。

フェーズ	アプローチ	作成したもの
1	サーバーロジック	[作成したエンドポイント、使用した SDK 機能]
2	Web API	[作成したファイル、統合したテーブル]
3	サーバーロジック	[作成したエンドポイント]
4	Cloud Flow	[登録したフロー、接続したトリガー]

まだデプロイしていない場合は、/deploy-site でデプロイするようユーザーに伝えてください。

4.4 スキルの使用状況を記録する

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

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

出力：推奨されるバックエンド統合をすべて実装済み

---

重要な注意事項

このスキルを使用しない場合

ユーザーの依頼が明確かつ曖昧さなく単一のアプローチに対応する場合は、このスキルをスキップして、実装スキルを直接実行してください。

• 「次のためのサーバーロジックエンドポイントを作成」→ /add-server-logic
• 「contacts テーブルに Web API を統合」→ /integrate-webapi
• 「メール送信用のクラウドフローを追加」→ /add-cloud-flow
• 「ケース詳細ページに AI による要約を追加」／「未解決のケースを要約」／「このページで KB 記事を提案」→ /add-ai-webapi

このスキルは、ユーザーがビジネス上の課題を説明し、適切なアプローチの選択に支援が必要な曖昧な依頼を対象としています。

例：ルーティングの例

例 1：シンプルな Dataverse CRUD → Web API

User: I need to show a list of products on the homepage and let users
      filter by category.

Recommendation: Web API
Reason: This is straightforward Dataverse read operations with filtering.
        No external APIs, no secrets, no server-side logic needed.
Skill: /integrate-webapi

例 2：認証情報を使用する外部 API → サーバーロジック

User: Add payment processing through Stripe. The API key must stay
      on the server.

Recommendation: Server Logic
Reason: Calls an external API (Stripe) with credentials that must be
        protected. Server logic hides the code and credentials from
        the browser.
Skill: /add-server-logic

例 3：バックグラウンドでのメール送信 → クラウドフロー

User: When a user submits the contact form, send them a confirmation
      email and notify the support team on Teams.

Recommendation: Cloud Flow
Reason: Email and Teams notifications are async — the user doesn't
        need to wait for them. Cloud Flows have built-in connectors
        for Outlook and Teams.
Skill: /add-cloud-flow

例 4：サーバー側の検証 → サーバーロジック（検証して実行）

User: Add validation that rejects orders when quantity exceeds
      inventory. Check the actual Dataverse data, not just the form.

Recommendation: Server Logic (validate-and-execute)
Reason: Server-side validation that can't be bypassed from the browser.
        The server logic checks inventory AND creates/updates the order
        in a single call — the client doesn't write the order via Web API
        because quantity validation would be bypassable.
Skill: /add-server-logic

例 5：ダッシュボードのパフォーマンス → サーバーロジック

User: The dashboard makes 3 separate API calls to load contacts,
      orders, and products. It's slow.

Recommendation: Server Logic
Reason: Batching multiple Dataverse queries into a single server
        endpoint reduces round-trips and improves load time.
Skill: /add-server-logic

例 6：CRUD ＋ バックグラウンド処理 → Web API ＋ クラウドフロー

User: Let users submit support tickets from the portal. After
      submission, assign it to the right team and send an email.

Recommendation: Web API + Cloud Flow
Reason: The ticket creation is a Dataverse write (Web API). The
        assignment and email happen in the background after the
        user submits (Cloud Flow).
Phases: Phase 1 → /integrate-webapi (ticket CRUD)
        Phase 2 → /add-cloud-flow (assignment + email, depends on ticket creation)

例 7：検証 ＋ 処理 ＋ 通知 → サーバーロジック ＋ クラウドフロー

User: When a user places an order, validate inventory, process the
      payment through Stripe, and send a confirmation email.

Recommendation: Server Logic + Cloud Flow
Reason: Inventory validation and Stripe payment need real-time
        server-side processing with credentials (Server Logic).
        The confirmation email is async (Cloud Flow).
Phases: Phase 1 → /add-server-logic (validate inventory + process payment — parallel)
        Phase 2 → /add-cloud-flow (confirmation email, depends on payment)

例 8：状態遷移 ＋ CRUD → サーバーロジック（検証して実行）＋ Web API

User: Build a procurement workflow with status transitions
      (Draft → Submitted → Approved) and let users edit request details.

Recommendation: Server Logic + Web API
Reason: Status transitions must be tamper-proof — server logic validates
        the transition AND writes the new status to Dataverse in one call
        (the Secure Action Principle). Editing non-sensitive fields like
        description or notes is safe via Web API since no business rule
        governs those writes.
Phases: Phase 1 → /add-server-logic (transition-request endpoint that
          validates AND writes status changes)
        Phase 2 → /integrate-webapi (read/list requests, edit description
          and notes — but NOT status, which goes through server logic)

NOTE: The Web API item must NOT include the status field in its Update
      operations. Status writes go exclusively through the server logic
      endpoint.

例 9：詳細ページでの AI 要約 → AI Web API（データ要約、サポートケースのレシピ）

User: Add an AI-generated summary card to the case detail page that
      includes the comments customers have posted.

Recommendation: AI Web API — Data Summarization
Reason: Microsoft Learn documents a ready-made Data Summarization
        configuration for this scenario on the standard incident table —
        POST to /_api/summarization/data/v1.0/incidents(<id>) with
        InstructionIdentifier "Summarization/prompt/case_summary" and
        $expand=incident_adx_portalcomments($select=description). The
        user can adopt this verbatim or tweak the columns / prompt for
        their own case-handling UX.
Skill: /add-ai-webapi

例 10：詳細ページでの関連ナレッジベース記事 → AI Web API（検索の要約）

User: On the case detail page, show relevant KB articles to help
      agents find answers faster.

Recommendation: AI Web API (Search Summary for related-record discovery)
Reason: Search Summary's grounded retrieval returns AI-ranked citations
        from the site's knowledge index — a much better fit than a
        hand-rolled OData keyword match on the knowledge article table.
        The citations rewrite into SPA routes for clean deep-linking.
Skill: /add-ai-webapi

例 11：一覧の要約 ＋ 閲覧可能なレコード → Web API ＋ AI Web API

User: On the dashboard, show the list of open cases from Dataverse
      and an AI summary highlighting the most common issue themes.

Recommendation: Web API + AI Web API
Reason: The list is direct Dataverse reads — Web API handles pagination,
        filtering, and status badges. The summary is a list-form Data
        Summarization call with $filter=statecode eq 0 using the tabular-
        insight prompt pattern. Web API item goes in Phase 1 because AI
        Web API reuses its Layer 1/2 prereqs (table permissions, Webapi
        site settings for the incident table).
Phases: Phase 1 → /integrate-webapi (incident list CRUD for the dashboard)
        Phase 2 → /add-ai-webapi (list summary for open cases, reuses
          Phase 1's Layer 1/2 — the AI skill detects this and skips its
          Web API delegation)

進捗の追跡

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

タスクの件名	activeForm	説明
サイトの存在を確認	サイトの前提条件を確認中	プロジェクトのルートを特定し、既存のバックエンド統合をスキャンします
ビジネス上の課題を把握	要件を分析中	ユーザーのニーズを特定し、不明点を明確にします
統合方法を推奨	アプローチを評価中	判断フレームワークを適用し、推奨案を提示します
実装スキルに引き継ぎ	バックエンド統合を実装中	承認されたスキルを実行し、結果を要約します

各タスクの開始時に TaskUpdate で in_progress に設定し、完了時に completed に設定します。

---

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