peterruiter/claude-build-framework

Criar uma integração com Dataverse / Dynamics 365

O guia está em docs/integrations-dynamics.md: leia-o primeiro; esta skill é a ordem de trabalho. Planeje-a como uma onda (waves-and-agents.md); o motor, o conector, o simulador e a interface administrativa podem ser agentes paralelos depois que os contratos (tabelas, interface do conector, nomes de configurações) forem escritos.

1. Pergunte ao proprietário (uma mensagem, numerada, cada uma com uma recomendação)

1. Quais fluxos, em qual direção: quais registros do produto se tornam quais linhas do Dataverse (contatos, leads, anotações na linha do tempo, tabelas de eventos do Customer Insights - Journeys, triggers personalizados), e se algo é lido de volta (listas de marketing estáticas, opt-outs). Padrão: uma direção, produto para Dynamics, mais leitura de listas estáticas se solicitado.
2. Modelo de login: recomende o próprio aplicativo multi-inquilino do produto com consentimento administrativo e um usuário de aplicativo com uma função personalizada de privilégio mínimo; mantenha o registro de aplicativo por cliente (certificado preferido) como alternativa. Pergunte se o serviço pode usar uma identidade gerenciada como credencial federada (sem segredo) ou precisa de um certificado.
3. Qual locatário do Entra hospeda o aplicativo multi-inquilino, quem o registra, quem conclui a verificação do editor. (O proprietário faz isso; você prepara as etapas.)
4. Regras de correspondência: contatos correspondidos por e-mail (todas as três colunas, ativo primeiro); nunca sobrescreva campos de CRM não vazios, a menos que mapeados como "substituir"; vincular contas apenas em um nome exato único; nunca criar contas. Confirme ou ajuste.
5. Consentimento: o cliente confirma seu aviso de privacidade antes de qualquer sincronização; condicione a uma pergunta de consentimento ou não; nunca escreva consentimento de marketing a menos que o produto seja onde o consentimento é dado e o proprietário decida escrever registros de consentimento do ponto de contato.
6. Jornadas: triggers personalizados desejados, para quais sinais (registrado, cancelado, check-in feito, lead capturado, ...), ou os triggers de negócio prontos para uso nos registros sincronizados são suficientes?
7. Um ambiente real para teste: qual (prefira um sandbox/dedicado de teste), o escopo (limite de registros, um trigger de teste), e a confirmação de que nenhuma alteração de esquema, solução, função de segurança ou registro de aplicativo é permitida sem uma aprovação separada.

Registre as decisões em STATE.md e a onda em ROADMAP.md.

2. Contratos e modelo de dados

• Tabelas: conexão (por workspace/tenant e ambiente: URL, id do tenant, tipo de login, nome do segredo no cofre, dica e validade, status, pausado até, JSON do resultado da sonda, JSON de configurações/mapeamento, privacidade confirmada por/em), item de sincronização (uma linha por registro: tipo, id de origem, tabela e id do CRM, versão, versão reivindicada, tentativas, próxima tentativa, último erro, último sinal), link por evento/escopo (incluído, evento CRM vinculado, campanha, pergunta de consentimento, patrocinadores ou fontes escolhidas), cursor de backfill, log de sincronização (30 dias).
• Interface do conector (neutro de CRM): Probe, Write(linhas) -> resultados (Synced | Retry | Throttled(RetryAfter) | Refused), Lookup (eventos, campanhas, listas), RecordLink, mapeamento padrão, colunas próprias. Nunca lance exceção para uma resposta que o CRM deu.
• Configurações: URL base de login (simulador em um laptop), id do cliente da plataforma, nomes de segredos no cofre. Adicione-os ao contrato de configurações (contracts.md).

3. Construir, nesta ordem

