1. Diagnóstico do Problema e Objetivos

1.1 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 é o segundo setor menos digitalizado do mundo, com produtividade estagnada nas últimas duas décadas. 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 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: McKinsey Global Institute, Reinventing Construction (2017); 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. Disponível em: https://www.cnnbrasil.com.br/economia/macroeconomia/burocracia-e-atrasos-podem-custar-r-59-bi-a-construcao-ate-2025-diz-estudo/

---

1.2 O Problema Real

O engenheiro responsável por uma obra precisa, diariamente, tomar decisões operacionais como:

• Quando concretar? — Concretagem em dia chuvoso compromete a cura e gera retrabalho.
• Quando pintar ou impermeabilizar? — Pintura e impermeabilização externas exigem dias secos consecutivos.
• Que frentes de serviço priorizar? — A alocação de equipes depende do que aconteceu nos últimos dias e do que está por vir.

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

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

Esse processo, embora simples conceitualmente, é repetitivo, manual e frequentemente negligenciado pela correria do canteiro. O resultado: decisões são tomadas sem dados atualizados, gerando paralisações evitáveis, retrabalho e atrasos.

---

1.3 Análise de Causas-Raiz

---

1.4 Consequências Mensuráveis

---

1.5 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.
• Distribuir iterativamente um briefing audiovisual consumível para gestores ou stakeholders não-técnicos do empreendimento, viabilizando consumo imediato nas primeiras horas logísticas do novo dia.

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.

---

1.6 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 com 3 cenários de teste (rotina normal, chuva intensa e problema logístico) para validação do pipeline.

---

1.7 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 4 minutos (automatizado, medido em ~3,7 min), ao final da fase de prototipagem.

Objetivos Específicos

---

---

2. 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 se ampara na arquitetura Serverless Logic através do n8n local conectado a microsserviços abertos e a inferências edge-hosted, consolidando 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.

2.1 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, extrai o caminho absoluto do projeto e as chaves de API. Exporta esses dados como variáveis globais 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.

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

Por que o Qwen 2.5 (14B)?

Em contrapartida de modelagens hospedadas pesadas (exemplo: ChatGPT, Claude) com latência dependente e Pay-As-You-Go, adotou-se localmente a arquitetura aberta Qwen 2.5. O peso de 14 bilhões de parâmetros representa um excelente equilíbrio entre raciocínio complexo, formatação rigorosa de saída e capacidade de rodar localmente sem custos, possibilitando inferência robusta e segura.

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 aba Métricas e ROI, §8.4).

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.

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.

---

2.3 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).

3. 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.

---

3.1 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:

• Cache de geocodificação: Como as coordenadas de uma obra não mudam, o par lat/lon pode ser armazenado localmente após a primeira consulta, eliminando chamadas recorrentes ao Nominatim.
• 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), com a geocodificação cacheável — mantendo-se muito abaixo de qualquer limite de taxa do Nominatim (1 req/s) e do OpenWeather.

---

3.2 O Preço da Alucinação Generativa

Risco: A aplicação local de Modelos de Linguagem de Larga Escala baseados no espectro de 4 a 14 Bilhões de Parâmetros expõe uma franja sensível em arquiteturas preditivas. O módulo preditivo que consolida as previsões operacionais fundamenta seu pensamento ativamente na documentação que recebe; todavia, a correlação entre uma chuva amena de 4mm e uma paralisação em lajes não é imperativa no paradigma físico-real, dependendo da alocação de drenagem in-loco que não compõe o payload do banco de dados (o LLM reage por hiperestímulo cego).

Mitigação implementada:

• Prompt Engineering restritivo: O prompt delimita estritamente 3 seções (dados, previsão, recomendação), reduzindo a margem para divagação ou correlações espúrias.
• Temperatura controlada (0.7): Valor calibrado para balancear criatividade e aderência aos dados fornecidos.
• 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.

---

3.3 Bloqueio Temporal de Hardware (Concorrência Sequencial)

Risco: A estratégia de delegação via executeCommand no nó do Kokoro TTS foi a adoção inteligente encontrada para by-passar os módulos faltantes do NodeJS usando processamentos Python on-premise isolados (Base64). No entanto, as bibliotecas kokoro_onnx e soundfile instanciadas subitamente a todo início de predição sobem a pilha de computação tensocial inteira do repouso, inferindo as redes ONNX dentro da VRAM (ou RAM partilhada) num fluxo imediato decorrente de uma finalização recém liberta do LLM. Dispositivos Edge fracos sofrerão gargalos térmicos em processamentos simultâneos.

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, §2.2). O timeout de 300s cobre com folga a inferência resultante.

