Manual — Formulário de Atualização YAML

O que é este formulário

O formulário de atualização YAML é uma ferramenta para que cada equipe de serviço possa revisar o contrato planejado da API TV 3.0 e indicar, rota por rota, o que deve ser mantido, removido ou corrigido no arquivo api-gateway-tv30.yaml.

O formulário é gerado automaticamente pelo Baliza a partir do último ciclo de comparação entre o YAML planejado e os swaggers implementados. Todas as rotas já estão pré-carregadas — a equipe só precisa marcar a ação proposta para cada uma e exportar o resultado.

Fluxo de trabalho

1. Abra o arquivo baliza-form-run7.html no navegador (duplo clique).
2. Use a aba do seu serviço (topo da página) para ver apenas suas rotas.
3. Para cada rota, selecione a ação proposta e preencha a justificativa.
4. Clique em ↓ JSON ou ↓ CSV para baixar o arquivo de resposta.
5. Envie o arquivo baixado para o arquiteto de API (Carlos Eduardo) via WhatsApp ou Mattermost.

Abas de serviço

No topo do formulário há abas, uma por serviço. Clique na aba do seu serviço para ver apenas as rotas que lhe dizem respeito. A aba Todas exibe o conjunto completo (241 rotas únicas).

Filtros e busca

Filtros por categoria

Ao lado das abas há botões de filtro rápido:

Campo de busca

O campo Filtrar por path... filtra as rotas visíveis por texto no método ou no caminho. Exemplos: digitar rooms mostra só rotas com /rooms; digitar delete mostra só rotas DELETE.

Categorias de rota

Cada rota exibe um badge colorido indicando sua situação atual no Baliza:

Campos por rota

Cada linha da tabela representa uma rota e tem quatro campos editáveis:

Campo "Rota equivalente"

Só é habilitado quando a ação é "↪ Implementado em outra rota". Use o formato MÉTODO /caminho/completo, por exemplo: PATCH /cms/v1/debates/sessions/{sessionId}/status. Quando a ação for outra, o campo fica desabilitado e cinza — ignore-o.

Campo "Justificativa"

Texto livre. Explique brevemente o motivo da decisão. Uma frase é suficiente. Exemplos:

• "Moderação é assíncrona via Kafka; endpoint HTTP quebraria separação de responsabilidades."
• "GET já retornado no detalhe do canal; rota separada é redundante."
• "Rota nova ainda não implementada — schema em definição."

Ações disponíveis

Selecione a ação que melhor descreve o que deve acontecer com cada rota no YAML:

Barra de progresso

No canto superior direito há um contador X / Y avaliados com uma barra de progresso. Conta quantas rotas já têm uma ação selecionada (qualquer opção diferente de pendente). A barra considera todas as rotas, não apenas as do filtro ativo.

Exportar JSON / CSV

No canto superior direito há dois botões de exportação. Ambos geram um arquivo com todas as rotas (incluindo pendentes), independente do filtro ativo.

Botão ↓ JSON (recomendado)

Gera baliza-yaml-proposals-run7.json com a estrutura:

{
  "meta": {
    "run_id": 7,
    "total": 241
  },
  "proposals": [
    {
      "service": "Meta 4 · CHAT",
      "method": "DELETE",
      "path": "/rooms/{roomId}/moderation/queue",
      "category": "so_planejado",
      "breaking": false,
      "action": "decisao_arquitetural",
      "equivalent_route": "",
      "justification": "Moderação assíncrona via Kafka",
      "priority": "alta"
    },
    ...
  ]
}

Botão ↓ CSV

Gera baliza-yaml-proposals-run7.csv com as mesmas colunas, compatível com Excel e Google Sheets. Útil para revisão offline em planilha.

Importar resposta anterior

O botão ↑ Importar permite carregar um JSON exportado anteriormente (por você ou por outra pessoa) para continuar o preenchimento ou consolidar respostas.

Ao importar, os campos preenchidos no JSON são aplicados às rotas correspondentes. Rotas já preenchidas no navegador são sobrescritas pelos valores do JSON importado. Rotas sem correspondência no arquivo são ignoradas.

Como enviar

O que acontece depois

Após receber os JSONs de todas as equipes, o arquiteto de API irá:

1. Consolidar todas as respostas em um único arquivo
2. Aplicar as mudanças no api-gateway-tv30.yaml em MRs separados por grupo de mudança
3. Solicitar schemas das rotas marcadas como Necessita schema
4. Abrir discussão para itens marcados como [DÚVIDA] antes de agir