1. Regras de domínio sem rede: validação de URL do ambiente (hosts do Dataverse incluindo nuvens soberanas, https, sem caminho), raiz da Web API (/api/data/v9.2/), escopo do token (https://<ENV>/.default), escape literal OData, análise de erro (código, mensagem), escritor e leitor de $batch (com conjuntos de alterações lidos), ids determinísticos (UUID v5 do workspace, host, tipo, id de origem), link profundo de registro (main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...). Testes de unidade.
2. Tokens: credenciais de cliente (segredo, asserção de certificado com x5t#S256, aplicativo da plataforma, token az do desenvolvedor apenas em Desenvolvimento), cache por hash até 5 minutos antes do vencimento, esquecer em 401 e tentar uma vez, primeira linha de erro do Entra para a interface.
3. Sonda: WhoAmI, RetrieveVersion(), conjuntos de entidades, atributos com capacidade de gravação e tamanho máximo, nomes de propriedades de navegação muitos-para-um, triggers personalizados prontos e seus parâmetros; modos oferecidos apenas quando suas tabelas existem.
4. Escritas: correspondência de contato seguida de upsert com detecção de duplicatas ativada, vinculação de conta quando único, notas e registros de propriedade por PATCH para ids determinísticos, leads apenas criação (If-None-Match: *), atualizações com If-Match: * (ou o ETag quando pessoas editam os mesmos campos), statecode com statuscode, triggers personalizados como ações não vinculadas com todos os atributos preenchidos.
5. Motor: hooks mais varredura, reivindicação entre réplicas (linhas de uma pessoa serial, dependências primeiro), cronograma de repetição com carta morta, pausa de 429 para a conexão por Retry-After, limite de concorrência por conexão, backfill em $batch (requisições independentes, Prefer: odata.continue-on-error, lotes pequenos), desconectar.
6. Interface administrativa em todos os idiomas configurados: assistente de conexão (ambiente, login com o link de consentimento administrativo para o aplicativo da plataforma, teste mostrando os modos encontrados, o que sincroniza, mapeamento validado contra colunas reais, quais eventos/escopos, confirmação de privacidade), página de conexão (status, log, repetir falha, substituir credenciais, vencimento do certificado), linha por registro com "Abrir no Dynamics" e "Sincronizar novamente", e uma gaveta de ajuda "Como conectar" listando os privilégios exatos da função e etapas do centro de administração do Power Platform.
7. Alertas: e-mail para os administradores do workspace uma vez quando o CRM recusar o login após a renovação.

4. Testar

• Simulador primeiro: copie templates/project/tests/standins/dataverse.mjs e seu teste para tests/standins/, estenda-o com suas tabelas (padrão em testing.md): endpoint de token, metadados, CRUD com upsert e cabeçalhos condicionais, ações não vinculadas, $batch, validação tipo Dataverse, controles para throttling, falhas, vencimento de token e estado. Um handler HTTP falso gêmeo para testes de unidade.
• Testes de unidade e banco de dados da lista do guia. Verificações no navegador do assistente e da página de conexão nas larguras de desktop e celular, claro e escuro, em dois idiomas.
• Relate como "verificado apenas contra o simulador" até que um ambiente real tenha sido executado.
• Sandbox real apenas com o OK explícito do proprietário para aquele ambiente e escopo: token via az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID> (nunca mude a conta padrão ou o perfil pac), registros marcados com um id de execução e um limite rígido, todo id criado registrado, a ordem de verificação do guia, limpeza pelos ids registrados, uma contagem de zero depois, e um breve relatório do que foi criado e removido.

5. Checklist do proprietário (entregue, não faça)

• Registre o aplicativo multi-inquilino (ou decida não fazê-lo), adicione sua credencial (identidade gerenciada federada ou certificado) e coloque qualquer segredo no cofre com o nome acordado; defina o id do cliente da configuração.
• Verificação do editor.
• Empacote a função de privilégio mínimo como uma solução gerenciada para clientes (opcional, mas recomendado).
• Para cada cliente: link de consentimento administrativo, usuário de aplicativo com a função, URL do ambiente e id do tenant no produto, Teste.

6. Registrar

STATE.md: o que foi construído, modos, o que foi executado onde, e uma tabela de Não Comprovado (ambiente real, nomes de propriedades de navegação, colunas obrigatórias em módulos opcionais, resposta real da detecção de duplicatas, $batch com conjuntos de alterações, um trigger personalizado real, throttling, consentimento administrativo e um certificado em um locatário de cliente). Atualize as marcas (confirm) do guia quando forem comprovadas. Nova entrada por versão em todos os idiomas.

Regras

• Nenhuma chamada a ambiente real, alteração de esquema/solução/função/registro de aplicativo/consentimento, ou exclusão de registros que você não criou, sem o aval explícito do proprietário para aquela ação exata.
• Nenhum segredo em código, logs, chat, commits ou relatórios; apenas no cofre. Registre host, status, código de erro.
• Placeholders em qualquer coisa compartilhada: <ENV>.crm4.dynamics.com, <TENANT_ID>, <CLIENT_ID>.
• Nenhuma atribuição de IA em nenhum lugar.