peterruiter/claude-build-framework

Construir una integración con Dataverse / Dynamics 365

La guía está en docs/integrations-dynamics.md: léela primero; este skill es el orden de trabajo. Planifícalo como una ola (waves-and-agents.md); el motor, el conector, el simulador y la interfaz de administración pueden ser agentes paralelos una vez que los contratos (tablas, interfaz del conector, nombres de configuración) estén escritos.

1. Preguntar al propietario (un mensaje, numerado, cada uno con una recomendación)

1. Qué flujos, en qué dirección: qué registros del producto se convierten en qué filas de Dataverse (contactos, leads, notas en la línea de tiempo, tablas de eventos de Customer Insights - Journeys, activadores personalizados), y si se lee algo de vuelta (listas de marketing estáticas, exclusiones). Valor predeterminado: una dirección, del producto a Dynamics, más lectura de listas estáticas si se solicita.
2. Modelo de inicio de sesión: recomendar la aplicación multiinquilino del producto con consentimiento administrativo y un usuario de aplicación con un rol personalizado de privilegios mínimos; mantener el registro de aplicación por cliente (certificado preferido) como alternativa. Preguntar si el servicio puede usar una identidad administrada como credencial federada (sin secretos) o necesita un certificado.
3. Qué inquilino de Entra aloja la aplicación multiinquilino, quién la registra, quién completa la verificación del publicador. (El propietario lo hace; tú preparas los pasos).
4. Reglas de coincidencia: contactos coincidentes por correo electrónico (las tres columnas, activo primero); nunca sobrescribir campos de CRM no vacíos a menos que estén mapeados como "reemplazar"; vincular cuentas solo por un nombre exacto único; nunca crear cuentas. Confirmar o ajustar.
5. Consentimiento: el cliente confirma su aviso de privacidad antes de que se sincronice algo; bloquear con una pregunta de consentimiento o no; nunca escribir consentimiento de marketing a menos que el producto sea donde se otorga el consentimiento y el propietario decida escribir registros de consentimiento del punto de contacto.
6. Journeys: si se desean activadores personalizados, para qué señales (registrado, cancelado, check-in, lead capturado, ...), o si los activadores comerciales estándar en los registros sincronizados son suficientes.
7. Un entorno real para pruebas: cuál (preferir un espacio aislado/prueba dedicado), el alcance (límite de registros, un activador de prueba), y la confirmación de que no se permiten cambios de esquema, solución, rol de seguridad o registro de aplicación sin una aprobación separada.

Registrar las decisiones en STATE.md y la ola en ROADMAP.md.

2. Contratos y modelo de datos

• Tablas: conexión (por espacio de trabajo/inquilino y entorno: URL, id del inquilino, tipo de inicio de sesión, nombre del secreto en el almacén, pista y caducidad, estado, pausado hasta, resultado de la sonda JSON, configuración/mapeo JSON, privacidad confirmada por/en), elemento de sincronización (una fila por registro: tipo, id de origen, tabla de CRM e id, versión, versión reclamada, intentos, próximo intento, último error, última señal), enlace por evento/alcance (incluido, evento de CRM vinculado, campaña, pregunta de consentimiento, patrocinadores o fuentes elegidos), cursor de relleno, registro de sincronización (30 días).
• Interfaz del conector (neutral para CRM): Probe, Write(rows) -> results (Synced | Retry | Throttled(RetryAfter) | Refused), Lookup (eventos, campañas, listas), RecordLink, mapeo predeterminado, columnas propias. Nunca lanzar una excepción por una respuesta dada por el CRM.
• Configuración: URL base de inicio de sesión (simulador en un portátil), id de cliente de la plataforma, nombres de secretos del almacén. Añadirlos al contrato de configuración (contracts.md).

3. Construir, en este orden

