Diagnóstico do Problema e Objetivos

Contexto do Setor da Construção Civil

O setor de construção civil é historicamente caracterizado por baixa digitalização e processos manuais suscetíveis a falhas humanas. De acordo com o relatório "Reinventing Construction" da McKinsey Global Institute (2017), a construção civil aparece como um dos setores menos digitalizados do índice — penúltima posição, à frente apenas da agricultura e da caça —, com produtividade estagnada nas duas décadas anteriores. No Brasil, o atraso é estrutural: erguer um prédio residencial padrão, que poderia levar pouco mais de um ano, leva em média mais do que o dobro desse tempo (Deloitte/Fiesp, 2023); e, conforme reportado pela imprensa, a CBIC — Câmara Brasileira da Indústria da Construção estima que os atrasos no processo respondem por cerca de 12% do custo de uma obra. A assimetria de informação entre canteiro e gerência é um dos principais fatores contribuintes.

Fontes e ressalvas:

>

- McKinsey Global Institute, Reinventing Construction (2017). O índice de digitalização usado no relatório é construído sobre setores da economia norte-americana — por isso a formulação aqui é "um dos setores menos digitalizados", e não "do mundo". É uma referência de 2017 e, portanto, com quase uma década: continua sendo a citação canônica sobre o tema, mas deve ser lida como diagnóstico estrutural, não como retrato do ano corrente.

- CNN Brasil, "Burocracia e atrasos podem custar R$ 59 bi à construção até 2025, diz estudo" (27/09/2023) — reportagem sobre o estudo Deloitte/Fiesp e a estimativa de custo da CBIC. Fonte secundária: os números de Deloitte/Fiesp e CBIC são citados conforme reportado, sem acesso aos estudos originais. Disponível em: https://www.cnnbrasil.com.br/economia/macroeconomia/burocracia-e-atrasos-podem-custar-r-59-bi-a-construcao-ate-2025-diz-estudo/

O Problema Real

Três decisões operacionais recorrentes de uma obra dependem, simultaneamente, do que já aconteceu no canteiro e da previsão do tempo. Não é uma percepção genérica: em cada uma delas há norma técnica ou recomendação prática que condiciona a execução ao clima.

Para tomar essas decisões, o responsável precisaria:

• Reler o diário de obras dos últimos dias para recuperar o que aconteceu (paralisações, avanços, problemas de material, etc.).
• Consultar a previsão do tempo para os próximos 5 dias.
• Cruzar essas duas informações e decidir o plano de ação.

O dado existe — o gargalo é consultá-lo

O registro diário não é opcional em obra pública: a Lei nº 14.133/2021 (art. 117, § 1º) determina que o fiscal do contrato anote "em registro próprio" todas as ocorrências relacionadas à execução, determinando o que for necessário para regularizar faltas ou defeitos. Em obra privada, o diário permanece como prática contratual e prova documental em disputas.

Ressalva de atualidade: a obrigatoriedade do Livro de Ordem no âmbito do sistema CONFEA/CREA (Resolução nº 1.024/2009, atualizada pela nº 1.094/2017) foi revogada pelo Plenário do Confea em fevereiro de 2023, a pedido da CBIC, por dificuldade dos CREAs em analisar os livros. Portanto, não é correto afirmar hoje que o diário de obras é obrigatório por resolução do conselho profissional — a obrigatoriedade que subsiste é a da obra pública (Lei de Licitações) e a de natureza contratual.

O problema, então, não é a ausência do dado — é que ele não é consultado na hora de decidir. Duas evidências setoriais sustentam isso:

• O diário é frequentemente subutilizado. A literatura setorial (institutos de ensino em engenharia de custos e fornecedores de RDO digital) descreve como comum que, na rotina acelerada do canteiro, o diário seja negligenciado ou preenchido de forma superficial — perdendo valor tanto como ferramenta de controle quanto como prova documental. (Ressalva de qualidade de fonte: são publicações setoriais e de fornecedores, não estudos acadêmicos revisados por pares.)
• Garimpar informação de projeto é um custo reconhecido e quantificado do setor. O estudo Construction Disconnected (FMI Corporation + PlanGrid, abril de 2018), com ~600 profissionais (500 nos EUA e 99 em Austrália, Nova Zelândia, Reino Unido e Canadá), apurou mais de 14 horas semanais por pessoa em atividades não-produtivas, das quais 5,5 h/semana apenas procurando dados de projeto.

Ressalva sobre o alcance deste dado — ele não dimensiona a tarefa deste projeto. Essas 5,5 h/semana agregam a busca por toda informação de projeto: normas técnicas, projetos executivos e construtivos, especificações, RFIs, relatórios diversos e registros de execução. A consulta ao diário de obras é apenas uma fatia desse conjunto, de tamanho desconhecido. A amostra é, além disso, majoritariamente norte-americana.

>

Ou seja: o estudo serve para estabelecer que o problema existe e tem custo mensurável, e não para validar o baseline de 40 min/dia adotado adiante. Uma inferência do tipo "40 min está abaixo dos ~66 min/dia do estudo, logo é conservador" seria indevida — compararia uma tarefa estreita com um agregado amplo, e a fatia realmente comparável poderia ser bem menor que 40 minutos.

O resultado prático: decisões tomadas sem dados atualizados, gerando paralisações evitáveis, retrabalho e atrasos.

Fontes desta seção:

>

- ABNT NBR 14931:2023 — Estruturas de concreto — Execução. A revisão de 2023 passou a tratar explicitamente a concretagem em períodos chuvosos (Tabela 7, classificação de intensidade de precipitação).

- ABNT NBR 9574:2008 — Execução de impermeabilização.

- ABRACO — Recomendação Prática RP PAC-001: Pintura Anticorrosiva. Disponível em: https://abraco.org.br/src/uploads/2017/12/RECOMENDAO-PRTICA.pdf

- Lei nº 14.133/2021, art. 117, § 1º — Lei de Licitações e Contratos Administrativos.

- Conselho Federal de Engenharia e Agronomia — Plenário do Confea revoga Livro de Ordem de obras e serviços (fev./2023). Disponível em: https://www.confea.org.br/plenario-do-confea-revoga-livro-de-ordem-de-obras-e-servicos

- FMI Corporation & PlanGrid — Construction Disconnected (2018). Disponível em: http://pg.plangrid.com/rs/572-JSV-775/images/Construction_Disconnected.pdf

Fatores Contribuintes

Os cinco fatores abaixo são o diagnóstico do porquê o cruzamento diário entre diário de obras e clima não acontece na prática. Não se trata de uma análise formal de causa-raiz (Ishikawa ou 5 Porquês) — é o levantamento dos fatores que sustentam o problema, derivados das evidências setoriais citadas acima e do desenho normativo das decisões afetadas pelo clima.

Consequências Estimadas

Nota metodológica — de onde vêm os ~40 minutos

Este número sustenta todo o cálculo de valor da aba Métricas e ROI, então precisa ser declarado pelo que é: uma premissa de trabalho arbitrada, não uma medição.

Não houve medição. Não há cronometragem em canteiro nem coleta com engenheiros em atividade.

Não existe estudo que isole exatamente esta tarefa. O dado da FMI/PlanGrid citado acima não serve para dimensioná-la, porque agrega a busca por normas, projetos executivos, especificações e relatórios diversos — a fatia correspondente ao diário de obras é desconhecida e pode ser bem menor. O que existe é um ponto de referência adjacente, sobre o qual o baseline foi construído em duas parcelas:

Fronteira do ganho — o que o pipeline efetivamente substitui

Esta distinção importa para não superestimar o retorno, e por isso vem antes dos cálculos:

O pipeline não vai a campo e não observa a obra. A captura do que aconteceu — andar no canteiro, apurar efetivo, medir avanço, registrar ocorrências — continua sendo trabalho do engenheiro, e não é eliminada. O que a automação remove é a consolidação, a redação e o cruzamento: transformar apontamentos em um resumo legível, buscar a previsão, correlacionar chuva com frentes de serviço, derivar o plano do dia e formatar tudo para distribuição — entregue pronto, em texto e áudio.

Portanto, quanto do baseline de 40 min é de fato recuperado depende de como a rotina do cliente está organizada. Se o preenchimento do RDO permanecer integralmente manual, o tempo efetivamente devolvido ao engenheiro se aproxima da faixa inferior da análise de sensibilidade (20 min/dia) em vez dos 40 min cheios. Essa é precisamente a razão de a aba Métricas e ROI apresentar o retorno em uma matriz de cenários, e não em um número único.

Como o documento lida com a incerteza. Em vez de tratar o baseline como constante, a aba Métricas e ROI o trata como variável: a análise de sensibilidade recalcula payback e ROI para 20, 30 e 40 min/dia, e o retorno permanece positivo no primeiro ano em 8 das 9 combinações testadas. A conclusão econômica do projeto não depende de acreditar nos 40 minutos.

