MÓDULO 1.3

🏗️ Migração de sites existentes

Audite jornadas, reaproveite lógica existente e introduza WebMCP como enhancement progressivo.

6

Tópicos

3h

Carga

Integrator

Nível

Migração

Tipo

0 de 60%
1

Faça um inventário funcional

O que é: Mapeie formulários, handlers, serviços, endpoints e estados antes de propor tools.

Por que aprender: A auditoria revela onde a regra já existe e onde a interface contém lógica que precisa ser separada.

Site existente estado de partida Camada WebMCP decisão observável Jornada preservada resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

form -> submitHandler -> enrollmentService -> POST /api/enrollments
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

formulários

02

funções JS

03

APIs

04

estado

2

Priorize jornadas por valor e risco

O que é: Nem toda funcionalidade merece migrar primeiro; combine frequência, valor, estabilidade e reversibilidade.

Por que aprender: O recorte correto entrega aprendizado cedo sem começar por uma ação crítica ou mal compreendida.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
prioridade = valor * frequencia * estabilidade / risco
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

valor

02

frequência

03

risco

04

estabilidade

3

Extraia lógica da interface

O que é: A mesma função de domínio deve atender clique humano e execução WebMCP.

Por que aprender: Compartilhar a lógica evita divergência entre o fluxo visual e o caminho do agente.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

async function iniciarInscricao(input, context) {
  return enrollmentService.start(input, context);
}
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

serviço comum

02

UI adaptadora

03

tool adaptadora

04

regra única

4

Crie wrappers finos

O que é: A tool traduz argumentos, chama o serviço existente, atualiza a UI e devolve uma resposta estruturada.

Por que aprender: Wrappers pequenos são mais fáceis de revisar e não recriam a aplicação dentro do registro WebMCP.

CÓDIGO DE REFERÊNCIA

execute: async (input, { signal }) => {
  const result = await service.start(input, { signal });
  ui.showDraft(result);
  return result;
}
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

tradução

02

serviço existente

03

UI sincronizada

04

retorno

5

Publique por enhancement progressivo

O que é: O caminho humano continua funcional quando WebMCP não existe ou está desativado.

Por que aprender: Uma tecnologia experimental entra como capacidade adicional, com observação e rollback.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

if (document.modelContext?.registerTool) {
  registerEnrollmentTools();
}
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

feature detect

02

fallback

03

rollout

04

rollback

6

Entregue o dossiê de migração

O que é: O dossiê conecta inventário, catálogo, riscos, implementação, testes e plano de publicação.

Por que aprender: A migração se torna revisável por produto, desenvolvimento, segurança e operação.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Produzir inventário, mapa de tools, riscos, plano de migração e uma primeira implementação em um site real.

Critério de Integrator responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

entrega/
  inventario.md
  catalogo-tools.json
  riscos.md
  prova-funcional/
  plano-rollout.md
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

mapa

02

risco

03

prova funcional

04

rollout

📦 Entrega do módulo

Produzir inventário, mapa de tools, riscos, plano de migração e uma primeira implementação em um site real.

Critério de aceite

A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.

Evidência

Inclua código, cenário testado, resultado observado e uma limitação conhecida.

← Voltar para a trilhaPróximo módulo: 1.4 →

Fontes técnicas