peterruiter/claude-build-framework

Construire une intégration Dataverse / Dynamics 365

Le guide est docs/integrations-dynamics.md : lisez-le en premier ; cette compétence est l'ordre de travail. Planifiez-la comme une vague (waves-and-agents.md) ; le moteur, le connecteur, le simulateur et l'interface d'administration peuvent être des agents parallèles une fois les contrats (tables, interface du connecteur, noms des paramètres) écrits.

1. Demander au propriétaire (un message, numéroté, chacun avec une recommandation)

1. Quels flux, dans quel sens : quels enregistrements du produit deviennent quelles lignes Dataverse (contacts, prospects, notes sur la timeline, tables d'événements Customer Insights - Journeys, déclencheurs personnalisés), et si quelque chose est lu en retour (listes marketing statiques, désabonnements). Par défaut : un sens, produit vers Dynamics, plus la lecture des listes statiques si demandé.
2. Modèle de connexion : recommander l'application multi-locataire du produit avec consentement admin et un utilisateur applicatif avec un rôle personnalisé aux privilèges minimaux ; conserver l'inscription d'application par client (certificat de préférence) comme solution de repli. Demander si le service peut utiliser une identité managée comme identité fédérée (sans secret) ou a besoin d'un certificat.
3. Quel locataire Entra héberge l'application multi-locataire, qui l'inscrit, qui effectue la vérification de l'éditeur. (Le propriétaire le fait ; vous préparez les étapes.)
4. Règles de correspondance : contacts mis en correspondance par email (les trois colonnes, actif en premier) ; ne jamais écraser les champs CRM non vides sauf si mappés "remplacer" ; lier les comptes uniquement sur un nom exact unique ; ne jamais créer de comptes. Confirmer ou ajuster.
5. Consentement : le client confirme son avis de confidentialité avant toute synchronisation ; conditionner par une question de consentement ou non ; ne jamais écrire le consentement marketing sauf si le produit est l'endroit où le consentement est donné et que le propriétaire décide d'écrire des enregistrements de consentement du point de contact.
6. Parcours (Journeys) : déclencheurs personnalisés souhaités, pour quels signaux (inscrit, annulé, enregistré, prospect capturé, ...), ou les déclencheurs métier prêts à l'emploi sur les enregistrements synchronisés suffisent-ils ?
7. Un environnement réel pour les tests : lequel (de préférence un sandbox/dédié), la portée (limite d'enregistrement, un déclencheur de test), et la confirmation qu'aucune modification de schéma, solution, rôle de sécurité ou inscription d'application n'est autorisée sans un accord séparé.

Enregistrez les décisions dans STATE.md et la vague dans ROADMAP.md.

2. Contrats et modèle de données

• Tables : connexion (par espace de travail/locataire et environnement : URL, identifiant du locataire, type de connexion, nom du secret dans le coffre, indice et expiration, statut, suspendu jusqu'à, résultat de la sonde JSON, paramètres/mappage JSON, confidentialité confirmée par/à), élément de synchronisation (une ligne par enregistrement : type, identifiant source, table CRM et identifiant, version, version revendiquée, tentatives, prochaine tentative, dernière erreur, dernier signal), lien par événement/portée (inclus, événement CRM lié, campagne, question de consentement, sponsors ou sources choisis), curseur de rembobinage, journal de synchronisation (30 jours).
• Interface du connecteur (neutre CRM) : Sonder, Écrire(lignes) -> résultats (Synchro | Réessayer | Limité(DélaiAvantRéessai) | Refusé), Rechercher (événements, campagnes, listes), LierEnregistrement, mappage par défaut, propres colonnes. Ne jamais lever d'exception pour une réponse donnée par le CRM.
• Paramètres : URL de base de connexion (simulateur sur un ordinateur portable), identifiant client de la plateforme, noms des secrets dans le coffre. Ajoutez-les au contrat de paramètres (contracts.md).

3. Construire, dans cet ordre

1. Règles métier sans réseau : validation de l'URL de l'environnement (hôtes Dataverse incl. clouds souverains, https, pas de chemin), racine de l'API Web (/api/data/v9.2/), portée du jeton (https://<ENV>/.default), échappement littéral OData, analyse des erreurs (code, message), lecteur et rédacteur $batch (avec jeux de modifications lus en premier), identifiants déterministes (UUID v5 de l'espace de travail, hôte, type, identifiant source), lien profond vers l'enregistrement (main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...). Tests unitaires.
2. Jetons : identifiants du client (secret, assertion de certificat avec x5t#S256, application de la plateforme, jeton az développeur en Développement uniquement), mise en cache par hachage jusqu'à 5 minutes avant l'expiration, oubli sur 401 et nouvelle tentative une fois, première ligne d'erreur d'Entra vers l'interface utilisateur.
3. Sonde : WhoAmI, ObtenirVersion(), ensembles d'entités, attributs avec possibilité d'écriture et longueur maximale, noms des propriétés de navigation plusieurs-à-un, déclencheurs personnalisés prêts et leurs paramètres ; modes proposés uniquement lorsque leurs tables existent.
4. Écritures : correspondance de contact puis mise à jour-insertion avec détection des doublons activée, lien de compte lorsqu'il est unique, notes et enregistrements possédés par PATCH vers des identifiants déterministes, prospects création-uniquement (If-None-Match: *), mises à jour avec If-Match: * (ou l'ETag lorsque les personnes modifient les mêmes champs), statecode avec statuscode, déclencheurs personnalisés comme actions non liées avec chaque attribut renseigné.
5. Moteur : crochets plus balayage, revendication entre réplicas (lignes d'une personne en série, dépendances en premier), planification des tentatives avec lettre morte, 429 mettant en pause la connexion pour DélaiAvantRéessai, limite de concurrence par connexion, rembobinage par $batch (requêtes indépendantes, Prefer: odata.continue-on-error, petits lots), déconnexion.
6. Interface d'administration dans chaque langue configurée : assistant de connexion (environnement, connexion avec le lien de consentement admin pour l'application de la plateforme, test montrant les modes trouvés, ce qui se synchronise, mappage validé par rapport aux colonnes réelles, quels événements/portées, confirmation de confidentialité), page de connexion (statut, journal, réessayer les échecs, remplacer les identifiants, expiration du certificat), ligne par enregistrement avec "Ouvrir dans Dynamics" et "Resynchroniser", et un tiroir d'aide "Comment se connecter" listant les privilèges de rôle exacts et les étapes du centre d'administration Power Platform.
7. Alertes : email aux administrateurs de l'espace de travail une fois lorsque le CRM refuse la connexion après renouvellement.

4. Tester

• Simulateur d'abord : copiez templates/project/tests/standins/dataverse.mjs et son test vers tests/standins/, étendez-le avec vos tables (modèle dans testing.md) : point de terminaison de jeton, métadonnées, CRUD avec mise à jour-insertion et en-têtes conditionnels, actions non liées, $batch, validation de type Dataverse, contrôles pour la limitation, les échecs, l'expiration des jetons et l'état. Un double gestionnaire HTTP factice pour les tests unitaires.
• Tests unitaires et de base de données à partir de la liste du guide. Vérifications navigateur de l'assistant et de la page de connexion aux largeurs de bureau et mobile, clair et sombre, dans deux langues.
• Signalez comme "vérifié uniquement contre le simulateur" jusqu'à ce qu'un environnement réel ait fonctionné.
• Sandbox réel uniquement avec l'accord explicite du propriétaire pour cet environnement et cette portée : jeton via az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <ID_ABONNEMENT> (ne jamais changer le compte par défaut ou le profil pac), enregistrements marqués avec un identifiant d'exécution et un plafond strict, chaque identifiant créé enregistré, l'ordre de vérification du guide, nettoyage par les identifiants enregistrés, un compte de zéro ensuite, et un court rapport de ce qui a été créé et supprimé.

5. Liste de contrôle du propriétaire (donnez-la, ne la faites pas)

• Inscrivez l'application multi-locataire (ou décidez de ne pas le faire), ajoutez son identifiant (identité managée fédérée ou certificat) et placez tout secret dans le coffre sous le nom convenu ; définissez le paramètre d'identifiant client.
• Vérification de l'éditeur.
• Empaquetez le rôle aux privilèges minimaux comme une solution managée pour les clients (optionnel mais recommandé).
• Pour chaque client : lien de consentement admin, utilisateur applicatif avec le rôle, URL de l'environnement et identifiant du locataire dans le produit, Tester.

6. Enregistrer

STATE.md : ce qui a été construit, les modes, ce qui a fonctionné où, et une table Non prouvé (environnement réel, noms des propriétés de navigation, colonnes requises dans les modules optionnels, réponse réelle de la détection des doublons, $batch avec jeux de modifications, un déclencheur personnalisé réel, la limitation, le consentement admin et un certificat dans un locataire client). Mettez à jour les marques (confirm) du guide lorsqu'elles sont prouvées. Nouveauté par version dans chaque langue.

Règles

• Aucun appel à un environnement réel, modification de schéma/solution/rôle/inscription d'application/consentement, ou suppression d'enregistrements que vous n'avez pas créés, sans l'accord explicite du propriétaire pour cette action exacte.
• Aucun secret dans le code, les journaux, le chat, les commits ou les rapports ; coffre uniquement. Enregistrez l'hôte, le statut, le code d'erreur.
• Espaces réservés dans tout ce qui est partagé : <ENV>.crm4.dynamics.com, <ID_LOCATAIRE>, <ID_CLIENT>.
• Aucune attribution IA nulle part.