>

A Solução: Relatório Diário Automatizado

O objetivo do relatório é simples e direto:

• Relembrar o responsável do que aconteceu nos últimos dias, com base no diário de obras, para que ele não precise voltar às anotações.
• Informar a previsão do tempo (OpenWeather) dos próximos 5 dias, para que ele planeje ações sensíveis ao clima (concretagem, pintura externa, impermeabilização, etc.).
• Sugerir um plano de ação técnico para o dia, cruzando automaticamente as informações anteriores.
• Manter o responsável atualizado de forma prática, sem recorrer ao diário de obras e já com sugestões concretas para os próximos dias.
• Entregar o resumo em texto e áudio a gestores e demais responsáveis não-técnicos do empreendimento, em formato consumível antes do início da jornada.

Planejamento Macro (PMC)

A estruturação executiva e modelagem lógica de negócios e desenvolvimento deste projeto foi concebida utilizando a metodologia Project Model Canvas (PMC). Para uma visualização interativa e holística com todos os blocos fundamentais (Por Quê, O Quê, Quem, Como, Quando e Quanto), acesse a página Canvas de Projeto.

Em resumo: o pipeline transforma dados dispersos (diário + clima) em uma orientação técnica acionável, entregue automaticamente toda manhã (em dia útil), em texto e áudio.

Contextualização do Desafio

Este projeto se insere no contexto de uma obra de edificação residencial multifamiliar de médio porte na cidade de São Paulo, com as seguintes características simuladas para validação do protótipo:

• Tipo: Edifício residencial — 4 pavimentos
• Fase atual: Estrutura e acabamento (concretagem de lajes e alvenaria)
• Equipe: 10 a 15 operários por dia útil
• Engenheiro residente: 1 profissional responsável por diário de obras e relatórios

Nota: os registros do diário de obras são simulados — 15 apontamentos com datas fixas entre 06/04 e 20/04/2026, cobrindo 3 cenários de teste (rotina normal, chuva intensa e problema logístico) para validação reprodutível do pipeline.

Objetivos SMART

Objetivo Principal

Desenvolver um pipeline que, automaticamente, relembre o responsável do que aconteceu na obra, informe a previsão do tempo (OpenWeather) e sugira um plano de ação técnico para o dia — reduzindo o tempo de consolidação de informações de ~40 minutos por dia (manual) para menos de 5 minutos (automatizado; mediana medida de 3,5 min, P50), ao final da fase de prototipagem.

Objetivos Específicos

O2 não foi atingido na métrica de tempo — e isso é uma decisão, não um acidente.

>

O objetivo O2 estabeleceu "relatório gerado em < 60 segundos". A medição real do nó do Ollama ficou em ~72 s de média, com pico de 139 s no payload longo (aba Testes de Stress). O alvo de 60 s não foi cumprido.

>

A causa é a escolha deliberada do Qwen 2.5:14B sobre modelos de 7B/8B: o 14B excede os 6 GB de VRAM da GTX 1660 Ti e força offloading para RAM/CPU, o que custa tempo. Os modelos menores testados rodariam dentro dos 60 s, mas não entregaram a mesma qualidade de relatório — coerência técnica, aderência aos dados e formatação limpa para locução (justificativa completa na aba Arquitetura e n8n).

>

Como o pipeline roda uma vez por dia, de madrugada, sem ninguém esperando, o requisito que de fato governa o negócio é o RNF01 (< 300 s ponta a ponta) — esse sim atingido em 8 de 9 execuções, com mediana de 208 s. Em retrospecto, o alvo de 60 s foi mal calibrado na etapa de planejamento: fixou um limite de componente antes de conhecer o custo real de inferência do modelo escolhido.

>

O caminho para cumpri-lo sem perder qualidade está no roadmap (aba Métricas e ROI, Prioridade 2): LLM quantizado mais leve ou inferência em GPU dedicada, com expectativa de cortar o tempo do Ollama pela metade.

Arquitetura do Processo de Automação n8n

A arquitetura do projeto foi concebida de forma nativa e centralizada no motor n8n. A escolha por esta ferramenta deveu-se à sua capacidade de orquestração visual e declarativa, permitindo a integração fluida entre APIs externas (Clima e Geolocalização), processamento de lógica de negócio e a coordenação de microsserviços especializados.

Topologia Computacional

A infraestrutura é 100% on-premise: o n8n roda localmente, orquestrando microsserviços abertos e inferência de IA executada na própria máquina (LLM e TTS). São 17 nós — um pipeline sequencial de dados e IA, a distribuição multicanal/auditoria em paralelo e um fluxo dedicado de tratamento de erros — disparados via cron schedule.

Nota de terminologia: este sistema não é serverless. Serverless designa execução em infraestrutura gerenciada de nuvem, sob demanda e sem servidor próprio — o oposto do que acontece aqui. O termo correto é on-premise (ou edge): há um servidor, ele é físico, e é o notebook do desenvolvedor. Essa escolha é justamente o diferencial de privacidade do projeto (ver aba Ética e LGPD).

Detalhamento dos Nós da Orquestração (n8n)

O workflow é composto por 17 nós, organizados em três blocos: um pipeline sequencial de dados e IA (1–10), a distribuição multicanal e auditoria em paralelo (11–14) e um fluxo dedicado de tratamento de erros (15–17).

Pipeline sequencial (dados → IA → áudio)

• Trigger Diário (06h30) — Schedule Trigger: Disparo automático programado para todo dia útil, às 06:30. Garante que o engenheiro receba o relatório antes de iniciar a jornada do dia.
• Configurações Iniciais (Code - JS): O "cérebro" de configuração. Lê o arquivo .env local diretamente do disco (via fs.readFileSync, com NODE_FUNCTION_ALLOW_BUILTIN=fs habilitado pelo start_n8n.sh), extrai o caminho absoluto do projeto e as chaves de API, e exporta esses dados para os nós seguintes.
• Nominatim - Geocodificação (HTTP Request): Converte o nome da cidade (vinda do .env) em coordenadas geográficas (Lat/Long) via OpenStreetMap, permitindo que a previsão do tempo seja precisa para o canteiro de obras.
• OpenWeather - Previsão (HTTP Request): Coleta a previsão meteorológica detalhada para os próximos dias, utilizando a chave de API dinâmica capturada no nó inicial.
• Consolidação de Dados (Code - JS): Realiza o processamento pesado de dados:
• Lê o arquivo registros_exemplo.json (Simulação do Diário de Obras).
• Filtra os registros do dia anterior (o último dia com apontamento, pulando fins de semana/feriados sem registro).
• Agrupa e formata a previsão do tempo por dia.
• Monta o prompt final (injetando os dados) para a Inteligência Artificial.
• Ollama - Gerar Relatório (HTTP Request): Envia o prompt para o modelo de LLM rodando localmente. Solicita a geração do relatório em texto corrido e natural.
• Parsear Output do LLM (Code - JS): Captura a resposta da IA e extrai os metadados (obra, cidade, período) para compor a mensagem final.
• Preparar Texto para TTS (Code - JS): Prepara o ambiente para a síntese de voz. Grava o texto do relatório em um arquivo temporário no disco, evitando problemas de caracteres especiais em linha de comando.
• Kokoro TTS - Gerar Áudio (Execute Command): Aciona o ambiente virtual Python e executa o microsserviço generate_audio.py. Transforma o texto em um arquivo .wav de alta fidelidade usando modelos ONNX.
• Preparar Saída Final (Code - JS): Consolida os caminhos dos arquivos gerados e valida se todos os componentes estão prontos. É o ponto de ramificação: a partir dele, os quatro nós seguintes são disparados em paralelo.

Distribuição multicanal e auditoria (em paralelo)

• Telegram - Enviar Áudio (Execute Command): Utiliza curl para enviar o áudio via API de Bot do Telegram, configurando o player nativo com título e autor, e enviando o relatório em texto logo em seguida.
• Gmail - Enviar Relatório (Execute Command): Aciona o microsserviço send_email.py, enviando o relatório em HTML formatado via SMTP do Gmail para a lista de destinatários (email_recipients.csv). Configurado com continueOnFail — se o Telegram cair, o e-mail ainda sai (e vice-versa).
• Gravar Histórico em CSV (Execute Command): Registra a execução em historico_relatorios.csv, criando um índice tabular que relaciona o áudio gerado ao dia correspondente.
• Logger - Métricas de Execução (Code - JS): Persiste a duração total e os canais ativados em execution_log.json — base para a análise de performance (ver aba Métricas e ROI).

Tratamento de erros (fluxo paralelo, sob falha)

• Error Trigger: "Escuta" qualquer falha fatal em qualquer nó do pipeline.
• Error Handler Global (Code - JS): Estrutura o erro (nó, mensagem, timestamp) e o persiste em error_log.json.
• Notificar Erro via Telegram (Execute Command): Alerta imediatamente o administrador com o stack trace do erro, garantindo observabilidade sem depender da interface do n8n.