1. Reglas de dominio sin red: validación de URL de entorno (hosts de Dataverse incluyendo nubes soberanas, https, sin ruta), raíz de Web API (/api/data/v9.2/), ámbito del token (https://<ENV>/.default), escape de literales OData, análisis de errores (código, mensaje), escritor y lector de $batch (con conjuntos de cambios leídos), ids deterministas (UUID v5 del espacio de trabajo, host, tipo, id de origen), enlace profundo de registro (main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...). Pruebas unitarias.
2. Tokens: credenciales de cliente (secreto, aserción de certificado con x5t#S256, aplicación de la plataforma, token az de desarrollador solo en Desarrollo), almacenar en caché por hash hasta 5 minutos antes de la caducidad, olvidar en 401 y reintentar una vez, la primera línea de error de Entra a la interfaz de usuario.
3. Sonda: WhoAmI, RetrieveVersion(), conjuntos de entidades, atributos con capacidad de escritura y longitud máxima, nombres de propiedades de navegación muchos-a-uno, activadores personalizados listos y sus parámetros; modos ofrecidos solo cuando existen sus tablas.
4. Escrituras: coincidencia de contactos y luego actualización o inserción con detección de duplicados activada, vinculación de cuentas cuando sea único, notas y registros propiedad de alguien mediante PATCH a ids deterministas, leads solo de creación (If-None-Match: *), actualizaciones con If-Match: * (o el ETag donde las personas editan los mismos campos), statecode con statuscode, activadores personalizados como acciones no enlazadas con cada atributo rellenado.
5. Motor: ganchos más barrido, reclamo entre réplicas (filas de una persona en serie, dependencias primero), programación de reintentos con buzón de mensajes no entregables, 429 pausando la conexión durante Retry-After, límite de concurrencia por conexión, relleno en $batch (solicitudes independientes, Prefer: odata.continue-on-error, lotes pequeños), desconexión.
6. Interfaz de administración en cada idioma configurado: asistente de conexión (entorno, inicio de sesión con el enlace de consentimiento administrativo para la aplicación de la plataforma, prueba mostrando los modos encontrados, qué se sincroniza, mapeo validado contra columnas reales, qué eventos/alcances, confirmación de privacidad), página de conexión (estado, registro, reintentar fallos, reemplazar credenciales, caducidad del certificado), línea por registro con "Abrir en Dynamics" y "Sincronizar de nuevo", y un panel de ayuda "Cómo conectar" que enumera los privilegios exactos del rol y los pasos del centro de administración de Power Platform.
7. Alertas: enviar correo electrónico a los administradores del espacio de trabajo una vez cuando el CRM rechace el inicio de sesión después de la renovación.

4. Pruebas

• Simulador primero: copiar templates/project/tests/standins/dataverse.mjs y su prueba a tests/standins/, extenderlo con tus tablas (patrón en testing.md): endpoint de token, metadatos, CRUD con actualización o inserción y cabeceras condicionales, acciones no enlazadas, $batch, validación similar a Dataverse, controles para limitación, fallos, caducidad de token y estado. Un gemelo de controlador HTTP falso para pruebas unitarias.
• Pruebas unitarias y de base de datos de la lista de la guía. Verificaciones en navegador del asistente y la página de conexión en anchos de escritorio y móvil, modo claro y oscuro, en dos idiomas.
• Informar como "verificado solo contra el simulador" hasta que se haya ejecutado un entorno real.
• Espacio aislado real solo con la aprobación explícita del propietario para ese entorno y alcance: token mediante az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID> (nunca cambiar la cuenta predeterminada o el perfil de pac), registros marcados con un id de ejecución y un límite estricto, cada id creado registrado, el orden de verificación de la guía, limpieza por ids registrados, un recuento de cero después, y un informe breve de lo que se creó y eliminó.

5. Lista de verificación del propietario (entregarla, no hacerla)

• Registrar la aplicación multiinquilino (o decidir no hacerlo), añadir su credencial (identidad administrada federada o certificado) y poner cualquier secreto en el almacén bajo el nombre acordado; establecer la configuración del id de cliente.
• Verificación del publicador.
• Empaquetar el rol de privilegios mínimos como una solución administrada para los clientes (opcional pero recomendado).
• Para cada cliente: enlace de consentimiento administrativo, usuario de aplicación con el rol, URL del entorno e id del inquilino en el producto, Probar.

6. Registrar

STATE.md: qué se construyó, modos, qué se ejecutó dónde, y una tabla No Probado (entorno real, nombres de propiedades de navegación, columnas requeridas en módulos opcionales, respuesta real de detección de duplicados, $batch con conjuntos de cambios, un activador personalizado real, limitación, consentimiento administrativo y un certificado en un inquilino de cliente). Actualizar las marcas (confirmar) de la guía cuando estén probadas. Nueva entrada de novedades por versión en cada idioma.

Reglas

• Sin llamadas a entornos reales, cambios de esquema/solución/rol/registro de aplicación/consentimiento, ni eliminaciones de registros que no hayas creado, sin la aprobación explícita del propietario para esa acción exacta.
• Sin secretos en código, registros, chat, commits o informes; solo en el almacén. Registrar el host, estado, código de error.
• Marcadores de posición en todo lo compartido: <ENV>.crm4.dynamics.com, <TENANT_ID>, <CLIENT_ID>.
• Sin atribución de IA en ninguna parte.