VE Facilites: caso técnico de um piloto de manutenção predial

O VE Facilites é um piloto de demonstração de uma plataforma para manutenção predial e condominial. A ideia é transformar a visita técnica num registro que o síndico consiga ler e conferir: a ordem de serviço, o checklist da disciplina, as fotos, a assinatura de quem recebeu o serviço e, no fim, um laudo em PDF. O sistema tem uma API em Java, um aplicativo Flutter para o técnico de campo e páginas web para o site, o portal do síndico e o painel de operação.

É um piloto, e nada além disso: não há cliente contratado. Este caso técnico mostra o que o código faz, as regras que impedem o laudo de inventar dado, os erros que viraram regra e o que ainda é maquete. Os números foram conferidos no repositório na versão de 30/10/2026, a mais recente.

Transparência: o VE Facilites é um projeto do autor deste blog, Jeremias Cardoso. O texto não cita empresa, pessoas nem cidade, e deixa de fora servidores, credenciais e detalhes de segurança.

Nota de atualização (30/10/2026): este post foi reescrito como caso técnico, e o nome do produto foi corrigido para VE Facilites. A versão de 23/09/2026 citava uma região, que saiu do texto. Ela também apresentava cinco disciplinas, um app que funcionava sem rede e sincronizava sozinho, fotos com anotações, assinatura biométrica e laudos em conformidade com o CREA. Conferido no código, o banco tem nove disciplinas, e incêndio não é uma disciplina própria: fica dentro de segurança eletrônica. Sem rede, o app só retoma um rascunho já salvo, e o envio é manual. A foto não tem anotação, a assinatura é um desenho na tela e o sistema não consulta o CREA: ele se recusa a emitir laudo sem responsável técnico e ART informados. Este texto descreve o que o código faz. Em 04/11/2026, a identificação do projeto passou a ser só a autoria deste blog.

O problema: a visita técnica que não vira prova

Em manutenção predial, o serviço costuma terminar numa conversa e numa foto de celular. O síndico não sabe o que foi conferido no quadro elétrico, a administradora não tem histórico por equipamento, e quando alguém contesta um serviço meses depois ninguém sabe dizer quem fez, quando, o que viu e quem respondia tecnicamente por aquilo. Para uma rotina pequena, planilhas de controle resolvem; o problema começa quando o registro precisa servir de prova.

O planejamento do projeto descreve a oportunidade assim: vender continuidade operacional de engenharia para condomínios e “provar cada entrega com agenda, ordem de serviço, checklist, fotos, histórico, responsáveis e fechamento visível ao cliente”. O mesmo documento manda evitar “qualquer alegação de compliance não auditada”. As duas frases resumem a intenção: registrar evidência, e não afirmar conformidade por conta própria. O laudo de hoje ainda escorrega nisso, como mostra a lista do que falta, no fim deste texto.

O piloto em números

Números do repositório em 30/10/2026, data do último commit.

A API usa Java 21, Spring Boot 3.3.4, PostgreSQL com migrações versionadas e a biblioteca OpenPDF para o laudo. O app usa Flutter, com SQLite no aparelho, captura de assinatura e câmera.

Da ordem de serviço ao laudo

O sistema tem quatro perfis: administração, gestão da operação, técnico de campo e síndico. O centro de tudo é a ordem de serviço, que pode ser preventiva mensal, corretiva urgente, vistoria diagnóstica, termografia periódica ou avulsa. Ela passa por quatro estados: agendada, em andamento, concluída ou cancelada.

Cada ordem de serviço pertence a uma disciplina e recebe os itens de checklist do catálogo daquela disciplina. As seis primeiras disciplinas entraram numa migração de setembro: elétrica, hidrossanitária, civil e fachadas, climatização (com os itens do plano de manutenção do ar-condicionado), segurança eletrônica e incêndio, e serviço avulso, com 45 critérios. Uma migração posterior acrescentou outras três, ligadas a fachada, manutenção predial e vistorias, com mais 10 critérios.

A conclusão é o momento mais vigiado. A API só conclui uma ordem que esteja em andamento e confere, entre outras coisas:

• se o orçamento foi aprovado pelo cliente, quando a ordem exige orçamento prévio;
• se o nome de quem assina foi informado e se a assinatura enviada é uma imagem válida;
• se as respostas cobrem exatamente os itens cadastrados na ordem, nem um a mais, nem um a menos;
• se cada item que exige foto tem ao menos uma foto anexada;
• se cada item marcado como crítico tem uma observação técnica descrevendo o defeito.

Passando tudo, as respostas, a assinatura, o resumo e o novo estado são gravados de uma vez, com um recibo do envio. Um teste de integração, dos que exigem banco e não rodaram nesta revisão, foi escrito para provar que, se a gravação da assinatura falhar, nada fica gravado.

As fotos têm tipo declarado por quem fotografou (antes, durante, depois, defeito crítico, placa do equipamento, entre outros) e legenda. Na chegada ao servidor, o arquivo ganha um resumo SHA-256, uma espécie de impressão digital do conteúdo: se um único byte mudar depois, o resumo não bate mais.

O laudo que se recusa a inventar

O laudo em PDF é a parte mais madura do sistema. Como o motor do simulador de manobras, ele falha fechado: na dúvida, recusa. As regras estão escritas no código, com o motivo de cada uma:

• só sai de ordem de serviço concluída;
• sem engenheiro responsável técnico e número da ART vinculados à ordem, a emissão é recusada, com uma mensagem que diz o que falta, a quem pedir e por quê: o laudo declara responsabilidade perante o CREA. O comentário do código completa: nem o responsável nem a ART podem ser escolhidos ou gerados pelo sistema;
• todo campo vazio sai como “não informado”. Nada de “N/A”, que leria como “não se aplica”, e nada de um nome plausível no lugar de um nome ausente;
• item sem resultado sai como “NÃO AVALIADO” e não entra na contagem de itens conformes;
• se uma foto não puder ser lida do armazenamento, ou se a assinatura estiver corrompida, o laudo não sai;
• cada foto impressa traz o resumo SHA-256, ou a frase “hash não disponível — integridade não verificável”.

A emissão acontece uma vez. Os bytes do PDF, a data e o resumo SHA-256 do arquivo inteiro ficam gravados na ordem de serviço. Nos downloads seguintes, o sistema não gera o documento de novo: ele devolve o original preservado, depois de conferir que o resumo ainda bate. Se o original sumiu ou não confere, a resposta é um erro, e o sistema avisa que não vai substituir o documento.

Uma página de verificação foi desenhada para fechar o ciclo. A pessoa escolhe o arquivo do laudo, o navegador calcula o resumo SHA-256 no próprio aparelho e pergunta à API qual laudo tem aquele resumo. O PDF também traz um código 2D com o endereço dessa consulta. Por enquanto, a página aponta para o endereço local de desenvolvimento da API, fixo no código.

O app de campo e o que “sem rede” quer dizer

O app do técnico mostra a agenda de ordens de serviço, abre o checklist, tira fotos e captura a assinatura do recebedor desenhada na tela, gravada como imagem PNG. A própria documentação da API diz que isso é evidência de captura, “sem alegação de identidade criptográfica ou assinatura qualificada”.

O rascunho de cada vistoria fica num banco SQLite do aparelho, separado por usuário e por ordem de serviço. O README do app é direto sobre o que isso permite: sem rede, um rascunho já salvo pode ser retomado, mas a ordem não é concluída sem rede e não há sincronização automática.

O envio da conclusão é manual. Antes dele, o app confere localmente se todos os itens foram respondidos e se há resumo, recebedor e assinatura. O corpo do envio é gravado no aparelho antes de sair, e a retentativa repete exatamente o mesmo corpo. Um envio pendente fica travado para edição: o código responde que “o conteúdo de um envio pendente não pode ser alterado”. As fotos sobem na hora em que são anexadas; se a rede falhar, o app avisa e a foto não entra numa fila.

Isso é menos do que a versão anterior deste texto prometia, e é o que existe. Numa garagem sem sinal, o técnico consegue continuar e guardar um checklist que já abriu com rede, mas precisa de rede para mandar fotos e concluir.

As páginas web: o que fala com a API e o que é maquete

