Max Bid: preservando um contrato de negócio em duas implementações

Como uma aplicação Rails de referência e um site TypeScript estático preservam o mesmo contrato de cálculo em navegadores e entregas diferentes.

O Max Bid é uma calculadora pública de margem de revenda construída em torno de uma decisão: qual é o maior valor que alguém pode pagar por um item e ainda atingir um lucro desejado depois da venda?

O desafio de engenharia não era o tamanho do formulário. Era manter um contrato de negócio compreensível e consistente em uma aplicação Rails de referência, uma implementação TypeScript no navegador e uma entrega no GitHub Pages. Este estudo documenta essas decisões sem alegar usuários, receita, resultados de clientes ou escala de produção. A evidência vem da calculadora pública, das notas técnicas publicadas pela Mirtilo IO e do registo documentado de releases. Os repositórios de implementação são privados; esta página não implica inspeção pública do código-fonte.

O método de trabalho por trás dessas evidências está descrito no artigo Engenharia assistida por IA: evidência acima do output.

Regra de negócio

A calculadora parte do preço de venda esperado:

lance máximo =
  preço de venda
  − comissão do leilão
  − taxa da plataforma
  − frete
  − embalagem
  − lucro desejado

As sete entradas são preço de venda esperado, custo de compra, custo de frete, custo de embalagem, comissão do leilão, taxa da plataforma e lucro desejado. Os valores monetários usam centavos de euro inteiros e um arredondamento consistente half-up nas fronteiras de cálculo definidas.

As decisões observáveis são explícitas: um custo de compra igual ao lance máximo resulta em Compre.; um custo maior resulta em Não compre!; uma entrada inválida não pode deixar uma recomendação antiga na tela; e trocar a moeda muda a unidade e a formatação, mas nunca aplica uma taxa de câmbio.

O Max Bid é uma ferramenta de planejamento, não orientação financeira, fiscal, jurídica ou sobre políticas de marketplace. Impostos, devoluções, descontos e regras da plataforma podem mudar o resultado real.

Implementação de referência em Rails

A aplicação Rails 8.1 é a implementação de referência para fórmulas, textos, acessibilidade, segurança e testes. Ela fornece um ambiente completo para exercitar o comportamento da calculadora e tornar o contrato visível em uma aplicação renderizada no servidor.

A implementação de referência não é tratada como um protótipo informal. O repositório registra regras de negócio, casos de borda, contrato de conteúdo, comportamento da interface, expectativas de segurança e estratégia de testes. Assim, a segunda implementação tem algo mais preciso para reproduzir do que uma captura de tela.

Implementação TypeScript de paridade

A implementação pública é uma aplicação TypeScript estática construída com Vite. Ela executa o cálculo no navegador e publica os assets gerados no GitHub Pages. Não há um servidor de aplicação permanente nem banco de dados para a calculadora pública.

O projeto TypeScript tem uma fronteira tipada entre as regras do domínio, o tratamento de idiomas e moedas e a interface no DOM. Um contrato canônico de conteúdo mantém os identificadores dos campos, textos, descrições, mensagens de validação e conteúdo SEO localizado. A implementação estática preserva o comportamento observável do Rails, mas se adapta a outro modelo de hospedagem.

Manter a versão pública estática reduz a quantidade de componentes em runtime, mas não remove a responsabilidade pela entrega. O artefato ainda precisa ser inspecionado, o comportamento no navegador precisa ser testado e a implantação precisa publicar exatamente o commit que passou pelo CI.

Localização

O Max Bid está disponível em inglês e português brasileiro. A versão em inglês oferece EUR e dólar americano. A versão em português oferece EUR e real brasileiro. A seleção de moeda muda a unidade e a formatação, mas não faz conversão cambial. Por isso, todos os valores de uma conta precisam usar a mesma moeda.

As regras de parsing e apresentação são localizadas juntas. Pessoas usando português podem informar valores como 1.200,50, enquanto a interface em inglês exibe 1,200.50. Exemplos, máscaras de entrada, mensagens de validação e detalhamento do resultado seguem o mesmo locale, em vez de traduzir apenas os rótulos.

