Documentação Técnica e Histórica

Projeto "Enche o Tanque" | Atualizado em Abril de 2026

1. Histórico do Projeto

O desenvolvimento iniciou-se a partir da importação de mockups e wireframes de telas projetadas para criar uma aplicação robusta de busca e registro de preços de combustíveis. A aplicação consolidou-se unindo uma Stack Node.js/React no front-end com um back-end Express e um banco de dados relacional MySQL na Oracle Cloud.

1.1. Principais Desafios e Resoluções

Autenticação do Google Maps: Inicialmente, a API Key sofria restrições de Referrer. Contornamos adicionando tratamento de erro educacional e listagem de URLs liberadas (CORS e Cloud Console).
Problemas Geomagnéticos de DB: O Banco de Dados MySQL (tb_postos) armazenava latitude e longitude no formato Graus/Minutos (ex: -22:30:58.591).
Solução: Implementou-se um algoritmo nativo customizado no Backend Node.js que converte silenciosamente as coordenadas da BD para decimais (float) e aplica a Fórmula de Haversine para desenhar o perímetro do mapa baseada em geodiversidade.
Bloqueio de Geolocalização (Timeout): Navegadores bloqueavam capturas por timeout em Iframes restritos no Mobile.
Solução: Criou-se um fluxo amigável de fallback. Se o GPS falhar, o App assume "Petrópolis-RJ (Padrão)" centralizado para evitar crashes.

2. Premissas Vencedoras do App

Crowdsourcing: Base retroalimentada pelo consumidor através de Notas (NFC-e / NFe).
Interpolação de Colorimetria (RGB): Pinos desenhados em HTML5 SVG se auto-formatam do Verde Esmeralda (abaixo da média) ao Vermelho (acima da média), baseando-se no contexto de variação temporal (Min, Máx, Avg).
Troféu Absoluto (🏆): Carga lógica garante exibição de Ouro incondicional ao Posto Top 1, guiando o gasto no painel inferior.
UX/MX Deep-Linked: Bottom cards touch-responsivos, acúmulo de feedback e interligação imediata à DeepLinks do GPS de Viagem.

3. Fluxo Funcional Operacional

O cidadão acessa o PWA pelo Celular.
Escanear uma Nota fiscal (QR) aloca os dados à tb_qrcode, sendo depois ingeridos pelo Robô Extrator SEFAZ (Web Scraping / API).
Toda operação limpa engorda a tb_abastecimentos e vincula id/datetime id_posto.
No Painel Cidadão, a busca local dispara via filtro de Km + Tipo combustível.
A resposta alimenta as coordenadas visuais da interface, já tratada pelo motor matemático do App.

4. Diagrama Lógico de Pilha Tecnológica

[ APP WEB (React + Tailwind + Vite) ] ├── GET Location Coordinates (GPS) └── GET Fetch /api/search-stations (Params) [ CLOUD MIDDLEWARE (Node.js Express) ] ├── Abre Pool c/ Oracle ├── INNER JOIN `tb_postos` & `tb_abastecimentos` └── Extrai Sub-List com "Fórmula de Haversine" [ DATA VAULT (Oracle MySQL) ] └── Absorve Data Stream do Robô Py/Sefaz

5. Roadmap Próx. Semana: FASE FROTAS (B2B)

O foco na próxima apresentação será mudar a chave do modelo B2C para Modelo B2B - o "Gold-mine" logístico.

Novos Modelos de Tabelas:

tb_empresas: Gestor Frotista.
tb_veiculos: (Placas, Consumo Médio, Quota Mensal de Litros).
tb_motoristas: O app se torna Auditor Oficial da Bomba de Gasolina.

O Ciclo: O Frotista obriga os funcionários dos Caminhões a usar nosso painel e bater NF para receberem Diária. De uma vez só: economizamos % mensal de Transportadoras colossais e, de tabela, ganhamos os motoristas preenchendo as notas e engordando o banco de dados do Cidadão comum todos os dias.

🎤 ROTEIRO DE APRESENTAÇÃO AVALIATIVA (O PITCH)

[Parte 1: A "Dor" - 1min]
"Boa noite a todos. Todo mercado é exposto, exceto o de combustível: só descobrimos que fomos roubados na quadra seguinte. Nossa arquitetura corta isso hoje. Mas não somos uma listinha estática: o 'Enche o Tanque' é um radar financeiro em tempo real."

[Parte 2: A Solução Backend - 1min]
"Tudo nasce no QR Code das Notas Fiscais antigas que jogamos fora. Nossa infraestrutura extrai o código do usuário, manda um bot aos servidores do Estado e transforma Papel em Relational Data na Nuvem Oracle Node.js de ponta a ponta de forma autônoma."

[Parte 3: Apresentando o Frontend (A Magia) - 1.5min]
(Mostrem a tela e o degrade de postos)
"O Cidadão de casa recebe nossa entrega de dados como um verdadeiro painel tático. Por manipulação da Fórmula de Haversine cruzada a cores RGBs da matriz estendida, todos os postos brilham pra você no mapa interpolando: O Absurdo estelar vermelho, e os Justos vibrando na Esmeralda... Mas claro, aquele ali reinando no topo em Dourado com Troféu, a matemática te aponta o lugar mais barato absoluto do município. Basta ele tocar o dedo e clicar e mandá-lo pro navegador nativo abrir seu GPS do veículo."

[Parte 4: A Dinâmica Escalonável Econômica (Fechamento Frotas) - 1.5min]
"Onde fica o lucro bilionário? Essa foi a entrega Social. A Terça-feira é a entrega Frotista Logística. Transformaremos o Painel pra acolher Empresas e seus 500 caminhões cada. O dono gerencia meta, e nós viramos a ferramenta obrigatória de auditoria do caminhoneiro rodoviário na Bomba. Ganhamos mercado de SaaS empresarial, a empresa corta % gigante do lucro suado dela... e nós usamos o fluxo massivo deles para ganhar 10 Mil novas NFs preenchendo todos os dados do munícipio na base inteira. Todo mundo traciona pra cima. Nós somos a plataforma inteira."