Especificações de Modelagem LLM (Qwen 2.5:14B) e TTS

Por que um modelo local, e por que o Qwen 2.5 (14B)?

A escolha por um modelo local não é uma alegação de superioridade técnica sobre modelos hospedados. Um Qwen 2.5 de 14B não compete com GPT-5 ou Claude em raciocínio complexo, e afirmar o contrário seria insustentável. A escolha foi feita por dois motivos concretos, que a tarefa em questão torna decisivos:

• Privacidade. O diário de obras é dado operacional do cliente — apontamentos, ocorrências, eventualmente nomes. Com inferência local, esse conteúdo nunca sai da máquina rumo a um modelo de terceiro. É a base do RNF02 e o argumento central da aba Ética e LGPD.
• Custo marginal zero. Não há cobrança por token nem por requisição: gerar o relatório nº 1.000 custa o mesmo que gerar o nº 1. Isso é o que torna a replicação para novas obras economicamente trivial.

Dentro dessa restrição — "tem que rodar aqui" —, o Qwen 2.5 de 14 bilhões de parâmetros foi o ponto de equilíbrio: entre os modelos testados que cabem em hardware de consumo, foi o que entregou aderência aos dados e formatação de saída limpa o suficiente para locução direta. A tarefa também ajuda: resumir apontamentos estruturados e cruzá-los com previsão de chuva é um problema delimitado, com o contexto inteiro fornecido no prompt — exatamente o tipo de trabalho em que um modelo médio local rende bem.

Decisão de projeto (trade-off consciente — qualidade × velocidade): o modelo de 14B excede a VRAM da GPU disponível (6 GB, GTX 1660 Ti), o que força parte da inferência para a RAM/CPU e aumenta o tempo de execução. Ainda assim, ele foi escolhido deliberadamente: os modelos menores (7B/8B) testados não entregaram a mesma qualidade de relatório — coerência técnica, aderência aos dados e formatação limpa para a leitura em áudio (TTS). Como o workflow roda uma vez por dia, de madrugada e sem intervenção humana, esse tempo extra de inferência não se torna uma limitação prática: prioriza-se a qualidade do relatório sobre a velocidade. Caso o cenário evolua para uso interativo/on-demand, a recomendação é migrar para um modelo quantizado mais leve ou para inferência em GPU dedicada/nuvem (ver o roadmap de melhorias na aba Métricas e ROI).

O Prompt de Engenharia (System Instructions)

Para extrair um output perfeito e formatado para leitura de áudio, o n8n utiliza um meta-prompt unificado injetado na API do Ollama:

Você é o assistente de planejamento diário do Engenheiro Ygor, responsável pela obra "{obra}", em {cidade}.

Sua função é gerar um relatório diário prático, que o engenheiro possa ouvir em áudio ou ler, e que o ajude a planejar o dia de trabalho. O relatório deve ser escrito em texto contínuo e fluente, como se estivesse falando diretamente com o engenheiro. 

IMPORTANTE: Escreva o relatório em texto corrido, sem usar títulos em negrito, sem marcadores como asteriscos (*), sem hífens decorativos (-), sem símbolos ou abreviações. O texto deve ser natural para ser ouvido em voz alta (TTS), evitando qualquer caractere que cause ruído na leitura.

Os dados abaixo são as únicas fontes de informação que você deve usar. Não invente, não suponha, não extrapole.

DIÁRIO DE OBRAS — dia anterior ({dataRefStr}):
{registrosFormatados}

PREVISÃO DO TEMPO — hoje e próximos dias:
{previsaoFormatada}

O relatório deve conter:
1. O que aconteceu no dia anterior (atividades, progresso, operários, ocorrências).
2. Previsão do tempo de hoje e dos próximos dias e impacto na obra.
3. Sugestão técnica concreta de ação para hoje e os próximos dias.

Português brasileiro. Linguagem técnica, porém natural para locução.

Lacuna conhecida — o nome do engenheiro está fixo no prompt. A obra e a cidade vêm de variáveis ({obra}, {cidade}), mas o nome do responsável está escrito diretamente no texto do prompt, dentro do nó Consolidação de Dados. Isso contradiz o princípio de "ponto único de verdade no .env" defendido na aba Robustez e Escala: da forma atual, replicar o pipeline para outra obra exigiria editar o JSON do workflow, e não só trocar o .env. A correção é pequena — ler um ENGENHEIRO_NOME do .env no nó de configuração e interpolá-lo no prompt — e está registrada no roadmap (aba Métricas e ROI, Prioridade 3, multi-tenant e onboarding templatizado). Está documentada aqui porque o requisito de multi-tenant do documento só se sustenta depois dessa mudança.

Tratamento de Áudio com Kokoro-ONNX

O output primário é enviado ao microsserviço assíncrono mantido em Python (scripts/generate_audio.py), que recebe o texto limpo, processa a síntese via API neural local em ONNX e gera o arquivo .wav com voz nativa do Português do Brasil.

Resultado Final e Prova de Conceito

Abaixo, a demonstração da entrega final realizada pelo sistema, em paralelo, nos dois canais de distribuição: Telegram (áudio com player nativo + relatório em texto) e E-mail (relatório HTML formatado).

Ouça o relatório. Este é o áudio gerado pelo pipeline — voz sintetizada localmente pelo Kokoro TTS (pf_dora, pt-BR), a partir do texto que o LLM produziu. Trecho de 40 segundos da execução de 22/06/2026, sem edição:

Duas ressalvas honestas sobre esta prova de conceito.

>

1. As datas do relatório vêm da base de teste, não do calendário. No áudio e no print acima, o sistema apresenta como "ontem" um apontamento de 20 de abril de 2026, enquanto o "hoje" da previsão do tempo é 23 de junho. Isso é esperado neste ambiente: o diário usado é a fixture registros_exemplo.json, com 15 registros fixos entre 06/04 e 20/04/2026, criada para reproduzir três cenários controlados. Ela não avança com o calendário, então toda execução posterior a 21/04 seleciona 20/04 como último dia com apontamento. A previsão do tempo, essa sim, vem da API em tempo real — daí a distância entre as duas datas.

>

O ponto que de fato merece atenção é outro: o nó de consolidação não impõe limite de idade ao registro que seleciona. Isso é inócuo com dados de teste, mas em produção significa que um diário sem preenchimento há uma semana produziria um relatório apresentando dado velho como recente, com sugestão de ação em cima dele. A guarda de frescor que resolve isso está detalhada na aba Análise e Limitações e consta do roadmap.

>

2. Os prints são de uma versão anterior do bot. O nome que aparece no Telegram (Relatório_Semanal_...) é resquício da fase em que o projeto rodava semanalmente; a cadência atual é diária. As capturas também estão em tela de celular (com barra de status e de navegação) e o e-mail aparece em modo escuro, o que prejudica a leitura do HTML formatado. Refazer os prints — bot renomeado, Telegram Web e Gmail Web em modo claro, com dados coerentes — está pendente.

Análise Crítica e Limitações Estruturais

Apesar do elevado grau de automação e integração autônoma construído por este projeto, existem potenciais fragilidades técnicas e logísticas na infraestrutura que precisam ser monitoradas e mitigadas antes da submissão a um patamar Enterprise-Grade de larga escala ou SaaS.

APIs Públicas em Free-Tier

Risco: O pipeline consome abertamente as rotas globais do OpenStreetMap Nominatim e da OpenWeather API.

• Nominatim: Os Terms of Use do OpenStreetMap desencorajam ativamente consultas pesadas e automatizações de massa, operando com regras estritas de limitação de taxa (ex: 1 request/segundo). Caso mais workflows passem a invocar esse recurso de maneira simétrica, é provável a inserção do Endereço IP do container em listas de negação/bloqueio.

• OpenWeather: A API gratuita suporta limites generosos de requisições diárias (~1.000/dia no free tier), muito acima da necessidade atual de 1 requisição por dia útil. Exige chave de API configurada.

Mitigação implementada:

• Header de identificação: Configurado o User-Agent personalizado (relatorio-obra/1.0) conforme exigido pelos termos do Nominatim.
• Frequência de consulta controlada: O pipeline executa 1x por dia útil (~21x/mês), mantendo-se muito abaixo de qualquer limite de taxa do Nominatim (1 req/s) e do OpenWeather (~1.000 req/dia no free tier).

Mitigação pendente (roadmap):

• Cache de geocodificação: como as coordenadas de uma obra não mudam, o par lat/lon deveria ser resolvido uma única vez e fixado no .env (ou em um cache local), eliminando por completo a dependência recorrente do Nominatim. Ainda não implementado — hoje o pipeline consulta o Nominatim a cada execução. Consta como item da Prioridade 3 do roadmap (aba Métricas e ROI). O risco atual é baixo (1 requisição por dia útil, muito abaixo do limite), mas a dependência é evitável e desnecessária.