São três públicos, em páginas separadas. O site institucional tem um formulário que envia o contato de verdade e a página de verificação do laudo. O painel de operação, usado pela administração, conversa com a API. O portal do síndico mistura as duas coisas: um modo real, ligado à API, e onze telas ilustrativas que avisam o que são, com frases como “Nesta maquete o campo já vem preenchido — não há envio de arquivo de verdade” e “Os valores desta maquete são ilustrativos e não representam tabela de preços”.

Essas frases nasceram de um erro. Em setembro, um relatório de revisão visual descrevia “conexão real” com o banco, e as três páginas web não tinham nenhuma chamada de rede no código. A regra que ficou: aparência não prova integração. O teste é procurar a chamada à API no código, não olhar a tela.

A demonstração em um clique

Para mostrar o sistema sem instalar nada, o repositório tem um pacote de demonstração para Windows. Um arquivo de dois cliques sobe um pequeno servidor local, escrito em PowerShell, e abre o navegador numa página com o site, o portal, um simulador do app numa moldura de celular e um roteiro de testes. O simulador avisa na tela que é ilustrativo e que não autentica nem sincroniza dados.

O servidor é em PowerShell por causa de um tropeço. A primeira versão procurava o Python, e no Windows o comando python pode existir sem o Python estar instalado: é um atalho da loja da Microsoft, que abre uma janela e não serve página nenhuma. Empacotar o interpretador deixaria o arquivo grande demais para mandar pelo WhatsApp.

Incidentes que viraram regra

1. O laudo que inventava responsável técnico (setembro de 2026). A primeira bateria de testes contra o sistema rodando, em 14/09, reprovou o piloto e aprovou só a fundação técnica. Uma das causas: o laudo completava sozinho o que faltava. Quando a ordem não tinha responsável técnico, o código punha um nome, números de registro e um número de ART derivado do código da ordem. Em 15/09, onze desses pontos saíram do código, e uma migração anulou as ARTs fabricadas que já estavam no banco. O comentário dela diz: “ART é fato jurídico emitido pelo CREA”, e “o sistema não pode deduzir nenhum dos dois”. Desde então, falta de dado vira recusa ou “não informado”.
2. Nenhuma ordem saía de agendada (14/09/2026). Na mesma bateria, a API não tinha nenhum caminho que levasse a ordem de agendada para em andamento, e a conclusão exige em andamento. Toda ordem nascia e morria agendada. O caminho de início foi criado nas rodadas seguintes, junto com a regra da foto obrigatória e da observação em item crítico.
3. O hash que mudava a cada download (17/09/2026). O PDF era gerado de novo a cada pedido, com a hora daquele momento nos metadados, e cada cópia tinha um resumo SHA-256 diferente, o que invalidava a via já entregue. A primeira correção fixou a data da emissão nos metadados. A definitiva, de outubro, foi guardar os bytes do primeiro PDF e devolver sempre o mesmo arquivo.
4. O atalho que fingia ser o Python (21/09/2026). Descrito acima: a demonstração passou a usar um servidor em PowerShell.
5. A tarefa fechada por um teste (02/10/2026). Uma revisão do controle do projeto achou tarefas marcadas como concluídas sem o ato que as concluía. A de contratar o condomínio-piloto tinha sido fechada com um registro de teste no banco. A regra registrada: tarefa cujo “pronto” é um ato humano não fecha com um arquivo; exige a prova externa, como um contrato ou uma mensagem.
6. A camada comercial era maquete (23/10/2026). Uma avaliação do site e do portal concluiu que o núcleo de ordem de serviço e laudo era real, mas a captação, o catálogo, os planos, a contratação, o orçamento e a comunicação eram maquete. Daí veio o desenho atual de piloto fechado: cliente convidado, conta criada pela administração e serviço avulso desligado, com a mensagem “Serviços avulsos não estão disponíveis no piloto fechado”. Em 27/10, duas migrações criaram o núcleo comercial de verdade: clientes, serviços, planos, pedidos de visita, orçamento ligado à ordem de serviço e registro de contatos.
7. O formulário que falhava calado (29/10/2026). Uma edição num script embutido no HTML do painel de operação deixou um erro de sintaxe. O navegador descartou o script inteiro, e o formulário de entrada parou de funcionar sem mostrar erro nenhum, a mesma falha silenciosa que derruba automações. A regra que ficou: conferir a sintaxe de todos os scripts das páginas antes de publicar.