Localização, portanto, faz parte do contrato. Ela é parte da paridade, não uma camada final de edição de texto.

Acessibilidade

A referência Rails e a implementação TypeScript tratam acessibilidade como comportamento observável. Campos, unidades, controles, mensagens de validação e a região de resultado têm nomes e relações acessíveis. Atualizações do resultado são anunciadas, o foco continua utilizável e a interface suporta interação por teclado e layouts responsivos.

O projeto TypeScript inclui verificações de DOM, end-to-end e acessibilidade. A linha de base documentada cobre cenários desktop e mobile, troca de tema, navegação direta e o artefato estático público. O objetivo é que a mesma decisão de negócio continue compreensível em qualquer dispositivo ou tecnologia assistiva.

Segurança e privacidade

A calculadora pública mantém os valores do cálculo na memória do navegador. A fronteira TypeScript valida a entrada, permite apenas idiomas e moedas suportados, renderiza valores controlados pelo usuário como texto e exclui os dados da calculadora de analytics, URLs e APIs externas. O artefato de produção não inclui source maps, e uma verificação procura segredos e conteúdo inseguro nos arquivos gerados.

A referência Rails acrescenta proteção contra CSRF, Content Security Policy, HTTPS, strong parameters e filtragem de parâmetros. Brakeman, auditoria de dependências e o checklist de release cobrem riscos que testes no navegador não conseguem cobrir sozinhos.

É uma fronteira de privacidade deliberadamente estreita: não há conta, histórico de cálculos, upload, fluxo de pagamento ou armazenamento de dados de revenda na calculadora pública.

CI/CD e entrega no GitHub Pages

Quando uma alteração afeta typescript/, o GitHub Actions instala as dependências travadas do Node.js 22 com npm ci e executa verificação de tipos, lint, testes unitários e de DOM, testes end-to-end, testes de acessibilidade, build de produção, inspeção do artefato, varredura de segurança e auditoria de dependências de alta severidade. O CI usa permissões de leitura no repositório, cancela execuções antigas e fixa actions de terceiros em SHAs de commit.

O workflow do Pages espera o CI terminar com sucesso depois de um push na main. Ele faz checkout do commit exato avaliado pelo CI, instala novamente as dependências travadas, recompila e inspeciona typescript/dist, configura o GitHub Pages e publica o artefato. Apenas o job de deploy recebe permissões de escrita no Pages e o token OIDC.

A calculadora estática pública está configurada para maxbid.mirtilo.io. O caminho de entrega também faz parte do caso: o Rails é a referência, o TypeScript é a implementação pública de paridade e o GitHub Pages é a fronteira de hospedagem.

Evidência de release

O repositório mantém um registro de evidências de release em vez de tratar um build bem-sucedido como a decisão completa de entrega. O registro identifica gates, comandos, limites, linha de base de navegadores e expectativas de rollback.

No checkpoint registrado, os gates automatizados locais estavam marcados como aprovados. O mesmo registro marcava como pendentes a matriz de navegadores nativos, a verificação manual de teclado e leitor de tela, o primeiro deploy em produção, o smoke de rollback em produção e o tempo de rollback. Este estudo mantém esses estados visíveis; não transforma verificações pendentes em alegações de operação de produção concluída.

Limites do produto e próximas decisões

O Max Bid não tem contas, fluxo de pagamento, exportações, uploads, comparação de marketplaces, links de afiliados ou telemetria dos valores calculados. É uma ferramenta pequena de planejamento, não uma integração com marketplace nem um produto de orientação financeira.

Não há aqui evidência de adoção, usuários pagantes, receita, impacto em clientes, gestão de incidentes em alta escala, observabilidade avançada ou exercício concluído de rollback em produção. Essas alegações precisam de registros próprios.

As próximas decisões devem preservar primeiro o contrato: qualquer recurso futuro precisa manter o cálculo explicável, preservar a paridade entre implementações e justificar seu efeito sobre privacidade, acessibilidade, testes e complexidade de entrega.