Duas fases em um sistema em produção: pipeline, documentos e financeiro na JV Elétrica

A JV Elétrica trabalha com projetos de micro geração distribuída — energia solar — e já tinha um sistema próprio no ar, com 137 projetos cadastrados e clientes usando o portal diariamente. O pedido não era construir algo novo. Era corrigir o que estava quebrado e estender o que faltava, sem parar a operação.

A decisão de entrada

Nenhuma stack nova foi introduzida. Não recriamos a autenticação, não recriamos o schema, não propusemos migração de plataforma. Todo o trabalho foi incremental sobre o sistema que já rodava em produção.

Isso é uma decisão de risco, não de preguiça. Sistema com 137 projetos ativos e clientes finais enviando documentos não é ambiente para reescrita. E antes de qualquer alteração de schema, backup completo do banco — compromisso assumido com o cliente na primeira conversa e cumprido em todas as rodadas.

Fase 1: os bugs que ninguém tinha achado

O escopo original tinha quatro bugs mapeados. Um deles era um documento técnico que travava: depois que o cliente final enviava o PDF assinado, o registro entrava em estado de validação e não podia mais ser apagado nem corrigido por ninguém. Se o arquivo estivesse errado, o fluxo simplesmente parava.

Outro era mais sutil: o servidor rodava em fuso de Berlim, e todos os horários exibidos no sistema estavam deslocados — não só na tela de auditoria, mas em todo lugar. Foi corrigido na origem, não maquiado por tela.

Durante a execução apareceram dois problemas que não estavam na lista. O link de download de arquivos expirava em uma hora e falhava em silêncio — quem tentasse abrir depois disso não recebia erro, só não funcionava. E a formatação de números não seguia o padrão brasileiro, o que só ficou visível através de um print enviado pelo cliente depois da entrega.

O formulário de dados do projeto

A entrega central da primeira fase foi um formulário completo em modal, com cinco blocos: tipo de projeto, dados do cliente, unidade geradora, informações da geradora e unidades beneficiárias. Uploads de documento, conta de energia, foto do padrão de medição, disjuntor e fachada.

Dois detalhes definiram a qualidade dele. A potência total do gerador e dos inversores é calculada em tempo real conforme o usuário digita quantidade e potência — sem botão de calcular, sem recarregar. E a soma das porcentagens das unidades beneficiárias precisa fechar exatamente em 100%, com o envio bloqueado enquanto não fechar. É uma regra do domínio, não uma validação genérica de formulário.

O que apareceu no suporte

Durante os sete dias de suporte, o cliente relatou que um usuário final havia enviado o documento errado e não conseguia removê-lo. A causa raiz era a mesma regra do bug original: depois de assinado, o registro sumia das opções de correção tanto para o admin quanto para o cliente. Existia um contorno pelo painel administrativo, mas não era self-service nem óbvio.

A correção foi um botão de cancelar envio e reenviar, disponível ao cliente final enquanto o documento aguarda validação. Ao confirmar, o arquivo errado é descartado, o registro volta ao estado anterior e o cliente reenvia imediatamente, sem depender do admin — que recebe notificação in-app do cancelamento. Migration aditiva no banco, com backup antes.

Corrigir o sintoma teria sido devolver o botão de apagar ao admin. Corrigir o problema foi devolver a autonomia a quem cometeu o erro.

Fase 2: painel, pipeline e financeiro

A segunda fase entrou por contrato direto, com cinco itens. Painel de usuários no admin, com troca de foto, telefone, redefinição de senha e exclusão. Novo estágio de vistoria reprovada no pipeline de projetos. Formulário simplificado de criação de projeto — apenas nome e observação — mantendo o formulário completo intocado.

E a parte financeira: dashboard com sistema de cores para leitura rápida de saldo e status, filtro de projetos com saldo devedor, visualização do saldo total pelo próprio usuário, e um botão de cobrança que dispara um e-mail com o resumo consolidado da conta do cliente.

O que o teste do cliente encontrou

O cliente testou no mesmo dia da entrega e apontou seis itens. Vale registrar, porque é onde aparece o trabalho real.

O upload de foto de usuário falhava por dois motivos em sequência: primeiro um cabeçalho de proteção ausente na requisição; depois de corrigir isso, uma pasta de armazenamento no servidor com dono errado, que impedia o serviço de escrever. O e-mail do novo estágio de vistoria reprovada não disparava porque o status recém-criado nunca havia sido mapeado no sistema de notificações — sem evento, sem e-mail.

E a foto do usuário não aparecia no cabeçalho do portal por um bug bem mais antigo: a sessão nunca carregava o campo de imagem, o que afetava todos os usuários desde sempre e não tinha relação com a Fase 2. Foi corrigido junto.

Processo

Todo o trabalho foi feito por acesso direto ao servidor, sem clone local. Backup do banco antes de cada rodada de alteração. QA com usuários administrador e cliente de teste descartáveis, apagados depois. Build e verificação de tipos limpos a cada rodada, com deploy confirmado por resposta do servidor antes de avisar o cliente.

Stack

Next.js · TypeScript · NextAuth · PostgreSQL · VPS Contabo