Testes: a API e o app rodaram, o banco não

Nesta revisão, os testes que não precisam de banco rodaram com o Maven: 183 execuções em 17 classes, nenhuma falha. Eles cobrem o laudo em PDF (30 execuções), o fluxo de ponta a ponta da ordem de serviço, as fotos, o catálogo, a verificação pública e a validação da assinatura, entre outros. Os testes do app Flutter também rodaram: 76 aprovados. Eles cobrem o rascunho, o envio, a sessão que expira no meio do checklist e as falhas do SQLite.

Os 91 testes das 8 classes marcadas para PostgreSQL ficam fora da execução padrão e só rodam contra um banco descartável preparado para isso. Eles não foram rodados aqui.

O que ainda não está resolvido

• Nenhum cliente. O piloto não tem cliente contratado. A decisão de nomear o primeiro condomínio e a data de início continua pendente no controle do projeto.
• Responsável técnico e ART reais. Sem eles, o sistema, corretamente, não emite laudo nenhum. É uma decisão do dono, não do código.
• Checklists sem o bloco normativo. O documento dos checklists se declara rascunho proposto e avisa para não aplicá-lo em ordem real antes da validação do responsável técnico. O bloco que citaria a norma está vazio de propósito.
• O laudo afirma o que ninguém verificou. Mesmo com o bloco normativo vazio, o cabeçalho do PDF traz a linha “Conformidade Normativa: ABNT NBR 5674 (Manutenção Predial) · ABNT NBR 14037 (Operação e Uso) · Legislação Vigente”, e o rodapé repete as duas normas. Nenhuma parte do sistema confere essa conformidade. É a mesma família de erro que o projeto já corrigiu no responsável técnico, agora no cabeçalho.
• Verificação ainda local. A página de verificação do laudo aponta para o endereço de desenvolvimento da API; publicada como está, não consulta nada.
• Disciplinas contadas de três jeitos. O planejamento fala em cinco, o roteiro de demonstração em quatro e o banco tem nove.
• App sem rede de verdade. Não há sincronização automática, conclusão sem rede nem fila de fotos.
• Portal do síndico em parte maquete. Onze telas são ilustrativas.
• Pagamento e nota fiscal fora do sistema. A plataforma não cobra nem fatura. O núcleo comercial monta atalhos para o WhatsApp e registra contatos, mas a API oficial do WhatsApp, o pagamento e a nota fiscal ficaram para depois do piloto.
• Documentação defasada em pontos. O README da API ainda cita as migrações até a V13, e o banco já está na V15.

Lições que valem fora da manutenção predial

1. Dado plausível é dado inventado. Um nome ou um número de ART “de exemplo” num laudo é pior do que o campo vazio.
2. Ausência se declara. “Não informado” e “não avaliado” contam a verdade; “N/A” e “conforme” por omissão, não.
3. Documento emitido não se regenera. Guardar os bytes do original é mais simples e mais forte do que tentar reproduzir o mesmo arquivo.
4. Aparência não prova integração. Procure a chamada à API no código antes de acreditar na tela.
5. “Sem rede” precisa de definição escrita. Dizer o que funciona sem sinal, e o que não funciona, evita a promessa errada.
6. Tarefa de ato humano fecha com prova externa. Contrato, mensagem ou documento, não um teste com dado fictício.
7. Piloto sem cliente é demonstração. O código pronto não substitui o primeiro condomínio real, a mesma lição do ZapOrca, um MVP ainda sem usuários.

Fontes

• Código, documentação, histórico de commits e testes: repositório do VE Facilites na versão de 30/10/2026, lido pelo autor, com os testes da API sem banco e os testes do app rodados localmente em 30/10/2026; extrato com os trechos, o método da contagem e os limites da verificação, verificado em 2026-10-30.
• Norma Técnica ABNT NBR 5674 — Manutenção de edificações: requisitos para o sistema de gestão de manutenção — Associação Brasileira de Normas Técnicas (ABNT) (norma técnica brasileira), verificado em 2026-09-23.