peterruiter/claude-build-framework

Eine Dataverse / Dynamics 365-Integration erstellen

Die Anleitung befindet sich in docs/integrations-dynamics.md: zuerst lesen; dieser Skill ist die Arbeitsreihenfolge. Planen Sie es als Welle (waves-and-agents.md); der Kern, der Connector, der Simulator und die Admin-Oberfläche können parallele Agents sein, sobald die Verträge (Tabellen, Connector-Schnittstelle, Einstellungsnamen) geschrieben sind.

1. Fragen Sie den Auftraggeber (eine Nachricht, nummeriert, jeweils mit einer Empfehlung)

1. Welche Datenflüsse, in welche Richtung: welche Produktdatensätze werden zu welchen Dataverse-Zeilen (Kontakte, Leads, Notizen auf der Timeline, Customer Insights – Journeys-Ereignistabellen, benutzerdefinierte Trigger), und ob etwas zurückgelesen wird (statische Marketing-Listen, Opt-Outs). Standard: eine Richtung, Produkt zu Dynamics, plus Lesen statischer Listen, falls gewünscht.
2. Anmeldemodell: empfehlen Sie die eigene Multi-Tenant-App des Produkts mit Admin-Zustimmung und einem Anwendungsbenutzer mit einer benutzerdefinierten Rolle mit geringsten Rechten; behalten Sie die kundenindividuelle App-Registrierung (Zertifikat bevorzugt) als Fallback bei. Fragen Sie, ob der Dienst eine verwaltete Identität als verbundene Anmeldeinformation (geheimnislos) verwenden kann oder ein Zertifikat benötigt.
3. Welcher Entra-Mandant hostet die Multi-Tenant-App, wer registriert sie, wer führt die Herausgeberüberprüfung durch. (Der Auftraggeber macht dies; Sie bereiten die Schritte vor.)
4. Abgleichsregeln: Kontakte werden per E-Mail abgeglichen (alle drei Spalten, zuerst aktiv); CRM-Felder, die nicht leer sind, werden nur überschrieben, wenn "Ersetzen" zugeordnet ist; Konten nur bei einem eindeutigen exakten Namen verknüpfen; niemals Konten erstellen. Bestätigen oder anpassen.
5. Zustimmung: Der Kunde bestätigt seinen Datenschutzhinweis, bevor etwas synchronisiert wird; die Synchronisation an eine Zustimmungsfrage knüpfen oder nicht; niemals Marketing-Zustimmung schreiben, es sei denn, das Produkt ist der Ort, an dem die Zustimmung erteilt wird und der Auftraggeber entscheidet, Kontaktpunkt-Zustimmungsdatensätze zu schreiben.
6. Journeys: Sind benutzerdefinierte Trigger gewünscht, für welche Signale (registriert, storniert, eingecheckt, Lead erfasst, ...), oder reichen die integrierten Geschäftstrigger für die synchronisierten Datensätze aus?
7. Eine echte Umgebung zum Testen: welche (bevorzugen Sie eine dedizierte Sandbox/Testversion), den Umfang (Datensatzbegrenzung, ein Test-Trigger), und die Bestätigung, dass ohne separate Genehmigung keine Schema-, Lösungs-, Sicherheitsrollen- oder App-Registrierungsänderungen erlaubt sind.

Dokumentieren Sie die Entscheidungen in STATE.md und die Welle in ROADMAP.md.

2. Verträge und Datenmodell

• Tabellen: Verbindung (pro Workspace/Mandant und Umgebung: URL, Mandanten-ID, Anmeldeart, Vault- Geheimnisname, Hinweis und Ablauf, Status, pausiert-bis, Sondierungsergebnis-JSON, Einstellungen/Zuordnungs-JSON, Datenschutz bestätigt von/um), Sync-Element (eine Zeile pro Datensatz: Art, Quell-ID, CRM-Tabelle und ID, Version, beanspruchte Version, Versuche, nächster Versuch, letzter Fehler, letztes Signal), pro Ereignis/Bereichs-Link (eingeschlossen, verknüpftes CRM-Ereignis, Kampagne, Zustimmungsfrage, gewählte Sponsoren oder Quellen), Nachhol-Cursor, Sync-Protokoll (30 Tage).
• Connector-Schnittstelle (CRM-neutral): Probe, Write(rows) -> results (Synced | Retry | Throttled(RetryAfter) | Refused), Lookup (Ereignisse, Kampagnen, Listen), RecordLink, Standardzuordnung, eigene Spalten. Niemals eine Ausnahme für eine Antwort werfen, die das CRM gegeben hat.
• Einstellungen: Login-Basis-URL (Simulator auf einem Laptop), Plattform-Client-ID, Vault-Geheimnisnamen. Fügen Sie sie dem Einstellungsvertrag hinzu (contracts.md).

3. Erstellen, in dieser Reihenfolge

