O Bug Que Estava Escondido na Camada da API

A view da mesa carregou. O canvas renderizou. A mesa existia no banco de dados.

Mas quando o front-end pediu ao servidor o estado atual da mesa — os assentos, os stacks, quem está sentado onde — o servidor retornou um 404. Nada. Sem assentos, sem dados do jogo, nada com o que o renderer pudesse trabalhar.

O canvas estava em branco porque não tinha nada para desenhar.

Aqui está a explicação técnica, mantida o mais curta possível: o API gateway na frente do table engine remove um prefixo de cada URL antes de encaminhar a request. /api/v1/tables/... chega no table engine como /tables/.... As rotas do table engine, como escritas pela sessão de build, foram registradas esperando o prefixo completo — então o servidor estava escutando em /api/v1/tables/... mas recebendo /tables/.... Toda request errava.

Não é um erro de lógica. Não é um algoritmo quebrado. Uma tabela de routing com os endereços errados. O tipo de coisa que só aparece quando você testa o stack completo junto.

Quanto Tempo Levou Para Encontrar?

Do início ao fix: menos de uma hora.

Isso é rápido. Aqui está o que tornou rápido: a metodologia de debugging.

Trabalhar com um agente AI nisso não significa perguntar "o que está errado?" e esperar uma resposta. Significa dar ao agente o contexto certo simultaneamente — a configuração do proxy que lida com o prefixo, os arquivos de registro de rotas no table engine, os logs de request mostrando 404 — e pedir para ele rastrear a discrepância.

Quando essas peças estão visíveis juntas, o agente pode fazer pattern-matching através de uma superfície que levaria vinte minutos para um engenheiro humano apenas navegar. O agente encontrou o mismatch entre a regra de rewrite do proxy e o registro de rota no table engine em cerca de três minutos.

O Bug Atrás do Bug

Encontrar o bug de routing expôs o próximo.

O endpoint agora respondia. Mas os dados que ele retornava estavam no formato errado.

O table engine fala uma linguagem internamente: números de assento, códigos de status como occupied, contagens de fichas brutas como inteiros simples. O renderer do front-end fala outra: índices de assento, strings de currency formatadas como $235.50, nomes de campos específicos que ele espera por contrato de uma definição de tipo contra a qual foi escrito.

Ninguém escreveu uma camada de tradução. A sessão de build escreveu o endpoint e ele retornou o formato interno. O renderer recebeu dados que não reconhecia e silenciosamente produziu nada.

Esta é a classe de bug que é notoriamente difícil de escrever um teste antecipadamente. Você tem que ter ambos os sistemas rodando, conectados, e tentando falar entre si para ver. Nenhum unit test cobre o gap entre dois sistemas quando nenhum dos sistemas tem um bug por si mesmo.

O Que Isto Significa para a Metodologia de Build

A fase de testing não significa que a metodologia falhou. Significa que a metodologia nos levou ao testing.

Toda plataforma de software tem uma camada de integração onde as peças têm que se encontrar no mundo real. O desenvolvimento spec-driven te leva a essa camada mais rápido. Não pula ela.

O próximo post nesta série cobre o que aconteceu quando aplicamos as correções — e o browser mostrou o mesmo resultado quebrado de qualquer jeito.

Para a metodologia de engenharia por trás de como construímos — o spec, as sessões, o que o agente faz durante uma sessão e o que o arquiteto faz — o write-up completo está em The Salty Korean.

Stay salty.