O Preço da Alucinação Generativa

Risco: Modelos de 4 a 14 bilhões de parâmetros geram texto plausível, não verificado. O risco concreto aqui é a correlação espúria: o modelo recebe "4 mm de chuva prevista" e pode concluir que a concretagem da laje deve ser suspensa — mas essa relação não é automática no mundo físico. Ela depende da drenagem do canteiro, da fase da cura, da cobertura disponível e da janela de aplicação, informações que não estão no dado enviado ao modelo. Ele infere a partir do que soa razoável no texto, sem acesso à realidade da obra. Quanto menor o modelo, maior a tendência a preencher essa lacuna com o que é estatisticamente comum em vez do que é tecnicamente correto.

Mitigação implementada:

• Prompt Engineering restritivo: O prompt delimita estritamente 3 seções (dados, previsão, recomendação) e instrui explicitamente "não invente, não suponha, não extrapole", reduzindo a margem para divagação ou correlações espúrias.
• Limite de tokens (num_predict: 2048): Impede respostas excessivamente longas, onde alucinações tendem a se acumular.
• Validação humana no primeiro mês: Recomenda-se que o engenheiro residente revise os relatórios nas primeiras 4 semanas antes de confiar plenamente no output automatizado. A decisão técnica permanece, em qualquer cenário, do responsável pela obra (ver aba Ética e LGPD).

Sobre a temperatura de 0.7 — trade-off assumido, não mitigação.

>

O pipeline roda com temperature: 0.7. Esse valor é alto para geração factual ancorada em dados: a prática comum em tarefas que não podem inventar é 0.1–0.3, e seria desonesto apresentar 0.7 como se fosse uma calibragem de segurança contra alucinação. Não é — é o oposto.

>

A escolha foi deliberada e tem um motivo específico deste projeto: o texto é feito para ser ouvido, não lido. Em temperaturas baixas, o modelo produziu relatórios corretos porém repetitivos e telegráficos, com estrutura previsível frase a frase — algo tolerável em tela, mas cansativo em locução de dois minutos. A 0.7 o texto ganha variação de construção e soa como alguém falando, que é o requisito de produto (o relatório concorre com o rádio do carro a caminho da obra).

>

O custo desse ganho é maior variabilidade, e ele é pago com as outras três barreiras: prompt restritivo com dados fechados, limite de tokens e validação humana no primeiro mês. É um trade-off consciente entre fluidez de locução e determinismo, e não uma afirmação de que 0.7 protege contra alucinação.

>

Próximo passo (roadmap): rodar uma bateria comparativa a 0.2, 0.3 e 0.7 sobre os mesmos três cenários de teste, avaliando (a) aderência aos dados e (b) qualidade percebida da locução, para trocar esta justificativa por uma medição.

Bloqueio Temporal de Hardware (Concorrência Sequencial)

Risco: O TTS roda via executeCommand porque o n8n não tem nó nativo para o Kokoro — a síntese é delegada a um script Python isolado (generate_audio.py). O efeito colateral é que as bibliotecas kokoro_onnx e soundfile carregam o modelo ONNX na memória a cada execução, logo depois de o LLM liberar a sua. Em hardware limitado, essas duas cargas disputam a mesma VRAM (ou a RAM compartilhada), e uma sobreposição entre elas causaria falha por falta de memória. Em máquinas edge mais fracas, o encadeamento das duas inferências também gera aquecimento sustentado e consequente throttling térmico.

Mitigação implementada:

• Execução sequencial garantida: O pipeline de dados e IA é linear (10 nós em série, do gatilho à preparação da saída), garantindo que o TTS só inicia após o LLM terminar completamente, evitando concorrência por VRAM. A distribuição multicanal ocorre apenas depois, em paralelo.
• Timeout de segurança (300s): O nó de requisição ao Ollama tem timeout de 5 minutos, prevenindo travamentos em caso de modelo lento.
• Trade-off de hardware assumido conscientemente: O modelo de 14B excede os 6 GB de VRAM (GTX 1660 Ti) e usa offloading para RAM/CPU — uma escolha deliberada por qualidade do relatório (modelos menores 7B/8B não atingiram o mesmo nível). É viável porque a execução é diária e off-line, tornando o tempo extra irrelevante (ver aba Arquitetura e n8n, "Especificações de Modelagem LLM e TTS"). O timeout de 300s cobre com folga a inferência resultante. O custo dessa decisão está registrado abertamente: o objetivo O2 (< 60 s de geração) não foi atingido — ver aba Diagnóstico e Objetivos.

Ausência de Guarda de Frescor no Dado de Entrada

Risco: O nó Consolidação de Dados seleciona o último registro do diário anterior à data de execução, sem verificar há quanto tempo esse registro foi feito. A regra existe para pular fins de semana e feriados sem apontamento — comportamento correto e desejado —, mas não tem limite superior. O pipeline não sabe distinguir "não há registro de ontem porque foi feriado" de "não há registro de ontem porque ninguém preencheu o diário há duas semanas": nos dois casos ele volta no tempo até achar algo e apresenta o que encontrar como o dia anterior.

Como isso ficou visível — e o que ele não significa. O relatório demonstrado na aba Arquitetura e n8n narra como "ontem" um apontamento de 20 de abril e situa o "hoje" em 23 de junho. Esse descompasso é um artefato do ambiente de teste, não um defeito em operação: a base registros_exemplo.json é uma fixture estática com 15 registros fixos entre 06/04 e 20/04/2026, construída para reproduzir três cenários controlados (rotina normal, chuva intensa e problema logístico). Datas fixas são exatamente o que se quer de uma base de teste — sem elas, os cenários não seriam reproduzíveis. Como a fixture não acompanha o calendário, qualquer execução posterior a 21/04 seleciona 20/04, e a distância cresce com o tempo. O pipeline fez precisamente o que foi programado para fazer.

O que o episódio de fato revela é uma lacuna de projeto que a base de teste apenas tornou observável: em produção, com um diário real, a mesma regra de seleção apresentaria um apontamento de uma semana atrás como se fosse de ontem, caso o engenheiro deixasse de preencher. E aí importa. O sistema não erraria ao gerar o texto — erraria ao selecionar o dado, e o LLM narraria fielmente o que recebeu. Nenhuma das mitigações de alucinação descritas acima protege contra isso, porque o dado é legítimo, apenas está vencido. O resultado seria um plano de ação construído sobre uma frente de serviço que já mudou — o cenário de "alucinação com consequência física" descrito na aba Ética e LGPD, com origem no dado e não no modelo.

Mitigação proposta (não implementada — item de roadmap):

• Guarda de frescor no nó de consolidação: comparar a data do último registro com a data de execução. Se a defasagem exceder N dias úteis (sugestão: 3), não tratar o registro como "ontem".
• Degradação explícita no relatório: nesse caso, o prompt deve receber a defasagem como dado ("último apontamento: 12 dias atrás") e instruir o modelo a declará-la abertamente na abertura do relatório.
• Supressão da sugestão técnica: com dado defasado, a seção de plano de ação deve ser substituída por um alerta de diário desatualizado — melhor não sugerir do que sugerir sobre base vencida.
• Alerta ao responsável: reaproveitar o canal de notificação de erro já existente para avisar que o diário está sem preenchimento.

Como efeito colateral bem-vindo, a guarda também resolve o incômodo da demonstração: com ela, uma execução sobre a fixture de abril passaria a declarar a defasagem em vez de silenciá-la.

Relatório de Testes de Stress — Pipeline Multicanal

Gerado em: 25/05/2026 às 16:12

Como ler estes números — limitações do desenho do teste.

>

- n = 3 rodadas por combinação componente × payload. É amostra pequena: suficiente para dimensionar ordens de grandeza e identificar o gargalo dominante, insuficiente para estimar caudas de distribuição ou percentis com confiança. Onde este documento afirma "média", leia "média de três medições" — a mesma ressalva de amostra que a aba Métricas e ROI aplica ao intervalo de Wilson vale aqui.

- A coluna RAM MB é ocupação total do sistema, não do processo. Os ~14–15 GB reportados nas linhas do Ollama e do TTS são a memória em uso na máquina inteira durante a medição, não o consumo do modelo isolado — o que explica por que aparecem valores acima dos 6 GB de VRAM da GPU. Com os 32 GB de RAM da máquina de referência, esse patamar representa pouco menos da metade da capacidade total — folga confortável, não saturação. Serve para mostrar a ordem de grandeza do offloading para RAM/CPU quando o modelo excede a VRAM, não um sinal de risco de memória.

- Ambiente: notebook com GTX 1660 Ti (6 GB VRAM), 32 GB RAM, execução local, rede residencial. Sem isolamento de carga: outros processos do sistema operacional estavam ativos.

Resumo por Componente

