Sistema de monitoramento hidrológico em tempo real para o Rio Piracicaba e afluentes no Vale do Aço, Minas Gerais. Desenvolvido com Laravel 11 e integração direta com a API oficial da Agência Nacional de Águas e Saneamento Básico (ANA).
🎬 Assista ao vídeo completo do projeto
🛰️ Integração com GIS e Experiência em ArcGIS
O projeto Monitor Rio Piracicaba foi planejado com foco em monitoramento geográfico e análise espacial, integrando conceitos e tecnologias de GIS (Geographic Information Systems).
Durante o desenvolvimento, foram aplicados princípios de georreferenciamento, manipulação de coordenadas geográficas (latitude/longitude) e visualização de dados hidrológicos em mapas interativos — conhecimentos diretamente relacionados ao uso de plataformas como ArcGIS e QGIS.
🌎 Experiência com GIS / ArcGIS
💡 Familiaridade com conceitos fundamentais de GIS, incluindo projeções cartográficas, shapefiles, camadas vetoriais e raster.
🛰️ Capacidade de integração de APIs geoespaciais (como ANA e IBGE) para análise e exibição de dados ambientais.
🗺️ Experiência em visualização de dados hidrológicos em mapas interativos, aplicável a plataformas como ArcGIS Online, ArcGIS Pro e bibliotecas Leaflet / Mapbox no ambiente web.
⚙️ Conhecimento prático em georreferenciamento e mapeamento de estações hidrológicas, utilizando coordenadas precisas.
🌐 Aplicável em projetos de monitoramento ambiental, saneamento, recursos hídricos e planejamento territorial.
🧭 Como GIS é aplicado no projeto
Cada estação hidrológica possui localização geográfica (latitude e longitude) registrada e utilizada para renderização em mapas.
Os dados obtidos da API da ANA podem ser correlacionados com mapas GIS, permitindo cruzamento de dados espaciais (rios, bacias, municípios).
O sistema foi projetado para futura integração com ArcGIS REST API ou serviços WMS/WFS para exibição de camadas ambientais.
{
"station": {
"id": 1,
"name": "Rio Piracicaba - Estação Centro",
"latitude": -19.4701,
"longitude": -42.5489,
"status": "active"
},
"river_data": {
"nivel": 2.45,
"vazao": 15.2,
"chuva": 0.5
}
}
- Visão Geral
- Objetivos e Importância
- Tecnologias e Arquitetura
- Modelo de Dados
- API Endpoints
- Integração com ANA
- Instalação
- Teste Local
- Deploy
- Testes E2E
- Funcionalidades
- Monitoramento
- Contribuição
- Agradecimentos
- Contato
- Licença
O Monitor Rio Piracicaba é uma aplicação web moderna e robusta desenvolvida para monitoramento hidrológico em tempo real do Rio Piracicaba e seus afluentes na região do Vale do Aço, Minas Gerais. O sistema integra dados oficiais da Agência Nacional de Águas (ANA) com uma interface intuitiva e responsiva, proporcionando acesso fácil e rápido a informações críticas sobre níveis de água, vazões e precipitação.
- 🔄 Tempo Real: Atualização automática de dados hidrológicos
- 📊 Analytics Avançados: Estatísticas e tendências hidrológicas
- 🌐 API Integrada: Conexão direta com dados oficiais da ANA
- 📱 Interface Responsiva: Design moderno e mobile-first
- 🚀 Performance: Cache inteligente e otimizações
- 🧪 QA Automatizado: 230+ testes E2E com Playwright
- 🔧 DevOps: CI/CD completo com GitHub Actions
- 🔒 Confiabilidade: Sistema de fallback com dados mock
- Monitoramento Contínuo: Fornecer dados hidrológicos atualizados do Rio Piracicaba
- Prevenção de Riscos: Alertar sobre níveis críticos e possíveis enchentes
- Gestão de Recursos: Auxiliar na gestão sustentável dos recursos hídricos
- Transparência: Disponibilizar informações públicas de forma acessível
- Educação Ambiental: Promover conscientização sobre recursos hídricos
O Rio Piracicaba é fundamental para o desenvolvimento socioeconômico do Vale do Aço, sendo utilizado para:
- 🏭 Abastecimento Industrial: Usiminas, ArcelorMittal e outras indústrias
- 🏠 Abastecimento Público: Milhares de famílias dependem do rio
- 🌾 Irrigação Agrícola: Suporte à produção agrícola regional
- ⚡ Geração de Energia: Pequenas centrais hidrelétricas
- 🐟 Preservação Ecológica: Manutenção do ecossistema aquático
Monitorar este recurso vital é essencial para a sustentabilidade e segurança da região.
- Laravel 11 - Framework PHP moderno e robusto
- PHP 8.1+ - Linguagem de programação server-side
- SQLite - Banco de dados leve e eficiente
- Composer - Gerenciador de dependências PHP
- React 19 - Biblioteca JavaScript para interfaces
- Inertia.js - Bridge entre Laravel e React
- TypeScript - JavaScript com tipagem estática
- Tailwind CSS 4.0 - Framework CSS utility-first
- Chart.js - Biblioteca para gráficos interativos
- Docker - Containerização da aplicação
- Nginx - Servidor web e proxy reverso
- GitHub Actions - CI/CD automatizado
- Fly.io - Plataforma de deploy cloud
- Certbot - Certificados SSL/TLS automáticos
┌─────────────────────────────────────────────────────────────┐
│ CAMADA DE APRESENTAÇÃO │
├─────────────────────────────────────────────────────────────┤
│ Frontend (React + Inertia.js + Tailwind CSS) │
│ • Dashboard Responsivo │
│ • Gráficos Interativos (Chart.js) │
│ • Componentes Reutilizáveis │
│ • PWA Ready │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CAMADA DE APLICAÇÃO │
├─────────────────────────────────────────────────────────────┤
│ Controllers (Laravel) │
│ • DashboardController │
│ • DataController │
│ • AnalyticsController │
│ • StationController │
│ • RiverDataController │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CAMADA DE SERVIÇOS │
├─────────────────────────────────────────────────────────────┤
│ Services (Business Logic) │
│ • AnaApiService (Integração ANA) │
│ • DataProcessingService │
│ • CacheService │
│ • NotificationService │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CAMADA DE DADOS │
├─────────────────────────────────────────────────────────────┤
│ Models & Database │
│ • Station (Estações Hidrológicas) │
│ • RiverData (Dados Hidrológicos) │
│ • SQLite Database │
│ • Cache (Redis/File) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ INTEGRAÇÃO EXTERNA │
├─────────────────────────────────────────────────────────────┤
│ API da ANA (Agência Nacional de Águas) │
│ • HidroWebService │
│ • Autenticação OAuth │
│ • Dados em Tempo Real │
│ • Fallback para Dados Mock │
└─────────────────────────────────────────────────────────────┘
- MVC (Model-View-Controller) - Separação clara de responsabilidades
- Repository Pattern - Abstração da camada de dados
- Service Layer - Lógica de negócio centralizada
- API Gateway - Integração padronizada com serviços externos
- Cache Strategy - Otimização de performance
- Error Handling - Tratamento robusto de erros
erDiagram
STATIONS {
bigint id PK
string name
string code UK
string location
decimal latitude
decimal longitude
text description
enum status
timestamp last_measurement
timestamp created_at
timestamp updated_at
}
RIVER_DATA {
bigint id PK
bigint station_id FK
decimal nivel
decimal vazao
decimal chuva
timestamp data_medicao
timestamp created_at
timestamp updated_at
}
USERS {
bigint id PK
string name
string email UK
timestamp email_verified_at
string password
string remember_token
timestamp created_at
timestamp updated_at
}
STATIONS ||--o{ RIVER_DATA : "has many"
USERS ||--o{ STATIONS : "manages"
id: Identificador único da estaçãoname: Nome da estação (ex: "Rio Piracicaba - Estação Centro")code: Código único da estação na ANAlocation: Localização geográfica da estaçãolatitude/longitude: Coordenadas GPS precisasstatus: Status operacional (active, inactive, maintenance)last_measurement: Timestamp da última medição
id: Identificador único do registrostation_id: Referência à estação (FK)nivel: Nível do rio em metrosvazao: Vazão em m³/schuva: Precipitação em mmdata_medicao: Timestamp da medição
- 1:N - Uma estação pode ter múltiplos registros de dados
- Cascade Delete - Exclusão em cascata para manter integridade
- Índices Otimizados - Performance em consultas temporais
GET / # Dashboard principal
GET /stations # Lista de estações
GET /data # Visualização de dados
GET /analytics # Análises e estatísticasGET /api/river-data # Lista dados hidrológicos
GET /api/river-data/chart # Dados para gráficos
GET /api/river-data/stats # Estatísticas consolidadas
POST /api/river-data # Criar novo registro
GET /api/river-data/{id} # Obter dados específicos
PUT /api/river-data/{id} # Atualizar dados
DELETE /api/river-data/{id} # Excluir dadosGET /api/stations # Lista todas as estações
GET /api/stations/discover-piracicaba # Descobrir estações do PiracicabaPOST /api/ana/fetch # Buscar dados da ANA
POST /api/ana/refresh-station # Atualizar estação específicaGET /health # Status da aplicação
GET /health/detailed # Status detalhado{
"data": [
{
"id": 1,
"station_id": 1,
"nivel": 2.45,
"vazao": 15.2,
"chuva": 0.5,
"data_medicao": "2024-09-20T12:00:00Z",
"station": {
"id": 1,
"name": "Rio Piracicaba - Estação Centro",
"code": "PIR001",
"location": "Ipatinga, MG"
}
}
],
"meta": {
"total": 150,
"per_page": 25,
"current_page": 1
}
}{
"status": "healthy",
"timestamp": "2024-09-20T12:00:00Z",
"database": "connected",
"cache": "working",
"storage": "writable",
"version": "1.3.0",
"environment": "production"
}A ANA é a agência reguladora federal responsável pela implementação da gestão de recursos hídricos no Brasil. Fundada em 2000, a ANA coordena o Sistema Nacional de Gerenciamento de Recursos Hídricos e mantém uma rede nacional de estações hidrológicas.
O sistema integra com a API oficial da ANA através do HidroWebService:
// Configuração de autenticação
'base_url' => 'https://www.ana.gov.br/hidrowebservice',
'auth' => [
'identificador' => env('ANA_API_IDENTIFICADOR'),
'senha' => env('ANA_API_SENHA'),
'token_ttl' => 3600 // 1 hora
]/EstacoesTelemetricas/OAUth/v1- Autenticação/EstacoesTelemetricas/HidroInventarioEstacoes/v1- Inventário de estações/EstacoesTelemetricas/HidroSerieCotas/v1- Dados de cotas/níveis/EstacoesTelemetricas/HidroSerieVazao/v1- Dados de vazão/EstacoesTelemetricas/HidroSerieChuva/v1- Dados de chuva
- Estação Vale do Aço - Principal estação industrial
- Estação Centro - Área urbana de Ipatinga
- Estação Zona Rural - Monitoramento agrícola
- 🔄 Cache Inteligente: Reduz chamadas desnecessárias à API
- 🛡️ Retry Logic: Tentativas automáticas em caso de falha
- 📊 Fallback: Dados mock quando API indisponível
- 📈 Rate Limiting: Respeita limites da API
- 🔍 Logging: Monitoramento completo das integrações
- PHP 8.1+ com extensões: pdo, pdo_sqlite, mbstring, xml, curl, zip, gd, intl
- Composer 2.0+
- Node.js 18+ e npm
- SQLite 3
- Git
# 1. Clone o repositório
git clone https://github.com/Wil-JC-Pimenta/monitor-rio.git
cd monitor-rio
# 2. Instale dependências PHP
composer install
# 3. Instale dependências Node.js
npm install
# 4. Configure o ambiente
cp .env.example .env
php artisan key:generate
# 5. Configure banco de dados
touch database/database.sqlite
php artisan migrate
# 6. Compile assets
npm run build
# 7. Inicie o servidor
php artisan serve# 1. Clone e navegue para o projeto
git clone https://github.com/Wil-JC-Pimenta/monitor-rio.git
cd monitor-rio
# 2. Execute com Docker Compose
docker-compose up -d
# 3. Acesse a aplicação
open http://localhost:8000# Executar script automatizado de teste
./teste-local.shO script irá automaticamente:
- ✅ Verificar pré-requisitos (PHP, Composer, Node.js)
- ✅ Testar dependências e Laravel
- ✅ Iniciar servidor em http://localhost:8000
- ✅ Testar endpoints principais
- ✅ Verificar dados de teste
# 1. Instalar dependências
composer install
npm install
# 2. Configurar ambiente
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed
# 3. Iniciar servidor
php artisan serve --host=0.0.0.0 --port=8000
# 4. Acessar no navegador
open http://localhost:8000- Dashboard: http://localhost:8000/
- Estações: http://localhost:8000/stations
- Dados: http://localhost:8000/data
- Análises: http://localhost:8000/analytics
- Health Check: http://localhost:8000/health
Para instruções detalhadas, consulte o Guia de Teste Local.
# Aplicação
APP_NAME="Monitor Rio Piracicaba"
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost:8000
# Banco de Dados
DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite
# Cache
CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync
# API ANA
ANA_API_BASE_URL=https://www.ana.gov.br/hidrowebservice
ANA_API_IDENTIFICADOR=seu_identificador
ANA_API_SENHA=sua_senha
ANA_CACHE_ENABLED=true
ANA_CACHE_TTL=3600# 1. Instale o Fly CLI
curl -L https://fly.io/install.sh | sh
# 2. Faça login
fly auth login
# 3. Deploy automático
fly deploy# Build da imagem
docker build -t monitor-rio .
# Execute o container
docker run -p 8000:80 monitor-rio# Execute o script de deploy completo
chmod +x scripts/setup-complete.sh
sudo ./scripts/setup-complete.shscripts/install-server.sh- Instala dependências do servidorscripts/configure-nginx.sh- Configura Nginxscripts/configure-ssl.sh- Configura HTTPS com Certbotscripts/configure-services.sh- Configura systemd servicesscripts/deploy.sh- Deploy contínuo automatizado
O projeto possui um sistema completo de testes End-to-End (E2E) com 230+ testes automatizados usando Playwright.
# Executar todos os testes E2E
npm run test:e2e
# Interface visual (recomendado)
npm run test:e2e:ui
# Com navegador visível
npm run test:e2e:headed
# Modo debug
npm run test:e2e:debug
# Ver relatórios
npm run test:e2e:report- ✅ Carregamento de páginas
- ✅ Exibição de métricas hidrológicas
- ✅ Gráficos e visualizações
- ✅ Navegação entre seções
- ✅ Responsividade mobile
- ✅ Listagem e busca
- ✅ Filtros por status
- ✅ Detalhes das estações
- ✅ Exportação de dados
- ✅ Acessibilidade
- ✅ Health check
- ✅ Performance e estresse
- ✅ Segurança e validação
- ✅ CORS e rate limiting
- Chrome - Desktop e Mobile
- Firefox - Desktop
- Safari - Desktop e Mobile
- Responsivo - Múltiplos viewports
- Relatórios HTML - Visualização detalhada
- Screenshots - Capturas em falhas
- Videos - Gravações de execução
- Traces - Rastreamento detalhado
- CI/CD Integration - Execução automática
Para mais detalhes, consulte a Documentação dos Testes E2E.
- 📊 Métricas em Tempo Real: Níveis, vazões e precipitação
- 📈 Gráficos Interativos: Visualizações temporais
- 🚨 Alertas: Notificações de níveis críticos
- 📱 Design Responsivo: Funciona em todos os dispositivos
- 📍 Localização GPS: Coordenadas precisas
- 📊 Status Operacional: Monitoramento de saúde
- 📈 Histórico: Dados históricos completos
- 🔍 Busca Avançada: Filtros e ordenação
- 📈 Tendências: Análise de padrões temporais
- 📊 Comparativos: Análise entre estações
- 📋 Relatórios: Exportação de dados
- 🎯 Alertas Personalizados: Configuração de limites
- ⏰ Agendamento: Atualizações programadas
- 🔄 Real-time: Dados em tempo real
- 📱 Notificações: Alertas push
- 📧 Email: Relatórios periódicos
GET /healthGET /health/detailed- 🗄️ Database: Status da conexão SQLite
- 💾 Cache: Funcionamento do sistema de cache
- 📁 Storage: Permissões de escrita
- 🌐 API ANA: Status da integração
- ⚡ Performance: Tempo de resposta
# Visualizar logs da aplicação
tail -f storage/logs/laravel.log
# Logs específicos da ANA
tail -f storage/logs/ana-api.log
# Debug de performance
php artisan telescope- 🍴 Fork o projeto
- 🌿 Crie uma branch para sua feature (
git checkout -b feature/AmazingFeature) - 💾 Commit suas mudanças (
git commit -m 'Add some AmazingFeature') - 📤 Push para a branch (
git push origin feature/AmazingFeature) - 🔄 Abra um Pull Request
- PSR-12 para PHP
- ESLint + Prettier para JavaScript/TypeScript
- Conventional Commits para mensagens de commit
- Testes obrigatórios para novas funcionalidades
# Testes PHP
php artisan test
# Testes com coverage
php artisan test --coverage
# Testes JavaScript
npm test- Laravel Framework - Base sólida para o desenvolvimento
- React & Inertia.js - Interface moderna e responsiva
- Tailwind CSS - Design system eficiente
- Chart.js - Visualizações interativas
- Docker - Containerização e deploy
Wilker Junio Coelho Pimenta
- 📧 Email: [email protected]
- 💼 LinkedIn: Wilker Pimenta
- 🐙 GitHub: @Wil-JC-Pimenta
- 🌐 Portfolio: wilkerpimenta.dev
Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.
MIT License
Copyright (c) 2024 Wilker Junio Coelho Pimenta
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- 📅 Última Atualização: Setembro 2025
- 🔢 Versão Atual: 1.4.0
- 📈 Status: Ativo e em desenvolvimento
- 🧪 Testes E2E: 230+ testes automatizados
- 🔧 CI/CD: GitHub Actions configurado
- 📚 Documentação: Guias completos de teste e deploy
- 🎯 Próximos Passos: Deploy em produção e monitoramento avançado
🌊 Desenvolvido com ❤️ para o Vale do Aço, Minas Gerais
Sistema de monitoramento hidrológico em tempo real do Rio Piracicaba