---

Relatório de Testes de Stress — Pipeline Multicanal

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

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 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.

>

4. 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.

>

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

Sim, para o escopo definido (Cronjob diário rodando de madrugada). Como a execução de ~3,7 minutos ocorre às 06:30 de forma serverless 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 servidor físico com GPUs RTX.

6. 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.

---

6.1. 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.

---

6.2. 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 permite que agentes externos (como ElasticSearch, Datadog ou simples dashboards no Grafana) façam a ingestão desses arquivos e construam alertas visuais de degradação de performance sem adicionar sobrecarga ao n8n.

---

6.3. 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 antes de levantar o orquestrador, injetando as chaves no SO de forma segura.
• Nó de Configuração Inicial: O n8n extrai essas variáveis do Node.js (process.env) no nó 1 e propaga os valores pelo restante do fluxo internamente.
• 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 exato seja clonado e rodado para 50 obras diferentes ao mesmo tempo. Basta instanciar 50 containers, injetando um arquivo .env diferente em cada um (com cidades, tokens e chats específicos), sem alterar uma única linha do arquivo JSON do workflow.

---

6.4. 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 garante escalabilidade horizontal impecável. 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. 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.

8. 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.

---

8.1. 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.

Execuções reais medidas (n = 9)

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 (docs/05_stress_test_results.md), 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.

Ganho sobre o processo manual (baseline)

---

8.2. 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.

8.2.1. 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 (§8.4): máquina dedicada always-on, wake timer/BIOS, watchdog com re-disparo e fallback opcional para nuvem.

---

8.3. 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.

8.3.1. Valor gerado para o cliente (construtora)

Custo-hora do engenheiro residente (base verificável e conservadora): 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.

Premissa conservadora: usa o salário-base, sem encargos. Com encargos sociais (~+70%: FGTS, INSS, 13º, férias), o custo real seria ~R$ 140/h e a economia ~R$ 93/execução. Portanto, R$ 55 é um piso seguro.

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.)

8.3.2. Retorno para o cliente (payback e ROI)

Tomando como referência paramétrica um custo de implantação de R$ 4.500 (licença, configuração de ambiente e treinamento):

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.

8.3.3. 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.

---

8.4. Propostas de Melhoria (Roadmap Priorizado)

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

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 do Nominatim.
• 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 (~11× mais rápida que os ~40 min manuais, dentro do SLA); confiabilidade modelada de ~98% por execução (limitada pela infraestrutura física, não pelo software, e 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 < 4 meses e ROI > 200% no primeiro ano para o cliente, com custo de operação próximo de zero. As melhorias prioritárias 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 para um relatório de obra gerado por IA local em ~3,5 minutos, com custo zero. 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.

9. 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.

---

9.1. 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: 40 minutos por dia, todo dia útil, para cada obra.

O problema. A construção civil é o 2º setor menos digitalizado do mundo (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: o engenheiro residente gasta cerca de 40 minutos relendo o diário de obras e cruzando manualmente com a previsão do tempo — um trabalho repetitivo que, pela correria, acaba negligenciado. 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 custava 40 minutos do dia passou a custar 3,5 minutos 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 (40 min/dia × R$ 82/h × 252 dias úteis), com payback inferior a 4 meses e ROI superior a 200% no primeiro ano — antes mesmo de contar o retrabalho evitado. 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 de custo zero, pronta para democratizar o planejamento inteligente em construtoras de pequeno e médio porte.

---

9.2. 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.

10. 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.

---

10.1. 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.

---

10.2. Aplicação da LGPD ao Projeto

10.2.1. Papéis e bases legais

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

10.2.3. Direitos dos titulares (art. 18) — como atender

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

10.2.5. 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 (§10.5).

---

10.3. 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 o PL 2.338/2023 — Marco Legal da IA brasileiro em tramitação).

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.

---

10.4. Impacto Social

Impactos positivos

• Democratização tecnológica: por ser open-source e de custo zero, 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

---

10.5. 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.