1. Domänenregeln ohne Netzwerk: Umgebungs-URL-Validierung (Dataverse-Hosts einschließlich souveräner Clouds, https, kein Pfad), Web-API-Stammverzeichnis (/api/data/v9.2/), Token-Bereich (https://<ENV>/.default), OData-Literal-Escaping, Fehleranalyse (Code, Nachricht), $batch-Schreiber und -Leser (mit Änderungssätzen durchgelesen), deterministische IDs (UUID v5 von Workspace, Host, Art, Quell-ID), Datensatz- Deep-Link (main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...). Komponententests.
2. Token: Client-Anmeldeinformationen (Geheimnis, Zertifikatsbestätigung mit x5t#S256, Plattform-App, Entwickler-az-Token nur in der Entwicklung), Cache nach Hash bis 5 Minuten vor Ablauf, bei 401 vergessen und einmal wiederholen, erste Fehlerzeile von Entra an die Benutzeroberfläche.
3. Sondierung: WhoAmI, RetrieveVersion(), Entitätssätze, Attribute mit Beschreibbarkeit und maximaler Länge, Many-to-One-Navigationseigenschaftsnamen, fertige benutzerdefinierte Trigger und deren Parameter; Modi werden nur angeboten, wenn ihre Tabellen existieren.
4. Schreibvorgänge: Kontakt-Match-dann-Upsert mit aktivierter Dublettenprüfung, Kontoverknüpfung bei Eindeutigkeit, Notizen und im Besitz befindliche Datensätze durch PATCH auf deterministische IDs, Leads nur-Erstellen (If-None-Match: *), Aktualisierungen mit If-Match: * (oder dem ETag, wo Personen dieselben Felder bearbeiten), statecode mit statuscode, benutzerdefinierte Trigger als ungebundene Aktionen mit jedem gefüllten Attribut.
5. Engine: Hooks plus Sweep, Anspruch über Repliken hinweg (die Zeilen einer Person seriell, Abhängigkeiten zuerst), Wiederholungsplan mit Dead Letter, 429 pausiert die Verbindung für Retry-After, Parallelitätsbegrenzung pro Verbindung, Nachholen in $batch (unabhängige Anforderungen, Prefer: odata.continue-on-error, kleine Batches), Trennen.
6. Admin-Oberfläche in jeder konfigurierten Sprache: Verbindungsassistent (Umgebung, Anmeldung mit dem Admin-Zustimmungs-Link für die Plattform-App, Test, der die gefundenen Modi anzeigt, was synchronisiert wird, Zuordnung gegen echte Spalten validiert, welche Ereignisse/Bereiche, Datenschutzbestätigung), Verbindungsseite (Status, Protokoll, Fehlgeschlagene wiederholen, Anmeldeinformationen ersetzen, Zertifikatsablauf), pro-Datensatz-Zeile mit "In Dynamics öffnen" und "Erneut synchronisieren" sowie einem "Wie verbinden"-Hilfebereich, der die genauen Rollenberechtigungen und Power Platform Admin Center-Schritte auflistet.
7. Warnungen: Einmalige E-Mail an die Workspace-Administratoren, wenn das CRM die Anmeldung nach der Erneuerung verweigert.

4. Testen

• Simulator zuerst: Kopieren Sie templates/project/tests/standins/dataverse.mjs und dessen Test nach tests/standins/, erweitern Sie es um Ihre Tabellen (Muster in testing.md): Token-Endpunkt, Metadaten, CRUD mit Upsert und bedingten Headern, ungebundene Aktionen, $batch, Dataverse-ähnliche Validierung, Steuerungen für Drosselung, Fehler, Token-Ablauf und Status. Ein gefälschter HTTP-Handler-Zwilling für Komponententests.
• Komponenten- und Datenbanktests von der Liste der Anleitung. Browserprüfungen des Assistenten und der Verbindungsseite in Desktop- und Telefonbreite, hell und dunkel, in zwei Sprachen.
• Melden Sie als "nur gegen den Simulator verifiziert", bis eine echte Umgebung ausgeführt wurde.
• Echte Sandbox nur mit ausdrücklicher Genehmigung des Auftraggebers für diese Umgebung und diesen Umfang: Token über az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID> (niemals das Standardkonto oder pac-Profil wechseln), markierte Datensätze mit einer Lauf-ID und einer harten Obergrenze, jede erstellte ID aufgezeichnet, die Prüfreihenfolge aus der Anleitung, Bereinigung nach aufgezeichneten IDs, eine Anzahl von null danach und ein kurzer Bericht darüber, was erstellt und entfernt wurde.

5. Checkliste für den Auftraggeber (geben, nicht selbst erledigen)

• Registrieren Sie die Multi-Tenant-App (oder entscheiden Sie sich dagegen), fügen Sie ihre Anmeldeinformationen (verbundene verwaltete Identität oder Zertifikat) hinzu und legen Sie alle Geheimnisse unter dem vereinbarten Namen im Tresor ab; setzen Sie die Client-ID-Einstellung.
• Herausgeberüberprüfung.
• Packen Sie die Rolle mit den geringsten Rechten als verwaltete Lösung für Kunden (optional, aber empfohlen).
• Für jeden Kunden: Admin-Zustimmungs-Link, Anwendungsbenutzer mit der Rolle, Umgebungs-URL und Mandanten-ID in das Produkt, Testen.

6. Aufzeichnen

STATE.md: Was erstellt wurde, Modi, was wo lief, und eine Tabelle "Unbewiesen" (echte Umgebung, Navigationseigenschaftsnamen, erforderliche Spalten in optionalen Modulen, die tatsächliche Antwort der Dublettenprüfung, $batch mit Änderungssätzen, ein echter benutzerdefinierter Trigger, Drosselung, Admin-Zustimmung und ein Zertifikat in einem Kundenmandanten). Aktualisieren Sie die (bestätigen)-Markierungen der Anleitung, sobald sie bestätigt sind. Eintrag "Was ist neu" pro Release in jeder Sprache.

Regeln

• Keine Aufrufe echter Umgebungen, Schema-/Lösungs-/Rollen-/App-Registrierungs-/Zustimmungsänderungen oder Löschungen von Datensätzen, die Sie nicht erstellt haben, ohne die ausdrückliche Freigabe des Auftraggebers für genau diese Aktion.
• Keine Geheimnisse in Code, Protokollen, Chat, Commits oder Berichten; Nur Tresor. Protokollieren Sie Host, Status und Fehlercode.
• Platzhalter in allem, was geteilt wird: <ENV>.crm4.dynamics.com, <TENANT_ID>, <CLIENT_ID>.
• Keine KI-Zuschreibung an irgendeiner Stelle.