Análise de Gargalos

Ranking de Latência (maior → menor)

Teste de Rajada (Burst) — SMTP

Reflexão Crítica sobre os Resultados

Com base nos resultados dos testes executados em 25/05/2026, apresenta-se a seguinte análise crítica do pipeline:

>

1. Qual é o gargalo real do pipeline?

O gargalo incontestável é o componente local de Inteligência Artificial, primariamente o Ollama (LLM), com média de ~72s (chegando a picos de 139s no payload longo, com CPU atingindo 99.8%), seguido pelo Kokoro TTS (~38s, com pico de 78s para textos de 3504 caracteres). Eles dominam quase 100% do tempo de execução. Para o otimizar, seria essencial diminuir a parametrização do modelo local (ex: de 14B para 7B/8B) ou mover a inferência de CPU para uma GPU robusta.

>

2. Existe correlação entre tamanho do payload e latência?

Sim, forte e linear para componentes de IA. No TTS, o tempo saltou de ~5.4s (140 chars) para ~78s (3504 chars). No Ollama, a latência cresce de ~4.7s (55 chars) para ~132.8s (1105 chars). Em contrapartida, os canais de rede (SMTP e texto do Telegram) apresentam tempos praticamente constantes (~3.1s e ~0.75s respectivamente), revelando que a latência de transferência de pequenos KB não é impactada pelo tamanho real do payload.

>

3. O que explica o outlier de 30,8 s no Telegram com payload curto?

Essa linha merece explicação porque é a maior anomalia da tabela: mín 0,736 s, méd 10,756 s, máx 30,777 s — variação de ~40× em uma mensagem de 38 caracteres. As outras três combinações do Telegram (médio, longo, upload de áudio) são estáveis, com tempos entre 0,74 s e 4,4 s e desvio irrelevante. Como a rodada de payload curto é a primeira chamada da bateria do Telegram, a hipótese mais provável é custo de conexão fria: resolução DNS, handshake TLS com api.telegram.org e possivelmente uma retentativa por timeout de rede — as duas rodadas seguintes, com a conexão já aquecida, voltaram a ~0,75 s. Um throttle do lado da API é menos provável, já que o volume era de uma mensagem.

Ressalva: isso é hipótese, não diagnóstico — o script não registra o tempo de handshake separadamente, então não há como confirmar pelos dados coletados. O que se pode afirmar com segurança é que a média de 10,756 s não representa o comportamento típico do canal; a mediana das três rodadas (~0,75 s) representa. Instrumentar a fase de conexão e repetir com n maior é o que fecharia essa questão.

Em termos de impacto: mesmo que o pior caso de 30 s se repetisse todo dia, ele consumiria ~10% do SLA de 300 s, e o canal de e-mail seguiria entregando em paralelo.

>

4. O teste de rajada SMTP revelou degradação?

Não. O envio em massa de 6 e-mails levou apenas ~18.3 segundos no total (média de ~3.05s por e-mail), com uma degradação negativa (-0.015s), confirmando que a conexão TLS aquecida mantém performance estável. Não há throttle evidente do Gmail para essa volumetria.

>

5. Quais otimizações seriam prioritárias para escalar?

* Adoção de um LLM quantizado mais veloz (Llama 3 8B q4) para cortar o tempo do Ollama pela metade.

* Uso de ThreadPools caso múltiplos áudios pequenos precisassem ser gerados (o script Python atual do TTS é sequencial).

* Manter a conexão SMTP (Session Pooling) se o sistema for usado para disparos para milhares de pessoas de forma individualizada.

>

6. O sistema está pronto para produção?

Sim, para o escopo definido (cronjob diário rodando de madrugada). Como a execução de ~3,5 minutos (mediana) ocorre às 06:30 localmente e sem intervenção humana, antes do início da jornada, a latência do Ollama é tolerável. Se o cenário mudar para uma API interativa em tempo real (on-demand), será mandatório migrar a inferência de IA para nuvem (OpenAI / Groq) ou para servidor físico com GPUs dedicadas.

Robustez, Escalabilidade e Boas Práticas

Para que um sistema de automação deixe de ser apenas um script utilitário e alcance o patamar Enterprise-Grade (preparado para produção e escalabilidade), ele precisa ser resiliente a falhas, facilmente monitorável e configurável sem alteração de código.

Tratamento de Erros e Resiliência (Error Handling)

A manipulação de erros foi projetada em duas camadas (Orquestrador e Microsserviços), visando garantir que o engenheiro sempre saiba o que aconteceu, sem que falhas parciais quebrem o fluxo inteiro.

Como foi implementado:

• Error Handler Global (n8n): Existe um fluxo de gatilho de erro (Error Trigger) que "escuta" qualquer falha fatal no pipeline. Caso o Nominatim negue a conexão ou o Ollama sofra um timeout, o nó de notificação via Telegram é acionado imediatamente com a stack trace do erro, avisando o administrador.
• Fallbacks de Continuidade (continueOnFail): Os nós paralelos de distribuição (Telegram e Gmail SMTP) estão configurados para continuar em caso de falha. Se a API do Telegram estiver fora do ar, o envio de E-mail acontece normalmente, garantindo que a informação chegue por pelo menos um canal.
• Retry com Exponential Backoff (Python): O microsserviço send_email.py intercepta exceções transitórias (ex: smtplib.SMTPException) e tenta o envio até 3 vezes, aguardando 2s, 4s e 8s entre as tentativas, abortando apenas em erros definitivos de autenticação.

Justificativa Arquitetural

Em ambientes de microsserviços integrados a APIs públicas em free-tier (OpenWeather, Nominatim, Telegram), a instabilidade de rede é uma certeza estatística, não uma probabilidade. Se o pipeline falhar silenciosamente por causa de uma queda de 5 segundos no SMTP, o engenheiro perderá o relatório de planejamento daquele dia. O graceful degradation (falhar graciosamente) garante confiança no sistema.

Logs Interpretáveis e Auditoria Estruturada

O monitoramento não depende da interface gráfica do n8n; ele gera telemetria agnóstica para ingestão externa.

Como foi implementado:

• JSON de Execução: O arquivo data/output/execution_log.json é populado a cada execução bem-sucedida, registrando a duração total do pipeline e os canais que foram ativados com sucesso.
• Log de Erros Isolado: Caso o Error Handler Global seja acionado, o erro é estruturado e persistido em error_log.json.
• Histórico CSV: A execução adiciona uma linha no arquivo historico_relatorios.csv, criando um índice tabular rápido de relacionar um áudio .wav gerado ao dia correspondente.
• Standard Out/Err (Python): Os microsserviços utilizam a biblioteca logging nativa do Python, entregando logs padronizados (INFO, WARNING, ERROR) diretamente ao terminal do orchestrator.

Justificativa Arquitetural

Depender do banco de dados SQLite interno do n8n para histórico de execuções é um gargalo de observabilidade. Ao persistir os logs em JSON e CSV no file system, a infraestrutura fica pronta para uma stack de observabilidade convencional, sem adicionar sobrecarga ao n8n. O caminho seria um coletor lendo os arquivos e uma camada de visualização por cima — por exemplo, Promtail → Loki → Grafana, ou Filebeat → Elasticsearch → Kibana. (Vale a precisão: o Grafana não faz ingestão de arquivos; ele consulta uma fonte de dados. Quem lê o arquivo é o coletor.) Com isso, alertas de degradação de latência ou de queda na taxa de sucesso passam a ser configuráveis sem tocar no workflow.

Uso Consistente de Variáveis de Ambiente (.env)

O código e o ambiente estão estritamente separados, seguindo os princípios do Twelve-Factor App.

Como foi implementado:

• Ponto Único de Verdade: Todas as chaves de API, credenciais SMTP, modelo LLM em uso e até a cidade alvo da obra estão armazenados unicamente no arquivo .env.
• Injeção via Wrapper: O arquivo de inicialização start_n8n.sh faz o _source_ do .env e habilita NODE_FUNCTION_ALLOW_BUILTIN=fs antes de levantar o orquestrador.
• Nó de Configuração Inicial: o nó 1 (Configurações Iniciais) lê o arquivo .env diretamente do disco com fs.readFileSync, faz o parse das chaves e propaga os valores pelo restante do fluxo. É por isso que o start_n8n.sh precisa liberar o módulo fs — sem essa permissão, o nó falha.
• Proteção de Repositório: O arquivo real é ignorado pelo .gitignore, e um arquivo documentado .env.example é disponibilizado para integração de novos desenvolvedores.

Justificativa Arquitetural

Hardcoding (chumbar variáveis no código) impede a portabilidade. O uso estrito do .env permite que este pipeline seja clonado e rodado para várias obras ao mesmo tempo: bastaria instanciar N containers, injetando um .env diferente em cada um (com cidades, tokens e chats específicos), sem alterar o JSON do workflow.

