peterruiter/claude-build-framework

構建 Dataverse / Dynamics 365 整合

指南位於 docs/integrations-dynamics.md：先閱讀它；此技能是工作順序。將其規劃為一個 wave（waves-and-agents.md）；一旦契約（資料表、連接器介面、設定名稱）撰寫完成，引擎、連接器、模擬環境和管理員 UI 可以成為並行代理程式。

1. 詢問客戶（一條訊息，帶編號，每條附有建議）

1. 哪些流程，方向為何： 哪些產品記錄成為哪些 Dataverse 資料列（聯絡人、潛在客戶、時間軸上的備註、Customer Insights - Journeys 事件資料表、自訂觸發器），以及是否有任何資料被讀回（靜態行銷清單、選擇退出）。預設：單向，從產品到 Dynamics，加上在要求時讀取靜態清單。
2. 登入模型： 建議使用產品自己的多租戶應用程式，搭配管理員同意和一個具有自訂最低權限角色的應用程式使用者；保留每個客戶的應用程式註冊（首選憑證）作為備用方案。詢問服務是否可以使用受控識別作為同盟憑證（無密碼）或需要憑證。
3. 哪個 Entra 租用戶託管多租戶應用程式，誰註冊它，誰完成發行者驗證。（客戶執行此操作；你準備步驟。）
4. 比對規則： 聯絡人透過電子郵件比對（所有三個資料行，先比對作用中的）；除非對應為「取代」，否則絕不覆寫非空的 CRM 欄位；僅在唯一且精確的名稱上連結帳戶；絕不建立帳戶。確認或調整。
5. 同意： 客戶在同步任何內容之前確認其隱私權通知；在同意問題上設為閘門或否；除非產品是給予同意的地方，且客戶決定寫入聯絡要點同意記錄，否則絕不寫入行銷同意。
6. 歷程： 是否需要自訂觸發器，用於哪些訊號（已註冊、已取消、已報到、已捕獲潛在客戶...），或者同步記錄上的現成業務觸發器就足夠了？
7. 用於測試的正式環境： 哪一個（偏好專用的沙箱/試用版）、範圍（記錄上限、一個測試觸發器）、以及確認未經單獨批准不得變更任何結構描述、解決方案、安全性角色或應用程式註冊。

將決策記錄在 STATE.md 中，將 wave 記錄在 ROADMAP.md 中。

2. 契約與資料模型

• 資料表：連線（每個工作區/租用戶和環境：URL、租用戶 ID、登入類型、保存庫密碼名稱、提示和到期日、狀態、暫停至、探查結果 JSON、設定/對應 JSON、隱私權確認者/時間）、同步項目（每筆記錄一行：類型、來源 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 的憑證判斷、平台應用程式、僅在開發環境中的開發人員 az 權杖）、按雜湊快取，直到到期前 5 分鐘、在收到 401 時忘記並重試一次、將 Entra 的第一個錯誤行傳遞給 UI。
3. 探查： WhoAmI、RetrieveVersion()、實體集、具有可寫入性和最大長度的屬性、多對一導覽屬性名稱、準備好的自訂觸發器及其參數；僅在其資料表存在時提供模式。
4. 寫入： 聯絡人比對然後 upsert，並啟用重複偵測、唯一時連結帳戶、透過 PATCH 到確定性 ID 的備註和擁有的記錄、僅建立的潛在客戶（If-None-Match: *）、使用 If-Match: *（或 ETag，當人員編輯相同欄位時）的更新、statecode 搭配 statuscode、將自訂觸發器作為未繫結動作，並填滿每個屬性。
5. 引擎： 掛鉤加上掃描、跨複本宣告（一個人按序列處理資料列、相依性優先）、具有死信佇列的重試排程、429 暫停連線，時間為 Retry-After、每個連線的並發上限、$batch 中的回填（獨立請求、Prefer: odata.continue-on-error、小批次）、中斷連線。
6. 每種設定語言的管理員 UI： 連線精靈（環境、使用平台應用程式的管理員同意連結進行登入、測試顯示找到的模式、同步內容、根據實際資料行驗證的對應、哪些事件/範圍、隱私權確認）、連線頁面（狀態、記錄、重試失敗、取代憑證、憑證到期日）、每筆記錄的行，帶有「在 Dynamics 中開啟」和「再次同步」、以及一個「如何連線」說明抽屜，列出確切的角色權限和 Power Platform 管理中心步驟。
7. 警示： 當 CRM 在更新後拒絕登入時，向工作區管理員發送一次電子郵件。

4. 測試

• 先使用模擬環境： 複製 templates/project/tests/standins/dataverse.mjs 及其測試到 tests/standins/，使用你的資料表擴展它（模式在 testing.md 中）：權杖端點、中繼資料、帶有 upsert 和條件標頭的 CRUD、未繫結動作、$batch、類似 Dataverse 的驗證、節流控制、失敗、權杖到期和狀態。用於單元測試的假 HTTP 處理器孿生。
• 來自指南清單的單元和資料庫測試。在桌面和手機寬度、淺色和深色模式下，以兩種語言檢查精靈和連線頁面的瀏覽器。
• 在正式環境執行之前，回報為**「僅針對模擬環境驗證」**。
• 僅在客戶明確同意該環境和範圍後，才使用真實沙箱： 權杖透過 az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID>（絕不切換預設帳戶或 pac 設定檔）、帶有執行 ID 和硬上限的標記記錄、記錄每個建立的 ID、來自指南的檢查順序、按記錄 ID 進行清理、之後計數為零、以及一份關於已建立和移除內容的簡短報告。

5. 客戶核對清單（提供，不要執行）

• 註冊多租戶應用程式（或決定不註冊），新增其憑證（同盟受控識別或憑證），並將任何密碼放入保存庫，使用約定的名稱；設定用戶端 ID 設定。
• 發行者驗證。
• 將最低權限角色打包為客戶的受控解決方案（可選但建議）。
• 對於每個客戶：管理員同意連結、具有該角色的應用程式使用者、環境 URL 和租用戶 ID 進入產品、測試。

6. 記錄

STATE.md：已構建的內容、模式、在哪裡執行過、以及一個未驗證資料表（正式環境、導覽屬性名稱、選用模組中需要的資料行、重複偵測的真實答案、帶有變更集的 $batch、真實的自訂觸發器、節流、管理員同意和客戶租用戶中的憑證）。當它們被證實時，更新指南的 (確認) 標記。每個版本每種語言的新功能條目。

規則

• 未經客戶明確同意執行該確切動作，不得進行任何正式環境呼叫、結構描述/解決方案/角色/應用程式註冊/同意變更，或刪除你未建立的記錄。
• 不得在程式碼、日誌、聊天、提交或報告中出現密碼；僅能放在保存庫。記錄主機、狀態、錯誤代碼。
• 在共享的任何內容中使用佔位符：<ENV>.crm4.dynamics.com、<TENANT_ID>、<CLIENT_ID>。
• 任何地方都不要有 AI 屬性說明。