Clima para Manejo

📌 Resumo Executivo

Uma aplicação Full Stack de alta performance para o agronegócio, projetada para auxiliar na tomada de decisão operacional no manejo da cana-de-açúcar. O sistema processa dados meteorológicos brutos e os transforma em indicadores de Janela Operacional (momentos ideais para colheita ou pulverização) e Balanço Hídrico (cálculo de P - ET₀).

📖 A História (Background)

"O que começou como um Teste Técnico evoluiu para um projeto de engenharia de software robusto."

Este projeto nasceu de um desafio técnico para uma vaga de desenvolvedor. Após a entrega inicial, decidi refatorar e expandir a aplicação para utilizá-la como um laboratório de boas práticas. O objetivo foi transformar um MVP simples em uma aplicação pronta para produção, implementando arquitetura limpa, testes automatizados, cache distribuído e pipelines de CI/CD.

Ele demonstra minha capacidade de:

• Entender regras de negócio complexas (Agronomia).
• Evoluir um código legado/inicial.
• Configurar infraestrutura e deploy do zero.

🛠️ Tech Stack & Arquitetura

O sistema utiliza uma Arquitetura Híbrida moderna, separando responsabilidades mas mantendo a simplicidade do deploy.

Frontend (A Experiência do Usuário)

• Next.js 14 (App Router): Escolhido pela capacidade de SSR (Server-Side Rendering), garantindo performance inicial rápida e bom SEO.
• TypeScript: Tipagem estrita de ponta a ponta para reduzir bugs em tempo de execução.
• Tailwind CSS + Shadcn/ui: Criação de interfaces responsivas, acessíveis e com modo escuro (Dark Mode) nativo.
• State Management: Uso de padrões de State Machine para gerenciar estados de interface (Loading, Success, Error, Empty).

Backend (O Motor de Processamento)

• FastAPI (Python 3.11): Escolhido pela performance assíncrona e facilidade em lidar com processamento de dados.
• Clean Architecture: O código é dividido em Camadas de Roteamento, Serviços (Lógica de Negócio) e Schemas (Contratos de Dados).
• Redis: Implementação de cache para armazenar resultados de requisições à API externa, reduzindo latência e evitando Rate Limits.
• Pydantic: Validação rigorosa de dados de entrada e saída.

Infraestrutura & DevOps

• Docker & Docker Compose: Ambiente de desenvolvimento totalmente containerizado, garantindo que "funciona na minha máquina" signifique "funciona em qualquer lugar".
• GitHub Actions (CI): Pipeline automatizado que roda testes (Pytest/Jest) e linters a cada Push ou PR.
• Vercel: Deploy automatizado com arquitetura Serverless.
• Open-Meteo API: Integração com serviços externos de meteorologia e geocodificação.

💡 Funcionalidades Chave & Desafios Técnicos

1. Algoritmo de Balanço Hídrico (FAO-56) Implementei a lógica agronômica para calcular a Evapotranspiração de Referência. O sistema cruza dados de precipitação com a perda de água do solo para dizer ao agrônomo o saldo hídrico real do dia.

2. Pattern de Proxy Reverso Para evitar problemas de CORS e expor chaves de API, o Next.js atua como um proxy. O cliente bate no Frontend ( /api/* ), que redireciona a chamada para o Backend Python internamente. Isso simplifica a segurança.

3. Estratégia de Cache Inteligente Dados meteorológicos não mudam a cada segundo. Implementei uma camada de cache (Redis) que armazena as previsões por cidade. Se um usuário busca "Ribeirão Preto" e, 1 minuto depois, outro usuário busca a mesma cidade, o dado é retornado instantaneamente do cache, sem consumir a API externa.

4. Design Resiliente O sistema trata falhas graciosamente. Se a API de clima cair, o usuário recebe feedbacks visuais claros (Toasts/Alertas) em vez de uma tela branca quebrada.

🚀 Como Rodar (Localmente)

# O projeto é 100% Dockerizado
git clone https://github.com/samdevtx/clima-manejo.git
cd clima-manejo
docker compose up --build