Ressalva honesta sobre esse "sem alterar uma linha". Hoje ainda não é verdade por completo: o nome do engenheiro responsável está escrito diretamente no texto do prompt, dentro do nó Consolidação de Dados (ver aba Arquitetura e n8n). Enquanto esse valor não vier do .env, replicar para outra obra exige editar o workflow — e o princípio de "ponto único de verdade" descrito acima vale para tudo, menos para esse campo. A correção é pequena e está no roadmap; até lá, o registro correto é este.

Organização Escalável via Microsserviços

Em vez de centralizar toda a lógica num único script monolítico de Python ou tentar forçar o n8n a processar áudio nativamente, adotou-se uma arquitetura de orquestração delegada.

Como foi implementado:

• O n8n atua puramente como "Maestro" (Orquestrador de rede, Cronjob e HTTP routing).
• Processamentos pesados de CPU (Síntese Neural Kokoro TTS) e fluxos stateful complexos (SMTP Timeout Handshake) são delegados via subprocessos para Workers em Python (generate_audio.py, send_email.py).

Justificativa Arquitetural

Essa organização abre um caminho claro para escalar horizontalmente — vale registrar que é um caminho projetado, não um resultado demonstrado: até aqui o sistema rodou apenas em uma máquina, e nenhuma execução distribuída foi testada. O desenho, porém, é o que torna essa evolução barata: se amanhã o modelo TTS Kokoro ficar pesado demais para a CPU local, o script generate_audio.py pode ser movido para uma GPU alugada na nuvem, e o n8n apenas trocará um comando local por uma chamada de API ou execução remota via SSH, sem quebrar o workflow principal. Cada ferramenta faz apenas o que foi desenhada para fazer melhor.

Métricas de Performance, Confiabilidade e ROI

Esta seção analisa quantitativamente o desempenho do pipeline em produção (latência real ponta a ponta), modela a taxa de sucesso considerando os riscos de uma operação on-premise, e quantifica o valor gerado para o cliente (tempo de engenharia recuperado, payback e ROI) junto com a viabilidade econômica da solução. Ao final, propõe um roadmap de melhorias priorizadas.

Latência: Tempo Real de Ponta a Ponta

Como o sistema opera localmente e de forma assíncrona (cronjob de madrugada), a métrica de latência relevante para o negócio é o tempo total decorrido entre o disparo do workflow e a entrega multicanal (Telegram + E-mail). Esse valor é registrado automaticamente em data/output/execution_log.json a cada execução bem-sucedida.

Número de manchete usado em todo o portal: a mediana (P50) de 3,5 min. A média (3,66 min) aparece somente na tabela de estatística descritiva abaixo. Onde este documento, o hero ou os painéis de síntese citarem "3,5 min", trata-se sempre da mediana das 9 execuções medidas.

Execuções reais medidas (n = 9)

Estas 9 execuções são de homologação, não de operação contínua. Sete delas ocorreram em ~45 minutos do dia 19/05 e as outras duas em 25/05 — são rodadas de teste disparadas manualmente para medir o pipeline, e não 9 dias de produção. Nenhuma conclusão deste documento depende de tratá-las como série temporal.

Estatística descritiva da latência ponta a ponta

