peterruiter/claude-build-framework

Dataverse / Dynamics 365 統合の構築

ガイドは docs/integrations-dynamics.md にあります。最初に読んでください。このスキルは作業の順序です。これをウェーブとして計画してください（waves-and-agents.md）。契約（テーブル、コネクタインターフェース、設定名）が記述された後、エンジン、コネクタ、スタンドイン、管理UIは並行エージェントとして動作できます。

1. オーナーに確認（1メッセージ、番号付き、各推奨事項付き）

1. 何がどの方向に流れるか: どの製品レコードがどのDataverse行（連絡先、リード、タイムライン上のメモ、Customer Insights - Journeysイベントテーブル、カスタムトリガー）になるか、そして何かが読み戻されるか（静的マーケティングリスト、オプトアウト）を決定します。デフォルト：一方向、製品からDynamicsへ。ただし、要求があれば静的リストの読み取りも行います。
2. サインインモデル: 製品独自のマルチテナントアプリ（管理者同意とカスタム最小権限ロールを持つアプリケーションユーザー）を推奨します。顧客ごとのアプリ登録（証明書推奨）はフォールバックとして保持します。サービスがマネージドIDをフェデレーション資格情報として使用できるか（シークレットなし）、それとも証明書が必要かを確認します。
3. マルチテナントアプリをホストするEntraテナント、誰が登録するか、誰が発行元確認を完了するか。（オーナーが行います。あなたは手順を準備します。）
4. マッチングルール: 連絡先はメールでマッチング（3つの列すべて、アクティブが優先）。空でないCRMフィールドを「置換」とマッピングされていない限り上書きしない。アカウントのリンクは一意の完全一致名のみ。アカウントを作成しない。確認または調整します。
5. 同意: 顧客は同期前にプライバシー通知を確認します。同意質問でゲートするかしないか。同意が与えられた製品であり、オーナーがコンタクトポイント同意レコードを書き込むと決定した場合を除き、マーケティング同意を書き込まない。
6. ジャーニー: カスタムトリガーが必要か（登録、キャンセル、チェックイン、リードキャプチャなど、どのシグナルに対して）、または同期されたレコードの標準ビジネストリガーで十分か。
7. テスト用の実際の環境: どれか（専用サンドボックス/トライアルを推奨）、範囲（レコード上限、1つのテストトリガー）、およびスキーマ、ソリューション、セキュリティロール、アプリ登録の変更は別途OKなしでは許可されないという確認。

決定事項をSTATE.mdとウェーブをROADMAP.mdに記録します。

2. 契約とデータモデル

• テーブル: 接続（ワークスペース/テナントおよび環境ごと：URL、テナントID、サインインの種類、ボールトシークレット名、ヒントと有効期限、ステータス、一時停止期限、プローブ結果JSON、設定/マッピングJSON、プライバシー確認者/日時）、同期アイテム（レコードごとに1行：種類、ソースID、CRMテーブルとID、バージョン、クレームバージョン、試行回数、次回試行時刻、最終エラー、最終シグナル）、イベント/スコープごとのリンク（含まれる、リンクされたCRMイベント、キャンペーン、同意質問、選択されたスポンサーまたはソース）、バックフィルカーソル、同期ログ（30日間）。
• コネクタインターフェース（CRMに依存しない）: Probe、Write(rows) -> results (Synced | Retry | Throttled(RetryAfter) | Refused)、Lookup（イベント、キャンペーン、リスト）、RecordLink、デフォルトマッピング、独自の列。CRMが返した回答に対して例外をスローしない。
• 設定: ログインベースURL（ラップトップ上のスタンドイン）、プラットフォームクライアントID、ボールトシークレット名。これらを設定契約（contracts.md）に追加します。

3. 以下の順序でビルド

