Capítulo 04 de 54

Clean Code Híbrido: A Cartilha do Engenheiro B2B

A Arquitetura Híbrida (Next.js + Supabase) só se sustenta se a base de código for legível, testável e universal. Códigos no estilo "Frankenstein" surgem quando a equipe não possui um padrão cultural de escrita.

Aqui estão as leis imutáveis (A Cartilha do Engenheiro B2B) que regem os nossos repositórios e guiam nossa Inteligência Artificial assistente.


1. A Regra do Idioma

  • Código-Fonte (O Core): É estritamente, obrigatoriamente e exclusivamente em Inglês. Variáveis (customer_id), funções (calculateTaxes), tabelas no banco (shopping_carts) e Tipagens (Interfaces). O Inglês garante compatibilidade global e sintonia com bibliotecas externas.
  • Diálogos e Comentários: As explicações do porquê o código foi feito de determinada forma, bem como a comunicação com o Especialista (usuário), devem ser sempre em Português.
  • Comentários de Commit: Simples, profissionais, curtos e sempre em Inglês. (Ex: fix: resolved checkout crash on mobile).

[!IMPORTANT] Formatação de Linhas: Os comentários dentro do código-fonte (em Português) nunca devem ultrapassar 80 caracteres por linha. Desenvolvedores não devem precisar usar a rolagem horizontal do monitor para ler explicações arquiteturais.


2. Testes Pragmáticos (Vitest vs Playwright)

Na cultura de empresas hiper-ágeis, buscar "100% de cobertura de testes unitários em botões do React" é perda de tempo e dinheiro. A nossa arquitetura divide o QA em duas trincheiras cirúrgicas:

Trincheira 1: O Backend Intocável (Vitest / TDD)

Quando estamos atuando no Supabase (Políticas RLS, Edge Functions financeiras, cálculos de preço), os testes unitários são obrigatórios e vêm primeiro. Você deve usar o Vitest localmente para simular tentativas de invasão:

  • O Usuário A consegue alterar o post do Usuário B no banco? (O teste deve garantir que a RLS barra). A regra é: Regras de negócio e segurança ganham Test-Driven Development (TDD) puro.

Trincheira 2: A Interface Visual (Playwright / E2E)

Quando estamos atuando no Next.js Frontend, a regra se inverte. Usamos o princípio da "Funcionalidade Primeiro". O desenvolvedor desenha a tela, coloca em pé e vê funcionando. Só depois, escrevemos um teste End-to-End (E2E) no Playwright que imita um robô abrindo o navegador, clicando no botão de login e realizando um fluxo crítico de ponta a ponta.


3. O Respeito à Separação (Interface vs Dados)

Um código híbrido limpo NUNCA executa comandos complexos de banco de dados diretamente dentro do componente visual do React.

Errado: Um componente Dashboard.tsx que carrega o layout e tem um loop de 30 linhas mapenado e formatando as faturas da Stripe, misturando HTML com lógica de redução de dados.

Certo: O componente Dashboard.tsx chama a função getDashboardMetrics(). Todo o trabalho sujo e consultas ficam nos bastidores (ou numa Edge Function, ou em arquivos separados na pasta lib/ ou actions/), e o componente React apenas recebe um Objeto Limpo para exibir na tela.