Leitura crítica: A latência mediana real (≈ 3,5 min) está confortavelmente dentro do requisito não-funcional RNF01 (< 5 min / 300s). Apenas 1 das 9 execuções (a #8, com 308s) ultrapassou o teto em ~8 segundos — provavelmente por um relatório mais longo combinado com pressão de memória. Esse resultado confirma que o protótipo é apto para o cenário de uso definido (entrega diária de madrugada, antes do início da jornada), onde mesmo 5 minutos são imperceptíveis para o usuário.

>

Nota sobre a cadência diária: estas 9 execuções foram medidas com o gatilho de homologação processando uma janela maior de dados. No modo diário, cada execução consolida apenas o dia anterior (≈ 1/7 do volume de registros), o que reduz o tamanho do prompt enviado ao LLM. Portanto, os números acima são um teto conservador — a latência diária tende a ser igual ou menor.

Decomposição da latência (onde o tempo é gasto)

Cruzando o tempo ponta a ponta com os testes de stress por componente (aba Testes de Stress), fica claro que a inferência de IA local domina o orçamento de tempo:

Conclusão: ~85% do tempo é consumido por dois nós de IA on-device. Otimizar a rede ou o n8n teria efeito desprezível; toda alavanca de melhoria de latência está na camada de modelos.

Efeito colateral registrado: é essa mesma escolha de modelo que faz o objetivo O2 (< 60 s de geração) não ser atingido — o nó do Ollama mede ~72 s de média. O alvo de negócio (RNF01, < 300 s ponta a ponta) é cumprido; o alvo de componente, não. A discussão completa está na aba Diagnóstico e Objetivos.

Ganho sobre o processo manual (baseline)

A premissa mais sensível do documento é o baseline de 40 minutos, não a latência medida — e ela é composta a partir de uma referência setorial adjacente, não medida diretamente. Soma-se a isso a fronteira do ganho: parte dessa rotina (a captura do dado em campo) não é substituída pelo pipeline, o que puxa o tempo efetivamente recuperado para baixo do teto de 40 min. Se o tempo manual real for de 20 minutos, o ganho cai para ~5,8× e o valor anual gerado cai pela metade, sem ainda assim inverter a conclusão econômica (ver a análise de sensibilidade adiante). É justamente por não ser um número apurado que ele entra na matriz de sensibilidade como variável, em vez de ser tratado como dado.

Taxa de Sucesso e Confiabilidade (Operação On-Premise)

Premissa adotada (conforme alinhamento): como o sistema roda em hardware local, a "taxa de sucesso" não se resume a o software funcionar — ela precisa incorporar os riscos físicos de uma operação on-premise: queda de energia, indisponibilidade da máquina, travamento de SO/processo, falha de rede e instabilidade das APIs públicas.

Sucesso observado vs. confiabilidade modelada

• Sucesso observado (controlado): 9 de 9 execuções concluídas (100%), todas com os 3 canais ativados (telegram, email, csv).
• Ressalva estatística honesta: com apenas 9 amostras, não é defensável afirmar "100% de confiabilidade". O intervalo de confiança de Wilson (95%) para 9/9 tem limite inferior de ~70%. Por isso, modelamos a confiabilidade esperada em regime contínuo a partir das taxas de falha de cada dependência.

Modelo de confiabilidade por execução

Cada execução só é bem-sucedida se todas as etapas críticas ocorrerem. O sistema falha graciosamente (multicanal + retry), então a falha de um único canal não derruba o pipeline — só há falha total se um componente crítico cair ou se ambos os canais falharem.

Cálculo composto (produto das probabilidades):

P(sucesso) ≈ 0,995 × 0,999 × 0,995 × 0,990 × 0,9995 ≈ 0,9787

Leitura crítica: Uma taxa de ~98% por execução é mais que adequada para uma cadência diária — e, ao contrário do modelo semanal, a falha de um dia tem baixo impacto: o relatório do dia seguinte cobre a lacuna (auto-recuperação natural da cadência diária). Os ~5 relatórios perdidos/ano se diluem em 252 execuções. O elo mais fraco não é o código, e sim a infraestrutura física (máquina ligada + energia). O graceful degradation já implementado (multicanal, retry, error handler global) protege bem contra falhas de rede/canal; o que falta endereçar é a disponibilidade do host.

O risco dominante: disponibilidade do host pessoal

O maior risco para uma operação on-premise em notebook pessoal é simplesmente a máquina não estar ligada/acordada todo dia útil às 06:30. A premissa P1 (aba Canvas de Projeto) assume o servidor disponível, mas em uso real isso é frágil — e numa cadência diária a exigência de disponibilidade é ainda maior. As mitigações estão no roadmap ao final desta aba: máquina dedicada always-on, wake timer/BIOS, watchdog com re-disparo e fallback opcional para nuvem.

Valor Gerado e Viabilidade Econômica

Importante: os valores abaixo são estimativas paramétricas com premissas explícitas para o mercado brasileiro. São facilmente ajustáveis — basta alterar a taxa-hora, os dias úteis ou o custo de implantação de referência. O objetivo é demonstrar a lógica de viabilidade econômica, não cravar um número exato.

Valor gerado para o cliente (construtora)

Custo-hora do engenheiro residente (base legal verificável): salário de 8,5 salários mínimos × R$ 1.621,00 = R$ 13.778,50/mês. Com jornada de 8 h × 21 dias úteis = 168 h/mês, o custo-hora é ≈ R$ 82,00/h — ou ≈ R$ 55,00 a cada 40 minutos.

Fontes dos dois números:

>

- 8,5 salários mínimos não é uma estimativa de mercado: é o salário mínimo profissional dos engenheiros previsto na Lei nº 4.950-A/1966, que fixa 6 salários mínimos para jornada de 6 horas e 8,5 salários mínimos para jornada de 8 horas — piso legal fiscalizado pelo sistema CONFEA/CREA. Usar o piso legal, e não uma pesquisa salarial, torna a premissa verificável e conservadora — a remuneração praticada para o cargo costuma ficar acima do piso.

- R$ 1.621,00 é o salário mínimo nacional vigente em 2026, reajustado a partir de 1º de janeiro de 2026 (era R$ 1.518,00 em 2025). Se este documento for lido em ano posterior, é este o valor a atualizar.

>

Duas ressalvas metodológicas:

>

1. O divisor de 168 h/mês (8 h × 21 dias úteis) é o mais desfavorável ao cálculo do que se usa como referência a jornada legal de 44 h semanais (~191 h/mês), que produziria ≈ R$ 72/h e economia de ~R$ 48 por execução. A conclusão econômica não muda — ver a análise de sensibilidade adiante.

2. O cálculo usa o salário-base, sem encargos. Com encargos sociais (~+70%: FGTS, INSS, 13º, férias), o custo real para a construtora seria ~R$ 140/h e a economia ~R$ 93/execução. Portanto, R$ 55 é um piso seguro, não uma projeção otimista.

A cada execução, o engenheiro economiza os ~40 minutos que gastaria compilando o diário e o clima manualmente — tempo redirecionado para atividades de maior valor agregado (gestão de equipe, análise, decisão em campo). Como o relatório agora é diário (todo dia útil), o valor se acumula:

(Upside não contabilizado neste piso: os encargos sociais elevariam o valor a ~R$ 23 mil/ano; e o retrabalho evitado — concretagem ou pintura externa programadas em dia de chuva — costuma ser o maior valor financeiro na construção. Também não monetizados: melhor comunicação com a diretoria, rastreabilidade e decisões mais bem informadas.)

Retorno para o cliente (payback e ROI)

O retorno depende de duas premissas que não são medidas, e sim arbitradas: o custo de implantação (não há venda realizada — não existe preço praticado) e o baseline de 40 min/dia (premissa arbitrada, ver aba Diagnóstico e Objetivos). Fixar um número único para cada uma e anunciar "ROI de 208%" transformaria duas suposições em um resultado. Em vez disso, o quadro abaixo mostra como a conclusão se comporta quando as duas premissas variam.

ROI no 1º ano — sensibilidade cruzada

Payback (meses) — mesma matriz

O que a matriz mostra: em 8 das 9 combinações o investimento se paga dentro do primeiro ano. A única célula negativa é o pior cenário simultâneo — implantação cara (R$ 8.000) e baseline manual de apenas 20 minutos —, e mesmo ali o retorno vira positivo no segundo ano, já que o custo recorrente de operação é ~R$ 0. Ou seja: a conclusão "vale a pena" é robusta às premissas, e não uma consequência de escolher os números certos.

Todo o retorno acima considera apenas o tempo de engenharia recuperado — o retrabalho evitado (uma concretagem ou pintura externa cancelada a tempo por causa da previsão de chuva), tipicamente o maior componente de valor na construção, entraria como upside e não está em nenhuma célula das tabelas.

Viabilidade econômica da solução

Do lado da construção da solução, o esforço total foi de ~150 h (pesquisa, desenvolvimento, testes e documentação) sobre uma stack 100% open-source, sem custos de licença ou de API. Disso decorrem duas propriedades econômicas que sustentam a viabilidade:

• Custo marginal de operação próximo de zero: toda a inferência (LLM + TTS) roda localmente; não há cobrança por token, por requisição ou por usuário — gerar o relatório nº 1.000 custa o mesmo que gerar o nº 1.
• Custo de replicação baixo: implantar o sistema em uma nova obra se resume a configurar variáveis de ambiente e canais de entrega. Num cenário comercial, o investimento de desenvolvimento se dilui rapidamente ao replicar a solução em poucas obras ou clientes, com esforço incremental mínimo por implantação.

Propostas de Melhoria (Roadmap Priorizado)

Melhorias derivadas diretamente das métricas acima, ordenadas por impacto × esforço.

Prioridade 0 — Lacunas conhecidas (precedem qualquer otimização)

Itens abertos que fecham lacunas já identificadas e documentadas neste portal. Não otimizam nada — apenas alinham o sistema ao que a documentação afirma sobre ele:

• Guarda de frescor no nó Consolidação de Dados: a seleção do "dia anterior" não impõe limite de idade ao registro, então um diário sem preenchimento recente produziria um relatório apresentando dado vencido como atual. Inócuo com a base de teste, relevante em produção — detalhamento e correção proposta na aba Análise e Limitações.
• Parametrizar o nome do engenheiro no prompt: valor hoje fixo no workflow, o que bloqueia a replicação multi-obra prometida pelo desenho de .env (ver abas Arquitetura e n8n e Robustez e Escala).
• Bateria comparativa de temperatura (0.2 / 0.3 / 0.7) sobre os três cenários de teste, para substituir a justificativa qualitativa do parâmetro por medição.
• Refazer as capturas de tela da prova de conceito com o bot renomeado, dados coerentes e captura em desktop no modo claro.

Prioridade 1 — Confiabilidade do host (maior risco, baixo esforço)

• Máquina dedicada always-on (mini-PC ou servidor) em vez de notebook pessoal — elimina o risco #1 (máquina desligada/suspensa).
• No-break (UPS) ou operação em notebook com bateria saudável — protege a janela de execução contra quedas de energia.
• Watchdog + re-disparo automático: se o execution_log.json não registrar sucesso até X horas após o gatilho, re-executar e/ou alertar (potencial de elevar a taxa de sucesso de ~98% para ~99,5%+).

Prioridade 2 — Latência (alto impacto técnico)

• LLM quantizado mais leve (ex.: Llama 3 8B / Qwen 2.5 7B em q4): expectativa de cortar o tempo do Ollama pela metade (~72s → ~35s), reduzindo a latência ponta a ponta de ~220s para ~130–150s.
• Inferência em GPU dedicada (offload do Ollama) em vez de CPU.
• TTS paralelizado (ThreadPool) caso múltiplos áudios passem a ser gerados.

Prioridade 3 — Escalabilidade & negócio

• Cache de geocodificação (fixar lat/lon no .env/DB) — remove a dependência recorrente do Nominatim. Ainda não implementado, apesar de a aba Análise e Limitações já descrever o mecanismo.
• Fallback para nuvem (Groq/OpenAI) acionado só quando o LLM local falhar — eleva confiabilidade sem custo recorrente em regime normal.
• Multi-tenant + onboarding templatizado — reduz o esforço de implantação por obra/cliente, pré-requisito para escalar a solução comercialmente (modelo SaaS).
• Dashboard de monitoramento (ingestão dos logs JSON/CSV em Grafana) para acompanhar latência e taxa de sucesso ao longo do tempo.

Resumo executivo desta seção: Latência mediana real de 3,5 min (P50) — ~11× mais rápida que o baseline manual estimado de ~40 min e dentro do SLA de 300 s em 8 de 9 execuções; confiabilidade modelada de ~98% por execução, limitada pela infraestrutura física e não pelo software, com falhas de baixo impacto na cadência diária; e ~R$ 13.860/ano de valor gerado por obra só em tempo de engenharia recuperado — payback de ~3,9 meses e ROI de ~208% no primeiro ano no cenário de referência, resultado que se mantém positivo em 8 das 9 combinações da análise de sensibilidade, com custo de operação próximo de zero. Em aberto e registrado: o objetivo O2 (< 60 s de geração) não foi atingido e há correções de defeito pendentes na Prioridade 0. As melhorias seguintes atacam primeiro a disponibilidade do host (maior risco) e depois a latência da camada de IA (maior consumo de tempo).

Síntese dos Resultados

Síntese visual dos resultados do projeto — de ~40 minutos por dia de compilação manual (baseline arbitrado, ver nota metodológica na aba Diagnóstico e Objetivos) para um relatório de obra gerado por IA local em 3,5 minutos de mediana, sem custo de API ou licença. Os números abaixo conectam cada métrica ao objetivo: transformar dados dispersos (diário + clima) em orientação técnica acionável, entregue automaticamente todo dia útil.

Data Storytelling e Síntese dos Resultados

Esta seção apresenta a narrativa dos dados do projeto: o objetivo não é apenas mostrar números, mas contar a história que os números revelam, conectando cada métrica ao objetivo do projeto — transformar dados dispersos do canteiro em uma orientação técnica acionável, entregue automaticamente todo dia útil.

A História dos Dados

Bons dados contam uma história com começo, meio e fim — e a do Assistente de Obra IA começa por um número simples, ainda que estimado: cerca de 40 minutos por dia, todo dia útil, para cada obra.

O problema. A construção civil é um dos setores menos digitalizados do índice da McKinsey (2017) e, no Brasil, erguer um prédio residencial padrão leva em média mais do que o dobro do tempo que poderia levar (Deloitte/Fiesp, 2023). No dia a dia, isso se traduz numa tarefa concreta: reler o diário de obras e cruzá-lo manualmente com a previsão do tempo antes de decidir se pode concretar, pintar ou impermeabilizar — decisões que as próprias normas técnicas condicionam ao clima previsto (NBR 14931:2023; ABRACO RP PAC-001). É um trabalho repetitivo que, pela correria do canteiro, acaba negligenciado, e cuja categoria de custo é reconhecida no setor: o estudo FMI/PlanGrid (2018) apurou 5,5 h/semana por pessoa procurando informação de projeto em geral — normas, projetos, relatórios —, da qual a consulta ao diário é uma fatia. O resultado é concretagem em dia de chuva, retrabalho e decisões "no escuro".

A solução e a prova. O pipeline automatiza esse cruzamento e entrega o relatório em texto e áudio — e os dados mostram que funciona. A latência mediana é de 3,5 minutos ponta a ponta, cerca de 11× mais rápido que os ~40 minutos manuais, medida em 9 execuções reais com 88,9% dentro do SLA de 5 minutos. Desse tempo, ~85% é a IA local (LLM + TTS): não é um defeito, e sim o preço de não depender de nuvem paga e manter os dados da obra dentro de casa. A confiabilidade modelada é de ~97,9% por execução — o equivalente a ~247 de 252 relatórios entregues por ano (dias úteis), sendo que a falha de um dia é naturalmente coberta pelo relatório do dia seguinte. E o custo por relatório é de R$ 0, já que toda a IA roda localmente. Em resumo: o que se estima custar 40 minutos do dia passou a custar 3,5 minutos medidos e zero reais.

O valor e o futuro. Traduzindo para o negócio: para a construtora, o sistema gera cerca de R$ 13.860/ano de valor por obra só em tempo do engenheiro recuperado (baseline arbitrado de 40 min/dia × R$ 82/h × 252 dias úteis), com payback de ~3,9 meses e ROI de ~208% no primeiro ano — antes mesmo de contar o retrabalho evitado, e mantendo-se positivo em 8 das 9 combinações da análise de sensibilidade. E, como toda a IA roda localmente, o custo marginal de operação é próximo de zero: replicar a solução em uma nova obra praticamente não adiciona custo. À frente, o roadmap eleva a confiabilidade (host dedicado + watchdog) e corta a latência pela metade (LLM quantizado), abrindo caminho para escalar como produto (SaaS multi-tenant). É uma solução sem custo de IA nem de licença, pronta para democratizar o planejamento inteligente em construtoras de pequeno e médio porte.

Conexão entre Métrica, História e Objetivo

A tabela abaixo amarra cada métrica à mensagem que ela transmite e ao objetivo original do projeto — garantindo que nenhum número exista por si só, mas sempre a serviço da narrativa. Os valores não são repetidos aqui: estão na aba Métricas e ROI, com a memória de cálculo completa.

Impacto Ético, LGPD e IA Responsável

Esta seção analisa em profundidade os impactos éticos, legais e sociais do Assistente de Obra IA. Aplica a LGPD (Lei nº 13.709/2018) ao fluxo concreto de dados do pipeline, mapeia o sistema contra princípios de IA Responsável, identifica riscos e propõe ações de mitigação acionáveis. A análise parte de um princípio: tecnologia em construção civil lida com pessoas (operários, engenheiros, gestores) e com decisões que afetam segurança e dinheiro — logo, responsabilidade não é acessório, é requisito.

Mapeamento de Dados Pessoais no Pipeline (Data Mapping)

O primeiro passo de qualquer análise de conformidade é saber quais dados pessoais o sistema realmente trata. Mapeamento do fluxo atual:

Risco latente em produção (dado sensível)

Hoje o diário de obras não contém nomes de operários nem detalhes de saúde. Porém, em uso real, ocorrências do tipo "acidente de trabalho com o operário Fulano" introduziriam dados pessoais sensíveis (saúde — art. 5º, II da LGPD), elevando o nível de exigência legal. Recomendação: o diário deve registrar ocorrências de forma anonimizada/agregada (ex.: "1 afastamento por acidente leve") salvo quando houver base legal e finalidade específica para identificar a pessoa.

Aplicação da LGPD ao Projeto

Papéis e bases legais

Princípios do art. 6º — autoavaliação

Direitos dos titulares (art. 18) — como atender

Segurança da informação (art. 46) — estado atual e melhorias

Transferência internacional de dados (art. 33)

Ponto central e diferencial do projeto:

• ✅ A IA (LLM Ollama + TTS Kokoro) roda 100% localmente. Nenhum dado do diário de obras é enviado a APIs de IA de terceiros (OpenAI, Google, etc.). Isso elimina a maior fonte de exposição de dados em projetos de IA e é uma vantagem decisiva de privacidade (RNF02).
• ⚠️ Canais de entrega usam servidores no exterior: Telegram e Gmail (Google) processam o conteúdo do relatório e os dados de contato em infraestrutura internacional. Isso configura transferência internacional e deve ser informado aos titulares; ambos os provedores possuem salvaguardas contratuais, mas a construtora deve declarar esse fluxo em seu aviso de privacidade.
• ✅ APIs OpenWeather/Nominatim recebem apenas a cidade/coordenadas da obra — dado não-pessoal.

Síntese LGPD: o ponto mais sensível de um projeto de IA — enviar dados a um modelo na nuvem — não existe aqui, pois a IA é local. As lacunas remanescentes (disclaimer, retenção, descadastro, criptografia em repouso) são de baixa complexidade e estão endereçadas no plano de ação de conformidade, ao final desta aba.

Análise de IA Responsável

O sistema é classificado, em termos de risco, como um sistema de IA de risco limitado/mínimo: ele apoia decisões (gera sugestões para um engenheiro avaliar), não decide automaticamente sobre pessoas, crédito, contratação ou segurança. Mesmo assim, aplicam-se princípios consagrados (OCDE, UNESCO) e as diretrizes do PL 2.338/2023 — Marco Legal da IA brasileiro.

Status legislativo do PL 2.338/2023 (verificado em agosto de 2026): o projeto foi aprovado pelo Senado Federal em 10 de dezembro de 2024 e segue em tramitação na Câmara dos Deputados, ainda sem votação final e sem sanção — portanto não é lei em vigor. O texto adota o modelo do AI Act europeu: classificação por nível de risco (excessivo, alto, baixo/moderado), direitos dos afetados (transparência, explicação, contestação) e criação de um sistema nacional de governança de IA. Como a tramitação pode mudar, esta seção declara a data da verificação em vez de afirmar um status permanente. A obrigação legal hoje vigente e aplicável a este projeto é a LGPD (Lei nº 13.709/2018), tratada nas seções anteriores.

O risco mais importante: alucinação com consequência física

Uma sugestão errada ("pode concretar quinta") tomada como verdade absoluta pode gerar prejuízo material e até risco de segurança. Por isso, o princípio mais crítico aqui é a supervisão humana: o sistema é explicitamente posicionado como assistente de planejamento, e a decisão final é — e deve continuar sendo — do engenheiro responsável, que possui o registro profissional (CREA) e a responsabilidade técnica pela obra.

Impacto Social

Impactos positivos

• Democratização tecnológica: por ser open-source e não ter custo de IA nem de licença, leva IA aplicada a construtoras de pequeno e médio porte, que normalmente ficam de fora da transformação digital do setor.
• Acessibilidade da informação: o formato em áudio (TTS) torna o relatório consumível por quem está em campo, em deslocamento, ou tem menor familiaridade com leitura de relatórios técnicos longos — aproximando o canteiro do escritório.
• Redução de desperdício: menos retrabalho (concretagem/pintura mal planejadas) significa menos consumo de material e energia — um ganho ambiental indireto.
• Valorização do trabalho humano: ao automatizar a tarefa repetitiva de compilação, devolve ao engenheiro tempo para o trabalho de maior valor (análise, decisão, gestão de equipe).

Riscos sociais e mitigação

Plano de Ação de Conformidade (Checklist Acionável)

Consolidação das lacunas identificadas, com prioridade. Itens de alta prioridade são de baixo esforço e alto retorno de conformidade.

Conclusão da seção: O Assistente de Obra IA nasce com uma vantagem ética e legal estrutural — a IA é local, então os dados da obra nunca saem para um modelo de terceiros. Isso resolve, por design, o problema mais grave de privacidade em projetos de IA. As lacunas restantes (transparência, descadastro, retenção, segurança em repouso) são pontuais e de baixo custo, e estão organizadas em um plano de ação priorizado. Eticamente, o sistema se mantém no lugar correto: um assistente que potencializa o engenheiro, sem jamais substituir o julgamento humano sobre uma decisão que envolve segurança, dinheiro e pessoas.