1. ネットワークなしのドメインルール: 環境URL検証（Dataverseホスト（ソブリンクラウド含む）、https、パスなし）、Web APIルート（/api/data/v9.2/）、トークンスコープ（https://<ENV>/.default）、ODataリテラルエスケープ、エラー解析（コード、メッセージ）、$batchライターとリーダー（変更セット読み取り対応）、決定論的ID（ワークスペース、ホスト、種類、ソースIDのUUID v5）、レコードディープリンク（main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...）。単体テスト。
2. トークン: クライアント資格情報（シークレット、x5t#S256による証明書アサーション、プラットフォームアプリ、Developmentでのみ開発者azトークン）、有効期限の5分前までハッシュでキャッシュ、401で破棄して1回再試行、最初のエラー行をUIに表示。
3. プローブ: WhoAmI、RetrieveVersion()、エンティティセット、書き込み可能性と最大長を持つ属性、多対1ナビゲーションプロパティ名、準備済みカスタムトリガーとそのパラメータ。テーブルが存在する場合のみモードを提供。
4. 書き込み: 重複検出を有効にした連絡先のマッチ→アップサート、一意な場合のアカウントリンク、ノートと所有レコードは決定論的IDへのPATCH、リードは作成のみ（If-None-Match: *）、更新はIf-Match: *（または同じフィールドを編集する場合のETag）、statecodeとstatuscode、カスタムトリガーはすべての属性を埋めた非バインドアクション。
5. エンジン: フックとスイープ、レプリカ間でのクレーム（1人の行は直列、依存関係優先）、デッドレター付き再試行スケジュール、429は接続をRetry-Afterだけ一時停止、接続ごとの同時実行上限、$batchでのバックフィル（独立リクエスト、Prefer: odata.continue-on-error、小バッチ）、切断。
6. 管理UI（すべての設定言語で）: 接続ウィザード（環境、プラットフォームアプリの管理者同意リンクによるサインイン、見つかったモード、同期内容、実際の列に対して検証されたマッピング、イベント/スコープ、プライバシー確認を示すテスト）、接続ページ（ステータス、ログ、失敗した再試行、資格情報の置換、証明書の有効期限）、レコードごとの行に「Dynamicsで開く」と「再同期」リンク、および正確なロール権限とPower Platform管理センターの手順を列挙した「接続方法」ヘルプドロワー。
7. アラート: 更新後にCRMがサインインを拒否した場合、ワークスペース管理者に1回メール送信。

4. テスト

• 最初にスタンドイン: templates/project/tests/standins/dataverse.mjsをコピーし、そのテストをtests/standins/にコピーします。テーブルを追加して拡張します（パターンはtesting.mdにあります）：トークンエンドポイント、メタデータ、upsertと条件付きヘッダーをサポートするCRUD、非バインドアクション、$batch、Dataverseライクな検証、スロットル制御、障害制御、トークン有効期限制御、状態制御。単体テスト用のフェイクHTTPハンドラツイン。
• ガイドのリストからユニットテストとデータベーステスト。ウィザードと接続ページのブラウザチェック（デスクトップと電話の幅、ライトとダーク、2言語）。
• 実際の環境が実行されるまで、「スタンドインに対してのみ検証済み」として報告します。
• 実際のサンドボックステストは、その環境と範囲についてオーナーの明示的なOKがある場合のみ：az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID> によるトークン（デフォルトアカウントやpacプロファイルを決して切り替えない）、実行IDとハードキャップでマークされたレコード、作成されたすべてのIDの記録、ガイドからのチェック順序、記録されたIDによるクリーンアップ、その後のカウントゼロ、および作成・削除されたものの短いレポート。

5. オーナーチェックリスト（提供するが、実行はしない）

• マルチテナントアプリを登録する（または登録しないと決定する）、その資格情報（フェデレーションマネージドIDまたは証明書）を追加し、合意された名前でボールトにシークレットを保存する。クライアントID設定を行う。
• 発行元確認。
• 最小権限ロールを顧客向けマネージドソリューションとしてパッケージ化する（オプションだが推奨）。
• 顧客ごとに：管理者同意リンク、ロールを持つアプリケーションユーザー、環境URLとテナントIDを製品に入力、テスト。

6. 記録

STATE.md：構築されたもの、モード、どこで何が実行されたか、および未証明テーブル（実際の環境、ナビゲーションプロパティ名、オプションモジュールの必須列、重複検出の実際の応答、変更セットを使用した$batch、実際のカスタムトリガー、スロットリング、顧客テナントでの管理者同意と証明書）。それらが証明されたときにガイドの**(確認)**マークを更新します。各言語でリリースごとの新機能エントリ。

ルール

• 実際の環境呼び出し、スキーマ/ソリューション/ロール/アプリ登録/同意の変更、または作成していないレコードの削除は、その正確なアクションに対するオーナーの明示的な許可なしに行わない。
• コード、ログ、チャット、コミット、レポートにシークレットを記述しない。ボールトのみ。ホスト、ステータス、エラーコードをログに記録する。
• 共有するもののプレースホルダー：<ENV>.crm4.dynamics.com、<TENANT_ID>、<CLIENT_ID>。
• どこにもAI帰属表示を入れない。